Skip to content

策略 ​

每个项目有一份策略,是一个 YAML(或 JSON)文档。它列出规则,规定没有规则命中时怎么办,并设定模式。策略 DSL 只描述选择条件,里面没有表达式,也没有代码,所以同一份文档在 Python SDK、TypeScript SDK 和控制面的预演里给出同样的判定。

一个例子 ​

yaml
schema_version: guard.policy.v1
policy_id: support-agent
version: 1
name: 客服 Agent 最小权限
mode: suggest
default_effect: deny
source: manual
rules:
  - rule_id: allow-customer-search
    effect: allow
    risk: normal
    match:
      action_type: tool.call
      resource: search_customer
      agent_id: support-agent
      argument_keys: [customer_id]
    message: 允许查询客户基础资料。
  - rule_id: deny-external-upload
    effect: deny
    risk: high
    match:
      action_type: tool.call
      resource: "upload_*"
      destination: "*.external.example"
    message: 禁止向未批准的外部服务上传数据。

全部字段见策略格式。

格式 v1 和 v2 ​

guard.policy.v1guard.policy.v2
规则效果allow、denyallow、deny、require_approval、degrade
执行器任何版本的 SDK项目里所有活跃的执行器都要支持格式 v2

发布格式 v2 的策略之前,项目里至少要有一个已连接的执行器,并且所有活跃的执行器都报告支持格式 v2。向导安装的 SDK 都支持。不再使用的执行器,在「执行器」页退役。不支持格式 v2 的旧 SDK 会直接拒绝加载 v2 策略,而不是读错。

模式 ​

模式拒绝规则需审批和降级规则没有规则命中、default_effect: deny
observe(只观察)放行并告警放行并告警放行并告警
suggest(建议)高风险规则拒绝;risk: normal 的规则放行并告警放行并告警放行并告警
enforce(强制执行)拒绝需审批 / 降级拒绝

规则不写 risk: normal 就是高风险,所以建议模式下大多数拒绝规则已经会拒绝。策略过期后,任何模式下都拒绝全部动作。新项目默认是只观察模式。

规则匹配什么 ​

规则里写了的每个条件都满足,规则才命中。没写的条件匹配任何值。

条件何时满足
action_type相等,或者 *(默认)
resource按通配符匹配(upload_*),或者 *(默认)
agent_id相等
destination按通配符匹配动作的目标地址;动作没有目标地址时不匹配
argument_keys动作带了这些参数名
argument_equals每个指定的参数等于给定值。值写 session.subject_id 表示「等于可信主体」
argument_in每个指定的参数是列表中的某个值
argument_regex每个指定的参数是不超过 4,096 个字符的字符串,并且整体匹配这个正则表达式
argument_path_under每个指定的参数是一个路径,解析之后位于给定目录之下
data_labels动作带了这些标签

和可信主体比较 ​

argument_equals: {customer_id: session.subject_id} 让 Agent 只能操作当前登录用户自己的记录。如果动作没有可信主体,却带着 customer_id,这条规则就没法检查。Guard 这时按当前模式把它当作这条规则的拒绝处理,原因是 SUBJECT_REQUIRED,所以缺少主体不会让拒绝规则悄悄失效。

正则表达式 ​

单个正则最多 1,024 个字符,一份策略里的正则合计最多 4,096 个字符。项目里有活跃的 TypeScript 执行器时,编辑器会提示超出两种 SDK 一致支持范围的写法:不能用 \d、\w、\s、\b、环视、内联标志和反向引用,^ 只能在开头,$ 只能在结尾。见 TypeScript SDK。

哪条规则说了算 ​

  1. expires_at 已过:所有动作拒绝(POLICY_EXPIRED)。
  2. 命中的规则里有拒绝规则:由它决定(RULE_DENIED)。拒绝总是压过放行,和顺序无关。
  3. 格式 v2 下,其余命中的规则里最具体的那条胜出,也就是写了最多条件的那条。一样具体时,require_approval 优先于 degrade,degrade 优先于 allow。
  4. 命中放行规则:放行(ALLOWED)。
  5. 没有规则命中:按 default_effect 决定(DEFAULT_DENY,或者放行)。

最后再按模式调整,见模式。规则在文件里的先后顺序不影响结果。

发布前先检查 ​

在自己的机器上:

sh
preworld-guard policy-validate policy.yaml
preworld-guard policy-schema --output guard-policy.schema.json

policy-validate 编译这份文件,打印编译结果和摘要。policy-schema 导出 JSON Schema,给编辑器和 CI 用。

控制台的编辑器还会拒收 YAML 锚点、别名、标签、合并键、重复的键和多文档,以及超过 64 KiB、嵌套超过 16 层或超过 5,000 个节点的文档。预演会在这些情况下给出提醒:

  • 强制执行模式、默认拒绝,却没有一条放行规则。
  • 策略设了过期时间。
  • 有需审批规则(需要审批的调用都必须带可信主体)。
  • 降级规则的替代工具没有被策略本身放行。
  • 接了云托管网关,模式却不是强制执行。

建议 ​

  • 先用只观察模式,再根据 Agent 实际做过的事生成候选。见发布策略。
  • 强制执行模式下用 default_effect: deny,只放行你们确认过的动作。漏了放行规则,会表现为一次看得见的拒绝,而不是一个没人发现的缺口。
  • 想让建议模式只对某些不太要紧的拒绝规则告警,就把它们标成 risk: normal。
  • message 写给会读到拒绝的人:模型、用户或者审核员。