WAF 接线离线自测（test-waf-wire.py）¶

位置：deploy/nfos/tools/test-waf-wire.py ｜语言：python3 ｜是否需要 root：否

工具性质：离线自测（只读仓库源码 + 写一个临时沙箱目录） 运行前提：仓库检出必须在场 —— 用 importlib 直接加载 deploy/nfos/gen-waf-from-libs.py。可从任意位置运行（工具会自动向上找到含 deploy/nfos 的祖先目录） 部署状态：随仓库检出运行，不部署到 /opt/Cy/services/system.d/nfos/

用途¶

离线自测 gen-waf-from-libs.py 的接线逻辑：花括号配对 + 历史命名修复 + 幂等。

源码 docstring 说明的动因（逐字引用）：

为什么值得单独测：线上是**静态配置**，插错一行就是 `nginx -t` 失败 + 整站 reload 回滚，
不能在服务器上试错。历史事故正是“include 被插进嵌套块”→ “if directive is not allowed here”。

源码 docstring 列出的 5 个验证点（逐字引用）：

验证点：
  1. include 只插到 `server {` 的 `{` 之后，绝不落进 if/location/map 等嵌套块；
  2. 一个文件里多个 443 server 时每个都插；80 端口的 server 不插；
  3. 历史命名 00-waf-enforce.conf 修成 .inc，且不会重复插；
  4. 幂等：再跑一次不改动；
  5. 插图不改变花括号计数（不破坏结构）。

实际执行的场景：A（全新站点，两个 443 server 都接线）、B（历史 .conf 残留修成 .inc）、C（server_blocks 块结构解析）、D（map 判定链真值表，含 block/log 两种模式）、E（编码容忍 %20/%2e/%2f 改写 + 用 Python re 复核命中语义）。

典型场景¶

改动 gen-waf-from-libs.py（wire_sites / server_blocks / collect / render / tolerant）之后的提交前必跑回归；
线上 nginx -t 报 if directive is not allowed here 一类接线事故时，用它在本地复现“include 插错位置”的假设；
调整特征库 waf: true / waf_action 语义后，验证生成的 map 判定链与真值表仍然正确。

用法与参数¶

本工具不接受任何命令行参数（源码直接执行，无 argparse、无 sys.argv 读取、无环境变量开关）。

参数	类型	默认值	说明
（无）	—	—	命令行参数、环境变量一律不读；全部输入为源码内置样例（`SAMPLE_FRESH` / `SAMPLE_LEGACY` / `SIGS` / `CASES`）

无参数时的默认行为：依次跑完场景 A–E 的全部检查项，打印 PASS/FAIL 行，并清理临时沙箱目录。

示例¶

在仓库根目录执行：

python deploy/nfos/tools/test-waf-wire.py

期望输出形态（分场景，逐项 PASS，末行为结论）：

=== 场景 A：全新站点（两个 443 server 都要接线）===
  PASS  两个 443 server 各插一行  行号=[2, 16]
  ...
=== 结果：全部通过 ===

情形	期望退出码
全部检查项通过（末行 `=== 结果：全部通过 ===`）	`0`
存在失败项（末行 `=== 结果：失败 N 项：[...] ===`）	`1`

依赖与权限¶

语言/版本：Python 3。
第三方依赖：无，标准库 io / os / shutil / sys / importlib.util / re。
仓库依赖：必需。加载 <repo>/deploy/nfos/gen-waf-from-libs.py；_nf_repo_root() 从脚本自身向上找第一个含 deploy/nfos 的祖先目录。
权限：不需要 root。

风险与注意事项¶

不影响线上 nginx：工具在把生成器指向沙箱前先改 genwaf.CONF_DIR = TMP，所有接线都发生在临时目录的 console.conf 副本上；不触碰 /opt/Cy/services/nginx.d/，不执行 nginx -t / reload。
会写文件（仅临时沙箱）：<repo>/.scratch/wire-selftest/（正常结束时 shutil.rmtree 删除）。这是本工具唯一的文件系统改动。
依赖被加载模块的当前实现：因为直接 exec_module 加载真实 gen-waf-from-libs.py，若该模块的模块级代码有副作用（写盘/联网），本自测会一并触发；同时它的函数签名变化会直接让本自测报错（这是预期行为，也是回归价值所在）。
genwaf.render(...) 的断言直接匹配生成的 nginx 片段文本（如 "1:1" 1;、return 403;），若生成器合法重构了输出格式，断言会 FAIL ——那是需要同步更新本自测，而非线上故障。

回滚¶

本工具不部署到线上、不改线上系统；不产出交付物。

落盘位置：<repo>/.scratch/wire-selftest/（及其下的 console.conf）。
恢复正常结束时会自动删除；若中途被中断（Ctrl+C），手动清理即可：

Remove-Item -Recurse -Force .scratch/wire-selftest

除该目录外无其它改动；不需要回滚线上配置。