Ravikiranbantwal/mcpsafe

# MCPSafe [](https://pypi.org/project/mcpsafe/) [](https://www.python.org/) [](LICENSE) []() []() [](https://sarifweb.azurewebsites.net/) MCPSafe 是首个面向 MCP（Model Context Protocol）服务器的开源安全与压力测试框架。通过 stdio 或 HTTP 连接任意 MCP 服务器，即可在一次命令中完成全面审计——包括提示注入、路径遍历、类型混淆、缺少认证、负载行为等。 ## 📖 交互式学习指南 初次接触 MCPSafe 或想了解代码实现？学习指南涵盖了每个模块、攻击类型和代码模式，并配有测验！ 👉 **[打开 MCPSafe 学习指南](https://ravikiranbantwal.github.io/mcpsafe/mcpsafe-learning-guide.html)** *(或本地打开 `mcpsafe-learning-guide.html`，无需互联网即可使用)* ## 为何选择 MCPSafe？ 大多数 MCP 安全工具仅静态分析工具描述。 MCPSafe 会连接正在运行的服务器，并测试**实际运行时行为**。 | 方法 | 工具 | MCPSafe | |---|---|---| | 静态描述分析 | Snyk Agent Scan, Proximity | ✅ 通过 T04 | | 实时对抗载荷测试 | mcpwn | ✅ 通过 T02/T03 | | 负载与并发测试 | Nobody | ✅ 通过 T05 | | 延迟基准测试 | Nobody | ✅ 通过 T08 | | 跨请求数据泄露 | Nobody | ✅ 通过 T05-001 | | JSON Schema 校验 | Nobody | ✅ 通过 T06 | | **反向提示注入（工具输出中毒）** | **Nobody** | **✅ 通过 T09** | | **跨会话数据泄露（多租户数据泄漏）** | **Nobody** | **✅ 通过 T10** | | **时序侧信道枚举** | **Nobody** | **✅ 通过 T11** | | **错误信息密钥泄露（15 种模式）** | **Nobody** | **✅ 通过 T12** | | **服务端采样滥用** | **Nobody** | **✅ 通过 T13** | | **通知洪水 DoS** | **Nobody** | **✅ 通过 T14** | | **并发调用重入（状态泄漏）** | **Nobody** | **✅ 通过 T15** | | **静默能力蔓延** | **Nobody** | **✅ 通过 T16** | | **跨会话 SHA-256 描述漂移** | **Nobody** | **✅ 通过 T17** | | **资源 URI SSRF（10 种载荷）** | **Nobody** | **✅ 通过 T18** | | **Unicode 同形字工具伪装** | **Nobody** | **✅ 通过 T19** | | **服务端内存泄漏检测** | **Nobody** | **✅ 通过 T20** | | SARIF 支持 GitHub 安全面板 | 无（暂未） | ✅ | | 回归对比（Compare） | 无 | ✅ | | 无需账户或 API 密钥 | 仅 mcpwn | ✅ | | 对认证 API 的限速感知节奏控制 | 无 | ✅ | ## 实际测试结果 MCPSafe v0.2.0 已审计 **13 个 MCP 服务器**，包括 Stripe、Cloudflare、GitHub 和 Anthropic 的参考服务器。四个误报已修复，以下为修复后验证结果： - **T02 注入** — IPv4 模式现在仅匹配私有地址范围（10.x、172.16-31.x、192.168.x、127.x、169.254.x）。合法 API 响应中的公网 IP（如 GitHub JSON、时间戳、版本字符串）不再误报。 - **T05 负载** — 连接中断降级从 HIGH 到 MEDIUM（可靠性限制，非安全漏洞）。真实的并发错误仍标记为 HIGH。 - **T09 输出净化** — 通过工具（read_file、git_diff、fetch、search_issues 等）不再扫描 PI 标记，因输出为原始数据。 - **T19 同形字** — 仅当混淆标识符与服务器上现有 ASCII 标识符冲突时才标记 HIGH。 **3,500+ 测试覆盖 20 模块 · 0 个 CRITICAL · 33 个 HIGH · 约 470 个 MEDIUM** | 服务器 | 传输方式 | CRITICAL | HIGH | MEDIUM | 显著发现 | |--------|-----------|:--------:|:----:|:------:|-----------------| | `@modelcontextprotocol/server-everything` | stdio | — | **16** | 71 | 通过 `args-prompt` 存储 PI；`trigger-long-running-operation` 的 INT_MAX 导致 DoS | | `mcp-server-sqlite` *(uvx)* | stdio | — | **14** | 8 | 通过 `mcp-demo` 提示模板存储 PI | | `mcp.stripe.com` *(认证)* 💳 | HTTP | — | — | 170 | `create_refund`、`cancel_subscription` 等均回显注入载荷 | | `mcp-server-fetch` *(uvx)* | stdio | — | 2 | 15 | `fetch` 工具提示注入；100 KB 载荷导致 DoS | | `mcp_text_processor` *(测试)* | stdio | — | 1 | 42 | 100 KB 载荷触发硬性超时 | | `@modelcontextprotocol/server-filesystem` | stdio | — | — | 91 | 路径工具回显注入载荷 | | `@modelcontextprotocol/server-github` *(认证)* | stdio | — | — | 45 | `search_issues` / `search_repositories` 回显注入 | | `mcp-server-git` *(uvx)* | stdio | — | — | ~60 | Git 工具错误信息回显注入载荷 | | `mcp_calculator` *(测试)* | stdio | — | — | 20 | — | | `mcp_notes` *(测试)* | stdio | — | — | 37 | — | | `mcp-server-time` *(uvx)* | stdio | — | — | 14 | — | | `docs.mcp.cloudflare.com` *(认证)* | HTTP | — | — | 2 | — | | `observability.mcp.cloudflare.com` *(认证)* | HTTP | — | — | 1 | — | ### 精选发现 **`@modelcontextprotocol/server-everything`（Anthropic 参考服务器）** — **16 HIGH，0 CRITICAL**。两类漏洞： 1. **存储提示注入** — `args-prompt` 提示模板将原始参数嵌入生成的 LLM 消息，导致 14 个 HIGH。 2. **整数溢出 DoS** — `trigger-long-running-operation` 在 `2147483647`（INT_MAX）与 `1e308`（最大浮点数）时挂起 35 秒以上，确认为资源耗尽 DoS。 **`mcp-server-sqlite`（uvx）** — **14 HIGH**，全部来自 `mcp-demo` 提示模板。原始参数未经净化直接嵌入消息，每个 PI-001..PI-016 载荷都会成为存储在 LLM 上下文中的注入。 **`mcp.stripe.com`（Stripe 支付，生产 HTTP，认证）** — **170 MEDIUM**。Stripe 生产服务器在所有金融工具（`create_refund`、`cancel_subscription`、`create_invoice`、`list_payment_intents` 等）中逐字回显注入载荷。任何消费工具输出的 LLM 均为提示注入攻击面。 **`@modelcontextprotocol/server-filesystem`** — **91 MEDIUM** 注入回显于文件路径工具（`read_file`、`write_file`、`list_directory`）。原始参数字符串传递给系统调用，畸形路径返回的 OS 错误包含原样载荷。 **`@modelcontextprotocol/server-github`** — **45 MEDIUM通过 `search_issues` / `search_repositories` 回显。用户查询字符串被转发给 GitHub API，结果原样返回。LLM 读取输出可能跟随注入指令，但因受 API 响应形状限制，危害低于直接数据泄漏。 **`mcp-server-fetch`（uvx）** — **2 HIGH**：经典提示注入与类型校验崩溃（浮点输入替代整型）。 **`mcp_text_processor`（测试服务器）** — **1 HIGH**：`extract_emails` 在 100 KB 载荷下硬性超时，真实资源耗尽 DoS。 **`observability.mcp.cloudflare.com`（Cloudflare，生产 HTTP，认证）** — **1 MEDIUM**。T04-001 检测到描述增长（1,001 → 1,603 字符），符合 CDN 截断行为，正确归类为 MEDIUM（非故意“地毯式拔毛”）。 ## 快速开始 ``` pip install mcpsafe ``` ``` # 扫描本地 stdio 服务器 mcpsafe scan "uvx mcp-server-git" # 扫描 HTTP 服务器（/mcp 端点自动检测 Streamable HTTP） mcpsafe scan "https://docs.mcp.cloudflare.com/mcp" --transport http # 扫描需要身份验证的 HTTP 服务器 mcpsafe scan "https://observability.mcp.cloudflare.com/mcp" --transport http \ --header "Authorization=Bearer cfat_your_token_here" # 传递多个 HTTP 标头 mcpsafe scan "https://api.example.com/mcp" --transport http \ --header "Authorization=Bearer token" \ --header "X-Org-ID=my-org" # 输出 JSON + HTML + SARIF（所有格式） mcpsafe scan "npx -y @modelcontextprotocol/server-filesystem /tmp" --output all # 传递子进程环境变量（仅 stdio 服务器） mcpsafe scan "uvx mcp-server-github" --env GITHUB_TOKEN=ghp_xxx # 生成配置文件 mcpsafe init # 比较两次扫描以跟踪回归 mcpsafe compare report-v1.json report-v2.json ``` ## 测试内容 MCPSafe v0.2.0 在 **20 模块** 上运行 **200+** 测试类型，涵盖发现、安全、性能与 Schema 校验。 ### 核心模块（T01–T08）——基础能力 | 模块 | 类别 | 检查内容 | |--------|----------|----------------| | **T01** 发现 | DISCOVERY | 服务器枚举、工具列表、资源/提示暴露、元数据一致性 | | **T02** 注入 | SECURITY | 每个字符串参数 16 种提示注入载荷——经典覆盖、SQL 探针、Shell 元字符、Unicode RLO、路径遍历、Jinja/Python 格式注入 | | **T03** 模糊器 | SECURITY | 类型混淆、边界值、超大载荷、深度嵌套、NaN/Infinity 在各参数中的处理 | | **T04** 工具中毒 | SECURITY | 工具描述变更（地毯式拔毛攻击）、基准漂移、隐藏指令。仅增长性变更被降级为 MEDIUM，避免 CDN 截断误报 | | **T05** 负载 | PERFORMANCE | 并发调用（10/50/100）、跨请求 UUID 泄漏检测、重连稳定性 | | **T06** 架构 | SCHEMA | JSON Schema 校验、必填字段强制、描述质量评分 | | **T07** 认证 | SECURITY | 缺失认证、Bearer 绕过、协议版本滥用、重放攻击、同形字工具名伪造 | | **T08** 延迟 | PERFORMANCE | 基准延迟、P95/P99 百分位、冷启动检测、负载后降级 | ### v0.2.0 新增（T09–T20）——高级攻击面 这些功能在其他 MCP 安全工具中尚不存在： | 模块 | 类别 | 检查内容 | |--------|----------|----------------| | **T09** 输出净化 | SECURITY | **反向提示注入** — 扫描**工具输出**中的 PI 标记，避免污染后续 LLM 调用。跳过 pass-through 工具（文件/差异/获取/搜索）以免误报 | | **T10** 跨会话泄漏 | SECURITY | 在会话 A 植入唯一标记，在独立会话 B 检查是否可见——检测共享缓存/全局状态的多租户失效 | | **T11** 时序侧信道 | SECURITY | 统计合理与随机输入的时序差异，采用修剪均值 + 5 倍比率 + 30 ms 绝对阈值，避免抖动误报 | | **T12** 错误密钥泄露 | SECURITY | 触发畸形参数错误路径，扫描 15 种密钥模式：AWS/GitHub/OpenAI/Anthropic/Stripe 密钥、JWT、Bearer 令牌、DB URI、`/etc/passwd`、环境变量、私有 IP | | **T13** 采样滥用 | SECURITY | 审计 `sampling` 能力声明，并检测工具执行期间未请求的客户端→服务端采样请求 | | **T14** 通知洪水 | SECURITY | 监控 5 秒静默窗口内的通知频率，>5/秒标 MEDIUM，>30 总数标 HIGH——客户端 DoS | | **T15** 重入 | SECURITY | 6 个并发调用携带唯一标记；若响应包含调用者未发送的标记，则判定为共享状态漏洞 | | **T16** 能力蔓延 | SECURITY | 在 T=0 与 T=3 秒分别拍摄工具/资源/提示/能力快照，任何静默增删均告警 | | **T17** Hash 漂移 | SECURITY | 对每个工具/资源/提示描述计算 SHA-256，指纹跨两独立会话比对——捕获每次连接 A/B 测试（地毯式拔毛前兆） | | **T18** 资源 URI SSRF | SECURITY | 向 `read_resource` 传入 10 个恶意 URI：AWS/GCP/Azure 元数据、`file://`、回连（Redis/Elasticsearch）、SSH 密钥、DNS 重绑定探测 | | **T19** Unicode 同形字 | SECURITY | 同形字符（Cyrillic/Greek/全角）、混合脚本、隐形控制符。仅在名称坍缩为已有 ASCII 标识符时标记 HIGH，避免合法国际化误报 | | **T20** 内存泄漏 | PERFORMANCE | 40 次调用探针；修剪四分位响应尺寸与延迟漂移分析 + 子进程 RSS 增长（stdio + psutil） | ### 真实漏洞案例 **存储提示注入（工具输出污染）**（T02、T09）——每个字符串参数经过 16 种攻击载荷（PI-001..PI-016）测试。若载荷在响应中**原样出现**，即判定为漏洞。已在 **server-everything、sqlite、server-filesystem、server-github、mcp-server-git、mcp.stripe.com** 中确认。 **提示模板注入（存储 PI）**（T02、T09）——如 `args-prompt`（server-everything）与 `mcp-demo`（sqlite）将原始参数嵌入提示消息。**每服务器 14–16 个 HIGH**，所有载荷均进入 LLM 上下文。 **工具描述“地毯式拔毛”攻击**（T04，由 Invariant Labs 2025 披露）——工具描述在 `list_tools()` 调用间静默变更。增长性变更被正确降级为 MEDIUM，避免 CDN 截断误报。 **DoS 通过整数溢出**（T03）——在 Anthropic 的 `trigger-long-running-operation` 中确认：INT_MAX（2,147,483,647）与 `1e308` 导致 35 秒以上挂起。 **跨请求数据泄露（并发）**（T05-001）——在 10 次并发调用中嵌入唯一 UUID；若 A 的响应包含 B 的 UUID，即判定为共享状态泄漏。与 MCP TypeScript SDK CVE 同级（CVSS 7.1）。 **SSRF 通过资源 URI**（T18）——向 `read_resource` 传入 `file:///etc/passwd`、AWS 元数据 `169.254.169.254` 等 10 个恶意 URI。**当响应内容匹配文件/元数据格式时为 CRITICAL**。 **错误信息密钥泄漏**（T12）——捕获将数据库连接串、密钥、JWT 等 15 种模式泄露到异常消息中的服务器。正则库含值脱敏。 ### T03 模糊器——模糊测试语料库 - **字符串攻击**：空字节、超长 Unicode、ANSI 转义、格式字符串（`%s %n`）、1 MB 载荷 - **整数边界**：`MAX_INT32+1`、`MIN_INT32-1`、超出 int64（`9_223_372_036_854_775_808`）、零、负数 - **类型混淆**：字符串替代整数（`"NaN"`、`"Infinity"`、`"-1"`）、槽位中的对象 - **数组攻击**：10,000 元素数组、混合类型数组（1,000 元素）、100 层嵌套数组 - **数字边界**：`"NaN"`、`"Infinity"`、`"-Infinity"`、`1e308`（溢出）、`1e-308`（下溢） - **对象攻击**：深度嵌套对象、冲突键、意外额外 ### T07 认证——认证与协议测试 缺失认证检测、Bearer 令牌绕过、API 密钥滥用、JWT none 算法攻击、OAuth 权限提升、会话令牌固定、速率限制检测（429/限流/节流）、所有已知 MCP 版本协议滥用（`2024-11-05`、`2024-10-07`、`2025-03-26`）、重复 `initialize()` 重放与运行状况检查、同形字工具名伪造。 ### T06 架构——描述质量评分 包含**描述质量**检查（T06-006），对工具描述进行 LLM 可用性评分： | 结果 | 严重性 | |--------|----------| | 无描述 | MEDIUM | | 无用描述（“A tool”, “Does stuff”） | MEDIUM | | 描述少于 30 字符 | LOW | | 未记录参数 | LOW | | 全部描述合格 | PASS | ## CLI 参考 ### `mcpsafe scan` ``` Usage: mcpsafe scan [OPTIONS] TARGET Options: --transport TEXT Transport type: stdio | http [default: stdio] --output TEXT Report format: json | html | sarif | all [default: json] --timeout INT Per-call timeout in seconds [default: 30] --modules TEXT Comma-separated module IDs (e.g. T01,T02,T07) --env TEXT KEY=VALUE subprocess env var, stdio only (repeatable) --header TEXT KEY=VALUE HTTP request header, http transport (repeatable) --config PATH Path to mcpsafe.toml config file --out-dir PATH Directory for output reports [default: ./mcpsafe-reports] --no-load Skip T05-003 stress test and large injection payloads --verbose Print full details for every finding as they are found ``` **`--header` 与 `--env`** — 使用 `--header` 传递 HTTP 请求头（Authorization、API 密钥）用于扫描 HTTP/HTTPS MCP 服务器；使用 `--env` 为 stdio 服务器设置子进程环境变量（读取凭证）。 **HTTP 传输自动探测** — MCPSafe 根据 URL 自动选择合适 HTTP 客户端。以 `/mcp` 结尾的 URL 使用 MCP Streamable HTTP 协议（Cloudflare 及新版服务器必需）；以 `/sse` 结尾使用旧版 SSE 协议；其他情况追加 `/mcp` 并优先尝试 Streamable HTTP。 ### `mcpsafe init` 生成带全部选项说明的注释式 `mcpsafe.toml` 配置文件。 ``` mcpsafe init # writes mcpsafe.toml in current directory mcpsafe init --output /path/to/dir # write to specific path mcpsafe init --force # overwrite existing file ``` MCPSafe 会在 `mcpsafe.toml` 包含敏感键名（token、secret、key、password、api_key）时发出警告，并检查 Unix 文件权限（建议 `chmod 600`）。 ### `mcpsafe compare` 对比两份 JSON 报告，突出新增发现与回归问题。 ``` mcpsafe compare baseline.json latest.json ``` ### `mcpsafe list-modules` 列出所有可用测试模块及其测试 ID。 ### `mcpsafe version` 打印 MCPSafe 版本后退出。 ## 输出格式 ### JSON 结构化报告，包含全部发现、服务器元数据与统计摘要。所有服务器返回的字符串在序列化前均经过净化（NUL 字节、ANSI 转义、控制字符去除）。 ``` { "scan_id": "a1b2c3d4-...", "mcpsafe_version": "0.2.0", "started_at": "2026-04-14T10:23:45Z", "server_info": { "name": "mcp-server-git", "protocol_version": "2024-11-05", "tool_count": 12 }, "summary": { "total_tests": 607, "passed": 534, "failed": 73, "overall_severity": "MEDIUM" }, "results": [ { "test_id": "T02-001", "severity": "MEDIUM", "description": "..." } ] } ``` ### HTML 自包含单文件报告（无 CDN 依赖），含严重性环形图、各分类发现表，深色/浅色主题设计，适合向利益相关者分享或附加到 GitHub 问题。 ### SARIF 2.1.0 兼容 GitHub 安全面板。非 PASS 结果以 SARIF 形式输出。 | MCPSafe 严重性 | SARIF 级别 | |:----------------:|:-----------:| | CRITICAL / HIGH | `error` | | MEDIUM | `warning` | | LOW / INFO | `note` | | PASS | （省略） | **GitHub Actions 集成：** ``` - name: Scan MCP server run: mcpsafe scan --transport stdio --target "uvx mcp-server-git" --output sarif --out-dir sarif-output - name: Upload SARIF to GitHub Security uses: github/codeql-action/upload-sarif@v3 with: sarif_file: sarif-output/ ``` ## CI/CD 集成 检测到 CRITICAL 或 HIGH 时，MCPSafe 退出码为 `1`，可直接作为流水线门禁。 ``` # .github/workflows/mcp-security.yml name: MCP Security Scan on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install MCPSafe run: pip install mcpsafe - name: Scan MCP server run: | mcpsafe scan \ --transport stdio \ --target "uvx mcp-server-git" \ --output all \ --out-dir ./mcpsafe-output - name: Upload SARIF to GitHub Security uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: ./mcpsafe-output/ - name: Upload HTML report uses: actions/upload-artifact@v4 if: always() with: name: mcpsafe-report path: ./mcpsafe-output/*.html ``` ## 终端输出示例 ``` ╭─────────────────────────────────────────────╮ │ MCPSafe v0.2.0 │ │ MCP Server Security & Stress Tester │ ╰─────────────────────────────────────────────╯ Target: uvx mcp-server-git --repository . Transport: stdio Server: mcp-server-git (protocol 2024-11-05) Tools: 12 Resources: 0 Prompts: 0 Running 20 modules (600+ tests)... ✓ T01 Discovery 100% 0:00:00 ✓ T08 Latency Baseline 100% 0:00:00 ✓ T06 Schema 100% 0:00:00 ⚠ T02 Injection 100% 0:00:15 [MEDIUM] ⚠ T03 Fuzzer 100% 0:00:15 [MEDIUM] ✓ T04 Tool Poison 100% 0:00:13 ✓ T09 Output Sanitization 100% 0:00:06 ✓ T12 Error Secret Leakage 100% 0:00:14 ✓ T13 Sampling Abuse 100% 0:00:07 ⚠ T16 Capability Creep 100% 0:00:14 [MEDIUM] ✓ T18 SSRF 100% 0:00:00 ✓ T19 Homoglyph 100% 0:00:00 ⚠ T07 Auth 100% 0:00:08 [LOW] ✓ T11 Timing Side-Channel 100% 0:00:00 ✓ T15 Reentrancy 100% 0:00:00 ⚠ T05 Load 100% 0:00:13 [MEDIUM] ✓ T10 Cross-Session Leakage 100% 0:00:01 ✓ T17 Hash Drift 100% 0:00:01 ✓ T14 Notification Flood 100% 0:00:05 ✓ T20 Memory Leak 100% 0:00:00 ✓ T08-005 Latency Comparison 100% 0:00:00 ┌──────────┬───────┐ │ CRITICAL │ 0 │ │ HIGH │ 0 │ │ MEDIUM │ 60 │ │ LOW │ 10 │ │ INFO │ 18 │ │ PASS │ 534 │ └──────────┴───────┘ Reports saved: JSON → ./mcpsafe-reports/mcpsafe-git-20260414-091438.json HTML → ./mcpsafe-reports/mcpsafe-git-20260414-091438.html SARIF → ./mcpsafe-reports/mcpsafe-git-20260414-091438.sarif Exit 0 — no CRITICAL or HIGH findings. ``` ## 架构设计 ``` mcpsafe/ ├── cli.py # click CLI: scan, init, compare, list-modules, version ├── runner.py # async orchestration, module dispatch, rich progress ├── transport.py # MCP connection factory (stdio / HTTP, async context managers) ├── models.py # dataclasses: TestResult, ScanReport, ServerInfo, Severity, Category ├── tests/ │ ├── _helpers.py # RateLimiter, SECRET_PATTERNS, cap_response, sanitise_server_string │ ├── t01_discovery.py # T01 — capability enumeration │ ├── t02_injection.py # T02 — prompt injection payloads │ ├── t03_fuzzer.py # T03 — malformed input fuzzing │ ├── t04_tool_poison.py # T04 — rug-pull mutation detection │ ├── t05_load.py # T05 — load / concurrency / UUID leakage │ ├── t06_schema.py # T06 — JSON Schema validation │ ├── t07_auth.py # T07 — auth / protocol / replay tests │ ├── t08_latency.py # T08 — latency benchmarks │ ├── t09_output_sanitization.py # T09 — reverse PI detection ✨ v0.2.0 │ ├── t10_cross_session.py # T10 — cross-session data leakage ✨ │ ├── t11_timing_side_channel.py # T11 — timing enumeration oracles ✨ │ ├── t12_secret_leakage.py # T12 — 15 secret patterns in errors ✨ │ ├── t13_sampling_abuse.py # T13 — server-initiated sampling ✨ │ ├── t14_notification_flood.py # T14 — client-side DoS ✨ │ ├── t15_reentrancy.py # T15 — concurrent-call state bleed ✨ │ ├── t16_capability_creep.py # T16 — silent inventory drift ✨ │ ├── t17_hash_drift.py # T17 — SHA-256 cross-session fingerprints ✨ │ ├── t18_ssrf.py # T18 — resource URI SSRF (10 payloads) ✨ │ ├── t19_homoglyph.py # T19 — Unicode confusables ✨ │ └── t20_memory_leak.py # T20 — RSS / latency / size drift ✨ └── reporter/ ├── _common.py # canonical server_slug() used by all reporters ├── json_reporter.py ├── html_reporter.py └── sarif_reporter.py templates/ └── report.html.j2 ``` **设计原则：** - 所有 I/O 使用 `async/await` —— 无阻塞事件循环调用 - 每个测试返回 `TestResult` 数据类 —— 无原始字典跨模块传递 - 所有 MCP 调用包裹在 `try/except` 中 —— 无测试可崩溃运行器 - 始终以毫秒级精度测量时间（`time.perf_counter()`） - 服务器返回的字符串在所有输出边界（终端、JSON、HTML、SARIF）均经过净化 ## MCPSafe 自身安全加固 MCPSafe 采用与所测服务器相同的攻击类别进行防护： **富格式标记注入预防** — 服务器返回字符串在嵌入终端前通过 `rich.markup.escape()` 处理，防止恶意服务器注入标记。 **不可变测试结果** — `HtmlReporter` 使用 `dataclasses.replace()` 创建 `TestResult` 对象的净化副本而非直接修改。源 `ScanReport` 永不变更，确保连续生成的 JSON 与 HTML 报告一致。 **递归 JSON 净化** — `JsonReporter` 在 `json.dumps()` 前应用 `_sanitise_value()`（深度上限 10）。来自不可信服务器的 NUL 字节、ANSI 转义与控制字符无法破坏 SIEM 解析器或日志聚合器。 **每次扫描状态隔离** — `t08_latency.py` 在每次扫描开始时清空模块级 `_baseline_latencies` 字典，防止前次运行的时序数据泄漏到后续扫描。 **配置凭证警告** — `mcpsafe init` 会在 `mcpsafe.toml` 包含敏感模式键时提醒，并检查 Unix 文件权限。 **输入校验** — `--timeout` 与 `--concurrency` 在扫描前校验；`mcpsafe compare` 使用防御式 `_load_report()` 辅助函数，在展示前校验 JSON 结构、必需键与类型。 ## 选项参考 | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `--transport` | `stdio` | 传输协议：`stdio`、`http` | | `--output` | `json` | 报告格式：`json`、`html`、`sarif`、`all` | | `--modules` | all | 逗号分隔的模块 ID 列表 | | `--out-dir` | `./mcpsafe-reports` | 报告输出目录 | | `--timeout` | `30` | 每次 MCP 调用超时秒数 | | `--header` | — | `KEY=VALUE` HTTP 请求头（仅 HTTP 传输，可重复） | | `--env` | — | 子进程环境变量（仅 stdio 传输，可重复） | | `--config` | — | `mcpsafe.toml` 路径 | | `--no-load` | `false` | 跳过 T05-003 压力测试与大型载荷 | | `--verbose` | `false` | 发现时即时打印 | ## 严重性等级 | 级别 | 含义 | |---|---| | **CRITICAL** | 可被利用——应阻止部署 | | **HIGH** | 严重——需及时修复 | | **MEDIUM** | 潜在漏洞——应调查 | | **LOW** | 最佳实践偏差或信息性弱点 | | **INFO** | 中性观察（如预期限流、需认证） | | **PASS** | 测试通过——无问题 | ## 开发 ``` git clone https://github.com/Ravikiranbantwal/mcpsafe cd mcpsafe pip install -e ".[dev]" # 运行单元测试 pytest tests/ -v # 针对真实服务器运行 mcpsafe scan "uvx mcp-server-git" --verbose ``` ### 添加测试模块 1. 创建 `mcpsafe/tests/t21_yourmodule.py`（编号在 T20 之后） 2. 实现 `async def run(session, server_info, config) -> list[TestResult]` 3. 在 `mcpsafe/runner.py` 注册（导入块与执行计划） 4. 使用测试 ID 格式 `T21-001`、`T21-002`…… 5. 返回 `TestResult` 数据类——绝不抛出异常；全部捕获并用 `TestResult.from_exception()` 包装 6. 若模块需要针对认证网关的速率限制，请使用 `RateLimiter(config)`（来自 `mcpsafe.tests._helpers`） ## 贡献 欢迎提交 Pull Request。在实现新测试模块前请先打开 Issue。 - 每个公共函数需包含文档字符串与类型提示 - 所有 MCP 调用必须包裹在 `try/except` 中——绝不让测试崩溃运行器 - 运行 `pytest tests/` 后再提交 ## 法律与负责任使用 负责任地使用 MCPSafe： - 仅扫描您拥有、运营或已获授权的服务器 - 不得在未获操作者同意的情况下扫描生产服务 - 将所有发现视为机密，直至披露给服务器操作者 ## 许可证 Polyform Noncommercial License 1.0.0**——免费用于个人使用、学术研究、开源项目与非营利安全工作。商业使用（付费审计、SaaS 等）需另行授权。

标签：GitHub Security, JSON Schema 验证, MCP 安全, MCP 安全框架, SARIF, T02, T03, T05, T06, T08, T09, T10, 动态测试, 后端开发, 安全压力测试, 安全规则引擎, 对抗性测试, 并发测试, 延迟测试, 提示注入, 模型上下文协议, 计算机取证, 认证绕过, 负载测试, 跨请求数据泄露, 运行时安全测试, 逆向工具, 集群管理, 静态分析对比