awoooi/docs/security/SECURITY-FINDING-CONTRACT.md

Security Finding v1 契約

項目	內容
日期	2026-05-13
狀態	草案，供 AwoooP mirror-only 消費
Schema	docs/schemas/security_finding_v1.schema.json
Sample snapshot	docs/security/security-finding-kali-sample.snapshot.json
原則	只保存脫敏 finding 摘要，不保存 raw secret、token、cookie、private key 或 exploit payload

0. 核心結論

security_finding_v1 是 Kali、Trivy、ZAP、Semgrep、detect-secrets、kube posture 等工具的共同 finding envelope。

初期它只做三件事：

1. 讓 findings 有穩定格式與可追溯 evidence ref。
2. 讓 AwoooP 可以 mirror 成 Runtime State / Channel Event / Audit。
3. 讓高風險項目產生 approval candidate，而不是直接執行修復。

它不授權 active scan、不授權 credentialed scan、不授權阻擋部署、不授權自動修復。

1. 必填欄位

欄位	說明
finding_id	穩定且可重算的 fingerprint，避免重複告警
scan_run_id	來源掃描或人工盤點批次
scanner	kali、trivy、zap、semgrep、detect-secrets、kube-bench、manual 或 other
asset_key	對齊 ADR-090 / Security Supply Chain 的資產 key
target_type	host、website、api_endpoint、container、package、repo、k8s_resource 或 tool
target	已脫敏 target identifier
category	exposure、cve、secret、misconfig、auth、tls、web、code、supply_chain 或 network
severity	scanner 初判嚴重度
confidence	scanner 或 reviewer 初判信心
recommended_mode	observe、warn、approve_required 或 block_candidate
evidence_ref	指向已脫敏 evidence，不存敏感原文
summary	繁體中文摘要
recommended_action	初期只作建議，不直接執行

2. 低摩擦模式對照

條件	recommended_mode	初期處理
LOW / MEDIUM 且信心不高	observe	mirror + 週期 review
MEDIUM 且有明確 owner	warn	建 follow-up，不阻擋部署
HIGH / CRITICAL、credential、RBAC、firewall、NetworkPolicy、secret rotation	approve_required	產生 approval candidate，人工核准後才進下一步
raw secret、無 rollback 的破壞性動作、/execute 類命令執行	block_candidate	預設不執行，只能走人工 exception

3. AwoooP 消費邊界

AwoooP 可以：

1. mirror 脫敏 finding 摘要。
2. 顯示 severity、confidence、asset、owner、recommended mode。
3. 建立 approval candidate。
4. 串到 Audit evidence 與 Channel Event。

AwoooP 不可以：

1. 直接啟動 Kali scan。
2. 直接呼叫 Kali /execute。
3. 自動 patch、merge、deploy 或 rotate secret。
4. 將 LOW / MEDIUM observation 變成 blocking gate。
5. 保存 raw secret、token、cookie、private key 或 exploit payload。

4. 第一個 sample

docs/security/security-finding-kali-sample.snapshot.json 只是一筆 contract sample，用來驗證 schema 與 AwoooP mirror 欄位，不代表已經接通 runtime ingestion。

目前 sample 取自 Kali 112 live 盤點中的 Harbor image scan failure 類型，已脫敏為 supply-chain warning，不阻擋任何部署。