awoooi/docs/security/KALI-SECURITY-MESH-EXECUTION-READINESS.md

# Kali 資訊安全網開工準備

> 日期：2026-05-06（台北時間）
> 狀態：原始規劃；2026-05-13 已完成 Kali 112 live 盤點、低風險主機更新、`security_finding_v1` sample 與 scan scope approval package；2026-06-04 已完成 Kali 112 只讀重驗證，尚未開始 AWOOOI runtime ingestion 實作
> 上游藍圖：`docs/security/KALI-SECURITY-MESH-BLUEPRINT.md`
> AwoooP 同步：`docs/security/AWOOOP-SECURITY-SUPPLYCHAIN-INTEGRATION-HANDOFF.md`

## 0. 目前裁示

統帥已批准繼續推進 Kali 資訊安全網，但明確指示：**先不要開始實作**。

因此本文件只是一份開工準備地圖，用來定義工作包、責任歸屬、閘門、證據與批准邊界。本文件不授權 runtime 變更、部署、更嚴格封鎖、破壞性掃描、credentialed scanning 或自動修復。

2026-05-06 追加長期方向：GitHub 應評估回到雲端主控面，Gitea 降級為本地 mirror / fallback。此項納入本次資安工作包，原因是 source control、CI/CD、Code Review、Codex 接力與部署權限本身就是供應鏈安全邊界。

2026-05-06 追加同步：統帥批准本支線開始推進，並要求立即同步給 AwoooP 工作 Session。本支線已建立 `docs/security/AWOOOP-SECURITY-SUPPLYCHAIN-INTEGRATION-HANDOFF.md`，作為雙 Session 共享契約與邊界文件。

2026-05-13 追加 live 狀態：統帥授權登入 `192.168.0.112` 後，已完成 Kali Scanner API health、service、crontab、Docker service 與更新狀態盤點，並完成 targeted scanner package update 與 `Asia/Taipei` 時區調校。完整紀錄見 `docs/security/KALI-INTEGRATION-STATUS.md`。本追加不代表已批准 active scan、credentialed scan、AWOOOI runtime ingestion、`/execute` 接入、full-upgrade 或 reboot。

2026-05-13 追加契約狀態：已建立 `docs/security/SECURITY-FINDING-CONTRACT.md`、`docs/security/security-finding-kali-sample.snapshot.json`、`docs/security/KALI-SCAN-SCOPE-APPROVAL-PACKAGE.md` 與 `docs/security/kali-scan-scope-approval.snapshot.json`。這代表 scope 與 finding envelope 可被 review / mirror，不代表已批准或執行任何 scan。

2026-06-04 追加只讀重驗證：已用既有 SSH key 讀取 `192.168.0.112` 狀態，確認 scanner `127.0.0.1:8080/health` 回 `200 healthy`、`kali-scanner.service` active / enabled、node-exporter 與 wg-easy 運作中、失敗服務單元為 `networking.service`、待更新套件仍為 1994、服務 hardening 仍為 `0 / 4`。本追加不代表已批准 active scan、credentialed scan、AWOOOI runtime ingestion、`/execute` 接入、full-upgrade、autoremove、reboot 或服務 hardening 套用。

## 1. 非實作邊界

目前允許：

| 允許事項 | 用途 |
|---|---|
| 細化架構與 ownership | 降低後續 coding 前的模糊地帶 |
| 先在文件中定義 schema 與 event contract | 避免 scanner payload 各自為政 |
| 定義 observe-only scan scope | 讓初期 rollout 保持低摩擦 |
| 標出需要批准的事項 | 避免誤觸高風險掃描或封鎖 |
| 準備驗證清單 | 讓後續實作可量測 |
| 盤點 Gitea 到 GitHub 的版本轉移範圍 | 把 source control 與 CI/CD 納入供應鏈安全治理 |

目前不允許：

| 不允許事項 | 原因 |
|---|---|
| 新增或修改 API endpoints | 這已經是實作 |
| 修改 DB migrations 或 models | 需要 schema 決策與 review |
| 修改 NetworkPolicy、firewall、RBAC、CORS 或 secrets | 可能影響 production 連通性或安全邊界 |
| 部署 Kali tools、jobs、cron、exporters 或 alerts | 屬於 runtime 行為變更 |
| 開始 active、exploit 或 credentialed scans | 需要明確批准與 scope |
| 加入 CI/CD blocking gates | 初期資安網必須先觀測 |
| 自動 rotate secrets 或自動關閉 ports | 屬於破壞性或 access-changing 行為 |
| 直接把 GitHub 切成唯一主控 | 必須先完成 Gitea 全量版本盤點、同步、runner 驗證與 rollback plan |

2026-05-13 例外說明：本輪只對既有 Kali 主機做授權登入、狀態盤點、targeted scanner package update、`jq` 安裝與時區調校；沒有新增 scanner job、沒有啟動 scan、沒有修改 AWOOOI runtime endpoint。

## 2. 開工準備閘門

| 閘門 | 問題 | 實作前必備 |
|---|---|---|
| G0 asset scope | 初期 observe-only scope 包含哪些資產？ | 已批准 target list 與 owner map |
| G1 data contract | 正規化 finding envelope 長什麼樣？ | 欄位清單、severity/confidence mapping、dedupe fingerprint |
| G2 storage | 每種 finding 要落到哪裡？ | 對 ADR-090 tables 的 mapping 與是否需新表的決策 |
| G3 safety | 哪些 scan 是 passive、active 或 credentialed？ | 每個 scope 的模式與批准規則 |
| G4 alerting | 哪些 findings 變成 warnings 或 incidents？ | secops taxonomy 與 escalation threshold |
| G5 privacy | 哪些 evidence 可以儲存或顯示？ | secrets、payloads、internal IPs、cookies 的 redaction rules |
| G6 ownership | 每一類 finding 由誰處理？ | 12 Agent ownership 與 human owner mapping |
| G7 rollback | 如何快速停用 scanning/alerts？ | kill switch 或 feature flags 已定義 |
| G8 source control | Gitea 現有專案版本如何完整轉移到 GitHub？ | repo/branch/tag/workflow/webhook/secret inventory 與 SHA 比對計畫 |

## 3. 初期 observe-only scope

先從已知且不需要干擾式探測的資產開始。

| 範圍 | 目標 | 模式 | 備註 |
|---|---|---|---|
| Scanner health | `192.168.0.112:8080` | health-only | 保持現有 `KaliScannerDown` 語意 |
| Host inventory | 110、112、120、121、188、111、168 | passive / read-only | 168 與 111 必須先加入 observe-only dev assets |
| Website perimeter | 公開產品 domains 與 AWOOOI public routes | passive DAST-safe | 只做 TLS/header/basic crawl |
| K8s posture | manifests 與 live read-only K8s metadata | read-only | RBAC、Pod Security、NetworkPolicy coverage |
| Container inventory | Harbor/runtime image list | read-only | 先盤 image metadata；CVE scan 等 schema mapping 完成 |
| Codebase | repo files、manifests、dependencies | local static scan | secrets/SAST/SBOM，不 blocking |
| Source control plane | Gitea repos、GitHub repos、branches、tags、workflows、webhooks | inventory-only | 先做版本與權限盤點，不切主控 |
| Observability tools | Prometheus、Alertmanager、SignOz、Sentry、Grafana、Langfuse | passive exposure review | 不做 admin action |

## 4. Finding contract 草案

第一波 coding 應以這份作為標準契約草案。

| 欄位 | 必填 | 說明 |
|---|---:|---|
| `finding_id` | 是 | 穩定且可重算的 fingerprint |
| `scan_run_id` | 是 | Scanner run 或 ADR-090 discovery run |
| `scanner` | 是 | `kali`、`trivy`、`zap`、`semgrep`、`detect-secrets` 等 |
| `scanner_version` | 否 | 進入 enforcement 後必填 |
| `asset_key` | 是 | 相容 ADR-090 的 asset 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 原始 severity 映射到 platform severity |
| `confidence` | 是 | scanner confidence 或 verifier confidence |
| `status` | 是 | `new`、`confirmed`、`false_positive`、`accepted_risk`、`fixed`、`expired` |
| `recommended_mode` | 是 | `observe`、`warn`、`approve_required`、`block_candidate` |
| `evidence_ref` | 是 | 指向脫敏 evidence，不存 raw exploit 或 secret |
| `summary` | 是 | 人可讀摘要，不能含敏感 payload |
| `recommended_action` | 是 | 初期只作為建議 |
| `owner_team` | 否 | 升級 incident 前必填 |
| `expires_at` | 否 | 暫時 accepted risk 時可用 |

## 5. ADR-090 落點地圖

| Finding 類型 | 主要落點 | 次要落點 | 升級方式 |
|---|---|---|---|
| Port/service exposure | `asset_inventory.metadata`、`asset_compliance_snapshot` | `asset_change_event` | 非預期且重複時才 alert |
| CVE/package/image | `asset_compliance_snapshot(cve_scan)` | `asset_coverage_snapshot(auto_alerting/playbook)` | 超過 threshold 才產生 `CVECritical` |
| Repo/config secret | `asset_compliance_snapshot(secret_rotated or secret_scan)` | `automation_operation_log` | confirmed 後立即 P0 human review |
| TLS/header/web issue | `asset_compliance_snapshot(ssl_cert_valid/web)` | website asset metadata | 先 warning ticket |
| K8s misconfig | `asset_compliance_snapshot(access_reviewed/encryption_at_rest)` | `asset_coverage_snapshot` | SRE/Security review |
| Monitoring blind spot | `asset_coverage_snapshot(auto_monitoring/auto_alerting)` | `alert_rule_catalog` | 僅 coverage gap alert |
| Tool permission risk | `asset_compliance_snapshot(access_reviewed)` | AwoooP policy/gateway audit | approval-required work item |
| Source control drift | `asset_inventory.metadata`、`asset_compliance_snapshot(access_reviewed)` | `automation_operation_log` | Gitea/GitHub SHA 或權限漂移時先 warning |

## 6. 12 Agent 工作包

| Agent | 工作包 | 實作前第一份交付 |
|---|---|---|
| Security Commander | Phase gates 與 escalation policy | 已簽核 observe-only scope |
| Asset Cartographer | Asset taxonomy 與 seed list | 112/111/168 + core assets mapping |
| Kali Orchestrator | Scanner jobs 與 output contract | Scanner-to-finding normalization spec |
| Network Mapper | Port 與 route inventory | Expected vs unexpected exposure table |
| Web Perimeter Agent | Website/API scan policy | Safe crawl 與 TLS/header checklist |
| Code Guardian | SAST/secrets/dependency scope | Repo scan tools 與 false-positive rules |
| Container Supply Agent | Image/SBOM/CVE flow | Harbor/runtime image map |
| K8s Guard | RBAC/PodSecurity/NetworkPolicy review | K8s posture checklist |
| Dev Host Steward | 168/111 observe-only policy | Dev host safe probe boundaries |
| Observability Sentinel | Metrics 與 alert wiring design | warning-only metric names 與 labels |
| Policy Gatekeeper | AwoooP approval/exception model | approve/block promotion criteria |
| Evidence Archivist | Evidence storage 與 redaction | sanitized evidence rules |
| Source Control Migration Steward | Gitea 全量版本盤點與 GitHub primary 遷移設計 | repo/branch/tag/workflow/webhook 對照表 |

## 7. 批准邊界

以下事項必須在未來實作前另外取得明確批准：

| 邊界 | 需要批准的原因 |
|---|---|
| 對 110/111/112/120/121/168/188 做 credentialed host scans | 會使用具權限存取 |
| 對 production websites 做 active DAST | 可能產生流量、噪音或狀態變更 |
| 對 live production 做 exploit verification | 高營運風險 |
| 修改 firewall/NetworkPolicy/RBAC/CORS | 會改變連通性與安全邊界 |
| Secret rotation | 可能中斷整合 |
| CI/CD blocking gates | 可能阻擋 release |
| 超過 ticket/PR draft 的 auto-remediation | 有 side effects |
| 新增付費 scanner/SaaS/provider | 觸發費用批准規則 |
| GitHub primary 切換 | 會改變 source control 主控面、runner、secrets 與部署審批鏈 |

## 8. 第一波程式實作開工清單

只有這份清單被接受後，才能開始實作。

| 檢查項 | 狀態 |
|---|---|
| Observe-only asset scope 已接受 | 草案已建立，待統帥核准實作 |
| `security_finding_v1` envelope 已接受 | 草案與 sample snapshot 已建立，待統帥核准實作 |
| Storage landing map 已接受 | 待確認 |
| 112/111/168 asset classification 已接受 | 草案已納入 `kali_scan_scope_approval_v1`，待統帥核准實作 |
| Redaction policy 已接受 | 草案已建立，禁止 raw secret / token / cookie / private key / exploit payload |
| No-blocking phase boundary 已接受 | 草案已建立，LOW / MEDIUM observation 不升 blocking gate |
| Human approval boundaries 已接受 | 草案已建立，safe crawl / credentialed / `/execute` / runtime ingestion / full-upgrade 分 gate |
| Rollback/disable flag 已命名 | 待確認 |
| Gitea 全量轉 GitHub inventory 已接受 | 待確認 |
| GitHub primary / Gitea mirror rollback plan 已接受 | 待確認 |
| AwoooP mirror-only handoff 已同步 | 已完成 |
| 共享事件 JSON Schema 已建立 | 已完成 |
| Kali 112 live health / update status 已記錄 | 已完成 |

## 9. 未來批准後的第一波實作順序

等未來明確批准開始實作後，建議順序如下：

1. 新增只定義契約的 data model 或 `security_finding_v1` Pydantic schema。
2. 產出 Gitea 全量版本盤點：repositories、branches、tags、workflows、webhooks、secret 名稱、GitHub 對應目標。
3. 在 scanner path 加入 112/111/168 的 host asset seed。
4. 在 feature flag 後新增 Kali result ingestion endpoint 或 adapter。
5. 將已脫敏 findings 存入 ADR-090-compatible snapshots。
6. 在 AIOps KPI 加入 `security_posture` read model。
7. 依 severity/category/asset 輸出 warning-only metrics。
8. 前端只增加 visibility，不增加 action buttons，最多 view/filter。

在自動封鎖、自動修復、active exploit verification、credentialed scans 之前必須停止。