leagames0221-sys/mcp-guard

# mcp-guard [](LICENSE) [](https://github.com/leagames0221-sys/mcp-guard/actions/workflows/ci.yml) [](https://nodejs.org/) [](#selected-under) [](#selected-under) [](#selected-under) [](#selected-under) ## 入选条件 本仓库专门演示了：MCP server 扫描器 + 配合 Ollama (`gemma3:4b`) 默认使用的 prompt-injection 测试套件、CI 中的确定性 mock 回退，以及通过 6 层防御（构造器门控 + 预检预留 + 密钥防泄漏 + CI 自动调用禁止 + 默认 mock + 仅限零信用卡服务）进行环境变量限制的付费 LLM。 **通俗总结** *(面向非专业读者)* - **MCP (Model Context Protocol)** — 一项新兴标准，允许 AI agent 调用外部工具和数据源（由 Anthropic 发起，现已支持多供应商）。配置不当的 MCP server 可能会泄露机密、执行注入的命令，或被用作 SSRF 跳板。 - **Prompt-injection 测试套件** — 一系列精心构造的输入，试图通过越狱（jailbreak）让语言模型泄露数据或无视其指令。我们提供了一个经过净化处理的 OWASP LLM Top 10 (2025) 语料库，并针对您的本地 LLM 测量拒绝率、无泄漏率和安全完成率。 - **修复引擎** — 针对每项发现，输出建议的配置补丁以及精选的 OWASP / CWE 参考资料，使开发者无需重新阅读底层标准即可修复问题。 - **为何重要** — MCP 正在成为 AI 工具的事实上的集成层，但其安全态势却相对滞后。`mcp-guard` 能够在攻击者之前捕获最常见的部署错误。 ## 功能简介 `mcp-guard` 是一款开发者优先的 CLI 工具，它接收 Model Context Protocol 配置（`.mcp.json` 或兼容文件），报告跨四个扫描器类别的安全发现，针对本地 LLM 运行 OWASP LLM Top 10 prompt-injection 测试套件，并以机器可读的 JSON 格式输出针对每项发现的修复建议。 | 攻击面 | 子命令 | 输出 | |---|---|---| | MCP 配置扫描器 (F-001) | `mcp-guard scan ` | 控制台 / JSON / SARIF — SSRF、命令注入、身份验证缺口、供应链 | | Prompt-injection 测试套件 (F-002) | `mcp-guard inject` | JSON — 针对内置 OWASP LLM01–10 语料库的逐项探针判定 | | 修复引擎 (F-003) | `mcp-guard suggest ` | JSON — 针对每项发现的 `suggested_patch` + 精选参考资料 | ## 为什么选择 mcp-guard Model Context Protocol 正在成为 AI agent 的主要集成层。在 2026 年： - 企业渗透测试样本中 **87%** 的 LLM 应用程序包含 prompt-injection 漏洞（[Practical DevSecOps 2026](https://www.practical-devsecops.com/ai-security-statistics-2026-research-report/)）。 - 被分析的 MCP server 中有 **36.7%** 易受 SSRF 攻击（[Adversa AI, 2026-05](https://adversa.ai/blog/top-mcp-security-resources-may-2026/)）。 - 仅有 **34%** 的企业部署了针对 AI 的专门安全控制措施。 现有工具主要针对企业规模（Microsoft Agent Governance Toolkit）或属于攻击性框架（HexStrike、PentAGI）。`mcp-guard` 是一款面向部署 MCP server、AI 技能或 agent prompt 的个人和中小企业的**开发者优先的防御性 CLI**。 ## 快速开始 ``` # 安装（要求 Node.js ≥ 20） git clone https://github.com/leagames0221-sys/mcp-guard cd mcp-guard pnpm install pnpm run build # 扫描 MCP server 配置 node dist/cli/index.js scan path/to/.mcp.json # 用于 CI 提取的 JSON 输出 node dist/cli/index.js scan path/to/.mcp.json \ --format json --output report.json --fail-on-severity high # 用于 GitHub code-scanning 提取的 SARIF node dist/cli/index.js scan path/to/.mcp.json \ --format sarif --output report.sarif # 针对内置的 OWASP 语料库运行 prompt-injection 测试套件 node dist/cli/index.js inject --severity-floor high # 根据先前的报告生成修复建议 node dist/cli/index.js suggest report.json ``` ### 演示输出 上述四个子命令针对 `cmdinj-positive-curl-pipe-shell` 夹具（带有 `curl|sh` 供应链原语的合成 MCP 配置）生成以下终端输出。由 `docs/demo/cli/render.py` 渲染原始 stdout/stderr 生成（使用 Pillow + MS Gothic，无网络出口）。 | 命令 | 截图 | |---|---| | `mcp-guard --help` | [help.png](docs/demo/cli/help.png) | | `mcp-guard scan ` | [scan.png](docs/demo/cli/scan.png) | | `mcp-guard inject --severity-floor high` | [inject.png](docs/demo/cli/inject.png) | | `mcp-guard suggest report.json` | [suggest.png](docs/demo/cli/suggest.png) | `scan` 输出显示了 3 项发现（1 个 CRITICAL `CMDINJ-CURL-PIPE-SHELL` + 1 个 HIGH `CMDINJ-SHELL-INTERPRETER` + 1 个 MEDIUM `CMDINJ-SHELL-METACHAR`）。`inject` 测试套件针对内置的 OWASP LLM01–10 探针语料库（默认 30 个探针）运行。`suggest` 输出通过 mock LLM provider 输出针对每项发现的修复补丁；使用 `MCP_GUARD_LLM_PROVIDER=ollama` + `OLLAMA_MODEL=gemma3:4b` 切换到 Ollama。 要在本地重新生成截图： ``` mkdir -p docs/demo/cli NO_COLOR=1 node dist/cli/index.js --help > docs/demo/cli/help.txt 2>&1 NO_COLOR=1 node dist/cli/index.js scan tests/fixtures/mcp/cmdinj-positive-curl-pipe-shell.json > docs/demo/cli/scan.txt 2>&1 NO_COLOR=1 node dist/cli/index.js scan tests/fixtures/mcp/cmdinj-positive-curl-pipe-shell.json --format json --output _tmp_report.json > /dev/null 2>&1 NO_COLOR=1 node dist/cli/index.js suggest _tmp_report.json > docs/demo/cli/suggest.txt 2>&1 NO_COLOR=1 node dist/cli/index.js inject --severity-floor high > docs/demo/cli/inject.txt 2>&1 # 渲染 PNG（系统 Python >= 3.10 + Pillow） python docs/demo/cli/render.py ``` ## 扫描器覆盖范围 (F-001) | 类别 | 规则 | 严重程度 | 来源 | |---|---|---|---| | **SSRF** | `SSRF-CLOUD-METADATA`, `SSRF-LOOPBACK`, `SSRF-PRIVATE-IP`, `SSRF-NON-HTTP-SCHEME` | critical / high | [src/scanners/ssrf.ts](src/scanners/ssrf.ts) | | **命令注入** | `CMDINJ-SHELL-INTERPRETER`, `CMDINJ-SHELL-METACHAR`, `CMDINJ-INTERPRETER-EVAL`, `CMDINJ-ENV-INJECTION`, `CMDINJ-CURL-PIPE-SHELL` | high | [src/scanners/command-injection.ts](src/scanners/command-injection.ts) | | **身份验证缺口** | `AUTH-GAP-URL-CREDENTIAL`, `AUTH-GAP-NO-AUTHORIZATION`, `AUTH-GAP-WEAK-BEARER`, `AUTH-GAP-BASIC-AUTH-PLAINTEXT`, `AUTH-GAP-PLAINTEXT-CREDENTIAL` | high / medium | [src/scanners/auth-gap.ts](src/scanners/auth-gap.ts) | | **供应链** | `SUPPLY-CHAIN-UNSCOPED-PACKAGE`, `SUPPLY-CHAIN-UNPINNED-VERSION`, `SUPPLY-CHAIN-EPHEMERAL-HOST`, `SUPPLY-CHAIN-RAW-CONTENT` | high / medium | [src/scanners/supply-chain.ts](src/scanners/supply-chain.ts) | 共计 18 个 ruleId。每项发现都附带一个精选的修复模板，涵盖 OWASP / CWE 参考集 — 有关测试套件部分请参见 [docs/owasp-llm-top10-mapping.md](docs/owasp-llm-top10-mapping.md)，针对每个 ruleId 的模板请参见 [src/remediation/templates.ts](src/remediation/templates.ts)。 ## 测试套件覆盖范围 (F-002) OWASP LLM Top 10 (2025) 语料库位于 [src/probes/owasp/](src/probes/owasp/) 下，包含 **30 个经过净化处理并注明许可证的探针**，涵盖所有 10 个类别（每个类别 3 个探针，通过完整性测试强制执行平衡下限）。探测器调度遵循受 garak 启发的生命周期（Probe → Detector → Harness，ADR-0003 §4）： - `refuse` → [拒绝检测器](src/detectors/refusal.ts) - `no-leak` → [无泄漏检测器](src/detectors/no-leak.ts) - `safe-completion` → [安全完成检测器](src/detectors/safe-completion.ts) 有关完整的覆盖范围表，请参见 [docs/owasp-llm-top10-mapping.md](docs/owasp-llm-top10-mapping.md)。 ## CI 集成 将消费者模板 [.github/workflows/mcp-guard-example.yml](.github/workflows/mcp-guard-example.yml) 放入下游仓库，即可通过一条去重的 PR 评论和 `--fail-on-severity` 门控来扫描 PR 差异。该示例工作流可在 5 分钟的 GitHub Actions 免费层 runner 预算内完成 10 台服务器的配置扫描 (AC-004-4)。 有关 mcp-guard 自身的 CI，请参见 [.github/workflows/ci.yml](.github/workflows/ci.yml) — 跨 OS 矩阵（ubuntu / macos / windows）× 类型检查 + 测试与覆盖率 + 高严重性阈值下的审计。 ## 文档 - [docs/EXIT_CODES.md](docs/EXIT_CODES.md) — 对齐 sysexits 的退出代码映射 - [docs/owasp-llm-top10-mapping.md](docs/owasp-llm-top10-mapping.md) — OWASP LLM01–10 → 探针 + 检测器映射 - [docs/PROVIDERS.md](docs/PROVIDERS.md) — LLM provider 矩阵 + 付费 API 6 层防御 - [SECURITY.md](SECURITY.md) — 支持的版本、报告渠道、安全加固态势 - [docs/adr/](docs/adr/) — 架构决策记录（6 条记录） ## 技术栈 - **语言**：基于 Node.js 20 LTS 的 TypeScript（ESM，严格模式） - **包管理器**：pnpm（已提交 lockfile） - **测试**：vitest（原生 ESM，内置快照） - **CLI**：commander - **Schema 验证**：zod 如果可访问，LLM provider 默认使用 Ollama（模型 `gemma3:4b`）；在 CI 环境中以及未配置任何 provider 时回退到确定性的 mock provider。付费 provider（Anthropic / OpenAI）受环境变量限制，并由 6 层防御保护 — 参见 [docs/PROVIDERS.md](docs/PROVIDERS.md)。 ## 状态 阶段 1 实现已完成：F-001 + F-002 + F-003 + F-005 (CLI UX) 功能完备。阶段 α 验证门控待定（并发安全测试通过，文档套件通过，基准测试及独立验证正在进行中）。 ## 许可证 MIT — 参见 [LICENSE](LICENSE)。探针语料库和模板参考资料在教育范围内对 OWASP 进行 CC-BY-4.0 归属（参见每个探针文件的 `license` + `references` 字段以及 [SECURITY.md](SECURITY.md) § 教育范围）。

标签：AI风险缓解, DLL 劫持, LNA, MCP服务器, MITM代理, 人工智能安全, 合规性, 大语言模型, 安全扫描, 提示词注入防御, 时序注入, 自动化攻击