Documentation

WAFtester is a command-line tool that tests whether your Web Application Firewall (WAF) actually blocks attacks. You point it at your website, it sends thousands of simulated attack payloads, and it tells you which ones got through.

If you are a developer, security engineer, DevOps engineer, or anyone responsible for a website’s security — this tool shows you where your defenses have gaps before an attacker finds them.

What Is a WAF and Why Test It?

A Web Application Firewall (WAF) sits between the internet and your website. It inspects incoming HTTP requests and blocks ones that look like attacks — SQL injection, cross-site scripting (XSS), path traversal, and dozens of other attack types.

Popular WAFs include AWS WAF, Cloudflare, Akamai, Imperva, Azure Front Door, and ModSecurity. If your website is behind any of these, you have a WAF.

The problem: WAFs ship with default rules that don’t cover everything. Rules get misconfigured. New endpoints get added without WAF rules. Attackers find creative ways around existing rules.

What WAFtester does:

• Sends 3,700+ real-world attack payloads across 50+ attack categories
• Tests whether your WAF blocks each one or lets it through
• Finds bypasses — payloads that evade your WAF rules using encoding, case changes, or structural tricks
• Measures your WAF’s detection rate with precision, recall, and F1 scores
• Generates reports in 16 formats for your team, your CI/CD pipeline, or your compliance auditor

Think of it as a fire drill for your WAF. You want to know it works before the real fire.

Quick Start

Go from zero to your first security scan in 60 seconds.

Step 1: Install WAFtester

The fastest way to install is with npm (Node Package Manager). npm comes bundled with Node.js — if you have Node.js installed, you already have npm.

npm install -g @waftester/cli

Don’t have Node.js? Download it from nodejs.org (choose the LTS version). After installing, open a new terminal and the npm command will be available. Alternatively, see the Installation section for Docker, Homebrew, and direct binary options that don’t require Node.js.

Step 2: Run your first scan

waf-tester scan -u https://your-app.com --smart

Replace https://your-app.com with your actual website URL. The --smart flag tells WAFtester to auto-detect your WAF vendor and tailor its payloads accordingly — it’s the recommended way to scan.

Step 3: Read the results

WAFtester prints results as it finds them. Here’s what the output means:

[bypass]  SQLi  |  ' OR 1=1--  |  POST /api/login  →  200 OK

• bypass — this payload got past your WAF (this is what you need to fix)
• SQLi — the attack category (SQL Injection in this case)
• ’ OR 1=1— — the exact payload that bypassed the WAF
• POST /api/login — the endpoint and HTTP method
• 200 OK — the server responded normally instead of blocking

At the end of the scan, you get a summary:

Payloads sent:    1,247
Blocked by WAF:   1,198 (96.1%)
Bypasses found:      49 (3.9%)
Critical:             3

A “critical” bypass means a high-severity attack payload reached your application. These need immediate attention.

Step 4: Generate a report

Add -o report.html to save an interactive HTML report you can share with your team:

waf-tester scan -u https://your-app.com --smart -o report.html

Open report.html in your browser to see every finding with evidence, severity, and remediation guidance.

The “do everything” command

If you want WAFtester to run a full assessment automatically — detect the WAF, scan for bypasses, test false positives, and generate a report — use auto:

waf-tester auto -u https://your-app.com -o report.html

This is the best starting point for a complete picture of your WAF’s effectiveness.

Want every command at a glance? See the Cheat Sheet — copy-paste commands for every use case.

Installation

WAFtester is a single binary with zero runtime dependencies. Choose the installation method that fits your setup.

npm (recommended for most users)

What this is: npm is the package manager that comes with Node.js. This method works on Windows, macOS, and Linux, and handles updates automatically.

Requirements: Node.js 18 or later (download).

npm install -g @waftester/cli

After installation, the waftester command is available globally. To update later:

npm update -g @waftester/cli

Don’t want to install permanently? Use npx to run WAFtester without installing it. npx downloads it temporarily, runs the command, and cleans up:

npx -y @waftester/cli scan -u https://your-app.com --smart

Homebrew (macOS and Linux)

What this is: Homebrew is a popular package manager for macOS (and Linux). If you use brew to install other tools, this is the natural choice.

brew install waftester/tap/waftester

To update:

brew upgrade waftester

Scoop (Windows)

What this is: Scoop is a command-line installer for Windows. If you prefer Scoop over npm, this works the same way.

scoop bucket add waftester https://github.com/waftester/scoop-waftester
scoop install waftester

AUR (Arch Linux)

What this is: The Arch User Repository hosts community packages for Arch Linux.

yay -S waftester-bin

Docker (no installation required)

What this is: Docker runs WAFtester inside a container. Nothing gets installed on your system. This is ideal for CI/CD pipelines, one-off scans, or if you don’t want to install anything.

Requirements: Docker installed and running (download).

# From Docker Hub
docker run --rm qandil/waftester scan -u https://your-app.com --smart

# From GitHub Container Registry
docker run --rm ghcr.io/waftester/waftester scan -u https://your-app.com --smart

Both registries have the same image. The --rm flag removes the container after the scan finishes.

To save a report from Docker:

docker run --rm -v $(pwd):/output qandil/waftester scan -u https://your-app.com --smart -o /output/report.html

This mounts your current directory into the container so the report file appears on your machine.

Binary download (any platform)

What this is: Pre-compiled executables you download directly. No package manager needed. Available for Linux (amd64, arm64), macOS (amd64, arm64), and Windows (amd64).

Download from GitHub Releases, or use the command line:

# Linux (auto-detects architecture)
curl -sSL https://github.com/waftester/waftester/releases/latest/download/waftester_linux_$(uname -m | sed s/aarch64/arm64/).tar.gz | tar xz
sudo mv waftester /usr/local/bin/

# macOS
curl -sSL https://github.com/waftester/waftester/releases/latest/download/waftester_darwin_$(uname -m).tar.gz | tar xz
sudo mv waftester /usr/local/bin/

Verify installation

After installing with any method, verify it works:

waf-tester version

You should see the version number, build date, and Go version. If you get “command not found”, restart your terminal or check that the installation directory is in your system’s PATH.

Core Commands

WAFtester has 33 commands. You don’t need to learn all of them — most users start with auto or scan and explore from there. Commands are grouped by what they do.

The essentials (start here)

auto — Full automated assessment. This is the “I don’t want to think about it” command. It detects your WAF, scans for vulnerabilities, tests bypasses, checks for false positives, and generates a report. One command, complete results.

waf-tester auto -u https://your-app.com --smart -o report.html

scan — Targeted vulnerability scanning. Use this when you want to test specific attack types or have more control than auto gives you.

# Scan for everything
waf-tester scan -u https://your-app.com --smart

# Scan only for SQL injection and XSS
waf-tester scan -u https://your-app.com -types sqli,xss

# Scan multiple targets from a file (one URL per line)
waf-tester scan -l targets.txt --smart

vendor — Identify which WAF is protecting a website. Checks against 198+ WAF signatures and tells you the vendor, version, and known bypass techniques in under 15 seconds.

waf-tester vendor -u https://your-app.com

WAF bypass and evasion

These commands help you find ways around your WAF rules — the same techniques attackers use.

bypass — Automated bypass discovery. WAFtester tries 65+ evasion techniques (encoding tricks, case manipulation, comment injection, etc.) to find payloads your WAF misses.

# Let WAFtester auto-select the best tamper scripts for your WAF
waf-tester bypass -u https://your-app.com --smart --tamper-auto

mutate — Mutation engine. Takes a single payload and generates up to 2,340 variants by combining 18 encoders, 13 injection locations, and 10 evasion techniques. This is how you find the one encoding trick your WAF rule pattern didn’t account for.

waf-tester mutate -u https://your-app.com -mode full -chain

fuzz — Content fuzzing with wordlists. Works like ffuf — the FUZZ keyword gets replaced with each word from the wordlist.

waf-tester fuzz -u https://your-app.com/FUZZ -w wordlist.txt -mc 200,301

See the Penetration Testing use case for full bypass workflows, or the cheat sheet for quick commands.

Assessment and benchmarking

assess — Enterprise-grade WAF assessment. Measures your WAF’s effectiveness with statistical scoring: precision (how many blocks were correct), recall (how many attacks were caught), and F1 score (overall accuracy). This is what compliance auditors and security teams need.

# Full assessment with false positive testing
waf-tester assess -u https://your-app.com -fp -corpus builtin,leipzig

fp — False positive testing. Sends legitimate (non-malicious) traffic to check if your WAF blocks real users by mistake. A WAF that blocks attacks but also blocks legitimate requests is misconfigured.

waftester fp -u https://your-app.com

See the Compliance & Benchmarking use case for scoring workflows and audit reports.

API and protocol testing

These commands test non-standard protocols that generic scanners miss. See the API Security use case for detailed examples.

openapi — Test every endpoint defined in your OpenAPI/Swagger specification. WAFtester reads the spec, understands parameter types, and generates schema-aware payloads.

# From a local spec file
waftester openapi -spec openapi.yaml --fuzz -u https://api.example.com

# From a remote URL
waftester openapi --spec-url https://api.example.com/openapi.json --fuzz

grpc — Test gRPC services via reflection. No .proto files needed — WAFtester discovers services and methods automatically.

waftester grpc -u api.example.com:443 --fuzz --category sqli

soap — Test SOAP/WSDL web services. WAFtester parses the WSDL, discovers operations, and generates XML-aware injection payloads.

waftester soap --wsdl https://example.com/service?wsdl --fuzz

Discovery and reconnaissance

discover — Find all endpoints on a website by crawling pages, parsing JavaScript, checking robots.txt, sitemaps, and the Wayback Machine.

waf-tester discover -u https://your-app.com

analyze — JavaScript analysis. Finds API endpoints, secrets, and DOM XSS sinks in JavaScript files.

waftester analyze -u https://your-app.com

probe — Protocol and infrastructure probing. Detects WAF vendor, HTTP version, TLS configuration, security headers, and technology stack in one pass.

waf-tester probe -u https://your-app.com

crawl — Advanced web crawler with JavaScript rendering, scope control, and authentication support.

waftester crawl -u https://your-app.com --depth 3

Intelligent workflows

WAFtester can learn about your target and create a custom test plan instead of using generic scans.

learn — Analyze discovery results and generate a targeted test plan based on the technologies, endpoints, and parameters found.

# Step 1: Discover endpoints
waf-tester discover -u https://your-app.com

# Step 2: Generate a test plan from what was found
waf-tester learn -discovery discovery.json

# Step 3: Execute the plan
waf-tester run -plan testplan.json

workflow — Multi-step workflow orchestration. Chain commands together in a repeatable YAML workflow.

template — Run Nuclei-compatible YAML templates. If you already have Nuclei templates, WAFtester can run them directly.

waftester template -u https://your-app.com -t templates/

Utilities

cicd — Generate CI/CD pipeline configuration files for 6 platforms (GitHub Actions, GitLab CI, Jenkins, Azure DevOps, CircleCI, Bitbucket Pipelines).

waf-tester cicd -p github-actions -u '${{ secrets.WAF_TARGET_URL }}'

cloud — Discover cloud resources (S3 buckets, Azure blobs, GCP storage) associated with a domain.

waftester cloud -d example.com

report — Generate enterprise HTML reports from saved scan results.

mcp — Start the MCP server for AI agent integration (see MCP Server section).

update — Download the latest attack payloads from OWASP and community sources.

validate — Check custom payload files for schema errors before using them in scans.

Complete command reference: See the Cheat Sheet for copy-paste one-liners for every command.

Output Formats

WAFtester can export results in 16 formats. The format is auto-detected from the file extension — no extra flags needed.

Reports for humans

These formats are designed for people to read and share.

Reports for CI/CD pipelines

These formats plug directly into security dashboards in your CI/CD platform. See CI/CD Integration for full setup guides.

Reports for security tools

These formats integrate with vulnerability management platforms and security infrastructure.

Multiple formats in one scan

You can output multiple formats simultaneously. WAFtester runs the scan once and writes all formats:

waf-tester scan -u https://your-app.com --smart \
  -o report.html \
  -o results.sarif \
  -o data.json

This gives you an HTML report for your team, SARIF for GitHub, and JSON for your automation scripts — from a single scan.

Real-time notifications

In addition to file outputs, WAFtester can send findings to messaging and monitoring platforms as the scan runs:

CI/CD Integration

What is CI/CD?

CI/CD stands for Continuous Integration / Continuous Deployment. It’s the system that automatically builds, tests, and deploys your code when you push changes. Popular CI/CD platforms include GitHub Actions, GitLab CI, Jenkins, and Azure DevOps.

Why automate WAF testing?

WAF rules change. New API endpoints get deployed. Developers add features that the WAF team doesn’t know about. If you only test your WAF manually once a quarter, you have three months of potential gaps.

Automating WAF tests in your CI/CD pipeline means:

• Every code push is tested for WAF coverage
• WAF rule changes are validated before going live
• New endpoints are automatically checked for missing protection
• Results appear in the same dashboards your team already uses (GitHub Security, GitLab SAST, SonarQube)
• Builds can fail if critical bypasses are detected, preventing insecure deployments

Generate your pipeline config automatically

WAFtester can generate CI/CD configuration files for your platform:

# GitHub Actions
waf-tester cicd -p github-actions -u '${{ secrets.WAF_TARGET_URL }}'

# GitLab CI
waf-tester cicd -p gitlab-ci -u '$WAF_TARGET_URL'

# Jenkins
waf-tester cicd -p jenkins -u '$WAF_TARGET_URL'

# Azure DevOps
waf-tester cicd -p azure-devops -u '$(WAF_TARGET_URL)'

Or set it up manually:

GitHub Actions

This workflow runs WAFtester on every push and pull request. Results appear in GitHub’s Security tab under “Code Scanning.”

name: WAF Security Test
on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: '0 6 * * 1'  # Also run weekly on Monday mornings

jobs:
  waf-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run WAFtester
        uses: waftester/waftester-action@v1
        with:
          target: ${{ secrets.WAF_TARGET_URL }}
          mode: scan
          args: --smart -o results.sarif -o results.json

      - name: Upload to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

      - name: Archive full results
        uses: actions/upload-artifact@v4
        with:
          name: waf-results
          path: results.json

Where to set the secret: Go to your repo Settings > Secrets and variables > Actions > New repository secret. Name it WAF_TARGET_URL and set it to your website URL (e.g., https://your-app.com).

What happens: After the workflow runs, go to the Security tab in your GitHub repo. You’ll see WAFtester findings alongside your other security alerts.

GitLab CI

Results appear in GitLab’s Security Dashboard and on merge request widgets.

waf-test:
  image: ghcr.io/waftester/waftester:latest
  stage: test
  script:
    - waf-tester scan -u $WAF_TARGET_URL --smart -o gl-sast.json
  artifacts:
    reports:
      sast: gl-sast.json
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"

Where to set the variable: Go to Settings > CI/CD > Variables and add WAF_TARGET_URL.

Azure DevOps

- task: CmdLine@2
  displayName: WAF Security Test
  inputs:
    script: |
      npx -y @waftester/cli scan \
        -u $(WAF_TARGET_URL) \
        --smart \
        -o results.sarif \
        -o results.json

- task: PublishBuildArtifacts@1
  displayName: Publish WAF Results
  inputs:
    pathToPublish: results.sarif
    artifactName: waf-security-results

Where to set the variable: Go to Pipelines > Library > Variable groups or set it directly in the pipeline YAML.

Jenkins

pipeline {
    agent any
    stages {
        stage('WAF Security Test') {
            steps {
                sh 'npx -y @waftester/cli scan -u $WAF_TARGET_URL --smart -o results.junit.xml -o results.json'
            }
            post {
                always {
                    junit 'results.junit.xml'
                    archiveArtifacts artifacts: 'results.json'
                }
            }
        }
    }
}

Docker-only CI (no install step)

If your CI environment has Docker but not Node.js, run WAFtester directly from the container image:

docker run --rm \
  -v $(pwd)/results:/output \
  ghcr.io/waftester/waftester \
  scan -u https://your-app.com --smart \
  -o /output/results.sarif \
  -o /output/report.html

Detailed CI/CD walkthrough: See the CI/CD & DevSecOps use case page with full setup guides for each platform.

MCP Server (AI Integration)

What is MCP?

MCP stands for Model Context Protocol. It’s a standard created by Anthropic that lets AI assistants (like Claude, GitHub Copilot, or Cursor) use external tools. Instead of just chatting, an AI agent with MCP can actually run WAFtester on your behalf.

What this means in practice

With MCP configured, you can talk to your AI assistant in natural language and it will run real scans:

You: “Scan example.com for SQL injection bypasses”

AI: runs waf-tester scan -u example.com -types sqli --smart, reads the results, and explains what it found

No command memorization. No flag lookup. You describe what you want, the AI executes it and interprets the results for you.

Why use MCP instead of running commands yourself?

• Natural language — ask for what you want instead of remembering flag syntax
• Contextual analysis — the AI reads the full output in context: findings, evidence, severity, and can explain remediation steps
• Multi-step workflows — “detect the WAF, scan for bypasses, then generate a report” happens in one conversation
• 27 tools available — the AI can detect WAFs, scan, assess, bypass, discover, learn, probe, mutate, generate CI/CD configs, manage payloads, run API spec scans, manage tampers, and track long-running tasks
• 12 resources — the AI can browse payload inventories, WAF signatures, evasion techniques, template directories, OWASP mappings, and configuration options
• 7 guided prompts — pre-built workflows for common scenarios like full security audits, WAF bypass discovery, and API spec-driven testing

Setup

WAFtester’s MCP server works with any MCP-compatible AI client. Setup takes one configuration block.

Claude Desktop

Add this to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "waftester": {
      "command": "npx",
      "args": ["-y", "@waftester/cli", "mcp", "--stdio"]
    }
  }
}

VS Code (GitHub Copilot)

Add this to your VS Code settings (.vscode/settings.json or global settings):

{
  "mcp": {
    "servers": {
      "waftester": {
        "command": "npx",
        "args": ["-y", "@waftester/cli", "mcp", "--stdio"]
      }
    }
  }
}

Cursor

Add this to your Cursor MCP settings:

{
  "mcpServers": {
    "waftester": {
      "command": "npx",
      "args": ["-y", "@waftester/cli", "mcp", "--stdio"]
    }
  }
}

n8n (workflow automation)

n8n is a workflow automation platform. Connect WAFtester’s MCP server to run scheduled scans and send results to Slack, email, Jira, or any of n8n’s 400+ integrations.

Start the MCP server with HTTP/SSE transport (n8n connects over HTTP, not stdio):

# Start the MCP server on port 8080
waf-tester mcp --http :8080

Then in n8n, add an MCP Client node and point it to http://localhost:8080/sse.

For a persistent setup with Docker:

# docker-compose.yml
services:
  waftester-mcp:
    image: qandil/waftester:latest
    command: mcp --http :8080
    ports:
      - "8080:8080"
    restart: unless-stopped

What you can ask

Once configured, try these prompts with your AI assistant:

• “What WAF is protecting example.com?”
• “Run a full security assessment of my-app.com and explain the findings”
• “Scan my staging API for SQL injection and XSS bypasses”
• “Generate a SARIF report for my-app.com and explain what each finding means”
• “Set up a weekly WAF test in GitHub Actions”
• “How does my WAF compare across attack categories? Show me the weak spots”

Deep dive: See the AI & MCP Agents use case for full workflow examples, a list of all 27 MCP tools, and an n8n automation walkthrough.

Advanced Options

These flags work with most commands. They control how WAFtester sends requests, how fast it scans, and how it handles authentication.

Scan speed and stealth

Control how aggressively WAFtester scans. Slower scanning avoids triggering rate limits or being blocked by the WAF’s bot detection.

Example: Scan a production site gently:

waf-tester scan -u https://production-app.com --smart \
  -c 3 --delay 200 --rate-limit 5 --realistic

Smart mode levels

The --smart flag has five intensity levels. Each one trades speed for thoroughness.

Authentication

Most commands accept these flags for testing authenticated endpoints:

Example: Scan behind authentication with a proxy:

waf-tester scan -u https://app.com/api --smart \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -b "session=abc123" \
  --proxy http://127.0.0.1:8080

Payload control

Service presets

If you know the backend framework, presets optimize scanning for that technology:

waf-tester scan -u https://app.com --smart --preset wordpress

Available presets: wordpress, drupal, nextjs, flask, django, rails, laravel, spring

TLS and protocol

Troubleshooting

”command not found: waftester”

The waftester binary isn’t in your system’s PATH.

If you installed via npm:

1. Check that Node.js is installed: node --version
2. Check the npm global install directory: npm root -g
3. Make sure that directory’s bin folder is in your PATH
4. Try running with npx instead: npx -y @waftester/cli version

If you downloaded the binary:

1. Move it to a directory in your PATH: sudo mv waftester /usr/local/bin/
2. Make it executable: chmod +x /usr/local/bin/waftester

On Windows: Restart your terminal after installing. If using the binary download, add the folder to your PATH in System Properties > Environment Variables.

Connection refused or timeout

WAFtester can’t reach the target URL.

# First, verify you can reach the target yourself
curl -I https://your-app.com

# Run with --debug to see the full HTTP request and response
waf-tester scan -u https://your-app.com --debug

Common causes:

• The URL is behind a VPN and you’re not connected
• The server is firewalled and doesn’t accept connections from your IP
• DNS resolution is failing — try using the IP directly
• The server requires TLS client certificates

WAF is blocking WAFtester itself (403 on every request)

Some WAFs detect scanning tools by User-Agent or request patterns and block everything.

# Use realistic browser headers
waf-tester scan -u https://your-app.com --smart --realistic --random-agent

# Slow down to avoid rate-based detection
waf-tester scan -u https://your-app.com --smart \
  --realistic --random-agent --delay 500 -c 2

# Use stealth mode (combines all of the above automatically)
waf-tester scan -u https://your-app.com --smart-mode=stealth

Too many false positives (findings that aren’t real)

WAFtester might report bypasses that aren’t actually exploitable.

# Use --smart mode — it auto-calibrates against your target's normal responses
waf-tester scan -u https://your-app.com --smart

# Run the false positive checker on your results
waftester fp -u https://your-app.com

# Increase confidence with auto-calibration
waf-tester scan -u https://your-app.com --smart --auto-calibrate

Rate limiting (429 Too Many Requests)

Your target (or its WAF) is rate-limiting your scan.

# Reduce speed
waf-tester scan -u https://your-app.com --smart \
  -c 2 --rate-limit 5 --delay 200

# Or use stealth mode which handles this automatically
waf-tester scan -u https://your-app.com --smart-mode=stealth

WAF not detected (vendor command shows nothing)

Some WAFs don’t expose their identity easily.

# Try with debug output to see what detection methods were attempted
waf-tester vendor -u https://your-app.com --debug

# Skip vendor detection and scan anyway
waf-tester scan -u https://your-app.com --no-vendor-check

Note: Not detecting the WAF vendor doesn’t mean there’s no WAF. It may be configured to hide its identity. WAFtester’s scanning still works without vendor detection — it just can’t optimize payload selection for a specific WAF.

Scan takes too long

# Limit to specific attack categories
waf-tester scan -u https://your-app.com --smart -types sqli,xss

# Use quick mode for a fast validation
waf-tester scan -u https://your-app.com --smart-mode=quick

# Increase parallelism (only for non-production targets)
waf-tester scan -u https://your-app.com --smart -c 50

Docker permission issues

# If you get "permission denied" in Docker
docker run --rm --user $(id -u):$(id -g) \
  -v $(pwd):/output \
  qandil/waftester scan -u https://your-app.com -o /output/report.html

Still stuck?

• Check the Cheat Sheet for the exact command syntax you need
• Browse the examples guide for real-world scenarios
• Open an issue on GitHub — include the command you ran, the error output, and your WAFtester version (waf-tester version)