策略格式
策略是一个 YAML 或 JSON 对象。任何一层出现不认识的字段都会被拒收。preworld-guard policy-schema 输出 JSON Schema,preworld-guard policy-validate <文件> 编译一份文件并打印它的摘要。规则怎样判定,见策略。
文档
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
schema_version | guard.policy.v1 或 guard.policy.v2 | guard.policy.v1 | require_approval 和 degrade 需要 v2 |
policy_id | 字符串,1–120 个字符 | runtime-default | |
version | 整数,≥ 1 | 1 | 发布时由控制面分配版本 |
name | 字符串 | 最小权限 · 运行时防护 | |
mode | observe、suggest 或 enforce | observe | 见模式 |
default_effect | allow 或 deny | allow | 没有规则命中时怎么办 |
source | 字符串 | manual | 策略的来源 |
finding_ids | 字符串列表 | [] | 这份策略对应的评测发现 |
expires_at | ISO 8601 时间,或 null | null | 过了这个时间,所有动作一律拒绝。读不出来的值视为已过期 |
rules | 规则列表 | [] | 规则编号必须唯一 |
规则
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
rule_id | 字符串,1–120 个字符 | 在策略内唯一 | |
effect | allow、deny、require_approval 或 degrade | 后两种需要格式 v2 | |
fallback_resource | 字符串 | degrade 必填,其他效果不能写 | |
risk | high 或 normal | high | 建议模式下只有高风险的拒绝规则会拒绝 |
match | 对象 | 匹配一切 | 见 match |
message | 字符串 | 动作符合当前运行时策略。 | 随判定一起显示 |
match
| 字段 | 类型 | 何时满足 |
|---|---|---|
action_type | 字符串 | 相等,或 *(默认) |
resource | 通配符 | 通配符匹配,或 *(默认) |
agent_id | 字符串 | 相等 |
destination | 通配符 | 动作的目标地址匹配;没有目标地址时永远不匹配 |
argument_keys | 字符串列表 | 这些参数名都在 |
argument_equals | 映射:参数名 → 值 | 每个参数等于对应的值;session.subject_id 表示可信主体 |
argument_in | 映射:参数名 → 字符串列表 | 每个参数是其中一个值 |
argument_regex | 映射:参数名 → 正则表达式 | 每个参数是字符串(≤ 4,096 个字符),并整体匹配这个表达式 |
argument_path_under | 映射:参数名 → 目录 | 每个参数是路径,解析后位于这个目录之下 |
data_labels | 字符串列表 | 动作带了这些标签 |
规则写的条件越多就越具体。格式 v2 里,非拒绝规则之间按具体程度决定谁胜出。
上限
| 项目 | 上限 |
|---|---|
| 单个正则表达式 | 1,024 个字符 |
| 一份策略里所有正则表达式合计 | 4,096 个字符 |
| 控制台编辑器里的策略源文 | 64 KiB、16 层、5,000 个节点 |
| 携带整份策略的请求 | 256 KiB |
控制台编辑器还会拒收 YAML 锚点、别名、标签、合并键、重复的键和多文档。