mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-20 16:07:11 +08:00
69 lines
4.8 KiB
Markdown
69 lines
4.8 KiB
Markdown
# ADR-0506：源码绑定的 Local Alpha 验证证据
|
||
|
||
- 状态：Accepted
|
||
- 日期：2026-08-27
|
||
- 决策：D-411
|
||
- 关联：ADR-0503、ADR-0504、ADR-0505
|
||
|
||
## 背景
|
||
|
||
ADR-0504 把 Local Trial Kit 的写入与离线审计收敛为一个 materializer，但 v1 manifest 在 `create` 时会无条件写入九个 `passed` 字段。调用者只需提供可构建镜像和 SBOM，即可得到一份声称已经通过漏洞扫描、fresh Owner、Edge/Standalone lifecycle 与原生 cancellation 的 manifest；materializer 并未收到这些 gate 的任何证据。
|
||
|
||
提交 `4239464a` 的 macOS Docker Desktop 复验进一步暴露了该语义错误：bundle 内容、checksum、reload 和入口 smoke 均通过，但完整 Owner 旅程因 bind-mount UID 语义失败；同提交的原生 Linux CI 后续通过。内容完整性、源码实现通过和 exact artifact 已被验证是三种不同事实，不能由一个常量同时代替。
|
||
|
||
## 决策
|
||
|
||
### 1. Alpha bundle 必须消费独立的 verification evidence
|
||
|
||
Local Alpha schema 升为 `qinglong/alpha-local-trial-kit@v2`。`create` 新增必需的 `--verification-evidence`，并把 `verification` 从九个常量改为 `verification-evidence.json` 的文件记录。闭合目录从六个文件增加为七个，evidence 同时进入 manifest byte/SHA-256 绑定与 `SHA256SUMS`。
|
||
|
||
缺少 evidence、旧 v1 manifest、额外文件、evidence mutation 或 subject 漂移全部失败关闭。旧 schema 尚未公开发布，因此不保留会继续接受无来源 `passed` 声明的兼容分支。
|
||
|
||
### 2. evidence 绑定 exact workflow 与 artifact subject
|
||
|
||
新增同一 materializer 的 `record-verification` 模式，只接受：
|
||
|
||
- repository `whyour/qinglong`；
|
||
- workflow ref `whyour/qinglong/.github/workflows/ql3-ci.yml@refs/heads/next`；
|
||
- `workflow_dispatch` event 与 `local-image` job；
|
||
- 完整 source/workflow SHA、十进制 run ID/attempt；
|
||
- Tier-1 architecture，以及从 Docker inspection 获得的 Application/operator exact image ID。
|
||
|
||
evidence 的 subject 同时绑定版本、源码、架构和两个不同镜像 ID；九个 gate 保持 exact closed set。bundle create 与 offline audit 都重新匹配 evidence subject 和 manifest，不允许把另一架构、另一镜像或另一 run 的 evidence 复制进来。
|
||
|
||
GitHub workflow 只能在 Trivy、inventory、SBOM、128 MiB entrypoint、fresh lifecycle、完整 Trial Kit journey 与原生 cancellation 均成功之后记录 evidence；静态审计固定 `journey → cancellation → record-verification → create → audit → upload` 顺序。
|
||
|
||
### 3. workflow provenance 不是公开发布签名
|
||
|
||
evidence 提供可定位、可交叉检查的 GitHub run identity，不声称调用者无法伪造 JSON。下载者仍需到 GitHub 检查该 run 的 source、attempt 和结论。公开 Release Set 继续使用独立的 immutable digest、Cosign 与 GitHub attestation，不以 Alpha evidence 替代供应链签名。
|
||
|
||
普通 push/PR 不生成或上传 Alpha artifact；本地构建、push CI 通过或 source-equivalent native gate 只能支持工程候选判断。只有显式 milestone dispatch 产生的 exact-image evidence 才允许 materializer 声称 Local Alpha Trial Kit。
|
||
|
||
## 被拒绝的替代方案
|
||
|
||
### 保留 manifest 内的固定 `passed` 字段
|
||
|
||
拒绝。它把“脚本知道有哪些 gate”错误提升为“这些 gate 已对当前 artifact 执行”。
|
||
|
||
### 仅加入 GitHub run URL，不绑定镜像 ID
|
||
|
||
拒绝。同一源码可以因基础 package、构建平台或配置产生不同镜像；source-level run 不能自动证明另一个本地 archive 的 exact bytes。
|
||
|
||
### 在 Alpha 阶段实现第二套签名系统
|
||
|
||
拒绝。正式 release workflow 已承担签名和 attestation；Alpha 需要的是诚实、可定位的阶段证据，不应复制生产发布 authority。
|
||
|
||
## 影响
|
||
|
||
- 本地无 evidence 的 archive 不再冒充用户 Alpha，只能按工程候选处理；
|
||
- 手动 milestone artifact 多一个小型 JSON 文件，不增加 Docker archive layer、workspace package、设备常驻 RSS、端口或依赖；
|
||
- 下载者可从 bundle 确定 exact GitHub run/attempt，并验证 evidence 与 image ID/source/architecture 一致；
|
||
- 旧的本地 `2620be05` 与 `4239464a` v1 bundle 保留为历史工程证据，但不能通过 v2 auditor。
|
||
|
||
## 验证
|
||
|
||
- 聚焦测试覆盖 v2 七文件正常物化、非 milestone provenance、detached workflow、archive/SBOM/evidence mutation、额外文件和闭合 CLI grammar；
|
||
- Local operator workflow audit 要求 GitHub workflow identity contexts、evidence input和严格 gate 顺序；
|
||
- `record-verification` 和 `create` 都从 image inspection 绑定两个不同 image ID；offline audit 不调用 Docker或网络；
|
||
- 首个真实可下载 v2 双架构 Trial Kit 仍需维护者授权的 `produce_alpha_artifacts=true` workflow 生成。
|