203 lines
14 KiB
Markdown
203 lines
14 KiB
Markdown
# IwoooS 前端資安態勢投影契約
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 日期 | 2026-05-19 |
|
||
| 狀態 | 草案 |
|
||
| Schema | `docs/schemas/iwooos_posture_projection_v1.schema.json` |
|
||
| Snapshot | `docs/security/iwooos-posture-projection.snapshot.json` |
|
||
| 模式 | `mirror_only` |
|
||
| runtime 執行授權 | `false` |
|
||
|
||
## 1. 目的
|
||
|
||
`iwooos_posture_projection_v1` 定義 IwoooS 如何把既有資安網資料投影到前端。
|
||
|
||
它只允許顯示資安態勢、headline progress、framework / runtime landing、non-blocking lanes、evidence refs 與下一個高層 gate。它不是掃描器、不是修復器、不是 approval gate，也不是 GitHub primary cutover 授權。
|
||
|
||
## 2. 來源
|
||
|
||
IwoooS 首版只讀取或對齊以下已提交 evidence：
|
||
|
||
| 來源 | 用途 |
|
||
|------|------|
|
||
| `security_mirror_status_rollup_v1` | 58% headline、36 contracts、0 active runtime gates、下一個高層 gate |
|
||
| `security_rollout_policy_v1` | 7 條 low-friction non-blocking lanes |
|
||
| `source_control_owner_response_validation_rollup_v1` | owner response 仍為 0、S4.9 下一個收件候選 |
|
||
| `kali_integration_status_v1` | Kali 112 observe-only 整合態勢 |
|
||
| `/iwooos` 前端路由 | 顯示入口，不提供執行按鈕 |
|
||
| 既有前端資安頁面 | 只讀索引，不搬移原頁責任邊界、不新增執行控制 |
|
||
|
||
## 3. 前端可顯示
|
||
|
||
1. Security Posture / Exposure 入口。
|
||
2. 58% headline progress 與框架 / runtime landing 判讀。
|
||
3. 36 個主要契約、33 ready、2 partial、1 contract-only、0 blocked。
|
||
4. 0 active runtime gates。
|
||
5. Exposure、source-control、Kali 112、approval boundary 四個面向。
|
||
6. 7 條 non-blocking lanes。
|
||
7. evidence refs 與下一個高層 gate。
|
||
8. 10 個既有前端資安相關頁面索引。
|
||
9. 4 個前端資安責任面與 5 個重疊 / 衝突控制。
|
||
10. 6 個只讀資安處理旅程階段。
|
||
11. 7 個 owner evidence readiness items。
|
||
12. 3 個只讀主機覆蓋 items：Kali 112、開發主機 168、開發主機 111。
|
||
13. 6 個主機動作 gate items：active scan、credentialed scan、Kali `/execute`、SSH / host change、Kali update、runtime blocking control。
|
||
14. 7 個主機 evidence readiness items：scope boundary、owner decision、credential handling、maintenance window、rollback plan、validation metrics、redacted ingestion。
|
||
15. 7 個主機 evidence collection order steps，顯示收件順序與前置依賴。
|
||
|
||
## 3.1 既有前端資安頁面整合
|
||
|
||
S2.10 將前端原本已存在的資安相關頁面收進 IwoooS，只作為 route / source / read-only mode 索引。
|
||
|
||
| Route | 來源 | IwoooS 呈現 |
|
||
|-------|------|-------------|
|
||
| `/security-compliance` | `SecurityPanel` / `CompliancePanel` | 安全合規整合頁 |
|
||
| `/security` | `apps/web/src/app/[locale]/security/page.tsx` | 既有安全監控頁 |
|
||
| `/compliance` | `apps/web/src/app/[locale]/compliance/page.tsx` | 既有合規頁 |
|
||
| `/alerts` | `useIncidents` / `IncidentCard` | 告警管理 |
|
||
| `/errors` | `ErrorsPanel` | 錯誤與 UX 稽核 |
|
||
| `/authorizations` | `LiveApprovalPanel` | HITL / multi-sig 授權中心 |
|
||
| `/governance` | Governance tabs | AI 治理中樞 |
|
||
| `/alert-operation-logs` | Alert operation log page | 告警操作稽核 |
|
||
| `/awooop/approvals` | AwoooP approvals page | AwoooP 審批佇列 |
|
||
| `/code-review` | Code Review page | AI Code Review 控制面 |
|
||
|
||
這些 route 仍保留原本功能與 owner 邊界；IwoooS 只提供可見索引，不把任何頁面升級成 scan、execute、repair、blocking gate、deploy approval 或 runtime authorization。
|
||
|
||
## 3.2 覆蓋與邊界矩陣
|
||
|
||
S2.11 將 10 個既有前端資安頁面分成四個責任面，讓使用者看懂「訊號在哪裡、人工控制在哪裡、治理稽核在哪裡、工程審查在哪裡」。
|
||
|
||
| 責任面 | Route | 邊界 |
|
||
|--------|-------|------|
|
||
| 訊號與暴露面 | `/security-compliance`、`/security`、`/compliance`、`/alerts`、`/errors` | 顯示風險、事件、錯誤、UX audit 與合規訊號，不把 observation 直接升 blocking |
|
||
| 人工控制邊界 | `/authorizations`、`/awooop/approvals` | 顯示 HITL / multi-sig / AwoooP approvals；不等於資安 runtime gate 已批准 |
|
||
| 治理與稽核 | `/governance`、`/alert-operation-logs` | 顯示治理事件、SLO、補救佇列與操作日誌；audit event 不是執行授權 |
|
||
| 工程審查 | `/code-review` | 顯示 AI Code Review pipeline；review 結果可產生 follow-up，不等於 deploy approval |
|
||
|
||
重疊 / 衝突控制：
|
||
|
||
1. IwoooS 保留原 route owner，不搬移資料寫入權。
|
||
2. 覆蓋矩陣不得升級成 runtime gate。
|
||
3. Code Review link 不等於 deploy approval。
|
||
4. AwoooP approval 狀態不等於資安 approval decision record。
|
||
5. 前端索引不得呼叫 Kali active scan 或 `/execute`。
|
||
|
||
## 3.3 資安處理旅程
|
||
|
||
S2.12 將使用者可見的資安處理流程固定為 6 個只讀階段：
|
||
|
||
| 順序 | 階段 | 輸出 |
|
||
|------|------|------|
|
||
| 1 | 讀取目前態勢 | 顯示 posture / progress / gate 狀態，不代表授權 |
|
||
| 2 | 開啟既有資安頁面 | 進入原 route，保留原 owner 與資料邊界 |
|
||
| 3 | 判讀非阻擋分流 | 建 follow-up，不直接升 blocking |
|
||
| 4 | 收 owner evidence | 更新 received / accepted 狀態，不執行 repo / refs / workflow / Kali 動作 |
|
||
| 5 | 等待人工決策 | 需要 decision record，不用 AwoooP approval、Code Review 或進度數字替代 |
|
||
| 6 | 準備後續 runtime gate | 只有人工批准後才另開 follow-up runtime gate；目前 active runtime gates 仍為 0 |
|
||
|
||
這個旅程是 status projection，不是 execution queue。任何 active scan、repair、deploy、GitHub primary、repo / refs / workflow / runner 或 secret 變更，都仍需獨立批准與後續 runtime gate。
|
||
|
||
## 3.4 Owner Evidence Readiness
|
||
|
||
S2.13 將 headline 進度下一步真正需要的 evidence 顯示成只讀 readiness board。
|
||
|
||
| 順序 | Evidence item | 目前狀態 | 解除條件 |
|
||
|------|---------------|----------|----------|
|
||
| 1 | S4.9 Gitea owner attestation response | next collection candidate；received=0、accepted=0 | 收到並接受脫敏 owner response |
|
||
| 2 | S4.10 GitHub target owner response | waiting owner response；received=0、accepted=0 | GitHub target owner response accepted |
|
||
| 3 | S4.11 refs truth owner response | waiting owner response；received=0、accepted=0 | refs truth owner response accepted |
|
||
| 4 | S4.12 workflow / secret name owner response | waiting owner response；received=0、accepted=0 | workflow / secret owner response accepted |
|
||
| 5 | Redacted finding ingestion | approval required；received=0、accepted=0 | 人工批准後接收脫敏 finding |
|
||
| 6 | Kali scan scope approval | approval required；received=0、accepted=0 | scan scope approval + follow-up runtime gate |
|
||
| 7 | Follow-up runtime gate | locked until human decision；active gate=0 | decision record accepted 後另開 runtime gate |
|
||
|
||
這個 board 只說明「還缺什麼」，不代表已收到 evidence、已接受 evidence、已批准、已可掃描、已可修復、已可部署或已可切 GitHub primary。
|
||
|
||
## 3.5 主機覆蓋視圖
|
||
|
||
S2.14 將統帥指定的 Kali 與兩台開發主機放進 IwoooS 的可見資安範圍，讓使用者能看懂哪些主機已被納入後續資安網路徑。
|
||
|
||
| 順序 | 主機 | 角色 | 目前狀態 |
|
||
|------|------|------|----------|
|
||
| 1 | `192.168.0.112` | Kali 資安主機 | 已在 posture / evidence refs 中作為 observe-only integration；active scan、`/execute`、SSH 變更與主機更新仍未批准 |
|
||
| 2 | `192.168.0.168` | 開發主機 | 已宣告為 observe-only scope；credentialed scan 與 runtime control 仍未批准 |
|
||
| 3 | `192.168.0.111` | 開發主機 | 已宣告為 observe-only scope；credentialed scan 與 runtime control 仍未批准 |
|
||
|
||
這個視圖只代表「納入視野」，不代表已啟動掃描、已登入主機、已更新 Kali、已調校主機、已建立 SSH 工作流或已允許 runtime control。
|
||
|
||
## 3.6 主機動作 Gate 矩陣
|
||
|
||
S2.15 將主機相關高風險動作拆成只讀 gate matrix，避免「主機已納入視野」被誤讀成「可以直接掃描、登入、更新或阻擋」。
|
||
|
||
| 順序 | 動作 | 相關主機 | 目前 Gate |
|
||
|------|------|----------|-----------|
|
||
| 1 | Active scan | `192.168.0.112`、`192.168.0.168`、`192.168.0.111` | 需要 S1.6 scan scope approval 與後續 runtime gate |
|
||
| 2 | Credentialed scan | `192.168.0.112`、`192.168.0.168`、`192.168.0.111` | 需要 scope、credential handling 與脫敏 evidence 規範；目前未批准 |
|
||
| 3 | Kali `/execute` | `192.168.0.112` | block candidate；需要人工 decision record 與 S3.4 follow-up runtime gate |
|
||
| 4 | SSH / host change | `192.168.0.112`、`192.168.0.168`、`192.168.0.111` | 需要明確人工批准、變更計畫與 rollback evidence |
|
||
| 5 | Kali host update | `192.168.0.112` | 需要維護窗口、更新清單、驗證指標與 rollback 計畫 |
|
||
| 6 | Runtime blocking control | `192.168.0.112`、`192.168.0.168`、`192.168.0.111` | 需要 accepted decision record；目前 active runtime gates 仍為 0 |
|
||
|
||
每個 item 都固定 `display_mode=gate_only`，且 `active_scan_authorized=false`、`credentialed_scan_authorized=false`、`ssh_change_authorized=false`、`host_update_authorized=false`、`runtime_execution_authorized=false`、`action_buttons_allowed=false`、`not_authorization=true`。
|
||
|
||
## 3.7 主機 Evidence Readiness
|
||
|
||
S2.16 將主機動作解鎖前需要的 evidence 顯示成只讀 readiness board。這一層只回答「要進下一步前缺什麼」，不代表任何 evidence 已收到或已接受。
|
||
|
||
| 順序 | Evidence item | 目前狀態 | 影響範圍 |
|
||
|------|---------------|----------|----------|
|
||
| 1 | Scope boundary | waiting redacted scope approval；received=0、accepted=0 | 112、168、111 的目標、排除範圍、深度與速率 |
|
||
| 2 | Owner decision record | waiting human decision record；received=0、accepted=0 | 人控決策，不可由可見狀態替代 |
|
||
| 3 | Credential handling | credential material collection forbidden；received=0、accepted=0 | credentialed scan 前的憑證來源、保存邊界、遮蔽與拒收規則 |
|
||
| 4 | Maintenance window | waiting maintenance window；received=0、accepted=0 | Kali update、SSH / host change 與主機調校窗口 |
|
||
| 5 | Rollback plan | waiting rollback plan；received=0、accepted=0 | 套件、設定、服務、工具鏈版本回復 |
|
||
| 6 | Validation metrics | waiting post-check metrics；received=0、accepted=0 | 掃描器、監控、服務與使用者流程 post-check |
|
||
| 7 | Redacted ingestion | waiting redacted payload acceptance；received=0、accepted=0 | finding / scan result 只能以脫敏摘要進 mirror |
|
||
|
||
每個 item 都固定 `display_mode=evidence_readiness_only`，且 `active_scan_authorized=false`、`credentialed_scan_authorized=false`、`ssh_change_authorized=false`、`host_update_authorized=false`、`runtime_execution_authorized=false`、`action_buttons_allowed=false`、`not_authorization=true`。
|
||
|
||
## 3.8 主機 Evidence 收件順序
|
||
|
||
S2.17 將 S2.16 的七個主機 evidence readiness items 排成建議收件順序。這一層只回答「先收哪個、下一個依賴什麼」，不把任何 evidence 標成 received / accepted。
|
||
|
||
| 順序 | 收件步驟 | Source item | 前置依賴 | 狀態 |
|
||
|------|----------|-------------|----------|------|
|
||
| 1 | 先定義 scope boundary | `host_scope_boundary_evidence` | 無 | `next_collection_candidate`；received=0、accepted=0 |
|
||
| 2 | 再收 owner decision | `host_owner_decision_record_evidence` | `collect_scope_boundary_first` | `waiting_previous_step`；received=0、accepted=0 |
|
||
| 3 | 隔離 credential handling | `host_credential_handling_evidence` | `collect_owner_decision_second` | `waiting_previous_step`；received=0、accepted=0 |
|
||
| 4 | 安排 maintenance window | `host_maintenance_window_evidence` | `collect_owner_decision_second` | `waiting_previous_step`；received=0、accepted=0 |
|
||
| 5 | 補 rollback plan | `host_rollback_plan_evidence` | `collect_maintenance_window_fourth` | `waiting_previous_step`；received=0、accepted=0 |
|
||
| 6 | 定義 validation metrics | `host_validation_metrics_evidence` | `collect_rollback_plan_fifth` | `waiting_previous_step`；received=0、accepted=0 |
|
||
| 7 | 最後才收 redacted ingestion | `host_redacted_ingestion_evidence` | `collect_validation_metrics_sixth` | `waiting_previous_step`；received=0、accepted=0 |
|
||
|
||
每個 step 都固定 `display_mode=collection_order_only`，且 `runtime_execution_authorized=false`、`action_buttons_allowed=false`、`not_authorization=true`。
|
||
|
||
這個順序是收件提示，不是工作佇列。不得因為某個 step 顯示為下一個候選，就啟動 scan、SSH、Kali update、raw payload ingestion、runtime blocking control，或把對應 evidence 標成已收到 / 已接受。
|
||
|
||
## 4. 仍禁止
|
||
|
||
IwoooS 不得提供下列輸出：
|
||
|
||
1. scan / execute / repair button。
|
||
2. repo creation、visibility change、refs sync / delete / force push。
|
||
3. workflow / webhook / runner / deploy key / branch protection / repository secret 修改。
|
||
4. GitHub primary switch 或 Gitea disable。
|
||
5. production deploy 或 runtime enforcement。
|
||
6. SSH 到主機、開 SSH session、更新 Kali、package upgrade、credentialed scan 或 active scan。
|
||
7. 套用 runtime blocking control。
|
||
8. 將主機 evidence 標記為 received / accepted，或匯入 raw host evidence。
|
||
9. 推進 host collection state 或跳過 host evidence dependency。
|
||
10. 把 58% progress、contract count、mirror readiness 或前端可見狀態當成授權。
|
||
|
||
## 5. 驗證
|
||
|
||
只讀驗證：
|
||
|
||
```text
|
||
python3 scripts/security/security-mirror-progress-guard.py
|
||
```
|
||
|
||
這個 guard 會確認 IwoooS 投影與 rollup / rollout policy 對齊，且 `runtime_execution_authorized=false`、`action_buttons_allowed=false`、`not_authorization=true`。
|