markusweldon/agentinel

# Agentinel

[](https://github.com/markusweldon/agentinel/actions/workflows/ci.yml) [](https://www.python.org/) [](LICENSE) [](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/) 如今，AI 助手会同时连接到多个 MCP 服务器。单独来看，这些服务器通常没有问题——但是**一旦将足够多的服务器连接在一起，你可能会不小心赋予某个 agent “致命三角”：即访问不受信任的内容 + 敏感数据 + 对外发送数据的途径**——这恰恰是 prompt injection 进行数据窃取所需的全部条件。Agentinel 将这种能力暴露出来，并标记出具体的风险。 它直接建立在先前研究的基础之上——Simon Willison 的[致命三角](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/)、Meta 的 [Rule of Two](https://ai.meta.com/blog/practical-ai-agent-security/) 以及 [OWASP Agentic Top 10](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/)。它并没有发明这些理念；而是将它们**转化为实际操作**，作为一种自动化检查工具，这样你就不必手工对你的 agent 设置进行威胁建模。 **`agentinel scan`**（静态扫描，无需 API key，绝不运行你的工具）会报告： - **跨服务器致命三角**——即当没有任何单个服务器构成威胁，但你组装的*组合*却构成了威胁时（这种情况很容易被忽略）； - 具体且可修复的问题：**tool poisoning**（工具元数据中的隐藏指令）、配置中的**密钥泄露**、**rug-pull drift**（工具的定义在你批准后被更改）、不安全的代码执行面、过宽的权限，以及跨服务器的命名遮蔽（name shadowing）； - 每个工具的**能力矩阵**（Rule of Two），让你可以准确看到在哪里切断这个三角。 **`agentinel probe`** 是一个**实验性**的、自适应的“攻击者后发制人”红队工具，它驱动线上 agent 对服务器发起攻击，并尝试窃取植入的 canary。*（该循环已通过脚本化模型进行了单元测试；但尚未针对线上模型进行验证——请将其输出视为起点，而非证明。）* 检查结果会映射到 OWASP ASI 类别，并支持导出到终端、JSON、**SARIF**（GitHub code scanning）以及一个独立的 **HTML 仪表板**。 ### 它的优势 - **将已知的威胁模型转化为自动化检查。** 无需手动推理 agent 的能力面——你会得到一份排好序的报告，包括*意外形成的跨服务器*致命三角（即单独安全的服务器组合后变成了真正的风险）。 - **在 15 个真实的 MCP 服务器上进行了验证。** 它正确地将 GitHub 的服务器标记为致命三角——这与外界披露的同一类漏洞相符——同时对无害服务器保持静默。这种精确度在每次提交时都会进行回归测试。 - **暴露具体的、可修复的风险**：在它扫描的服务器中，包括 tool poisoning、密钥泄露、rug-pull drift 以及不安全的代码执行面——每一项都映射到带有修复建议的 OWASP ASI 类别。 - **开放、可扩展且具有互补性。** 免费使用，旨在与商业扫描器（如 Snyk Agent Scan）并行工作，增加跨服务器/集群视图以及线上服务器探测功能。 静态的 `scan` 非常稳定且经过全面测试。`probe` 目前是**实验性**的——其循环已进行单元测试，但尚未针对线上模型进行验证——目前的覆盖范围是 OWASP ASI 列表中 MCP 可观察到的部分（ASI01–05）。 ## 30 秒演示 — 无需设置，不依赖外部环境 ``` git clone https://github.com/markusweldon/agentinel && cd agentinel uv sync uv run agentinel scan --stdio "python fixtures/vulnerable/poisoned_server.py" ``` ``` ╭─────────────────────────────────────╮ │ Agentinel — MCP security scan │ │ server: acme-devtools tools: 4 │ ╰─────────────────────────────────────╯ Capability matrix (Rule of Two) Tool A B C acme-devtools:fetch_url ● · · acme-devtools:read_notes · ● · acme-devtools:send_report · · ● acme-devtools:run · · ● Severity OWASP Class Target Title HIGH ASI01 tool_poisoning acme-devtools:read_notes Hidden instructions in tool metadata HIGH ASI02 lethal_trifecta server:acme-devtools Lethal Trifecta / Rule-of-Two violation HIGH ASI05 unsafe_code_execution acme-devtools:run Unsafe code/command execution surface ... 6 findings (5 high, 1 medium) result: FAIL (--fail-on high) ``` 添加 `--html report.html` 可生成本 README 顶部展示的仪表板，或使用 `--sarif findings.sarif` 输出用于 GitHub 的 Security 标签页。示例报告位于 [`examples/`](examples/) 目录中。 ## 扫描你自己的设置 将 `--config` 指向你的助手正在使用的 MCP 配置——Agentinel 会读取它，连接到你已安装的每个服务器，并将它们的真实工具作为一个集群进行分析： ``` uv run agentinel scan --config ~/.cursor/mcp.json --html report.html uv run agentinel scan --config "$HOME/Library/Application Support/Claude/claude_desktop_config.json" ``` **设计上为只读。** 扫描时仅向每个服务器请求其能力列表（`initialize` → `list_tools` / `list_resources` / `list_prompts`）。它**绝不会调用任何工具**——整个代码库中没有任何地方包含 `call_tool`——因此不会发送、写入、删除或执行任何内容。它仅读取工具的*元数据*并分析文本。（启动服务器以读取其列表会运行该服务器自身的启动过程，这完全类似于你的助手在每次启动时所做的事情。） ## 它的适用场景 Agentinel 是**开放且具有教育意义**的，专注于在繁忙的 agent 设置中容易被忽略的两件事： - **意外形成的跨服务器致命三角**——单独安全的服务器组合成了一条真实的数据窃取路径；以及 - **针对 MCP 工具面本身的自适应探测**，而不仅仅是模型端点。 它的构建是为了**补充**团队已经在使用的 agent 安全工具以及“在创建之初即保证安全”的理念——以任何人都能阅读、运行和扩展的形式，尽早暴露出危险的能力组合和有风险的工具元数据。 ## 特征检查的工作原理 **致命三角 / Rule of Two。** 每个工具都会在三个维度上进行分类——**A** 摄取不受信任的内容，**B** 接触敏感数据/系统，**C** 更改状态或与外部通信——分类依据是 MCP 工具注解（`openWorldHint`、`destructiveHint`、`readOnlyHint`）以及保守的关键字信号。注解只会*提高*风险等级，绝不会消除风险（服务器自行声明的 `readOnlyHint` 可能会被攻击者控制）。如果单个工具——或整个组合集群——跨越了这三个维度，任何 prompt injection 都可以将它们串联起来导致数据泄露。这就是 [Simon Willison 的致命三角](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) 和 [Meta 的 Rule of Two](https://ai.meta.com/blog/practical-ai-agent-security/)。 **自适应探测（攻击者后发制人）。** 探测器将目标的工具接入到一个持有**植入的 canary secret** 的真实 agent 中，然后由一个*攻击者 LLM* 精心构造一个 injection——通过不受信任的输入工具的输出（真实的间接注入）或用户的对话轮次发送。如果 agent 没有泄露 canary，攻击者会读取对话记录并在下一轮尝试一个**更强、完全不同**的 payload。成功与否是通过确定性方式检测的（检查工具调用的参数中是否包含 canary），因此判定结果不依赖于容易出错的判断模型。根据 [“The Attacker Moves Second”](https://simonwillison.net/2025/Nov/2/new-prompt-injection-papers/)：静态基准测试会夸大鲁棒性；而自适应攻击则不会。工具实际上永远不会被执行。 ## OWASP Agentic Top 10 (2026) 覆盖范围 | ASI | 类别 | Agentinel 检查内容 | |---|---|---| | ASI01 | Agent Goal Hijack | tool poisoning，自适应 prompt-injection 探测 | | ASI02 | Tool Misuse & Exploitation | 致命三角（单服务器 + 跨服务器），canary 窃取探测 | | ASI03 | Identity & Privilege Abuse | 过度/通配符权限，配置中的密钥 | | ASI04 | Agentic Supply Chain | 工具遮蔽，rug-pull / 未锁定的服务器 | | ASI05 | Unexpected Code Execution | 不安全的代码/命令执行面 | | ASI06–ASI10 | Memory poisoning · inter-agent comms · cascading failures · trust exploitation · rogue agents | 路线图 | v1 专注于从 MCP 服务器可观察到的内容；多 agent 类别（ASI07–ASI10）已列入路线图。有关完整的攻击类别 → ASI 映射，请参见 [THREAT_MODEL.md](THREAT_MODEL.md)。 ## 评估 **回归防护（自身测试固件）。** 一个带有标签的语料库（`fixtures/`），包含故意设置漏洞的服务器和良性对照组；如果召回率下降或干净的对照组触发了发现，CI 就会失败： ``` uv run pytest -q -s # [self-eval] recall=100% precision=100% (0 false positives) ``` 这证明了检测器没有退化——但这相当于 Agentinel 给自己的作业打分。真正的考验是那些它*没有*编写过的工具定义： **真实世界目录。** [`fixtures/real-world/catalog.json`](fixtures/real-world/catalog.json) 保存了热门 MCP 服务器的公开工具规范（从其文档中复制，从未被执行过）。Agentinel 的判定结果： | 服务器 | 维度 | 判定结果 | |---|:--:|---| | **GitHub** | A·B·C | 🔴 致命三角 — 读取 issues/PRs（不受信任），读取私有代码库 + 密钥警报，创建/推送/合并 | | **Notion** | A·B·C | 🔴 致命三角 — 读取评论 + 数据库（不受信任），写入页面 | | Puppeteer | A | 🟠 不安全的代码执行 — `evaluate` 运行任意 JavaScript | | Kubernetes | B·C | 🟠 代码执行 — `kubectl_generic` 运行任何命令（同时接近致命三角） | | filesystem | B·C | 🟡 接近致命三角（读取 + 写入本地文件） | | git | B·C | 🟡 接近致命三角 | | GitLab | B·C | 🟡 接近致命三角（侧重于写入——正确地*未*被标记为完整的致命三角） | | Slack | A·C | 🟡 接近致命三角（读取频道历史记录，发送消息） | | Stripe | B·C | 🟡 接近致命三角（财务数据 + 资金流动） | | Sentry | A | ✅ 安全（读取不受信任的错误内容，但仅涉及一个维度） | | Postgres | B | ✅ 安全（只读查询——*未*被误标记为代码执行） | | Google Drive | B | ✅ 安全 | | fetch | A | ✅ 安全 | | memory | C | ✅ 安全 | | time | — | ✅ 安全 | 关于 GitHub 的判定结果与 Invariant Labs 披露的真实 [GitHub MCP exploit](https://invariantlabs.ai/blog/mcp-github-vulnerability) 相符。同样重要的是 Agentinel *没有*标记的内容：GitLab（侧重于写入）被判定为接近致命三角而非完整的致命三角，Postgres 的只读 `query` 没有被认定为代码执行，而 fetch/time/memory/Sentry/Drive 则保持静默——这种精确度在每次提交时都会通过真实世界目录进行回归测试。 ## CI / GitHub Action 拦截 pull requests 并将扫描结果上传到 GitHub code scanning： ``` - uses: markusweldon/agentinel/.github/actions/agentinel-scan@main with: stdio: "npx -y @acme/mcp-server@1.4.2" fail-on: high ``` 当发现有结果满足 `--fail-on` 条件时，`agentinel scan` 将以非零状态退出，并且 `--sarif` 输出结果会显示在 Security 标签页中。 ## 在你的助手中运行它 Agentinel 也可以作为 MCP 服务器运行，这样助手就可以按需审计工具定义： ``` claude mcp add agentinel -- uv run agentinel-mcp ``` 它公开了一个只读工具 `assess_tools`，用于分析你传递给它的工具元数据——它绝不启动或连接到任何东西（那种危险操作恰恰正是 Agentinel 会标记的内容）。实时扫描仍然保留在 CLI 中，由人工提供扫描目标。 ## 架构 ``` src/agentinel/ ├── mcp_client.py connect (stdio/HTTP) + enumerate tools/resources/prompts ├── config.py parse .mcp.json / Cursor / Claude / VS Code configs ├── taxonomy.py OWASP ASI01–10, severities, attack classes + metadata ├── models.py Pydantic: CapabilityAxes, Finding, Report, ProbeReport ├── static/ scan engine: classifier · trifecta · fleet · tool_poisoning · shadowing · capabilities ├── dynamic/ probe engine: llm · harness · adaptive (attacker-moves-second) ├── report/ terminal (rich) · sarif · html dashboard ├── scanner.py static orchestration → Report ├── prober.py adaptive probe orchestration → Report └── server.py Agentinel's own (read-only) MCP server ``` ## 伦理 动态探测会向正在运行的 agent 发送对抗性输入。**仅对你拥有或获得明确授权测试的 MCP 服务器进行探测。** Agentinel 绝不执行目标的工具，并使用合成的 canary 而非真实密钥。请参见 [ETHICS.md](ETHICS.md)。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：AI安全, Chat Copilot, MCP服务器, StruQ, 提示词注入检测, 静态代码审计