MCP Agent Firewall

一个用于 Model Context Protocol (MCP) 2026-07-28 流量的确定性安全网关。

它位于代理/MCP 客户端与远程 MCP 服务器之间，并在信任边界的两个方向上都实施强制：

• 执行前： 协议完整性、确定性策略、固定工具模式、签名的人工审批

• 执行后： 响应侧凭据 DLP、有界检查、显式不可信内容标记，以及隐私最小化的输出审计

LLM 永远不拥有安全决策权。

当前里程碑 — v0.5.0

v0.5 新增了响应侧输出遏制。

已授权的工具调用不再被假定为会产生可信输出。每个上游响应在返回给调用方之前都会被检查。类似密钥/凭据的输出会被阻止，类似提示注入的文本会被标记，所有通过的上游内容都会被明确标记为不可信。

agent / MCP client
        |
        v
MCP header/body integrity
        |
        v
deterministic policy
        |
        +--> DENY ------------------------------> stop
        |
        v
pinned tool catalog + JSON Schema
        |
        v
signed human approval when required
        |
        v
mcp.upstream.dispatch                   [CLIENT span]
        |
        v
upstream MCP server
        |
        |  UNTRUSTED OUTPUT
        v
mcp.output.inspect
        |
        +--> credential / secret -------------> BLOCK 502 / -32046
        |
        +--> malformed / binary / oversized --> BLOCK 502 / -32046
        |
        +--> prompt-injection signal ----------> FLAG + pass through
        |
        +--> clean ----------------------------> pass through
        |
        v
explicit untrusted-content headers
        |
        v
agent / MCP client

Parallel controls:
- privacy-minimized request + output SQLite audit
- low-cardinality OpenTelemetry metrics
- optional OTLP HTTP export

Related MCP server: guardrails-mcp-server

响应侧遏制

凭据/密钥 DLP

确定性输出扫描器会阻止已识别的凭据材料，包括：

• 结构化密钥字段，如 access_token、refresh_token、api_key、private_key、authorization、password、secret 及相关变体

• PEM 私钥材料

• Bearer 凭据

• AWS access-key ID

• GitHub 风格令牌

• OpenAI 风格 sk- 凭据

• JWT 形态的凭据字符串

被阻止的上游响应会被替换为防火墙生成的 JSON-RPC 错误：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32046,
    "message": "Upstream MCP response blocked by output containment",
    "data": {
      "action": "block",
      "signals": ["sensitive_key"],
      "untrusted": true
    }
  }
}

被阻止的响应体不会在错误中回显。

提示注入处理

输出提示注入正则只是信号，而非安全权威。

例如，类似"忽略之前的指令"的内容如果不含阻止性密钥信号，则允许通过，但调用方会收到：

Mcp-Firewall-Untrusted-Content: true
Mcp-Firewall-Output-Inspection: flagged
Mcp-Firewall-Output-Signals: prompt_injection_signal

即使是干净输出也会收到：

Mcp-Firewall-Untrusted-Content: true
Mcp-Firewall-Output-Inspection: clean

这保留了工具返回的数据与可信指令之间的区别。

故障关闭的响应边界

输出检查会阻止：

• 声明为 JSON 但无法解析的内容

• 非 UTF-8 二进制输出

• 大于 MAX_RESPONSE_BYTES（默认 262,144 字节）的响应

• 深度超过 32 层的 JSON

• 超过 10,000 个节点的 JSON 遍历

以 { 或 [ 开头的 UTF-8 输出即使上游服务器声明了误导性的非 JSON 媒体类型，也会被进行 JSON 解析，从而防止通过内容类型规避结构化密钥 DLP。

当前限制：httpx 会在大小检查之前缓冲上游响应。因此该限制约束的是检查/返回行为，但还不是流式网络内存限制。

隐私最小化的输出审计

GET /v1/audit/output 受与请求审计访问相同的 X-Operator-Token 控制保护。

输出审计记录仅包含：

• 时间戳

• 方法/工具名称

• clean、flagged 或 blocked 结果

• 固定词汇的信号名称

• 响应 SHA-256

• 响应字节长度

原始上游响应体永远不会持久化到输出审计中。

OpenTelemetry 可观测性

安全相关 span 包括：

• mcp.firewall.request

• mcp.policy.evaluate

• mcp.schema.validate

• mcp.approval.issue

• mcp.approval.verify

• mcp.approval.consume

• mcp.upstream.dispatch

• mcp.output.inspect

低基数指标：

工具名称和请求哈希仅用于 trace，不作为指标维度。Trace 字符串经过清理并有长度限制。原始请求参数、响应体、审批回执、身份和认证令牌均被排除在遥测之外。

v0.1–v0.4 保留的请求侧控制

• MCP-Protocol-Version、Mcp-Method 和 Mcp-Name 完整性检查

• 默认拒绝的确定性工具策略

• 针对 shell/命令/凭据类工具的显式拒绝模式

• 对具有后果性的发送/创建/更新/删除/购买/转账/部署工具的人工审批

• 嵌套密钥字段、受保护路径、字符串大小和数字请求约束

• 提示注入信号，但不赋予正则安全权威

• SHA-256 固定的可信工具目录

• JSON Schema 2020-12 参数验证

• 可信 x-mcp-header / Mcp-Param-* 体-头验证

• HMAC-SHA256 短期一次性审批回执

• 调用方授权永不转发到上游

• 每进程速率限制和有界请求体

• W3C TraceContext 提取 + 生成的上游传播

• 可选的 OTLP HTTP trace/metric 导出

配置

UPSTREAM_MCP_URL=https://your-mcp-server.example/mcp
MAX_BODY_BYTES=65536
MAX_RESPONSE_BYTES=262144

APPROVAL_SIGNING_KEY=<random-secret-at-least-32-bytes>
APPROVAL_ISSUER_TOKEN=<operator-only-token>
APPROVAL_DEFAULT_TTL_SECONDS=300
APPROVAL_MAX_TTL_SECONDS=900

TRUSTED_TOOL_CATALOG_PATH=./config/trusted_tools.example.json
TRUSTED_TOOL_CATALOG_SHA256=<canonical-catalog-sha256>

AUDIT_READ_TOKEN=<operator-only-token>

OTEL_ENABLED=false
OTEL_SERVICE_NAME=mcp-agent-firewall
OTEL_EXPORTER_OTLP_ENDPOINT=

运行所有门禁

pip install -e ".[dev]"
ruff check app tests scripts
pytest -q
python scripts/run_benchmark.py --fail-on-unsafe
python scripts/run_approval_benchmark.py
python scripts/run_schema_benchmark.py
python scripts/run_observability_benchmark.py
python scripts/run_output_benchmark.py
docker build -t mcp-agent-firewall:test .

已验证的 v0.5 回归证据

已在 GitHub Actions 上针对 v0.5 实现验证：

• 74 个 pytest 测试通过

• 策略安全基准：32/32 精确决策

• 策略安全基准：0 个不安全误接受，0 个误阻止

• 签名审批安全基准：11/11 通过

• 签名审批安全基准：0 个不安全误接受

• 可信模式 / MCP 头基准：12/12 通过

• 可信模式 / MCP 头基准：0 个不安全误接受，0 个误阻止

• 可观测性隐私/传播基准：14/14 通过

• 可观测性基准：0 个检测到的遥测泄漏

• 输出遏制基准：11/11 通过

• 输出遏制基准：0 个不安全误接受

• Ruff：通过

• Docker 构建：通过

输出遏制基准涵盖干净直通、结构化密钥字段、PEM 私钥、Bearer 凭据、GitHub 风格凭据、提示注入信号、格式错误的 JSON、二进制输出、响应大小限制、误导性内容类型，以及不回显的公开检查元数据。

可观测性基准执行真实的 FastAPI/MCP 请求，并检查 W3C 父上下文、策略/模式/审批/输出 span、有界指标维度、生成的上游 trace 传播、输出不可信标记，以及捕获的遥测中不存在注入的密钥哨兵。

这些是合成回归测试，并非对通用生产安全或完整凭据/提示注入检测的声明。

有关信任边界、控制和残余风险，请参阅 docs/THREAT_MODEL.md。

后续里程碑

1. 带密钥 ID 和有界重叠的审批签名密钥轮换

2. 流式响应大小强制和可选的安全内容类型白名单

3. 多副本部署的共享重放/速率限制状态

4. 针对固定目录的实时上游 tools/list 漂移检测

5. 可选的 OPA/Rego 后端，带确定性本地回退

6. 从真实 MCP trace 派生的对抗性语料库