m0rvayne/mcp-redteam

我为企业构建 MCP 连接器和 AI 自动化。在客户项目中部署了 70 多个连接器。其中一些开始出问题——连接中断、配置冲突、我忘记删除的服务器仍然留在配置文件中消耗资源。 我试图寻找一些工具来审计这些问题。我发现了 mcp-scan——它只读取工具描述，不接触源代码。Cisco 的扫描器——78% 的误报率。没有任何工具真正去读取服务器代码并告诉你“第 42 行，你对未经处理的输入使用了 exec()”。 我构建了自己的工具。我在 106 个公开的 MCP 服务器上运行了它。其中 7 个存在远程代码执行漏洞。其中一个甚至在 GitHub 上有 2.5 万颗星。 将其开源是因为，如果我的连接器有这些问题，你的也会有问题。 两种操作模式： - **Claude Code plugin** — 读取源代码，探测工具，检测行为不匹配，映射跨服务器攻击链。生成交互式 HTML 报告。 - **独立 CLI** — 确定性扫描。25 条 Semgrep 规则 + 6 项配置健康检查，输出 SARIF。无需 Claude 即可在 CI/CD 中运行。 ## 目前可用的功能 | 功能 | 状态 | 方式 | |---------|--------|-----| | 配置健康扫描器 | 可用 | 死服务器、范围冲突、凭据暴露、供应链、CVE 检查 | | Semgrep 代码分析 | 可用 | 25 条规则（Python + JS/TS）：注入、遍历、SSRF、eval、密钥、stdout | | SARIF 输出 | 可用 | GitHub Security 标签页集成 | | JSON 输出 | 可用 | 适用于 CI/CD 的机器可读格式 | | 终端输出 | 可用 | 带有风险评分的 Rich 彩色表格 | | CI 退出代码 | 可用 | `--fail-on critical` 返回退出代码 1 | | LLM 行为分析 | 可用 | Anthropic SDK，行为不匹配检测（可选） | | 自身安全审计 | 可用 | 审计了 10 个漏洞 — 5 个已修复，5 个已记录缓解措施 | | Claude Code plugin | 可用 | AI 驱动的深度审计并生成 HTML 报告 | | HTML 报告输出 | 可用 | `--format html` 生成自带终端样式的报告 | | 95+ 测试 | 通过 | 单元测试、安全测试、压力测试、边缘情况、Hypothesis 模糊测试 | ## 尚不可用的功能 - 审计历史（JSONL 日志，对新发现/已确认/已修复的发现进行跨运行比较） - CLI 中的跨服务器攻击链检测（仅存在于 Claude Code plugin 中） - CLI 中的自动修复（仅存在于 Claude Code plugin 中） - MCPTox 基准验证 - 社区规则贡献 ## 安装 **Claude Code plugin**（深度 AI 原生审计）： ``` # 克隆到你的项目目录 git clone https://github.com/m0rvayne/mcp-redteam.git cd mcp-redteam # CLAUDE.md 文件自动作为一个 skill 激活 # 从任何连接了 MCP 服务器的项目： /mcp-redteam ``` **独立 CLI**（确定性，适配 CI/CD）： ``` pip install redteam-mcp mcp-redteam scan ./your-mcp-server --no-llm ``` **远程 MCP 服务器**（通过 URL、OAuth 或 token）： ``` pip install 'redteam-mcp[remote]' mcp-redteam scan-remote https://your-server.com/mcp --token ``` 要求 Python 3.10+。代码分析需单独安装 Semgrep：`pip install semgrep`。 **更多示例：** ``` # HTML 报告 mcp-redteam scan ./server --format html -o report.html # 在发现 critical 问题时使 CI 失败 mcp-redteam scan ./server --fail-on critical --format sarif -o results.sarif # 使用不同的 LLM 模型进行行为分析 MCP_REDTEAM_MODEL=claude-haiku-4-5 mcp-redteam scan ./server ``` ## 检查内容 ### 配置健康（确定性） 死机/断开连接的服务器，范围冲突（同一服务器处于多个范围中），git 追踪的配置文件中的凭据（CVE-2025-59536），未固定的 npx/uvx 包（供应链），enableAllProjectMcpServers 绕过（CVE-2026-21852），孤立的 MCP 进程。 ### 代码安全（Semgrep，25 条规则） | 规则 | 检测内容 | 语言 | |------|----------------|-----------| | Shell 注入 | subprocess + shell=True 带有用户输入 | Python | | 路径遍历 | open()/Path() 没有进行 realpath 检查 | Python, JS/TS | | SSRF | 带有用户可控 URL 的 HTTP 请求 | Python, JS/TS | | Eval 注入 | 带有用户输入的 eval()/exec()/new Function() | Python, JS/TS | | 硬编码密钥 | 源代码中的 API 密钥、token、密码 | Python, JS/TS | | Stdout 污染 | stdio 处理程序中的 print()/console.log() | Python, JS/TS | | 缺失错误处理 | 没有 try/catch 的工具函数 | Python, JS/TS | | 响应中的凭据 | 工具返回值中的 API 密钥/token | Python, JS/TS | | 缺失信号处理程序 | 没有 SIGTERM/SIGINT 的服务器 | Python | | 阻塞式同步调用 | async 函数内部的 requests.get() | Python | | OAuth 过度授权 | 过度的 OAuth 权限范围（gmail.modify, admin） | Python | | HTTP 无超时 | 没有超时的 httpx/requests/fetch | Python, JS/TS | | subprocess 无超时 | 没有超时的 subprocess/spawn | Python, JS/TS | | 危险参数名 | 名为 cmd, exec, eval, code 的工具参数 | JS/TS | | 环境密钥无轮换 | 直接使用从 os.getenv 获取的 API 密钥 | Python | 基于 48+ 个 CVE、OWASP MCP Top 10，以及来自 Invariant Labs、Trail of Bits、Palo Alto Unit 42、OX Security 和 Snyk 的研究。 ### LLM 行为分析（可选，需要 API 密钥） - **行为不匹配**：工具描述声称做 X，代码却做了 Y - **隐藏操作**：未声明的网络请求、文件写入、子进程调用 - **凭据处理不当**：密钥被记录、在错误中泄露、不安全地存储 ## 横向对比 | | mcp-scan (Snyk) | Cisco MCP Scanner | **mcp-redteam** | |---|---|---|---| | 方法 | 静态描述扫描 | YARA + LLM-as-judge | **Semgrep 污点分析 + LLM 行为分析** | | 读取源代码 | 否 | 仅限 Python | **是 — Python + JS/TS** | | 配置验证 | 否 | 配置发现 | **是 — 6 项检查，CVE 检测** | | 行为不匹配 | 否 | 否 | **是（LLM 层）** | | SARIF 输出 | 否 | 否 | **是** | | CI 退出代码 | 是 | 否 | **是** | | 自我测试 | 未知 | 未知 | **95+ 测试，自身安全审计** | | 云依赖 | 需要 Snyk API | Cisco API（可选） | **无 — 确定性模式下完全本地化。LLM 模式使用 Anthropic API** | ### 为什么不直接使用 mcp-scan？ mcp-scan 读取的是服务器**对自己的描述**——即工具描述。而 mcp-redteam 检查的是服务器**实际做了什么**——源代码分析 + 行为分析。 对于一个描述干净但代码存在泄露的服务器：mcp-scan 会放过它。而我们能抓到它。 mcp-scan 无法检测到的真实漏洞（它们存在于代码中，而不是描述中）： - 提交到 git 的 `.env` 文件中的 Trello API 密钥 - 以明文形式存储的 Instagram session cookies - 通过未转义的剪贴板输入进行的 AppleScript 注入 - 权限为 `644` 的 Google OAuth token ## 审计历史（计划在 v1.0 中推出） 审计历史功能尚未实现。计划的设计是：每次审计都会保存一个 JSONL 日志，后续运行会比较结果，将发现分类为**已确认**、**新增**或**已修复**——从而将 LLM 的非确定性转化为优势。 ## 架构 ``` /mcp-redteam | +-----------------+ | Phase 0: Config | +-----------------+ | +-----------+ | Discovery | +-----------+ | | 1 server = 1 agent | +----------+ +----------+ +----------+ +----------+ | Agent-01 | | Agent-02 | | Agent-03 | | Agent-N | | youtube | | trello | | instagram| | server-N | | health | | health | | health | | health | | arch | | arch | | arch | | arch | | complete | | complete | | complete | | complete | | security | | security | | security | | security | +----+-----+ +----+-----+ +----+-----+ +----+-----+ | | | | +------+-----+-----+------+ | +-------------------------+ | Chain analysis + report | +-------------------------+ | +----------------+ | HTML + Fix | +----------------+ ``` ## 测试 涵盖 9 个测试文件的 95+ 个测试： - **test_semgrep.py** — 每个脆弱性 fixture 都被检测到，每个良性 fixture 都是干净的 - **test_self_security.py** — 21 个测试：对我们自己的代码进行漏洞审计 - **test_stress.py** — 1000/10000 个发现、并发扫描、Unicode - **test_fuzzing.py** — 基于 Hypothesis 属性测试：任意输入，不崩溃 - **test_edge_cases.py** — 损坏的 JSON、文件缺失、空字节、超时 - **test_models.py** + **test_formatters.py** — 核心逻辑的单元测试 - **test_cli.py** — 11 个测试：CLI 参数解析、输出格式、退出代码 - **test_config_scanner.py** — 13 个测试：配置健康检查、范围冲突、凭据检测 ## 目前的局限性 - Plugin 需要带有已连接 MCP 服务器的 Claude Code - CLI 需要安装 semgrep 才能进行代码分析（如果未安装则优雅跳过） - LLM 分析需要 ANTHROPIC_API_KEY - 破坏性测试被有意跳过 — 仅进行只读探测 - 源代码分析适用于本地服务器；对 pip/npm 包可能存在访问限制 - Plugin 报告质量随模型能力而变化（Opus > Sonnet > Haiku） - 尚未在生产环境的 MCP 服务器上测量误报率 ### 已知的误报模式 - SSRF 规则会在 URL 由配置而非用户输入构建的 `httpx.get()` 上触发 - 路径遍历规则会在路径已验证但该验证未被识别为过滤器的 `open()` 上触发 - Stdout 污染会标记 `__main__` 块中的 `print()`（安全，不在 MCP 处理程序中） ## 文档 `docs/` 文件夹可独立使用： - **[attack-playbook.md](docs/attack-playbook.md)** — 18 种攻击类别，48+ 个 CVE，有效载荷和检测方法 - **[best-practices.md](docs/best-practices.md)** — MCP 服务器安全清单 - **[reference-server.md](docs/reference-server.md)** — 安全服务器模板（Python + Node.js） ## 参考 - [OWASP MCP Top 10](https://owasp.org/www-project-mcp-top-10/) - [Invariant Labs — 工具投毒攻击](https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks) - [Trail of Bits — MCP 安全层](https://blog.trailofbits.com/2025/07/28/we-built-the-security-layer-mcp-always-needed/) - [Palo Alto Unit 42 — MCP 攻击向量](https://unit42.paloaltonetworks.com/model-context-protocol-attack-vectors/) - [OX Security — STDIO 设计缺陷](https://www.ox.security/blog/the-mother-of-all-ai-supply-chains-critical-systemic-vulnerability-at-the-core-of-the-mcp/) - [NSA — MCP 安全指南](https://www.nsa.gov/Portals/75/documents/Cybersecurity/CSI_MCP_SECURITY.pdf) - [存在漏洞的 MCP 项目](https://vulnerablemcp.info/) ## 许可证 [MIT](LICENSE)

标签：Claude Code插件, Go语言工具, LNA, MCP服务器, Web报告查看器, 红队评估, 逆向工具, 错误基检测, 静态代码分析