aak204/MCP-Trust-Kit

# MCP Trust Kit [](https://github.com/aak204/MCP-Trust-Kit/actions/workflows/ci.yml) [](https://github.com/aak204/MCP-Trust-Kit/releases) [](LICENSE) [](https://www.python.org/downloads/)  **面向 MCP 服务器的确定性表面风险评估。** `MCP Trust Kit` 通过 `stdio` 扫描本地 MCP 服务器，发现其工具，运行确定性 检查以评估协议和工具规范，以及暴露的高风险能力，计算出 `0..100` 的 分数，并输出可完美融入 CI 流程的终端、JSON 和 SARIF 格式结果。JSON 和 SARIF 包含一个显式的 `scan_timestamp` 字段供下游消费者使用。 **MCP Trust Kit 评估的是表面风险，而非业务意图。** 低分意味着暴露的工具接口值得审查。这并不代表服务器是恶意的。 高分意味着确定性发现较少。这并不代表服务器是安全的。 ## 为什么需要它 MCP 服务器向 agent 暴露工具。这使得在采用之前有两个问题值得自动化评估： - 服务器的元数据和 schema 接口是否足够清晰以供审查？ - 服务器是否暴露了具有高破坏范围（blast radius）的能力？ `MCP Trust Kit` 的定位非常明确。它不是一个安全平台、网关、托管 服务或认证机构。它是一个具有稳定输出的确定性扫描器。 ## 检查内容 目前，扫描器会对两大类问题进行扣分： - 协议和工具规范 重复的工具名称、缺失的描述、模糊的描述、薄弱的 schema、缺失的 schema 类型、任意的顶级属性、可选的关键字段 - 暴露的高风险能力 命令执行、文件系统修改、网络请求原语、下载并执行模式 它**不会**对以下内容评分： - 业务意图 - 运行时隔离和部署控制 - MCP 服务器接口之外的人工审批流程 - 可利用性声明 ## 本地快速开始 扫描内置的不安全演示服务器： ``` python -m venv .venv source .venv/bin/activate pip install -e .[dev] mcp-trust scan --cmd python examples/insecure-server/server.py ``` 生成 JSON 和 SARIF 并执行分数阈值检查： ``` mcp-trust scan \ --min-score 80 \ --json-out mcp-trust-report.json \ --sarif mcp-trust-report.sarif \ --cmd python examples/insecure-server/server.py ``` 扫描器直接启动 `--cmd`，无需通过 shell。在实际操作中，这意味着 `python`、`npx`、 `uvx` 或编译好的二进制文件都可以正常工作，只要您传入真实的可执行文件名和参数即可。

Windows (PowerShell)

``` python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -e .[dev] .\.venv\Scripts\mcp-trust scan --cmd .\.venv\Scripts\python examples\insecure-server\server.py ```

## 运行真实的 MCP 服务器 经过验证的示例记录在 [docs/validated-servers.md](docs/validated-servers.md) 中。 相对安全的公开示例： ``` mcp-trust scan --cmd npx -y @modelcontextprotocol/server-memory@2026.1.26 ``` 高风险但合法的公开示例： ``` mkdir -p .tmp-mcp-fs mcp-trust scan --cmd npx -y @modelcontextprotocol/server-filesystem@2026.1.14 .tmp-mcp-fs ``` 在 Windows 上，如有需要请使用 `npx.cmd` 代替 `npx`。 ## GitHub Actions 快速开始 将此工作流放入您的仓库中： ``` name: MCP Trust Scan on: pull_request: workflow_dispatch: permissions: contents: read security-events: write jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Run MCP Trust Kit uses: aak204/MCP-Trust-Kit@v0.5.0 with: cmd: python path/to/your/server.py min-score: "80" json-out: mcp-trust-report.json sarif-out: mcp-trust-report.sarif - name: Upload SARIF if: always() uses: github/codeql-action/upload-sarif@v3 with: sarif_file: mcp-trust-report.sarif ``` 此操作将在以下情况失败： - 扫描在技术上失败时 - 最终分数低于 `min-score` 时 如果 `v0.5.0` 标签尚未发布，请在私下测试时使用分支名称或 commit SHA。 ## 示例输出 [`examples/insecure-server`](examples/insecure-server/README.md) 的当前输出： ``` Server: Insecure Demo Server Version: 0.1.0 Protocol: 2025-11-25 Target: stdio:[".\\.venv\\Scripts\\python","examples\\insecure-server\\server.py"] Tools: 4 Findings: 7 Severity: error=2, warning=5, info=0 Total Score: 10/100 Score Meaning: Deterministic surface-risk score based on protocol/tool hygiene and risky exposed capabilities. Why This Score: Score is driven mainly by detected command execution and file system issues. High-Risk Capabilities: command execution, file system, external side effects Review First: write_file, exec_command, debug_payload, do_it Category Scores: - spec: 60/100 (penalties: 40) - auth: 100/100 (penalties: 0) - secrets: 100/100 (penalties: 0) - tool_surface: 50/100 (penalties: 50) Top Findings: - ERROR dangerous_exec_tool [exec_command]: Tool 'exec_command' appears to expose host command execution. - ERROR dangerous_fs_write_tool [write_file]: Tool 'write_file' appears to provide filesystem write access. - WARNING schema_allows_arbitrary_properties [debug_payload]: Tool 'debug_payload' allows arbitrary additional input properties. - WARNING weak_input_schema [debug_payload]: Tool 'debug_payload' exposes a weak input schema that leaves free-form input underconstrained. - WARNING overly_generic_tool_name [do_it]: Tool 'do_it' uses an overly generic name that hides its behavior. Score Limits: - Low score means higher exposed surface risk, not malicious intent. - High score means fewer deterministic findings, not a guarantee of safety. ``` 由当前扫描器生成的示例启动产物： - [sample-reports/insecure-server.report.json](sample-reports/insecure-server.report.json) - [sample-reports/insecure-server.report.sarif](sample-reports/insecure-server.report.sarif) - [sample-reports/insecure-server.terminal.md](sample-reports/insecure-server.terminal.md) ## 规则类别 评分模型目前暴露了四个顶级评分维度： - `spec` - `auth` - `secrets` - `tool_surface` 发现本身也被分组为感知能力的风险类别： - `metadata_hygiene` - `schema_hygiene` - `command_execution` - `file_system` - `network` - `external_side_effects` 当前的确定性规则： - `duplicate_tool_names` - `missing_tool_description` - `overly_generic_tool_name` - `vague_tool_description` - `missing_schema_type` - `schema_allows_arbitrary_properties` - `weak_input_schema` - `missing_required_for_critical_fields` - `dangerous_exec_tool` - `dangerous_shell_download_exec` - `dangerous_fs_write_tool` - `dangerous_fs_delete_tool` - `dangerous_http_request_tool` - `dangerous_network_tool` - `write_tool_without_scope_hint` - `tool_description_mentions_destructive_access` ## 评分 评分模型旨在保持简单且可预测： 1. 从 `100` 开始 2. 对发现的问题扣除固定罚分 3. 限制在 `0..100` 范围内 4. 以相同方式计算类别分数 `v0.5.0` 中的严重性映射： | 严重性 | 罚分 | | --- | --- | | `info` | `0` | | `warning` | `10` | | `error` | `20` | 该分数旨在具有可审查性、稳定性，并且便于在 CI 中进行推理。 ## 在真实 MCP 服务器上的验证 验证日期：`2026-03-29` | 服务器 | 来源 | 结果 | 备注 | | --- | --- | --- | --- | | `examples/insecure-server` | 本地演示 | `10/100` | 故意设置为高风险的确定性夹具 | | `@modelcontextprotocol/server-memory@2026.1.26` | 官方公开包 | `100/100` | 在当前的确定性规则下没有发现问题 | | `@modelcontextprotocol/server-filesystem@2026.1.14` | 官方公开包 | `40/100` | 合法的文件系统修改接口被标记为高风险 | 命令、注意事项和发现： - [docs/validated-servers.md](docs/validated-servers.md) ## 架构 ``` stdio transport -> normalization -> rules registry -> scoring engine -> terminal / JSON / SARIF ``` 更多细节： - [docs/architecture.md](docs/architecture.md) ## 示例与文档 - [examples/insecure-server/README.md](examples/insecure-server/README.md) - [examples/fake_stdio_server.py](examples/fake_stdio_server.py) - [docs/validated-servers.md](docs/validated-servers.md) - [docs/architecture.md](docs/architecture.md) - [docs/assets/filesystem-scan-hero.svg](docs/assets/filesystem-scan-hero.svg) - [.github/workflows/example.yml](.github/workflows/example.yml) ## 生态系统与互补工具 `MCP Trust Kit` 被设计为**第 1 层（静态风险）**扫描器。为了构建完整的 Agentic DevSecOps 流水线，我们建议将其与运行时可观测性工具配合使用： * [**Veridict**](https://github.com/xkumakichi/veridict)（第 2 层 - 运行时信任）：一个轻量级中间件，用于记录实际工具执行情况，并根据真实执行历史给出信任判定。如果说 MCP Trust Kit 回答的是“其破坏范围在结构上是否安全？”，那么 Veridict 回答的则是“该服务器在生产环境中是否真的可靠？”。 ## 路线图 `v0.5.0` 之后的短期工作： - 扩展针对 `auth` 和 `secrets` 的确定性规则 - 在存在源码上下文时改进 SARIF 位置映射 - 添加更多真实世界的验证案例和示例报告 - 在当前评分范围保持稳定后，添加更多传输选项 不在近期规划内的内容： - 核心引擎中基于 LLM 的评分 - 托管扫描 - 发布流程中的注册表集成 - 认证式的声明 ## 许可证 Apache-2.0。详见 [LICENSE](LICENSE)。

标签：DLL 劫持, MCP, MCP服务器, Python, SARIF, 云安全监控, 代码安全扫描, 协议安全性, 反取证, 大模型安全, 大语言模型, 安全合规, 安全评估, 攻击面评估, 无后门, 模型上下文协议, 确定性扫描, 网络代理, 表面风险, 静态分析, 风险扫描, 风险评分