awoooi/docs/security/SECURITY-APPROVAL-GATE.md

資安人工批准 Gate 契約

項目	內容
日期	2026-05-13
狀態	草案
Schema	docs/schemas/security_approval_gate_v1.schema.json
Snapshot	docs/security/security-approval-gate.snapshot.json
模式	approval_gate_only
runtime 執行授權	false

0. 核心結論

security_approval_gate_v1 是 S3 的第一個框架契約。

它讓 AwoooP 能顯示、排序、記錄人工批准，但不讓批准自動變成執行。

批准後最多只能進入下一步設計、草案、只讀 inventory、低噪音 scope 或人工 exception；任何真正 runtime action 都還需要後續 runtime gate。

S3.1 開始，實際人工決策紀錄由 security_approval_decision_record_v1 保存。S3.2 開始，可用 security_approval_review_packet_v1 把 gate item 包成 review packet。S3.3 開始，決策後 next state 由 security_approval_state_transition_v1 定義。Gate 定義可審項目與批准範圍；Review Packet 協助人工審查；Decision Record 保存決策結果與 audit evidence；State Transition 避免批准被誤解成執行。

1. 目前 Gate 狀態

指標	數量
Gate items	8
Pending human decision	7
Block candidate	1
Approved	0
Runtime actions authorized	false
Immediate execution after approval	false
Raw secret storage authorized	false

2. 建議審查順序

順序	Gate	初期批准範圍
1	Redacted finding ingestion	只批准設計或 draft PR
2	Safe web crawl	只批准低噪音 scope 定義
3	Gitea read-only inventory	只批准只讀 inventory 或 redacted admin export
4	GitHub target decisions	只批准逐 repo 決策草案
5	Ref truth review	只批准人工分類與 reconcile 草案
6	Credentialed scan	只允許人工 exception 設計，仍需 runtime gate
7	Kali full-upgrade / reboot	只允許維護窗口與 rollback 規劃
8	Kali /execute	預設維持 block candidate

3. AwoooP 可做

1. 顯示 gate item、risk、required reviewers 與 evidence refs。
2. 記錄 approve / reject / defer / request more evidence / keep blocked。
3. 將人工決策寫入 Audit evidence。
4. 顯示批准範圍與仍然禁止事項。
5. 提醒哪些項目需要 follow-up runtime gate。
6. 將決策結果寫成 security_approval_decision_record_v1，但維持 execution_authorized=false。
7. 將 gate item 包成 security_approval_review_packet_v1，只顯示 review lane、required reviewers 與仍禁止事項。
8. 依 security_approval_state_transition_v1 顯示 next state；approve_scope 仍只進入 waiting runtime gate。

4. AwoooP 不可做

1. 不自動批准。
2. 不在批准後自動執行。
3. 不把 approval queue 接成 runner。
4. 不啟動 scan、credentialed scan 或 Kali /execute。
5. 不建立 GitHub repo、不改 visibility、不 sync refs、不切 GitHub primary。
6. 不保存 raw secret、token、cookie、private key 或 exploit payload。

5. 階段定位

S3.0 只讓人工批准有一致語言與可稽核格式。

它仍然不是 runtime enforcement，也不是一次把資安等級拉滿。低風險與中風險觀察仍以 observe / warn 為主；只有不可逆或高風險動作才進 gate。