vawkdh-job/mcp-riskmap

# mcp-riskmap [](https://github.com/vawkdh-job/mcp-riskmap/actions/workflows/ci.yml) [](https://github.com/vawkdh-job/mcp-riskmap/actions/workflows/mcp-riskmap.yml) [](https://github.com/vawkdh-job/mcp-riskmap/releases) [](https://pypi.org/project/mcp-riskmap/) [](LICENSE) `mcp-riskmap` 是一个本地优先的静态审计工具，专为 MCP 和 agent-tool 仓库设计。它会在不启动不受信任的 MCP 服务器的情况下，查找有风险的 MCP 配置、启用 shell 的工具处理程序、类似 prompt injection 的工具描述，以及缺失的维护者指南。 本项目特意保持精简和保守。它专为希望在本地开发、pull request 和 GitHub Code Scanning 中获取快速审查信号的维护者而设计。 ## 为什么会有这个项目 MCP 服务器通常会暴露能够触及文件、shell、网络、凭据或本地开发者状态的工具。参考服务器和社区示例虽然有用，但在分享配置或接受工具更改之前，每个维护者仍然需要具备威胁模型和基本的安全防护措施。 `mcp-riskmap` 专注于易于审查的静态信号： - 通过 `cmd`、`powershell`、`bash` 或 `sh` 启动的 MCP 配置 - 远程安装 pipeline，例如 `curl ... | sh` 或 `curl ... | iex` - 传递给 MCP 服务器的类似于密钥的环境变量 - 整个进程环境变量直接传递给 Python 或 JavaScript 子进程 - Python 的 `subprocess(..., shell=True)`、`os.system`、`eval` 和 `exec` - JavaScript 的 `child_process.exec` 和 `spawn(..., { shell: true })` - 似乎使用了用户可控路径输入的 Python 和 JavaScript 文件系统访问 - 看起来像模型控制 prompt injection 的工具文本 - 看起来像 prompt injection 或工具投毒文本的 JSON 工具元数据 - 缺失 `AGENTS.md`、`SECURITY.md` 或 `LICENSE` ## 安装 来自 PyPI： ``` python -m pip install --upgrade mcp-riskmap ``` 从代码库检出版本： ``` python -m pip install -e . ``` 来自 GitHub： ``` python -m pip install "git+https://github.com/vawkdh-job/mcp-riskmap.git@v0.2.0" ``` 用于开发而无需安装： ``` $env:PYTHONPATH = "src" python -m mcp_riskmap.cli scan examples/unsafe-mcp-server python -m mcp_riskmap.cli --version ``` ## 用法 ``` mcp-riskmap scan . mcp-riskmap scan . --format json mcp-riskmap scan . --format markdown --output report.md mcp-riskmap scan . --format sarif --output results.sarif --fail-on high mcp-riskmap scan . --exclude "examples/**" --exclude "tests/**" mcp-riskmap scan . --profile ci mcp-riskmap baseline . --output mcp-riskmap-baseline.json mcp-riskmap scan . --baseline mcp-riskmap-baseline.json --profile ci ``` `--fail-on high` 会在至少有一个高危或严重发现时返回退出代码 `1`。 对于已经审查过的 fixture 目录、生成的输出，或者不应该阻塞 CI 的故意写的不安全示例，请使用 `--exclude`。 使用 `--profile` 应用常见的失败策略： - `local`：报告发现的问题，但不失败。 - `audit`：报告发现的问题，但不失败，旨在用于审查工件。 - `ci`：遇到高危或严重发现时失败。 - `release`：遇到中危、高危或严重发现时失败。 `--fail-on` 会覆盖所选的 profile。 在已经在代码库中采用 `mcp-riskmap` 且审查过现有发现时，请使用 `baseline`。基线会记录当前的发现，而 `scan --baseline` 将仅报告基线中尚未记录的新发现。 有关推荐的基线工作流，请参阅 [docs/baseline-ratchet.md](docs/baseline-ratchet.md)。 ## 示例 - `examples/unsafe-mcp-server/` 包含用于扫描程序演示的故意带有风险的 MCP 配置和工具处理程序模式。 - `examples/safe-mcp-server/` 包含使用解析后基础目录边界检查的更安全的文件读取模式。 - `docs/rules.md` 包含每条规则的不安全示例、较安全的模式以及审查说明。 ## 示例输出 ``` SEVERITY RULE LOCATION MESSAGE -------- ------------------------- ------------ ------------------------------------------------ CRITICAL MCP-CONFIG-REMOTE-INSTALL mcp.json:5 MCP server 'unsafe-demo' downloads and executes... HIGH PY-SHELL-TRUE server.py:6 A Python tool handler can pass input through a shell. HIGH JS-CHILD-PROCESS-EXEC server.js:4 A JavaScript tool handler can pass input through a shell. ``` ## 输出格式 - `table`：紧凑的终端输出 - `json`：适合自动化的结构化输出 - `markdown`：适合 issue 和发布说明的报告 - `sarif`：兼容 GitHub Code Scanning 的输出 结构化输出会在写入 JSON 或 SARIF 之前，对类似于密钥的证据值进行脱敏处理。 ## 审查后的抑制规则 如果维护者审查了某项发现并接受了相关风险，可以在同一行或上一行添加精确的抑制规则： ``` # mcp-riskmap: 忽略 PY-SHELL-TRUE subprocess.run(command, shell=True) ``` 尽可能使用特定于规则的抑制。`mcp-riskmap: ignore` 会抑制下一行的所有规则，应仅保留给生成的或有文档说明的 fixture 代码使用。 ## GitHub Action 本仓库包含一个复合 GitHub Action： ``` name: mcp-riskmap on: pull_request: push: branches: [main] jobs: scan: runs-on: ubuntu-latest permissions: contents: read security-events: write steps: - uses: actions/checkout@v6 - uses: vawkdh-job/mcp-riskmap@v0.1.5 with: path: . format: sarif output: mcp-riskmap.sarif fail-on: high exclude: | examples/** tests/** - uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: mcp-riskmap.sarif ``` 在 [docs/ci-examples](docs/ci-examples/) 中提供了更多可直接复制粘贴的工作流。 ## 安全立场 `mcp-riskmap` 不会执行 MCP 服务器。它仅读取文件并报告静态发现。这意味着它会遗漏仅在运行时出现的行为，但对于快速审查未知的配置和 pull request 来说更加安全。 ## 为什么仅限静态？ 一些 MCP 扫描程序通过启动已配置的服务器来检查实时的工具描述。这可能很有用，但当审查者在查看未知仓库或 pull request 时却存在风险。`mcp-riskmap` 旨在审查流程的早期运行：它读取文件，标记明显的风险，并在不执行目标项目命令的情况下生成审查工件。 ## 与动态扫描程序相比 `mcp-riskmap` 并非动态 MCP 检查的替代品。对于需要在 CI 和代码审查中获取快速审查信号的维护者来说，它是一道初级的防护栏。 | 领域 | mcp-riskmap | 动态扫描程序 | | --- | --- | --- | | 启动被扫描的 MCP 服务器 | 否 | 通常会 | | 对未知 PR 是否安全 | 专为此设计 | 取决于沙箱环境 | | 对 CI/SARIF 友好 | 是 | 取决于工具 | | 运行时行为覆盖率 | 有限 | 较好 | | 静态源码/配置审查 | 主要重点 | 各不相同 | ## 当前局限性 - 规则是保守的 regex/静态检查，而非完整的污点分析。 - 扫描程序不会检查实时的 MCP 工具响应。 - 密钥检测基于键名，不进行高熵扫描。 - JavaScript 和 Python 分析器优先关注常见的高风险模式。 ## 路线图 - 添加 CI 示例，以便从其他仓库中使用 `mcp-riskmap`。 - 添加规则严重性 profile。 - 改进针对 MCP prompt injection 和工具投毒模式的工具元数据检查。 - 添加兼容 Semgrep 的模式导出。 有关 issue 级别的里程碑，请参阅 [ROADMAP.md](ROADMAP.md)。 ## OpenAI Codex 在 OSS 适配中的应用 本项目旨在作为一个开源安全和维护者自动化工具进行维护。它包含测试、CI、SARIF 输出、GitHub Code Scanning 支持、已发布的 PyPI 包、示例、安全文档、贡献指南、AGENTS.md、受保护的主分支工作流说明以及带标签的发布。 Codex/API 额度将用于审查规则更改、生成回归测试、分类 issue、改进文档以及生成发布说明。AI 的输出在合并前应由维护者进行审查。 有关特定于应用程序的维护者工作流说明，请参阅 [docs/codex-for-oss.md](docs/codex-for-oss.md)。

标签：AI安全, Chat Copilot, Go语言工具, MCP, OpenCanary, Python, 无后门, 网络安全审计, 逆向工具, 错误基检测, 静态代码分析