awoooi/docs/security/CD-RUNNER-SECRET-INJECTION-CHANGE-EVIDENCE-ACCEPTANCE.md

# CD / Runner / Secret 注入變更證據驗收只讀帳本

| 項目 | 內容 |
|------|------|
| 日期 | 2026-06-15 |
| 狀態 | `change_evidence_acceptance_ledger_ready_no_runtime_action` |
| 工具 | `scripts/security/cd-runner-secret-injection-change-evidence-acceptance.py` |
| Snapshot | `docs/security/cd-runner-secret-injection-change-evidence-acceptance.snapshot.json` |
| Source evidence | `docs/security/source-control-workflow-secret-name-local-evidence.snapshot.json` |
| Source export request | `docs/security/source-control-workflow-secret-name-export-request.snapshot.json` |
| Source owner response | `docs/security/source-control-workflow-secret-name-owner-response.snapshot.json` |
| runtime gate | `0` |

## 1. 目的

此帳本補在 workflow / runner / secret 名稱 inventory、redacted export request 與 owner response 收件包之後，專門驗收「CD / runner / secret injection 變更證據」是否足夠進入 reviewer acceptance。

它只處理 metadata-only evidence ref，不呼叫 Gitea / GitHub API、不讀 secret store、不讀 secret value、不修改 workflow、不啟用 runner、不 rotate secret、不 dispatch workflow、不觸發部署，也不把 deploy marker、Gitea Actions success、AwoooP approval 或 UI 可見狀態當成 runtime 授權。

## 2. 固定範圍

| 指標 | 數值 | 解讀 |
|------|------|------|
| `change_evidence_candidate_count` | `5` | CD pipeline、Code Review、Deploy alerts、Runner attestation、Secret parity 五類候選 |
| `c0_change_evidence_candidate_count` | `4` | CD、Code Review、Runner、Secret parity 為 C0 |
| `c1_change_evidence_candidate_count` | `1` | Deploy alerts / monitoring route 為 C1 |
| `write_capable_candidate_count` | `5` | 五類都可能影響 workflow、runner、secret injection、通知或部署路徑 |
| `local_workflow_file_count` | `33` | 本機只讀 workflow evidence 數 |
| `gitea_workflow_file_count` | `12` | Gitea workflow evidence 數 |
| `github_workflow_file_count` | `21` | GitHub workflow evidence 數 |
| `local_referenced_secret_name_count` | `42` | 只保存 secret 名稱，不保存 value |
| `runner_label_count` | `5` | `awoooi-host`、`harbor`、`k8s`、`self-hosted`、`ubuntu-latest` |
| `export_request_count` | `9` | 九個 in-scope repo 仍需 owner / read-only export |
| `export_lane_count` | `5` | webhook、runner、deploy key、branch protection / CODEOWNERS、secret name parity |
| `required_evidence_field_count` | `19` | 變更證據必填欄位 |
| `reviewer_check_count` | `19` | reviewer 必檢規則 |
| `outcome_lane_count` | `8` | 收件結果分流 |
| `blocked_action_count` | `32` | 明確禁止動作 |

## 3. 必填變更證據欄位

1. `proposed_workflow_or_config_change_ref`
2. `workflow_diff_ref`
3. `runner_attestation_ref`
4. `secret_name_parity_ref`
5. `secret_injection_route_ref`
6. `deploy_marker_readback_ref`
7. `gitea_action_run_ref`
8. `guard_result_ref`
9. `log_redaction_review_ref`
10. `notification_route_owner_ref`
11. `blast_radius`
12. `maintenance_window`
13. `rollback_owner`
14. `rollback_plan_ref`
15. `postcheck_evidence_ref`
16. `affected_scope`
17. `redacted_evidence_refs`
18. `reviewer_outcome`
19. `not_approval`

以上欄位都只能保存脫敏 ref、commit、artifact pointer、run id、job id、ticket 或 hash。不得貼 secret value、secret hash、masked token、partial token、runner token、webhook secret、private key、deploy key private material、cookie、authorization header、完整 credential URL 或未脫敏截圖。

## 4. Reviewer checks

| Check | 用途 |
|------|------|
| `change_ref_present` | 確認有 proposed workflow / config / policy change ref |
| `workflow_diff_ref_only` | 確認只收 workflow diff ref 或 committed patch ref |
| `gitea_actions_run_readback_ref_shape` | 確認 Gitea Actions readback 只保存 run / job / status ref |
| `deploy_marker_not_runtime_approval` | deploy marker 只能當部署證據，不代表 runtime approval |
| `runner_owner_attestation_present` | runner label、executor、host alias、owner 與維護窗口可追溯 |
| `hosted_minutes_risk_review_present` | hosted runner 額度與供應鏈風險需獨立 review |
| `secret_name_parity_ref_only` | secret parity 只能保存名稱、scope、present-absent 與 owner metadata |
| `no_secret_value_or_hash` | 確認沒有 secret value、hash、partial token 或 credential derivative |
| `secret_injection_path_called_out` | 涉及 CD / K8s secret injection 時標出 injection path 與 owner |
| `step_env_with_secret_guard_result_present` | 必須有 `check-gitea-step-env-secrets` 或等價 guard result |
| `telegram_route_owner_present` | 通知路徑必須確認 SRE route owner，不得新增 legacy route |
| `deploy_key_and_webhook_material_absent` | 不保存 webhook secret、deploy key private material、runner token 或 write token |
| `branch_protection_or_required_checks_impact_called_out` | 影響 required checks / CODEOWNERS / branch protection 時需標出影響 |
| `blast_radius_present` | 標出 repo、workflow、runner、secret metadata、notification、deploy path 影響 |
| `maintenance_window_present` | future workflow / runner / secret injection 變更需獨立維護窗口 |
| `rollback_owner_present` | rollback owner 與回復方式必須可追溯 |
| `postcheck_evidence_present` | 需有 guard result、run status、route smoke 或 notification receipt ref |
| `no_execution_claim` | 不把帳本、owner response、CD success 或 AwoooP approval 當執行批准 |
| `cross_project_sync_noted` | 影響 AwoooP、IwoooS、代理賞金協議、監控或公開服務時需跨專案同步 ref |

## 5. Outcome lanes

| Lane | 說明 |
|------|------|
| `waiting_change_evidence` | 尚未收到 CD / runner / secret injection 變更證據 |
| `quarantine_sensitive_payload` | 收到敏感值、runner token、webhook secret、private key 或未脫敏截圖時隔離 |
| `reject_unredacted_or_runtime_claim` | 出現未脫敏 payload 或把 evidence 誤當執行批准時拒收 |
| `request_supplement` | 缺 workflow diff、runner owner、secret parity、guard result、rollback 或 post-check 時補件 |
| `ready_for_reviewer_acceptance` | metadata 合格後進 reviewer acceptance |
| `ready_for_runtime_approval_package` | reviewer 接受後只能形成 runtime approval package |
| `waiting_maintenance_window` | future workflow / runner / secret injection 仍需獨立維護窗口 |
| `waiting_runtime_gate` | change evidence accepted 後 runtime gate 仍等待獨立人工批准 |

## 6. 禁止動作

此帳本明確禁止修改 workflow、未批准 dispatch workflow、啟用或重啟 runner、修改 runner label、使用 runner admin token、啟用 GitHub hosted runner、收集 secret value / hash / partial token、建立 / 更新 / rotate / 刪除 repo secret、讀 secret store、修改 secret injection path、修改 webhook、修改 webhook secret、修改 deploy key、修改 branch protection、修改 CODEOWNERS、sync refs、force push、切 GitHub primary、停用 Gitea、把 CD pipeline 當 action 執行、注入 K8s secret、ArgoCD sync、production deploy 或新增 action button。

## 7. 完成度與邊界

| 工作 | 完成度 | 邊界 |
|------|--------|------|
| CD / Runner / Secret injection change evidence acceptance artifact | `100%` | 只讀帳本與 snapshot 已建立 |
| Gitea workflow / runner source-control 只讀治理成熟度 | `70% -> 72%` | 只代表變更證據驗收規則補齊，不代表 workflow / runner 可修改 |
| Secret metadata 只讀治理成熟度 | `66% -> 68%` | 只代表 secret name / injection owner evidence gate 補齊，不代表可讀或可改 secret |
| change evidence received / accepted | `0%` | 尚未收到或接受任何變更證據 |
| runtime approval package | `0%` | 尚未形成 runtime approval package |
| active runtime gate | `0` | 不開 workflow、runner、secret、deploy、ArgoCD 或 production action |

## 8. 下一步

1. 要求 owner 只提供 workflow diff ref、runner attestation ref、secret name parity ref、secret injection route ref、Gitea run readback ref、guard result ref、rollback owner 與 post-check evidence。
2. reviewer 只檢查 metadata 完整性、no-secret-value 與 no-execution-claim，不保存 raw workflow payload 或 credential material。
3. 若未來要進 runtime approval package，必須另開維護窗口、rollback owner、跨專案同步與 production post-check gate。