cognis-digital/mcpscan

# mcpscan — 扫描 MCP 服务器的 RCE/SSRF/无身份验证/工具投毒漏洞 [](https://pypi.org/project/cognis-mcpscan/) [](https://github.com/cognis-digital/mcpscan/actions) [](LICENSE) [](https://github.com/cognis-digital) **一款用于 Model Context Protocol (MCP) 服务器及其驱动 agent 的漏洞扫描器。** 它将扫描结果映射到 **OWASP LLM Top-10**、**CWE** 编号以及 **Microsoft agent 威胁分类法** —— 支持从源码静态分析（基于真实的 AST 污染数据流）、探测线上 endpoint、获取 GitHub 远程 URL，以及通过 **可选的 AI 审查层** 进行检测。 *AI 安全与治理 — 保护 LLM、agent 及 MCP 供应链。* ## 使用说明 — 分步指南 `mcpscan` 用于发现 MCP 服务器中的 RCE/SSRF/无身份验证/工具投毒及其他漏洞，并将每个发现映射到 OWASP LLM Top-10、CWE 以及 Microsoft agent 威胁分类法。它支持扫描源码、远程 URL 或线上 endpoint。 1. **安装：** pip install cognis-mcpscan # 或者：pip install -e . mcpscan --version 2. **静态扫描源码**（MCP 服务器代码的文件或目录）。输出格式：`table`、`json`、`sarif`、`html`、`badge`： mcpscan scan ./my-mcp-server --format table 3. **生成报告**供工具使用并保存： mcpscan scan ./my-mcp-server --format sarif --out mcpscan.sarif 4. **扫描远程/运行中的目标** — 拉取 GitHub URL，或探测运行中的 endpoint（可选择使用 bearer token）： mcpscan url https://github.com/org/repo/blob/main/server.py --format json mcpscan probe https://mcp.example.com --token "$TOKEN" 5. **在 CI 中设置门禁** — 当发现结果的严重程度达到或超过指定级别时中断构建；当你需要进行 LLM 分诊时，可添加默认确定性的可选 `--ai` 审查层： mcpscan scan ./my-mcp-server --format sarif --out mcpscan.sarif --fail-on high mcpscan scan ./my-mcp-server --ai --ai-focus "tool poisoning" # 可选，非确定性 ## 检测内容 **静态扫描**（指向 MCP 服务器源码的目录或文件）： - **RCE / 命令执行** — `eval`、`exec`、`os.system`、`os.popen`、 `subprocess(..., shell=True)`，以及 JS 的 `child_process.exec`、`eval`、 `new Function`、`spawn({shell:true})`。Python 代码会使用 `ast` 模块进行解析。 - **AST 污染数据流** — 针对真正的 Python **源 -> 汇** 追踪：如果工具参数或 `request.*` 源（通过变量、f-string、拼接、`.format()`）流入命令/eval/SSRF/路径/反序列化汇，即使源和汇位于*不同的行*，也会被标记为 `taint.*` — 而不仅仅是单行特征匹配。 - **SSRF** — 使用非字面量 URL（`CWE-918`）的出站 HTTP 请求（`requests`、`urllib`、`httpx`、`fetch`、`axios` 等）。 - **路径穿越** — 对动态路径（`CWE-22`）执行文件操作（`open`、`os.remove`、`fs.*`、`send_file`）。 - **不安全的反序列化** — 对不受信任的数据（`CWE-502`）使用 `pickle`/`yaml.load`/`marshal`/`dill`；系统会识别出 `yaml.safe_load` 是安全的。 - **SSTI** — 从用户输入（`jinja2.Template`、 `render_template_string`，handlebars/ejs/pug）编译的模板（`CWE-1336`）。 - **机密信息暴露** — 硬编码的 AWS / GitHub / Slack / OpenAI / Google 密钥和私钥块（`CWE-798`）。 - **MCP / agent 类问题** — **工具投毒**（工具描述/文档字符串中的提示词注入）、**混淆代理人 / token 透传**（将入站 `Authorization` 头或 token 转发到下游调用）、**过度授权**（未经确认的破坏性工具），以及**地毯式抽薪 / 版本漂移**（未锁定的 `requirements.txt` / 浮动的 `package.json` 依赖）。 - **Shell 工具运行用户输入** — 如果工具/函数将其自身的参数传递给 shell 子进程（`subprocess(..., shell=True)`、 `os.system`/`os.popen`），将通过受限的按函数 AST 遍历被标记为 `static.shell_tool_input`（`CWE-78`， OWASP-LLM `LLM06`）。 **MCP 配置规范**（JSON 客户端/服务器配置 — `.mcp.json`、`mcp.json`、 `claude_desktop_config.json` 等，可由 `scan` 自动发现）： - **配置中硬编码的 bearer / 密钥** — 服务器 `env`、`headers` 或 `args` 中内置的凭证（`config.hardcoded_secret`、`CWE-798`、 `LLM02`）。环境变量占位符（`${VAR}`）会被识别为安全。 - **服务器绑定 `0.0.0.0` 且无身份验证** — 在同一文件中没有任何身份验证的、监听所有接口的监听器（`config.open_bind_no_auth`， `CWE-306`、`LLM06`）。 - **无 TLS 的远程传输** — 通过明文 `http://` 传输的非环回 MCP 传输 URL（`config.no_tls_remote`、`CWE-319`、`LLM02`）；环回地址和 `https://` 被视为安全。 **动态扫描**（通过 `urllib` 探测运行中的 HTTP MCP endpoint）： - **缺少身份验证**（`live.no_auth`）、**明文传输** （`live.no_tls`），以及**过于宽泛的能力** — 无需身份验证即可访问的破坏性工具、没有输入 schema 的工具，以及 `additionalProperties: true` schema。 **远程扫描** — `mcpscan scan-url ` 通过 `urllib` 获取公共 MCP 服务器文件（自动将 `github.com/.../blob/...` 规范化为 raw 链接）并进行扫描，无需克隆。 ## 安装 ``` pip install cognis-mcpscan # 或，来自此 repo： pip install -e ".[dev]" ``` 仅使用标准库 — 没有运行时依赖。 ## 快速开始 ``` mcpscan --version mcpscan scan demos/01-basic/ # static scan a dir mcpscan scan demos/02-deep/ # deep rule pack + taint mcpscan scan demos/03-config/ # MCP config hygiene + shell-tool input mcpscan scan path/to/server.py --format sarif --out r.sarif # SARIF for code-scanning mcpscan scan path/to/server.py --format html --out r.html # self-contained HTML report mcpscan scan path/to/server.py --format badge # shields.io endpoint JSON mcpscan scan path/to/server/ --fail-on high # CI gate (exits 1) mcpscan scan-url https://github.com/owner/repo/blob/main/server.py # scan a remote file mcpscan scan path/to/server/ --ai # opt-in AI review layer mcpscan probe http://127.0.0.1:8080/mcp --fail-on high # live no-auth probe mcpscan probe https://mcp.example.com/mcp --token "$TOKEN" # authenticated probe ``` ## 输出格式 - **表格**（默认） — 人类可读的终端摘要，包含 0-100 的评分以及每个发现的 CWE / OWASP / MS 分类标签。 - **JSON** — 适用于流水线的机器可读发现结果（`--format json`）。 - **SARIF 2.1.0** — 可直接导入 GitHub 代码扫描 / IDE 问题面板；规则元数据携带 `cwe`、`owasp-llm` 和 `ms-agent-taxonomy`（`--format sarif`）。 - **HTML** — 一份简洁、独立（无外部资源）的报告，可附加到 PR 或电子邮件中（`--format html`）。 - **徽章** — 一个 [shields.io endpoint](https://shields.io/badges/endpoint-badge) JSON 对象 `{schemaVersion,label,message,color}`，以便展示实时状态徽章（`--format badge`）。 `--fail-on {critical,high,medium,low,info}` 会在任何发现结果的严重程度达到或超过指定级别时，使进程以退出码 `1` 退出 — 可将其直接集成到 CI 中。 ### 状态徽章 将徽章 JSON 发布到可访问的地方（例如提交它，或推送到 gist），并将 shields.io endpoint 徽章指向它： ``` mcpscan scan . --format badge --out mcpscan-badge.json ``` ```  ``` ## 可选的 AI 审查 (`--ai`) `--ai` **默认关闭** — 如果没有该选项，mcpscan 是**逐字节确定性**的。启用后，mcpscan 会通过本地的 **Cognis fleet** LLM 后端（OpenAI 兼容的 llama.cpp / Ollama — 数据不离开本地机器）运行相同的源码，以发现特征规则之外的*新*逻辑缺陷。AI 的发现结果会被合并并标记为 `source="ai"`（在适用时标记为 `novel`），并根据 CWE + 行号与规则发现结果进行去重。 ``` export COGNIS_AI_BACKEND=uncensored-fleet # or COGNIS_AI_ENDPOINT=http://127.0.0.1:8774/v1 mcpscan scan path/to/server/ --ai ``` 如果提供了 `--ai` 但后端未配置或无法访问，mcpscan 将打印明确的提示，并继续输出确定性的规则发现结果 — 它**绝不会崩溃**。 ## CI / GitHub Action mcpscan 提供了一个可复用的 Action。将其添加到任何 MCP 服务器仓库中，每个 PR 都会被扫描，发现结果表格将作为 PR 评论发布，并且构建会根据你选择的严重程度而失败： ``` # .github/workflows/mcpscan-action.yml name: mcpscan on: [push, pull_request] permissions: contents: read pull-requests: write jobs: mcpscan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: cognis-digital/mcpscan@main with: path: . fail-on: high comment-pr: "true" # comments findings on the PR via gh api # ai: "false" # opt-in; set COGNIS_AI_* env to enable ``` 消费者只需这一行 `uses: cognis-digital/mcpscan@main` 步骤即可。 ## 演示 请参阅 [`demos/01-basic/SCENARIO.md`](demos/01-basic/SCENARIO.md)。它包含一个故意设置了漏洞的 FastMCP 服务器，并展示了 mcpscan 会标记的五种漏洞类别（以及一个它正确识别为安全的工具）。 ## 作为 MCP 服务器使用 每个 Cognis Neural Suite 工具都会附带一个 MCP 服务器，以便 agent 可以将其作为一种限定范围的能力进行调用： ``` python -m mcpscan.mcp_server # requires the `mcp` extra + cognis_core ``` ## 它如何融入 Cognis Neural Suite ## 互操作性 `mcpscan` 可与包含 300 多个工具的 Cognis 套件组合 — JSON 输入/输出以及共享的 OpenAI 兼容 `/v1` 主干网络。请参阅 **[INTEROP.md](INTEROP.md)** 了解套件映射、组合模式和参考技术栈。 ## 集成 通过 [`cognis-connect`](https://github.com/cognis-digital/cognis-connect) 将 `mcpscan` 的发现结果转发到 STIX/MISP/Sigma/Splunk/Elastic/Slack/webhooks。请参阅 **[INTEGRATIONS.md](INTEGRATIONS.md)**。 ## 许可证 在 **Cognis Open Collaboration License (COCL) v1.0** 下源码可见 — 个人、内部评估、研究和教育用途免费；**商业/生产用途需要许可证** (licensing@cognis.digital)。 请参阅 [LICENSE](LICENSE)。 ## 负责任地使用 这是双重用途的安全软件。请仅对你拥有或获得书面明确授权测试的系统、数据和身份使用它，并遵守适用的法律。 ## 关于 **[Cognis Digital](https://cognis.digital)** — 美国怀俄明州 · *让明天更美好：高级网络安全、AI 创新和区块链专业知识。*

标签：AI安全, AI风险缓解, Chat Copilot, OWASP Top 10, Python, 无后门, 模型上下文协议, 自动化payload嵌入, 逆向工具, 错误基检测, 静态代码分析