cognis-digital/wafproof

# wafproof **使用标记的 canary 语料库验证你自己的检测规则。** `wafproof` 是一个小巧且无依赖的测试工具，用于衡量*你的*检测函数或 WAF 风格的 regex 规则集在捕获已知恶意输入时的效果，同时**不会误报良性的相似输入**。它提供了一组精心挑选且原创的简短、通用 canary 模式语料库，涵盖常见的类别（XSS、SQL 注入、路径遍历、命令注入），每个恶意模式都配有相似的良性字符串，并通过你提供的检测器运行它们，以计算检出率、误报率、精确率/召回率以及各个类别的细分情况。 许可证：COCL 1.0 ## 被动模式与主动模式 `wafproof` 有两种模式，其中安全模式为默认模式。 **被动模式（默认 —— 完全离线）。** 除 `probe` 外的每个命令（`run`、`report`、`corpus`、`evade`、`diagnose`、`scan`、`enrich`）都是被动的：它只读取本地输入 —— 规则集、标记过的语料库、请求字段转储、保存的 HAR 捕获记录、SBOM —— 将字符串通过*你*提供的检测器进行处理，并统计命中数。**绝不联网。** 这是你日常使用的模式。 **主动模式（`probe`）—— 仅限授权使用，默认关闭。** `probe` 是唯一接触网络的命令。它会将 `wafproof` 自身的通用检测 canary 发送到**你拥有或获得明确授权测试的目标**，并记录该目标*自身*的 WAF 是否拦截了它们 —— 这是对*你的*边界防御进行的防御性冒烟测试，而非攻击。除非满足**所有**以下条件，否则它将拒绝运行： - 传入 `--authorized`（明确的操作者确认；默认为 OFF）， - 提供非空的范围内主机名 `--target-allowlist`，且目标主机包含其中（在发送任何字节之前，其他任何主机都会被拒绝）， - 强制执行正数的 `--rate-limit`（请求/秒，默认为 `1.0`），以确保探测永远不会演变成洪水攻击。 这里没有任何漏洞利用 payload：canary 是简短的、通用的、长度受限的字符串，其目的就是被*识别并拦截*。每次主动运行时都会打印显眼的授权使用横幅。**只能将其指向你已获授权测试的系统 —— 未经授权的探测可能是违法的。** ``` # refused — active mode 默认关闭 wafproof probe --target http://staging.internal/search --target-allowlist staging.internal # -> error: active probing 默认禁用；请传递 --authorized ... # allowed — 明确同意 + scope + rate limit，针对您自己的 host wafproof probe --target http://staging.internal/search \ --authorized --target-allowlist staging.internal --rate-limit 2 ``` ## 为什么需要它 当你编写或加强 WAF 规则、regex 黑名单或自定义检测函数时，可能会出现两种问题，而你通常在生产环境中才会发现它们： 1. **覆盖盲区** —— 规则遗漏了它本应捕获的攻击特征（假阴性；低召回率/检出率）。 2. **误报** —— 规则拦截了仅仅*看起来*可疑的合法流量（假阳性；例如将名字 `O'Brien` 误报为 SQLi）。 `wafproof` 将这两者转化为你可以随时间观察并在 CI 中作为门控指标的数值。 ## 安装 ``` pip install -e . ``` 仅使用标准库，支持 Python 3.10+。会安装一个 `wafproof` 控制台命令。 ## 快速开始 使用内置语料库评估捆绑的示例规则集： ``` wafproof run --rules examples/rules.json ``` ``` Detection evaluation ============================================================ corpus entries : 27 TP=15 FP=0 FN=0 TN=12 detection rate (recall) : 100.00% precision : 100.00% F1 : 100.00% false-positive rate : 0.00% accuracy : 100.00% Per category ------------------------------------------------------------ category recall prec fpr n command-injection 100.0% 100.0% 0.0% 7 path-traversal 100.0% 100.0% 0.0% 6 sqli 100.0% 100.0% 0.0% 7 xss 100.0% 100.0% 0.0% 7 ``` 示例规则集经过精心设计，在内置语料库上得分完美，为你提供了一个现成的参考。将 `--rules` 指向*你的*规则集，观察 FN/FP 列亮起 —— 这些正是你需要调查的条目。 ## 命令 ### `wafproof run` 评估检测器并打印指标表（或使用 `--json`）。 ``` wafproof run --rules my_rules.json wafproof run --rules my_rules.json --json wafproof run --callable mypkg.detect:is_malicious ``` 任何遗漏的 canary（假阴性）和误报（假阳性）都会按 id 和类别列出，让你清楚知道需要修复哪个规则。 添加 `--sarif FILE`（用于 `run` 或 `report`）还可以为每个假阴性和假阳性输出 **SARIF 2.1.0** 报告 —— 请参阅下文的[SARIF 导出](#sarif-export-code-scanning)。 ### `wafproof corpus` 列出带标签的语料库，可选择按类别筛选。 ``` wafproof corpus wafproof corpus --category sqli wafproof corpus --json ``` ### `wafproof report` 评估并对召回率应用 **通过/失败门控** —— 如果检测覆盖率低于阈值，则以非零状态退出。将其放入 CI 中，以便在有人“简化”规则时捕获覆盖率的回退。 ``` wafproof report --rules my_rules.json --fail-under 0.8 echo $? # 0 if recall >= 0.8, else 1 ``` ### `wafproof evade` **对 canary 实现 100% 的召回率并不意味着 100% 安全。** 一个能捕获 `