shadow-mcp

shadow-mcp

发现并评定这台机器上实际存在的 MCP 服务的风险等级。

大多数 MCP 安全工具都假设你已经有一份待审计的服务列表。 但在真实的开发者机器上并非如此：服务散落在 Claude Code、 Codex、Claude Desktop、项目本地的 .mcp.json 文件、DXT 扩展和不会绑定端口的 实时进程中。shadow-mcp 会先找到它们，再评定风险等级。

这是针对 OWASP MCP09:2025 — Shadow MCP Servers 的本地优先解决方案。

功能

discover  ->  inventory  ->  risk-grade  ->  report

1. 发现（只读）来自受支持配置和运行时来源的 MCP 服务： Claude Code（~/.claude.json，用户和项目范围）、claude mcp list （可捕获文件中不存在的远程服务和插件服务）、Codex （~/.codex/config.toml 和配置文件）、项目 .mcp.json、Claude Desktop 配置和 DXT 扩展清单，以及实时进程表。
2. 清点：将发现记录合并为每个逻辑服务一个条目，即使同一服务在不同宿主中 使用不同名称（personal-ops 与 personal_ops），并跟踪所有来源。
3. 评定风险等级：通过委托现有引擎而非重新实现来完成：
   • MCPAudit 用于提供 0-10 能力综合评分和注入问题发现
   • mcp-trust 用于提供权威的 A-F 危险等级（已知时）
   • 一个精简的本地层，用于补充引擎覆盖不足的配置相关 OWASP 维度 （密钥/MCP01、供应链来源/MCP04、传输暴露/MCP07）。
4. 报告：生成按风险排序的终端表格、机器可读的 JSON 清单或 Markdown 报告，另附 Shadow 与关注事项 部分，列出值得注意的差异 （正在运行但未配置、影响范围广、能力强但未评级）。

风险模型及其 OWASP 映射见 docs/risk-model.md。

安装

在此仓库根目录中，使用 uv：

make setup

评定引擎（mcp-audits 和 mcp-trust）是从 PyPI 解析的运行时依赖项， 而非可编辑的同级目录检出或 engines 依赖组。 已安装的 mcp-trust 包提供其种子目录；--registry-db 或 SHADOW_MCP_MCPTRUST_DB 可用于选择明确指定的本地注册表。

使用

uv run shadow-mcp scan                      # full pipeline, terminal report
uv run shadow-mcp scan --json out.json      # machine-readable inventory
uv run shadow-mcp scan --format markdown    # markdown report
uv run shadow-mcp discover                  # inventory only, no grading
uv run shadow-mcp sources                   # per-collector counts
uv run shadow-mcp grade-missing             # A-F for servers the registry hasn't scanned
uv run shadow-mcp deep-scan cost-tracker    # connect to a server, grade its real tools

实用选项：--no-processes（跳过实时进程扫描）、--no-cli（跳过 claude mcp list）、--no-mcpaudit（仅清点并使用 mcp-trust）、--home PATH （将发现范围指向一个测试树）。

静态评定与连接后评定

默认情况下，评定是静态的（仅基于配置）：不会启动任何服务，因此评级 反映的是配置中可见的内容。这种方式安全，但较为粗略——只有连接并列出工具后， 才能了解服务的实际能力。

shadow-mcp scan --connect（或 deep-scan [names...]）会启动每个 stdio 服务并枚举其实际工具，委托 MCPAudit 的连接后引擎进行能力评级，从而得到有区分度的 结果（文件系统服务的评级会从静态 A 跃升至连接后 D）。此功能需主动启用， 因为连接会执行服务；远程端点永远不会被启动（它们属于网络扫描 层级），而需要真实密钥才能启动的服务则会回退到静态评级。

开发与安全验证

已提交的 uv.lock 固定了 PyPI 运行时和开发依赖关系图。在仓库根目录运行：

make check

测试套件使用合成主目录。请保持 SHADOW_MCP_RUN_CONNECT 未设置：明确选择启用的连接测试属于单独的服务执行流程。CI 会在 Python 3.11 至 3.15 上运行相同的汇总检查；请参阅工作流。make build 会生成发布工作流使用的 wheel 和 sdist。

请勿将常规的 scan、discover、sources、grade-missing 或 MCP 工具调用用作开发冒烟测试：它们默认会盘点这台机器。CLI deep-scan 和 scan --connect 还会执行服务。对于已更改的 JSON 或 Markdown 报告，请检查相应的 fixture 测试（tests/test_report.py）并检查合成输出；此 CLI 没有浏览器界面。实际工作站或连接行为需要单独获得明确授权后进行验证。

安全

• 只读发现。 收集器会解析配置、调用 claude mcp list（除非设置了 --no-cli），并列出进程；它们发现的内容不会被修改。（--connect/deep-scan 是唯一会执行服务的路径，而且只有在你明确要求时才会执行。）
• 不保留机密。 我们会记录环境变量的名称（以便根据 MCP01 标记包含机密的服务），但绝不记录其值。存储之前，会对命令参数、URL 和进程父命令中的内嵌凭据进行脱敏。捕获的清单仍包含本地路径和主机名，因此请将 *.inventory.json 视为私有文件（默认会被 git 忽略）。

用作 MCP 服务

shadow-mcp 可以将自身的清单工具作为 MCP 服务提供，让 Agent 无需离开当前对话即可查询你的本地 MCP 环境。

工具

工具	描述
scan_local	完整流程（发现 → 清点 → 评级 → 报告）。返回 JSON。
discover_local	清点所有 MCP 服务，不进行评级。返回 JSON。
deep_scan	对指定服务进行评级；若列表为空，则对所有服务进行评级（静态操作，不会启动进程）。接受 names: list[str]。返回 JSON。
list_sources	返回一次 discover 运行中各收集器的来源计数。返回 JSON。

运行服务

# directly from a local checkout
uv run shadow-mcp mcp-serve

# via uvx (once published to PyPI)
uvx shadow-mcp mcp-serve

仅限本地。 MCP 工具会读取本地配置和进程表，跳过 claude mcp list，并且绝不会连接托管的 MCP 端点或启动服务。评级是静态的（基于配置）；connect=False 始终会被强制执行。

范围

这是一个本地优先的工具：它根据一台机器的配置和进程清点该机器。后续扩展网络扫描（探测主机/端口以查找远程 MCP 端点、清点整个组织的设备群、检查仿冒名称的距离来源）明确不在此范围内——相关扩展内容请参阅 docs/risk-model.md 的末尾和项目说明。

状态

技术栈

Python 3.11+；由 uv 管理并锁定的依赖项；Ruff、mypy 和 pytest 检查；Hatchling wheel 和 sdist 构建。

已知风险

• 最低 Python 版本仍为 3.11，待所有者决定是否提升到 3.12。
• MCP 工具名称 deep_scan 暂不更改，待所有者决定；名称相似的 CLI 命令可以连接服务。
• 身份与清单匹配中的身份冲突。
• 对进程的发现结果会在所有者分类前按名称去重。
• 评级证据最多包含 8 条发现结果，且 critical 的优先级低于 low。
• 收集器故障可能不会显示出来。
• sources 和 grade-missing 会忽略 --json。
• 报告写入不是原子操作。
• Markdown 和 Rich 输出的转义方式不同。
• 依赖项主版本升级、迁离 Hatchling、覆盖率阈值、软件包发布、标签和版本发布均不在范围内。

后续步骤

解决 Python 最低版本和 MCP 工具命名的决策，然后在后续阶段处理已列出的行为风险。