euanmcrosson-dotcom/mcp-recon

# mcp-recon [](https://github.com/euanmcrosson-dotcom/mcp-recon/actions/workflows/ci.yml) [](LICENSE) [](docs/SPEC.md) [](#tests) [](https://github.com/euanmcrosson-dotcom/capnagent) 核心论点：目前每个正在采用 MCP 的团队都在问*“这个 服务器实际上做了什么？”*，然而并没有对应的工具。智能体生态系统 的增长速度超过了其安全工具的发展速度。mcp-recon 正是为了填补这一空白中的侦察部分而诞生的。[capnagent](https://github.com/euanmcrosson-dotcom/capnagent) 则是防御端：获取侦察报告，推导出严格的 能力约束，并拒绝约束之外的一切操作。 ## 目录 - [概览](#at-a-glance) - [核心功能](#what-you-get) - [命令速查表](#command-cheatsheet) - [输出示例](#sample-output) - [通过单条管道实现 侦察 → capnagent](#recon--capnagent-in-one-pipe) - [为什么会有这个项目](#why-this-exists) - [安装](#installation) - [横向对比](#how-it-compares) - [本项目不是什么](#what-this-is-not) - [测试](#tests) - [伴生项目 — capnagent](#companion-project--capnagent) - [许可证](#license) ## 概览 | 覆盖范围 | 攻击面 | 性能 | |---|---|---| | **4 / 4** 扫描了 Anthropic 参考服务器 | **5** 条命令 · **4** 个 schema 标记的产物 | 在 14 个工具的服务器上，扫描预算=200，耗时 <60s | | 在公开数据集中分类了 **37 个工具** | enumerate · fuzz · classify · report · scan | 确定性的（带有种子的 PRNG，默认 `0xC0FFEE`） | | 在数据集上进行 **1374 次 fuzz 调用**（1 项已确认的 DoS 发现） | 基于规则，而非由 LLM 介入 | 在 100 个工具的服务器上内存占用 <256MB | 将工具映射到 **OWASP LLM01 / LLM06 / LLM08** 和 **MITRE ATLAS** 类别。每次输出都会附带一个可复制粘贴的、针对每个工具的 [capnagent](https://github.com/euanmcrosson-dotcom/capnagent) 约束条款。可重现性契约详见 [capnagent 的 `docs/EVALUATION.md`](https://github.com/euanmcrosson-dotcom/capnagent/blob/master/docs/EVALUATION.md)。 ## 核心功能 对任何 MCP 服务器（stdio 或 HTTP）运行 `mcp-recon scan`，即可获得 一个证据文件夹：工具清单、fuzz 记录、 分类结果，以及一份安全审查人员或值班开发人员都能轻松阅读的 Markdown 威胁画像。JSON 文件是报告中链接到的 可被机器解析的证据。针对公共数据集中的任意 4 个服务器运行，你的输出将与 `examples/public-servers/server-/` 中的内容逐字节匹配。 ## 命令速查表 ``` mcp-recon enumerate # → inventory.json mcp-recon fuzz [--budget=N] [--seed=N] # → fuzz.json mcp-recon classify [--fuzz=] # → classification.json mcp-recon report [--fuzz=] # → report.md mcp-recon scan --out= [--budget=N] [--seed=N] # → 4 artefacts ``` 服务器规格格式：`stdio: [args...]`（启动进程，通过 stdio 通信）或 `http://host:port`（HTTP 传输）。 ## 输出示例 ``` $ mcp-recon scan "stdio:npx -y @modelcontextprotocol/server-filesystem /tmp" \ --out=./reports/filesystem --budget=200 mcp-recon: 14 tools, 4 confused-deputy candidates mcp-recon: fuzz — ok=4 protocol_error=719 runtime_error=0 mcp-recon: wrote 4 artefacts to ./reports/filesystem/ $ ls ./reports/filesystem/ inventory.json fuzz.json classification.json report.md ``` 以下是生成的 `classification.json` 的一个代码片段 —— 每个工具都会获得 一个分类、一个权限级别、一个混淆代理结论以及 一个可复制粘贴的 capnagent 约束条款： ``` { "tool": "edit_file", "data_class": "filesystem", "authority_level": "write", "confused_deputy_candidate": true, "confidence": 0.91, "rationale": "name match \"\\b(write[_-]?file|edit[_-]?file|create[_-]?directory|move[_-]?file)\\b\" → filesystem/write (0.70); description match → filesystem/read (0.50); schema: arg \"path\" is path-shaped → filesystem (0.40); user-controllable string arg + non-read authority → confused-deputy candidate", "recommended_caveat": "tool == \"edit_file\" AND caller == \"\" AND arg.path starts_with \"/\" AND now <= @ // WRITE filesystem" } ``` 完整的重点发现 —— 包括 `everything` 服务器的 DoS 攻击面和 `filesystem` 包装器的缺失边界 —— 位于 [`docs/WRITEUP.md`](docs/WRITEUP.md) 中。 ## 通过单条管道实现 侦察 → capnagent ``` ┌──────────────┐ inventory.json ┌──────────────┐ │ │ fuzz.json │ │ │ MCP server │ ──▶ classification ──▶│ capnagent │ ──▶ deny anything │ │ .json │ issuer │ outside scope │ │ report.md │ │ └──────────────┘ └──────────────┘ ▲ │ │ ▼ └────────── scoped caller ◀────── signed capability ``` mcp-recon 负责记录工具表面；capnagent 负责执行边界限制。 每个项目均可独立运行。结合使用，它们便构成了任何 MCP 架构智能体 的统一安全态势。先运行 mcp-recon，然后将 建议的约束条款粘贴到你的 capnagent 签发器中，即可发布。 ### 通过单条管道从侦察到 capnagent 签发器 `classification.json` 为每个工具提供了一个可复制粘贴的约束条款，但 手动粘贴本身就是一种潜在风险。`caveats` 命令会生成一个 机器可读的签发计划，可直接输入到 capnagent 签发器中： ``` $ mcp-recon caveats ./reports/filesystem/classification.json \ --caller=agent:planner \ --sandbox-prefix=/var/agent-sandbox/tenant-42 \ --expiry=2026-12-31T23:59:59Z \ > ./reports/filesystem/caveats.json mcp-recon: 14 plans (14 ready, 0 flagged) — schema=mcp-recon/v0.1/caveats ``` 输出的文档（模式为 `mcp-recon/v0.1/caveats`）每个 工具对应一个条目，其中 `caveats: string[]` 已被拆分为单独的 capnagent DSL 谓词，并替换了操作符绑定。计划会 使用结构化的原因集进行标记（`classification_unknown`、`low_confidence`、 `cdc_without_arg_constraint`、`unsubstituted_placeholder`），从而使 审查面可通过机器进行检查。 不使用任何绑定运行可获取“审查过程”—— 每个计划都会被标记， 但你可以确切地看到在 提交具体值之前需要绑定哪些占位符。特定工具的覆盖（库 API 中的 `per_tool_overrides`）可让你进一步收紧分类器 未加约束的潜在混淆代理。 ## 为什么会有这个项目 **为了正在采用 MCP 的开发者。** 在将第三方 MCP 服务器接入你的智能体之前，先对其运行 mcp-recon。你可以在 30 秒内获得一份 真实的威胁画像 —— 这个东西*实际上* 允许智能体做什么，以及保留其效用的最小约束是什么？ **为了审计智能体技术栈的安全团队。** mcp-recon 将 “我们依赖 N 个 MCP 服务器” 转化为 “这是整合后的工具 表面，这是每个工具的分类，这里是潜在的 混淆代理所在。” 一份你可以审阅的可打印工件。 **为了 AI 安全研究人员。** mcp-recon 的报告是 [capnagent 紫队语料库](https://github.com/euanmcrosson-dotcom/capnagent/tree/master/docs/purple-team) 中第 N 轮分析报告的 输入。 侦察 → 能力差距 → 攻击 PoC → 修复 → CLOSED。 ## 安装 ``` # 通过 npm 安装（推荐 — v0.2.2+） npx mcp-recon scan \ "stdio:npx -y @modelcontextprotocol/server-filesystem $HOME/sandbox" \ --out=./reports/filesystem --budget=200 # 或者全局安装 npm install -g mcp-recon mcp-recon --help ``` 用于开发： ``` git clone https://github.com/euanmcrosson-dotcom/mcp-recon cd mcp-recon npm install npm run -w mcp-recon build # 通过 tsx 直接运行 CLI（开发环境无需构建步骤） npx tsx packages/mcp-recon-cli/src/bin/recon.ts scan \ "stdio:npx -y @modelcontextprotocol/server-filesystem $HOME/sandbox" \ --out=./reports/filesystem --budget=200 ``` ## 文档 - [`docs/SPEC.md`](docs/SPEC.md) — v0.1 表面，服务器规格语法，输出模式 - [`docs/METHODOLOGY.md`](docs/METHODOLOGY.md) — 分类器规则，fuzz 维度，信号，可证伪性 - [`docs/WRITEUP.md`](docs/WRITEUP.md) — 公共数据集发现 + 核心观察结论 - [`schemas/`](schemas/) — 四种传输格式的正式 JSON Schema 文件 - [`findings/`](findings/) — 记录在案的发现语料库 (F001–F006) - [`SECURITY.md`](SECURITY.md) — 漏洞报告政策 - [`CONTRIBUTING.md`](CONTRIBUTING.md) — 如何添加分类器规则、fuzz 维度、数据集条目 ## 横向对比 | | mcp-recon | [NVIDIA garak](https://github.com/NVIDIA/garak) | Burp / ZAP | 手动审查 | |---|---|---|---|---| | **范围** | MCP 服务器工具表面 | 模型行为测试 | HTTP 模糊测试 | 一切 | | **输出** | 结构化 JSON + Markdown | 报告 | 代理日志 | 人工文本 | | **确定性** | 是（带种子的 PRNG） | 部分 | 否 | 否 | | **LLM 参与** | 否（基于规则） | 是 | 否 | 是 | | **OWASP LLM / MITRE ATLAS 映射** | 是（按工具） | 部分 | 否 | 取决于作者 | | **配套强制执行** | [capnagent](https://github.com/euanmcrosson-dotcom/capnagent) | 无 | 无 | 无 | mcp-recon **并不能**替代上述任何工具 —— 它是 其他人没有在构建的那一环：一种确定性的、具备 schema 感知能力的 MCP 服务器工具表面表征，且采用 可直接接入能力边界执行层的格式。 ## 本项目不是什么 - **不能替代 capnagent。** mcp-recon 记录了当前的 内容；capnagent 则强制执行被允许的内容。这两者你都需要。 - **不是针对模型本身的漏洞扫描器。** 请使用 [NVIDIA garak](https://github.com/NVIDIA/garak) 实现此目的。我们 测试的是*工具表面*，而不是模型行为。 - **不是漏洞利用框架。** 我们发送恶意的 schema 是为了表征其处理能力，而不是进行实际的漏洞利用。 - **不是代理 / MITM 工具。** 这超出了项目范围。参见 [`docs/SPEC.md`](docs/SPEC.md) §“v0.1 不做什么”。 ## 测试 该工作区目前通过了 **68 个单元及基于属性的测试** （`npm test`），涵盖了 schema 解析、带种子的 PRNG、所有六个恶意维度的 fuzz 生成器、分类规则、Markdown 报告渲染器以及端到端的 `scan` 流程。 另外两个集成测试文件（`enumerate.integration.test.ts`、 `fuzz.integration.test.ts`）在本地生成 MCP 服务器的情况下，对实际传输进行了 测试。 ``` npm test # all packages, vitest npm run typecheck # tsc --noEmit, strict mode npm run lint # biome check ``` ## 伴生项目 — capnagent mcp-recon 是 [capnagent](https://github.com/euanmcrosson-dotcom/capnagent) 的攻击侧（互补）组件， 后者为 AI 智能体的工具调用提供了能力受限的授权。它们共同实现了 标准的*先侦察后设限*安全工作流： ``` [ mcp-recon ] → threat profile → [ capnagent ] "what is "what should "deny anything here?" we allow?" outside that" ``` 每个项目均可独立运行。结合使用，它们便构成了任何 MCP 架构智能体 的统一安全态势。 ## 许可证 [Apache-2.0](LICENSE)。

标签：MCP服务器, MITM代理, 云资产清单, 代理安全, 安全合规, 安全扫描, 开源安全工具, 攻击面分析, 无线安全, 时序注入, 暗色界面, 模式识别, 网络代理, 网络安全, 能力枚举, 自动化攻击, 逆向工程, 逆向工程平台, 隐私保护