feat(iwooos): tighten Wazuh owner evidence preflight

2026-06-25 18:33:42 +08:00
parent 82a6138275
commit 856fbcddb9
4 changed files with 89 additions and 9 deletions
--- a/docs/LOGBOOK.md
+++ b/docs/LOGBOOK.md
@@ -1,3 +1,30 @@
+## 2026-06-25｜Wazuh owner evidence 預檢補上 Dashboard API 分欄
+
+**背景**：Wazuh Dashboard 可進入且 index pattern 三項通過，但 API connection 仍卡住、API version 尚未驗證。若 owner evidence 仍只收單一 `dashboard_api_status_ref`，後續容易把「索引可讀」誤當成「Wazuh API / registry 已恢復」。
+
+**本輪更新**：
+- `scripts/security/wazuh-agent-visibility-owner-evidence-preflight.py` 加嚴 owner evidence 必填欄位，新增 `dashboard_api_connection_check_status`、`dashboard_api_version_check_status`、`dashboard_index_pattern_statuses`、`dashboard_api_degradation_root_cause`、`dashboard_api_repair_postcheck_ref`。
+- Reviewer checks 從 `10` 增加到 `15`，明確要求 API connection、API version、index pattern、manager registry counts 與 IwoooS readback 分開驗收。
+- Outcome lanes 從 `5` 增加到 `8`，新增 `request_dashboard_api_status_supplement`、`request_dashboard_api_repair_postcheck`、`reject_index_pattern_only_green`。
+- Forbidden payloads 從 `18` 增加到 `22`，補上 raw dashboard request、Dashboard API secret、stored API password、API token。
+- `docs/security/WAZUH-AGENT-VISIBILITY-OWNER-EVIDENCE-PREFLIGHT.md` 與 committed snapshot 已同步。
+
+**驗證**：
+- `python3 scripts/security/wazuh-agent-visibility-owner-evidence-preflight.py --root .`：`fields=28 checks=15 aliases=6 export_received=0 received=0 accepted=0 runtime_gate=0`。
+- `python3 scripts/security/wazuh-agent-visibility-runtime-gate.py --root .`：`registry=0 route=200 transport=6 dashboard_degraded=1 api_connection=pending_or_spinning index_ok=3 runtime_gate=0`。
+- `python3 scripts/security/security-mirror-progress-guard.py --root .` 通過。
+- `python3 -m py_compile scripts/security/wazuh-agent-visibility-owner-evidence-preflight.py scripts/security/wazuh-agent-visibility-runtime-gate.py` 通過。
+- `python3 scripts/ops/doc-secrets-sanity-check.py ...` 與 `git diff --check` 通過。
+
+**完成度同步**：
+- Wazuh owner evidence 收件預檢：`100%` source-side。
+- Dashboard API 分欄驗收規格：`100%` source-side。
+- Owner evidence received / accepted：`0 / 0`。
+- Wazuh manager registry accepted：`0%`。
+- Wazuh API live query / active response / host write / secret collection / runtime gate：`0% / false`。
+
+**邊界**：本輪沒有連線 Wazuh、沒有 SSH、沒有讀 secret、沒有保存 raw dashboard request、沒有修改 Dashboard stored API、沒有重新註冊 agent、沒有重啟服務、沒有改 Nginx / firewall / Docker / K8s，也沒有 active scan、active response 或 host write。
+
 ## 2026-06-25｜Wazuh Dashboard API Gate 正式站驗證完成

 **背景**：前一筆已把 Wazuh Dashboard 啟動畫面納入 source-side Gate；本輪追到正式部署 marker 後，補齊 `/zh-TW/iwooos` 桌機與手機 production readback，確認前台不再把 Dashboard 可見誤報成 Wazuh 可用。
--- a/docs/security/WAZUH-AGENT-VISIBILITY-OWNER-EVIDENCE-PREFLIGHT.md
+++ b/docs/security/WAZUH-AGENT-VISIBILITY-OWNER-EVIDENCE-PREFLIGHT.md
@@ -29,6 +29,11 @@ Wazuh 用戶端消失事故不能用 Dashboard 畫面、代理服務在線、TCP
 - `registry_export_summary_ref`
 - `manager_health_ref`
 - `dashboard_api_status_ref`
+- `dashboard_api_connection_check_status`
+- `dashboard_api_version_check_status`
+- `dashboard_index_pattern_statuses`
+- `dashboard_api_degradation_root_cause`
+- `dashboard_api_repair_postcheck_ref`
 - `redacted_evidence_refs`
 - `followup_owner`
 - `rollback_owner`
@@ -43,6 +48,11 @@ Wazuh 用戶端消失事故不能用 Dashboard 畫面、代理服務在線、TCP
 - `per_host_registry_matrix` 每列只能使用公開別名，不得包含內網位址、agent 原名或 raw payload。
 - `last_seen` 時間窗需能覆蓋事故觀察區間。
 - manager health ref 與 dashboard API status ref 不可互相替代。
+- Dashboard API connection 若仍是 pending / spinning，不得接受為 Wazuh 可用。
+- Dashboard API version 必須獨立驗證；index pattern 三綠勾不可替代 API version。
+- index pattern 已通過只能代表索引 pattern 可讀，不可替代 manager registry counts。
+- Dashboard API 退化根因必須至少分類為 stored API、RBAC / run_as、rate-limit、TLS trust 或 readonly account scope 其中之一。
+- Dashboard API repair postcheck 必須包含 API connection、API version、manager registry counts 與 IwoooS readback。
 - redacted evidence refs 不得包含 raw payload、截圖原文或主機完整輸出。
 - owner decision 不可直接授權 active response、host write 或 secret rotation。
 - rollback owner 與 postcheck plan 必須存在。
@@ -54,6 +64,7 @@ Wazuh 用戶端消失事故不能用 Dashboard 畫面、代理服務在線、TCP
 - raw Wazuh payload、raw log、完整 journal、未脫敏截圖。
 - agent 原名、內網位址、完整主機輸出。
 - authorization header、token、basic auth、password、cookie、private key、client key。
+- raw dashboard request、Dashboard API secret、stored API password、API token。
 - 夾帶 active response、host write、firewall change、Nginx reload 或其他 runtime 操作要求。

 ## Manager registry 脫敏匯出契約
@@ -91,20 +102,22 @@ Wazuh manager registry 才是判定「所有用戶端是否仍在」的主要來
 - 只允許公開節點別名，不允許內網位址、主機原名或 agent 原名。
 - agent id 僅能用不可逆 evidence ref，不得放完整值、雜湊、前後綴或 client key。
 - 每個缺口必須有 gap reason，不得以 Dashboard 空白或口頭說明補成綠燈。
+- Dashboard API connection / version / index pattern 必須分欄呈現，不得合併成單一 healthy。
+- Dashboard API 修復證明只能收脫敏 ref，不得收 stored API secret、token、密碼或完整 request。
 - 只收計數、狀態桶、時間窗與證據 ref，不收 raw API payload、完整 CLI output 或截圖原文。

 ## 現況計數

 | 項目 | 計數 |
 |---|---:|
-| 必要欄位 | `23` |
-| Reviewer 檢查 | `10` |
+| 必要欄位 | `28` |
+| Reviewer 檢查 | `15` |
 | 公開節點別名 | `6` |
 | 逐主機必填欄位 | `9` |
 | Registry export received | `0` |
 | Registry export accepted | `0` |
-| Outcome lanes | `5` |
-| Forbidden payloads | `18` |
+| Outcome lanes | `8` |
+| Forbidden payloads | `22` |
 | Owner evidence received | `0` |
 | Owner evidence accepted | `0` |
 | Runtime gate | `0` |
@@ -118,7 +131,7 @@ python3 scripts/security/wazuh-agent-visibility-owner-evidence-preflight.py --ro
 預期：

 ```text
-WAZUH_AGENT_VISIBILITY_OWNER_EVIDENCE_PREFLIGHT_OK fields=23 checks=10 aliases=6 export_received=0 received=0 accepted=0 runtime_gate=0
+WAZUH_AGENT_VISIBILITY_OWNER_EVIDENCE_PREFLIGHT_OK fields=28 checks=15 aliases=6 export_received=0 received=0 accepted=0 runtime_gate=0
 ```

 ## 邊界
--- a/docs/security/wazuh-agent-visibility-owner-evidence-preflight.snapshot.json
+++ b/docs/security/wazuh-agent-visibility-owner-evidence-preflight.snapshot.json
@@ -25,6 +25,10 @@
    "cookie",
    "private_key",
    "client_keys",
+    "raw_dashboard_request",
+    "dashboard_api_secret",
+    "stored_api_password",
+    "api_token",
    "active_response_enable",
    "host_write",
    "firewall_change",
@@ -36,6 +40,7 @@
    "agent service active、TCP 連線存在、Dashboard 可見或口頭宣稱都不可替代 manager registry counts。",
    "逐主機 registry export 必須使用固定公開節點別名與狀態桶，不能把 agent 原名或內網識別資訊帶到前台。",
    "若 evidence 夾帶 raw log、未脫敏截圖、內網位址、agent 原名或 secret，必須隔離，不得渲染到前台。",
+    "Dashboard index pattern 三綠勾不可替代 API connection、API version 或 manager registry 驗收。",
    "任何 active response、host write、firewall、Nginx、Docker、K8s 或 secret 變更都要切獨立人工批准。"
  ],
  "outcome_lanes": [
@@ -43,6 +48,9 @@
    "request_missing_fields",
    "quarantine_sensitive_payload",
    "reject_runtime_action_request",
+    "request_dashboard_api_status_supplement",
+    "request_dashboard_api_repair_postcheck",
+    "reject_index_pattern_only_green",
    "ready_for_reviewer_validation"
  ],
  "registry_export_contract": {
@@ -73,6 +81,8 @@
      "只允許公開節點別名，不允許內網位址、主機原名或 agent 原名。",
      "agent id 僅能用不可逆 evidence ref，不得放完整值、雜湊、前後綴或 client key。",
      "每個缺口必須有 gap reason，不得以 Dashboard 空白或口頭說明補成綠燈。",
+      "Dashboard API connection / version / index pattern 必須分欄呈現，不得合併成單一 healthy。",
+      "Dashboard API 修復證明只能收脫敏 ref，不得收 stored API secret、token、密碼或完整 request。",
      "只收計數、狀態桶、時間窗與證據 ref，不收 raw API payload、完整 CLI output 或截圖原文。"
    ],
    "registry_export_accepted_count": 0,
@@ -98,6 +108,11 @@
    "registry_export_summary_ref",
    "manager_health_ref",
    "dashboard_api_status_ref",
+    "dashboard_api_connection_check_status",
+    "dashboard_api_version_check_status",
+    "dashboard_index_pattern_statuses",
+    "dashboard_api_degradation_root_cause",
+    "dashboard_api_repair_postcheck_ref",
    "redacted_evidence_refs",
    "followup_owner",
    "rollback_owner",
@@ -111,6 +126,11 @@
    "per_host_registry_matrix 每列只能使用公開別名，不得包含內網位址、agent 原名或 raw payload。",
    "last_seen 時間窗需能覆蓋事故觀察區間。",
    "manager health ref 與 dashboard API status ref 不可互相替代。",
+    "Dashboard API connection 若仍是 pending / spinning，不得接受為 Wazuh 可用。",
+    "Dashboard API version 必須獨立驗證；index pattern 三綠勾不可替代 API version。",
+    "index pattern 已通過只能代表索引 pattern 可讀，不可替代 manager registry counts。",
+    "Dashboard API 退化根因必須至少分類為 stored API、RBAC / run_as、rate-limit、TLS trust 或 readonly account scope 其中之一。",
+    "dashboard API repair postcheck 必須包含 API connection、API version、manager registry counts 與 IwoooS readback。",
    "redacted evidence refs 不得包含 raw payload、截圖原文或主機完整輸出。",
    "owner decision 不可直接授權 active response、host write 或 secret rotation。",
    "rollback owner 與 postcheck plan 必須存在。"
@@ -121,9 +141,9 @@
  "summary": {
    "active_response_authorized_count": 0,
    "expected_scope_alias_count": 6,
-    "forbidden_payload_count": 18,
+    "forbidden_payload_count": 22,
    "host_write_authorized_count": 0,
-    "outcome_lane_count": 5,
+    "outcome_lane_count": 8,
    "owner_evidence_accepted_count": 0,
    "owner_evidence_quarantined_count": 0,
    "owner_evidence_received_count": 0,
@@ -131,8 +151,8 @@
    "per_host_required_field_count": 9,
    "registry_export_accepted_count": 0,
    "registry_export_received_count": 0,
-    "required_field_count": 23,
-    "reviewer_check_count": 10,
+    "required_field_count": 28,
+    "reviewer_check_count": 15,
    "runtime_gate_count": 0,
    "secret_value_collection_allowed_count": 0
  }
--- a/scripts/security/wazuh-agent-visibility-owner-evidence-preflight.py
+++ b/scripts/security/wazuh-agent-visibility-owner-evidence-preflight.py
@@ -38,6 +38,11 @@ REQUIRED_FIELDS = [
    "registry_export_summary_ref",
    "manager_health_ref",
    "dashboard_api_status_ref",
+    "dashboard_api_connection_check_status",
+    "dashboard_api_version_check_status",
+    "dashboard_index_pattern_statuses",
+    "dashboard_api_degradation_root_cause",
+    "dashboard_api_repair_postcheck_ref",
    "redacted_evidence_refs",
    "followup_owner",
    "rollback_owner",
@@ -52,6 +57,11 @@ REVIEWER_CHECKS = [
    "per_host_registry_matrix 每列只能使用公開別名，不得包含內網位址、agent 原名或 raw payload。",
    "last_seen 時間窗需能覆蓋事故觀察區間。",
    "manager health ref 與 dashboard API status ref 不可互相替代。",
+    "Dashboard API connection 若仍是 pending / spinning，不得接受為 Wazuh 可用。",
+    "Dashboard API version 必須獨立驗證；index pattern 三綠勾不可替代 API version。",
+    "index pattern 已通過只能代表索引 pattern 可讀，不可替代 manager registry counts。",
+    "Dashboard API 退化根因必須至少分類為 stored API、RBAC / run_as、rate-limit、TLS trust 或 readonly account scope 其中之一。",
+    "dashboard API repair postcheck 必須包含 API connection、API version、manager registry counts 與 IwoooS readback。",
    "redacted evidence refs 不得包含 raw payload、截圖原文或主機完整輸出。",
    "owner decision 不可直接授權 active response、host write 或 secret rotation。",
    "rollback owner 與 postcheck plan 必須存在。",
@@ -62,6 +72,9 @@ OUTCOME_LANES = [
    "request_missing_fields",
    "quarantine_sensitive_payload",
    "reject_runtime_action_request",
+    "request_dashboard_api_status_supplement",
+    "request_dashboard_api_repair_postcheck",
+    "reject_index_pattern_only_green",
    "ready_for_reviewer_validation",
 ]

@@ -80,6 +93,10 @@ FORBIDDEN_PAYLOADS = [
    "cookie",
    "private_key",
    "client_keys",
+    "raw_dashboard_request",
+    "dashboard_api_secret",
+    "stored_api_password",
+    "api_token",
    "active_response_enable",
    "host_write",
    "firewall_change",
@@ -128,6 +145,8 @@ REGISTRY_EXPORT_REDACTION_REQUIREMENTS = [
    "只允許公開節點別名，不允許內網位址、主機原名或 agent 原名。",
    "agent id 僅能用不可逆 evidence ref，不得放完整值、雜湊、前後綴或 client key。",
    "每個缺口必須有 gap reason，不得以 Dashboard 空白或口頭說明補成綠燈。",
+    "Dashboard API connection / version / index pattern 必須分欄呈現，不得合併成單一 healthy。",
+    "Dashboard API 修復證明只能收脫敏 ref，不得收 stored API secret、token、密碼或完整 request。",
    "只收計數、狀態桶、時間窗與證據 ref，不收 raw API payload、完整 CLI output 或截圖原文。",
 ]

@@ -227,6 +246,7 @@ def build_snapshot() -> dict[str, Any]:
            "agent service active、TCP 連線存在、Dashboard 可見或口頭宣稱都不可替代 manager registry counts。",
            "逐主機 registry export 必須使用固定公開節點別名與狀態桶，不能把 agent 原名或內網識別資訊帶到前台。",
            "若 evidence 夾帶 raw log、未脫敏截圖、內網位址、agent 原名或 secret，必須隔離，不得渲染到前台。",
+            "Dashboard index pattern 三綠勾不可替代 API connection、API version 或 manager registry 驗收。",
            "任何 active response、host write、firewall、Nginx、Docker、K8s 或 secret 變更都要切獨立人工批准。",
        ],
    }