每一次 AI-agent 工具调用，都会在发生时打上 MITRE ATT&CK 标签 —— 并且当一系列看似无害的调用累积构成攻击时，会触发 关联警报。

## 目录 - [为什么选择 Agentmetry？](#why-agentmetry) - [安装与快速开始](#install--quick-start) - [Agentmetry 的工作原理](#how-agentmetry-works) - [覆盖范围与局限性](#coverage--limitations) - [功能与集成](#capabilities--integrations) - [行为检测引擎](#behavioral-detection-engine) - [数据防泄漏 (DLP)](#data-loss-prevention-dlp) - [仪表盘](#dashboard) - [转发至 SIEM](#forwarding-to-a-siem) - [CLI 参考](#cli-reference) - [贡献](#contributing) - [安全性](#security) - [许可证](#license) ## 为什么选择 Agentmetry？ 当自主 agent 运行某个工具时，大多数技术栈不会留下任何你可以直接交给事件响应人员的记录。日志只显示进程，不显示**意图**、**会话边界**或**人类批准了什么**。 Agentmetry 是面向 AI agent 的开源**端点黑匣子记录器** —— 完全在你的本地机器上运行，并可选转发至你现有的 SIEM。 我们通过以下方式实现： - **拦截** 通过 IDE 生命周期 hook（Cursor、Claude Code、Codex、Antigravity）和 MCP stdio 审计代理拦截 agent 的工具调用 - **标准化** 将每个事件标准化为带有 MITRE ATT&CK 扩展和 SHA-256 参数哈希的 v1.1.0 标准 schema - **检测** 单个事件无法揭示的关联行为序列（凭据窃取、绕过护栏、先侦察后窃取） - **阻断** 在 hook 边界使用本地正则表达式 DLP 引擎拦截密钥和 PII（支持 `log` 或 `block` 模式） - **转发** 将相同的 JSONL 轨迹转发至 Loki、Elastic ECS、Splunk HEC 或通用 webhook —— 无需将云端作为核心记录系统 **Agentmetry 不是 CASB 或针对影子 AI 的监控工具。** 它只记录你接入的 agent。如果你面临的问题是浏览器中不受管理的 ChatGPT，你需要的是网络/端点策略 —— 而不是黑匣子记录器。 ## 安装与快速开始 Agentmetry 完全在本地运行。除非你明确转发，审计轨迹永远不会离开你的机器。 ### 先睹为快：看它如何捕获风险（30 秒） 无需服务器，无需 API key，无需配置。克隆并运行： ``` git clone https://github.com/blitzcrieg1/agentmetry.git && cd agentmetry pip install -r apps/orchestrator/requirements.txt python scripts/demo.py ``` 它会通过真实的 ingest API 重放一个 agent 会话：该 agent 读取了一个 SSH 私钥，运行了包含 AWS 密钥的命令，然后获取了一个 URL。Agentmetry 为每次调用打上 MITRE ATT&CK 标签，利用 DLP 捕获 AWS 密钥（仅存储匹配规则， 绝不存储实际值），然后 —— 无需额外指令 —— **将密钥读取与 网络调用进行关联，并触发 `CRITICAL` 级别的凭据窃取检测。**

这些事件中的任何单一事件都不会触发警报。但这个序列会。这就是整个 产品理念在一个界面上的体现。 ### 查看包含完整案例的仪表盘 ``` python scripts/demo_dashboard.py # seeds 5 sessions + 4 detections, serves http://127.0.0.1:8010/ ``` 一条命令即可生成真实的演示轨迹并在本地提供仪表盘服务 —— 无需 API key，无需云端。点击被标记的会话，检测结果会直接呈现在那里， 并在下方展开完整的事件详情：

请参阅[仪表盘导览](docs/dashboard-tour.md)了解每个视图展示的内容以及 如何阅读它们。 ### 前置条件 | 要求 | 版本 | |-------------|---------| | Python | 3.10+ | | Node.js | 18+ | ### 1. 克隆并安装 ``` git clone https://github.com/blitzcrieg1/agentmetry.git cd agentmetry # Python orchestrator cd apps\orchestrator python -m venv .venv .\.venv\Scripts\activate pip install -e ".[dev]" copy .env.example .env cd ..\.. # Next.js dashboard cd apps\dashboard npm install cd ..\.. ``` ### 2. 启动黑匣子记录器 ``` scripts\start-dev.bat ``` 仪表盘 → [http://localhost:3000](http://localhost:3000) · Orchestrator API → [http://localhost:8000](http://localhost:8000) ### 3. 接入你的 IDE（一次性操作） ``` powershell -ExecutionPolicy Bypass -File scripts\install_cursor_hooks.ps1 powershell -ExecutionPolicy Bypass -File scripts\install_claude_hooks.ps1 ``` 完全退出并重启 Cursor / Claude Code，以便加载 hook。 ### 4. 验证 ``` python scripts\agentmetry_ingest.py selftest ``` 事件应在几秒钟内出现在仪表盘的 **Flight Recorder** 中。 当 agent 运行工具时，Agentmetry 会自动： 1. 在参数离开 hook 进程之前**拦截**生命周期 hook 或 MCP 的 `tools/call` 2. **哈希化** 处理工具参数（SHA-256），并清除命令字符串中的内联密钥 3. **增强** 使用 MITRE 战术/技术映射和会话关联来丰富每个事件 4. **存储** 在本地存储标准 JSONL（`audit-forward.jsonl`）—— 作为 hook 路径的核心记录系统 5. **检测** 贯穿会话时间线的多步行为模式 6. **转发** 转发至你的 SIEM 接收器和告警 webhook（可选，尽力而为） ## Agentmetry 的工作原理 ### 架构 ``` flowchart TB subgraph Capture["Capture Layer (Tier A + B)"] HOOKS["IDE Lifecycle Hooks
Cursor · Claude · Codex · Antigravity"] PROXY["MCP Audit Proxy
mcp_audit_proxy.py"] end subgraph Gate["Local Security Gate"] DLP["DLP Scanner
regex rules"] HASH["Arg Hash + Secret Scrub"] end subgraph Core["Orchestrator :8000"] INGEST["POST /api/v1/audit/ingest"] CANON["Canonical Schema v1.1.0
MITRE enrichment"] DETECT["Sequence Detection Engine"] OUTBOX[("SQLite Outbox
events.db")] end subgraph Output["Outputs"] JSONL["audit-forward.jsonl"] DASH["Dashboard
Flight Recorder + Analytics"] SIEM["Loki · Elastic · Splunk · Webhook"] end HOOKS --> DLP PROXY --> DLP DLP -->|allow| HASH DLP -->|deny| INGEST HASH --> INGEST INGEST --> CANON CANON --> OUTBOX CANON --> JSONL CANON --> DETECT JSONL --> DASH JSONL --> SIEM ``` ### 捕获路径 ``` flowchart LR subgraph TierB["Tier B — IDE Hooks"] C["Cursor"] CL["Claude Code"] AG["Antigravity"] CX["Codex"] end subgraph TierA["Tier A — MCP Proxy"] MCP["Any MCP Client"] WRAP["Audit Proxy wraps server command"] end INGEST["agentmetry_ingest.py → /audit/ingest"] C --> INGEST CL --> INGEST AG --> INGEST CX --> INGEST MCP --> WRAP --> INGEST ``` | 组件 | 路径 | 职责 | |-----------|------|------| | **Hook client** | `scripts/agentmetry_ingest.py` | 将 IDE 生命周期事件映射为标准 payload；在进程内对参数进行哈希处理 | | **MCP proxy** | `apps/orchestrator/tools/mcp_audit_proxy.py` | 包装任何 stdio MCP 服务器；记录每一次 `tools/call` 及错误 | | **Ingest API** | `core/audit/ingest.py` | 标准化 payload，推断审批（`inferred:*`），写入接收器 | | **DLP engine** | `core/audit/dlp/` | 对工具参数进行正则表达式扫描（验证器如 Luhn）；在执行前阻断或记录 | | **Detection engine** | `core/audit/detection/` | 针对会话事件时间线的关联序列规则 | | **Sinks** | `core/audit/sinks.py` | File、webhook、Elastic ECS、Splunk HEC | | **Replay** | `core/audit/replay.py` | 从本地 outbox 重建 ASCII 时间线 | ### 标准事件 每次运行都会生成强类型的、适配 SIEM 的 JSON。单条 `tool_called` 记录如下： ``` { "schema_version": "1.1.0", "correlation_id": "thread-8892", "timestamp_utc": "2026-07-12T09:14:22.041+00:00", "actor": {"type": "user", "id": "dev_01", "role": "operator"}, "action": {"type": "tool_called", "outcome": "success"}, "agent": {"name": "cursor", "skill_id": ""}, "tool": { "qualified": "vault_fs.read_file", "server": "vault_fs", "input_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "parameters_redacted": true, "mitre": {"tactic": "Collection (TA0009)", "technique": "Data from Local System (T1005)"} }, "model": {"id": "claude-3-5-sonnet", "provider": "anthropic"} } ``` 完整 schema → [docs/agentmetry-event-schema.md](docs/agentmetry-event-schema.md) ## 覆盖范围与局限性 Agentmetry 记录你接入的 agent —— 通过 **IDE hook** 或 **MCP proxy**。它对于无法看到的内容毫不掩饰。 | 等级 | 设置 | Agentmetry 覆盖范围 | |------|-------|---------------------| | **A** | 由审计代理包装的 MCP 服务器 | **全量工具调用捕获** —— 包含每一次 `tools/call` 及错误响应、参数哈希、会话关联 | | **B** | IDE hook（Cursor、Claude、Codex、Antigravity） | 工具调用（成功/失败）、审批提示；根据执行情况**推断** approve/deny，并标记为 `inferred:*` | | **C** | 不受管理的 ChatGPT、关闭了 hook 的 Cursor | **不可见。** 属于 CASB / 安全 Web 网关的范畴 | ## 功能与集成 | | | | --- | --- | | 🎥 **Flight Recorder** | 实时审计流，支持动态列、拖拽布局、CSV 导出和会话下钻 | | 📊 **分析与进程树** | 会话级别图表、MITRE 战术分解、横向 React Flow 时间线 | | 🔍 **行为检测** | 关联序列规则 —— 凭据窃取、绕过护栏、先侦察后窃取 | | 🛡️ **本地 DLP** | 正则表达式扫描器，在工具执行前阻断 AWS 密钥、GitHub token、Slack token 和 PII | | 🎯 **MITRE ATT&CK 映射** | 在每个标准事件上打上对应的战术/技术标签 | | 🔐 **参数哈希** | 默认对工具参数进行 SHA-256 哈希处理 —— 明文永远不会通过 hook 跨网络传输 | | 📡 **原生 SIEM 导出** | Elastic ECS、Splunk HEC、Loki/LogQL、通用 webhook，以及在拒绝时触发的告警 webhook | | 🔁 **重放与证据** | ASCII 会话时间线 + 防篡改证据包导出 | | 👥 **多 IDE 支持** | Cursor、Claude Code、Codex、Antigravity —— 全局 hook 安装脚本 | ### 集成 | 类别 | 目前支持 | 路线图 | | -------- | --------------- | ------- | | **IDE / Agent 宿主** | Cursor · Claude Code · Codex · Antigravity | Windsurf · VS Code Copilot | | **MCP 传输** | Stdio 审计代理（可包装任何 MCP 服务器命令） | SSE / 流式 HTTP 代理 | | **可观测性 / SIEM** | Loki · Grafana · Elastic ECS · Splunk HEC · 通用 webhook | Datadog · New Relic | | **检测格式** | 引擎内置序列规则 · LogQL · Elastic · Splunk · [Sigma pack](docs/integrations/sigma/README.md) | STIX/TAXII 导出 | | **策略引擎** | 正则表达式 DLP 清单（`policies/dlp/`） | OPA / Rego 策略即代码 | | **合规文档** | [ISO 42001 映射](docs/compliance/iso-42001-mapping.md) · [AI Act 检查清单](docs/compliance/ai-act-deployer-checklist.md) | SOC 2 证据模板 | Agentmetry 是由社区构建的。欢迎浏览[开放议题](https://github.com/blitzcrieg1/agentmetry/issues)或[路线图](ROADMAP.md)。 ## 行为检测引擎 单个事件的 MITRE 标签说明单个工具调用*是什么*。检测引擎则说明一系列调用的**序列**意味着什么 —— 这是 EDR 无法看到的信号，因为它从未掌握 agent 的会话边界。 规则在**事件到达时**运行。触发的规则在每个会话中作为标准的一等事件（`action.type: detection`，`action.outcome: `）发送到与其他事件相同的接收器 —— 这样一来，无需任何人打开仪表盘，它就能到达你的 SIEM、你的告警 webhook 以及实时数据流。相同的检测结果也可以在 `GET /audit/detections/{correlation_id}` 请求时从轨迹中重新计算得出。 ``` sequenceDiagram participant IDE as IDE / MCP Proxy participant IN as Ingest API participant DB as JSONL Outbox participant ENG as Detection Engine participant API as GET /audit/detections/{id} IDE->>IN: tool_called / approval_response / session_end IN->>DB: append canonical event Note over ENG: Rules run over time-ordered session events ENG->>ENG: credential-exfil ENG->>ENG: approval-denied-then-executed ENG->>ENG: discovery-then-collect API->>DB: load events for correlation_id API->>ENG: run_detections(events) ENG-->>API: ranked Detection list ``` | 规则 ID | 严重程度 | 模式 | | ------- | -------- | ------- | | `credential-exfil` | critical | 凭据访问 (T1552) → 网络外传 (TA0011) | | `approval-denied-then-executed` | critical | 人类拒绝了受限工具 → 同一工具随后成功执行 | | `autonomous-unapproved-write` | high | 自主 agent 在未获得事先人工批准的情况下进行写入/删除 | | `discovery-then-collect` | medium | 文件系统侦察突增 (TA0007) → 数据收集 | 查询某个会话的检测结果： ``` GET /api/v1/audit/detections/{correlation_id} X-API-Key: ``` ## 数据防泄漏 (DLP) Agentmetry 内置了本地正则表达式 DLP 引擎，可在工具参数被执行或记录**之前**对其进行扫描。当在 `block` 模式下触发匹配时，hook 将拒绝执行并发出 `tool_denied` 事件。 ``` flowchart LR HOOK["Pre-tool hook"] --> SCAN["DLP Scanner
policies/dlp/manifest.yaml"] SCAN -->|match + block| DENY["tool_denied
reason: dlp:rule_id"] SCAN -->|pass| EXEC["Tool executes + audit log"] SCAN -->|match + log| WARN["Audit + allow
(observe mode)"] ``` | 环境变量 | 默认值 | 描述 | | --- | ------- | ----------- | | `AGENTMETRY_DLP_MODE` | `log` | `log` · `block` · `disable` | | `AGENTMETRY_DLP_PII` | `1 | 启用 PII 规则（如 SSN 等） | | `AGENTMETRY_DLP_RULES_PATH` | `policies/dlp/manifest.yaml` | 自定义规则清单 | 规则涵盖 AWS 密钥、GitHub PAT、Slack token、bearer header、私钥以及美国 SSN 模式。无需修改 Python 代码即可添加自定义正则表达式规则 —— 只需将条目放入清单文件中。 ## 仪表盘 位于 `:3000` 的 Next.js 仪表盘为 SOC 分析师提供了 agent 活动的实时视图： | 视图 | 特性 | | ---- | -------- | | **Flight Recorder** | 实时事件流、来源徽章、结果过滤器、可展开的行详情、原始 JSON 视图 | | **列管理器** | 拖拽式列布局，内置了针对模型、技能、主机、MCP 服务器和失败原因的字段 —— 可通过列设置面板重新排序或隐藏 | | **分析** | 结果分布、MITRE 战术图表、会话 ID 搜索 | | **进程树** | 选定会话内事件的横向 React Flow 时间线 | 支持深色模式，可通过主题切换按钮切换。Logo 和面板会自动适应。 ## 转发至 SIEM 对于通过 IDE hook 捕获的 agent（常见情况），标准 JSONL 轨迹是**核心记录系统**；SQLite outbox 为 orchestrator 自身的运行提供支持。转发器采用尽力而为的机制。 | 接收器 | 环境变量 | |------|-----| | **File（默认）** | `AGENTMETRY_AUDIT_SINK=file` | | **Webhook** | `AGENTMETRY_AUDIT_SINK=webhook` + `AGENTMETRY_AUDIT_WEBHOOK_URL=...` | | **Elastic ECS** | `AGENTMETRY_AUDIT_SINK=elastic` + `AGENTMETRY_AUDIT_ELASTIC_URL` + `AGENTMETRY_ELASTIC_API_KEY` | | **Splunk HEC** | `AGENTMETRY_AUDIT_SINK=splunk` + `AGENTMETRY_AUDIT_SPLUNK_HEC_URL` + `AGENTMETRY_SPLUNK_HEC_TOKEN` | | **告警 Webhook** | `AGENTMETRY_AUDIT_ALERT_WEBHOOK_URL=...`（在拒绝/错误结果时触发） | 使用 Loki + Grafana 的家庭实验室 SIEM： ``` docker compose -f docker-compose.loki.yml up -d # Grafana → http://localhost:3001 # 探索: {job="agentmetry"} | json ``` 集成指南 → [docs/integrations/](docs/integrations/) ## CLI 参考 `scripts\agentmetry.bat`（或在 orchestrator 的虚拟环境中使用 `python -m cli`）： | 命令 | 功能说明 | |---------|--------------| | `agentmetry start` / `stop` / `status` | 在后台运行 orchestrator；检查健康状态 | | `agentmetry replay ` | 从 `events.db` 获取某次运行的 ASCII 审计时间线 | | `agentmetry export --evidence` | 生成防篡改的批量打包文件（JSON + SHA-256） | | `agentmetry verify ` | 重新计算证据导出文件的完整性哈希值 | | `agentmetry doctor` | 对 python、路径等进行预检 | `scripts\agentmetry.bat` 保留作为旧版别名。 ## 贡献 Agentmetry 欢迎在检测规则、DLP 模式、SIEM 适配器和仪表盘 UX 等方面做出贡献。 | 领域 | 从这里开始 | | ---- | ---------- | | Hook 适配器 | [docs/agentmetry-external-ingest.md](docs/agentmetry-external-ingest.md) | | 事件 schema | [docs/agentmetry-event-schema.md](docs/agentmetry-event-schema.md) | | 检测规则 | `apps/orchestrator/core/audit/detection/rules.py` | | DLP 规则 | `policies/dlp/manifest.yaml` | | Sigma pack | [docs/integrations/sigma/README.md](docs/integrations/sigma/README.md) | | 路线图 | [ROADMAP.md](ROADMAP.md) | 在提交 PR 之前请运行测试： ``` cd apps\orchestrator python -m ruff check core api tests python -m pytest -q ``` ## 安全性 Agentmetry 是专为安全敏感环境设计的： - **本地优先** —— 除非你配置了转发器，否则审计数据将保留在你的机器上 - **默认参数哈希** —— 明文工具参数永远不会离开 hook 进程 - **可选 API key** —— 使用 `AGENTMETRY_API_KEY` 保护 ingest/tail/export 端点 - **DLP 阻断** —— 防止密钥和 PII 到达工具执行边界 - **防篡改导出** —— 证据包包含 SHA-256 完整性哈希 请通过带有 `security` 标签的 GitHub Issues 报告漏洞，或在仓库中开启私密的安全公告。 合规文档 → [docs/compliance/](docs/compliance/) ## 许可证 Apache-2.0。欢迎贡献代码、提供 schema 反馈和检测规则！ ## 维护者 由 Ioannis L. 构建和维护 —— 在 [LinkedIn](https://www.linkedin.com/in/ioannis-l-074439194/) 上与我联系。

标签：AI代理, AMSI绕过, ETW劫持, MITM代理, StruQ, 威胁检测, 日志记录, 逆向工具