72 lines
3.2 KiB
Markdown
72 lines
3.2 KiB
Markdown
# 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，不阻擋任何部署。
|