martian7777/mcp-agent-security-scanner

## 🚨 问题背景 AI agent 现在正通过 MCP (Model Context Protocol) 连接到工具、文件、GitHub、Slack、Gmail、Notion、数据库和内部系统。**这带来了严重的安全风险：** - 🔓 不受限制的 shell 访问 (`bash -c "$USER_INPUT"`) - 🔑 硬编码在配置文件中的 API 密钥和 token - 📁 过度宽松的文件系统访问权限 (`/`, `/etc/shadow`, `~/.ssh`) - 📧 无需确认即可发送电子邮件、删除文件或清空数据库表的工具 - 💉 可能会劫持 agent 行为的 prompt 注入模式 - ⚠️ 从不受信任的路径 (`/tmp/Downloads/sketchy-tool`) 运行的二进制文件 **OWASP 现在有一个涵盖工具投毒、过度授权和上下文欺骗的 [MCP Top 10](https://owasp.org/www-project-mcp-top-10/)。** GitHub 增加了对 MCP 工作流的密钥扫描支持。攻击面是真实存在且不断扩大的。 **MCP-Scan 可以在几秒钟内发现这些风险。** ## ⚡ 快速开始 ### 安装 ``` pip install mcp-agent-security-scanner ``` ### 扫描 ``` mcp-scan scan ./mcp-config.json ``` ### 就是这样。仅需 3 行代码。 ## 📥 示例输入 以下是一个危险的 MCP 配置： ``` { "mcpServers": { "terminal.run": { "command": "bash", "args": ["-c", "eval $USER_INPUT"], "env": { "OPENAI_API_KEY": "sk-proj-abc123def456ghi789jkl012mno" } }, "gmail.send": { "command": "node", "args": ["gmail-mcp-server", "--no-confirm"], "env": { "GMAIL_TOKEN": "ya29.a0AfH6SMBx_FAKE_TOKEN" } }, "filesystem": { "command": "/tmp/Downloads/sketchy-binary", "args": ["/", "/etc/shadow", "/root/.ssh"] } } } ``` ## 📊 示例输出 ``` ┌──────────────────────────────────────────────────────────┐ │ MCP Security Scan Report │ │ File: mcp-config.json │ │ Version: 0.1.1 │ └──────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────┐ │ Findings: 8 HIGH | 3 MEDIUM | 3 LOW (14 total) │ └──────────────────────────────────────────────────────────┘ Severity │ Rule │ Server │ Message ──────────┼─────────┼────────────────┼────────────────────────────────────── HIGH │ MCP-001 │ terminal.run │ Uses dangerous command: "bash" HIGH │ MCP-002 │ terminal.run │ OpenAI API key exposed in env HIGH │ MCP-006 │ gmail.send │ High-risk tool: email sending HIGH │ MCP-008 │ filesystem │ Binary from untrusted path: /tmp/ MEDIUM │ MCP-003 │ filesystem │ Access to sensitive path: /etc/shadow MEDIUM │ MCP-003 │ filesystem │ Access to sensitive path: /root/.ssh LOW │ MCP-005 │ terminal.run │ No allowedTools defined ``` ## 🔍 扫描规则 | 规则 | 名称 | 严重程度 | 捕获内容 | |------|------|----------|----------------| | **MCP-001** | 危险的 Shell 命令 | 🔴 高 | `bash`, `powershell`, `eval`, `sudo`, `ssh`, 管道 `curl` | | **MCP-002** | 暴露的密钥 | 🔴 高 | OpenAI 密钥, GitHub PAT, AWS 密钥, Slack token, 私钥 | | **MCP-003** | 过度宽松的路径 | 🟡 中 | `/`, `/etc`, `~/.ssh`, `C:\Windows\System32` | | **MCP-004** | 不受信任的 MCP 服务器 | 🟡 中 | 来自 `/tmp`, `Downloads`、未经验证的源的二进制文件 | | **MCP-005** | 缺少工具白名单 | 🔵 低 | 无 `allowedTools` 限制 → 完整的 agent 访问权限 | | **MCP-006** | 高风险工具 | 🔴 高 | 无门控的电子邮件发送、文件删除、数据库写入、Slack 发布 | | **MCP-007** | Prompt 注入 | 🟡 中 | “忽略之前的指令”、模板注入、越狱 | | **MCP-008** | 不安全的二进制执行 | 🔴 高 | 从 `/tmp/`, `Downloads/`, `.cache/` 执行 | ## 🐍 Python 库 API 在你自己的工具中以编程方式使用 `mcp-scan`： ``` from mcp_scan import scan_config, scan_file, ScanPolicy # 扫描 config 字典 result = scan_config({ "mcpServers": { "my-server": { "command": "bash", "args": ["-c", "rm -rf /"] } } }) print(result.has_errors) # True print(result.highest_severity) # "HIGH" print(result.total_findings) # 3 for finding in result.findings: print(f"[{finding.severity}] {finding.rule_id}: {finding.message}") # 使用自定义 policy 扫描 policy = ScanPolicy( allowed_commands=["node", "python"], trusted_servers=["@modelcontextprotocol/"], ignored_rules=["MCP-005"], ) result = scan_config(config, policy=policy) # 直接扫描文件 result = scan_file("./mcp-config.json") # 导出为 SARIF from mcp_scan import to_sarif_json print(to_sarif_json(result)) ``` ## 🌐 Web 仪表盘 启动内置仪表盘： ``` pip install mcp-agent-security-scanner[server] mcp-scan serve ``` 打开 `http://localhost:8000` —— 粘贴你的配置，点击 **Scan Now**，即可获得包含严重程度卡片、发现结果表格和 SARIF 导出的即时可视化结果。 ## 🐳 Docker ``` cd docker docker compose up --build ``` 仪表盘可通过 `http://localhost:8000` 访问。挂载你的配置文件： ``` docker run --rm -v $(pwd):/configs mcp-scan mcp-scan scan /configs/mcp-config.json ``` ## ⚙️ CI/CD 集成 ### GitHub Actions ``` - name: Install mcp-scan run: pip install mcp-agent-security-scanner - name: Scan MCP configs run: mcp-scan scan ./mcp-config.json --fail-on HIGH - name: Upload SARIF (optional) run: mcp-scan scan ./mcp-config.json --output sarif > results.sarif - uses: github/codeql-action/upload-sarif@v3 with: sarif_file: results.sarif ``` 当检测到高严重程度的发现时，扫描器将以退出代码 **1** 退出，自动使你的 CI pipeline 失败。 ## 📋 自定义扫描策略 创建 `mcp-policy.yaml` 以自定义行为： ``` trusted_servers: - "@modelcontextprotocol/" - "npx" allowed_commands: - "node" - "python" ignored_rules: - "MCP-005" max_severity: HIGH ``` ``` mcp-scan scan ./config.json --policy ./mcp-policy.yaml ``` ## 🏗️ 架构 ``` Input (CLI / API / Library) ↓ Parser (JSON / YAML → Pydantic McpConfig) ↓ Engine (8 security rules + policy filtering) ↓ Output (Rich terminal / JSON / SARIF / Dashboard) ``` 有关完整的架构图和威胁模型，请参阅 [docs/architecture.md](docs/architecture.md)。 ## 🎯 实际用例 - **AI 编程 agent** — 使用 Cursor、Windsurf 或 Claude Code 以及 MCP 服务器的团队，在授予 agent 访问代码库和基础设施的权限之前，需要审核工具权限。 - **企业级 AI 部署** — 推出具有工具使用功能的 Claude、GPT 或 Gemini 的公司，需要针对电子邮件、Slack、数据库和文件系统访问的安全门控。 - **平台工程** — 平台团队可以在 CI/CD 中运行 `mcp-scan`，以强制执行组织内所有 MCP 配置的安全策略。 - **合规性** — 安全团队可以生成 SARIF 报告以用于审计跟踪，并与 GitHub Advanced Security 集成。 ## 🗺️ 路线图 - [ ] **自定义规则引擎** — 用 YAML 编写你自己的规则 - [ ] **持续监控** — 监控配置文件的更改并发出警报 - [ ] **Slack/Discord 警报** — 在发现新风险时发送通知 - [ ] **VS Code 扩展** — 在你的编辑器中进行内联警告 - [ ] **MCP 运行时分析** — 在运行时监控实际的工具调用 - [ ] **组织范围的策略** — 集中策略管理 - [ ] **SBOM 集成** — 用于 MCP 服务器依赖项的软件物料清单 (SBOM) ## 📄 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：AI代理, LNA, MCP, Python, StruQ, 安全扫描, 无后门, 时序注入, 请求拦截, 逆向工具