MCPGuard-Lab

一个基于真实 mcp==2.0.0 SDK 的 MCP 工具调用安全实验项目。它不依赖外部大模型或 API Key，通过确定性策略完成工具白名单、参数校验、文件边界、SSRF 防护、敏感操作确认、输出脱敏、工具描述投毒检测和 JSONL 审计，并用回归用例验证防护没有被后续改动破坏。

使用边界：本项目仅用于本地实验、授权测试和防御研究，不包含面向未授权目标的攻击功能。

已实现能力

• MCP 2.0 stdio 服务端与真实客户端往返测试。
• 六个演示工具：安全计算、根目录内文件读取、笔记查询、公开 URL 请求、工具元数据检查、确认后写笔记。
• 工具白名单与 JSON Schema 严格校验，拒绝额外参数。
• 文件路径规范化，拒绝绝对路径、目录穿越和根目录逃逸。
• URL 协议、用户信息、端口、DNS 解析结果检查，拒绝回环、私网、链路本地等非公网地址。
• 写操作 confirmed=true 门禁。
• 不可信工具输出显式打标；密码、Token、API Key 与 Bearer 凭据递归脱敏。
• 工具名称/描述中的高风险提示注入信号检测。
• 每次决策写入 JSONL：请求 ID、时间、工具、参数、允许/拒绝、原因和结果。
• pytest 单元/集成测试和可重复的攻击回归报告。

架构

MCP Client
   │ stdio / MCP 2.0
   ▼
MCP Server ──► GuardedGateway ──► PolicyEngine
                      │                 ├─ allowlist + schema
                      │                 ├─ path boundary
                      │                 ├─ URL / SSRF
                      │                 └─ confirmation
                      ├─ Tool handler
                      ├─ untrusted labeling + redaction
                      └─ JSONL audit

核心原则是“先决策、后执行、再净化输出、全程留痕”。提示词文本不会直接获得额外权限，权限以代码中的白名单和策略为准。

快速运行（Windows）

py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m mcpguard.regression

也可以直接运行：

powershell -ExecutionPolicy Bypass -File .\scripts\verify.ps1

报告会生成在：

• reports/regression-report.md
• reports/regression-report.json
• reports/regression-audit.jsonl

MCP 客户端配置示例

先执行 pip install -e .，再把以下结构换成当前仓库绝对路径：

{
  "mcpServers": {
    "mcpguard-lab": {
      "command": "D:/path/to/mcpguard-lab/.venv/Scripts/python.exe",
      "args": ["-m", "mcpguard.server"],
      "env": {
        "MCPGUARD_WORKSPACE": "D:/path/to/mcpguard-lab/fixtures/workspace",
        "MCPGUARD_NOTES": "D:/path/to/mcpguard-lab/fixtures/workspace/notes",
        "MCPGUARD_AUDIT": "D:/path/to/mcpguard-lab/reports/audit.jsonl"
      }
    }
  }
}

真实边界

• 工具描述投毒检测是高信号规则层，不能代替人工审查和固定白名单。
• confirmed=true 是本地实验中的显式确认门禁；生产环境应使用由宿主 UI/身份系统签发、不可由模型自行伪造的确认凭证。
• URL 工具当前禁用重定向，避免首跳通过检查后跳向内网；生产版还应限制响应大小、内容类型和出口网络。
• 不可信内容打标能降低“数据被当指令”的风险，但最终宿主 Agent 仍需遵循信任边界。
• 回归数据只代表仓库内固定用例，不代表可以阻断所有提示注入或所有 MCP 风险。

目录

src/mcpguard/       核心实现
tests/              单元测试与真实 MCP stdio 集成测试
fixtures/           可公开的本地测试数据
reports/            自动生成的测试和审计证据
scripts/verify.ps1  一键验证入口

参考

• Model Context Protocol Python SDK
• AgentDojo