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.admit | MCP 代理决定某个工具或资源要不要出现在列表里时 |
mcp.call | MCP 代理处理每次 tools/call 时 |
mcp.read | MCP 代理处理每次资源读取时 |
mcp.sampling、mcp.elicitation.form、mcp.elicitation.url | MCP 代理处理上游服务反过来发出的提问时 |
network.http | 受控 HTTP 客户端和 HTTP broker |
guard.authorize(...) 和 @guard.tool(...) 也可以传你们自己的 action_type。
一次调用的过程
- Agent 提出一次调用。执行器构造动作,在本地按策略判定。策略已经在内存里,不需要访问网络。
- 记录一条
proposed事件,带上判定结果。 - 判定允许执行时,记录
started,用判定过的那份参数执行工具,再记录completed和结果状态。 - 不允许时,工具不执行,你们的代码或模型拿到原因(见模型看到什么)。
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、网络规则和沙箱,并用一条本应失败的调用实际验证一遍。