owasp-scan

@guardbee/mcp-owasp-scan

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

一个命令行工具和 MCP 服务，用于执行统一的 OWASP MCP Top 10 检查。它会一次性运行七个 GuardBee 审计器，检查整个代码库；也可以对运行中的 MCP 服务的工具列表进行评级，并以 A–F 等级报告每个 OWASP ID 下的所有发现。支持输出为文本、JSON 或 SARIF，以便用于 GitHub 代码扫描。

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

快速开始

# Static scan of a repository, fail CI on high or critical findings
npx @guardbee/mcp-owasp-scan scan ./src --format=sarif --fail-on=high > owasp.sarif

# Connect to a running MCP server and grade its tools
npx @guardbee/mcp-owasp-scan live --url=https://mcp.example.com/mcp
npx @guardbee/mcp-owasp-scan live --stdio=npx --arg=-y --arg=@modelcontextprotocol/server-filesystem --arg=.

# Grade a saved tools/list response
npx @guardbee/mcp-owasp-scan catalog ./tools.json --format=json

作为 MCP 服务使用（Claude Desktop、Cursor、VS Code）：

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

模式

模式	输入	执行内容
scan <path>	文件或目录	secret-scanner、mcp-server-auditor、oauth-auditor、audit-gap-auditor、context-oversharing-auditor、toxic-flow-auditor、tool-poisoning-scanner
live	--url=<streamable HTTP URL> 或搭配 --arg=… 的 --stdio=<command>	连接服务，调用 tools/list，然后运行 toxic-flow-auditor 和 tool-poisoning-scanner
catalog <tools.json>	tools/list 转储内容（{ "tools": [...] } 或裸数组）	与 live 相同的检查，离线运行

scan 会完整读取 TypeScript/JavaScript、Python（FastMCP、官方 SDK、底层服务端）和 Go（官方 go-sdk、mark3labs/mcp-go）MCP 服务：工具定义、处理程序接收点和 OAuth 规则。其他语言（Rust、Java、Kotlin、C#、Ruby、PHP、Swift）仅应用与语言无关的规则（机密、URL、配置）。报告的 coverage 会列出每个源文件的语言、扫描深度（full 或 patterns）以及发现的工具定义数量，并提供按语言汇总的结果（文本输出中的 languages:），因此无法深入读取的文件会明确显示，而不会被静默判定为通过。

--discover-shadow 会为 scan 增加一项 MCP09 检查：通过 mcp-config-auditor 检查本机配置的 MCP 服务（Cursor、Claude Desktop、Windsurf、VS Code），而 --allowlist=<path> 会将获准的服务标记出来。

OWASP MCP Top 10 覆盖情况

ID	风险	覆盖工具
MCP01	令牌 / 凭据泄露	secret-scanner、mcp-server-auditor
MCP02	权限 / 过度代理权限	mcp-server-auditor
MCP03	工具投毒 / rug pull 攻击面	tool-poisoning-scanner（scan、live、catalog）
MCP04	供应链	不在此元扫描范围内：使用 mcp-dependency-auditor 和 mcp-slopsquat-scanner，它们需要网络
MCP05	通过工具进行命令 / 代码注入	mcp-server-auditor
MCP06	提示词 / 上下文注入	不在此元扫描范围内：使用 mcp-prompt-injection-scanner 扫描 Agent 读取的内容
MCP07	身份验证 / OAuth 配置错误	oauth-auditor
MCP08	缺少审计和遥测	audit-gap-auditor
MCP09	未知 MCP 服务	mcp-config-auditor（--discover-shadow）
MCP10	有害数据流 / 上下文过度共享	toxic-flow-auditor、context-oversharing-auditor（scan、live、catalog）

等级

等级	判定条件
F	致命三要素：一个 Agent 可以读取不可信内容、访问敏感数据并将数据发送出去
D	存在任何严重发现
C	存在任何高危发现
B	仅有中危或低危发现
A	未发现问题

CLI 选项

选项	默认值	含义
--format=text|json|sarif	text	报告格式。SARIF 可上传到 GitHub 代码扫描
--fail-on=any|critical|high|medium|none	any	存在达到或高于此严重级别的发现时，退出码为 1
--max-files=<n>	5000	路径扫描达到此文件数后停止
--discover-shadow	关闭	在 scan 中加入 MCP09 主机清单
--allowlist=<path>	–	--discover-shadow 的已批准服务列表

退出码：0 表示干净（或低于 --fail-on），1 表示存在达到或高于 --fail-on 的发现，2 表示用法错误。

MCP 工具

工具	功能
owasp_scan_path	对路径执行 scan 模式（path、maxFiles、discoverShadow、allowlistPath）
owasp_scan_live	执行 live 模式（使用 url，或使用 args 的 command）
owasp_scan_catalog	对 JSON 字符串执行 catalog 模式
list_owasp_coverage	上方的覆盖情况表

GitHub Actions

- run: npx -y @guardbee/mcp-owasp-scan scan . --format=sarif --fail-on=high > owasp.sarif
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: owasp.sarif

相关软件包

每个审计工具也都有独立的软件包，提供更多选项：mcp-secret-scanner、mcp-server-auditor、mcp-oauth-auditor、mcp-audit-gap-auditor、mcp-context-oversharing-auditor、mcp-toxic-flow-auditor、mcp-tool-poisoning-scanner、mcp-config-auditor。若要在运行时强制执行这些规则，而不是在代码中查找问题，请将 mcp-security-proxy 部署在 MCP 服务前面。

反馈

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