Leash MCP观测器深度解读:如何拦截并强制执行AI代理的MCP工具调用

原创2026-11-16 20:39:59807 阅读

Leash MCP观测器深度解读:如何拦截并强制执行AI代理的MCP工具调用

Leash MCP观测器是 Leash 项目内建的透明代理组件,用于拦截、记录并强制执行 AI 代理发出的 MCP(Model Context Protocol)工具调用。它嗅探 JSON-RPC 与 SSE 两种传输,解析出 method 与工具名,再交由策略判定——不合规的 tools/call 会被直接拒绝。下面拆解这条从"抓包"到"执法"的完整链路。

  • 🕵️ 双传输嗅探:同时覆盖 JSON-RPC 与 SSE 流式响应
  • 🚦 转发前拦截:拒绝发生在请求发往上游之前
  • 📜 Cedar 策略驱动:forbid 语句自动转译为 MCP 拒绝规则
  • 📊 全链路遥测:结构化日志 + OpenTelemetry 指标与 span

核心拦截链路:从透明代理到策略判定

整个机制的核心是 proxy.go 中的透明 MITM 代理,配合 mcp_observer.go 中的 MCP 观测器。完整流程共 8 步:

  1. Agent 向 MCP 服务器发起 HTTP(S) 请求(如 mcp.context7.com)
  2. eBPF LSM 先做网络层策略检查
  3. MITM 代理拦截 TLS 连接并读取 JSON-RPC 载荷
  4. 观测器解析 method 字段(如 tools/call)并提取 params.name(工具名)
  5. 策略检查器执行 CheckMCPCall(server, tool) 判定
  6. 若被拒绝,代理返回 403 Forbidden 及拒绝原因
  7. 若放行,请求被转发到上游服务器
  8. 事件写入 WebSocket 事件流,附带 server、tool、method 等元数据

💡 关键点:网络层放行 ≠ 工具调用放行。连接策略放行后,代理仍能在 HTTP 层精确到"单个工具"进行执法,形成两层防御。

请求嗅探:JSON-RPC 与 SSE 双传输

代理创建时会实例化观测器(见 mcp_observer.go#L85-L98)。每个 HTTP 请求进入 inspectHTTPRequest 后按顺序处理:

  1. 内容类型过滤:非 application/json 请求直接跳过
  2. 限额嗅探:最多读取 1MB 请求体,随后把完整请求体原样恢复,不影响后续转发
  3. 信封解析:校验 jsonrpc: "2.0",提取 method、id;若是 tools/call 则解析 params.name 得到工具名
  4. 事件映射:将方法名映射为语义化事件
JSON-RPC 方法 生成的事件名
tools/call mcp.call
tools/list mcp.discover
initialize / initialized mcp.initialize / mcp.initialized
resources/list、resources/read mcp.resources.*
prompts/list、prompts/get mcp.prompts.*

SSE 传输同样被完整覆盖:当响应 Content-Type 为 text/event-stream 时,响应体会被包装成流式嗅探器(sseSniffer),逐块读取并按 SSE 事件边界解析 data: 行,默认每连接最多记录 10 个事件,防止长连接耗尽内存。

强制执行:不转发,直接返回 JSON-RPC 错误

判定逻辑由 PolicyChecker 接口承接,真正执行在 enforceMCPCall:

  • 仅对 tools/call 方法生效
  • 调用 CheckMCPCall(server, tool):无 MCP 规则时全部放行;有规则时按 server + tool 规范化匹配,首个匹配规则生效
  • 被拒绝时,代理不转发请求,而是直接构造一个标准的 JSON-RPC 错误体返回,然后关闭连接

拒绝响应示例(由 proxy.go#L344 构造):

{"jsonrpc":"2.0","id":"1","error":{"code":-32000,"message":"MCP tools/call denied by policy (server=xxx) (tool=yyy)"}}

同时观测器会写入一条 decision=denied 的 mcp.call 事件,并记录 http.request 日志行,形成完整审计闭环。

还有一个精妙细节:当存在 MCP 策略时,代理会通过 setForceParse 开启强制解析——即使观测模式为 off,也会解析出 method 与 tool 供判定使用。这意味着强制执行不受观测开关影响,只记录不拦截时也不会漏判。

Cedar 策略如何转译为 MCP 规则

用户以 Cedar 策略声明意图,转译器 cedar_to_leash.go 将其编译为运行时规则,支持三种模式:

1️⃣ 服务器级拒绝——阻断到某服务器的全部 MCP 流量,同时转译为网络拒绝规则(双保险):

forbid (principal, action == Action::"McpCall", resource)
when { resource in [ MCP::Server::"mcp.untrusted.com" ] };

2️⃣ 工具级拒绝——只拦截某个服务器上的特定工具,其余工具照常可用:

forbid (principal, action == Action::"McpCall", resource == MCP::Tool::"resolve-library-id")
when { resource in [ MCP::Server::"mcp.context7.com" ] };

3️⃣ 信息型 permit——V1 中仅记录不执行,转译时产生 mcp_allow_noop lint 警告。

⚠️ 注意:工具级拒绝必须同时提供 MCP::Tool 与 MCP::Server 两个资源才能生效。更多示例见 CEDAR.md。

观测数据:结构化日志与 OpenTelemetry 遥测

每次 MCP 交互都会产出一条结构化日志,包含 event、server、method、tool、status、outcome、decision、duration_ms 等字段;enhanced 模式下还会追加 transport、proto 与截断后的 session 字段。

遥测层由 mcp_instruments.go 提供:

  • 指标:mcp.requests_total、mcp.errors_total 计数器与 mcp.request.duration 耗时直方图
  • 追踪:每个请求生成一个 span(如 mcp.tools/call:xxx),启用传播时还会向转发请求注入 W3C trace 头,实现跨服务关联
  • 策略提示:最近观测到的 server / tool 列表通过 SnapshotMCPHints 暴露给补全引擎,帮助你在编辑策略时自动联想

配置 MCP 观测器:3 个环境变量速查

MCP 观测器由 mcp_config.go 读取环境变量完成配置,全部有合理默认值:

环境变量 默认值 作用
LEASH_MCP_OBS basic 观测模式:off / basic / enhanced(enhanced 追加 transport、proto、session 字段)
LEASH_MCP_SNIFF_LIMIT 1048576(1MB) 单请求/响应的嗅探字节预算
LEASH_MCP_SSE_EVENT_LIMIT 10 每个 SSE 连接最多记录的事件数

当前限制与适用边界

限制 说明
仅 forbid 生效 permit 目前仅作信息记录,会触发 mcp_allow_noop lint 警告
HTTP/2 隧道 ALPN 协商为 h2 的连接走透明隧道,不解析 MCP 载荷
大载荷放弃嗅探 请求体超过嗅探预算时跳过解析,转发不受影响
工具级策略需双资源 MCP::Tool 必须与 MCP::Server 同时出现

总结

Leash MCP观测器把"AI 代理调用了哪个 MCP 工具"从黑盒变成了可审计、可拦截的白盒:透明代理负责抓包,观测器负责解析,Cedar 策略负责决策,OTel 负责度量。配合 Leash 的 eBPF 文件/网络监控,你可以在 Control UI(默认 localhost:18080)中完整看到 AI 代理的每一次工具调用,并即时拒绝高危操作——这也是"take your AI agents for a walk"这句口号的具体落地。

相关源码入口:

登录后查看全文
leash