17 KiB
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. 前端可顯示
- Security Posture / Exposure 入口。
- 58% headline progress 與框架 / runtime landing 判讀。
- 36 個主要契約、33 ready、2 partial、1 contract-only、0 blocked。
- 0 active runtime gates。
- Exposure、source-control、Kali 112、approval boundary 四個面向。
- 7 條 non-blocking lanes。
- evidence refs 與下一個高層 gate。
- 10 個既有前端資安相關頁面索引。
- 4 個前端資安責任面與 5 個重疊 / 衝突控制。
- 6 個只讀資安處理旅程階段。
- 7 個 owner evidence readiness items。
- 3 個只讀主機覆蓋 items：Kali 112、開發主機 168、開發主機 111。
- 6 個主機動作 gate items：active scan、credentialed scan、Kali
/execute、SSH / host change、Kali update、runtime blocking control。 - 7 個主機 evidence readiness items：scope boundary、owner decision、credential handling、maintenance window、rollback plan、validation metrics、redacted ingestion。
- 7 個主機 evidence collection order steps，顯示收件順序與前置依賴。
- 7 個主機 evidence intake preflight checks，顯示未來 evidence 進人工 review 前的拒收 / 隔離規則。
- 7 個主機 evidence review outcome lanes，顯示 preflight 後的人工審查分流結果。
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 |
重疊 / 衝突控制：
- IwoooS 保留原 route owner，不搬移資料寫入權。
- 覆蓋矩陣不得升級成 runtime gate。
- Code Review link 不等於 deploy approval。
- AwoooP approval 狀態不等於資安 approval decision record。
- 前端索引不得呼叫 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 標成已收到 / 已接受。
3.9 主機 Evidence Intake Preflight
S2.18 將主機 evidence 進人工 review 前的預檢條件顯示成只讀規則。這一層只回答「未來 evidence 送進來前要先擋什麼」，不接收 payload、不驗收 evidence、不推進 counters。
| 順序 | 預檢項目 | 拒收 / 隔離條件 | 目前狀態 |
|---|---|---|---|
| 1 | Metadata pointer only | 缺 redacted metadata pointer | preflight_ready_not_executed；received=0、accepted=0 |
| 2 | Collection order match | 跳過 S2.17 前置依賴 | dependency_check_waiting_evidence；received=0、accepted=0 |
| 3 | Scope before scan | scan evidence 沒有 scope boundary | waiting_scope_evidence；received=0、accepted=0 |
| 4 | Owner before host change | SSH / update / tuning / blocking evidence 缺 owner decision pointer | waiting_owner_decision_pointer；received=0、accepted=0 |
| 5 | Credential plaintext blocked | 出現帳密、token、private key、session 或憑證明文 | plaintext_credential_collection_forbidden；received=0、accepted=0 |
| 6 | Raw payload blocked | 出現完整掃描 raw output、未脫敏 finding、host dump 或 log bundle | raw_payload_collection_forbidden；received=0、accepted=0 |
| 7 | Frontend counters frozen | 前端嘗試推進 received / accepted | frontend_counter_transition_forbidden；received=0、accepted=0 |
每個 check 都固定 display_mode=intake_preflight_only、raw_payload_allowed=false、secret_value_collection_allowed=false、runtime_execution_authorized=false、action_buttons_allowed=false、not_authorization=true。
這個 preflight board 不代表已收到任何主機 evidence，也不代表已進人工 review。真正收件仍需要脫敏 evidence pointer、owner decision 與後續人工驗收。
3.10 主機 Evidence Review Outcome Lanes
S2.19 將主機 evidence 通過 preflight 後可能進入的人工審查結果分流顯示成只讀 lanes。這一層只回答「下一步該補什麼或顯示什麼結果」，不建立 approval record、不啟動 runtime gate、不改 received / accepted。
| 順序 | Outcome lane | 來源預檢 | 下一步 |
|---|---|---|---|
| 1 | Ready for human review | metadata pointer、dependency order、scope、owner decision | 顯示人工審查候選；received=0、accepted=0 |
| 2 | Needs scope evidence | scope before scan | 補脫敏 scope boundary pointer，不進 scan |
| 3 | Needs owner decision | owner before host change | 補 owner decision record pointer，不啟動主機動作 |
| 4 | Quarantine dependency skip | collection order match | 顯示隔離原因，不推 counter |
| 5 | Reject raw payload | raw payload blocked | 要求改交脫敏摘要 |
| 6 | Reject credential plaintext | credential plaintext blocked | 不保存、不轉送、不顯示憑證明文 |
| 7 | Waiting runtime gate | frontend counters frozen、owner decision | 人工審查後仍需另開 runtime gate；active runtime gates=0 |
每個 lane 都固定 display_mode=review_outcome_only、received_count=0、accepted_count=0、approval_record_created=false、runtime_execution_authorized=false、action_buttons_allowed=false、not_authorization=true。
這個 outcome board 不代表 evidence 已進 review、approval record 已建立或任何主機操作可執行。它只讓使用者理解「預檢後可能被導向哪一類人審結果」。
4. 仍禁止
IwoooS 不得提供下列輸出：
- scan / execute / repair button。
- repo creation、visibility change、refs sync / delete / force push。
- workflow / webhook / runner / deploy key / branch protection / repository secret 修改。
- GitHub primary switch 或 Gitea disable。
- production deploy 或 runtime enforcement。
- SSH 到主機、開 SSH session、更新 Kali、package upgrade、credentialed scan 或 active scan。
- 套用 runtime blocking control。
- 將主機 evidence 標記為 received / accepted，或匯入 raw host evidence。
- 推進 host collection state 或跳過 host evidence dependency。
- 未通過 preflight 就接受 host evidence。
- 收集 host credential plaintext、ingest host raw payload，或由前端推進 host evidence counters。
- 從 review outcome lane 建立 host approval record、把 review lane 當 runtime gate，或把 review outcome 標成 accepted。
- 把 58% progress、contract count、mirror readiness 或前端可見狀態當成授權。
5. 驗證
只讀驗證：
python3 scripts/security/security-mirror-progress-guard.py
這個 guard 會確認 IwoooS 投影與 rollup / rollout policy 對齊，且 runtime_execution_authorized=false、action_buttons_allowed=false、not_authorization=true。