DaoyuanLi2816/mcp-fence

# mcp-fence 工具 [](https://github.com/DaoyuanLi2816/mcp-fence/actions/workflows/ci.yml) [](https://pypi.org/project/mcp-fence/) [](https://www.python.org) [](LICENSE)  `mcp-fence` 是一个开发者工具。将其指向您的 `mcp.json`（或您编写的任何正在运行的 MCP 服务器），它将会： 1. **静态扫描**配置和源代码，检查工具投毒、危险的启动命令、明文密钥、模式漏洞以及未经身份验证的 HTTP 传输。 2. **通过 stdio 实时检查**服务器——运行 `initialize`、`tools/list`，收集模式/注解。 3. 使用模式感知的负载（路径遍历、命令注入、SSRF、提示注入、过大输入、类型混淆）对每个工具进行**模糊测试**。默认安全；可通过 `--toy-mode` 或 `--allow-unsafe` 选择运行时负载。 4. 使用合理的配置文件（`strict`、`filesystem-readonly`、`network-deny`、`dev`）在 Docker 中对任何 stdio 服务器进行**沙箱化**。 5. 以纯文本表格、JSON、SARIF 2.1.0（用于 GitHub 代码扫描）或完全离线的 HTML 页面**报告**发现结果。 它**是非破坏性的**、**本地优先**，并且**默认不使用任何云 LLM**。可选的本地 LLM 判断器可以与本地 Ollama 或兼容 OpenAI 的端点通信。 ## 安装 从 PyPI 安装： ``` pip install mcp-fence ``` 从源代码安装（供贡献者使用）： ``` git clone https://github.com/DaoyuanLi2816/mcp-fence cd mcp-fence python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate python -m pip install -e ".[dev]" ``` 需要 Python 3.11+。 ## 30 秒快速入门 ``` # 在工作目录中启动捆绑示例。 mcp-fence init-example ./mcp-fence-examples # 静态扫描故意投毒的元数据服务器。 mcp-fence scan examples/vulnerable_metadata_server/mcp.json # 实时检查安全基线。 mcp-fence inspect examples/safe_server/mcp.json # 模糊测试任意文件读取服务器。 mcp-fence fuzz examples/vulnerable_filesystem_server/mcp.json # 生成一个 `docker run` 命令来沙盒化以上任何一项。 mcp-fence sandbox examples/vulnerable_filesystem_server/mcp.json \ --profile strict --dry-run # 将保存的 JSON 结果转换为离线 HTML 报告。 mcp-fence scan examples/vulnerable_metadata_server/mcp.json \ --format json --output /tmp/scan.json mcp-fence report /tmp/scan.json --format html --output /tmp/scan.html ``` ## 输出示例 ``` mcp-fence 0.1.0 :: scan :: target=examples/vulnerable_metadata_server/mcp.json summary: total=1 score=7/100 verdict=FAIL by_severity: high=1 by_category: secrets=1 # 结果 SEV RULE TITLE CATEGORY WHERE DETAIL HIGH MCPG006 Plaintext secret in env secrets param=OPENAI_API_KEY Environment variable OPENAI_API_KEY appears to be a plaintext secret. ``` ## 支持的传输方式 | 传输方式 | 扫描 | 检查 | 模糊测试 | 沙箱 | 备注 | | ----------------- | ---- | ---- | -------- | ---- | ------------------------------------------------ | | stdio | ✓ | ✓ | ✓ | ✓ | 一等支持。 | | streamable-http | ✓ | — | — | — | 仅静态（配置）；v0.2 版本将支持实时 HTTP 检查器。 | | sse / websocket | ✓ | — | — | — | 同上。 | ## 支持的风险类别 完整目录在 [`docs/risk_catalog.md`](docs/rule_catalog.md)。重点包括： - **工具投毒** — 工具描述中的提示注入短语、隐藏的 HTML 注释、零宽字符、易混淆的工具名称（Unicode + ASCII 视觉混淆，如 `Iist_files` 与 `list_files`）。 - **危险的启动命令** — `shell=True`、`curl | sh`、`sudo`、`/var/run/docker.sock`、`--privileged`、引用 `~/.ssh` 或 `~/.aws`。 - **传输绑定** — `0.0.0.0` 且无认证，无 Bearer Token 的 HTTP。 - **模式风险** — 无界字符串、缺少 `additionalProperties`、高风险参数名（`command`、`path`、`url`、`webhook` 等）未设置 pattern/enum/maxLength。 - **动态** — 路径遍历命中预设的假密钥、命令注入标记被回显、SSRF 接受元数据 IP、畸形输入通过模式验证、工具输出中的敏感模式。 - **协议** — 服务器挂起、模式不匹配、stdio 上的非 JSON 输出。 ## 为什么 MCP 服务器需要自己的扫描器 MCP 服务器的输出会直接流入 LLM 的上下文。工具描述、名称或响应中的任何内容都可能被助手解释为指令： - 一旦您安装了他人的服务器，工具的*元数据*就变成了攻击者可控的。 - 工具的*输入*是 LLM 可控的，默认是不可信的。 - 工具的*输出*最终会出现在 LLM 的提示中，并可能携带来自外部内容的注入负载。 通用的 SAST / npm-audit / pip-audit 没有为此建模。mcp-fence 具有专门为其构建的规则和模糊测试器。 ## 安全边界 - **非破坏性负载。** 命令注入标记是 `echo MCPG_FUZZ_MARKER_8f2a`。永远不会发出 `rm`、`mv`、`chmod` 或破坏性原语。 - **本地优先。** 任何代码、配置或扫描结果都不会上传到任何地方。 - **默认不使用云 LLM。** 可选的 `--llm-judge` 仅与本地端点通信。 - **无公网扫描。** SSRF 负载测试工具的验证行为；我们不会为您发起出站请求。 - **安全的路径探测。** 路径遍历负载针对捆绑示例中预设的 `fake_secret.txt` 或任何明确指定的 `--traversal-target`。它们从不针对 `/etc/shadow` 或 `~/.ssh/`。 `--allow-unsafe` 是一个显式的安全出口，用于在 `mcp-fence sandbox` Docker 配置文件中使用。请参阅 [`SECURITY.md`](SECURITY.md) 和 [`docs/sandboxing.md`](docs/sandboxing.md)。 ## 可选的本地 LLM 判断器 (Ollama / vLLM) 要对工具描述进行语义可疑性评分，请启用可选的判断器： ``` ollama pull qwen3:8b mcp-fence scan examples/vulnerable_metadata_server/mcp.json \ --inspect --llm-judge ollama --llm-model qwen3:8b ``` 适用于 16 GB 显存的 GPU（例如 RTX 4080）。失败时会静默处理：无论如何，核心扫描都会完成。详见 [`docs/local_llm.md`](docs/local_llm.md)。 ## GitHub Action 将 [`.github/workflows/mcp-fence.yml`](.github/workflows/mcp-fence.yml) 添加到任何包含 `mcp.json` 的仓库中。它会扫描每个配置并将 SARIF 上传到 GitHub 的代码扫描仪表板。 ``` - name: install mcp-fence run: pip install mcp-fence - name: scan run: mcp-fence scan path/to/mcp.json --format sarif --output mcp-fence.sarif - uses: github/codeql-action/upload-sarif@v3 with: sarif_file: mcp-fence.sarif category: mcp-fence ``` ## 最有用的五个命令 ``` mcp-fence scan examples/vulnerable_metadata_server/mcp.json mcp-fence inspect examples/safe_server/mcp.json mcp-fence fuzz examples/vulnerable_filesystem_server/mcp.json mcp-fence sandbox examples/vulnerable_shell_server/mcp.json --profile strict --dry-run mcp-fence report /tmp/scan.json --format html --output /tmp/scan.html ``` ## 路线图 请参阅 [`docs/roadmap.md`](docs/roadmap.md)。v0.2 版本将添加基于 AST 的源代码扫描、HTTP/SSE 实时检查器、本地 SSRF 捕获服务器以及预训练的工具投毒分类器。 ## 许可证 Apache-2.0。详见 [`LICENSE`](LICENSE)。

标签：AI风险缓解, Docker沙盒, MCP协议, MCP安全, SARIF报告, SSRF检测, 二进制发布, 云安全监控, 代码安全, 协议检查, 命令注入检测, 威胁情报, 安全扫描, 安全测试, 开发者工具, 开源工具, 攻击性安全, 时序注入, 本地优先, 模式验证, 漏洞枚举, 请求拦截, 路径遍历检测, 逆向工具, 静态分析, 非破坏性