waf-checker

# WAF Checker

[![GitHub Release](https://img.shields.io/github/v/release/SecH0us3/waf-checker?color=blue&label=release)](https://github.com/SecH0us3/waf-checker/releases)
[![GitHub Action](https://img.shields.io/badge/action-v1-blue?logo=githubactions&logoColor=white)](https://github.com/SecH0us3/waf-checker/releases)
[![Coverage: Core](https://img.shields.io/badge/coverage:%20core-93.0%25-brightgreen)](packages/core)
[![Coverage: CLI](https://img.shields.io/badge/coverage:%20cli-93.5%25-brightgreen)](packages/cli)
[![Tests](https://img.shields.io/badge/tests-366%20passed-brightgreen)]()

This project helps you check how well your Web Application Firewall (WAF) protects your product against common web attacks. It can be run as a Cloudflare Worker (with a built-in interactive Web UI) or as a standalone Node.js CLI tool.

## 🧪 Test Coverage & Status

All packages are thoroughly tested with automated unit, integration, property-based (fast-check fuzzing), network resilience, and reverse engineering suites (100% SSRF safety compliance, protocol evasion techniques, and report formatters):

| Package | Line Coverage | Statements | Functions | Test Suite |
| :--- | :---: | :---: | :---: | :---: |
| [**`@waf-checker/core`**](https://github.com/sech0us3/waf-checker/blob/main/packages/core) | `93.0%` 🟢 | `92.6%` | `96.4%` | 🟢 282 passing |
| [**`@waf-checker/cli`**](https://github.com/sech0us3/waf-checker/blob/main/packages/cli) | `93.5%` 🟢 | `92.8%` | `96.7%` | 🟢 54 passing |
| [**`@waf-checker/worker`**](https://github.com/sech0us3/waf-checker/blob/main/packages/worker) | `Passing` 🟢 | — | — | 🟢 30 passing |
| **Total Monorepo Suite** | **`93.2%`** | **`92.7%`** | **`96.6%`** | **🟢 366 tests passing** |

## Features

### Core Testing
- Enter a target URL, pick HTTP methods (GET, POST, etc.), and attack categories.
- Sends requests with attack payloads (in parameters, headers, or as file paths).
- Color-coded terminal and web results: 🟢 403/BLOCKED = blocked, 🔴 2xx/5xx = potential bypass, 🟠 3xx = redirect.
- Results displayed in a filterable table with details for each payload.

### 🕵️ WAF Reverse Engineering & CRS Matrix (`--reverse`)
- **OWASP Core Rule Set (CRS v3/v4) Mapping**: Audits active vs disabled rule IDs (`920xxx`, `921xxx`, `930xxx`, `931xxx`, `932xxx`, `933xxx`, `934xxx`, `941xxx`, `942xxx`, `943xxx`, `944xxx`) with Paranoia Levels (PL1-PL4).
- **Inspection Body Limit Detection**: Binary search probing (8KB – 128KB, precision ~1KB) to identify buffer truncation boundaries.
- **Anomaly Scoring Mode Detection**: Probes collaborative scoring mode vs strict regex blocking mode and identifies score thresholds.
- **Safe Rate Limit Probing**: Safe ramp-up up to 30 req/s with immediate early termination upon HTTP 429 and `Retry-After` extraction.

### 🛡️ WAF Virtual Patching & Auto-Remediation (`--patch` / `patch` command)
- **Instant Mitigation**: Automatically transforms detected WAF bypasses (HTTP 200) into ready-to-deploy firewall rules, reverse proxy configurations, and Infrastructure-as-Code (Terraform HCL / Cloud CLI).
- **Supported Platforms (11 Dialects)**:
  - **Cloudflare WAF**: Wirefilter expressions (`http.request.uri.query contains ...` / `matches ...`) & `cloudflare_ruleset` Terraform HCL.
  - **AWS WAF v2**: Native JSON Rule Statements (`ByteMatchStatement`, `RegexPatternSet`, `OrStatement`) & `aws_wafv2_rule_group` Terraform HCL.
  - **Google Cloud Armor**: CEL expressions (`request.path.matches(...)`, `request.headers[...]`), `gcloud compute security-policies` CLI commands, & Terraform `google_compute_security_policy`.
  - **Azure WAF (Front Door & App Gateway)**: Custom Rule JSON definitions, `az network front-door waf-policy` CLI commands, & Terraform `azurerm_cdn_frontdoor_firewall_policy`.
  - **ModSecurity & OWASP Coraza**: OWASP CRS-compatible `SecRule` directives (SecLang) with `@pm` token collapsing. Supported via `--patch modsecurity` or `--patch coraza`.
  - **NGINX**: Native `location ~* \.(ext)$ { return 403; }`, `location ~ /\.(git|svn)`, and `map` configuration blocks.
  - **HAProxy**: High-performance native ACLs (`path_end -i`, `path_beg -i`, `query -m sub -i`, `req.hdr()`) with `http-request deny deny_status 403`.
  - **Caddy Server**: Idiomatic Caddyfile named matchers (`@waf_patch_*`) with CEL expressions (`expression {http.request.uri.query}.matches(...)`) and `respond 403`.
  - **Apache HTTP Server**: `mod_rewrite` rules (`RewriteCond %{QUERY_STRING}` / `%{REQUEST_URI}` / `%{HTTP_USER_AGENT}` + `RewriteRule ^ - [F,L]`) for `httpd.conf`, `<VirtualHost>`, or `.htaccess`. Supported via `--patch apache`.
  - **Envoy Proxy**: Route entries matching `:path`/headers via RE2 `safe_regex` with `direct_response: 403` (or forward-and-tag in simulate mode) for a route_configuration virtual_host. Supported via `--patch envoy`.
  - **Kubernetes Ingress (K8s)**: Production-ready `kind: Ingress` YAML manifests with `nginx.ingress.kubernetes.io/server-snippet` annotations.
- **Dual-Tier Defense**:
  - **Strict Hotfix**: Exact token signatures with **0% false positive risk** for immediate zero-day incident response.
  - **Heuristic Pattern**: Generalized regular expressions covering the entire vulnerability class structure.
- **Web UI Remediation Studio**: Interactive dashboard modal with live previews across all vendors, 1-click clipboard copy, format toggles, and file export.

### Attack Categories (28 total)
SQL Injection, XSS, Command Injection, Path Traversal, SSRF, Local File Inclusion, Sensitive Files, Open Redirect, SSTI, XXE, NoSQL Injection, GraphQL Injection, JWT Attack (Header), JWT Attack (Param), Prototype Pollution (JSON Body), Prototype Pollution (URL/Param), LDAP Injection, XPath Injection, Spreadsheet Formula Injection, Log4Shell (JNDI), CRLF Injection, HTTP Parameter Pollution, User-Agent, IP Bypass, HTTP Request Smuggling, Web Cache Poisoning, UTF8/Unicode Bypass, WAF Inspection Limit Bypass (Padding).

### WAF Detection
- Auto-detect WAF type before testing (Cloudflare, AWS WAF, OWASP Coraza, BunkerWeb, ModSecurity, Akamai, Imperva, F5 BIG-IP, etc.).
- Suggests specific bypass techniques based on detected WAF.
- Can auto-switch to WAF-specific advanced payloads.

### Advanced Payloads & Encoding
- WAF Bypass Payloads — double encoding, unicode, mixed case, comment injection, polyglot payloads.
- Enhanced Payloads — modern evasion techniques.
- Encoding Variations — URL, Unicode, HTML Entity, Hex, Octal, Base64 encoding with automatic combinations.
- WAF-specific bypasses for Cloudflare, AWS WAF, ModSecurity.

### HTTP Protocol Manipulation
- HTTP Verb Tampering — test uncommon HTTP methods.
- Parameter Pollution — duplicate and split parameters across query/body.
- Content-Type Confusion — alternate content types to bypass rules.
- Request Smuggling headers.
- Host Header Injection variations.
- HTTP Method Override via headers (`X-HTTP-Method-Override`, etc.).

### Batch Testing
- Test multiple URLs at once.
- Configurable concurrency and delay between requests.
- Real-time progress tracking.

### 🔀 Regression Diffing (`--compare` / `--fail-on-regression`)
- Diff a scan against a previously saved JSON report to surface **new bypasses** (previously blocked, now not), **newly blocked** payloads, and added/removed tests.
- CI gate (`--fail-on-regression`) that fails only on *worsening* WAF posture, not on the full result list — ideal for catching managed-ruleset drift.

---

## Project Structure

The project is structured as an NPM Workspaces monorepo:

- [**`packages/core/`**](file:///Users/alex/src/waf-checker/packages/core): The core security testing library, payloads definition, WAF fingerprinting signatures, and obfuscation encoders.
- [**`packages/worker/`**](file:///Users/alex/src/waf-checker/packages/worker): Cloudflare Worker package serving the static HTML/JS Web UI and JSON API endpoints.
- [**`packages/cli/`**](file:///Users/alex/src/waf-checker/packages/cli): Node.js command-line interface tool for executing audits directly from your terminal.

---

## Installation & Building

From the root directory, install dependencies and build all workspaces:

```bash
npm install
npm run build
```

---

## How to Run

### 1. Web Version (Cloudflare Worker)

To run the Worker dev server locally (requires Wrangler):

```bash
npm run dev:worker
```

The Web UI will be accessible at `http://localhost:8787` (or another port if 8787 is occupied).

To deploy the Worker to Cloudflare:
```bash
npx wrangler deploy --workspace=packages/worker
```

The Worker needs the **Workers Paid** plan: scan and audit pages are sized for its 10,000 subrequests per request (`[limits] subrequests` in `wrangler.toml`, `WORKER_SUBREQUEST_LIMIT` in `packages/core/src/check.ts`). The Free plan allows only 50 external subrequests per request: one scan page with the User-Agent bypass test (on by default in the UI) or with redirects followed goes past that.

### 2. CLI Version (Node.js)

#### Install it as a global `waf-checker` command (recommended)

After `npm install && npm run build` at the repo root, link the CLI so it runs
from **any directory** — no `cd` into the repo and no long `node .../dist` paths:

```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
```

The published package bundles its code, so you can also install a packed build
globally without the repo: `npm pack --workspace @waf-checker/cli` then
`npm i -g ./waf-checker-cli-*.tgz`.

#### Shell completion (bash / zsh / fish)

`waf-checker completion <shell>` prints a completion script (omit `<shell>` to
auto-detect from `$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
```

#### Running without a global install

You can always invoke the built entrypoint directly:

```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 Detection
Detect the WAF vendor behind a target URL:
```bash
node packages/cli/dist/index.js detect <url>
```

#### Vulnerability payload audit
Run an audit against a target 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
```

#### Batch Audits
Run batch audits for a list of URLs defined in a file:
```bash
node packages/cli/dist/index.js batch targets.txt --concurrency 3
```

#### Generating Reports
Save audit results in **SARIF**, **JUnit XML**, **HTML**, **Markdown**, **CSV**, or **JSON** format:
```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
```
> The report format is deduced from the output file extension, or set explicitly with `-f, --format` (`json`, `csv`, `html`, `sarif`, `markdown`, `junit`). Each attack payload becomes a JUnit `<testcase>`; WAF bypasses are reported as `failure`s and transport/server errors as `error`s, so CI runners surface them directly.

#### CI/CD Integration & Protection Thresholds
Fail CI/CD pipelines when protection rate is below required threshold or when bypasses are detected:
```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
```

#### 🔀 Regression Diffing (Scan vs Scan)
WAF posture drifts over time — a vendor ships a managed-ruleset update, a CRS rule gets disabled, an origin change shifts a verdict. Instead of re-triaging the full result list every run, compare against a previously saved JSON report and gate CI on *worsening* only. A payload that was `blocked` in the baseline report and is no longer blocked counts as a regression; a payload newly blocked counts as an improvement. Matching is by `(category, method, evasion technique, payload)`, and network errors / origin-side blocks are treated as inconclusive so they never show up as false regressions.

```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
```

#### 🛡️ Virtual Patching & Auto-Remediation
Automatically generate ready-to-deploy firewall rules across all 11 supported platforms (`cloudflare`, `aws`, `gcp`, `azure`, `modsecurity`, `nginx`, `haproxy`, `caddy`, `apache`, `envoy`, `k8s`, or `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/
```

#### 🐳 Local Docker & Staging Environment Testing (`--allow-local`)
By default, `waf-checker` strictly blocks private IP ranges (`127.0.0.1`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) to prevent Server-Side Request Forgery (SSRF). When testing your own local Docker containers or staging servers, use `--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
```

#### 🧪 Automated Live Docker E2E Suite (`npm run test:e2e`)
Run end-to-end integration audits against live Docker containers (ModSecurity CRS, Caddy, HAProxy, NGINX, and Backend) in one command:
```bash
npm run test:e2e
```
See the complete [Local WAF Testing & E2E Validation Guide](https://github.com/sech0us3/waf-checker/blob/main/docs/LOCAL_WAF_TESTING.md) for full benchmarks, architecture diagrams, and manual reproduction steps.

---

## 🚀 GitHub Action (CI/CD)

Integrate automated WAF security testing into your GitHub Actions workflow:

```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 Version

You can run the CLI using Docker, either by pulling the pre-built image from GitHub Container Registry or by building it locally.

#### Using Pre-built Image (Recommended)

The pre-built Docker image is available on [GitHub Container Registry](https://github.com/SecH0us3/waf-checker/pkgs/container/waf-checker-cli) at `ghcr.io/sech0us3/waf-checker-cli`.

##### Pull the image
```bash
docker pull ghcr.io/sech0us3/waf-checker-cli:latest
```

##### Print help
```bash
docker run --rm ghcr.io/sech0us3/waf-checker-cli:latest --help
```

##### Run a check
```bash
docker run --rm -it ghcr.io/sech0us3/waf-checker-cli:latest check https://example.com
```

##### Run batch audits (mounting a local directory)
```bash
docker run --rm -it -v "$(pwd):/data" ghcr.io/sech0us3/waf-checker-cli:latest batch /data/targets.txt --concurrency 3
```

#### Building Locally

##### Build the image
```bash
docker build -t waf-checker-cli .
```

##### Print help
```bash
docker run --rm waf-checker-cli --help
```

##### Run a check
```bash
docker run --rm -it waf-checker-cli check https://example.com
```

##### Run batch audits (mounting a local directory)
```bash
docker run --rm -it -v "$(pwd):/data" waf-checker-cli batch /data/targets.txt --concurrency 3
```

---

## 🔌 API & Integration (for External Consumers & Fuzzers)

The Cloudflare Worker exposes a public REST API consumed by scanners and fuzzers (including [swazz](https://github.com/SecH0us3/swazz)). Full OpenAPI 3.1 specification is available in [`docs/openapi.yaml`](https://github.com/sech0us3/waf-checker/blob/main/docs/openapi.yaml).

### Endpoints Overview

| Endpoint | Method | Description |
|---|---|---|
| `/api/waf-detect` | `GET` | Fingerprints WAF vendor, confidence score, and suggested bypasses. |
| `/api/check` | `GET`, `POST` | Probes target with attack payloads. Supports pagination & category filtering. |
| `/api/virtual-patch` | `POST` | Generates remediation rules for Cloudflare, AWS, ModSec, NGINX, Caddy, HAProxy, Coraza. |
| `/api/reverse-engineer` | `GET`, `POST` | Reverse engineers OWASP CRS rules, anomaly thresholds, and body limits. |
| `/api/audit` | `GET`, `POST` | **Unified audit**: executes detection, security checks, and virtual patches, usually in one request (see Audit Paging). |

### Key Integration Features

- **Pagination Envelope (`?envelope=1` or `?envelope=true`)**:
  Wrap results in a structured envelope with pagination metadata:
  ```json
  {
    "results": [...],
    "page": 0,
    "pageSize": 50,
    "total": 72,
    "hasMore": true
  }
  ```
  *(Omit `?envelope=1` to receive the default bare JSON array for backwards compatibility).*

- **Audit Paging (`/api/audit`)**:
  An audit returns everything in one response (`hasMore: false`) unless its plan exceeds what one Cloudflare Worker request's subrequest budget allows (1658 items). That covers no detected WAF (513 items) and every WAF's bypass variations up to Sophos (1321); a Qrator-protected target (2441 items) comes back over two pages, as does any audit where you pass a smaller `pageSize`. Responses carry `page`, `pageSize`, `total`, `hasMore` and `detectedWAF` (`""` if none was found). While `hasMore` is true, request `page=<page + 1>&detectedWAF=<detectedWAF>`; passing `detectedWAF` back skips re-detection (`detection` is then `null`) and keeps page boundaries stable. `patches` covers that response's results; for one bundle over several pages, `POST` the combined `results` to `/api/virtual-patch`.

- **Normalized Confidence (`/api/waf-detect`)**:
  Provides `confidencePercent` (0–100) alongside raw `confidence` and `confidenceThreshold` (`40`).

- **Per-Result Verdict & Block Flags**:
  Every `AuditResultItem` includes:
  - `blocked: boolean` — Whether the WAF intervened before reaching the origin.
  - `verdict: 'blocked' | 'passed' | 'exposed'` — Distinct outcome differentiating between leaks (`exposed`) and coverage gaps (`passed`).
  - `error: string | null` — Explicit error category on network drop (e.g. `'timeout'`, `'dns'`, `'connection_reset'`).

- **Self-Scan Refusal (HTTP 422)**:
  Refuses accidental self-scans targeting the service infrastructure with `{ "error": "self-scan refused", "code": "SELF_SCAN_REFUSED" }`.

---

## Testing

To run the workspace-wide test suite (utilizing Vitest):

```bash
npm test
```

---

Read my blog at [yoursec.substack.com](https://yoursec.substack.com/)