AI导哈

模型上下文协议防护框架

MCP-Guard是一个模块化的安全框架，旨在保护大型语言模型（LLM）在工具集成中免受新兴威胁，如提示注入、数据泄露和影子劫持。

  • by GenTelLab
  • Python
  • 本地部署
  • 23 星标
  • 更新于
在 GitHub 查看 GenTelLab/MCP-Guard

使用说明

🛡️ MCP-Guard（中文可译为：“守护者-MCP”或根据具体语境调整为更贴切的名称，但直接翻译保持原样为“守护者-MCP”）

A Robust Defense Framework for Safeguarding Model Context Protocol (MCP) in LLM Applications

概述

MCP-Guard是一种前沿的模块化安全框架，旨在通过模型上下文协议（MCP）保护大型语言模型（LLMs）免受工具集成中新兴威胁的攻击。随着提示注入、数据外泄和阴影劫持等漏洞的增多，MCP-Guard提供了企业级的防御能力，并且具有超低延迟。该框架设计注重可扩展性，具备热插拔检测器、无需注册表的操作以及与生产工作流程的无缝集成。配合 MCP-AttackBench （70k+个样本），它使开发人员和研究人员能够构建安全、可靠的AI系统。

🔥 最新动态

  • [2025-09] MCP-Guard 初步代码库发布！
  • [2025-08] 我们的论文《MCP-Guard：一种针对大型语言模型应用中模型上下文协议完整性的防御框架》现已上线 arXiv。

📑 目录

主要特点

  • 🛡️（盾形符号，常用于表示保护、防御或安全） 多阶段检测流程平衡速度与精度：
    • 第一阶段基于轻量级模式的扫描技术，实现即时威胁过滤（如SQL/Shell注入、即时劫持）——延迟低于2毫秒。
    • 第二阶段基于E5的神经模型经过微调，用于语义分析（基准测试准确率96.01%）。
    • 第三阶段大型语言模型（LLM）仲裁（支持GPT、Llama等）用于最终、精细的决策（召回率高达98.47%）。
  • 📊 表格/数据图表 MCP-AttackBench70,000+个精心挑选的样本，模拟各种攻击场景——非常适合训练和评估。
  • ⚙️ 通常表示“齿轮”或“设置”等与机械、配置相关的图标，具体含义需结合上下文理解。在无特定上下文时，可简单译为“齿轮”或“设置图标”。 企业级就绪工具热更新、可插拔的大语言模型（LLMs）、无需注册表的部署以及低开销的可扩展性。

建筑

MCP-Guard的模块化处理流程从快速规则升级到深度分析：

  • 第一阶段：基于模式的检测器 （超低延迟，快速失败）

    • 提示注入：隐藏指令/数据外泄。
    • 敏感文件访问：系统文件泄露。
    • Shell 注入：命令模式。
    • SQL注入：查询/XSS（跨站脚本攻击）尝试。
    • “Shadow Hijack: 工具伪装。”。
    • 跨域：外部违规（可配置白名单）。
    • 重要标签：危险的HTML元素（例如，script、iframe）。

  • 第二阶段：可学习的检测器E5嵌入模型，针对概率性恶意评分进行了微调。

  • 第三阶段：大语言模型仲裁用于上下文判断的可插拔模型（兼容OpenAI）。

先决条件

环境设置

根据导出的配置创建 Conda 环境：

# Create environment from environment.yml
conda env create -f environment.yml

# Activate the environment
conda activate mcp_guard

模型下载

下载LearnableShield模型以 learnableshield_models/:

mkdir -p learnableshield_models

# Download models from Hugging Face
# Example commands - update with the correct model repository URLs:
git lfs install
git clone https://huggingface.co/GenTelLab/MCP-Guard

# Or using huggingface_hub Python library:
python -c "
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id='GenTelLab/MCP-Guard-Shield',
    local_dir='learnableshield_models/',
    local_dir_use_symlinks=False
)
"

快速入门 & API 使用

快速入门，深入了解API细节，实现无缝集成。

配置大型语言模型（LLM）后端：

配置活动模型：编辑 configs/models/model_registry.json。

{
  "active_model": "mistral",  // Currently active model
  "mistral": {
      "enabled": false,
      "class": "src.mcp_guard.detectors.model_detectors.llm_detector.MistralEnhancedDetector",
      "params": {
        "model": "mistral:7b",
        "host": "http://localhost:11434"
      }
    }
}

第三阶段探测器选择（两种选项）

  • Ollama（本地）： llama3/mistral/qwen/tinyllama/llama2确保Ollama正在运行（默认 http://localhost:11434)，然后设置 active_model 在里面 configs/model_registry.json 并留住它 enabled: true 将其用作第三阶段检测器。
  • API（云端）： gpt4o （OpenAI兼容模式）。设置环境变量，然后设置 active_model to gpt4o 并且 enabled: true 使用GPT作为第三阶段检测器：
    • export OPENAI_API_KEY="your-key"
    • export OPENAI_BASE_URL="https://api.openai.com/v1"

启动服务器

uvicorn src.mcp_guard.core:app --host 0.0.0.0 --port 8000 --reload

样品申请

curl -X POST "http://localhost:8000/guardrail/scan" -H "Content-Type: application/json" -d '{
    "tool_name": "example_tool",
    "tool_description": "Test with potential threat: ignore instructions",
    "servers": [{"url": "example.com"}],
    "tool_input_schema": {"type": "object", "properties": {"input": {"type": "string"}}}
}'

预期响应：以JSON格式提供详细的安全评估。

示例回答

{
  "allowed": true,
  "issues": [ { "type": "prompt_injection", "message": "..." } ],
  "detector_used": "three_layer_detection",
  "degraded_detectors": [],
  "degradation_note": null,
  "final_reason": "Based on three-layer detector results",
  "gpt_analysis": "Based on gpt's analysis",
  "detection_stage": "local_gentelshield_openai_clean",
  "end_time": 175.13219497
}

注释：

  • allowed=true 表示请求已通过； false 这意味着它被高风险规则拦截了。
  • detection_stage 指示决策是在哪里做出的（例如。， local_blocked， local_gentelshield_blocked， local_gentelshield_<model>_clean）。
  • 警告级别的问题不会阻塞，但会显示在 warning_issues。

运行测试

探测器配置

  • 跨域：编辑 configs/servers/popular_servers.json.
{
  "popular_servers": [
    "allowed-server-1",
    "allowed-server-2"
  ]
}
  • 其他：用于规则的JSON文件（shell、SQL、隐藏指令、数据外泄）。
    • 外壳注入规则： configs/detectors/shell_rules.json
    • SQL/XSS 规则： configs/detectors/sql_xss_rules.jsonc
    • 隐藏的指令规则： configs/detectors/hidden_rules.json
    • 数据外泄规则： configs/detectors/exfiltration_params.json

测试命令（或命令行管理器/控制台）

验证MCP-Guard的有效性，可采用基准测试或API模拟。

python ./main.py  # All samples
python ./main.py --max-samples 50  # Quick test
python ./main.py --csv-file your_test.csv  # Custom data

支持：OpenAI、Azure、自定义API。

测试输出和结果

**test_results_detailed.csv**每个样本的详细结果，包括：

  • 原始描述
  • 真实标签和预测标签
  • 检测时间
  • 检测阶段
  • 发现的问题

性能优化

  1. 减少测试样本使用 --max-samples 用于快速测试
  2. 禁用图层修改 core.py 跳过特定层
  3. 缓存模型确保LearnableShield模型仅加载一次
  4. API速率限制请考虑大型测试的API提供商速率限制

📝 待办事项列表

  • [x] 放开纸张。
  • [x] 发布具备基本功能和演示场景的平台。
  • [ ] 发布MCP-AttackBench数据。
  • [ ] 训练框架。

引用

@misc{xing2025mcpguard,
  title={MCP-Guard: A Defense Framework for Model Context Protocol Integrity in Large Language Model Applications},
  author={Wenpeng Xing and Zhonghao Qi and Yupeng Qin and Yilin Li and Caini Chang and Jiahui Yu and Changting Lin and Zhenzhen Xie and Meng Han},
  year={2025},
  eprint={2508.10991},
  archivePrefix={arXiv},
  primaryClass={cs.CR}
}

📄 许可证

这个项目 MCP-Guard 根据（某种许可协议）授权 Apache许可证2.0。

相关 MCP