🔍 MCPScan

MCP 服务器配置安全扫描器

在你的 AI 智能体使用工具权限之前，先一步捕获其中的漏洞。

## 🆕 v0.2.0 版本更新 - **📄 HTML 报告** (`--report html`) — 精美的独立 HTML 报告，包含暗色主题、执行摘要、严重程度卡片和详细发现。零依赖 —— 可作为单个文件分享。 - **📋 SARIF JSON 导出** (`--report json`) — 兼容 GitHub Code Scanning 的 SARIF v2.1.0 输出。可直接上传至 GitHub Advanced Security。 - **🔀 Diff 模式** (`mcpscan diff baseline.json current.json`) — 对比两次扫描以追踪新增/已解决的发现。作为 PR 门禁使用 `--fail-on-new`。 - **🧪 132 项测试** — 覆盖所有模块的全面测试。 ## 问题背景 MCP (Model Context Protocol) 服务器赋予 AI 智能体访问强大工具的能力 —— 文件系统、网络、数据库、Shell。配置错误或恶意的 MCP 服务器可能会： - 🔓 **泄露凭证** — 硬编码在配置中的 API 密钥和令牌 - 🎯 **导致 SSRF** — 通过云元数据端点访问内部网络 - 💉 **注入提示词** — 通过工具描述劫持智能体行为 - 👻 **影子工具** — 用恶意版本替换合法工具 - 🐚 **授予 Shell 访问权** — 不受限制的命令执行 - ☠️ **产生毒性数据流** — 将数据源链接到外部接收点以进行渗漏 - 📤 **渗漏数据** — 将敏感信息发送到外部端点 **MCPScan 能在几秒钟内发现这些问题 —— 100% 本地运行，零云依赖。** ## 快速开始 ``` # 安装 pip install mcpscan # 扫描您的 Claude Desktop 配置 mcpscan scan ~/.config/claude/claude_desktop_config.json # 自动发现并扫描您系统上的所有 MCP 配置 mcpscan discover # 扫描任意 MCP 配置 mcpscan scan config/mcporter.json ``` ## 安装 ### 通过 PyPI 安装（推荐） ``` pip install mcpscan ``` ### 从源码安装 ``` git clone https://github.com/kryptonomeai-cloud/mcpscan.git cd mcpscan pip install -e . ``` ### 包含开发依赖 ``` pip install -e ".[dev]" ``` ## 使用方法 ### 基础扫描 ``` $ mcpscan scan config.json ╭─────────────────────────────╮ │ MCPScan Report │ │ Config: config.json │ │ Format: claude_desktop │ │ Servers: 6 │ ╰─────────────────────────────╯ 🔴 CRITICAL (1) [CRED-001] Secret exposed in URL: Zapier-style secret key Server: zapier → Use environment variables instead of embedding secrets in URLs. 🟠 HIGH (2) [CRED-002] Hardcoded secret in env: PAPERLESS_API_KEY Server: paperless → Use a secrets manager or .env file (gitignored). [PERM-001] Unrestricted shell access Server: terminal → Limit allowed commands or use a sandboxed environment. ╭──────────────────────────╮ │ Score: 42/100 (Poor) │ ╰──────────────────────────╯ ``` ### HTML 报告 ``` $ mcpscan scan config.json --report html -o report.html # 生成一个独立的 HTML 文件，包含： # • 包含总体风险评分的执行摘要 # • 严重程度计数卡 (critical/high/medium/low/info) # • 服务器概览表 # • 包含证据和补救措施的详细发现 # • 深色主题 (#0a0a0b) 配以青色点缀 — 外观极佳 ``` ### SARIF 导出（GitHub Security） ``` # 生成用于 GitHub Code Scanning 的 SARIF $ mcpscan scan config.json --report json -o results.sarif # 上传到 GitHub (在 CI 中): # gh api repos/{owner}/{repo}/code-scanning/sarifs \ # --field sarif=@results.sarif ``` ### Diff 模式 — 追踪扫描间的变化 ``` # 保存基线 $ mcpscan scan config.json --format json -o baseline.json # 稍后，再次扫描并比较 $ mcpscan scan config.json --format json -o current.json $ mcpscan diff baseline.json current.json ✅ Resolved: [CRED-001] Secret exposed in URL (zapier) 🆕 New: [PERM-003] Container escape vector (docker) Score: 42 → 58 (+16) # 用作 PR 门禁 — 如果出现新问题则失败 $ mcpscan diff baseline.json current.json --fail-on-new ``` ### 自动发现配置 ``` # 查找并扫描您系统上的所有 MCP 配置 $ mcpscan discover Found 3 MCP configurations: ✅ Claude Desktop — ~/.config/claude/claude_desktop_config.json (4 servers) ✅ mcporter — ~/.openclaw/config/mcporter.json (6 servers) ❌ Cursor — not found # 一次扫描所有发现的配置 $ mcpscan discover --scan ``` ### 输出格式 ``` # 终端 (默认) — 彩色，人类可读 mcpscan scan config.json # JSON — 用于 CI/CD 管道 mcpscan scan config.json --format json # Markdown — 用于报告和 PR mcpscan scan config.json --format markdown -o report.md ``` ### 动态检查（连接性） ``` # 包含实时连接性和 TLS 检查 mcpscan scan config.json --dynamic ``` ### CI/CD 集成 ``` # 如果存在任何高 (high) 及以上严重程度的发现，则构建失败 mcpscan scan config.json --fail-on high # 用于机器解析的 JSON 输出 mcpscan scan config.json --format json --fail-on medium ``` ### 检查解析后的配置 ``` mcpscan info config.json ``` ## 安全检查模块 MCPScan 包含 **10 个安全检查模块**，涵盖 **40+ 条独立规则**： | # | 模块 | ID | 规则 | 检测内容 | |---|--------|-----|-------|-----------------| | 1 | **Credentials** | `CRED-001..004` | 4 | URL、环境变量和命令参数中的 API 密钥、令牌、密码 | | 2 | **Permissions** | `PERM-001..005` | 5 | Shell 执行、文件系统访问、提权、Docker/容器逃逸 | | 3 | **SSRF** | `SSRF-001..003` | 3 | 内部网络、云元数据端点 (AWS/GCP/Azure)、危险 URI 方案 | | 4 | **Tool Shadowing** | `SHADOW-001..002` | 2 | 跨服务器的重复工具名称、重叠的工具类别 | | 5 | **Input Validation** | `VAL-001..005` | 5 | `npx -y` 自动安装、未锁定版本、已知易受攻击的包 | | 6 | **Transport** | `TRANS-001..002` | 2 | 未加密的 HTTP 端点、无 TLS 的远程 SSE 连接 | | 7 | **Descriptions** | `DESC-001..002` | 2 | 可疑的元数据模式、工具描述中的注入向量 | | 8 | **Prompt Injection** | `INJECT-001..005` | 5 | 系统提示词覆盖尝试、隐藏指令、角色扮演攻击 | | 9 | **Connectivity** | `CONN-001..013` | 13 | 实时 TCP 可达性、TLS 证书验证、过期检查（动态） | | 10 | **Toxic Flows** | `TOXIC-001..002` | 2 | 数据源 → 外部接收点链、服务器间的数据渗漏路径 | ### 严重程度级别 | 级别 | 含义 | |-------|---------| | 🔴 **Critical** | 紧急安全风险 —— 凭证泄露、云元数据 SSRF、sudo 权限 | | 🟠 **High** | 高风险 —— Shell 执行、硬编码机密、工具影子 | | 🟡 **Medium** | 中等风险 —— 未加密 HTTP、npx 自动安装、容器访问 | | 🔵 **Low** | 轻微隐患 —— 未锁定版本、动态包执行 | | ⚪ **Info** | 信息提示 —— 内部网络访问、远程连接 | ## MCPScan vs 云扫描器 | | MCPScan | 基于云的扫描器 | |---|---------|---------------------| | **数据隐私** | ✅ 100% 本地 —— 机密永不离开你的设备 | ❌ 配置上传至第三方服务器 | | **速度** | ✅ <1 秒完成扫描 | ⏳ 网络往返 + 排队 | | **离线** | ✅ 无需联网即可工作 | ❌ 需要网络连接 | | **成本** | ✅ 免费且开源 | 💰 通常付费/免费增值 | | **CI/CD** | ✅ `pip install` + 一条命令 | 🔧 API 密钥、Webhook、配置 | | **可审计性** | ✅ 可阅读每一行源代码 | ❌ 黑盒 | | **MCP 专用** | ✅ 专为 MCP 配置构建 | ⚠️ 通用或改编的扫描器 | **你的 MCP 配置包含 API 密钥、令牌和基础设施详情。为什么要发送到云端？** ## 支持的配置格式 - ✅ **Claude Desktop** (`claude_desktop_config.json`) - ✅ **Cursor** (`.cursor/mcp.json`) - ✅ **VS Code** (`.vscode/mcp.json`) - ✅ **Windsurf** (`.windsurf/mcp.json`) - ✅ **Continue.dev** (`.continue/config.json`) - ✅ **mcporter** (`mcporter.json`) - ✅ 任何具有 `mcpServers` 结构的 JSON ### 自动发现 MCPScan 可以自动在您的系统中查找所有受支持客户端的 MCP 配置。运行 `mcpscan discover` 以扫描 macOS、Linux 和 Windows 的常用位置。 ## 功能特性 - [x] 10 个安全检查模块，包含 40+ 条独立规则 - [x] 跨 6 种流行客户端自动发现 MCP 配置 - [x] 严重程度评分 (0-100) 及字母等级 - [x] 静态 + 动态（实时连接性/TLS）分析 - [x] 跨服务器分析（毒性数据流、工具影子） - [x] 多种输出格式（终端、JSON、Markdown） - [x] CI/CD 集成，支持 `--fail-on` 阈值 - [x] HTML 报告 —— 暗色主题、自包含、可分享 - [x] SARIF JSON 导出 —— 兼容 GitHub Code Scanning - [x] Diff 模式 —— 追踪扫描间新增/已解决的发现 - [x] 100% 离线 —— 数据永不离开你的设备 - [x] 零云依赖 - [x] 可扩展的检查架构 - [ ] VS Code 扩展 - [ ] Pre-commit Hook ## 开发 ``` # 克隆并安装 git clone https://github.com/kryptonomeai-cloud/mcpscan.git cd mcpscan pip install -e ".[dev]" # 运行测试 (132 项测试) pytest tests/ -v # 针对测试 fixtures 运行 mcpscan scan tests/fixtures/vulnerable_1.json mcpscan scan tests/fixtures/vulnerable_2.json ``` ## 隐私 MCPScan 是 **100% 本地** 的： - ✅ 完全在你的机器上运行 - ✅ 从不向任何外部服务发送数据 - ✅ 零云依赖 - ✅ 完全离线工作 你的 MCP 配置可能包含机密 —— MCPScan 永远不会将它们传输到任何地方。 ### 添加新的安全检查 1. 在 `src/mcpscan/checks/` 中创建新文件 2. 遵循现有模式实现检查函数 3. 在 `src/mcpscan/checks/__init__.py` 中注册 4. 添加测试固件和测试用例 ## 许可证 MIT — 详情见 [LICENSE](LICENSE)。

由 Fyzi Security 构建 · 保护 AI 工具链安全

标签：CISA项目, DevSecOps, DNS 反向解析, HTML 报告, LLM 安全, MCP, Model Context Protocol, PyPI, Python, SARIF, SSRF 防护, URL发现, 上游代理, 云安全监控, 加密, 安全检测, 工具访问控制, 文档结构分析, 无后门, 漏洞扫描器, 网络安全, 逆向工具, 防御绕过, 隐私保护, 静态分析