Safety Proxy MCP Tools

MCP工具的安全代理

   

一个安全代理，用于在模型上下文协议（MCP）工具调用与基于代码的策略执行及人工智能安全模型之间进行调解。

概述

安全代理（Safety-Proxy）拦截来自AI代理的MCP工具调用，根据安全策略和安全模型对其进行评估，并决定是否允许或拒绝执行。所有决策均会被追踪并记录下来，以供审计之用。

主要特点：

• 🛡️ 以代码形式的策略执行（OPA Rego + Python DSL）
• 🤖 人工智能安全模型集成（Llama-Guard，ShieldGemma）
• 📊 使用Grafana仪表板展示OpenTelemetry追踪数据
• 📈 基于Prometheus指标和SLO的自动扩展
• 🔍 利用套件，阻断率≥90%
• ⚡ p95延迟开销≤150ms
• 🏗️ 免费版基础设施（Docker Compose）

快速入门

先决条件

• Python 3.11+
• Docker 和 Docker Compose
• 制作（可选，为方便起见）

安装

# Clone the repository
git clone https://github.com/StanchPillow55/Safety-Proxy-MCP-Tools.git
cd safety-proxy

# Install dependencies
pip install -r requirements-dev.txt

# Start infrastructure services
make docker-up
# Or: docker compose -f infra/docker-compose.yml up -d

# Verify services are running
docker ps

运行测试

# Run unit tests
make test

# Run exploit suite
python exploit/run.py --mode all

# Run load tests
make load-test

# Run chaos tests
python exploit/chaos_test.py

建筑学

Agent ⇄ MCP Shim → Safety-Proxy → Policy Engine → Safety Models → Tool
                                ↓
                         OpenTelemetry → Grafana
                                ↓
                           PostgreSQL

团队结构

合作伙伴A - 后端核心

• FastAPI 代理服务
• 策略引擎（OPA + DSL）
• 决策组合器
• OTEL（观测、追踪、实验、学习）仪器仪表
• 数据库 & Slack 警报
• 仪表盘

合作伙伴B - 模型、垫片、测试

• Llama-Guard适配器 （CPU，带有超时设置）
• ShieldGemma适配器 （CPU，带备用方案）
• MCP垫片 用于工具包装
• 利用套件（或：攻击套件） 带有种子和藤蔓
• 负载测试 （蝗虫）
• 混沌测试 （故障场景）

合作伙伴B的组件

1. 模型适配器

位于 models/：

• llama_guard/adapter.py - Llama-Guard CPU适配器
• shieldgemma/adapter.py - ShieldGemma CPU适配器
• test_adapters.py - 适配器的单元测试

特点：

• 超时保护（默认5000毫秒）
• 在故障情况下回退到仅策略模式
• 用于异步评分的ThreadPoolExecutor
• 统一的 SafetyScore 接口

2. MCP Shim（注：MCP Shim可能是一个特定技术或系统中的术语，根据上下文，这里直接保留原英文形式，若需具体翻译需更多背景信息）

位于 mcp-shim/shim.py:

from mcp_shim.shim import SafetyProxyShim, SimulatedTools

async with SafetyProxyShim(agent_id="my_agent") as shim:
    tools = SimulatedTools(shim)
    
    # Safe operation - will be allowed
    await tools.list_files("/home/user")
    
    # Dangerous operation - will be blocked
    try:
        await tools.delete_file("/etc/passwd")
    except ToolCallBlockedError as e:
        print(f"Blocked: {e}")

3. 利用套件（或“攻击套件”）

位于 exploit/：

• seeds/benign.jsonl - 100+ 个良性测试用例（JSONL 格式）
• seeds/attacks.jsonl - 8+ 种攻击场景（JSONL 格式）
• run.py - 利用指标驱动的运行器

注： 测试种子数据采用JSONL（JSON Lines）格式——每行一个JSON对象。

# Run all tests
python exploit/run.py --mode all

# Run only attacks
python exploit/run.py --mode attack --count 10

# Run smoke tests (smaller subset)
python exploit/run.py --mode all --count 40

# Generate JSON report
python exploit/run.py --mode all --output report.json

# Validate with CI assertions
python scripts/ci_assert.py report.json --min-block 0.20 --max-fp 0.10

指标：

• 开采区块成功率（目标≥90%）
• 误报率（目标≤1%）
• 延迟p95/p99（目标≤150毫秒）
• SLO合规报告

4. 负载测试

位于 exploit/load_test.py：

# Run with Locust
locust -f exploit/load_test.py --host=http://127.0.0.1:8000 \
    --users 50 --spawn-rate 10 --run-time 5m

5. 混沌测试

位于 exploit/chaos_test.py：

python exploit/chaos_test.py

测试：

• 正常运行基线
• 模型超时处理
• 高并发负载（100个请求）
• 在压力下保持安全

开发工作流程

设置预提交钩子（Pre-commit Hooks）

make precommit

格式化与代码检查

make format  # Black + Ruff
make lint    # Ruff + mypy

运行完整测试套件

make test        # Unit tests with coverage
make exploit     # Exploit suite
make load-test   # Load tests
make chaos-test  # Chaos tests

环境变量

创造 .env.local:

# Database
DATABASE_URL=postgresql://safetyproxy:devpassword@localhost:5432/safetyproxy

# Redis
REDIS_URL=redis://localhost:6379/0

# OTEL
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

# Slack (optional)
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

# Models
LLAMA_GUARD_MODEL_PATH=meta-llama/LlamaGuard-7b
SHIELDGEMMA_MODEL_PATH=google/shieldgemma-2b
MODEL_TIMEOUT_MS=5000

SLOs（可译为“学习成果”或根据具体语境翻译为“学生学习目标”等，这里采用一种通用的翻译）

• 延迟p95 ≤ 150ms 的附加开销
• 安全≥90%的利用阻断率
• 准确性良性调用的假阳性率≤1%
• 可用性≥99.5%的代理可用时间

监控与自动扩展

Safety-Proxy 在（某处）暴露 Prometheus 指标 /metrics 以实现全面可观测性和基于SLO的自动扩展。

指标端点

# Access metrics (when proxy is running)
curl http://localhost:8000/metrics

关键指标：

• safety_proxy_requests_total - 按状态、决策、代理、工具划分的请求数量
• safety_proxy_request_duration_seconds - 请求延迟直方图（p50，p95，p99）
• safety_proxy_requests_in_flight - 当前并发请求
• safety_proxy_decisions_total - 决策结果（允许/拒绝）
• safety_proxy_policy_duration_seconds - 政策评估延迟
• safety_proxy_model_duration_seconds - 模型推理延迟
• safety_proxy_5xx_errors_total - 错误率追踪

水平Pod自动扩展器（HPA）

当部署到Kubernetes时，Safety-Proxy支持基于以下条件的自动扩展：

基本缩放（默认）：

• CPU利用率（目标70%）
• 内存利用率（目标为80%）

高级扩展（使用Prometheus适配器）：

• p95延迟 ≤ 150毫秒
• 每个Pod每秒的请求数
• 5xx错误率 \< 0.5%

# Deploy with HPA enabled
helm install safety-proxy ./infra/helm \
  -f ./infra/helm/values.yaml \
  --namespace safety-proxy

# Watch autoscaling in action
kubectl get hpa -n safety-proxy -w

配置：

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  customMetrics:
    enabled: true  # Requires Prometheus Adapter
    latencyP95TargetSeconds: "0.15"  # 150ms SLO
    requestsPerSecondTarget: "100"   # 100 RPS per pod
    errorRatePercentageTarget: "0.005"  # 0.5% error rate

行为：

• 当阈值被超过时，立即扩展规模
• 逐渐减小（5分钟稳定期）以避免振翅（或剧烈波动）
• 在中断期间保持至少2个Pod（Pod中断预算）

看 docs/METRICS_AND_AUTOSCALING.md 以获取完整的设置指南。

基础设施

所有服务均通过 Docker Compose 在本地运行：

• PostgreSQL（通常直接音译为“波斯特格瑞斯”或保持原英文名，不常用中文译名） (端口 5432) - 决策日志
• Redis (端口 6379) - 缓存
• Grafana（音译为“格拉夫纳”或保持原名不译，根据语境可选择） (端口 3000) - 仪表板
• Tempo 翻译成中文是“节奏”或“速度”，具体取决于上下文。在音乐领域，Tempo 通常指的是乐曲的速度或节奏，即每分钟的拍数（BPM）。在更广泛的语境中，它也可以指任何活动或事件的节奏或速度 (端口 4317/4318) - 分布式追踪
• 洛基 (端口 3100) - 日志聚合

访问 Grafana：http://localhost:3000（开发环境中无需认证）

文档

• docs/PROJECT_CONTEXT.md - 项目概述与决策
• docs/METRICS_AND_AUTOSCALING.md - Prometheus指标与HPA自动伸缩指南
• docs/API.md - 代理API端点（合作伙伴A）
• docs/DEMO.md - 演示脚本（合作伙伴A）
• docs/RUNBOOK.md - 操作指南（合作伙伴A）
• PROMETHEUS_METRICS_SUMMARY.md - 实施概要

许可证

麻省理工学院（MIT）

贡献；做出贡献

查看工作计划于 docs/PROJECT_CONTEXT.md 用于团队角色分配和任务分解。