文档/审计查询与 Run 排障报告

审计查询与 Run 排障报告#

管理员可在控制台“审计事件”中查询当前项目的变更,在 Run 详情下载排障报告。报告用于排障和关联查询,不代表已执行外部操作。

这些命令和报告随 v0.1.0-alpha.1 之后的主干源码提供。

查询与导出#

guardrailctl audit list --server http://127.0.0.1:8080 \
  --session-file ./session.json --resource-type policy-binding --limit 20

guardrailctl audit export --server http://127.0.0.1:8080 \
  --session-file ./session.json --resource-type policy-binding \
  --from 2026-11-01T00:00:00Z --to 2026-12-01T00:00:00Z \
  --output ./audit-page.json

使用 auth login 创建的管理员会话。支持按事件类型、操作者 ID、资源类型、存储资源 ID 精确筛选,以及包含开始时间、不包含结束时间的范围筛选。CLI 时间必须带 RFC3339 时区;页面使用浏览器本地时区。

--resource-id 指审计记录里的 ID。绑定事件使用 sceneKey + "\n" + kind + "\n" + resourceId 的 SHA-256;管理员查询详情可看到场景和变更前后的绑定。

结果按事件 ID 倒序排列,每页默认 20 条,上限 100 条。将 nextCursor 传给 --cursor 获取下一页,保持项目与筛选条件一致。新插入的事件不会导致后续旧页重复。每次导出一页;页面导出时重新查询,第一页可能包含新事件。继续导出时使用响应中的游标,另存为新文件。

导出移除操作者、资源原始 ID 和详情,保留它们的指纹、事件 ID、类型及时间。哈希可用于关联,不能保证低熵标识无法猜测;管理员普通查询含原始详情,不能直接视为脱敏结果。分享前仍需检查保留字段。

缺失的历史详情正常返回;非法或超过 4096 字节的详情省略并标注 detailsUnavailable。未归属工作空间和项目的旧事件不会被分配给当前项目。接口只查询服务已经写入的事件,不新增执行回执、读取审计或数据保留/删除机制。项目密钥和 Run 提交凭据不能查询审计。

Run 报告#

guardrailctl run report --server http://127.0.0.1:8080 \
  --key-file ./project-key.json --output ./run-report.json run_REPLACE_ME

所有参数放在 Run ID 前。项目密钥需要 runs:read,只能访问所属项目;管理员使用控制台或管理 API。Run 提交凭据不能读取报告。

报告包含冻结策略版本与摘要、状态、决策、有效期、结构化原因,最多 20 条近期提交摘要,以及最终提交中检查结论、证据要求、观测时间与内容指纹。nextBefore 表示仍有旧提交,可使用现有提交列表接口继续查询。并发产生的新提交需要刷新后才能看到。

报告不包含 YAML、ChangeSet 正文、资源选择详情、自由文本摘要或原始证据;保留场景、检查和证据要求等标识,分享前应检查。未形成最终提交的 Run 没有最终证据块,中间观测需通过已鉴权的提交入口查询。指纹只标识已存内容,不证明观测真实,报告不能作为执行授权。

两种导出默认写标准输出;--output 创建私有的 0600 新文件,不覆盖已有文件或符号链接。不要向问题反馈附加会话或密钥文件。

接口与验收#

接口 身份凭据
GET /api/v1alpha1/audit-events 管理员会话
GET /api/v1alpha1/runs/{runId}/report 管理员会话
GET /runtime/v1alpha1/runs/{runId}/report 具有 runs:read 的项目密钥

审计查询使用 Unix 秒传递 from 和 to,指定 redacted=true 可返回脱敏页。

运行 make smoke-bindings 启动隔离的真实服务,完成绑定增改删、审计分页与脱敏导出,再提交拒绝结果,核对报告中的策略和证据指纹。结束后清理临时服务与文件。

审计分页索引由 SQLite、PostgreSQL、MySQL 的第 4 版迁移创建,保留已有事件。自动迁移在启动时执行,外部管理数据库需先应用随包迁移。

文件导出目录需要支持硬链接。目标已存在时返回用法错误(退出码 2),权限或文件系统能力不足时返回导出失败(退出码 1),可改用标准输出或支持硬链接的文件系统。没有操作者的历史记录省略操作者指纹。