lorbeere711/mcp-security-scanner

# MCP Security Scanner 专为 MCP 服务器设计的 npm-audit。 在安装 MCP 服务器之前，只需运行一条命令即可查看其实际功能。 在将 MCP 服务器连接到 Claude、Codex、Cursor 或其他 AI agent 之前，扫描它们是否存在危险工具、提示注入风险、过度权限以及不安全的 agent 能力。  ## 快速开始 ``` npx mcp-security-scanner scan ./mcp-server-config.json ``` 将其添加到 CI 中： ``` - uses: lorbeere711/mcp-security-scanner@v0 with: target: ./mcp.json format: sarif ``` ## 定位 `mcp-security-scanner` 专注于为 MCP 服务器提供快速、可解释的安装时风险检查。 该项目与运行时沙箱机制和广泛的研究工作有本质区别： - 它是一个轻量级的 CLI，你可以在 CI 和预安装工作流中运行。 - 它会报告具体且可解释的发现，并提供可操作的修复文本。 - 它生成机器可读的输出（`json`、`sarif`），供安全工具使用。 ## 扫描内容 (MVP 0.1) - 危险权限 - 提示注入指示符 - 不安全的工具描述 - 潜在的数据泄露路径 - 缺失的元数据信号（名称/许可证） - 无白名单的广泛文件系统/网络权限 - 风险评分（`0-100`）及面向严重程度的报告输出 ## 缘由 MCP 的普及正在迅速增长，而安全检查往往是临时的。该扫描器为 CI pipeline 和本地强化审查提供了实用的基线。 ## 安装 使用 npx： ``` npx mcp-security-scanner scan ./mcp-server-config.json ``` 或者在本地安装以进行开发： ``` npm install npm run build ``` ## 用法 ``` mcp-security-scanner scan ./mcp-server-config.json mcp-security-scanner scan ./mcp-server-config.yaml mcp-security-scanner scan --server @modelcontextprotocol/server-filesystem mcp-security-scanner audit ./mcp-server-config.json --format sarif mcp-security-scanner scan ./mcp-server-config.json --format json mcp-security-scanner scan ./mcp-server-config.json --format sarif --output report.sarif ``` 格式： - `text`：人类可读的报告（默认） - `json`：机器可读的完整扫描结果（`schemaVersion: "1.0.0"`） - `sarif`：用于代码扫描工具的 SARIF 2.1.0 报告 JSON schema 版本 `1.0.0` 对于自动化消费者是稳定的： ``` { "schemaVersion": "1.0.0", "target": "examples/insecure.json", "scannedAt": "2026-06-13T00:00:00.000Z", "findings": [ { "id": "PERM-001", "severity": "high", "title": "Dangerous permission detected", "description": "Permission shell can enable high-impact actions.", "recommendation": "Apply least-privilege.", "path": "permissions" } ] } ``` 必填的顶层字段包括 `schemaVersion`、`target`、`scannedAt` 和 `findings`。每个发现都包含 `id`、`severity`、`title`、`description` 和 `recommendation`；当扫描器能够指向特定的配置位置时，会包含 `path`。 输出示例： ``` HIGH filesystem tool exposes /Users without allowlist MED tool "fetch_url" can retrieve arbitrary external content LOW missing server metadata / license ``` 退出代码： - `0`：无高危或严重发现 - `1`：扫描器/运行时错误 - `2`：检测到高危或严重发现 ## 开发 ``` npm run dev -- scan ./examples/insecure.json npm run lint npm run test npm run build npm run pack:check ``` ## 对抗性测试基准 此代码库在 [examples/fixtures/](examples/fixtures/) 下包含对抗性基准测试件，以明确扫描器的确定性行为。 - 安全的测试件位于 [examples/fixtures/safe/](examples/fixtures/safe/) - 不安全的测试件位于 [examples/fixtures/unsafe/](examples/fixtures/unsafe/) - 预期结果记录在 [examples/fixtures/manifest.json](examples/fixtures/manifest.json) 中 每个清单条目包括： - `expectedFindingIds`：该测试件必须存在的发现 - `mustMissFindingIds`：有意预期缺失的发现（已知的漏报） - `notes`：该测试件存在的原因说明 使用以下命令运行测试件基准测试： ``` npm run test ``` ### 已知限制：自然语言泄露意图 扫描器在多项规则中是确定性的且由关键词驱动。这意味着自然语言描述可能暗示了风险行为，但并未匹配当前的 keyword 模式。 示例：某个工具描述说它将“与配置好的 service endpoint 共享诊断信息”，这可能代表了一种数据泄露意图，但目前可能不会触发 `EXFIL-001`。 此限制作为已知的漏报在对抗性测试件套件中被明确追踪，因此遗漏是可见的，并且会进行回归测试，而不是被隐藏。 ### 添加新的基准测试件 1. 将测试件 JSON 文件添加到 [examples/fixtures/](examples/fixtures/) 下的相应文件夹中。 2. 在 [examples/fixtures/manifest.json](examples/fixtures/manifest.json) 中添加或更新对应的条目。 3. 保持测试件元数据专注于发现 ID（`expectedFindingIds` 和 `mustMissFindingIds`），以避免脆弱的测试。 4. 运行 `npm run test` 并确认预期检测和已知遗漏的行为均已明确。 ## GitHub Action ``` - uses: lorbeere711/mcp-security-scanner@v0 with: target: ./mcp.json format: sarif ``` 或者扫描服务器包： ``` - uses: lorbeere711/mcp-security-scanner@v0 with: server: @modelcontextprotocol/server-filesystem format: sarif ``` ## 发布准备 ``` npm run prepublishOnly npm run pack:check ``` 如果检查通过，请在配置了 npm 凭据的可信环境中进行发布。 ## 贡献想法 - good first issue：添加针对文件系统过度权限的检测器 - good first issue：添加 JSON 输出增强和稳定的 schema 文档 - help wanted：改进 SARIF 映射以提升 GitHub 代码扫描用户体验 - help wanted：添加 MCP 服务器注册表扫描器支持 - research：将已知的 MCP 漏洞映射到检测器规则 有关计划的工作和评估想法，请参阅 [docs/ROADMAP.md](docs/ROADMAP.md)。 ## 路线图 - 规则配置和抑制 - CI 集成助手 - 扩展的 MCP schema 感知 ## 许可证 MIT

标签：AI安全, Chat Copilot, MCP, MITM代理, 暗色界面, 自动化攻击, 静态代码扫描