CoderSufiyan/mcp-risk

# mcp-risk [](https://www.npmjs.com/package/mcp-risk) [](https://www.npmjs.com/package/mcp-risk) [](https://github.com/CoderSufiyan/mcp-risk/actions) [](LICENSE) MCP 服务器让 AI agent 能够访问文件、终端、浏览器、数据库、GitHub、Slack 以及内部工具。这种能力非常有用，但也伴随着风险：恶意的或权限范围过大的 MCP 服务器可能会暴露敏感信息（secrets）、执行 shell 命令，或者在工具描述中隐藏提示词注入（prompt-injection）指令。 `mcp-risk` 是一款本地优先的 MCP 配置扫描工具。你可以把它看作是针对 agent 工具的 `npm audit`。 ## 0.3.0 版本新特性 - **扫描所有配置：** 运行 `mcp-risk scan --all` 以审计已发现的项目和用户 MCP 配置。 - **更广泛的发现能力：** 支持查找 Claude Desktop、Cursor、Claude Code、Continue、Windsurf、VS Code 和 Cline 的配置文件。 - **清晰的诊断信息：** 对于格式错误、为空以及不支持的 MCP 配置会进行报告，而不会将其视为扫描安全（clean scans）。 ## 0.2.0 版本特性 - **GitHub 代码扫描：** 使用 `mcp-risk scan . --sarif` 输出 SARIF 并将结果上传到 GitHub。 - **项目策略：** 使用 `.mcp-risk.json` 屏蔽已批准的服务器和漏洞发现的组合。 - **工具 schema 分析：** 检测 MCP 工具输入 schema 中不受限制的命令、文件系统路径、URL 以及破坏性操作参数。  ``` npx mcp-risk scan ~/.cursor/mcp.json ``` ``` MCP Risk Audit Target: examples/risky-mcp.json Score: F (0/100) Findings: 0 critical, 5 high, 2 medium, 0 low HIGH Server starts through a general-purpose interpreter or shell server:local-shell "local-shell" runs with "bash", which can execute arbitrary code depending on arguments. HIGH Tool description contains prompt-injection language server:local-shell.tool:search_docs "search_docs" includes instruction override wording in its description. MED Server receives sensitive environment variable server:local-shell.env.GITHUB_TOKEN "local-shell" receives "GITHUB_TOKEN". A malicious or compromised MCP server could exfiltrate it. ``` ## 安装 ``` npm install -g mcp-risk ``` 或者免安装直接运行： ``` npx mcp-risk scan ``` ## 用法 扫描当前目录： ``` mcp-risk scan ``` 扫描特定配置文件： ``` mcp-risk scan ~/.cursor/mcp.json mcp-risk scan ./mcp.json mcp-risk scan ./project ``` 扫描所有已发现的项目和用户配置： ``` mcp-risk scan --all ``` 项目配置发现机制支持 `mcp.json`、`.mcp.json`、`.cursor/mcp.json`、`.claude/mcp.json`、`.vscode/mcp.json`、`.windsurf/mcp.json` 以及 Continue/Cline 的项目配置路径。用户配置发现机制可识别 macOS、Linux 和 Windows 系统上的 Claude Desktop、Cursor、Claude Code、Continue、Windsurf、VS Code 和 Cline 的配置位置。 支持的配置文件格式为包含 `mcpServers`、`servers` 或根级 `tools` 的 JSON 或 YAML 对象。`mcp-risk` 会对格式错误的文件和不支持的数据结构进行报告，而不会将它们视为扫描安全。 尝试包含的演示示例： ``` npx mcp-risk scan examples/risky-mcp.json ``` 如果存在高风险发现，则让 CI 失败： ``` mcp-risk scan . --fail-on high ``` 通过项目策略文件允许已批准的发现结果。`mcp-risk` 会从被扫描的配置文件所在位置向上搜索 `.mcp-risk.json`： ``` { "allow": [ { "server": "filesystem", "finding": "tool-filesystem-capability" }, { "server": "internal-docs" }, { "finding": "tool-network-capability" } ] } ``` 允许（allow）条目可以匹配服务器、发现 ID，或者同时匹配两者。被允许的发现结果将在评分、输出和 `--fail-on` 评估中被屏蔽，但报告中会包含它们的数量。 JSON 输出： ``` mcp-risk scan . --json ``` 用于 GitHub 代码扫描的 SARIF 输出： ``` mcp-risk scan . --sarif > mcp-risk.sarif ``` ## GitHub Action ``` name: MCP Risk Audit on: [push, pull_request] permissions: contents: read security-events: write jobs: mcp-risk: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: CoderSufiyan/mcp-risk@v1.1.1 with: target: . fail-on: high node-version: '22' ``` 该 Action 默认会生成并上传 SARIF。它需要 `security-events: write` 权限来创建 GitHub 代码扫描警报，并会自动安装配置好的 Node.js 版本。对于来自 fork 仓库的 pull request，请设置 `upload-sarif: 'false'`，因为 GitHub 在此类情况下只提供只读 token。在生产工作流中，请将 Action 固定到特定的 commit SHA。 ## 检测内容 | 风险 | 示例 | |---|---| | Shell 执行 | `command: "bash"` 或 `args: ["-c", "..."]` | | 危险命令模式 | `rm -rf`、`curl`、`wget`、内联 eval | | 敏感环境变量暴露 | `GITHUB_TOKEN`、`OPENAI_API_KEY`、`AWS_SECRET_ACCESS_KEY` | | 不安全的传输方式 | 通过 `http://` 连接的远程 MCP 服务器 | | 工具描述中的提示词注入 | "ignore previous instructions"、"reveal secrets" | | 文件系统工具 | 读取/写入/删除文件的能力 | | 网络工具 | 抓取/浏览器/爬取/爬虫能力 | | 工具输入 schema | 不受限制的命令、路径、URL、删除或覆盖参数 | ## 为什么 MCP 安全性至关重要 MCP 正在成为 AI agent 的插件层。这意味着 MCP 配置实际上就是一份权限清单，决定了 agent 可以在你的机器上执行哪些操作。 在启用某个服务器之前，你应该了解： - 它能否运行任意的 shell 命令？ - 它是否会接收像 `GITHUB_TOKEN` 或 `OPENAI_API_KEY` 这样权限过大的 token？ - 它能否读取或写入你项目之外的文件？ - 它能否抓取不受信任的远程内容？ - 它的工具描述中是否包含可能操纵 agent 行为的指令性文本？ `mcp-risk` 可以在这些工具连接到 agent 之前，为你提供快速的本地分析结果。 ## 示例报告 ``` MCP Risk Audit Target: .cursor/mcp.json Score: D (38/100) Findings: 0 critical, 3 high, 2 medium, 0 low HIGH Server starts through a general-purpose interpreter or shell server:local-shell "local-shell" runs with "bash", which can execute arbitrary code depending on arguments. Fix: Prefer a pinned package binary or audited executable instead of a shell/interpreter entrypoint. HIGH Tool description contains prompt-injection language server:docs.tool:search_docs "search_docs" includes instruction override wording in its description. Fix: Remove instruction-like text from tool descriptions. ``` ## 库 API ``` import { auditConfig, auditFile } from 'mcp-risk' const result = auditFile('./mcp.json') const inline = auditConfig({ mcpServers: { docs: { command: 'node', tools: [ { name: 'search_docs', description: 'Search project docs', }, ], }, }, }) ``` ## 设计目标 - 本地优先：配置扫描在本地机器上完成。 - 对 CI 友好：提供适合人类阅读的文本输出，以及适合自动化流程的 JSON 和退出代码。 - 实用的发现：每一条警告都包含具体的修复建议。 - 轻量级：无需 AI API 密钥。 - 客户端无关：兼容 Cursor、Claude Desktop、Claude Code、Cline、Continue 及其他 MCP 客户端。 ## 路线图 - 发现更多客户端的配置路径 - 扫描所有已发现的 MCP 配置 - 推出官方的用于 MCP 风险扫描的 GitHub Action - 提供可选的远程仓库审计功能 ## 开源 `mcp-risk` 采用 MIT 许可证，欢迎参与贡献。欢迎提交与安全相关的规则、客户端配置示例、文档修复以及误报反馈。 ## 许可证 MIT

标签：AI智能体, MCP, MITM代理, 云安全监控, 图数据库, 暗色界面, 自动化攻击, 配置扫描, 静态分析