@waftester/cli

The most comprehensive WAF testing CLI & MCP server. Detect, fingerprint, and bypass Web Application Firewalls with 2,800+ payloads, 96 tamper scripts, and quantitative security metrics (FPR, F1, MCC).

Why WAFtester?

| Traditional Approach | WAFtester | |---------------------|-----------| | Chain 5+ tools (wafw00f, sqlmap, nuclei, scripts) | Single auto command — end-to-end | | Manually select tampers per WAF vendor | Auto-selects from 96 tampers based on detected WAF | | Binary pass/fail results | Statistical metrics: FPR, Precision, F1 Score, MCC | | HTTP only | Native GraphQL, gRPC, SOAP, WebSocket support | | Manual result correlation | Unified JSON, SARIF, HTML, JUnit, CycloneDX output |

Quick Start

# Run without installing — downloads correct binary for your platform
npx -y @waftester/cli scan -u https://example.com

# Or install globally
npm install -g @waftester/cli
waf-tester scan -u https://example.com

What You Can Do

Full Automated Assessment

waf-tester auto -u https://target.com --smart

Executes the complete lifecycle: endpoint discovery → WAF fingerprinting → optimal tamper selection → 2,800+ payload testing → quantitative report generation.

WAF Detection & Fingerprinting

Identify WAF vendors with 198 vendor signatures:

$ waf-tester vendor -u https://protected.example.com

  Vendor         Cloudflare
  Confidence     98%
  Evidence       cf-ray header, __cfduid cookie, 1020 error page

Recommended tampers: charunicodeencode, space2morecomment, randomcase

Covers Cloudflare, AWS WAF, Akamai, Imperva, Azure WAF, F5, ModSecurity, Fortinet, Barracuda, Sucuri, Radware, Citrix ADC, Palo Alto, Sophos, Wallarm, and more.

Bypass Discovery

$ waf-tester bypass -u https://target.com --smart --tamper-auto

  Payload Variants Tested     2,847
  Blocked by WAF              2,728 (95.8%)
  Bypassed WAF                119 (4.2%)

Top Bypass Chains:
  1. charunicodeencode + space2morecomment    (42 bypasses)
  2. modsecurityversioned + randomcase        (31 bypasses)
  3. between + equaltolike                    (19 bypasses)

The mutation engine combines 49 mutator functions with base payloads for comprehensive encoding, evasion, and injection variation coverage.

Automate bypass chain discovery by testing tamper combinations against WAF rules:

# Automated bypass discovery — tests tamper combinations systematically
waf-tester bypass -u https://target.com --discover

# Write custom tamper scripts in Tengo and load from a directory
waf-tester scan -u https://target.com --tamper-dir ./my-tampers

Enterprise Assessment with Metrics

$ waf-tester assess -u https://target.com -fp -o assessment.json

  Detection Rate (TPR)    94.2%
  False Positive Rate      0.3%
  Precision               99.7%
  Recall                  94.2%
  F1 Score                0.969
  MCC                     0.942

Includes benign traffic corpus testing (Leipzig integration) for false positive measurement.

Service Presets

Use service presets for platform-specific testing. Presets add known endpoints and attack surface hints to improve discovery coverage.

# Test an Authentik identity provider
waf-tester auto -u https://sso.example.com -service authentik

# Test an n8n automation instance
waf-tester discover -u https://automation.example.com -service n8n

# Custom presets — drop JSON files in presets/ directory
WAF_TESTER_PRESET_DIR=./my-presets waf-tester auto -u https://target.com -service myapp

Built-in presets: authentik, gitlab, grafana, immich, intranet, jenkins, jira, keycloak, n8n, nextcloud, sonarqube, webapp, wordpress. Create custom presets by adding JSON files — see the Examples Guide.

Targeted Scanning

# SQL injection and XSS
waf-tester scan -u https://target.com -types sqli,xss

# All 50+ attack categories
waf-tester scan -u https://target.com -types all

# Multi-protocol
waf-tester scan -u https://api.example.com/graphql -types graphql
waf-tester scan -u grpc://service:50051 -types grpc
waf-tester scan -u wss://api.example.com/socket -types websocket

Browser & SPA Testing

# DOM event crawling — discovers hidden UI states in single-page apps
waf-tester headless -u https://spa.example.com --event-crawl

# Browser-based scanning for JavaScript-rendered targets
waf-tester headless -u https://app.example.com --smart

MCP Server (AI Integration)

WAFtester includes a built-in Model Context Protocol server with 27 tools, 7 guided prompts, and 12 resources for AI-powered security testing from Claude Desktop, VS Code, Cursor, and other MCP clients.

Claude Desktop

Add to claude_desktop_config.json:

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

VS Code

Add to .vscode/mcp.json in your workspace:

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

Cursor

Add to Cursor MCP settings:

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

API Spec Scanning

Scan OpenAPI, Swagger, Postman, HAR, AsyncAPI, gRPC, and GraphQL endpoints with one command:

# OpenAPI / Swagger spec (auto-detected)
waf-tester scan --spec openapi.yaml -u https://api.example.com

# Postman Collection with environment variables
waf-tester scan --spec collection.postman_collection.json --env staging.postman_environment.json

# HAR recording from browser DevTools
waf-tester scan --spec recording.har -u https://api.example.com

# Preview endpoints without scanning
waf-tester scan --spec openapi.yaml -u https://api.example.com --dry-run

Output Formats

| Format | Use Case | Flag | |--------|----------|------| | JSON | Automation, APIs | -format json | | JSONL | Streaming, real-time | -stream -json | | SARIF | GitHub/GitLab Security, VS Code | -format sarif | | HTML | Stakeholder reports | -format html | | PDF | Executive reports with severity matrix | -format pdf | | Markdown | Documentation, wikis | -format md | | CSV | Spreadsheets, data analysis | -format csv | | JUnit | CI/CD test frameworks | -junit-export results.xml | | XML | Legacy integrations | -xml-export results.xml | | CycloneDX | SBOM vulnerability exchange | -cyclonedx-export results.json | | SonarQube | SonarQube import | -sonarqube-export results.json | | GitLab SAST | GitLab security dashboard | -gitlab-sast-export results.json | | Console | Terminal display (default) | -format console |

CI/CD Integration

GitHub Actions (Recommended)

Use the official WAFtester Action for zero-install CI/CD:

- uses: waftester/waftester-action@v1
  with:
    target: ${{ env.TARGET_URL }}
    scan-type: scan
    format: sarif

Alternative: npx in GitHub Actions

- name: WAF Security Assessment
  run: |
    npx -y @waftester/cli scan -u ${{ env.TARGET_URL }} \
      -format sarif -o results.sarif

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

Also integrates with SonarQube, GitLab SAST, DefectDojo, Elasticsearch, Slack, Teams, PagerDuty, Jira, Azure DevOps, and OpenTelemetry.

All 36 Commands

| Command | Description | |---------|-------------| | auto | Full automated assessment (discovery → detection → testing → report) | | scan | Targeted vulnerability scanning across 50+ categories | | vendor | WAF vendor detection and fingerprinting (198 signatures) | | probe | WAF detection + protocol info in one pass | | bypass | Bypass discovery with tamper chain optimization | | assess | Enterprise assessment with statistical metrics | | tampers | List and rank tamper scripts by WAF vendor effectiveness | | discover | Full discovery (crawl + JS + sitemap + Wayback + event crawl) | | fuzz | Smart fuzzing with parameter-aware mutation | | mutate | Mutation matrix testing (49 mutator functions) | | headless | Browser-based testing for JS-rendered targets | | template | Run Nuclei-compatible YAML templates (HTTP, DNS, TCP, UDP) | | grpc | Test gRPC services via reflection | | soap | Test SOAP/WSDL endpoints | | mcp | Start MCP server for AI-powered testing | | cicd | Generate CI/CD pipeline configs | | crawl | Spider target for endpoint and parameter discovery | | analyze | JavaScript analysis for endpoints and secrets | | cloud | Cloud resource discovery | | report | Generate reports from saved results | | run | Execute specific payload categories against target | | race | Race condition testing | | smuggle | HTTP request smuggling tests | | learn | Analyze target and generate test plans | | fp | False positive testing with benign traffic corpus | | protocol | Protocol detection and fingerprinting | | validate | Payload and spec validation | | workflow | YAML workflow orchestration | | plugin | Plugin management | | compare | Compare two scan result JSON files (severity deltas, risk scores, CI exit code) | | update | Check for and install updates | | docs | Built-in command reference | | validate-templates | Validate Nuclei/custom scan templates |

Platform Support

| Platform | Architecture | Package | |---|---|---| | macOS | x64 (Intel) | @waftester/darwin-x64 | | macOS | arm64 (Apple Silicon) | @waftester/darwin-arm64 | | Linux | x64 | @waftester/linux-x64 | | Linux | arm64 | @waftester/linux-arm64 | | Windows | x64 | @waftester/win32-x64 | | Windows | arm64 | @waftester/win32-arm64 |

ARM64 platforms with x64 emulation (Rosetta 2, Windows WoW) are supported as fallback.

Environment Variables

| Variable | Description | |---|---| | WAF_TESTER_BINARY_PATH | Override binary path (skip platform resolution) | | WAF_TESTER_PAYLOAD_DIR | Override bundled payload directory | | WAF_TESTER_PRESET_DIR | Override bundled service preset directory | | WAF_TESTER_TEMPLATE_DIR | Override bundled template directory |

License

Business Source License 1.1 — converts to open source after the change date. See LICENSE for full terms.

Community payloads are licensed under MIT.

Links

• Website
• Documentation
• Command Reference
• Cheat Sheet
• GitHub
• Examples
• Installation Guide
• Changelog
• Issues