SteveMonsway/mcp-trust

# MCP Trust 用于 Model Context Protocol (MCP) 服务器的基于证据的预检扫描器。 在你的 AI agent 使用 MCP 服务器之前对其进行检查。 本仓库涵盖 **Phase 0 → Phase 4**：一个可用的 CLI、一个确定性规则 引擎（30 条规则）加上 12 条 Semgrep AST 规则、配置/静态/元数据扫描、真正的 `@modelcontextprotocol/sdk` 内省与 Docker 沙箱（Level 2）、 JSON / Markdown / **HTML** / **SARIF** 报告，配备 **GitHub Action**（Code Scanning + PR 评论）， 以及一个针对真实 MCP 服务器的**公开基准测试**（参见 [`docs/benchmark.md`](docs/benchmark.md)）。 ## 快速开始 从 npm 安装（无需克隆）： ``` # 一次性运行，无需安装： npx @mcp-trust/cli scan github:owner/repo # 或者全局安装： npm install -g @mcp-trust/cli mcp-trust scan github:owner/repo # scan a public GitHub repo mcp-trust scan npm:@org/mcp-server # scan npm package metadata mcp-trust scan ./claude_desktop_config.json # scan a local MCP config mcp-trust scan ./path/to/repo --format json,md,html,sarif ``` **报告输出位置：** 文件将写入 `./reports/.{json,md,html,sarif}` （使用 `--output ` 更改文件夹）。在浏览器中打开 `.html`，或阅读 `.md`。 当检查结果满足 `--fail-on`（默认为 `high`）时，退出代码为非零，因此它可以作为 CI 门禁。

从源码构建（面向贡献者）

``` pnpm install && pnpm build pnpm --filter @mcp-trust/cli dev scan ./fixtures/repos/js-exec --format json,md,sarif ```

## GitHub Action 在每个 pull request 上运行 MCP Trust —— 将 SARIF 上传到 Code Scanning，发布 总结评论，并在超过严重性阈值时使作业失败 (TZ §11)： ``` name: MCP Trust Scan on: [pull_request] jobs: mcp-trust: runs-on: ubuntu-latest permissions: contents: read security-events: write # SARIF upload pull-requests: write # PR comment steps: - uses: actions/checkout@v4 - uses: SteveMonsway/mcp-trust/packages/action@v0.5.0 # or @main with: fail-on: high # low|medium|high|critical upload-sarif: true comment-pr: true ``` 输入：`target`（默认：workspace）、`fail-on`、`output`（`sarif,md,json`）、 `upload-sarif`、`comment-pr`、`no-semgrep`。输出：`decision`、`risk`、`score`、 `sarif-file`、`exceeded`。Action 定义：[`packages/action/action.yml`](packages/action/action.yml)。 ## 公开基准测试 MCP Trust 提供了一个针对 **452 个真实的公开 MCP 服务器**的可复现基准测试 （JavaScript / TypeScript / Python；`registry-seed/seed-targets.yml`）。最新运行结果： **32 BLOCK · 91 NEEDS_REVIEW · 112 APPROVE_WITH_RESTRICTIONS · 217 APPROVE**。 ``` pnpm scan:seed # clone + static + Semgrep for each seed target pnpm reports:public # → public-reports/.{md,html} + index.json ``` 每个目标都会获得一份 Markdown + 独立 HTML 报告；`public-reports/index.json` 是机器可读的索引（每个目标的 decision / risk / score / findings + 运行 摘要）。**BLOCK 是基于 *runtime* 代码的能力证据，而不是恶意软件判定** —— 测试、示例和构建脚本中的发现严重性受到限制，因此它们不会导致 错误的 BLOCK，而 MCP Trust 无法分析的代码（Go、Rust、……）会被标记上 **⚠️ 限制**说明，因此 APPROVE 绝不会被误读为完全无风险的证明。 **浏览报告：** [`public-reports/index.html`](public-reports/index.html)（可搜索/过滤）或 [`public-reports/`](public-reports/README.md)（按服务器 / 公司名称） · 分析文章：[`docs/benchmark.md`](docs/benchmark.md) · 方法论： [`docs/blog/mcp-trust-public-benchmark.md`](docs/blog/mcp-trust-public-benchmark.md)。 ## MCP Trust 检查内容 - **安装/配置风险** —— 未锁定的 `npx`/`uvx`、`curl | sh`、`sudo`、内联 shell、 内嵌 secret、敏感路径、明文 HTTP endpoint、广泛的 home/root 访问权限。 - **代码风险（regex/AST-lite）** —— `child_process.exec`、`execSync`、`eval`/`Function`、 Python `subprocess(shell=True)`/`os.system`、任意文件写入/删除、secret 环境访问。 - **工具/提示元数据（工具投毒）** —— 指令覆盖、隐藏、 数据外泄和针对系统提示的措辞、隐藏/编码内容。 - **能力映射** —— 推断的 filesystem / shell / network / credential 能力， 来自 runtime 内省（可信 fixtures）或静态推断。 - **供应链** —— 缺失仓库、仓库/包不匹配、安装脚本、 配置中的浮动版本、缺失安全策略。 ## MCP Trust **不**做的事情 MCP Trust 是一个**风险评估工具，不能保证**服务器是安全的。它不能 取代代码审查、沙箱隔离、endpoint 安全或供应商风险管理。 设计使然： - 它**绝不**在沙箱之外执行不受信任的代码。在主机上，runtime 内省**仅**针对受信任的 fixture 路径（`fixtures/mcp/…`、 `examples/…`、`mock-mcp-servers/…`）运行；真正的目标**仅**在 Docker 沙箱（`--sandbox docker`，Level 2）内运行。否则，能力映射将以静态方式构建。 - 覆盖范围如实报告 —— 每份报告都会显示评估过和未评估的内容。 ## 评分与决策 单一事实来源位于 `packages/core/src/scoring/thresholds.ts`： | Score | 风险等级 | Decision | |---|---|---| | 0–29 | LOW | APPROVE | | 30–59 | MEDIUM | APPROVE_WITH_RESTRICTIONS | | 60–79 | HIGH | NEEDS_REVIEW | | 80–100 | CRITICAL | BLOCK | 严重性覆盖可以**提高**（绝不会降低）决策 —— 例如，确信的 critical 发现会强制要求 `BLOCK`；`curl | sh` / `sudo` / 内嵌 secret 至少强制要求 `NEEDS_REVIEW`。参见 [docs/scoring.md](docs/scoring.md)。 ## 命令 ``` mcp-trust scan [--format console,json,md,html,sarif] [--output dir] [--fail-on high] \ [--introspect] [--sandbox docker] [--no-semgrep] [--timeout 30s] mcp-trust bench scan [--out dir] # scan a seed list of public servers mcp-trust bench render [--out dir] # render md/html per target + index.json mcp-trust rules list mcp-trust explain mcp-trust version ``` 退出代码：`0` ok · `1` 超出阈值 · `2` 扫描器错误 · `3` 目标错误 · `5` 沙箱失败。 ## 规则 Phase 1 中实现了 30 条规则。有关完整的目录（已实现 + 计划中），请参见 [docs/rule-catalog.md](docs/rule-catalog.md) 。 ## 路线图 以下是简短版本；完整的用户/公司路线图请见 [ROADMAP.md](ROADMAP.md)。 - **Phase 1–4（已完成）：** CLI、30+12 条规则、Docker 沙箱、`@modelcontextprotocol/sdk` 内省、JSON/MD/**HTML**/**SARIF**、GitHub Action，以及 452 个服务器的公开基准测试。 - **下一步（免费）：** 策略文件（`--policy`）、更多语言的规则、npm 发布。 - **未来（付费，团队版）：** 托管 API、控制台、私有/持续扫描、Slack、GitHub App。 ## 开发 ``` pnpm install pnpm build # turbo build all packages pnpm test # vitest (159 tests) pnpm typecheck # tsc --noEmit across packages ``` ## 免责声明 MCP Trust 提供基于证据的风险评估。它不保证服务器是 安全或恶意的。请将结果作为安全审查、沙箱隔离和策略决策的输入。 ## License Apache-2.0。

标签：GitHub Action, GraphQL安全矩阵, LNA, MCP, MITM代理, 后端开发, 安全扫描器, 请求拦截, 错误基检测, 静态代码分析