From 9fa84845bedd1d777fbe64ec73534120e22bef0e Mon Sep 17 00:00:00 2001 From: wpdev Date: Sat, 15 Aug 2026 20:38:09 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20NinjaFirewall=20=E7=9B=B8=E5=AE=B9?= =?UTF-8?q?=E6=80=A7=20=E2=80=94=20=E4=BF=9D=E8=AD=B7=20WAF=20=E8=A8=AD?= =?UTF-8?q?=E5=AE=9A=E9=81=B8=E9=A0=85=E4=B8=8D=E8=A2=AB=E9=87=8D=E5=B0=8E?= =?UTF-8?q?=E5=90=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 評估 NinjaFirewall (WP Edition) 4.9 的相容性，結論是兩者可共存且 不需要開發 AddOn（該外掛全 codebase 零個 apply_filters('nfw_*') / do_action('nfw_*')，官方相容手段全在部署層）。但核心有一個隱患必須補。 TMDO_Options_Manager::register_settings_group() 以 pre_update_option_{key} 回傳 $old_value，讓選項不再落地 wp_options、改存專屬設定表。而 NinjaFirewall 的 Full WAF 走 auto_prepend_file，在 WordPress 載入前就以 原生 mysqli 直查 wp_options 取 nfw_options / nfw_rules。一旦這些鍵被 重導向，WAF 會讀不到設定而靜默停止防護 —— 不報錯、不寫 log。 nfw_rules 約 77KB 且 autoload=auto，正是 autoload 瘦身最誘人的目標， 因此這條路徑並非理論風險。 Added - PROTECTED_OPTIONS 常數與註冊守衛（nfw_options / nfw_rules / nfw_checked）， 命中時發出 _doing_it_wrong()。守衛置於方法開頭，全部鍵都被擋時提前返回， 不再建立空的設定表。 - tests/unit/OptionsManagerProtectedTest.php（4 tests / 10 assertions）， 鎖住「受保護鍵絕不會被掛上 pre_option_* / pre_update_option_* 攔截」。 - docs/WAF-COMPATIBILITY.md：模式差異、symlink 多租戶部署、WP SaaS 開站 流程與驗證清單、三條開發約束、實測風險矩陣。 Changed - Migration Wizard 輪詢 500ms → 2s，與四個 stress-test 面板一致。 原本 2 req/s 打同一 REST endpoint，易觸發 WAF rate-limit 與 bot 偵測。 autoload 最佳化不受影響：optimize_autoload() 只改 autoload 欄位、不刪列， 而 Full WAF 的 SELECT * 不看 autoload。 驗證：591 tests / 1166 assertions 通過，PHPCS 零違規，版本一致性 1.0.2。 dev30 於 Full WAF 與 WP WAF 兩種模式下實測，firewall log 中 TMDO 相關 攔截 0 筆。 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01SdjXAU473eekjPBB8vPVRS --- 2meet-data-optimizer.php | 4 +- CHANGELOG.md | 43 +++ PLAN.md | 27 +- admin/assets/wpdo-migration-wizard.js | 4 +- docs/WAF-COMPATIBILITY.md | 279 ++++++++++++++++++ .../options/class-tmdo-options-manager.php | 32 ++ tests/unit/OptionsManagerProtectedTest.php | 100 +++++++ 7 files changed, 484 insertions(+), 5 deletions(-) create mode 100644 docs/WAF-COMPATIBILITY.md create mode 100644 tests/unit/OptionsManagerProtectedTest.php diff --git a/2meet-data-optimizer.php b/2meet-data-optimizer.php index a843da7..653c501 100644 --- a/2meet-data-optimizer.php +++ b/2meet-data-optimizer.php @@ -3,7 +3,7 @@ * Plugin Name: 2meet Data Optimizer * Plugin URI: https://2meet.io/2meet-data-optimizer * Description: 通用 WordPress 反 EAV 引擎：將 postmeta / usermeta / termmeta / commentmeta 自動分流至四象限扁平表（Hot / Warm / Cold / Archive），大幅提升搜尋與篩選效能。從 wp-data-optimizer v2.16.0 提煉的純核心，整合層交給 11 個 AddOn。 - * Version: 1.0.1 + * Version: 1.0.2 * Requires at least: 6.0 * Tested up to: 6.9.4 * Requires PHP: 8.1 @@ -26,7 +26,7 @@ if ( ! defined( 'ABSPATH' ) ) { } // ── Constants ────────────────────────────────────────────────────────────── -define( 'TMDO_VERSION', '1.0.1' ); +define( 'TMDO_VERSION', '1.0.2' ); define( 'TMDO_DB_VERSION', '2.1.0' ); define( 'TMDO_PATH', plugin_dir_path( __FILE__ ) ); define( 'TMDO_URL', plugin_dir_url( __FILE__ ) ); diff --git a/CHANGELOG.md b/CHANGELOG.md index 16e2121..2aa3a21 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,49 @@ Versioning follows [Semantic Versioning](https://semver.org/). --- +## [1.0.2] — 2026-08-15 — NinjaFirewall 相容性：WAF 設定選項保護 + +**性質**：防禦性修正 + 文件。無 schema 變更，無破壞性變更。 + +### Added + +- **`docs/WAF-COMPATIBILITY.md`** — NinjaFirewall (WP Edition) 4.9 相容性評估 + + 結論：兩者可共存，**不需要開發 AddOn**（NinjaFirewall 全 codebase 零個 + `apply_filters('nfw_*')` / `do_action('nfw_*')`，官方相容手段全在部署層）。 + 文件涵蓋 WP WAF 與 Full WAF 的模式差異、symlink 多租戶部署的必要設定、 + 三條開發約束，以及實測風險矩陣。 + +- **`TMDO_Options_Manager::PROTECTED_OPTIONS`** 常數與註冊守衛 + （`modules/options/class-tmdo-options-manager.php`） + + `register_settings_group()` 會以 `pre_update_option_{key}` 回傳 `$old_value`， + 讓選項不再落地 `wp_options`、改存專屬設定表。但 NinjaFirewall 的 Full WAF 走 + `auto_prepend_file`，在 WordPress 載入前就以**原生 mysqli 直查 `wp_options`** + 取 `nfw_options` / `nfw_rules`。一旦這些鍵被重導向，WAF 會讀不到設定而 + **靜默停止防護 —— 不報錯、不寫 log**。 + + 現以 `PROTECTED_OPTIONS`（`nfw_options` / `nfw_rules` / `nfw_checked`）在註冊 + 階段擋下，並發出 `_doing_it_wrong()`。守衛置於方法開頭，全部鍵都被擋時提前 + 返回，不再建立空的設定表。 + + 註：autoload 最佳化不受影響 —— `optimize_autoload()` 只改 `autoload` 欄位、 + 不刪列，而該處的 `SELECT *` 不看 autoload。 + +- **`tests/unit/OptionsManagerProtectedTest.php`** — 4 tests / 10 assertions + + 鎖住「受保護鍵絕不會被掛上 `pre_option_*` / `pre_update_option_*` 攔截」這個 + 核心保證，並驗證全數受保護時不對資料庫發出查詢。 + +### Changed + +- **Migration Wizard 輪詢間隔 500ms → 2s**（`admin/assets/wpdo-migration-wizard.js`） + + 原本 2 req/s 打同一個 REST endpoint，容易觸發 WAF 的 rate-limit 與 bot 偵測。 + 改為 2 秒，與四個 stress-test 面板既有的輪詢節奏一致。 + +--- + ## [1.0.1] — 2026-08-08 — Schema Registry 冪等性修正（cold zone 欄位重複累積） **性質**：核心 bug 修復。無 schema 變更，無 API 變更，無破壞性變更。 diff --git a/PLAN.md b/PLAN.md index c5092b3..3cb3e9d 100644 --- a/PLAN.md +++ b/PLAN.md @@ -6,7 +6,7 @@ ## Current state -- **Version**: 0.1.0 (scaffold + 4 phase 完成 2026-05-15) +- **Version**: 1.0.2 (2026-08-15；scaffold + 4 phase 完成於 2026-05-15) - **Phase**: 全 4 phase 已完成 - **Source**: 從 `wp-data-optimizer v2.16.0` 提煉 @@ -287,3 +287,28 @@ AddOn 測試 bootstrap 直接 `require` 核心 plugin 的 `tests/bootstrap.php` - `v0.1.0` — 本 release（Phase 0-4 完成） - `v0.1.1` — Phase 5 follow-up（tests / PHPCS / packaging） - `v0.2.0` — WPDO_ deprecation notice + wpdo → tmdo migration CLI + +--- + +## NinjaFirewall 相容性 ✅（2026-08-15，v1.0.2） + +計畫檔：`~/.claude/plans/2meet-data-optimizer-ninjafirewall-effervescent-lighthouse.md` + +- [x] 評估與 NinjaFirewall 4.9 的相容性 → **不需要開發 AddOn** +- [x] 診斷 `Cannot retrieve user options from database (#3)` → 與本外掛無關，根因為 symlink 部署 +- [x] 建立 `/var/www/Studio/.htninja`（symlink-safe 站台錨點，全租戶共用） +- [x] dev30 啟用 ninjafirewall，補上缺失的 `nfw_options` / `nfw_rules` +- [x] `TMDO_Options_Manager::PROTECTED_OPTIONS` 守衛 + 4 個單元測試 +- [x] Migration Wizard 輪詢 500ms → 2s +- [x] `docs/WAF-COMPATIBILITY.md` +- [x] 全套件回歸：591 tests / 1166 assertions OK + +### Lessons learned（WAF） + +- **`__DIR__` 會解析 symlink**。NinjaFirewall Full WAF 用 `dirname(dirname(dirname(__DIR__)))`（`lib/firewall.php:78`）推導站台位置，在 symlink 共享 codebase 的 SaaS 架構下，所有租戶都會被判定成「共享目錄所屬的那個站」，於是連錯資料庫、撈不到自己的 `nfw_options`，回錯誤碼 6（訊息寫作 `#3`）。**per-site 的可靠錨點是 `$_SERVER['DOCUMENT_ROOT']`**（web server 的 root 指令值，不受 symlink 影響），這正是 `.htninja` 的搜尋基準。 +- **`.htninja` 放在 `dirname(DOCUMENT_ROOT)` 可服務全部租戶**（`firewall.php:47-48` 的第二順位），因為內容以 DOCUMENT_ROOT 動態推導，一份檔案通用。切勿在其中寫 `return` —— `'ALLOW'` / `'BLOCK'` 是有意義的回傳值。 +- **`NFW_LOG_DIR` 對 WP WAF 模式同樣必要**：L78 的誤判在兩種模式都存在，只是 WP WAF 不用它連 DB，但 log / cache / session 仍會全部寫進共享目錄互相覆蓋。 +- **WAF 失效是靜默的**。讀不到設定時 `nfw_quit()` 直接返回，不擋任何請求也不寫 log —— 「your site is not protected」是字面意思。因此任何會讓 `nfw_options` 離開 `wp_options` 的機制（例如本外掛的 `register_settings_group()` 重導向）都必須擋在註冊階段。 +- **`.user.ini` 必須讓 php-fpm worker 可讀**。dev32 那份是 `root:root 0640`，www-data 讀不到 → `auto_prepend_file` 靜默失效、Full WAF 等同沒裝。排查時容易誤判成「WAF 有在跑」，實際上擋下請求的是共享 mu-plugin 的 WP WAF。 +- **判斷 WAF 是否真的生效，要用會被規則擋的請求實測**（例如 `?x=../../etc/passwd` → 規則 1 → 403），光看首頁 200 或後台無錯誤訊息都不算數。 +- WP-CLI 完全豁免（`firewall.php:18-23`），所以 CLI 全綠**不能**當作「WAF 與外掛相容」的證據，必須另外走 HTTP 驗證。 diff --git a/admin/assets/wpdo-migration-wizard.js b/admin/assets/wpdo-migration-wizard.js index 109e4c4..2b2665f 100644 --- a/admin/assets/wpdo-migration-wizard.js +++ b/admin/assets/wpdo-migration-wizard.js @@ -3,7 +3,7 @@ * * - Confirms options + checkbox before starting. * - Calls REST endpoints under /wp-json/wpdo/v1/migration/. - * - Polls /status every 500ms while job is active. + * - Polls /status every 2s while job is active. * - Streams log lines with fade-in; live-updates ratio + progress bar. * * @since 2.8.0 @@ -11,7 +11,7 @@ (function () { 'use strict'; - const POLL_INTERVAL_MS = 500; + const POLL_INTERVAL_MS = 2000; const config = window.wpdoMigrationWizard || {}; const i18n = config.i18n || {}; const restUrl = (config.restUrl || '').replace(/\/$/, ''); diff --git a/docs/WAF-COMPATIBILITY.md b/docs/WAF-COMPATIBILITY.md new file mode 100644 index 0000000..f4cba3c --- /dev/null +++ b/docs/WAF-COMPATIBILITY.md @@ -0,0 +1,279 @@ +# WAF 相容性 — NinjaFirewall + +適用：2meet-data-optimizer v1.0.2+ / NinjaFirewall (WP Edition) 4.9 + +**結論：兩者可共存，且不需要開發 AddOn。** 本文記錄實測結果、symlink 多租戶部署的必要設定、WP SaaS 的開站流程與驗證清單，以及開發時必須遵守的三條約束。 + +> 只想開新站台的話，直接看 §3；踩到 `Cannot retrieve user options from database (#3)` 看 §2。 + +--- + +## 1. 兩種模式的差異 + +NinjaFirewall 只有兩種模式（「WP+」是付費版本，不是模式）： + +| | WordPress WAF | Full WAF | +|---|---|---| +| 載入方式 | mu-plugin `0-ninjafirewall.php` | `auto_prepend_file`（`.user.ini` / php.ini） | +| 執行時機 | WordPress 載入中 | **WordPress 載入之前** | +| 讀設定 | `get_option('nfw_options')` | 自行解析 wp-config.php，**原生 mysqli 直查 `{prefix}options`** | +| symlink 安全 | ✅ 站台身分由 WordPress 決定 | ❌ 自行以 `__DIR__` 推導（見 §2） | + +這個差異是後續所有注意事項的根源：**Full WAF 完全繞過 WordPress**，因此 TMDO 的任何 PHP 攔截器對它都不存在，但反過來，TMDO 對 `wp_options` 的**持久性**改動會影響它。 + +--- + +## 2. Symlink / 多租戶部署（必讀） + +WP SaaS 常以 symlink 共享 codebase： + +``` +tenant-a/wp-content/plugins -> /shared/plugins +tenant-b/wp-content/plugins -> /shared/plugins +``` + +Full WAF 在 `lib/firewall.php:78` 這樣推導站台位置： + +```php +$nfw_['wp_content'] = dirname(dirname(dirname( __DIR__ ))); +``` + +**PHP 的 `__DIR__` 會解析 symlink 到真實路徑**，於是每個租戶都被判定為「共享目錄所屬的那個站」。接著 `firewall.php:120-121` 讀到錯誤的 wp-config.php、連到錯誤的資料庫，撈不到該站的 `nfw_options`，最後在 `firewall.php:613` 回傳錯誤碼 6： + +``` +NinjaFirewall fatal error: Cannot retrieve user options from database (#3). +Review your installation, your site is not protected. +``` + +最後那句是字面意義的 —— 此時 WAF 已 `nfw_quit()`，**完全不做任何過濾**。 + +### 解法：以 DOCUMENT_ROOT 為錨點 + +`.htninja` 的搜尋位置是 `$_SERVER['DOCUMENT_ROOT']`（`firewall.php:47-48`），那是 web server 的 per-site 值，不受 symlink 影響。第二順位是 `dirname(DOCUMENT_ROOT)`，因此**一份檔案即可服務所有租戶**： + +```php +`）不會外洩內容，但不該依賴它。 + +### 3.2 每個新租戶站台（順序不可顛倒） + +**順序很重要**：先確保錨點與設定就緒，再安裝 Full WAF。順序顛倒會直接撞上 §2 的 `#3` 錯誤。 + +**Step 1 — 啟用外掛，建立該站自己的設定** + +```bash +wp --path=/var/www/sites/ plugin activate ninjafirewall +wp --path=/var/www/sites/ option list --search='nfw*' --fields=option_name,autoload +# 必須看到 nfw_options 與 nfw_rules，否則後續一定 #3 +``` + +`nfw_options` / `nfw_rules` 存在**該租戶自己的資料庫**，不會因為 codebase 共享而自動存在。這是 `#3` 最常見的成因 —— 路徑修對了，但那個站從沒跑過 installer。 + +**Step 2 — 確認目錄權限** + +php-fpm worker（通常 www-data）必須能在 `nfwlog/` 建立與寫入檔案： + +| 路徑 | 建議 | 理由 | +|---|---|---| +| `wp-content/nfwlog/` 及子目錄 | `2775` `wpdev:www-data` | setgid 確保新檔繼承 group；group 需 `w` 否則 WAF 寫不了 log | +| `nfwlog/` 內檔案 | `664` | 同上 | +| `nfwlog/session/` | 不用管 | 由 WAF 自建，它會用自己的嚴格權限（`0700`） | +| `.user.ini`（裝 Full WAF 後才有） | `664` `wpdev:www-data` | www-data 需可讀，否則 auto_prepend 靜默失效 | + +```bash +NFWLOG=/var/www/sites//wp-content/nfwlog +sudo find "$NFWLOG" -type d -exec chmod 2775 {} + +sudo find "$NFWLOG" -type f -exec chmod 664 {} + +``` + +若 `nfwlog/` 的 owner 本來就是 www-data（例如全程由後台建立），預設 `0755` 也可運作 —— owner 有寫入權。會出事的是「owner 是別人、group 只有 `r-x`」這種組合。 + +**Step 3 — 安裝 Full WAF（從後台）** + +務必從 WordPress 後台操作，不要手工建檔：後台以 www-data 執行，權限天然正確；且官方安裝流程有 sandbox 驗證，會先確認 `auto_prepend_file` 真的生效才寫入設定，避免寫出讓整站 500 的 `.user.ini`。 + +裝完立刻檢查 `.user.ini` 權限（見上表）。`root:root 0640` 是常見的踩雷組合 —— PHP 讀不到，Full WAF 等同沒裝，而表面上一切正常。 + +**Step 4 — 套用 nginx 規則並 reload** + +```bash +sudo nginx -t && sudo systemctl reload nginx +``` + +### 3.3 開站後驗證（每站必跑） + +四項缺一不可。只做前兩項會漏掉最隱蔽的失效模式。 + +```bash +SITE=https://.example.com +NFWLOG=/var/www/sites//wp-content/nfwlog + +# (1) 模式判別 —— 回 Forbidden 代表 Full WAF 生效（auto_prepend 已套用到所有 PHP 請求） +curl -sk "$SITE/wp-content/plugins/ninjafirewall/lib/i18n.php" | head -c 9; echo + +# (2) 攔截能力 —— 應為 403 +curl -sk -o /dev/null -w '%{http_code}\n' "$SITE/?t=../../etc/passwd" + +# (3) 記錄能力 —— 最容易被漏掉的一項，log 必須增長 +before=$(stat -c%s "$NFWLOG/firewall_$(date +%Y-%m).php") +curl -sk -o /dev/null "$SITE/?t=../../etc/passwd" +after=$(stat -c%s "$NFWLOG/firewall_$(date +%Y-%m).php") +[ "$after" -gt "$before" ] && echo "log OK" || echo "log FAIL — 檢查 nfwlog 權限" + +# (4) web 封鎖與功能未損 +for p in /wp-content/nfwlog/ /wp-content/nfwlog/readme.txt /.user.ini /.htaccess; do + printf "%-40s %s\n" "$p" "$(curl -sk -o /dev/null -w '%{http_code}' "$SITE$p")" # 全部應為 403 +done +for p in / /wp-json/ /wp-admin/; do + printf "%-40s %s\n" "$p" "$(curl -sk -o /dev/null -w '%{http_code}' "$SITE$p")" # 200 / 200 / 302 +done +``` + +**第 (3) 項為什麼不能省**：攔截與記錄是兩件事。權限不足時 WAF 照樣回 403，但一筆記錄都寫不進去 —— 你得到一個沒有稽核軌跡的防火牆，事故調查時等於沒有。更嚴重的是同一個權限問題會讓 `session/` 建不出來，而 `wl_admin` 管理員白名單靠 `NFWSESSID` session 承載 `nfw_goodguy` 旗標，於是管理員實際上是被全規則掃描的 —— 這正是「後台操作偶爾莫名 403」的來源。 + +### 3.4 排查時的常見誤判 + +這幾項在實測中都出現過，全部會誤導判斷： + +| 現象 | 直覺結論 | 實際 | +|---|---|---| +| 首頁 200、後台沒有錯誤訊息 | WAF 正常 | 完全不能推論。WAF 失效時是 `nfw_quit()` 靜默放行，不擋也不記 | +| 攻擊 payload 回 403 | Full WAF 生效 | 可能來自共享 mu-plugin 的 WP WAF。用 §3.3 第 (1) 項區分 | +| `nfwlog/` 下的檔案回 403 | nginx 規則生效 | 也可能是 nginx 以 www-data 開不了 root-only 檔案。修好權限後會突然變 200 | +| `/.well-known/` 回 403 | dotfile 規則誤擋了 ACME | 多半是目錄存在但 autoindex off。用實檔測：`/.well-known/acme-challenge/` 若回 404（WordPress 頁面）而非 403，代表規則有正確放行 | +| `wp-login.php` 回 404 | nginx 改壞了 | 檢查是否啟用 `wps-hide-login` 之類的登入頁隱藏外掛 | +| `wp tmdo doctor` 全綠 | WAF 與外掛相容 | WP-CLI 完全豁免 WAF（`firewall.php:18-23`），CLI 結果不能當相容性證據，必須另外走 HTTP 驗證 | + +### 3.5 每租戶獨立的維運負擔 + +symlink 共享的是 codebase，**不是設定與狀態**。以下每一項都是 per-tenant： + +- **`nfw_options` / `nfw_rules`** 存在各自的 `wp_options`。`nfw_rules` 約 77 KB 且 `autoload=auto`，N 個租戶就是 N 份。 +- **規則更新**要逐站執行，沒有集中派送機制。 +- **log / cache / session** 各自獨立（前提是 §2 的 `NFW_LOG_DIR` 已正確設定，否則全部寫進共享目錄互相覆蓋）。 +- **停用租戶站台時**，`nfwlog/readme.txt` 明示：解除安裝後要等 5 分鐘再刪除該目錄，否則站台可能崩潰。 + +規劃階段就要把這些算進成本 —— 特別是「規則更新要逐站跑」這點，租戶數量上去之後需要自動化。 + +--- + +## 4. 開發約束（三條） + +### 4.1 不得重導向 WAF 的設定選項 + +`TMDO_Options_Manager::register_settings_group()` 以 `pre_update_option_{key}` 回傳 `$old_value`，讓選項不再落地 `wp_options`。而 Full WAF 是用原生 mysqli 直查該表 —— 一旦 `nfw_options` / `nfw_rules` 被重導向，WAF 會讀不到設定而**靜默停止防護：不報錯、不寫 log**。 + +v1.0.2 起由 `PROTECTED_OPTIONS` 常數擋下，測試見 `tests/unit/OptionsManagerProtectedTest.php`。新增任何「WordPress 載入前就會以原生 SQL 讀取 `wp_options`」的第三方元件時，必須把它的設定鍵加進該清單。 + +**autoload 最佳化不受此限** —— `optimize_autoload()` 只改 `autoload` 欄位、不刪列，而 Full WAF 那句 `SELECT *` 不看 autoload。 + +### 4.2 不得把 option 名稱字串放進 GET/POST + +規則 **322**（`lev=3`，CRITICAL）： + +``` +(^|\S['"])nfw_(?:options|rules)\b +``` + +任何 GET/POST 值含 `nfw_options` 或 `nfw_rules` 字串即 **403**（why: "Attempt to modify NinjaFirewall settings"）。 + +這對「列出 autoload 清單讓使用者勾選清理」這類 UI 是直接的地雷 —— 而 `nfw_rules` 正好是最大的 autoload 項目之一，必然出現在清單裡。若要做這種介面，用索引或 hash 當作 POST 值，或直接走 CLI。 + +### 4.3 不得以 base64 傳送含 SQL 語意的 payload + +`nfw_check_b64()`（`firewall.php:1412-1448`，`post_b64` 選項，預設開）會把每個 POST 值 base64 解碼後再比對。明文的 SQL 規則多半需要「以數字/引號開頭」或「以註解結尾」才命中，**base64 版只要「含有」就 CRITICAL 403** —— 涵蓋 `SELECT...FROM...WHERE`、`INSERT INTO`、`UNION SELECT`、`UPDATE...SET`、以及序列化物件 `O:n:"..."`。 + +換言之，**編碼會讓事情變糟，不是變好**。硬編碼白名單只有 `fpd_print_order` 與 `g-recaptcha-response` 兩個欄位名。 + +--- + +## 5. 風險矩陣（實測結果） + +於 dev30（**Full WAF**、`wl_admin=1`、`no_restapi=0`、`admin_ajax` 未設）實測。**同一組項目在 WP WAF 模式下結果完全相同** —— 兩種模式都跑過： + +| 項目 | 結果 | +|---|---| +| `wp tmdo status` / `wp tmdo doctor` | ✅ 不受影響（CLI 豁免） | +| `GET /wp-json/wpdo/v1/listings`（**無 cookie**） | ✅ 200，且回的是 JSON 而非 WAF 的 HTML 403 頁 | +| `?hp_price_min=100&hp_featured=1` 動態欄位 filter | ✅ 200 | +| 首頁 / REST 根 | ✅ 200 | +| 後台 `/wp-admin/` | ✅ 302（導向登入） | +| firewall log 中的 TMDO 相關攔截 | ✅ **0 筆**（log 內全部攔截皆為刻意送出的測試 payload） | + +最後一項是判斷相容性的核心證據：不是「沒看到錯誤」，而是逐筆檢查 firewall log 的攔截記錄，確認沒有任何一筆來自本外掛的正常操作。 + +仍需留意的情境： + +| 風險 | 觸發條件 | 緩解 | +|---|---|---| +| Full WAF 靜默失效 | WAF 設定選項被重導向 | §4.1（已由 `PROTECTED_OPTIONS` 擋下） | +| 規則 322 誤擋 | option 名稱字串進 GET/POST | §4.2 | +| migration 中斷 | `run_sync_loop()` 的 110 秒同步 POST（`class-tmdo-migration-orchestrator.php:443` `set_time_limit(120)`）被代理切斷；鎖 `LOCK_TTL_SEC=1800` 才釋放 | 大站用 `force_async=true` 或走 CLI | +| REST 回 HTML 而非 JSON | 非 administrator 角色，或以 Application Password / JWT 呼叫（無 `NFWSESSID` cookie）→ 不在 `wl_admin` 白名單。403 頁面是 HTML（`firewall.php:1585-1590`），client 端看到的是「JSON parse error」這種難查的錯 | 程式化呼叫走 CLI；或確認帶 cookie | +| admin-ajax 被當 bot | `admin_ajax` 選項開啟時，缺 `HTTP_ACCEPT` / `Accept-Language` / UA 不含 `Mozilla` 的請求回 **404**（`firewall.php:1760-1802`） | curl / server-to-server 呼叫需帶完整 header；預設此選項未開 | + +**WP-CLI 完全豁免**：`firewall.php:18-23` 對 `defined('WP_CLI') && WP_CLI && PHP_SAPI === 'cli'` 直接 `return`。TMDO 全部 63 個 CLI 子命令零風險 —— 這也是 migration、snapshot restore、backfill 等重操作建議走 CLI 的另一個理由。 + +**管理員幾乎豁免**：`wl_admin=1` 時，帶 `NFWSESSID` cookie 的 administrator 只跑 3 條規則就 `nfw_quit(20)`（`firewall.php:233-252`）。 + +--- + +## 6. 為什麼不需要 AddOn + +| 理由 | 證據 | +|---|---| +| 無對外 hook API | 全 codebase 零個 `apply_filters('nfw_*')` / `do_action('nfw_*')` | +| 官方相容手段都在部署層 | `.htninja`、`exclude_waf_list` UI、wp-config 常數 —— 沒有一項是 plugin 程式碼掛得上的 | +| 常見衝突模式在 TMDO 全不存在 | 無 loopback self-POST、無 `db.php`/`object-cache.php` drop-in、無 wp-config 改動、無 `auto_prepend` 操作、無 `$_FILES` 上傳 | + +NinjaFirewall 處理「合法外掛送 SQL 被擋」的官方做法是**在引擎裡硬編碼白名單**（例：`firewall.php:1434-1439` 的 JetPack 例外），需向 NinTechNet 回報才會納入，第三方無法自行擴充。 + +因此本外掛的相容性工作全部落在**核心的三條約束**（§4）與**部署設定**（§2），沒有 AddOn 的著力點。 diff --git a/modules/options/class-tmdo-options-manager.php b/modules/options/class-tmdo-options-manager.php index a84ecb4..7eee3e4 100644 --- a/modules/options/class-tmdo-options-manager.php +++ b/modules/options/class-tmdo-options-manager.php @@ -46,6 +46,22 @@ final class TMDO_Options_Manager { 'wpb_backup_options', ); + /** + * 禁止重導向的選項名稱清單 + * + * 這些選項會被「WordPress 載入之前」執行的元件以原生 SQL 直查 wp_options + * （NinjaFirewall Full WAF 走 auto_prepend_file，以 mysqli 讀取 nfw_options + * 與 nfw_rules）。一旦被 register_settings_group() 重導向至專屬設定表， + * 該元件會讀不到設定而靜默停止運作 —— 不報錯、不寫 log。 + * + * 註：autoload 最佳化不受此限，因為那些元件的 SELECT 不看 autoload 欄位。 + */ + private const PROTECTED_OPTIONS = array( + 'nfw_options', + 'nfw_rules', + 'nfw_checked', + ); + /** autoload 合計閾值（MB），超過則警告 */ private const AUTOLOAD_WARNING_THRESHOLD_MB = 1; @@ -202,6 +218,22 @@ final class TMDO_Options_Manager { public static function register_settings_group( string $group_name, array $option_keys ): void { global $wpdb; + // 受保護的選項不得重導向，否則會讓 WordPress 載入前讀取它的元件靜默失效 + foreach ( array_intersect( $option_keys, self::PROTECTED_OPTIONS ) as $protected_key ) { + _doing_it_wrong( + __METHOD__, + esc_html( "選項 {$protected_key} 由 WordPress 載入前的元件以原生 SQL 直讀 wp_options，重導向會使其靜默失效，已略過。" ), + '1.0.2' + ); + } + + $option_keys = array_diff( $option_keys, self::PROTECTED_OPTIONS ); + + // 全部都被擋下就不必建表 + if ( empty( $option_keys ) ) { + return; + } + $table = $wpdb->prefix . TMDO_TABLE_PREFIX . 'settings_' . sanitize_key( $group_name ); // 建立設定專屬表 diff --git a/tests/unit/OptionsManagerProtectedTest.php b/tests/unit/OptionsManagerProtectedTest.php new file mode 100644 index 0000000..cb740ff --- /dev/null +++ b/tests/unit/OptionsManagerProtectedTest.php @@ -0,0 +1,100 @@ +setAccessible( true ); + $prop->setValue( null, array() ); + } + + // ── 常數契約 ──────────────────────────────────────────────────────────── + + public function test_protected_options_covers_ninjafirewall_keys(): void { + $ref = new ReflectionClass( 'TMDO_Options_Manager' ); + $protected = $ref->getConstant( 'PROTECTED_OPTIONS' ); + + $this->assertIsArray( $protected ); + foreach ( array( 'nfw_options', 'nfw_rules', 'nfw_checked' ) as $key ) { + $this->assertContains( + $key, + $protected, + "{$key} 必須列入 PROTECTED_OPTIONS，否則重導向後 NinjaFirewall Full WAF 會靜默失效" + ); + } + } + + // ── 註冊守衛 ──────────────────────────────────────────────────────────── + + public function test_protected_options_are_not_registered(): void { + TMDO_Options_Manager::register_settings_group( + 'waf_guard_test', + array( 'nfw_options', 'nfw_rules', 'nfw_checked' ) + ); + + $this->assertSame( + array(), + TMDO_Options_Manager::get_redirected_options(), + '受保護的選項不得進入重導向清單' + ); + } + + public function test_protected_options_get_no_interception_filters(): void { + TMDO_Options_Manager::register_settings_group( + 'waf_guard_test', + array( 'nfw_options', 'nfw_rules' ) + ); + + $hooks = $GLOBALS['_wp_filter_callbacks'] ?? array(); + + foreach ( array( 'nfw_options', 'nfw_rules' ) as $key ) { + $this->assertArrayNotHasKey( + "pre_option_{$key}", + $hooks, + "pre_option_{$key} 不得被掛上 —— 會讓 WAF 讀到轉址後的值" + ); + $this->assertArrayNotHasKey( + "pre_update_option_{$key}", + $hooks, + "pre_update_option_{$key} 不得被掛上 —— 會讓設定不再寫回 wp_options" + ); + } + } + + /** 全部鍵都被擋下時應提前返回，不建立設定表。 */ + public function test_all_protected_keys_skips_table_creation(): void { + global $wpdb; + + $before = $wpdb->last_query ?? null; + + TMDO_Options_Manager::register_settings_group( + 'waf_guard_test', + array( 'nfw_options' ) + ); + + $this->assertSame( + $before, + $wpdb->last_query ?? null, + '不應對資料庫發出任何查詢' + ); + } +}