# WAF 检测器
[](https://github.com/SecH0us3/waf-checker/releases)
[](https://github.com/SecH0us3/waf-checker/releases)
[](packages/core)
[](packages/cli)
[]()
本项目可帮助你检查你的 Web 应用防火墙（WAF）对常见 Web 攻击的防护效果。它既可以作为 Cloudflare Worker 运行（内置交互式 Web UI），也可以作为独立的 Node.js CLI 工具运行。
## 🧪 测试覆盖率与状态
所有包均通过自动化单元测试、集成测试、基于属性的测试（fast-check 模糊测试）、网络韧性测试和逆向工程测试套件进行了全面测试（100% SSRF 安全合规、协议规避技术和报告格式化器）：
| 包 | 行覆盖率 | 语句 | 函数 | 测试套件 |
| :--- | :---: | :---: | :---: | :---: |
| [**`@waf-checker/core`**](https://github.com/sech0us3/waf-checker/blob/main/packages/core) | `93.0%` 🟢 | `92.6%` | `96.4%` | 🟢 282 项通过 |
| [**`@waf-checker/cli`**](https://github.com/sech0us3/waf-checker/blob/main/packages/cli) | `93.5%` 🟢 | `92.8%` | `96.7%` | 🟢 54 项通过 |
| [**`@waf-checker/worker`**](https://github.com/sech0us3/waf-checker/blob/main/packages/worker) | `通过` 🟢 | — | — | 🟢 30 项通过 |
| **单仓库测试套件总计** | **`93.2%`** | **`92.7%`** | **`96.6%`** | **🟢 366 项测试通过** |
## 功能特性
### 核心测试
- 输入目标 URL，选择 HTTP 方法（GET、POST 等）和攻击类别。
- 发送携带攻击载荷的请求（位于参数、请求头或文件路径中）。
- 终端和 Web 结果采用颜色编码：🟢 403/BLOCKED = 已拦截，🔴 2xx/5xx = 可能存在绕过，🟠 3xx = 重定向。
- 结果以可筛选的表格展示，并附有每个载荷的详细信息。
### 🕵️ WAF 逆向工程与 CRS 矩阵（`--reverse`）
- **OWASP 核心规则集（CRS v3/v4）映射**：审计启用与禁用的规则 ID（`920xxx`、`921xxx`、`930xxx`、`931xxx`、`932xxx`、`933xxx`、`934xxx`、`941xxx`、`942xxx`、`943xxx`、`944xxx`）及其偏执等级（PL1-PL4）。
- **检查请求体限制检测**：通过二分搜索探测（8KB – 128KB，精度约 1KB）识别缓冲区截断边界。
- **异常评分模式检测**：探测协作评分模式与严格正则拦截模式，并识别评分阈值。
- **安全速率限制探测**：安全地逐步提升至最高 30 req/s，一旦收到 HTTP 429 立即提前终止，并提取 `Retry-After`。
### 🛡️ WAF 虚拟补丁与自动修复（`--patch` / `patch` 命令）
- **即时缓解**：自动将检测到的 WAF 绕过（HTTP 200）转换为可直接部署的防火墙规则、反向代理配置和基础设施即代码（Terraform HCL / Cloud CLI）。
- **支持的平台（11 种方言）**：
- **Cloudflare WAF**：Wirefilter 表达式（`http.request.uri.query contains ...` / `matches ...`）及 `cloudflare_ruleset` Terraform HCL。
- **AWS WAF v2**：原生 JSON 规则语句（`ByteMatchStatement`、`RegexPatternSet`、`OrStatement`）及 `aws_wafv2_rule_group` Terraform HCL。
- **Google Cloud Armor**：CEL 表达式（`request.path.matches(...)`、`request.headers[...]`）、`gcloud compute security-policies` CLI 命令及 Terraform `google_compute_security_policy`。
- **Azure WAF（Front Door 与 App Gateway）**：自定义规则 JSON 定义、`az network front-door waf-policy` CLI 命令及 Terraform `azurerm_cdn_frontdoor_firewall_policy`。
- **ModSecurity 与 OWASP Coraza**：兼容 OWASP CRS 的 `SecRule` 指令（SecLang），支持 `@pm` 令牌折叠。通过 `--patch modsecurity` 或 `--patch coraza` 支持。
- **NGINX**：原生 `location ~* \.(ext)$ { return 403; }`、`location ~ /\.(git|svn)` 及 `map` 配置块。
- **HAProxy**：高性能原生 ACL（`path_end -i`、`path_beg -i`、`query -m sub -i`、`req.hdr()`）配合 `http-request deny deny_status 403`。
- **Caddy Server**：地道的 Caddyfile 命名匹配器（`@waf_patch_*`），配合 CEL 表达式（`expression {http.request.uri.query}.matches(...)`）和 `respond 403`。
- **Apache HTTP Server**：用于 `httpd.conf`、`<VirtualHost>` 或 `.htaccess` 的 `mod_rewrite` 规则（`RewriteCond %{QUERY_STRING}` / `%{REQUEST_URI}` / `%{HTTP_USER_AGENT}` + `RewriteRule ^ - [F,L]`）。通过 `--patch apache` 支持。
- **Envoy Proxy**：通过 RE2 `safe_regex` 匹配 `:path`/请求头的路由条目，配合 `direct_response: 403`（或在模拟模式下转发并标记），用于 route_configuration 的 virtual_host。通过 `--patch envoy` 支持。
- **Kubernetes Ingress（K8s）**：生产就绪的 `kind: Ingress` YAML 清单，带有 `nginx.ingress.kubernetes.io/server-snippet` 注解。
- **双层防御**：
- **严格热修复**：精确令牌签名，**0% 误报风险**，用于即时零日事件响应。
- **启发式模式**：覆盖整个漏洞类别结构的通用正则表达式。
- **Web UI 修复工作室**：交互式仪表盘模态框，提供所有厂商的实时预览、一键复制到剪贴板、格式切换和文件导出。
### 攻击类别（共 28 种）
SQL 注入、XSS、命令注入、路径遍历、SSRF、本地文件包含、敏感文件、开放重定向、SSTI、XXE、NoSQL 注入、GraphQL 注入、JWT 攻击（Header）、JWT 攻击（Param）、原型污染（JSON Body）、原型污染（URL/Param）、LDAP 注入、XPath 注入、电子表格公式注入、Log4Shell（JNDI）、CRLF 注入、HTTP 参数污染、User-Agent、IP 绕过、HTTP 请求走私、Web 缓存投毒、UTF8/Unicode 绕过、WAF 检查限制绕过（填充）。
### WAF 检测
- 测试前自动检测 WAF 类型（Cloudflare、AWS WAF、OWASP Coraza、BunkerWeb、ModSecurity、Akamai、Imperva、F5 BIG-IP 等）。
- 根据检测到的 WAF 建议特定的绕过技术。
- 可自动切换为针对特定 WAF 的高级载荷。
### 高级载荷与编码
- WAF 绕过载荷 — 双重编码、unicode、大小写混合、注释注入、多语言载荷。
- 增强载荷 — 现代规避技术。
- 编码变体 — URL、Unicode、HTML 实体、Hex、八进制、Base64 编码及自动组合。
- 针对 Cloudflare、AWS WAF、ModSecurity 的特定 WAF 绕过。
### HTTP 协议操纵
- HTTP 动词篡改 — 测试不常见的 HTTP 方法。
- 参数污染 — 在查询/正文中重复和拆分参数。
- Content-Type 混淆 — 使用替代内容类型绕过规则。
- 请求走私头部。
- Host 头部注入变体。
- 通过头部覆盖 HTTP 方法（`X-HTTP-Method-Override` 等）。
### 批量测试
- 一次测试多个 URL。
- 可配置的并发数和请求间延迟。
- 实时进度跟踪。
### 🔀 回归差异对比（`--compare` / `--fail-on-regression`）
- 将扫描结果与之前保存的 JSON 报告进行差异对比，以呈现**新的绕过**（之前被阻止，现在未被阻止）、**新被阻止**的载荷，以及新增/移除的测试。
- CI 门禁（`--fail-on-regression`），仅在 WAF 态势*恶化*时失败，而非在完整结果列表上失败 — 非常适合捕获托管规则集的漂移。
---
## 项目结构
该项目采用 NPM Workspaces monorepo 结构：
- [**`packages/core/`**](file:///Users/alex/src/waf-checker/packages/core)：核心安全测试库、载荷定义、WAF 指纹识别签名和混淆编码器。
- [**`packages/worker/`**](file:///Users/alex/src/waf-checker/packages/worker)：Cloudflare Worker 包，提供静态 HTML/JS Web UI 和 JSON API 端点。
- [**`packages/cli/`**](file:///Users/alex/src/waf-checker/packages/cli)：Node.js 命令行界面工具，用于直接从终端执行审计。
---
## 安装与构建
从根目录安装依赖并构建所有工作区：
```bash
npm install
npm run build
```
## 如何运行
### 1. Web 版本（Cloudflare Worker）
要在本地运行 Worker 开发服务器（需要 Wrangler）：
```bash
npm run dev:worker
```
Web UI 可通过 `http://localhost:8787` 访问（如果 8787 端口被占用，则使用其他端口）。
要将 Worker 部署到 Cloudflare：
```bash
npx wrangler deploy --workspace=packages/worker
```
Worker 需要 **Workers Paid** 计划：扫描和审计页面的规模是按照每次请求 10,000 个子请求来设计的（`wrangler.toml` 中的 `[limits] subrequests`，`packages/core/src/check.ts` 中的 `WORKER_SUBREQUEST_LIMIT`）。Free 计划每次请求只允许 50 个外部子请求：一个扫描页面如果启用了 User-Agent 绕过测试（UI 中默认开启）或跟随重定向，就会超出该限制。
### 2. CLI 版本（Node.js）
#### 将其安装为全局 `waf-checker` 命令（推荐）
在仓库根目录执行 `npm install && npm run build` 之后，链接 CLI，使其可以从**任意目录**运行——无需 `cd` 进入仓库，也无需使用冗长的 `node .../dist` 路径：
```bash
# Expose `waf-checker` on your PATH from the built workspace
npm link --workspace @waf-checker/cli
# …now, from anywhere:
waf-checker --help
waf-checker check https://example.com
# Uninstall later with:
npm rm -g @waf-checker/cli
```
已发布的包已捆绑其代码，因此你也可以在没有仓库的情况下全局安装打包构建：`npm pack --workspace @waf-checker/cli`，然后 `npm i -g ./waf-checker-cli-*.tgz`。
#### Shell 补全（bash / zsh / fish）
`waf-checker completion <shell>` 会打印补全脚本（省略 `<shell>` 则从 `$SHELL` 自动检测）：
```bash
# bash
waf-checker completion bash | sudo tee /etc/bash_completion.d/waf-checker
# or, without root: echo 'source <(waf-checker completion bash)' >> ~/.bashrc
# zsh (into a directory on your $fpath)
waf-checker completion zsh > "${fpath[1]}/_waf-checker"
# fish
waf-checker completion fish > ~/.config/fish/completions/waf-checker.fish
```
#### 无需全局安装即可运行
你始终可以直接调用构建后的入口点：
```bash
# Print general CLI help and usage
node packages/cli/dist/index.js --help
# Print check command help (lists all methods, categories, and WAF vendors)
node packages/cli/dist/index.js check --help
# Discover detectable WAF vendors and payload categories (JSON for automation)
node packages/cli/dist/index.js list-wafs --json
node packages/cli/dist/index.js list-categories --json
```
#### WAF 检测
检测目标 URL 背后的 WAF 厂商：
```bash
node packages/cli/dist/index.js detect <url>
```
#### 漏洞载荷审计
针对目标 URL 运行审计：
```bash
# Default check (GET method, all payload categories)
node packages/cli/dist/index.js check https://example.com
# Custom check with specific methods, categories, and WAF evasion enabled
node packages/cli/dist/index.js check https://example.com -m GET,POST -c "SQL Injection,XSS" --auto-detect-waf --encoding-variations
```
#### 批量审计
对文件中定义的 URL 列表运行批量审计：
```bash
node packages/cli/dist/index.js batch targets.txt --concurrency 3
```
#### 生成报告
将审计结果保存为 **SARIF**、**JUnit XML**、**HTML**、**Markdown**、**CSV** 或 **JSON** 格式：
```bash
# Generate SARIF report for GitHub Code Scanning
node packages/cli/dist/index.js check https://example.com -o results.sarif
# Generate JUnit XML for CI test reporting (GitHub Actions, GitLab CI, Jenkins)
node packages/cli/dist/index.js check https://example.com -o results.xml
# Generate interactive HTML report
node packages/cli/dist/index.js check https://example.com -o report.html
# Generate Markdown summary for CI
node packages/cli/dist/index.js check https://example.com -o summary.md
```
> 报告格式由输出文件扩展名推断，或通过 `-f, --format`（`json`、`csv`、`html`、`sarif`、`markdown`、`junit`）显式指定。每个攻击载荷都会成为一个 JUnit `<testcase>`；WAF 绕过会报告为 `failure`，传输/服务器错误会报告为 `error`，因此 CI 运行器会直接将其呈现出来。
#### CI/CD 集成与防护阈值
当防护率低于所需阈值或检测到绕过时，使 CI/CD 流水线失败：
```bash
# Fail if WAF protection rate is below 95%
node packages/cli/dist/index.js check https://example.com --threshold 95 -q
# Fail immediately on any detected bypass
node packages/cli/dist/index.js check https://example.com --fail-on-bypass -q
```
#### 🔀 回归差异对比（扫描 vs 扫描）
WAF 防护态势会随时间发生漂移——厂商发布托管规则集更新、某条 CRS 规则被禁用、源站变更导致判定结果改变。与其每次运行都重新对完整结果列表进行分诊，不如与之前保存的 JSON 报告进行对比，并仅在*恶化*时对 CI 进行门禁。在基线报告中为 `blocked` 且现在不再被拦截的 payload 计为回归；新被拦截的 payload 计为改进。匹配依据为 `(category, method, evasion technique, payload)`，网络错误 / 源站侧拦截被视为不确定，因此它们绝不会显示为误报的回归。
```bash
# Save a known-good baseline report
node packages/cli/dist/index.js check https://example.com -f json -o baseline.json -q
# Later: diff the current scan against it and print regressions/improvements
node packages/cli/dist/index.js check https://example.com --compare baseline.json -q
# Fail CI only when a previously-blocked payload is no longer blocked
node packages/cli/dist/index.js check https://example.com --compare baseline.json --fail-on-regression -q
```
#### 🛡️ 虚拟补丁与自动修复
自动生成可立即部署的防火墙规则，覆盖全部 11 个受支持的平台（`cloudflare`、`aws`、`gcp`、`azure`、`modsecurity`、`nginx`、`haproxy`、`caddy`、`apache`、`envoy`、`k8s` 或 `all`）：
```bash
# Generate and save Cloudflare Terraform rules during audit
node packages/cli/dist/index.js check https://example.com --patch cloudflare --patch-output ./cloudflare-patch.tf
# Generate GCP Cloud Armor gcloud commands and Terraform
node packages/cli/dist/index.js check https://example.com --patch gcp --patch-output ./cloud-armor.sh
# Generate Azure WAF rules with simulation (Log) mode
node packages/cli/dist/index.js check https://example.com --patch azure --patch-action simulate --patch-output ./azure-rules.json
# Generate HAProxy ACLs for haproxy.cfg
node packages/cli/dist/index.js check https://example.com --patch haproxy --patch-output ./haproxy-patches.cfg
# Generate Caddyfile named matchers
node packages/cli/dist/index.js check https://example.com --patch caddy --patch-output ./patches.caddyfile
# Generate Apache mod_rewrite rules for .htaccess
node packages/cli/dist/index.js check https://example.com --patch apache --patch-output ./patches.htaccess
# Generate Kubernetes Ingress YAML manifests
node packages/cli/dist/index.js check https://example.com --patch k8s --patch-output ./ingress-patch.yaml
# Generate patches for all vendors from a saved JSON audit report file
node packages/cli/dist/index.js patch audit-report.json --waf all --output ./patches/
```
#### 🐳 本地 Docker 与预发布环境测试（`--allow-local`）
默认情况下，`waf-checker` 会严格阻止私有 IP 范围（`127.0.0.1`、`10.0.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16`），以防止服务端请求伪造（SSRF）。在测试你自己的本地 Docker 容器或预发布服务器时，请使用 `--allow-local`：
```bash
# Audit a local OWASP ModSecurity Docker container and run reverse engineering
node packages/cli/dist/index.js check http://127.0.0.1:8088/ --allow-local --reverse
# Audit a local Caddy or HAProxy reverse proxy and generate patches
node packages/cli/dist/index.js check http://127.0.0.1:8089/ --allow-local --patch caddy
```
#### 🧪 自动化实时 Docker E2E 测试套件（`npm run test:e2e`）
通过一条命令对实时 Docker 容器（ModSecurity CRS、Caddy、HAProxy、NGINX 和后端）运行端到端集成审计：
```bash
npm run test:e2e
```
查看完整的 [本地 WAF 测试与端到端验证指南](https://github.com/sech0us3/waf-checker/blob/main/docs/LOCAL_WAF_TESTING.md)，了解完整基准测试、架构图和手动复现步骤。
---
## 🚀 GitHub Action (CI/CD)
将自动化 WAF 安全测试集成到你的 GitHub Actions 工作流中：
```yaml
name: WAF Security Audit
on:
push:
branches: [ main ]
schedule:
- cron: '0 0 * * 1' # Weekly audit
jobs:
waf-audit:
runs-on: ubuntu-latest
permissions:
security-events: write # Required for SARIF upload
contents: read
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Run WAF Checker
uses: SecH0us3/waf-checker@main
with:
target-url: 'https://staging.example.com'
threshold: '95'
enhanced: 'true'
advanced: 'true'
sarif-output: 'waf-results.sarif'
html-output: 'waf-report.html'
- name: Upload SARIF to GitHub Security Tab
if: always()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: 'waf-results.sarif'
- name: Upload HTML Report Artifact
if: always()
uses: actions/upload-artifact@v4
with:
name: waf-audit-report
path: waf-report.html
```
### 3. Docker 版本
你可以使用 Docker 运行 CLI，既可以从 GitHub Container Registry 拉取预构建镜像，也可以在本地构建。
#### 使用预构建镜像（推荐）
预构建的 Docker 镜像可在 [GitHub Container Registry](https://github.com/SecH0us3/waf-checker/pkgs/container/waf-checker-cli) 上获取，地址为 `ghcr.io/sech0us3/waf-checker-cli`。
##### 拉取镜像
```bash
docker pull ghcr.io/sech0us3/waf-checker-cli:latest
```
##### 打印帮助
```bash
docker run --rm ghcr.io/sech0us3/waf-checker-cli:latest --help
```
##### 运行检查
```bash
docker run --rm -it ghcr.io/sech0us3/waf-checker-cli:latest check https://example.com
```
##### 运行批量审计（挂载本地目录）
```bash
docker run --rm -it -v "$(pwd):/data" ghcr.io/sech0us3/waf-checker-cli:latest batch /data/targets.txt --concurrency 3
```
#### 本地构建
##### 构建镜像
```bash
docker build -t waf-checker-cli .
```
##### 打印帮助
```bash
docker run --rm waf-checker-cli --help
```
##### 运行检查
```bash
docker run --rm -it waf-checker-cli check https://example.com
```
##### 运行批量审计（挂载本地目录）
```bash
docker run --rm -it -v "$(pwd):/data" waf-checker-cli batch /data/targets.txt --concurrency 3
```
## 🔌 API 与集成（面向外部调用方与模糊测试器）
Cloudflare Worker 暴露了一个公共 REST API，供扫描器和模糊测试器（包括 [swazz](https://github.com/SecH0us3/swazz)）调用。完整的 OpenAPI 3.1 规范见 [`docs/openapi.yaml`](https://github.com/sech0us3/waf-checker/blob/main/docs/openapi.yaml)。
### 端点概览
| 端点 | 方法 | 描述 |
|---|---|---|
| `/api/waf-detect` | `GET` | 指纹识别 WAF 厂商、置信度评分以及建议的绕过方式。 |
| `/api/check` | `GET`、`POST` | 使用攻击载荷探测目标。支持分页与类别过滤。 |
| `/api/virtual-patch` | `POST` | 为 Cloudflare、AWS、ModSec、NGINX、Caddy、HAProxy、Coraza 生成修复规则。 |
| `/api/reverse-engineer` | `GET`、`POST` | 逆向分析 OWASP CRS 规则、异常阈值和请求体限制。 |
| `/api/audit` | `GET`、`POST` | **统一审计**：执行检测、安全检查与虚拟补丁，通常在一次请求中完成（参见审计分页）。 |
### 关键集成特性
- **分页信封（`?envelope=1` 或 `?envelope=true`）**：
将结果包装在带有分页元数据的结构化信封中：
```json
{
"results": [...],
"page": 0,
"pageSize": 50,
"total": 72,
"hasMore": true
}
```
*（省略 `?envelope=1` 以接收向后兼容的默认裸 JSON 数组）。*
- **审计分页（`/api/audit`）**：
除非其计划超出单个 Cloudflare Worker 请求的子请求预算所允许的范围（1658 项），否则审计会在一次响应中返回所有内容（`hasMore: false`）。这涵盖了未检测到 WAF 的情况（513 项）以及每个 WAF 的绕过变体直至 Sophos（1321 项）；受 Qrator 保护的目标（2441 项）会分两页返回，任何传入较小 `pageSize` 的审计也是如此。响应携带 `page`、`pageSize`、`total`、`hasMore` 和 `detectedWAF`（若未找到则为 `""`）。当 `hasMore` 为 true 时，请求 `page=<page + 1>&detectedWAF=<detectedWAF>`；回传 `detectedWAF` 会跳过重新检测（此时 `detection` 为 `null`）并保持分页边界稳定。`patches` 涵盖该响应的结果；对于跨多页的单个捆绑包，将合并后的 `results` `POST` 到 `/api/virtual-patch`。
- **归一化置信度（`/api/waf-detect`）**：
在原始 `confidence` 和 `confidenceThreshold`（`40`）之外，还提供 `confidencePercent`（0–100）。
- **逐结果判定与拦截标志**：
每个 `AuditResultItem` 都包含：
- `blocked: boolean` — WAF 是否在到达源站之前进行了干预。
- `verdict: 'blocked' | 'passed' | 'exposed'` — 区分泄漏（`exposed`）与覆盖缺口（`passed`）的不同结果。
- `error: string | null` — 网络中断时的显式错误类别（例如 `'timeout'`、`'dns'`、`'connection_reset'`）。
- **自扫描拒绝（HTTP 422）**：
拒绝针对服务基础设施的意外自扫描，返回 `{ "error": "self-scan refused", "code": "SELF_SCAN_REFUSED" }`。
---
## 测试
要运行整个工作区的测试套件（使用 Vitest）：
```bash
npm test
```
---
阅读我的博客：[yoursec.substack.com](https://yoursec.substack.com/)
