mcp-config-auditor

@guardbee/mcp-config-auditor

🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇩🇪 Deutsch

一个 MCP 服务，用于审计设备上的 MCP 客户端配置：Cursor mcp.json、Claude Desktop claude_desktop_config.json、Windsurf mcp_config.json 和 VS Code mcp.json。

mcp-server-auditor 会读取 MCP 服务的源代码。此软件包会读取决定 Agent 将运行哪些服务的配置。它不会启动这些服务，也不会将配置发送到任何地方。

默认关闭遥测。设置 GUARDBEE_TELEMETRY=1 后，它会发送服务、工具、成功状态、耗时以及文件路径等简短参数值；较长的字符串以及 content、token 或 password 等字段会被替换为占位符。请参阅 @guardbee/mcp-telemetry。

Claude ──► mcp-config-auditor ──► mcp.json  (or host-wide discover)
              │
              ├─ Unpinned package     (npx -y pkg, @latest)
              ├─ Typosquat            (one edit from a known server package)
              ├─ Secret in env/args
              ├─ autoApprove "*"
              ├─ Remote HTTP without auth
              ├─ Cross-server shadowing (when you pass a tool inventory)
              ├─ Agent SKILL.md (allowed-tools, body, lookalike names)
              └─ Shadow MCP discover  (OWASP MCP09 — host paths + org allowlist)

检查项

模式	严重程度	OWASP	含义
unpinned_package	high	MCP04:2025	启动器（npx、uvx、pnpm、yarn、bunx、pipx）运行的包未指定 major.minor.patch 版本
unpinned_container_image	high	MCP04:2025	docker run / podman run 按标签而非 @sha256: 摘要启动镜像
typosquat_package	critical	MCP04:2025	包名称与已知 MCP 服务包仅相差一个字符
secret_in_env	critical	MCP01:2025	值的格式像凭据，或敏感键包含较长的字面值
secret_in_args	critical	MCP01:2025	命令行中包含令牌
auto_approve_wildcard	critical	MCP02:2025	autoApprove / alwaysAllow 为 * 或 true
cleartext_remote	high	MCP07:2025	非回环 http:// URL
unauthenticated_remote	high/medium	MCP07:2025	非回环 URL 未提供 Authorization / API 密钥标头，且没有令牌环境变量
cross_server_tool_shadow	high	MCP03:2025	两个服务上存在同名工具
confusable_tool_name	critical	MCP03:2025	不同服务上的工具名称包含同形异义字符或仅相差一个字符
cross_server_tool_redirect	high	MCP03:2025	描述指示模型调用其他服务的工具
skill_unrestricted_shell	critical	MCP02:2025	allowed-tools 包含未限定的 Bash、shell 或 *
skill_unrestricted_write	high	MCP02:2025	allowed-tools 包含未限制路径的 Write 或 Edit
skill_instruction_override	critical	MCP06:2025	技能指示模型忽略之前的指令
skill_covert_instruction	critical	MCP06:2025	技能指示模型向用户隐瞒其行为
skill_secret_file_read	critical	MCP01:2025	技能指示模型读取 .ssh、.env 或类似文件
skill_at_secret_ref	critical	MCP01:2025	@ 引用内嵌了凭据路径
secret_in_skill	critical	MCP01:2025	技能文件中写有字面令牌
skill_name_shadow	high	MCP03:2025	两个 SKILL.md 文件使用了相同名称
skill_confusable_name	critical	MCP03:2025	两个技能名称仅在易混淆字符上不同
shadow_mcp_server	high	MCP09:2025	discover — 服务已安装在主机上，但不在组织允许列表中
allowlist_not_configured	medium	MCP09:2025	运行 discover 时未配置允许列表
unreviewed_mcp_server	low	MCP09:2025	在 discover 期间发现的服务尚无允许列表
mcp_server_drift_across_clients	medium	MCP09:2025	两个客户端中的同一服务键映射到不同的包 / URL

回环 URL（localhost、127.0.0.1、::1）不属于远程问题。占位值（${API_KEY}、changeme）不属于机密信息。报告的机密信息匹配项会经过脱敏。Bash(git diff:*) 是命令允许列表，不属于不受限的 shell。单独使用 Read 不会触发标记。

快速开始

{
  "mcpServers": {
    "guardbee-mcp-config-auditor": {
      "command": "npx",
      "args": ["-y", "@guardbee/mcp-config-auditor"]
    }
  }
}

npx @guardbee/mcp-config-auditor scan .cursor/mcp.json --fail-on=high --format=sarif > results.sarif
npx @guardbee/mcp-config-auditor inventory ./tool-inventory.json
npx @guardbee/mcp-config-auditor discover --allowlist=./mcp-allowlist.json --fail-on=high

Shadow MCP discover (MCP09)

遍历本机上常见的 Cursor / Claude Desktop / Claude Code / Windsurf / VS Code / Gemini CLI / Cline / Zed 路径，并将每个已安装的服务与组织允许列表进行比对。不会启动服务。Claude Code 的项目级服务（~/.claude.json 中的 projects["<path>"].mcpServers）会列在 claude-code:<path> 下；支持 Zed 的 context_servers 和带注释的 JSON。

清单。 --format=json 会添加 inventory：针对每个服务，列出其客户端、配置路径、名称、传输方式、命令和参数、npm/PyPI 软件包及版本和是否已固定、URL、环境变量和标头的名称、自动批准设置，以及该服务的检测结果。清单不会包含任何密钥：环境变量和标头的值会省略，--token/--api-key 类标志后面的参数值、KEY=value 键值对、提供商令牌和连接字符串中的密码都会替换为 [redacted]，URL 中的凭据和查询参数值也会移除。--format=text 会打印相同的列表；--format=sarif 会打印检测结果。

全组织范围。 --upload 会将清单发送到 GuardBee 仪表板（使用 GUARDBEE_API_KEY，即具有 gateway.write 范围的工作区密钥），仪表板会保留每台机器的最新清单；可通过设备管理工具或登录脚本运行此命令。清单会包含机器的主机名、操作系统和操作系统用户名；--no-user 会省略用户名。

GUARDBEE_API_KEY=gb_… npx @guardbee/mcp-config-auditor discover --allowlist=./mcp-allowlist.json --upload --fail-on=none

允许列表 JSON：

{
  "names": ["filesystem", "github"],
  "packages": ["@modelcontextprotocol/server-filesystem", "@guardbee/mcp-secret-scanner"],
  "hosts": ["mcp.example.com"]
}

也可以按行填写：name:filesystem、package:@scope/pkg、host:mcp.example.com，或直接填写服务名称。

目录扫描会打开 mcp.json、mcp_config.json、claude_desktop_config.json 和 SKILL.md。传入文件路径即可扫描其他名称的文件。名为 SKILL.md 的文件会作为 Agent 技能进行审计。目录扫描会显示同名和相似技能的检测结果，因为单个文件无法查看其他文件。

guardbee.yml：

mcp-config-auditor:
  fail-on: high
  max-files: 5000
  exclude:
    - "fixtures/"

工具清单结构：

{
  "servers": [
    { "name": "github", "tools": [{ "name": "create_issue", "description": "Open an issue" }] }
  ]
}

由于客户端配置不会列出工具，检测影子工具需要该清单。rug-pull-detector 可以收集实时的 tools/list；此软件包会比对其中的多个列表。

反馈

有问题、想法或误报？欢迎在 GitHub Discussions 中发起讨论，或提交问题。如果 GuardBee 对你有帮助，请在代码库点一个 ⭐，帮助其他人发现它。