Nienie22/pharos-agent-incident-response

# Pharos Agent 事件响应 Pharos Agent 事件响应是一个专为自治链上 agent 设计的端到端安全响应系统。它可以检测可疑的 agent 或钱包活动，将原始信号转化为结构化的事件，提出受策略控制的遏制措施，收集批准，执行安全响应，并在 Pharos Atlantic 上记录可验证的事件凭证。 本项目采用面向生产环境的 monorepo 架构构建，包含 Web 指挥中心、HTTP API、TypeScript SDK、CLI、MCP 工具接口、responder 和 watcher 服务、策略引擎、集成模块以及 Solidity 合约。 ## 为什么需要它 自治 agent 可以批准支出者、轮换密钥、执行交易，并以远超人类安全团队手动反应的速度转移价值。当会话密钥泄露，或 agent 签署了危险的授权时，团队需要一个快速、可控、非托管且可审计的响应闭环。 Pharos 提供了这个闭环： - 通过 watcher、威胁情报源和 webhook 检测危险行为。 - 使用确定性的策略逻辑对严重程度和置信度进行评估。 - 提出遏制计划，例如撤销授权、暂停 agent 或轮换密钥元数据。 - 在执行任何响应之前进行模拟。 - 对写操作要求明确的 guardian 或策略批准。 - 在 Pharos Atlantic 上执行，而无需托管用户资金。 - 锚定凭证，以便对事件进行审查和独立验证。 ## 当前状态 已实现并部署至 Pharos Atlantic 测试网。 - Web 指挥中心支持演示模式和实时 API 模式。 - API、SDK、CLI、MCP、watcher、responder、policy、integrations 和 contracts 均已实现。 - 测试套件在 JavaScript、TypeScript 和 Foundry 工作区中均通过。 - Pharos Atlantic 验收场景 S1-S5 在链 ID `688689` 上通过。 - 面向 CLI、SDK、MCP 和 policy 包的公开 npm 包元数据已准备就绪。 部署证明： - 验收报告：`docs/atlantic-acceptance-results.md` - 公共清单：`deployments/atlantic.public.json` - 完整验收凭证：`deployments/atlantic.acceptance.json` ## 架构 ``` flowchart LR Threats["Threat signals
GoPlus, Pharos watcher, webhook feeds"] Watcher["services/watcher
signal ingestion"] Policy["packages/policy
schemas, scoring, planning, hashes"] API["apps/api
HTTP incident API"] Responder["services/responder
simulate, authorize, execute, verify"] Contracts["packages/contracts
IncidentRegistry
EmergencyPolicyController"] Web["apps/web
Incident Command Center"] CLI["bin/cli.js
pharos-incident"] SDK["packages/sdk
TypeScript HttpClient"] MCP["apps/mcp
agent tool surface"] Integrations["packages/integrations
GoPlus, Pharos, webhooks"] Threats --> Watcher Watcher --> API Integrations --> API API --> Policy API --> Responder Responder --> Contracts Contracts --> API Web --> SDK CLI --> SDK MCP --> SDK SDK --> API ``` ## 事件响应流程 ``` sequenceDiagram participant Signal as Threat Signal participant API as Pharos API participant Policy as Policy Engine participant Guardian as Guardian / Wallet participant Responder as Responder participant Chain as Pharos Atlantic Signal->>API: detect(subject, rawSignals) API->>Policy: score severity and confidence API-->>API: create incident snapshot API->>Policy: propose deterministic response plan Policy-->>API: plan hash and required approvals API->>Responder: simulate(planHash) Responder-->>API: simulation digest and warnings Guardian->>API: approve(planHash, signature) API->>Responder: execute approved plan Responder->>Chain: submit containment transaction Chain-->>Responder: tx receipt Responder->>Chain: anchor closure receipt API-->>Guardian: verifiable response evidence ``` ## Monorepo 结构 ``` . |-- apps | |-- api # Fastify HTTP API for incident lifecycle operations | |-- mcp # MCP tools for AI agents and automation clients | `-- web # React/Vite command center and guided demo UI |-- bin | `-- cli.js # pharos-incident CLI entrypoint |-- deployments # Public Pharos Atlantic manifests and receipts |-- docs # Runbooks, threat model, verification, reports |-- infra | `-- alibaba # Serverless deployment definitions |-- packages | |-- contracts # Solidity IncidentRegistry and policy controller | |-- integrations # GoPlus, Pharos, and webhook clients | |-- policy # Types, Zod schemas, scoring, planning, hashes | `-- sdk # Typed TypeScript API client and Atlantic helpers |-- scripts # Deployment, acceptance, build, and security scripts `-- services |-- responder # Simulation, authorization, execution, verification `-- watcher # Signal collection and checkpointing ``` 本地渲染输出、生成的视频、超能力规划笔记、日志、截图、构建输出和环境变量文件均被刻意忽略，不会包含在公开仓库中。 ## 包 | 包 | 用途 | | --- | --- | | `pharos-agent-incident-response` | 提供 `pharos-incident` 的 CLI 包 | | `@pharos-incident/sdk` | 针对 HTTP API 的强类型 TypeScript 客户端 | | `@pharos-incident/mcp` | 用于 agent 工作流的 MCP 工具接口 | | `@pharos-incident/policy` | 共享的策略 schema、评分、规划和哈希 | 这些包配置了 `publishConfig: { "access": "public" }` 以便公开发布到 npm。发布顺序为： ``` @pharos-incident/policy @pharos-incident/sdk @pharos-incident/mcp pharos-agent-incident-response ``` ## 从源码快速开始 前置要求： - Node.js 20 或更高版本 - npm - Foundry，仅用于 Solidity 合约测试和部署 安装、构建和测试： ``` npm install npm run build npm run typecheck npm test ``` 运行 Web 指挥中心： ``` cd apps/web npx vite ``` 运行 API： ``` cd apps/api set PHAROS_INCIDENT_API=1 set PORT=8799 npm start ``` PowerShell 等效命令： ``` cd apps/api $env:PHAROS_INCIDENT_API = "1" $env:PORT = "8799" npm start ``` 默认情况下，当没有可用的 API 时，Web 应用可以回退到预设的演示模式。实时测试网模式使用配置的 API 以及在 Pharos Atlantic 上的注入钱包。 ## CLI CLI 映射了主要的事件生命周期 API。 ``` pharos-incident [options] ``` 命令： ``` detect --subject

--signals triage --id propose --id simulate --plan approve --plan --approver

--signature execute --plan --approver

--signature verify --plan close --plan ``` 配置 API 基础 URL： ``` export PHAROS_INCIDENT_API_URL=https://your-api.example.com ``` PowerShell： ``` $env:PHAROS_INCIDENT_API_URL = "https://your-api.example.com" ``` 只读命令示例： ``` pharos-incident triage --id 0x... pharos-incident simulate --plan 0x... pharos-incident verify --plan 0x... ``` 检测命令示例： ``` pharos-incident detect \ --subject 0x0000000000000000000000000000000000000001 \ --signals '[{"source":"goplus","type":"MALICIOUS_APPROVAL","severity":90,"evidenceHash":"0x0000000000000000000000000000000000000000000000000000000000000000","confidenceBps":9500,"observedAt":1730000000}]' ``` 写操作受到严格保护。`approve`、`execute` 和 `close` 命令需要： ``` export PHAROS_INCIDENT_CONFIRM=1 ``` PowerShell： ``` $env:PHAROS_INCIDENT_CONFIRM = "1" ``` ## SDK SDK 为应用程序代码、机器人、Serverless 作业和集成测试提供了一个强类型的 `HttpClient`。 ``` import { HttpClient } from "@pharos-incident/sdk"; const client = new HttpClient("https://your-api.example.com"); const incident = await client.detect({ subject: "0x0000000000000000000000000000000000000001", rawSignals: [ { source: "goplus", type: "MALICIOUS_APPROVAL", severity: 90, evidenceHash: "0x0000000000000000000000000000000000000000000000000000000000000000", confidenceBps: 9500, observedAt: Date.now(), }, ], }); const triage = await client.triage(incident.id); const plan = await client.propose(incident.id); const simulation = await client.simulate(plan.planHash); ``` 主要 SDK 方法： ``` detect(input) triage(incidentId) propose(incidentId) simulate(planHash) approve(input) approvalNonce(planHash, approver) submitApprovalIntent(intentId, intent, signature) confirmApproval(intentId, txHash) execute(input) transaction(txHash) verify(planHash) close(planHash) ``` SDK 还从 `@pharos-incident/sdk` 导出了 Pharos Atlantic 常量和 ABI 辅助工具。 ## MCP `@pharos-incident/mcp` 将事件生命周期公开为可供 AI agent 和自动化运行时使用的工具。 可用工具： | 工具 | 描述 | 写保护 | | --- | --- | --- | | `incident_detect` | 对钱包或 agent 主体运行检测 | 否 | | `incident_triage` | 读取事件的严重程度和评分 | 否 | | `incident_propose` | 构建确定性的响应计划 | 否 | | `incident_simulate` | 模拟计划操作 | 否 | | `incident_verify` | 读取关闭凭证和验证状态 | 否 | | `incident_approve` | 提交批准 | 是，需要 `confirm: true` | | `incident_execute` | 执行已批准的计划 | 是，需要 `confirm: true` | | `incident_close` | 关闭已验证的计划 | 是，需要 `confirm: true` | 编程式用法： ``` import { HttpClient } from "@pharos-incident/sdk"; import { buildTools } from "@pharos-incident/mcp"; const client = new HttpClient("https://your-api.example.com"); const tools = buildTools(client); const triageTool = tools.find((tool) => tool.name === "incident_triage"); const result = await triageTool?.run({ id: "0x..." }); ``` MCP 包刻意要求写工具必须显式确认。除非传入 `confirm: true`，否则 agent 无法调用 `incident_approve`、`incident_execute` 或 `incident_close`。 ## API 接口 HTTP API 支持 CLI、SDK、MCP 工具和 Web 应用所使用的相同生命周期。 ``` POST /detect GET /triage/:incidentId POST /propose POST /simulate POST /approve POST /approvals/nonce POST /approve/confirm POST /execute GET /transactions/:txHash GET /verify/:planHash POST /close ``` ## Web 指挥中心 `apps/web` 是一个专为安全操作人员设计的 React/Vite 界面。 它包含： - 解释事件响应价值主张的主页。 - 包含恶意授权、可疑交易爆发和会话密钥泄露场景的引导式演示。 - 用于安全的内存工作流的演示模式。 - 用于 API 和基于钱包的 Pharos Atlantic 工作流的实时测试网模式。 - 事件列表和事件详情视图。 - 钱包连接、网络就绪状态检查和证据面板。 ## 合约与 Pharos Atlantic 网络：`pharos-atlantic` | 合约 | 地址 | | --- | --- | | IncidentRegistry | `0x0d93b5cD4356652ef6b4776949A86979e9c00cdE` | | EmergencyPolicyController | `0xA2F7fEED38f72eF63ACa52696C1620a3e2EecE2d` | | AgentRegistry | `0x2d1B360dec14e63846735939E793bcb1655Aa93b` | 浏览器： ``` https://atlantic.pharosscan.xyz ``` 运行合约测试： ``` npm run contracts:test ``` 部署并针对配置的 Pharos Atlantic 凭证运行验收测试： ``` cp .env.example .env npm run deploy:atlantic npm run acceptance:atlantic ``` 在 Windows 上，请确保 `forge.exe` 位于 `PATH` 中，或者安装在 `scripts/run-forge.mjs` 检查的其中一个路径下： ``` %USERPROFILE%\.foundry\bin %USERPROFILE%\foundry C:\foundry ``` ## 安全模型 - 默认情况下允许读操作。 - 写操作在 CLI 和 MCP 中需要明确的确认。 - 实时的 Web 批准使用在 Pharos Atlantic 上注入的钱包。 - 计划哈希和关闭哈希是确定性的。 - 响应计划在执行前会进行模拟。 - 部署清单在公开使用前会进行净化处理。 - `.env`、私有部署文件、本地渲染输出、日志、截图和生成的构建产物会被 git 忽略。 运行本地密钥扫描： ``` npm run secret-scan ``` ## 文档 - 实现指南：`docs/README-implementation.md` - 威胁模型：`docs/threat-model.md` - 策略模型：`docs/policy.md` - 隔离模型：`docs/isolation.md` - Atlantic 运行手册：`docs/atlantic-runbook.md` - 验收结果：`docs/atlantic-acceptance-results.md` - 最终验证报告：`docs/final-verification-report.md` - Web 演示报告：`docs/web-demo-report.md` - 运行手册：`docs/runbooks/` ## 许可证 MIT

标签：MITM代理, Web3, 区块链安全, 安全编排与自动化响应, 库, 应急响应, 智能合约, 暗色界面, 自动化攻击, 自动化防御