cognis-digital/ssrfmcp
GitHub: cognis-digital/ssrfmcp
一款基于授权的防御性 SSRF 探测工具，专门检测暴露 URL 获取能力的 MCP 服务器是否存在服务端请求伪造漏洞。
Stars: 0 | Forks: 0
# ssrfmcp — 针对获取 URL 的 MCP 服务器的基于授权的 SSRF 探测工具套件
[](https://pypi.org/project/cognis-ssrfmcp/)
[](https://github.com/cognis-digital/ssrfmcp/actions)
[](LICENSE)
[](https://github.com/cognis-digital)
**一个防御性的、基于授权的 SSRF 测试套件，专为获取 URL 的 MCP 工具设计。**
*AI 安全与治理 — 保护 LLM、agent 和 MCP 供应链。*
许多 MCP 服务器暴露了“获取此 URL”的工具。如果该工具没有 SSRF 防护，攻击者（或受到 prompt 注入的 agent）可以迫使服务器访问云元数据端点（`169.254.169.254`）、环回管理服务，或通过 `file://` 读取本地文件。`ssrfmcp` 会针对你控制的目标探测这些弱点，并报告哪些 payload 成功穿透及其严重性。
## 使用说明 — 分步指南
`ssrfmcp` 是一个**基于授权的防御性** SSRF 探测工具，用于获取 URL 的 MCP 服务器。除非你确认获得授权，否则它将拒绝针对 `--target` 运行。
1. **安装**（从克隆的代码库进行可编辑安装，或通过 wheel 安装）：
pip install -e .
# 提供 `ssrfmcp` 控制台脚本
2. **首先安全地尝试**针对内置的本地 mock 运行（仅限环回 — 仍需要授权标志）：
ssrfmcp demo --i-have-authorization
3. **探测你拥有 / 已获授权测试的真实目标。** 将 `--target` 指向 MCP 工具端点；`--tool`/`--arg` 用于指定获取工具及其 URL 参数：
ssrfmcp scan --target http://127.0.0.1:8080/mcp \
--tool fetch --arg url --i-have-authorization
（在另一个 shell 中运行 `ssrfmcp mock` 以提供本地易受攻击的端点服务，
或运行 `ssrfmcp mcp` 将 ssrfmcp 自身作为 MCP 服务器功能暴露出来。）
4. **读取 / 使用输出。** 默认的 `--format table` 会打印风险评分和每个 payload 的裁定结果；切换为 `json`、`sarif`、`html` 或 `badge` 以便工具集成。可选的 `--ai` 标志（环境变量 `COGNIS_AI_*`）会合并新的发现，并在后端无法访问时平滑降级：
ssrfmcp scan --target http://127.0.0.1:8080/mcp --i-have-authorization \
--format json > ssrf.json
5. **控制 CI**，使用 `--fail-on`（`critical|high|medium|low|info`）；当存在达到或超过该严重级别的易受攻击的发现时，退出码为非零：
ssrfmcp scan --target http://127.0.0.1:8080/mcp --i-have-authorization \
--format sarif --fail-on high > ssrf.sarif
## 负责任 / 授权使用
这是**双用途安全软件**。它**仅**针对你明确提供的 `--target` 运行，并且**拒绝在没有 `--i-have-authorization` 的情况下运行**。仅在你拥有或获得书面授权测试的 MCP 服务器上使用，并遵守适用的法律。
## 工作原理
1. **Canary** — 启动一个仅限环回的本地 `http.server`，带有每次运行唯一的 token。如果目标获取了 canary URL，则证明存在 *blind* SSRF 回调，并且该命中将被归因于确切的 payload。
2. **Payload** — 向目标的获取工具提交一组精心挑选的、深入的 SSRF 探测：
- **云元数据：** AWS IMDSv1（root / IAM 凭据 / user-data）、GCP（元数据 + 默认 service-account OAuth token）、Azure（IMDS + Managed Identity token）、Alibaba（`100.100.100.200`）、OpenStack、DigitalOcean。
- **内部触达：** `http://localhost`、`127.0.0.1`、IPv6 `[::1]`、常见管理端口、链路本地（IPv4 + 通过 IPv6 `fd00:ec2::254` 的 AWS IMDS）。
- **`file://`** 本地文件泄露（POSIX + Windows）。
- **替代协议：** `gopher://`（Redis 走私）、`dict://` (memcached)、`ftp://`。
- **IP 混淆 / 黑名单绕过：** 十进制、八进制、十六进制、点分十六进制、短格式 `127.1`、表意文字点号主机欺骗、`userinfo@` 混淆。
- **基于重定向**触达内部端点，以及一个 **DNS-rebinding 前体** canary，用于证明目标会重新解析攻击者的主机名。
3. **双重预言机检测** — 融合内部端点的响应体指纹（反射型 SSRF — IMDS 标记、IAM/OAuth 凭据字段、`root:x:0:0` 等）与环回 canary 回调日志（blind SSRF），然后分配严重性、**CWE**（CWE-918 SSRF / CWE-22 file / CWE-350 rebind）以及 0–100 的风险评分。
Payload 仅发送到你提供的目标，不会发送到其他任何地方。canary 仅监听环回地址。仅使用标准库 — 无需任何 pip 依赖。
## 安装
```
pip install cognis-ssrfmcp
# 或者，从此 repo：
pip install -e ".[dev]"
```
## 快速开始
```
ssrfmcp --version
ssrfmcp demo --i-have-authorization # probe the bundled mock target
ssrfmcp demo --i-have-authorization --format json # machine-readable
ssrfmcp demo --i-have-authorization --format sarif # GitHub code-scanning
ssrfmcp demo --i-have-authorization --format html > report.html # shareable report
ssrfmcp demo --i-have-authorization --format badge > badge.json # shields.io endpoint
# 针对你自己的 MCP fetch tool：
ssrfmcp scan --i-have-authorization \
--target http://127.0.0.1:8731/mcp/call \
--tool fetch --arg url --fail-on high
# 自行 Serve 这个 bundled mock vulnerable endpoint：
ssrfmcp mock --port 8731
# 将 ssrfmcp 作为 MCP server 暴露 (Cognis.Studio / Claude Desktop / Cursor)：
ssrfmcp mcp
```
### 目标契约
`ssrfmcp scan` 会向你的 `--target` POST 形如 `{"tool": "<--tool>", "arguments": {"<--arg>": ""}}` 的 JSON，并检查响应体。调整 `--tool` / `--arg` 以匹配你服务器的获取工具。（如有需要，可用一个小型 shim 包装不兼容的服务器。）
## 输出格式
- **Table**（默认）— 人类可读的终端摘要，包含每个 payload 的裁定结果、CWE 和技术手法
- **JSON** — 机器可读的发现 + 风险评分 + CWE，适用于 pipeline
- **SARIF** — 直接接入 GitHub code-scanning / IDE 问题面板（带有 CWE 标签）
- **HTML** (`--format html`) — 一份干净、自包含的报告（无外部资源、无 JS、无网络请求），你可以将其附加到工单或电子邮件中
- **Badge** (`--format badge`) — 一个 [shields.io 端点](https://shields.io/endpoint) JSON `{schemaVersion,label,message,color}`，允许你展示实时状态徽章
当存在达到或高于指定严重性（默认为 `high`）的易受攻击的发现时，`--fail-on ` 会使进程以非零状态退出，从而干净利落地控制 CI 流程。
### 状态徽章
将 `ssrfmcp --format badge` 输出发布到可访问的位置（例如 Pages URL 或 gist），然后将 shields.io 指向它：
```
```
## 可插拔 AI 模式（可选，默认关闭）
`ssrfmcp` 默认**逐字节确定性运行** — 如果不使用 `--ai`，甚至不会构建任何 AI 后端。传入 `--ai` 可在探测记录上*额外*运行可插拔的 **Cognis AI 后端**，并合并确定性规则可能遗漏的任何**新发现**（标记为 `source="ai"`，`novel=true`）（例如时序/错误泄露预言机、不寻常的可接受协议、重定向行为等）。
AI 发现会通过 `(CWE, technique)` 与规则发现进行去重。
它完全针对你的**本地** OpenAI 兼容集群运行 — 数据不会离开当前设备。通过环境变量进行配置（在设置其中一个变量之前保持关闭）：
```
export COGNIS_AI_BACKEND=uncensored-fleet # or: cognis-code
# 或者直接 point：
export COGNIS_AI_ENDPOINT=http://127.0.0.1:8774/v1
export COGNIS_AI_MODEL=Josiefied-Qwen3-8B-abliterated
ssrfmcp demo --i-have-authorization --ai --format json
```
如果指定了 `--ai` 但后端无法访问/未配置，`ssrfmcp` 会向 stderr 打印明确的提示，并**继续执行确定性规则发现**（它绝不会崩溃，且退出码仍反映规则发现的结果）。
## 在 CI 中使用 — 可重用的 GitHub Action
`ssrfmcp` 附带了一个复合 GitHub Action。将其放入工作流中，以在 CI 中扫描目标，在 PR 上评论发现，并根据严重性阈值决定是否失败：
```
jobs:
ssrf-scan:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write # to comment findings on the PR
steps:
- uses: cognis-digital/ssrfmcp@main
with:
target: http://127.0.0.1:8731/mcp/call
tool: fetch
arg: url
fail-on: high
comment-pr: "true"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
只是想试一试？设置 `demo: "true"` 来探测内置的 mock 目标，而不是 `target`。该 action 会将 `scan.json`、`scan.sarif`、`scan.html` 和 `badge.json` 作为构建产物上传。**仅供防御 / 授权使用** — 仅将 `target` 指向你拥有或已明确获得测试授权的 MCP 服务器。
## 内置演示场景
- [`demos/01-basic/`](demos/01-basic/SCENARIO.md) — 探测本仓库中内置的故意带有 SSRF 漏洞的 mock MCP 获取工具。
## 如何融入 Cognis Neural Suite
`ssrfmcp` 附带了一个 MCP 服务器，因此 [Cognis.Studio](https://cognis.studio) agent 可以将其作为受范围限制、受授权控制的功能来调用（该 MCP 工具需要 `i_have_authorization=true`，与 CLI 标志保持一致）。
**`ai-security` 中的同级工具：** [`mcpharden`](https://github.com/cognis-digital/mcpharden)、[`aegis`](https://github.com/cognis-digital/aegis)、[`promptmirror`](https://github.com/cognis-digital/promptmirror)、[`adversa`](https://github.com/cognis-digital/adversa)、[`guardpost`](https://github.com/cognis-digital/guardpost)、[`ragshield`](https://github.com/cognis-digital/ragshield)
## 互操作性
`ssrfmcp` 可与超过 300 个工具的 Cognis 套件组合使用 — JSON 输入/输出和共享的 OpenAI 兼容 `/v1` 骨干网络。有关套件图谱、组合模式和参考技术栈，请参阅 **[INTEROP.md](INTEROP.md)**。
## 集成
通过 [`cognis-connect`](https://github.com/cognis-digital/cognis-connect) 将 `ssrfmcp` 的发现转发至 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, CISA项目, LNA, MCP服务器, Python, SSRF检测, 无后门, 逆向工具