Skip to content

Guard 怎么工作 ​

组成部分 ​

部分运行在哪里做什么
执行器你们的环境里:在 Agent 进程内(SDK),或者在它旁边(MCP 代理、HTTP broker)加载策略,在每个动作执行前判定,记录判定结果,发心跳
控制面我们托管,或者部署在你们的网络里保存项目、成员、策略和各个版本、审核、审批票据、事件和审计记录
控制台浏览器里,由控制面提供接入、编辑和审核策略、动作审批、事件、成员

执行器用自己的执行器凭据,经 HTTPS 访问控制面。控制面从不主动调用你们的 Agent。

什么是动作 ​

副作用发生之前,执行器先构造一个动作:谁在做、要做什么、对什么做。

字段含义
action_type动作类型:tool.call、mcp.call、network.http 等
resource工具、MCP 工具或逻辑资源的名字,比如 search_customer、mcp:finance__transfer
arguments工具将要收到的参数。用来判定,不上传
destination出站调用的目标地址,HTTP 用
data_labels你们的代码加的标签,比如 finance
agent_id执行器凭据所属的 Agent
subject_id可信主体:Agent 替哪个最终用户做事。它来自你们的应用(guard_run(subject_id=...) 或适配器的 resolve),不来自模型

Guard 自己的防护点用到的动作类型:

动作类型由谁产生
tool.call@guard.tool 和所有框架适配器
mcp.admitMCP 代理决定某个工具或资源要不要出现在列表里时
mcp.callMCP 代理处理每次 tools/call 时
mcp.readMCP 代理处理每次资源读取时
mcp.sampling、mcp.elicitation.form、mcp.elicitation.urlMCP 代理处理上游服务反过来发出的提问时
network.http受控 HTTP 客户端和 HTTP broker

guard.authorize(...) 和 @guard.tool(...) 也可以传你们自己的 action_type。

一次调用的过程 ​

  1. Agent 提出一次调用。执行器构造动作,在本地按策略判定。策略已经在内存里,不需要访问网络。
  2. 记录一条 proposed 事件,带上判定结果。
  3. 判定允许执行时,记录 started,用判定过的那份参数执行工具,再记录 completed 和结果状态。
  4. 不允许时,工具不执行,你们的代码或模型拿到原因(见模型看到什么)。

started 记录不下来(比如本地事件队列满了)时,工具不执行,原因是 GUARD_AUDIT_UNAVAILABLE。

五种判定结果 ​

判定控制台写法结果
allow放行工具执行
deny拒绝工具不执行
allow_with_warning放行并告警工具执行;事件里记下强制执行时本应得到的判定(would_effect)。出现在只观察和建议模式下
require_approval需审批工具不执行,开一张一次性的审批票据;审核员批准后,同一次调用可以执行一次。需要策略格式 v2 和强制执行模式。见动作审批与降级
degrade降级原工具不执行,改为执行你们注册的、范围更窄的替代工具,替代工具单独判定一次。需要策略格式 v2 和强制执行模式

每个判定都带着做出判定的规则、原因码(比如 RULE_DENIED、DEFAULT_DENY)、策略版本和策略摘要。哪条规则说了算,见策略。

Guard 无法判定时 ​

Guard 判定不了就不执行。这些情况都没有判定结果,工具不会执行:

  • 连不上控制面,本地也没有有效的策略缓存。
  • 本地缓存的策略超过了允许的离线时长。
  • 执行器凭据已撤销或过期(GUARD_CREDENTIALS_INVALID)。401、403 从不退回去用缓存。
  • started 记录写不下来(GUARD_AUDIT_UNAVAILABLE)。
  • 适配器 resolve 给出的可信主体和 guard_run 里的不一致(GUARD_SUBJECT_MISMATCH),或者 resolve 出错(GUARD_IDENTITY_UNAVAILABLE)。
  • SDK 内部出错。

策略过了 expires_at 之后,不管什么模式,所有动作一律拒绝(POLICY_EXPIRED)。

无法判定时 Agent 那边看到什么,各框架不同:有的中止运行,有的把错误结果交给模型。见框架适配器。

离线与策略缓存 ​

  • 执行器把最近一次校验过的策略存在 .preworld-guard/policy.json(用 PREWORLD_GUARD_CACHE 改位置)。缓存绑定项目和控制面地址,读取时校验 SHA-256。
  • 调了 guard.start() 的执行器每 15 秒发一次心跳,发现新的策略版本就立即加载。没调的话,客户端在用到策略、且距离上次检查满 60 秒时刷新。
  • 连不上控制面时,执行器继续按缓存的策略判定。超过 5 分钟没有刷新成功(默认 max_stale_age=300),所有受保护的动作一律阻断,直到重新连上控制面。
  • 事件先存进本地有上限的队列(SQLite,和策略缓存在同一个目录),控制面恢复后再发出去。队列满了会阻止新的动作,而不是让它们不留记录地执行。
  • 控制面不可用期间,新的审批既提交不了,也用不了。

哪些数据会离开你们的环境 ​

用 SDK 接入时,只发送脱敏事件:

  • 各种 ID:事件、任务、追踪、动作、项目、Agent 和可信主体。
  • 尝试了什么:动作类型、资源、目标地址、数据标签、防护点,以及参数的名字。
  • 判定:结果、would_effect、规则、原因码、说明、策略版本和摘要。
  • 结果:状态、返回值或错误的类型,以及参数、返回值和错误文字的 SHA-256 摘要。

参数值、工具返回值、模型的提示词和输出、源代码、你们的业务凭据都留在进程里。资源名、目标地址和主体 ID 仍可能敏感,导出的事件要像其他日志一样保护。见安全说明。

Guard 看不到什么 ​

Guard 只能判定经过它的东西。没包装的工具、模型厂商托管的工具(比如模型自带的搜索)、shell 命令、直接打开的 socket 都绕得过去。要堵住这些路径,用独立进程里的 MCP 代理、HTTP 出站 broker、网络规则和沙箱,并用一条本应失败的调用实际验证一遍。