mcp-server-auditor

@guardbee/mcp-server-auditor

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

一个 MCP（Model Context Protocol）服务，用于扫描其他 MCP 服务的工具定义，检查其中不安全的模式。

ai-code-scanner 会检查通用的大模型/AI 集成代码，而此软件包专门检查 MCP 服务本身：通过 server.tool(...) 定义的工具权限有多大、参数约束有多宽松，以及处理程序会将工具输入直接传递给哪些危险调用点（shell/文件系统/HTTP/SQL）。MCP 生态系统发展迅速，但目前还没有通用工具来审计这些服务的安全性。

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

Claude ──► mcp-server-auditor ──► An MCP server's source code
              │
              ├─ Excessive agency    (execSync(input.command), a tool named "run_shell")
              ├─ Unsafe input        (fetch(input.url) → SSRF, SQL string interpolation)
              ├─ Loose schema        (a parameter typed z.any()/z.unknown())
              ├─ Secrets exposure    (a hardcoded API key in a schema default, the entire process.env)
              └─ Network exposure    (wildcard CORS)

---

功能

• 10 种模式，5 个类别 — 权限过大、不安全输入、宽松的架构、机密信息泄露、网络暴露
• Python 和 Go 服务：追踪工具输入从工具定义（FastMCP 参数、低级 arguments、go-sdk 类型化参数、mcp-go request.RequireString(...)）经普通赋值，到 shell、文件写入/删除、HTTP 和 SQL 调用的传递过程
• 每个发现项都包含风险原因和建议采取的措施（recommendation），而不只是“发现了问题”
• SARIF 2.1.0 输出 — CI/CD 集成（GitHub Code Scanning 等）
• 支持通过 guardbee.yml 配置文件进行配置
• 每种模式都有一个正向测试和一个负向（误报）测试，并提供存在漏洞和安全的 Python 与 Go 测试样例

---

快速开始

Claude Desktop / MCP 客户端

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

CLI（CI/CD）

npx @guardbee/mcp-server-auditor scan ./src --fail-on=high --format=sarif > results.sarif

---

MCP 工具

工具	描述
scan_text	扫描给定的文本/代码片段
scan_file	扫描单个文件
scan_directory	递归扫描目录（自动跳过 node_modules、.git、dist）
list_patterns	按类别列出所有支持的模式

---

检测到的模式

类别	模式	严重程度	OWASP	含义
excessive-agency	shell_exec_from_tool_input	严重	MCP05:2025	工具处理程序将工具输入直接传入 shell 调用，例如 execSync/spawn
excessive-agency	eval_of_tool_input	严重	MCP05:2025	工具输入通过 eval()/new Function() 作为代码执行
excessive-agency	unrestricted_shell_tool_name	高	MCP05:2025	工具名称（run_shell、execute_sql 等）直接暗示执行 shell/SQL
unsafe-input	fs_write_from_raw_tool_input	高		工具输入中的路径未经验证便传入文件写入/删除调用（路径遍历）
unsafe-input	ssrf_fetch_from_tool_input	高		工具输入中的 URL 未经允许列表检查便直接传入 fetch/axios（SSRF）
unsafe-input	sql_injection_via_tool_input	严重	MCP05:2025	工具输入通过模板字面量插入 SQL 字符串
loose-schema	overly_permissive_tool_schema	中	工具参数的类型为 z.any()/z.unknown()——接受任何内容
secrets-exposure	hardcoded_secret_in_tool_schema	严重	凭据形式的架构字段默认值是硬编码字面量
secrets-exposure	full_env_exposed_to_tool_caller	严重	整个 process.env 被展开、字符串化或返回（而非单个具名变量）
network-exposure	permissive_cors_on_server	中	通配符 CORS（Access-Control-Allow-Origin: *）或不带选项的 cors()

Python 和 Go

Python（.py）和 Go（.go）文件也会进行工具输入流检查。检查会从工具定义中获取工具的输入名称，跟踪它们在处理程序中的普通赋值（command = f"du {directory}"），并在发现输入流到达以下接收调用时报告：

模式	严重程度	接收调用
python_shell_from_tool_input	严重	subprocess.*、os.system、os.popen、asyncio.create_subprocess_*
python_eval_of_tool_input	严重	eval、exec
python_fs_write_from_tool_input	高	open(..., "w"/"a"/"x")、os.remove/rename/…、shutil.rmtree/move、Path(...).write_text/unlink
python_ssrf_from_tool_input	高	requests.*、httpx.*、client.get(...)、urlopen（URL 参数）
python_sql_injection_via_tool_input	严重	cursor.execute(f"...{x}...")、% / .format / +
go_shell_from_tool_input	严重（sh -c），高（参数列表）	exec.Command、exec.CommandContext
go_fs_write_from_tool_input	高	os.WriteFile、os.Remove、os.RemoveAll、os.Rename、os.Create、用于写入的 os.OpenFile
go_ssrf_from_tool_input	高	http.Get/Post/NewRequest…、client.Get
go_sql_injection_via_tool_input	严重	使用 fmt.Sprintf 或 + 的 db.Query…/Exec…

当处理程序会将路径与基础目录进行检查（is_relative_to、commonpath、.parents、filepath.IsLocal、filepath.Rel、strings.HasPrefix）时，会跳过文件类发现；当处理程序会检查主机允许列表时，会跳过 HTTP 类发现。对于这两种语言，名为 run_shell、execute_sql 等的工具也会被报告。Rust、Java、Kotlin、C# 和其他语言仅使用语言无关模式。

这些发现均为启发式结果——基于静态文本模式的扫描，并非完整的 AST/类型分析。此设计旨在降低误报率，但仍应手动审查每项发现。

---

配置（guardbee.yml）

mcp-server-auditor:
  fail-on: high       # any | critical | high | medium | low | none
  max-files: 5000
  exclude:
    - ".test.ts"
    - "fixtures/"

---

开发

npm run build
npm test

---

许可证

MIT — GuardBee

反馈

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