发布策略
适用范围:当前托管生产使用组织工作区。个人工作区及其所有者自审需等待控制面升级;自部署实例请按实际版本与身份配置判断。
策略不会自己变。正常的路径是:起草一份候选策略,拿 Agent 实际做过的事预演,由第二个人独立审核,再发布成一个新版本。任何一个已发布版本都可以回滚,回滚同样生成新版本。有两种情况不经审核:回滚(会记下原因),以及留给紧急变更的直接发布接口(见用 API 操作)。
| 步骤 | 谁(控制台角色) | 在哪里 |
|---|---|---|
| 起草候选 | 所有者、管理员 | 「策略」(编辑 DSL)或「策略工作流」(从观察生成) |
| 预演 | 编辑器里:所有者、管理员;已保存的候选:所有人 | 「策略」「策略工作流」 |
| 提交独立审核 | 所有者、管理员 | 「策略工作流」 |
| 批准或驳回 | 审核员 | 「策略工作流」 |
| 发布 | 所有者、管理员 | 「策略工作流」 |
| 回滚 | 所有者、管理员 | 「策略工作流」→ 已发布版本 |
候选的状态依次是草稿、独立审核中、已批准或已驳回、已发布。过了有效期就是已过期。已过期的候选不能再审核或发布。
起草候选
从观察生成
在「策略工作流」点「从观察生成候选」,根据项目的事件生成一份最小权限的放行清单。可以设定:
- 一个动作至少要出现几次(1–100)。
- 观察窗口(1–90 天)。
- 候选的模式(只观察、建议或强制执行)。
- 候选的有效期(1–720 小时)。
只统计成功执行过的动作的脱敏事件。候选只放行出现次数够多的动作,其他一概不放行。窗口里没出现过的动作不在里面。没有动作达到次数要求时,会提示「观察窗口内没有满足次数阈值的成功动作」。
在编辑器里写
在「策略」页以 YAML 编辑当前策略,这里还能写拒绝、需审批和降级规则。点「预演」检查,点「保存为候选」保存,可以附一段说明,有效期 1 到 720 小时(默认 168)。没保存的修改留在当前标签页里,刷新页面或会话过期都不会丢。
从评测发现生成
测试系统可以把一条发现以 guard.eval.finding.v1 格式发给 Guard(POST /v1/eval/findings/import),再生成候选(POST /v1/eval/findings/{finding_id}/candidate-policy)。同一条发现重复导入不会产生新内容。evidence_ref 应该指向你们自己的证据系统,不要把原始数据放进 bundle。
预演
预演用新的候选重放近期事件,显示每个判定会怎样变化。预演从不执行工具。
- 重放口径:全部尝试过的动作,或者仅已完成的动作。窗口 1 到 90 天,最多抽样 500 个动作。
- 能看到:当前版本和候选版本,候选的格式、模式、默认判定和规则数,执行器是否都支持这个格式,提醒,规则变化,以及变化前后的判定数目和判定变了的动作样例。
- 信息不足:控制面只有脱敏事件,只知道参数名,不知道参数值。按参数值判定的规则(
argument_equals、argument_in、argument_regex、argument_path_under)没法据此判断。这些动作显示为「信息不足」,并写明缺了哪些字段,不会去猜。
在你们这边回放
要判断按参数值写的规则,就在有参数值的地方回放。点「下载策略,在客户侧回放」保存 candidate-policy.json,然后:
preworld-guard policy-replay --policy candidate-policy.json --records actions.json --output replay-report.jsonactions.json 是 1 到 1,000 条完整的动作(带 arguments),不超过 2 MiB。回放不执行工具,不访问网络,报告里只有判定结果,没有参数值。
审核
点「提交独立审核」把候选交给独立审核员,可以附一段说明。审核员批准或驳回,也可以写审核意见。
- 作者和提交审核的人不能审核。
- 审核员的可信主体必须和作者不同。
- 管理员不能批准策略审核,这要审核员角色。 后续支持个人工作区的控制面版本允许所有者自审候选;当前托管生产仍采用上述组织职责分离规则,不能用该例外绕过第二人审核。
所以当前托管生产的组织项目至少需要两个人。
发布
已批准的候选由所有者或管理员发布。点「准备发布」,页面列出会变什么:模式(比如「强制执行 → 只观察」)、版本、执行器是否支持这个格式、提醒和规则变化。再点「发布 v6」(按钮上写的是下一个版本号)。
- 发布的内容必须和审核时的摘要一致。
- 审核期间如果有人发布了别的版本,这次发布会被拒绝,需要基于当前版本重新起草。
- 格式 v2 的策略要求所有活跃的执行器都支持格式 v2。
执行器在下一次心跳时加载新版本,所以大约 15 秒内生效。「执行器」页显示每个执行器加载了哪个版本:「已加载当前策略」「待确认」或「仍在用旧版本」。
回滚
在已发布版本里选一个更早的版本,写明原因(1 到 500 个字符),点「发布回滚版本」。Guard 把那个版本的内容发布成一个新版本,控制操作审计里记下原因。历史不会被改写。
用 API 操作
不登录控制台的自部署环境,可以用项目令牌走同样的流程。先用 admin 令牌从观察生成候选:
curl -X POST "$PREWORLD_GUARD_ENDPOINT/v1/policy/candidates" \
-H "Authorization: Bearer $GUARD_ADMIN_TOKEN" -H 'Content-Type: application/json' \
-d '{"min_occurrences":3,"window_days":7,"mode":"suggest"}'用 POST /v1/policy/candidates/{candidate_id}/preview 预演,然后发起审核,用 reviewer 令牌批准,最后带着审核 ID 和当前策略版本发布:
candidate_id='cand_...'
review_id=$(curl -s -X POST "$PREWORLD_GUARD_ENDPOINT/v1/policy/candidates/$candidate_id/reviews" \
-H "Authorization: Bearer $GUARD_ADMIN_TOKEN" -H 'Content-Type: application/json' \
-d '{"comment":"已确认观察窗口内的最小权限范围。"}' | jq -r .review_id)
curl -X POST "$PREWORLD_GUARD_ENDPOINT/v1/policy/candidates/$candidate_id/reviews/$review_id/approve" \
-H "Authorization: Bearer $GUARD_REVIEWER_TOKEN" -H 'Content-Type: application/json' \
-d '{"comment":"批准,按建议模式发布。"}'
curl -X POST "$PREWORLD_GUARD_ENDPOINT/v1/policy/candidates/$candidate_id/publish" \
-H "Authorization: Bearer $GUARD_ADMIN_TOKEN" -H 'Content-Type: application/json' \
-d "{\"expected_version\":1,\"review_id\":\"$review_id\"}"其他接口:
| 接口 | 做什么 |
|---|---|
GET /v1/policy/versions | 已发布版本 |
GET /v1/policy/diff?from_version=1&to_version=2 | 两个版本之间改了什么 |
POST /v1/policy/rollback | 把一个更早的版本发布成新版本 |
POST /v1/policy/dsl/preview | 预演一份已用 policy-validate 检查过的 YAML 文档 |
POST /v1/policy/publish 和 POST /v1/policy/dsl/publish 不经候选和审核直接发布。只在紧急情况下用:它们会记进控制操作审计,但没有第二个人检查过。