# 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，不阻擋任何部署。