AI导哈

MCP安全网关

MCP-Guard是一个用于Model Context Protocol (MCP)集成的策略和安全网关，提供静态检查、动态扫描和最小权限策略执行功能。

  • by DraigCavid
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 DraigCavid/MCP-Guard

使用说明

MCP-Guard（开源核心）

针对模型上下文协议（MCP）集成的策略+安全网关。

  • 解析MCP清单，静态检查作用域和工具。
  • 在沙箱中主动扫描服务器。
  • 在持续集成（CI）和运行时强制执行最小权限策略。
  • 生成带签名的报告和CycloneDX软件物料清单（SBOM）以供审计追踪。

为什么是现在？

  • OpenAI 应用程序开发工具包（2025年10月6日）和 Claude 代码插件（2025年10月9日）加速了 MCP 集成。
  • MCP规范RC版（2025年11月）和GitHub上的MCP注册表使得清单的整洁性变得至关重要。
  • 早期的MCP（可能指某种系统或平台的缩写，具体需根据上下文确定，此处保留原样）安全研究表明，范围错误等同于数据外泄——事件发生前需设置防护栏。

快速入门

uv venv
source .venv/bin/activate
uv pip install -e .[dev]
pytest -q  # run unit tests
uvicorn api.main:app --reload  # launch REST API
python -m cli.__main__ scan --policy policy/rules.yaml tests/data/safe_manifest.json --no-active

提示：在不使用（特定工具或环境）的情况下运行时，CLI 选项必须放在清单路径之前 scan 子命令。

CLI 使用方法

# static analysis only
python -m cli.__main__ scan --policy policy/rules.yaml --no-active tests/data/safe_manifest.json

# full scan with signed report
python -m cli.__main__ scan --policy policy/rules.yaml --json-output reports/safe.json tests/data/safe_manifest.json

# batch scan directory (mix of safe + vuln manifests)
python -m cli.__main__ scan --policy policy/rules.yaml --no-active tests/data/safe_manifest.json tests/data/vuln_manifest.json

# exit code 2 when blocking findings are detected
python -m cli.__main__ scan --policy policy/rules.yaml tests/data/vuln_manifest.json --no-active || echo "blocked"

# containerized sandbox probes
python -m cli.__main__ scan --sandbox container --sandbox-preset baseline --policy policy/rules.yaml tests/data/safe_manifest.json

# apply OPA bundles as additional guardrails (sample rego under policy/opa)
python -m cli.__main__ scan --opa-policy policy/opa/baseline.rego tests/data/safe_manifest.json

# redact sensitive metadata fields before persisting reports
python -m cli.__main__ scan --metadata token=mysecret --redact-metadata token --json-output reports/out.json tests/data/safe_manifest.json

# capture sandbox probe artifacts alongside reports
python -m cli.__main__ scan --sandbox-artifacts-dir artifacts/ --sandbox container tests/data/safe_manifest.json

# run what-if analysis with additional policies/presets
python -m cli.__main__ scan --what-if-policy policy/rules.yaml --what-if-preset dlp tests/data/safe_manifest.json

# scan using registry slugs (auto fetch manifest via MCP registry)
python -m cli.__main__ scan registry://demo --registry-cache cache/registry.json --no-active

# diff reports to inspect new/resolved findings
python -m cli.__main__ report-diff reports/prev.json reports/current.json --format human

# aggregate trend analytics across multiple reports
python -m cli.__main__ report-trends reports/*.json --format json

# generate risk heatmap alongside trend analytics
python -m cli.__main__ report-trends reports/*.json --heatmap-output heatmap.html

# view policy/preset recommendations from history
python -m cli.__main__ report-trends --history reports/history.jsonl --recommend

# list available OPA presets packaged with MCP-Guard
python -m cli.__main__ opa-presets

# append scan metrics to history & include in trends
python -m cli.__main__ scan --history-log reports/history.jsonl tests/data/safe_manifest.json
python -m cli.__main__ report-trends --history reports/history.jsonl --format human

# predict next risk score from history
python -m cli.__main__ risk-predict reports/history.jsonl --format human

# map findings to compliance controls
python -m cli.__main__ report-compliance reports/current.json --framework SOC2

# generate compliance dashboard (JSON or HTML)
python -m cli.__main__ compliance-dashboard reports/current.json --output dashboard.json

# run scans in parallel with retries
python -m cli.__main__ parallel-scan tests/data/safe_manifest.json tests/data/vuln_manifest.json --concurrency 3 --retries 1

# enqueue scans for persistent orchestrator service
python -m cli.__main__ queue-scan tests/data/safe_manifest.json --queue orchestrator/queue.json
python -m cli.__main__ orchestrator-service --queue orchestrator/queue.json --once

API使用

  1. uvicorn api.main:app --reload
  2. curl -XPOST http://localhost:8000/scan -H 'Content-Type: application/json' -d @docs/examples/inline-request.json

API返回静态/活动发现计数、完整报告有效载荷以及签名哈希。参见 docs/examples/demo_safe.md。

政策套餐

  • 基线政策位于 policy/rules.yaml （不使用通配符，资源白名单，出站限制）。
  • 通过YAML进行扩展或覆盖；支持忽略发现结果和严重性覆盖。
  • 所有针对OPA的钩子（hooks）都位于 core/policy/opa_adapter.py。

已签名的报告与软件物料清单（SBOM）

通过CLI/API生成的报告使用SHA-256摘要进行签名，并包含描述每个MCP工具的CycloneDX SBOM组件。工件可以直接从CI上传 infra/github-actions/ci.yml。

应用SDK预检（或预飞行检查）

使用 adapters/apps_sdk/preflight.ts 当存在阻止MCP-Guard检测结果时，阻止ChatGPT应用程序的提交。它读取清单文件，调用API，并将计数显示给应用程序SDK。

注册表同步与策略操作

  • python -m cli.__main__ registry cache/registry.json 将下载最新的MCP注册表索引。
  • 报告和API响应现在包含严重性摘要（metrics.static， metrics.active) 以支持仪表板和持续集成（CI）问题分类。
  • 风险评分是根据严重程度计数（CRITICAL/高/MEDIUM/中/LOW/低）来计算的，以便快速确定优先级。
  • 沙盒探针工件被捕获为JSON格式，并打包成ZIP文件（参见 metadata.sandbox_artifacts_bundle）。

容器与持续集成（CI）

  • infra/devcontainer.json – 配备UV的即开即用VS Code开发容器。
  • infra/Dockerfile – 生产镜像，用于暴露FastAPI服务。
  • infra/github-actions/ci.yml – 在拉取请求上执行 pytest、命令行接口（CLI）冒烟测试，并上传报告工件。

仓库地图

api/            FastAPI service, HTTP routes, Pydantic models
core/           Manifest parser, analyzer, policy engine, active scanner, reports, SBOM
cli/            Typer-powered CLI with rich reporting
adapters/       Integrations (ChatGPT Apps preflight, Claude Code placeholder)
policy/         Baseline policies and docs
tests/          Pytest coverage with safe/vuln fixtures
infra/          Devcontainer, Dockerfile, GitHub Actions workflow
docs/           Scenarios, policy notes, runbooks

路线图快照

  • D0：解析器 + 策略引擎（完整）。
  • D1：主动沙盒扫描器（完整）。
  • D2：CLI、API、CI关卡（完成）。
  • 扩展功能：OPA适配器、注册表同步、Claude Code插件钩子、SBOM加固（开放）。

支持与社区

基于Apache-2.0的开源核心。企业版增加了单点登录（SSO）/基于角色的访问控制（RBAC）/审计追踪功能。请提出问题、建议规则或加入社区Slack（待定）以获取策略调整的反馈。

相关 MCP