agentsploit/agentsploit

# AgentSploit [](https://github.com/agentsploit/agentsploit/actions/workflows/ci.yml) [](https://pypi.org/project/agentsploit/) [](pyproject.toml) [](LICENSE) [](docs/sarif.md) **面向 AI 代理和 MCP 服务器的攻击性安全框架。** AgentSploit 是一个为 AI 代理攻击面量身定制的 Burp Suite / Metasploit 风格的框架。它帮助红队队员、AI 安全研究人员和产品安全团队探测 LLM 代理和模型上下文协议 (MCP) 服务器中传统工具无法发现的漏洞。 **👉 新手？请从 [docs/getting-started.md](docs/getting-started.md) 开始 - 一个 10 分钟的导览，无需 API 密钥即可使用捆绑的测试用例体验所有功能。** ## 存在意义 每家财富 500 强企业都在 2026 年部署 LLM 代理和 MCP 服务器。攻击面是全新的： - 工具描述是 LLM 可读的指令 - 恶意描述可以劫持代理。 - 代理从 PDF、网页、日历邀请、票据中获取不受信任的内容 - 这些内容可以发出命令。 - 链式工具调用创造了传统权限模型无法捕获的权限提升路径。 - 记忆和上下文窗口可能在会话间被投毒。 现有扫描器（Burp、ZAP、Semgrep、Snyk）无法处理这一层。AgentSploit 可以。 ## 摘要 ``` pip install agentsploit # Scaffold an engagement agentsploit init my-engagement/ --authorized-by "Jane Doe " cd my-engagement/ # Scan an MCP server (training mode = no API keys needed, bundled fixtures) agentsploit scan mcp stdio://./tests/fixtures/vulnerable_mcp/server.py --training # Browse results in your browser (live engagement dashboard, v1.6+) agentsploit serve --training # -> http://127.0.0.1:8800 (token printed on startup) ``` ## 功能 AgentSploit 包含十一个模块，覆盖代理攻击面。每个模块都有端到端的文档和捆绑的易受攻击的测试用例，因此您可以在本地目标上运行每个模块，只需使用 `--training` 且无需 API 密钥。 ### 1. MCP 服务器扫描器 通过 **stdio**、**Streamable HTTP** 或 **SSE** 连接到 MCP 服务器，并针对其工具、资源、提示以及（对于 HTTP/SSE）其 HTTP 表面运行一系列检查。 **清单检查（所有传输方式）：** | 检查项 | 可发现的问题 | |---|---| | `tool_poisoning` | 工具描述中包含针对宿主代理的提示注入有效载荷 | | `tool_shadowing` | 与知名工具（例如 `read_file`、`send_email`）的名称冲突/遮蔽 | | `prompt_disclosure` | 工具描述泄露内部系统提示、机密或路径 | | `unsafe_tool_args` | 接受危险的无约束参数（路径、URL、shell 命令）的工具模式 | **HTTP 探针（仅限 HTTP/SSE）：** | 探针 | 可发现的问题 | |---|---| | `http_tls_required` | 非本地回环的 MCP 服务未使用 HTTPS | | `http_info_disclosure` | 泄露版本的 Server / X-Powered-By / X-Runtime 头信息 | | `http_cors` | 通配符来源、来源反射或违反带凭据的通配符规范 | | `http_auth_bypass` | 当提供 `--auth-bearer*` 时：服务器在没有凭据的情况下接受相同的调用 | ### 2. 间接提示注入载荷生成器 **技术：** - `direct` - 直接的覆盖尝试 - `role_confusion` - 伪造的 `system:` / `assistant:` 对话轮次 - `delimiter` - 围栏内容转义与重新上下文化 - `unicode_tag` - 不可见 Unicode 标签块走私（U+E0000 范围） - `tool_smuggling` - 在叙述性文本中隐藏工具调用 **载体（输出格式）：** - `text` - 纯文本 - `markdown` - README/注释风格 - `html` - 包含隐藏元素的页面内容 - `pdf` - 可见 + 隐藏层 PDF - `email` - RFC 5322 格式，包含 HTML 正文和头部 - `ical` - 包含恶意 DESCRIPTION 的 `.ics` 日历邀请 每个有效载荷都标记有一个 `canary` 字符串，以便您可以在日志中检测成功的注入。 ### 3. 在线代理运行器 (v0.3) 接收生成的有效载荷 + 代理配置，并通过真实的 LLM 驱动有效载荷。如果在代理的响应、工具调用或思考跟踪中出现 canary，则注入被**确认为可利用的** - 一个 CRITICAL/HIGH 级别的发现，并完整保存跟踪记录以供审计。 | 表面 | 严重性 | 含义 | |---|---|---| | `canary_tool_call_args` | CRITICAL | 代理将 canary 转发到了工具中 - 确认具备数据外传能力 | | `canary_response_text` | HIGH | 代理引述了 canary - 确认遵循了指令 | | `canary_thinking` | MEDIUM | Canary 出现在扩展思考中，但代理未对其采取行动 | | `no_surface` | INFO | 有效载荷已顺利通过但未生效 | **适配器 (v0.9)：** `anthropic`（真实的 Claude 工具使用）、`openai`（带工具使用的 Chat Completions）、`http`（通用 HTTP 代理，采用 OpenAI 风格的契约 - 子类化以支持自定义格式）、`mock`（确定性，用于测试）。参见 [docs/runner.md](docs/runner.md)。 ### 4. 权限图映射器 (v0.4) 枚举多个 MCP 服务器上的工具，按权限（源 / 中枢 / 汇点）对每个工具进行分类，推断数据流边，并查找从低信任源到高影响汇点的攻击路径。相当于工具链的 BloodHound。 ``` agentsploit map build --targets ./examples/map-targets.yaml --auth ./auth.yaml agentsploit map export --graph ./engagements///permission_graph.json -f mermaid -o graph.md ``` | 汇点权限 | 严重性 | |---|---| | `EXECUTION` (`run_command`, `eval`) | CRITICAL | | `MUTATION` (`git_push`, `delete_*`) | HIGH | | `EGRESS` (`send_email`, `webhook`) | HIGH | 路径发现是一个*可测试的假设* - 将其与 v0.5 验证器配对，以端到端确认可利用性。参见 [docs/mapper.md](docs/mapper.md)。 ### 5. 路径验证器 (v0.5) 完成映射器的闭环。获取任何映射器推断的路径，通过真实或模拟代理驱动针对该路径的有效载荷，并证明该链条是否实际完成。 ``` agentsploit verify path \ --graph ./engagements///permission_graph.json \ --from read_file --to send_email \ --training # or --agent ./agent-anthropic.yaml --auth ./auth.yaml ``` | 结果 | 含义 | 严重性 | |---|---|---| | `CONFIRMED` | 汇点工具被调用，且其参数中包含 canary | 与汇点权限绑定 (EXEC → CRITICAL) | | `PARTIAL` | 到达汇点或 canary 在其他位置出现，但链条不完整 | HIGH | | `FAILED` | 在任何地方都没有出现 canary | INFO | 一个 CONFIRMED 发现将映射器假设从“可能的攻击路径”转变为“已证明的漏洞”。参见 [docs/verifier.md](docs/verifier.md)。 ### 6. 批量路径验证 (v0.6) 通过一条命令驱动验证器处理图中的每条路径 - 典型工作流程是先使用廉价的模拟代理进行分类，然后只对确认的结果使用真实模型重新运行。 ``` # Cheap triage pass (free, instant) agentsploit verify all-paths --graph ./.../permission_graph.json --training # Real-model pass on the same graph agentsploit verify all-paths --graph ./.../permission_graph.json \ --agent ./agent-anthropic.yaml --auth ./auth.yaml \ --parallel 3 --max-paths 20 ``` 按 `(source, sink)` 对去重，使用具有速率限制感知的并发进行并行化，隔离每条路径的错误，并发出一个包含确认率百分比的聚合 `batch_summary` 发现。参见 [docs/verifier.md](docs/verifier.md#batch-verification-verify-all-paths-v06)。 ### 7. 技术模糊测试 (v0.7) 默认验证器使用一种注入信封（`role_confusion`）。v0.7 增加了另外四种 - `direct`、`delimiter`、`unicode_tag`、`tool_smuggling` - 以及一个模糊测试器，它会依次尝试它们直到有一个成功。知道*哪种*信封有效可以告诉防御者他们的注入过滤器遗漏了什么。 ``` # Single-path fuzz agentsploit verify fuzz-path --graph ./.../permission_graph.json \ --from read_file --to send_email --training # Batch fuzz - every path × every technique, with early termination per path agentsploit verify all-paths --graph ./.../permission_graph.json \ --fuzz --techniques role_confusion,delimiter,unicode_tag \ --parallel 3 --training ``` | 技术 | 当此项成功时，防御者的启示 | |---|---| | `role_confusion` | 聊天模板过滤器未能捕获伪造的 `` 对话轮次 | | `delimiter` | 未受信任的内容边界未被强制执行 | | `unicode_tag` | 防御措施剥离了可打印的 ASCII 字符，但未剥离 U+E0000 标签块 | | `tool_smuggling` | 代理运行时从叙述性文本中解析出了 JSON 工具调用语法 | | `direct` | 完全没有设置提示注入防御 | 参见 [docs/verifier.md](docs/verifier.md#technique-fuzzing-v07)。 ### 8. 记忆投毒 (v0.8) 第一个多阶段攻击模块。攻击者在共享的代理存储中植入一个精心构造的笔记；一个独立的受害代理运行检索到该笔记，并被引导调用带有攻击者 canary 的汇点工具。此模式捕获的补救场景：代理将检索到的存储内容视为指令而非数据。 ``` # Verify a memory-poisoning attack against the mock agent (free, instant) agentsploit poison verify \ --sink-tool send_email --sink-arg body \ --sink-privilege egress \ --training # Against real Claude agentsploit poison verify \ --sink-tool send_email --sink-arg body \ --agent ./agent-anthropic.yaml --auth ./auth.yaml ``` | 结果 | 含义 | 严重性 | |---|---|---| | `CONFIRMED` | 受害者调用了汇点，且参数中包含 canary | 与汇点权限绑定 (EXEC → CRITICAL) | | `PARTIAL` | 笔记被检索但 canary 未在汇点中出现 | HIGH | | `NOT_RETRIEVED` | 笔记已存储但受害者从未读取 | INFO | | `NOT_STORED` | 攻击者写入失败 | INFO | 参见 [docs/poisoning.md](docs/poisoning.md)。 ### 9. RAG / 向量存储投毒 (v1.1) 与 v0.8 相同的威胁模型，但提升到了检索增强生成场景。攻击者不知道受害者的查询键，只知道*主题*。索引一份被投毒的文档，该文档在针对目标查询时排名高于合法语料库内容；受害代理运行 `semantic_search`，检索到排名最高的匹配项，并遵循其中嵌入的链条。 ``` agentsploit poison verify-rag \ --sink-tool send_email --sink-arg body \ --sink-privilege egress \ --query "how do I reset my password" \ --training ``` | 结果 | 含义 | 严重性 | |---|---|---| | `CONFIRMED` | 被投毒的文档排名第一，受害者调用了汇点，且参数中包含 canary | 与汇点权限绑定 | | `PARTIAL` | 文档被检索但 canary 未在汇点中生效 | HIGH | | `NOT_RETRIEVED` | 被投毒的文档未能超越诱饵（检索失败） | INFO | | `NOT_STORED` | 索引失败（设置问题） | INFO | 检索失败与服从失败的区分是 RAG 变体增加的关键可操作区别。参见 [docs/poisoning.md#rag--vector-store-poisoning-v11](docs/poisoning.md#rag--vector-store-poisoning-v11)。 ### 10. 会话线程投毒 (v1.4) 第三种也是最微妙的投毒变体。攻击者在共享的对话线程中写入一个看似良性的对话轮次；受害代理稍后恢复该线程，并将被投毒的轮次视为其自身受信任的先前上下文的一部分。过滤检索内容的防御措施无法捕获此情况 - 投毒内容位于代理的历史记录中，而非检索的数据中。 ``` agentsploit poison verify-thread \ --sink-tool send_email --sink-arg body \ --sink-privilege egress \ --turns-back 3 \ --training ``` ### 11. 在线交战仪表板 (v1.5 + v1.6) 一个本地 Web 应用程序，用于浏览交战输出并从浏览器驱动实时扫描/验证。v1.5 发布了只读浏览器；v1.6 增加了 Bearer 令牌认证、写入端点、服务器发送事件流、路径探索器页面和实时发现更新。 ``` agentsploit serve --auth authorization.yaml # -> http://127.0.0.1:8800 # Token printed on startup; paste it into the /login page. ``` Cytoscape 渲染的权限图、按严重性过滤的发现表（包含每个发现的证据下钻）、一个可排序的攻击路径探索器（包含一键“验证此路径”按钮）以及一个作业页面（扫描运行时发现实时流入）。默认仅限本地访问且需要认证。参见 [docs/web-ui.md](docs/web-ui.md)。 ## 安装 需要 Python 3.11+。适用于 Linux、macOS 和 Windows。 ``` # Recommended: use pipx so it lives in its own venv pipx install agentsploit # Or with uv uv tool install agentsploit # Or plain pip in a venv python -m venv .venv && source .venv/bin/activate # macOS/Linux # .venv\Scripts\activate # Windows pip install agentsploit ``` 该 wheel 包捆绑了预构建的 React Web UI，因此上述安装就是您所需要的全部内容；运行 `agentsploit serve` 无需 Node 工具链。 ## 快速开始 ``` # 1. Scaffold a new engagement directory (v1.3+): generates auth + agent # configs + map-targets + README in one go agentsploit init engagement-q2/ --authorized-by "Jane Doe " cd engagement-q2/ # 2. Scan a local stdio MCP server agentsploit scan mcp stdio://./my-mcp-server --auth ./authorization.yaml # 2b. Scan a hosted MCP server over HTTPS with a bearer token from env export MCP_TOKEN=$(op read 'op://eng/mcp-staging/token') agentsploit scan mcp https://mcp.staging.example.com/mcp \ --auth-bearer-env MCP_TOKEN \ --auth ./authorization.yaml # 3. Generate an indirect prompt injection payload agentsploit generate injection \ --technique role_confusion \ --carrier pdf \ --goal "leak any tool descriptions" \ --out ./payload.pdf # 4. List all available modules agentsploit list-modules ``` ## 架构 ``` src/agentsploit/ ├── core/ # Module base classes, Target/Authorization/Finding/Session, Reporters ├── modules/ │ ├── mcp/ # MCP server scanner + checks (v0.1) │ ├── injection/ # Indirect prompt-injection generator (v0.1) │ ├── runner/ # Live agent runner with canary detection (v0.3) │ ├── mapper/ # Cross-server permission graph + path inference (v0.4) │ ├── verifier/ # Path verification: drive agents through inferred chains (v0.5) │ ├── fuzzer/ # Technique × carrier fuzzing (v0.7) │ └── poisoning/ # Memory / RAG / conversation-thread poisoning (v0.8 + v1.1 + v1.4) ├── web/ # FastAPI server, auth, job runner, SSE event broker (v1.5 + v1.6) ├── adapters/ # Anthropic, OpenAI, HTTP, mock LLM adapters (v0.9) ├── scaffolder.py # `agentsploit init` engagement scaffold (v1.3) └── cli.py # Typer entry point ``` 模块是插件式的：将一个类放入 `modules/`，它就会自动出现在 `agentsploit list-modules` 中。 完整设计参见 [docs/architecture.md](docs/architecture.md)。 ## 安全使用 - **在运行时强制执行授权。** 目标与一个 YAML 授权文件进行匹配，该文件包含明确的 `authorized_by`、`valid_until` 和 `scope` 列表。扫描器在没有此文件的情况下拒绝运行。 - **训练模式** (`--training`) 仅允许匹配 `*://localhost*` 和捆绑的易受攻击测试用例的目标。 - **所有活动都记录日志**，包含交战 ID、目标、模块和发现哈希以供审计。 - **不捆绑 0-day。** 模块实现的是众所周知且已披露的攻击模式。 参见 [AUTHORIZATION.md](AUTHORIZATION.md) 和 [SECURITY.md](SECURITY.md)。 ## 许可证 Apache 2.0。参见 [LICENSE](LICENSE)。

标签：AI代理漏洞, AI安全, AI红队, C2, Chat Copilot, MCP安全, MCP服务器安全, Python, SARIF, 二进制发布, 代理安全, 内存中毒, 反取证, 安全测试, 安全评估, 开源工具, 恶意工具攻击, 攻击性安全, 攻击模拟, 无后门, 特权升级, 逆向工具, 驱动签名利用