agentmetry

<div align="center"> <p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/logo/agentmetry-logo-white.svg"> <img src="docs/logo/agentmetry-logo-black.svg" alt="Agentmetry" width="360" /> </picture> </p> <h1>Agentmetry：面向 AI 代理的 SIEM</h1> <p>开源的飞行记录器和 AI 代理工具使用安全层。<br/> 每次工具调用、每次拒绝、每次人工审批 — 哈希、关联并存储在您拥有的 JSONL 轨迹中。<br/> 按需重放；当您需要 SIEM 时，转发到 Loki、Elastic 或 Splunk。</p> <p align="center"> <a href="https://github.com/blitzcrieg1/agentmetry/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge" alt="Apache 2.0 License"></a> <a href="https://github.com/blitzcrieg1/agentmetry"><img src="https://img.shields.io/badge/status-public%20alpha-orange?style=for-the-badge" alt="项目状态：公开测试"></a> <img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey?style=for-the-badge" alt="平台：Windows | Linux"> </p> <p align="center"> <a href="#install--quick-start"><strong>快速开始</strong></a> · <a href="docs/agentmetry-external-ingest.md"><strong>文档</strong></a> · <a href="docs/agentmetry-event-schema.md"><strong>模式</strong></a> · <a href="ROADMAP.md"><strong>路线图</strong></a> · <a href="#security"><strong>安全</strong></a> </p> </div> <p align="center"> <img src="docs/assets/dashboard.png" alt="Agentmetry 飞行记录器仪表盘：来自 Cursor、Claude 和 Antigravity 的工具调用实时流，每个调用都标记了 MITRE ATT&CK 技术，带有 credential-access 读取 ~/.ssh/id_rsa 突出显示为红色。" width="880"> </p> <p align="center"> <em>每个 AI 代理工具调用，都标记了 MITRE ATT&CK — 以及当一系列看似无害的调用累积成攻击时的<strong>关联警报</strong>。</em> </p> --- > 🚧 **公开测试**: 核心捕获、重放和 SIEM 转发可用于早期探索。API 和集成表面可能会迅速演变。 --- ## 目录 - [为什么选择 Agentmetry？](#为什么选择agentmetry) - [安装和快速开始](#安装和快速开始) - [Agentmetry 工作原理](#agentmetry工作原理) - [覆盖范围和限制](#覆盖范围和限制) - [功能和集成](#功能和集成) - [行为检测引擎](#行为检测引擎) - [数据丢失防护（DLP）](#数据丢失防护dlp) - [仪表盘](#仪表盘) - [转发到 SIEM](#转发到siem) - [CLI 参考](#cli参考) - [贡献](#贡献) - [安全](#安全) - [许可证](#许可证) --- ## 为什么选择 Agentmetry？ 当自主代理运行工具时，大多数堆栈都不会保留您可能交给事件响应人员的任何信息。日志显示了一个过程；它们不显示**意图**、**会话边界**或**人类批准的内容**。 Agentmetry 是开源的**端点飞行记录器**，适用于 AI 代理 — 在您的机器上运行，支持可选转发到您已经运行的 SIEM。 > 不变的、运营商拥有的审计轨迹，用于受监管的 AI 代理 — 在 IDE 生命周期边界和 MCP 线路上捕获工具执行，而不是在供应商云中 我们通过以下方式实现： - **拦截** 代理工具调用，通过 IDE 生命周期钩子（Cursor、Claude Code、Codex、Antigravity）和 MCP stdio 审计代理 - **规范化** 每个事件为规范模式 v1.1.0，具有 MITRE ATT&CK 增强和 SHA-256 参数哈希 - **检测** 相关行为序列，单个事件无法揭示（credential exfil、guardrail bypass、recon-then-grab） - **阻止** 钩子边界处的机密和个人识别信息，使用本地正则表达式 DLP 引擎（`log` 或 `block` 模式） - **转发** 相同的 JSONL 轨迹到 Loki、Elastic ECS、Splunk HEC 或通用 webhook — 不将云作为记录系统 **Agentmetry 不是 CASB 或 shadow-AI 间谍。** 它记录您连接的代理。如果您的问题是未经管理的 ChatGPT 在浏览器中，您需要网络/端点策略 — 而不是飞行记录器。 --- ## 安装和快速开始 Agentmetry 完全本地运行。审计轨迹在您明确转发之前不会离开您的机器。 ### 立即体验（30 秒） 无需服务器，无需 API 密钥，无需配置。克隆并运行： ```bash git clone https://github.com/blitzcrieg1/agentmetry.git && cd agentmetry pip install -r apps/orchestrator/requirements.txt python scripts/demo.py ``` 它通过真实的摄入 API 重放代理会话：代理读取 SSH 私钥，运行包含 AWS 密钥的命令，然后获取 URL。Agentmetry 用 MITRE ATT&CK 标记每个调用，用 DLP 捕获 AWS 密钥（存储规则，而不是值），然后 — 在未被要求的情况下 — **关联密钥读取与网络调用并触发 `CRITICAL` credential-exfil 检测。** <p align="center"> <img src="docs/assets/demo.gif" alt="终端重放：代理读取 SSH 私钥和 AWS 密钥，然后获取 URL；Agentmetry 用 MITRE ATT&CK 标记每个调用，DLP 标志 AWS 密钥（不存储），并触发关键 credential-exfil 检测。" width="760"> </p> 无需单个事件就是警报。序列是。 这就是一个屏幕上的整个产品。 ### 查看带有故事的仪表盘 ```bash python scripts/demo_dashboard.py # 种子 5 会话 + 4 检测，服务 http://127.0.0.1:8010/ ``` 一条命令播种一个现实的演示轨迹并在本地提供仪表盘 — 无需 API 密钥，无需云。点击一个标记的会话，检测就在那里，带有下方展开的完整事件细节： <p align="center"> <img src="docs/assets/dashboard-detection.png" alt="Agentmetry 中固定会话，显示关键 credential-exfil 检测横幅 — credential access 后跟 network egress，T1552.004 到 T1071.001 — 上方为展开的 id_rsa 读取事件详情。" width="900"> </p> 查看 [仪表盘游览](docs/dashboard-tour.md) 了解每个视图显示的内容以及如何阅读。 ### 先决条件 | 需求 | 版本 | |-------------|---------| | Python | 3.10+ | | Node.js | 18+ | ### 1. 克隆和安装 ```powershell git clone https://github.com/blitzcrieg1/agentmetry.git cd agentmetry # Python 调度器 cd apps\orchestrator python -m venv .venv .\.venv\Scripts\activate pip install -e ".[dev]" copy .env.example .env cd ..\.. # Next.js 仪表盘 cd apps\dashboard npm install cd ..\.. ``` ### 2. 启动飞行记录器 ```powershell scripts\start-dev.bat ``` 仪表盘 → [http://localhost:3000](http://localhost:3000) · 调度器 API → [http://localhost:8000](http://localhost:8000) ### 3. 连接您的 IDE（一次性） ```powershell powershell -ExecutionPolicy Bypass -File scripts\install_cursor_hooks.ps1 powershell -ExecutionPolicy Bypass -File scripts\install_claude_hooks.ps1 ``` 完全退出并重启 Cursor / Claude Code 以加载钩子。 ### 4. 验证 ```powershell python scripts\agentmetry_ingest.py selftest ``` 事件应在几秒钟内出现在仪表盘 **飞行记录器** 中。 当代理运行工具时，Agentmetry 会自动： 1. **拦截** 生命周期钩子或 MCP `tools/call` 在参数离开钩子进程之前 2. **哈希** 工具参数（SHA-256）并在命令行字符串中清除内联机密 3. **增强** 每个事件都带有 MITRE 战术/技术映射和会话关联 4. **存储** 规范 JSONL 本地（`audit-forward.jsonl`）— 钩子路径的记录系统 5. **检测** 跨会话时间线的多步骤行为模式 6. **转发** 到您的 SIEM 接收器和警报 webhook（可选，最好尽力） --- ## Agentmetry 工作原理 ### 架构 ```mermaid flowchart TB subgraph Capture["捕获层（Tier A + B）"] HOOKS["IDE 生命周期钩子<br/>Cursor · Claude · Codex · Antigravity"] PROXY["MCP 审计代理<br/>mcp_audit_proxy.py"] end subgraph Gate["本地安全门"] DLP["DLP 扫描器<br/>正则表达式规则"] HASH["参数哈希 + 机密清除"] end subgraph Core["调度器 :8000"] INGEST["POST /api/v1/audit/ingest"] CANON["规范模式 v1.1.0<br/>MITRE 增强"] DETECT["序列检测引擎"] OUTBOX[("SQLite 输出盒<br/>events.db")] end subgraph Output["输出"] JSONL["audit-forward.jsonl"] DASH["仪表盘<br/>飞行记录器 + 分析"] 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 ``` ### 捕获路径 ```mermaid flowchart LR subgraph TierB["Tier B — IDE 钩子"] C["Cursor"] CL["Claude Code"] AG["Antigravity"] CX["Codex"] end subgraph TierA["Tier A — MCP 代理"] MCP["任何 MCP 客户端"] WRAP["审计代理包装服务器命令"] end INGEST["agentmetry_ingest.py → /audit/ingest"] C --> INGEST CL --> INGEST AG --> INGEST CX --> INGEST MCP --> WRAP --> INGEST ``` | 组件 | 路径 | 角色 | |-----------|------|------| | **钩子客户端** | `scripts/agentmetry_ingest.py` | 将 IDE 生命周期事件映射到规范有效载荷；哈希参数在进程内 | | **MCP 代理** | `apps/orchestrator/tools/mcp_audit_proxy.py` | 包装任何 stdio MCP 服务器；记录每个 `tools/call` + 错误 | | **摄入 API** | `core/audit/ingest.py` | 规范化有效载荷，推断批准（`inferred:*`），写入接收器 | | **DLP 引擎** | `core/audit/dlp/` | 工具参数的正则表达式扫描（验证器，例如 Luhn）；在执行前阻止或记录 | | **检测引擎** | `core/audit/detection/` | 会话事件时间线上的关联序列规则 | | **接收器** | `core/audit/sinks.py` | 文件、webhook、Elastic ECS、Splunk HEC | | **重放** | `core/audit/replay.py` | 从本地输出盒重放 ASCII 时间线 | ### 规范事件 每次运行都会发出类型化的、SIEM 就绪的 JSON。单个 `tool_called` 行： ```json { "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"} } ``` 完整模式 → [docs/agentmetry-event-schema.md](docs/agentmetry-event-schema.md) --- ## 覆盖范围和限制 Agentmetry 记录您连接的代理 — **IDE 钩子** 或 **MCP 代理**。它对其无法看到的内容保持诚实。 | 层 | 设置 | Agentmetry 覆盖范围 | |------|-------|---------------------| | **A** | 用审计代理包装的 MCP 服务器 | **完整的工具调用捕获** — 每个 `tools/call` + 错误响应，参数哈希，会话关联 | | **B** | IDE 钩子（Cursor、Claude、Codex、Antigravity） | 工具调用（成功/失败），批准提示；推断批准/拒绝 **inferred** | | **C** | 无管理的 ChatGPT，Cursor 关闭钩子 | **不可见。** CASB / 安全网页关领域 | --- ## 功能和集成 | | | | --- | --- | | 🎥 **飞行记录器** | 实时审计尾部，具有动态列，拖放布局，CSV 导出和会话钻取 | | 📊 **分析和进程树** | 会话级图表，MITRE 战术分解，水平 React Flow 时间线 | | 🔍 **行为检测** | 关联序列规则 — credential exfil，guardrail bypass，recon-then-grab | | 🛡️ **本地 DLP** | 正则表达式扫描器在工具执行前阻止 AWS 密钥，GitHub 令牌，Slack 令牌和 PII | | 🎯 **MITRE ATT&CK 映射** | 每个规范事件上的工具战术/技术标签 | | 🔐 **参数哈希** | 默认情况下工具参数的 SHA-256 — 钩子中从未传输纯文本 | | 📡 **SIEM 原生导出** | Elastic ECS，Splunk HEC，Loki/LogQL，通用 webhook，拒绝警报 webhook | | 🔁 **重放和证据** | ASCII 会话时间线 + 防篡改证据包导出 | | 👥 **多 IDE 支持** | Cursor，Claude Code，Codex，Antigravity — 全局钩子安装脚本 | ### 集成 | 类别 | 当前支持 | 路线图 | | -------- | --------------- | ------- | | **IDE / 代理主机** | 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 包](docs/integrations/sigma/README.md) | STIX/TAXII 导出 | | **策略引擎** | 正则表达式 DLP 清单（`policies/dlp/`） | OPA / Rego 策略即代码 | | **合规文档** | [ISO 42001 映射](docs/compliance/iso-42001-mapping.md) · [AI 法案核对清单](docs/compliance/ai-act-deployer-checklist.md) | SOC 2 证据模板 | Agentmetry 是社区驱动的。浏览 [开放问题](https://github.com/blitzcrieg1/agentmetry/issues) 或 [路线图](ROADMAP.md)。 --- ## 行为检测引擎 每事件的 MITRE 标签表示单个工具调用是什么。检测引擎表示一个**序列**的调用意味着什么 — EDR 无法看到的信号，因为它从未具有代理的会话边界。 规则在事件到达时运行。触发的规则会在会话中作为第一个规范事件发出 (`action.type: detection`, `action.outcome: <severity>`)，发送到与所有内容相同的接收器 — 因此它会到达您的 SIEM，警报 webhook 和实时动态信息流，而无需任何人打开仪表盘。相同的发现会根据关联 ID 在 `GET /audit/detections/{correlation_id}` 上重新计算。 > **Alpha 限制。** 实时关联状态在内存中且按进程 — 重启调度器会重置正在进行的会话的警报连续性。JSONL 轨迹保持权威，因此不会丢失任何检测 — 它会在查询时重新计算，但重新启动中间会话可能会延迟实时警报。检测状态不会在进程间共享。 ```mermaid sequenceDiagram participant IDE as IDE / MCP 代理 participant IN as 摄入 API participant DB as JSONL 输出盒 participant ENG as 检测引擎 participant API as GET /audit/detections/{id} IDE->>IN: tool_called / approval_response / session_end IN->>DB: 追加规范事件 Note over ENG: 规则在有序会话事件上运行 ENG->>ENG: credential-exfil ENG->>ENG: approval-denied-then-executed ENG->>ENG: discovery-then-collect API->>DB: 加载关联 ID 的事件 API->>ENG: run_detections(events) ENG-->>API: 排名检测列表 ``` | 规则 ID | 严重程度 | 模式 | | ------- | -------- | ------- | | `credential-exfil` | critical | 凭证访问（T1552）→ 网络外流（TA0011） | | `approval-denied-then-executed` | critical | 人工否决的 gated 工具 → 稍后成功执行相同工具 | | `autonomous-unapproved-write` | high | 自主代理在没有人工批准的情况下写入/删除 | | `discovery-then-collect` | medium | 文件系统侦察突发（TA0007）→ 数据收集 | 查询某个会话的检测： ```http GET /api/v1/audit/detections/{correlation_id} X-API-Key: <optional> ``` --- ## 数据丢失防护（DLP） Agentmetry 配备了一个本地正则表达式 DLP 引擎，在工具参数执行或记录之前扫描它们。当在 `block` 模式下触发匹配时，钩子拒绝执行并发出 `tool_denied` 事件。 ```mermaid flowchart LR HOOK["预工具钩子"] --> SCAN["DLP 扫描器<br/>policies/dlp/manifest.yaml"] SCAN -->|匹配 + 阻止| DENY["tool_denied<br/>reason: dlp:rule_id"] SCAN -->|通过| EXEC["工具执行 + 审计日志"] SCAN -->|匹配 + 日志| WARN["审计 + 允许<br/>(观察模式)"] ``` | 环境变量 | 默认值 | 描述 | | --- | ------- | ----------- | | `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 令牌，承载标头，私钥和美国 SSN 模式。添加自定义正则表达式规则 — 将条目放入清单中，无需接触 Python。 --- ## 仪表盘 :3000 处的 Next.js 仪表盘为安全运营分析师提供了代理活动的实时视图： | 视图 | 功能 | | ---- | -------- | | **飞行记录器** | 实时事件尾部，源徽章，结果过滤器，可展开的行详情，原始 JSON 视图 | | **列管理器** | 拖放列布局，包含模型，技能，主机，MCP 服务器和失败原因的内置字段 — 通过列设置面板重新排序或隐藏 | | **分析** | 结果分布，MITRE 战术图表，会话 ID 搜索 | | **进程树** | 水平 React Flow 时间线，显示选定会话中的事件 | 支持深色模式，带有主题切换。徽标和面板自动适应。 --- ## 转发到 SIEM 系统 对于通过 IDE 钩子捕获的代理（常见情况），规范的 JSONL 跟踪是**记录系统**；SQLite 出站队列支持编排器的自身运行。转发器尽力而为。 | 接收端 | 环境变量 | |------|-----| | **文件（默认）** | `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 的 Homelab SIEM： ```powershell docker compose -f docker-compose.loki.yml up -d # Grafana → http://localhost:3001 # 探索：{job="agentmetry"} | json ``` 集成指南 → [docs/integrations/](docs/integrations/) --- ## 命令行参考 `scripts\agentmetry.bat`（或 `python -m cli` 在编排器的虚拟环境中）： | 命令 | 功能 | |---------|--------------| | `agentmetry start` / `stop` / `status` | 运行编排器分离；检查健康状态 | | `agentmetry replay <thread_id>` | 单次运行的 ASCII 审计时间线，从 `events.db` | | `agentmetry export --evidence` | 防篡改批量包（JSON + SHA-256） | | `agentmetry verify <evidence.json>` | 重新计算证据导出的完整性哈希 | | `agentmetry doctor` | Python、路径等的预检 | `scripts\agentmetry.bat` 保留为旧别名。 --- ## 贡献 Agentmetry 欢迎在检测规则、DLP 模式、SIEM 适配器和仪表盘 UX 方面的贡献。 | 领域 | 开始这里 | | ---- | ---------- | | 钩子适配器 | [docs/agentmetry-external-ingest.md](docs/agentmetry-external-ingest.md) | | 事件模式 | [docs/agentmetry-event-schema.md](docs/agentmetry-event-schema.md) | | 检测规则 | `apps/orchestrator/core/audit/detection/rules.py` | | DLP 规则 | `policies/dlp/manifest.yaml` | | Sigma 包 | [docs/integrations/sigma/README.md](docs/integrations/sigma/README.md) | | 路线图 | [ROADMAP.md](ROADMAP.md) | 在打开拉取请求之前运行测试： ```powershell cd apps\orchestrator python -m ruff check core api tests python -m pytest -q ``` --- ## 安全 Agentmetry 设计用于安全敏感的环境： - **本地优先** — 审计数据保留在您的机器上，除非您配置转发器 - **默认参数哈希** — 明文工具参数永远不会离开钩子进程 - **可选 API 密钥** — 使用 `AGENTMETRY_API_KEY` 保护摄入/尾部/导出端点 - **DLP 阻止** — 阻止秘密和个人身份信息到达工具执行边界 - **防篡改导出** — 证据包包括 SHA-256 完整性哈希 通过 GitHub 问题报告漏洞，并使用 `security` 标签，或在存储库上打开私有的安全咨询。 合规文档 → [docs/compliance/](docs/compliance/) --- ## 许可证 Apache-2.0。欢迎贡献、模式反馈和检测规则！ --- ## 维护者 由 Ioannis L. 构建和维护 — 在 [LinkedIn](https://www.linkedin.com/in/ioannis-l-074439194/) 上联系。