策略
每个项目有一份策略,是一个 YAML(或 JSON)文档。它列出规则,规定没有规则命中时怎么办,并设定模式。策略 DSL 只描述选择条件,里面没有表达式,也没有代码,所以同一份文档在 Python SDK、TypeScript SDK 和控制面的预演里给出同样的判定。
一个例子
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.v1 | guard.policy.v2 | |
|---|---|---|
| 规则效果 | allow、deny | allow、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。
哪条规则说了算
expires_at已过:所有动作拒绝(POLICY_EXPIRED)。- 命中的规则里有拒绝规则:由它决定(
RULE_DENIED)。拒绝总是压过放行,和顺序无关。 - 格式 v2 下,其余命中的规则里最具体的那条胜出,也就是写了最多条件的那条。一样具体时,
require_approval优先于degrade,degrade优先于allow。 - 命中放行规则:放行(
ALLOWED)。 - 没有规则命中:按
default_effect决定(DEFAULT_DENY,或者放行)。
最后再按模式调整,见模式。规则在文件里的先后顺序不影响结果。
发布前先检查
在自己的机器上:
preworld-guard policy-validate policy.yaml
preworld-guard policy-schema --output guard-policy.schema.jsonpolicy-validate 编译这份文件,打印编译结果和摘要。policy-schema 导出 JSON Schema,给编辑器和 CI 用。
控制台的编辑器还会拒收 YAML 锚点、别名、标签、合并键、重复的键和多文档,以及超过 64 KiB、嵌套超过 16 层或超过 5,000 个节点的文档。预演会在这些情况下给出提醒:
- 强制执行模式、默认拒绝,却没有一条放行规则。
- 策略设了过期时间。
- 有需审批规则(需要审批的调用都必须带可信主体)。
- 降级规则的替代工具没有被策略本身放行。
- 接了云托管网关,模式却不是强制执行。
建议
- 先用只观察模式,再根据 Agent 实际做过的事生成候选。见发布策略。
- 强制执行模式下用
default_effect: deny,只放行你们确认过的动作。漏了放行规则,会表现为一次看得见的拒绝,而不是一个没人发现的缺口。 - 想让建议模式只对某些不太要紧的拒绝规则告警,就把它们标成
risk: normal。 message写给会读到拒绝的人:模型、用户或者审核员。