WAF Checker

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	93.0% 🟢	92.6%	96.4%	🟢 282 passing
@waf-checker/cli	93.5% 🟢	92.8%	96.7%	🟢 54 passing
@waf-checker/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 with (or forward-and-tag in simulate mode) for a route_configuration virtual_host. Supported via .

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/: The core security testing library, payloads definition, WAF fingerprinting signatures, and obfuscation encoders.
• packages/worker/: Cloudflare Worker package serving the static HTML/JS Web UI and JSON API endpoints.
• 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:

npm install
npm run build

---

How to Run

1. Web Version (Cloudflare Worker)

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

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:

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:

# 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
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:

# 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:

node packages/cli/dist/index.js detect <url>

Vulnerability payload audit

Run an audit against a target URL:

# 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:

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:

# 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 failures and transport/server errors as errors, 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:

# 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.

# 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):

# 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:

# 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:

npm run test:e2e

See the complete Local WAF Testing & E2E Validation Guide for full benchmarks, architecture diagrams, and manual reproduction steps.

---

🚀 GitHub Action (CI/CD)

Integrate automated WAF security testing into your GitHub Actions workflow:

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 at ghcr.io/sech0us3/waf-checker-cli.

Pull the image

docker pull ghcr.io/sech0us3/waf-checker-cli:latest

Print help

docker run --rm ghcr.io/sech0us3/waf-checker-cli:latest --help

Run a check

docker run --rm -it ghcr.io/sech0us3/waf-checker-cli:latest check https://example.com

Run batch audits (mounting a local directory)

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

docker build -t waf-checker-cli .

Print help

docker run --rm waf-checker-cli --help

Run a check

docker run --rm -it waf-checker-cli check https://example.com

Run batch audits (mounting a local directory)

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). Full OpenAPI 3.1 specification is available in 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:

  {
    "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):

npm test

---

Read my blog at yoursec.substack.com