awoooi/docs/security/NGINX-CONFIG-DRIFT-DETECTOR.md

Nginx 配置只讀漂移偵測器

項目	內容
日期	2026-06-11
狀態	repo_only_detector_ready
工具	scripts/security/nginx-config-drift-detector.py
Snapshot	docs/security/nginx-config-drift-repo.snapshot.json
runtime gate	0

1. 目的

本工具把 Nginx 從「靠人記得不要手改」推進到「有可重跑的 source-of-truth 指紋與後續 live 比對格式」。目前只讀 repo 內配置，不 SSH、不 reload、不修改主機。

2. 已納管 source-of-truth

config id	主機	repo source	live path	等級
host188_all_sites	192.168.0.188	infra/ansible/roles/nginx/templates/188-all-sites.conf.j2	/etc/nginx/sites-enabled/all-sites.conf	C0
host188_internal_tools_https	192.168.0.188	infra/ansible/roles/nginx/templates/188-internal-tools-https.conf.j2	待 owner 確認	C0
host110_ollama_proxy	192.168.0.110	infra/ansible/roles/nginx/templates/110-ollama-proxy.conf.j2	/etc/nginx/sites-enabled/110-ollama-proxy.conf	C1

3. 可產出的證據

工具會輸出：

1. repo raw / normalized SHA-256。
2. server_name 清單。
3. listen 清單。
4. proxy_pass upstream 清單。
5. TLS certificate / key path 清單。
6. /admin route、ACME challenge route、WebSocket route。
7. live conf 若由 owner 提供，會比較 normalized hash、server name、upstream 與 TLS path 差異。

4. 指令

repo-only snapshot：

python3 scripts/security/nginx-config-drift-detector.py \
  --root . \
  --generated-at 2026-06-11T12:00:00+08:00 \
  --output docs/security/nginx-config-drift-repo.snapshot.json

未來 owner 提供 live conf 匯出檔後，可用比較模式：

python3 scripts/security/nginx-config-drift-detector.py \
  --root . \
  --live-file host188_all_sites=/path/to/redacted-live-188-all-sites.conf \
  --live-file host110_ollama_proxy=/path/to/redacted-live-110-ollama-proxy.conf

5. 判讀規則

狀態	意義	可做事項
repo_only_no_live_evidence	只有 repo source-of-truth 指紋，尚未比較 live	可作為 owner request packet，不能宣稱 live 無漂移
matched	owner 提供的 live 檔與 repo normalized hash / 語意比對一致	可記 evidence，仍不代表 reload 已授權
drift_detected	live 與 repo 出現 hash 或語意差異	建立 P0 drift evidence 與 owner decision，不自動覆寫 live
live_file_missing	指定的 live 匯出檔不存在	要求補件，不做判斷

6. 邊界

1. 本工具不執行 SSH。
2. 本工具不執行 nginx -t。
3. 本工具不 reload / restart Nginx。
4. 本工具不讀 TLS private key 內容。
5. 本工具不收 secret value。
6. 本工具不開 runtime gate。

7. 完成度

工作	完成度	說明
repo source-of-truth 指紋	100%	已覆蓋三份 Nginx source templates
domain / upstream / TLS / admin / ACME 摘要	100%	已由 parser 產出
owner-provided live file 比對格式	70%	支援手動提供 live conf 檔，不主動取得 live
live Nginx 證據收集	0%	本階段不 SSH、不讀主機
Nginx reload / restart	0%	未授權且未執行

8. Preflight 銜接

docs/security/PUBLIC-GATEWAY-PREFLIGHT-INVENTORY.md 會消費本工具與 DNS / TLS 清冊的 repo-only 結果，固定 Nginx reload / route change 前必備的 owner、live conf、rendered diff、nginx -t、route smoke、maintenance window 與 rollback owner 欄位。

此銜接仍不代表 live conf 已收、drift 已判定、nginx -t 已執行或 reload 已授權。