mcp-supply-audit

mcp-supply-audit

将 MCP 服务作为软件制品进行审计：注册表条目、软件包、配置和工具定义。

一个 MCP 服务。仅进行静态检查。它绝不会运行所检查的代码。

状态：预发布，正在开发中。 尚未发布。此处内容不构成安全保证。

快速开始

在安装 MCP 服务之前，检查其注册表条目、软件包、配置和工具定义。

对于 Claude Code，使用 uv：

claude mcp add mcp-supply-audit -- uvx mcp-supply-audit

若要固定一个版本，请改用 uvx [email protected]。scan_mcp_config 会在扫描的配置中标记未固定版本的形式（CF001）。

对于 Claude Desktop，请将以下内容添加到其配置文件中的 mcpServers：

{
  "mcpServers": {
    "mcp-supply-audit": {
      "command": "uvx",
      "args": ["mcp-supply-audit"]
    }
  }
}

然后粘贴类似以下内容的提示词：

• “在安装 MCP 服务 <namespace>/<name> 之前对其进行审计。”
• “扫描此 MCP 配置：”后接你的配置 JSON。
• “检查 npm 软件包 <name> 是否有安全公告和安装脚本。”

隐私。 所有工具都接受粘贴的文本或名称，不接受文件路径。配置扫描报告不会显示环境变量、标头或参数的值，也不会显示 URL 路径或查询参数。报告会显示服务名称、键名、参数位置，以及 URL 的协议、主机和端口。你粘贴的文本仍会像其他消息一样发送给 MCP 客户端及其模型，因此请先移除真实密钥。

示例：扫描由 4 个虚构服务组成的配置，其中包含一个未固定版本的 npx 软件包、一个纯 HTTP URL、env 中的明文 API 密钥以及 / 路径参数，还有 bash -c。输出采用 scripts/demo.py 的摘要格式，并精简了覆盖范围列表：

Severity counts: critical 0, high 3, medium 2, low 0, info 0
Assessment: findings_present

Findings (5):
  [high] CF002: Remote server URL does not use https
      at servers[1].url
  [high] CF003: Credential-named env entry holds a literal value
      at servers[2].env
  [high] CF004: Server starts through a shell (sh) with an inline script
      at servers[3].args[0]
  [medium] CF001: Package runner (npx) runs a package with no version, not an exact version
      at servers[0].args[1]
  [medium] CF005: Path argument grants a filesystem root
      at servers[2].args[2]

Checks that ran (16):
  CF001:servers[0]
  ...
Skipped checks (12):
  CF002:servers[0]: not_applicable
  ...
Notes:
  - Servers scanned: 4. Servers skipped: 0.
  - Absence of findings is not proof of safety. Only static checks were run; see coverage for which checks ran and which were skipped.

发现项仅供审查参考，并非最终判定。也请查看跳过的检查。

从源代码检出目录运行

在此仓库的检出目录中运行 uv sync，然后将客户端指向该目录：

claude mcp add mcp-supply-audit -- uv --directory /path/to/mcp-supply-audit run mcp-supply-audit

为什么要开发此项目

大多数 MCP 安全扫描器都侧重于工具描述。本项目将服务视为供应链制品进行检查：注册表条目是否与其软件包和仓库匹配，名称是否与热门名称相似，软件包版本自身的元数据和安全公告说明了什么，以及你即将复制的配置实际上会执行什么操作。

当前可用功能

通过 FastMCP 服务以 stdio 方式提供 6 个工具（工具接口）。所有工具均为只读，只接受名称或粘贴的文本，不接受路径。

• audit_server：并发运行以下适用于单个服务的检查（注册表名称，或软件包名称加 pypi/npm），总时限为 30 s，并返回一份合并报告。失败或超时的检查会列为已跳过；报告的其余部分仍会返回。
• audit_registry_entry：检查 MCP Registry 条目与其软件包之间的一致性、所有者匹配情况、软件包和版本是否存在、所有权标记、状态以及远程 URL（以文本形式）。
• audit_package：检查某个 PyPI 或 npm 软件包版本的 OSV.dev 安全公告、撤回或弃用状态、安装脚本（仅限 npm）、来源证明、发布时效（仅限 PyPI）以及声明的仓库。
• check_typosquat：检查名称是否与日期标注的参考列表中的名称相似（精选的 PyPI 和 npm 名称；对于注册表名称，还包括从 MCP Registry 抓取的名称）。
• scan_mcp_config：扫描 MCP 客户端配置中的服务，检查未固定版本的运行器、纯 HTTP 远程服务、硬编码密钥、Shell 包装程序、宽泛路径、非注册表来源和高风险环境变量。
• scan_tool_definitions：检查 tools/list 快照中的隐藏 Unicode 字符、类似指令的措辞、跨工具引用、数据外传措辞、编码后的数据块及其他指标。

出站请求仅发送到 registry.modelcontextprotocol.io、pypi.org、registry.npmjs.org 和 api.osv.dev。

设计原则

• 绝不执行扫描目标。 仅进行静态分析和元数据检查。没有工具接受文件系统路径。
• 默认将输入视为恶意内容。 目标中的文本经过净化、长度限制，且仅作为带引号的证据，在 untrusted_text 下返回。隐藏字符会显示为可见的 \uXXXX 转义序列。
• 使用确定性规则，不在检测中使用大模型。 结果可复现，并经过单元测试。
• 发现项仅作为指示，不是定论。 每份报告都会列出已运行和已跳过的检查，并说明没有发现项并不能证明安全。
• 按 ID 映射至 OWASP MCP Top 10（测试版，v0.1）。

限制

静态检查无法观察运行时行为。审计和遥测方面的盲区、影子服务以及上下文过度共享均不在此工具的检测范围内。

各项检查的限制：注册表检查、 软件包检查、 拼写仿冒检查、 配置检查。

评估

数据来自 docs/eval-baseline.md，测量日期为 2026-11-09，仅针对工具定义规则 TD001 至 TD008。发现项是供审查的指示，并非定论；没有发现项并不能证明安全。

测量内容。 对 19 个正例进行静态检测（属于单个 tools/list 快照的范围，且来源均已获取并阅读），对这些正例生成的 125 个变异样本进行检测，并使用包含 9 个服务和 77 个工具的良性语料库。共运行两次：一次是在任何规则变更之前进行的基线测试；另一次是在相同测试样本上调整 TD002 至 TD004 后进行的测试，属于样本内测试。

	基线	调整后（样本内）
至少有一条预期规则触发	12/19	19/19
完全匹配（触发结果等于预期）	6/19	15/15（所有计入的模式中为 15/19）
额外触发的规则	0/19	0/19
良性发现项	尚无良性语料库	0，针对 9 个服务和 77 个工具

15/15 的结果部分是按设计得出的：有 4 个 TD004 预期结果被判定为超出该规则文档所述的范围，因此未计入分母；它们恰好就是 4 个不匹配项。

已知规避方式（调整后检测到的变异样本）。相似字符：TD002 为 1/14，TD003 为 0/5，TD004 为 0/4。用空格拆分的词：TD002 为 6/14，TD003 为 1/5，TD004 为 2/4。

拼写仿冒（注册表层级）。 标记了 51 对，经人工审查后：25 对可能是仿冒项，10 对确实不同，16 对不明确。根据不明确项的计数方式，精确率为 49% 至 80%（排除不明确项后为 71%）。未测量召回率。一位编写了这些规则的审查者仅根据名称作出判断。

限制。

• 正例测试样本是由一个已阅读规则的模型改写生成的，因此其措辞可能比真实攻击更贴近规则。
• 调整后的数据属于样本内结果。基线是样本外参考数据。
• 77 个良性工具中有 66 个来自同一发布者的参考服务，且没有电子邮件、聊天或机密信息工具。其余工具来自作者自己的两个服务，它们也作为开发阶段的负例。良性发现项为零，并不代表其他服务的误报率。
• 保留集评估尚待进行：脚本已经准备好，但语料库尚未收集。

开发

uv sync
uv run pytest -q
uv run ruff check
uv run ruff format --check

安全

如需报告此项目中的漏洞，请参阅 SECURITY.md。

许可证

MIT