docs(iwooos): 記錄 Wazuh release apply proof

2026-06-24 21:47:08 +08:00
parent 6a83ae48a1
commit 5ea64ca472
4 changed files with 88 additions and 7 deletions
--- a/docs/LOGBOOK.md
+++ b/docs/LOGBOOK.md
@@ -128,7 +128,7 @@
 - Mac Mini / MacBook 的 `~/.codex/CODEX-START-HERE.md` 與 `codex-workstation-sync-dashboard.snapshot.json` 已從舊 `V10.651` / MacBook blocked wording 校準為 current-main baseline；仍未同步 auth、SQLite、sessions、raw conversations、`.env`、runtime volumes、raw `.git`。

 **Wazuh 分工邊界**：
- IwoooS 主控視窗同步的 Wazuh 只讀 API 邊界最新 HEAD 是 `22fe67e0`，release patch SHA-256 是 `b2512bc8095434b6c1216592d53c4ce175f78fc12f47072c157fc48a08ddade7`。
+- IwoooS 主控視窗同步的 Wazuh 只讀 API 邊界 Wazuh API commit 是 `47d36e85`；最終分支 HEAD 與 release patch set SHA-256 需在 final docs commit 後以 `git rev-parse HEAD`、`git format-patch gitea/main..HEAD`、`shasum -a 256` 讀回，避免 committed 文件自我引用造成 hash 漂移。
 - 該 lane 的 source / tests / release gate 已完成，但 push/deploy/production readback 仍是 `0`，production `/api/iwooos/wazuh` 404 不屬本視窗修復事項。
 - 本視窗不得為 Wazuh 404 改 Nginx、Docker、K8s、firewall、Wazuh manager 或 secret；`wazuh_api_live_query_authorized=false`、`wazuh_active_response_authorized=false`、`active_scan_authorized=false`、`host_write_authorized=false`、`runtime_gate_count=0` 維持。

@@ -201,6 +201,14 @@

 **Release handoff 補充**：受控 workspace 的 Gitea HTTPS push 因非互動式 credential 缺失失敗；本輪未複製或使用舊 workspace 內嵌明文 token。已新增 `docs/security/IWOOOS-WAZUH-READONLY-API-RELEASE-HANDOFF.md`，供具備正式 Gitea / release 權限的 lane 合併 `codex/iwooos-wazuh-boundary-guard-20260624` 分支 HEAD 或同等 patch，並以 production `/api/iwooos/wazuh` readback 驗證不再 404。

+**Release apply proof 補充，21:58 Asia/Taipei**：
+- Wazuh API commit：`47d36e85 fix(iwooos): 接上 Wazuh 只讀 API 邊界`；最終分支 HEAD 與 release patch set SHA-256 不硬寫進 committed 文件，需在 final docs commit 後以命令讀回。
+- 已從最新 `gitea/main=80604403` 建立獨立 worktree 並套用 patch set 成功；後續若文件 commit 再變動，release 執行者需重新 `git format-patch gitea/main..HEAD` 與 apply-check，避免沿用舊 patch SHA。
+- 乾淨套用 worktree 通過 `pytest apps/api/tests/test_iwooos_wazuh_api.py`、`wazuh-readonly-route-boundary-guard.py`、`wazuh-readonly-release-gate.py`、`security-mirror-progress-guard.py`、`doc-secrets-sanity-check.py`、`py_compile` 與 `git diff --check`。
+- `docs/security/wazuh-readonly-release-gate.snapshot.json` 已補上 `release_patch_apply_proof_complete_count=1` 與 `gitea_push_blocker_observed_count=1`，並記錄 `production_readback_status=predeploy_404_observed`。
+- 非互動式 `git push gitea HEAD:codex/iwooos-wazuh-boundary-guard-20260624` 仍因 Gitea HTTPS credential 缺失失敗：`could not read Username`；不得以舊 workspace 明文 token、Nginx / firewall / Wazuh secret 修改或 host 重啟繞過。
+- Production `/api/iwooos/wazuh` 與 `/api/v1/iwooos/wazuh` 仍回 `404`，正式 readback 不加 `--allow-predeploy-404` 會正確阻擋；因此 production deploy / readback、Wazuh live metadata env、event refs / host forensic refs、active response / host write 仍全部 `0% / false`。
+
 ## 2026-06-24｜21:04 recovery readback 與 MOMO V10.651 雙機基準收斂

 **背景**：前一輪 MOMO workspace readback 指到 `V10.646`，但 21:04 live health 已回 `V10.651`。因此本輪重新比對 Gitea `wooo/ewoooc` `main`、正式站 `/health`、Mac Mini / MacBook Pro Codex workspace 與 full-stack cold-start，避免「網站可用」和「版本 / 資料最新」互相混淆。
--- a/docs/security/IWOOOS-WAZUH-READONLY-API-RELEASE-HANDOFF.md
+++ b/docs/security/IWOOOS-WAZUH-READONLY-API-RELEASE-HANDOFF.md
@@ -18,7 +18,9 @@

 本地 commit：

- `codex/iwooos-wazuh-boundary-guard-20260624` 分支 HEAD：`fix(iwooos): 接上 Wazuh 只讀 API 邊界`
+- `codex/iwooos-wazuh-boundary-guard-20260624` Wazuh API commit：`47d36e85 fix(iwooos): 接上 Wazuh 只讀 API 邊界`
+- `codex/iwooos-wazuh-boundary-guard-20260624` 最終分支 HEAD 不硬寫在本文件內；請在 release 前用 `git rev-parse HEAD` 讀回，避免 commit 自我引用造成 hash 漂移。
+- Release patch set 需在最終 docs commit 後以 `git format-patch gitea/main..HEAD` 重新產生，再用 `shasum -a 256` 讀回；不得沿用 rebase 前或文件修正前的舊 patch SHA。

 變更範圍：

@@ -47,15 +49,15 @@

 ## 已完成驗證

-已在 `/Users/ogt/codex-workspaces/awoooi-dev` 執行：
+已在 `/private/tmp/awoooi-iwooos-wazuh-boundary-verify-20260624` 執行：

 ```bash
 pytest apps/api/tests/test_iwooos_wazuh_api.py
 python3 scripts/security/wazuh-readonly-route-boundary-guard.py --root .
 python3 scripts/security/wazuh-readonly-release-gate.py --root .
 python3 scripts/security/security-mirror-progress-guard.py --root .
-python3 scripts/ops/doc-secrets-sanity-check.py docs apps/api/src/api/v1/iwooos.py apps/web/src/app/api/iwooos/wazuh/route.ts scripts/security/wazuh-readonly-route-boundary-guard.py
-python3 -m py_compile apps/api/src/api/v1/iwooos.py scripts/security/wazuh-readonly-route-boundary-guard.py scripts/security/security-mirror-progress-guard.py
+python3 scripts/ops/doc-secrets-sanity-check.py docs apps/api/src/api/v1/iwooos.py apps/web/src/app/api/iwooos/wazuh/route.ts scripts/security/wazuh-readonly-route-boundary-guard.py scripts/security/wazuh-readonly-production-readback.py scripts/security/wazuh-readonly-release-gate.py
+python3 -m py_compile apps/api/src/api/v1/iwooos.py scripts/security/wazuh-readonly-route-boundary-guard.py scripts/security/wazuh-readonly-production-readback.py scripts/security/wazuh-readonly-release-gate.py scripts/security/security-mirror-progress-guard.py
 git diff --check
 ```

@@ -65,10 +67,31 @@ git diff --check
 - `wazuh-readonly-route-boundary-guard`：`route=2 public_ui_files=1 forbidden=0 runtime_gate=0`。
 - `wazuh-readonly-release-gate`：`source=1 push=0 deploy=0 readback=0 runtime_gate=0`。
 - `security-mirror-progress-guard`：`SECURITY_MIRROR_PROGRESS_GUARD_OK`。
- `doc-secrets-sanity-check`：`DOC_SECRET_SANITY_OK scanned_files=967`。
+- `doc-secrets-sanity-check`：`DOC_SECRET_SANITY_OK scanned_files=969`。
 - `py_compile`：通過。
 - `git diff --check`：通過。

+## 乾淨套用 Proof
+
+乾淨套用 proof 需從最新 `gitea/main=80604403` 或更新的主線建立獨立 worktree：
+
+```bash
+git worktree add /private/tmp/awoooi-iwooos-wazuh-release-apply-check-<timestamp> gitea/main
+git am /private/tmp/awoooi-iwooos-wazuh-boundary-release-patch-<timestamp>/*.patch
+```
+
+此 proof 只證明 patch 可乾淨落在最新主線並通過 guard，不代表已 push、已部署或已啟用 Wazuh live metadata。最終 patch SHA 與 apply-check commit 應由 release 執行者在 final docs commit 之後用命令讀回，不寫入會自我漂移的 committed 文件。
+
+乾淨套用 worktree 驗證結果：
+
+- `pytest apps/api/tests/test_iwooos_wazuh_api.py`：`4 passed`。
+- `python3 scripts/security/wazuh-readonly-route-boundary-guard.py --root .`：`WAZUH_READONLY_ROUTE_BOUNDARY_GUARD_OK route=2 public_ui_files=1 forbidden=0 runtime_gate=0`。
+- `python3 scripts/security/wazuh-readonly-release-gate.py --root .`：`WAZUH_READONLY_RELEASE_GATE_OK source=1 push=0 deploy=0 readback=0 runtime_gate=0`。
+- `python3 scripts/security/security-mirror-progress-guard.py --root .`：`SECURITY_MIRROR_PROGRESS_GUARD_OK`。
+- `python3 scripts/ops/doc-secrets-sanity-check.py ...`：`DOC_SECRET_SANITY_OK scanned_files=969`。
+- `python3 -m py_compile ...`：通過。
+- `git diff --check`：通過。
+
 尚未部署前的 production 現況記錄：

 ```bash
@@ -77,11 +100,20 @@ python3 scripts/security/wazuh-readonly-production-readback.py --allow-predeploy

 預期只可回 `status=predeploy_404_observed`。正式部署驗收不得加 `--allow-predeploy-404`。

+目前實測：
+
+```json
+{"http_status": 404, "runtime_gate_count": 0, "schema_version": "iwooos_wazuh_production_readback_v1", "status": "predeploy_404_observed"}
+```
+
+不加 `--allow-predeploy-404` 時會正確阻擋：`BLOCKED production readback returned 404; Wazuh FastAPI compatibility route is not deployed`。
+
 ## Release 前 Gate

 合併 / 部署前需確認：

 - 使用具備正式權限的 Gitea lane 合併 `codex/iwooos-wazuh-boundary-guard-20260624` 分支 HEAD 或同等 patch；不得 force push。
+- 目前非互動式 push 實測仍被 Gitea HTTPS credential 擋住：`fatal: could not read Username for 'https://gitea.wooo.work': terminal prompts disabled`。
 - 不得複製舊 workspace 的內嵌明文 Gitea token。
 - 不得把 Wazuh URL、帳密、token、cookie、private key、runner token 或 webhook secret 寫入 repo。
 - 不得為了讓 API 變 200 而直接改 Nginx、Docker、K8s、firewall、Wazuh manager、Wazuh rule、Wazuh decoder 或 Wazuh active response。
@@ -129,6 +161,7 @@ python3 scripts/security/wazuh-readonly-production-readback.py --json
 | Wazuh route boundary source guard | `100%` | 已納入 `security-mirror-progress-guard` |
 | Production readback 驗收腳本 | `100%` | 已完成；正式部署後不得接受 404 |
 | Wazuh release gate snapshot / guard | `100%` | 已完成；固定 push/deploy/readback 仍 blocked |
+| 乾淨套用 proof | `100%` | patch set 可落在最新 `gitea/main` 並通過同組 guard；最終 hash 以 release 前 readback 為準 |
 | Gitea push | `0%` | 受控 workspace HTTPS credential 缺失 |
 | Production deploy / readback | `0%` | 等待 release lane |
 | Wazuh server-side env enable | `0%` | 等待 owner gate 與 secrets 注入 |
--- a/docs/security/wazuh-readonly-release-gate.snapshot.json
+++ b/docs/security/wazuh-readonly-release-gate.snapshot.json
@@ -14,12 +14,13 @@
    "wazuh_active_response_authorized": false,
    "wazuh_api_live_query_authorized": false
  },
-  "generated_at": "2026-06-24T21:36:00+08:00",
+  "generated_at": "2026-06-24T22:05:00+08:00",
  "missing_required_source_paths": [],
  "mode": "repo_release_gate_no_runtime_no_secret_collection",
  "operator_interpretation": [
    "此 gate 通過不代表 production 已部署，只代表 source-side Wazuh read-only API 與 guard 可交接。",
    "正式 release 前不得用 predeploy 404 當成功，也不得為了修 404 直接改 Nginx、Docker、K8s、firewall 或 Wazuh secret。",
+    "乾淨套用 proof 通過只代表 release patch 可落在最新主線，不代表已 push、已部署或已啟用 Wazuh live metadata。",
    "live Wazuh metadata query 必須另走 owner gate 與 server-side env；active response、host write、Kali active scan 仍為 0 / false。"
  ],
  "release_gates": [
@@ -41,6 +42,12 @@
      "runtime_authorized": false,
      "status": "passed"
    },
+    {
+      "gate_id": "release_patch_apply_proof",
+      "required_evidence": "同等 patch 已可乾淨套用到最新 gitea/main 並通過同組 guard",
+      "runtime_authorized": false,
+      "status": "passed"
+    },
    {
      "gate_id": "gitea_branch_push",
      "required_evidence": "具備正式權限的 lane 推送或合併 codex/iwooos-wazuh-boundary-guard-20260624",
@@ -66,6 +73,17 @@
      "status": "blocked_owner_gate_required"
    }
  ],
+  "release_lane_evidence": {
+    "apply_check_status": "passed_external_readback_required_after_final_commit",
+    "base_commit": "80604403",
+    "base_ref": "gitea/main",
+    "gitea_push_blocker": "https_noninteractive_credential_required",
+    "production_readback_status": "predeploy_404_observed",
+    "release_patch_set_readback": "generate with git format-patch gitea/main..HEAD after the final docs commit, then record sha256 outside the committed file",
+    "source_branch": "codex/iwooos-wazuh-boundary-guard-20260624",
+    "source_fix_commit": "47d36e85",
+    "source_head_readback": "run git rev-parse HEAD after the final docs commit; do not hardcode a self-referential commit hash"
+  },
  "required_source_paths": [
    "apps/api/src/api/v1/iwooos.py",
    "apps/api/tests/test_iwooos_wazuh_api.py",
@@ -78,6 +96,7 @@
  "status": "blocked_waiting_gitea_push_and_production_deploy",
  "summary": {
    "active_response_authorized_count": 0,
+    "gitea_push_blocker_observed_count": 1,
    "gitea_push_complete_count": 0,
    "host_forensics_ref_accepted_count": 0,
    "host_write_authorized_count": 0,
@@ -87,6 +106,7 @@
    "production_readback_passed_count": 0,
    "production_readback_script_complete_count": 1,
    "release_handoff_complete_count": 1,
+    "release_patch_apply_proof_complete_count": 1,
    "route_boundary_guard_complete_count": 1,
    "runtime_gate_count": 0,
    "source_side_fix_complete_count": 1,
--- a/scripts/security/wazuh-readonly-release-gate.py
+++ b/scripts/security/wazuh-readonly-release-gate.py
@@ -41,14 +41,27 @@ def build_report(root: Path, generated_at: str | None = None) -> dict[str, Any]:
        "generated_at": generated_at or now_iso(),
        "status": "blocked_waiting_gitea_push_and_production_deploy",
        "mode": "repo_release_gate_no_runtime_no_secret_collection",
+        "release_lane_evidence": {
+            "source_branch": "codex/iwooos-wazuh-boundary-guard-20260624",
+            "source_fix_commit": "47d36e85",
+            "source_head_readback": "run git rev-parse HEAD after the final docs commit; do not hardcode a self-referential commit hash",
+            "base_ref": "gitea/main",
+            "base_commit": "80604403",
+            "release_patch_set_readback": "generate with git format-patch gitea/main..HEAD after the final docs commit, then record sha256 outside the committed file",
+            "apply_check_status": "passed_external_readback_required_after_final_commit",
+            "production_readback_status": "predeploy_404_observed",
+            "gitea_push_blocker": "https_noninteractive_credential_required",
+        },
        "required_source_paths": REQUIRED_SOURCE_PATHS,
        "summary": {
            "source_side_fix_complete_count": 1 if source_ready else 0,
            "route_boundary_guard_complete_count": 1 if (root / "scripts/security/wazuh-readonly-route-boundary-guard.py").exists() else 0,
            "production_readback_script_complete_count": 1 if (root / "scripts/security/wazuh-readonly-production-readback.py").exists() else 0,
            "release_handoff_complete_count": 1 if (root / "docs/security/IWOOOS-WAZUH-READONLY-API-RELEASE-HANDOFF.md").exists() else 0,
+            "release_patch_apply_proof_complete_count": 1,
            "missing_required_source_path_count": len(missing_paths),
            "gitea_push_complete_count": 0,
+            "gitea_push_blocker_observed_count": 1,
            "production_deploy_complete_count": 0,
            "production_readback_passed_count": 0,
            "predeploy_404_observed_count": 1,
@@ -78,6 +91,12 @@ def build_report(root: Path, generated_at: str | None = None) -> dict[str, Any]:
                "required_evidence": "wazuh-readonly-production-readback.py 可在 release 後不接受 404",
                "runtime_authorized": False,
            },
+            {
+                "gate_id": "release_patch_apply_proof",
+                "status": "passed",
+                "required_evidence": "同等 patch 已可乾淨套用到最新 gitea/main 並通過同組 guard",
+                "runtime_authorized": False,
+            },
            {
                "gate_id": "gitea_branch_push",
                "status": "blocked_credential_required",
@@ -122,6 +141,7 @@ def build_report(root: Path, generated_at: str | None = None) -> dict[str, Any]:
        "operator_interpretation": [
            "此 gate 通過不代表 production 已部署，只代表 source-side Wazuh read-only API 與 guard 可交接。",
            "正式 release 前不得用 predeploy 404 當成功，也不得為了修 404 直接改 Nginx、Docker、K8s、firewall 或 Wazuh secret。",
+            "乾淨套用 proof 通過只代表 release patch 可落在最新主線，不代表已 push、已部署或已啟用 Wazuh live metadata。",
            "live Wazuh metadata query 必須另走 owner gate 與 server-side env；active response、host write、Kali active scan 仍為 0 / false。",
        ],
    }