MCP Tool Security Inspector

针对 Model Context Protocol 工具元数据的可解释、确定性静态分析。

安全声明： MCP Tool Security Inspector 是一款防御性分析工具。它识别可能值得审查的指标，但不确定 MCP 工具或服务器是否绝对恶意或安全。

截图占位符

• screenshots/clean-scan.png — 干净目录摘要

• screenshots/suspicious-scan.png — 发现证据与建议

• screenshots/drift-comparison.png — 基线漂移表

Related MCP server: mcp-guardian

问题

AI 客户端通常会将 MCP 工具名称、描述、模式（schema）和元数据暴露给模型。该目录是一个信任边界：误导性指令、隐藏能力、意外的凭据字段或后续的模式变更，即使没有工具运行也值得审查。mcpsec 分析该静态表面，不调用工具，也不获取元数据 URL。

什么是 MCP 和 MCP 工具？

Model Context Protocol 是一种开放协议，用于将 AI 应用程序连接到暴露上下文和能力的服务器。工具是一种具名的可调用能力，带有描述性元数据以及输入和可选输出的 JSON Schema。本版本针对官方 2026-07-28 规范和稳定的官方 Python SDK v2，同时兼容较旧的常见目录封装格式。

威胁模型与工具投毒

工具元数据可能影响人工审批和模型工具选择。恶意发布者、被攻陷的服务器、依赖或意外配置都可能添加模型导向的指令、隐藏措辞、特权字段或混淆。参见 威胁模型 和 工具投毒。

功能

• 单工具、数组、直接 tools 对象和 JSON-RPC tools/list 响应加载

• 未知字段保留和 Unicode NFC 规范化

• 稳定的 UTF-8 规范 JSON 和 SHA-256 完整/组件指纹

• 注重隐私的基线和字段级漂移分类

• 指令覆盖、隐藏、敏感数据、模式、不匹配、混淆和能力检测器

• 使用安全加载和有界字面匹配的严格纯数据 YAML 规则

• 可解释的、有上限的 0–100 风险评分

• 丰富的终端、JSON、CSV 和 SARIF 2.1.0 输出

• 证据脱敏和电子表格公式注入缓解

• CI 严重性阈值及文档化的退出码

• 无遥测、无工具调用、无图标下载、无 URL 获取、无元数据执行

架构

flowchart LR
  A["Hostile JSON catalog"] --> B["Bounded loader"]
  B --> C["Normalizer"]
  C --> D["Canonicalizer + SHA-256"]
  C --> E["Detectors + data-only rules"]
  E --> F["Capped risk engine"]
  D --> G["Baseline comparator"]
  F --> H["Terminal / JSON / CSV / SARIF"]
  G --> H

该实现从不将目录内容发送给模型，也从不执行扫描值。参见 架构。

安装

python -m venv .venv
# Windows: .\.venv\Scripts\Activate.ps1
# Linux/macOS: source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
mcpsec --help

参见 PREPARATION.md 了解审计环境和编辑器建议。

快速开始与扫描

mcpsec scan examples/clean_tools.json
mcpsec scan examples/suspicious_tools.json
mcpsec scan examples/mixed_tools.json --format json
mcpsec scan examples/suspicious_tools.json --format csv --output report.csv --redact
mcpsec scan examples/suspicious_tools.json --format sarif --output report.sarif
mcpsec scan examples/mixed_tools.json --rules rules/default_rules.yml --fail-on high

结构化报告不包含 ANSI 转义序列。以电子表格公式字符开头的 CSV 字段会以撇号作为前缀。

基线与模式漂移工作流

mcpsec baseline examples/clean_tools.json --output baseline.json
mcpsec compare examples/clean_tools.json --baseline baseline.json
mcpsec compare examples/changed_tools.json --baseline baseline.json --verbose
mcpsec fingerprint examples/clean_tools.json

更改后的夹具修改了计算器描述和输入模式，并添加了 unit_converter。基线存储哈希和结构摘要，而非完整描述、默认值或示例机密。参见 模式漂移。

风险评分

每个发现的配置贡献乘以置信度。贡献按类别分组并上限为 35；类别风险使用 100 × (1 − Π(1 − category/100)) 组合。两个已记录的关联增加有界协同：指令覆盖 + 隐藏增加 10，隐藏 + 敏感数据语言增加 7。最终值四舍五入并上限为 100。

区间：0–19 信息性，20–39 低，40–59 中，60–79 高，80–100 严重。评分用于优先审查；它不是概率或结论。

规则与可解释性

mcpsec rules list
mcpsec rules validate rules/default_rules.yml
mcpsec explain SEC-001

自定义规则允许 ID、名称、类别、字段、字面模式、严重性、置信度、评分、建议、理由、良性用途和启用状态。它们不能包含 Python 表达式、shell 命令、导入、模板或可执行正则表达式。参见 检测规则。

输出格式

终端表格汇总工具数量、干净/受影响总数、严重性、风险、规则 ID、证据和建议。JSON 保留类型化发现；CSV 便于分析；SARIF 提供与 GitHub 代码扫描兼容的结构，供未来集成使用。

CI 使用

退出码为 0（未超过配置阈值）、1（完成的扫描超过 --fail-on）、2（无效用户输入）和 3（内部故障）。

mcpsec scan catalog.json --fail-on medium

附带的 GitHub Actions 工作流安装 Python，运行 Ruff lint/format 检查、mypy 和带覆盖率的 pytest。它不需要机密，不连接服务器，也不发布。

测试

ruff check .
ruff format --check .
mypy src
python -m pytest --cov=mcpsec --cov-report=term-missing --cov-report=html

在 Windows 上，scripts\test.ps1 -q 即使环境未激活也会运行正确的虚拟环境解释器。使用 scripts\dev-inspector.ps1 启动本地演示服务器；参见 示例服务器指南。Inspector 打印的 /sandbox 地址是内部 iframe 端点，不是主用户界面。

测试涵盖输入形状、Unicode、规范化、哈希、基线、漂移、检测器、风险上限、规则验证、安全 YAML、结构化报告、CSV 中和以及 CLI 退出码。

安全模型与误报

所有输入都是不可信数据。文件有大小限制；字符串有长度限制；YAML 使用 safe_load；模式内容经过验证但从不求值；自定义匹配是字面且有界的；终端转义字节被中和；报告器不渲染 HTML。发现结果说"可疑"或"需要审查"，从不断言被攻陷。每个内置规则都通过 mcpsec explain 记录其理由、良性触发因素和指导。

参见 SECURITY.md、检测规则 和 限制。

限制

干净扫描不建立信任；可疑扫描不证明恶意意图。静态元数据可能与运行时实现不同。启发式方法无法理解每种语言、业务上下文、模式引用或提示注入变体。人工审查和运行时控制仍然必要。

路线图

• v0.2：仅使用 SDK tools/list 的可选加入、白名单本地目录检索

• 更丰富的 MCP 2026-07-28 x-mcp-header 验证

• 签名基线信封和基线策略配置文件

• 规则包版本控制、带理由的抑制和增量 SARIF

• 更多语言感知启发式方法和基于语料库的误报测量

贡献与许可

参见 CONTRIBUTING.md。安全报告遵循 SECURITY.md。根据 MIT 许可证 授权。