# Wazuh 用戶端消失事故只讀回讀

| 項目 | 內容 |
|------|------|
| 日期 | 2026-06-24 |
| 狀態 | `runtime_dashboard_agent_visibility_incident_readonly_triage` |
| 事故焦點 | Wazuh Dashboard 顯示用戶端消失，但 IwoooS 尚未具備 live agent registry readback |
| runtime gate | `0` |

## 1. 結論

這次不能再用「Wazuh 已建置」或「Dashboard 可開」當成資安機制有效。IwoooS production `/api/iwooos/wazuh` 與 `/api/v1/iwooos/wazuh` 目前已部署並回 `200 disabled_waiting_iwooos_wazuh_owner_gate`，但仍是 owner gate disabled 狀態，`configured=false`、manager query accepted `0`、runtime gate `0`；因此它只能證明只讀路由存在，尚未真正讀到 Wazuh manager 的 agent count、agent status、last seen 或 event refs。

2026-06-25 10:43 CST 再次只讀確認：112 的 Wazuh manager、indexer、dashboard 都仍為 active；manager 端 `1514` 觀察到多條 agent transport 連線；受管節點 A 的 agent service active 且 transport 已建立。但 Dashboard stored API / API check 仍在出錯，已觀察到 `400 / 429 / 500`、stored API unreachable、login 500、run_as / internal user 權限錯誤與 TLS client trust 錯誤。這表示「Dashboard 用戶端消失」目前不能簡化成所有 agent 都停了；更精準的故障層是 Dashboard 到 Wazuh API 的 stored API、RBAC / run_as、rate-limit 與 TLS trust。

但 manager 端 agent registry 的真實清單尚未被獨立驗收，因為本視窗沒有 Wazuh API 只讀帳號，也沒有 112 root read 權限；`kali` 使用者不屬於 `wazuh` 群組，不能直接讀 Wazuh manager 受限目錄或 registry CLI；因此 `wazuh_live_agent_registry_readback` 必須維持 `0`。

## 2. 只讀證據摘要

| 檢查面 | 證據 | 判定 |
|--------|------|------|
| IwoooS production route | `https://awoooi.wooo.work/api/iwooos/wazuh` 與 `/api/v1/iwooos/wazuh` 皆回 `200 disabled_waiting_iwooos_wazuh_owner_gate`；`configured=false`、`runtime_gate_count=0` | 路由已部署，但 owner gate 未開，IwoooS 尚未讀到 Wazuh live metadata |
| 公開 Wazuh domain | `wazuh.wooo.work` 未形成可用公開入口 | 不可用公開 domain 代表 Wazuh runtime 狀態 |
| 110 agent | `wazuh-agent.service` active running；啟動於 2026-06-23 14:50 CST；本機 agent key 存在 | 110 agent 端未消失 |
| 110 manager target | `ossec.conf` manager address 指向 `192.168.0.112` | 112 是 manager control plane |
| 188 agent | `wazuh-agent.service` active running；啟動於 2026-06-23 14:50 CST | 188 agent 端未消失 |
| agent 到 manager | 110 / 188 到 `192.168.0.112:1514` 皆有 ESTABLISHED 連線；`1514 / 1515 / 55000` targeted reachability 成功 | agent network path 正常 |
| 112 control plane | `wazuh-manager`、`wazuh-indexer`、`wazuh-dashboard` 均 active running；啟動於 2026-06-23 14:48-14:51 CST；`NRestarts=0` | 112 服務沒有整體掛掉 |
| 112 API endpoint | `https://192.168.0.112:55000/` 從本機、110、188 皆回 `401` | API 活著但需要認證 |
| 112 agent transport | 2026-06-25 10:43 CST manager 端只讀觀察到 `6` 條 `1514` established transport | 傳輸層有 agent 連線，但不能替代 registry 驗收 |
| Dashboard 讀取層 | 2026-06-25 10:40-10:41 CST `/api/check-stored-api`、`/api/check-api`、`/api/login` 觀察到 `400 / 429 / 500`、stored API unreachable、run_as / internal user 權限錯誤與 TLS client trust 錯誤 | Dashboard stored API / RBAC / run_as / rate-limit / TLS trust 需維修 |
| manager registry 讀取權限 | `kali` 使用者不能直接執行 manager registry 工具；`sudo -n` 讀取需要密碼；一般權限也無法讀 Wazuh manager 受限目錄 | agent registry truth 仍未驗收，不能結案 |

## 3. 為什麼前一版沒有擋住

1. IwoooS 先前只建立 readback plan、前台卡與 release gate，沒有真正接 Wazuh manager agent registry。
2. `active_runtime_gate=0` 是正確邊界，但前台文案容易讓人誤會「Wazuh 已整合」等於「agent 消失會被抓到」。
3. production 只讀 API 已部署，但仍缺少 manager live metadata：`agent_total`、`agent_active`、`agent_disconnected`、`last_seen_present` 都沒有 accepted readback。
4. 缺少 no-false-green 告警：Dashboard 429/500、Wazuh API 401、agent 連線存在、IwoooS route 200 但 owner gate disabled 這些狀態仍需合成一張 AI 事件卡。
5. 缺少 owner evidence：誰在 2026-06-23 14:48 後建立、重啟、登入或調整 112/Wazuh，尚未有脫敏 owner 回覆。
6. 原 source-side API 缺少 agent count 退化分類：若 Wazuh manager registry 回 `agent_total=0` 或低於預期下限，不能再沿用正常 `readonly_metadata_available` 狀態。

## 3.1 新增 no-false-green guard

本輪新增 `scripts/security/wazuh-agent-visibility-runtime-gate.py` 與 `docs/security/wazuh-agent-visibility-runtime-gate.snapshot.json`。這個 guard 的目的不是修復 Dashboard，而是防止 IwoooS 在沒有 agent registry 讀回時誤顯示綠燈。

目前機器可讀狀態固定為：

- `manager_agent_registry_readback_passed=false`
- `iwooos_live_route_readback_passed=false`（production route 已回 `200`，但尚未接入 manager live metadata）
- `dashboard_agent_list_recovered=false`
- `manager_transport_established_connection_count=6`
- `dashboard_stored_api_unreachable_observed=true`
- `dashboard_api_login_500_observed=true`
- `dashboard_api_rate_limited_observed=true`
- `dashboard_api_run_as_permission_error_observed=true`
- `dashboard_api_tls_client_cert_unknown_observed=true`
- `manager_registry_cli_permission_blocked=true`
- `runtime_gate_count=0`
- `active_response_authorized=false`
- `host_write_authorized=false`
- `secret_value_collection_allowed=false`

解除條件必須是 Wazuh API 只讀中繼資料或 owner 提供的脫敏 registry evidence，不能用 Dashboard 看起來正常、agent service active、TCP 連線存在或 UI 卡片可見替代。

本輪再補 IwoooS Wazuh API source-side no-false-green：`/api/iwooos/wazuh` 與 `/api/v1/iwooos/wazuh` 在 `agent_total=0` 時回 `wazuh_agent_registry_empty`，在低於 server-side `IWOOOS_WAZUH_EXPECTED_MIN_AGENT_COUNT` 時回 `wazuh_agent_registry_below_expected`。這只改判讀與 metadata，不代表 production 已部署、manager registry 已驗收或 active response 已授權。

本輪另新增 Wazuh agent visibility owner evidence preflight：`scripts/security/wazuh-agent-visibility-owner-evidence-preflight.py`、`docs/security/wazuh-agent-visibility-owner-evidence-preflight.snapshot.json` 與人讀版 `docs/security/WAZUH-AGENT-VISIBILITY-OWNER-EVIDENCE-PREFLIGHT.md`。它固定 owner 必要欄位、reviewer 檢查、拒收分流與禁止 payload；`received / accepted / runtime_gate` 仍全部為 `0`。

## 4. 立即凍結邊界

在 manager 端 agent registry 被只讀驗收前，以下全部維持禁止：

- 不重啟 `wazuh-manager`、`wazuh-indexer`、`wazuh-dashboard`。
- 不重新註冊 agent、不重產 `client.keys`、不刪 agent。
- 不改 Wazuh API 使用者、stored API、憑證、TLS、rate-limit 或 Dashboard 設定。
- 不改 firewall、Nginx、WireGuard、Docker、systemd、K8s、ArgoCD。
- 不把 Dashboard 空白、Dashboard 恢復、agent active、route 200、IwoooS UI 可見當成事件結案。
- 不收 Wazuh 密碼、token、cookie、private key、raw log、raw payload 或截圖中的敏感資訊。

## 5. 修復與納管優先順序

| 優先 | 工作 | 驗收條件 | 目前完成度 |
|------|------|----------|------------|
| P0-A | Wazuh manager agent registry 只讀驗收 | owner 提供脫敏 `agent_total / active / disconnected / last_seen` ref，或經 server-side secret metadata 啟用 IwoooS 只讀 API；source-side 已能把 registry 空或低於預期判成退化，並新增 owner evidence 收件預檢 | `56%` source-side、`0%` live registry accepted |
| P0-B | Dashboard stored API / rate-limit / TLS trust 修復 gate | 查明 `/api/check-stored-api` 429/500 根因；維修前有 owner、rollback、postcheck；維修後 Dashboard 與 API count 一致 | `35%` |
| P0-C | IwoooS live metadata route 正式部署 | `/api/iwooos/wazuh` 不再 404，回傳 schema `iwooos_wazuh_readonly_status_v1`，不洩漏 agent identity / internal IP / secret；下一步是 manager live metadata owner gate | `100%` production route、`0%` manager metadata accepted |
| P0-D | Wazuh agent disappearance alert card | 產出 `ai_automation_alert_card_v1`，包含 agent count delta、Dashboard API status、manager health、next gate、owner；本輪已新增 `wazuh_dashboard_api_readback_degraded` formatter / test / guard、AwoooP `/runs/ai-alert-cards` delivery readback contract 與 Runs 前台面板 | `92%` source-side、`0%` production receipt |
| P0-E | 112/Wazuh owner response | 回覆 owner role/team、decision、reason、affected scope、redacted evidence refs、rollback owner、followup owner | `0%` |
| P1-A | 110/188 agent receipt heartbeat | 每台 host 定期只讀確認 service active、manager target、1514 established、last evidence ref | `45%` |
| P1-B | Dashboard no-false-green | Dashboard 429/500 或 Wazuh API check failure 要進 IwoooS incident，不可顯示綠燈 | `15%` |
| P1-C | 機器可讀 runtime gate | `wazuh-agent-visibility-runtime-gate.py` 納入 `security-mirror-progress-guard.py`，未驗收 registry 時 guard 保持 blocked snapshot | `100%` source-side、`0%` runtime |

## 6. 下一步

1. 請 Wazuh/112 owner 補脫敏 agent registry evidence：`agent_total`、`active`、`disconnected`、`never_connected`、`last_seen` 時間窗，不提供密碼或 raw payload。
2. 啟用 IwoooS Wazuh manager live metadata 前，先完成 server-side env owner、secret source metadata、readonly account scope、rollback owner 與 postcheck。
3. 若 owner 批准維修 Dashboard stored API，必須先做 read-only preflight：rate-limit 現況、stored API 指向、TLS trust、API user scope、Dashboard 與 manager 版本、回滾方式。
4. 補 IwoooS AI 事件卡正式 readback：source-side formatter 已能把 Dashboard/API mismatch 分類為 `wazuh_dashboard_api_readback_degraded`，AwoooP 已有 `/api/v1/platform/runs/ai-alert-cards` 只讀 delivery readback contract 與 Runs 前台面板；下一步需 production deploy、live outbound readback、AwoooP timeline 顯示與 IwoooS 前台 readback。

## 7. 完成度

- 現場只讀鑑別：`70%`。
- 真正 agent registry 驗收：`0%`。
- IwoooS production route readback：`100%`。
- Wazuh manager registry live metadata accepted：`0%`。
- Dashboard stored API 修復：`0%`。
- SOC / Wazuh no-false-green 納管：`66%`。
- active response / host write / auto block：`0%`，保持關閉。
