MCP Blast-Radius Auditor

MCP 爆炸半径审计器

在将任何 MCP 服务添加到 Agent 之前，了解它实际能触及哪些内容。

没有清单？仍可获得完整的爆炸半径报告。添加清单后，还能发现偏差。

此外，如果服务声明了清单：发现 MCP 服务触及它声称不会触及的文件，并在 CI 中阻止合并。

通过表层分析，静态提取第三方 MCP 服务能够访问的内容（文件、网络、子进程、环境变量）。存在清单时，将分析结果与声明的边界进行比较。

**扫描范围（默认）：**仅扫描生产包 — 排除 tests/、docs/、examples/、scripts/、benchmarks/、.github/ 和 test_*.py 模式；JSON 输出包含 scan_scope 和 excluded_file_count。传入 --include-peripheral 可扫描整个仓库。

只需 3 步即可试用

① 用一条命令扫描你的服务

pip install mcp-blast-radius==0.2.5
mcp-blast-radius-gate --gate-mode advisory --target-dir /path/to/your-mcp-server

将 --target-dir 指向你的发布包根目录（例如 src/）。默认范围会排除测试、文档和脚本。

② 阅读 JSON

字段	含义
gate_pass	扫描是否完成（advisory = 无论结果如何都生成报告；blocking = 出现偏差时以状态码 1 退出）
blocking_reasons	以 DIVERGENCE: 开头的行 = 声明与观测结果不一致（如果你发布了清单）
blast_radius	静态能力范围（网络、子进程、环境变量、文件系统）
confidence 标签	declared / observed-static / cannot-determine — 仅静态分析，表示上限

未声明的能力通常是配置漂移，并非恶意行为。网络/子进程计数应视为上限，而非已确认的流量。

③ 申请审计徽章（可选，自愿申请）

已完成干净的扫描，并想获得带签名的 README 徽章？提交徽章申请 — 粘贴你的命令和 JSON。免费，有效期 90 天，无回连。标准：BADGE_CRITERIA.md。

如需独立验证任何已发布的证明：pip install cryptography，然后运行 packaging/scripts/verify_attestation.py（接受本地路径或 HTTPS URL）。参见 BADGE_CRITERIA.md §Verify。

---

机器可读元数据

• Agent Card（能力、限制、定价）：agent_card.json
• 目录条目（定价、安装、MCP 端点）：aos-standard/catalog
• 规范：AOS-v0.1

示例演练

git clone --depth 1 https://github.com/oraios/serena.git /tmp/serena
mcp-blast-radius-gate --gate-mode advisory --target-dir /tmp/serena

检查 blast_radius 以及 blocking_reasons 中的任何 DIVERGENCE: 行。

报告扫描问题

提交 GitHub issue，并附上你的 JSON 输出（会自动加载结构化模板）。

30 秒扫描

pip install mcp-blast-radius
mcp-blast-radius-gate --gate-mode blocking --target-dir /path/to/mcp-server

pipx run mcp-blast-radius 会启动 MCP stdio 服务（用于 Claude Desktop / Cursor）。如需通过命令行扫描，请使用上文的 mcp-blast-radius-gate。

• **红色（阻止）：**检测到偏差 — 代码触及了清单中未声明的路径或能力。
• **绿色：**未发现偏差（或没有清单 — 仅生成爆炸半径报告，并以建议模式通过）。

安装

python3 -m venv .venv
source .venv/bin/activate
pip install .

CLI 入口

mcp-blast-radius          # MCP stdio server
mcp-blast-radius-gate     # CI gate (default blocking, exit 1 on fail)

CI 阻止门

mcp-blast-radius-gate --gate-mode blocking --target-dir .
# no divergences → exit 0 / divergences or declaration violations → exit 1

MCP 工具

• aos_compliance_validate — 扫描单个 MCP 服务目录（必须提供 target_dir；tool_id 为可选标签）
• aos_compliance_self_test — 连线冒烟测试

默认 gate_mode=advisory。在 CI 中使用 gate_mode=blocking，以便在出现偏差时失败。

提取内容

层级	范围	置信度
依赖项	requirements.txt、pyproject.toml、package.json	declared
Python AST	导入、文件 I/O、网络、环境变量、子进程；MCP 工具归属	observed-static / cannot-determine
差异	清单中的 permitted_output_paths / oracle_paths 与观察到的访问行为	不匹配时阻止

限制： 仅进行静态分析。动态导入、getattr/eval、混淆处理和原生扩展可能会隐藏功能。我们不声称覆盖全面——每项发现都包含一个 confidence 标签。

环境

变量	用途
AOS_VALIDATOR_TARGET_DIR	未提供 target_dir 时使用的默认扫描根目录
AOS_VALIDATOR_MCP_LOG	本地工具调用日志的 JSONL 路径（绝不会对外发送）
AOS_VALIDATOR_CALLER	调用方标签（ci、smoke_self_call 等）

示例

aos_compliance_validate target_dir=/path/to/my-mcp-server gate_mode=blocking

许可证

MIT