Use Case: API Security

Your API Spec Is Your Attack Surface

Name: WAFtester
Author: WAFtester

Point WAFtester at any API spec — OpenAPI, Swagger, Postman, HAR, AsyncAPI, gRPC, or SOAP. It reads the schema, generates targeted payloads, and tests every parameter.

The Problem

📄

Specs Rot Silently

Your OpenAPI spec says 200 endpoints. Your WAF has rules for 50 of them. The other 150 are unprotected but nobody knows because nobody tested from the spec.

🔌

Multi-Format Blind Spots

Your team uses OpenAPI specs, QA exports Postman collections, and DevTools captures HAR files. No WAF scanner tests all of them. Until now.

🎯

Generic Payloads Miss Context

Scanners that ignore your schema send string payloads to integer fields and integer payloads to file uploads. Schema-aware fuzzing finds what generic scanning cannot.

Unified Spec Scanning (v2.9.0)

One command, any format. WAFtester auto-detects the spec type from file content — not the extension — and generates a targeted scan plan.

Unified Spec Scanning

$ waftester scan --spec openapi.yaml -u https://api.example.com

  ╔══════════════════════════════════════════════╗
  ║  API Spec Scanner                            ║
  ╚══════════════════════════════════════════════╝

  Spec:        openapi.yaml (OpenAPI 3.1)
  Base URL:    https://api.example.com
  Endpoints:   47 paths, 128 operations
  Parameters:  312 (query: 89, body: 186, header: 37)
  Intensity:   normal

  [scanning] POST /api/v1/users .................. 3 findings
  [scanning] GET  /api/v1/users/{id} ............. 1 finding
  [scanning] PUT  /api/v1/orders/{id}/status ..... 2 findings
  [scanning] POST /api/v1/search ................. 5 findings
  ...

  ┌──────────────────────────────────────────────┐
  │ Results                                      │
  ├──────────────────┬───────────────────────────┤
  │ Endpoints tested │ 128                       │
  │ Parameters fuzzed│ 312                       │
  │ Payloads sent    │ 4,680                     │
  │ WAF blocks       │ 4,231 (90.4%)             │
  │ Bypasses found   │ 449 (9.6%)                │
  │ Critical         │ 12                        │
  └──────────────────┴───────────────────────────┘

From a Local File

 $ waftester scan --spec openapi.yaml -u https://api.example.com

Works with .yaml, .json, .har — format auto-detected from content.

From a Remote URL

 $ waftester scan --spec-url https://api.example.com/openapi.json

Fetches spec directly. Target URL extracted from spec's servers block.

Dry-Run Preview

 $ waftester scan --spec api.yaml --dry-run

See the full scan plan before sending a single request.

Intensity Control

 $ waftester scan --spec api.yaml --intensity deep

quick | normal | deep | paranoid — more payloads per endpoint.

OpenAPI 3.x / Swagger 2.0

Feed your OpenAPI 3.x or Swagger 2.0 spec. WAFtester reads every path, parameter, and schema definition, then generates type-aware payloads for each endpoint.

OpenAPI / Swagger Examples

# OpenAPI 3.x from local file
$ waftester scan --spec openapi.yaml -u https://api.example.com

# Swagger 2.0 from URL (common for .NET APIs)
$ waftester scan --spec-url https://api.example.com/swagger/v1/swagger.json

# Target optional when spec has servers block
$ waftester scan --spec openapi.yaml

# Scan only auth-related endpoints
$ waftester scan --spec openapi.yaml -u https://api.example.com --group auth

# Deep intensity with severity filter
$ waftester scan --spec openapi.yaml -u https://api.example.com \
    --intensity deep -msev critical,high

# Filter to specific API version
$ waftester scan --spec swagger.json -u https://api.example.com \
    --path "/api/v2/*"

# Skip deprecated endpoints
$ waftester scan --spec swagger.json -u https://api.example.com \
    --skip-group deprecated

What WAFtester Does With Your Spec

Reads every path, method, parameter, and request body schema
Generates type-correct payloads (strings for strings, integers for integers, then injects attack payloads)
Respects required vs. optional parameters
Groups endpoints by tags for selective scanning with --group and --skip-group
Reports findings per-endpoint with exact parameter + payload that bypassed the WAF

Postman Collections (v2.9.0)

Export your Postman collection and scan every endpoint with schema-aware attacks. WAFtester handles variable substitution from environment files and CLI overrides.

Postman Collection Scanning

# Basic: collection file only (uses baseUrl from collection)
$ waftester scan --spec MyAPI.postman_collection.json

# With environment file for variable substitution
$ waftester scan --spec MyAPI.postman_collection.json \
    --env staging.postman_environment.json \
    -u https://staging-api.example.com

# Override specific variables
$ waftester scan --spec MyAPI.postman_collection.json \
    --env production.postman_environment.json \
    --var "api_key=test-key-123" \
    --var "base_url=https://api.example.com"

# Scan only the "Users" folder from the collection
$ waftester scan --spec MyAPI.postman_collection.json \
    --env staging.postman_environment.json \
    --group Users

Environment Files

--env loads .postman_environment.json

Variable Override

--var key=value (repeatable)

Folder Filtering

--group scans specific folders

How Postman Variables Work

Variables like {{base_url}} in the collection are resolved automatically from the environment file. Use --var to override any variable — it takes precedence over the environment file.

HAR Recordings (v2.9.0)

Record browser traffic with Chrome DevTools, export the HAR file, and scan every captured endpoint. No spec required — your real traffic is the spec.

HAR-Based Scanning

# Export HAR from Chrome DevTools > Network tab > Export HAR
# Then scan all captured endpoints
$ waftester scan --spec recording.har -u https://api.example.com

# Quick triage with fast intensity
$ waftester scan --spec recording.har -u https://api.example.com \
    --intensity quick

# Skip static assets (CSS, JS, images)
$ waftester scan --spec recording.har -u https://api.example.com \
    -ep "\.(css|js|png|jpg|woff)$"

No Spec? No Problem.

Record real traffic with DevTools, export HAR, and scan. Every request becomes a test target — including AJAX calls, API fetches, and WebSocket messages your spec might not document.

Response Capture

HAR files include full request/response pairs. WAFtester uses responses to calibrate baseline behavior and detect bypasses more accurately.

AsyncAPI (v2.9.0)

Test event-driven APIs defined with AsyncAPI 2.x specs. WAFtester reads channel definitions and generates payloads for message schemas, including WebSocket endpoints.

AsyncAPI Scanning

# AsyncAPI 2.x spec (YAML or JSON)
$ waftester scan --spec asyncapi.yaml -u https://api.example.com

# WebSocket channels from AsyncAPI
$ waftester scan --spec asyncapi.yaml -u wss://api.example.com/ws

Event-Driven Coverage

Tests publish/subscribe channels defined in your AsyncAPI spec. Each message schema is fuzzed with type-aware payloads.

WebSocket Native

AsyncAPI specs with WebSocket bindings are scanned over persistent WS connections, testing message injection across each channel.

gRPC

WAFtester connects via gRPC reflection, discovers all services and methods, and generates protobuf-aware payloads. No proto files needed.

gRPC Security Testing

$ waftester grpc -u api.example.com:443 --list

  Services:
    UserService      (4 methods)
    OrderService     (6 methods)
    PaymentService   (3 methods)

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

  [fuzzing] UserService.CreateUser ............... 2 findings
  [fuzzing] OrderService.SearchOrders ............ 4 findings
  [fuzzing] PaymentService.ProcessPayment ........ 0 findings

  Bypasses: 6 | Blocked: 342 | Coverage: 13 methods

Reflection API

No .proto files needed

Field-Aware

Payloads match protobuf types

TLS + mTLS

Client certs supported

SOAP / WSDL

Point at a WSDL URL. WAFtester parses the service definition, discovers all operations, and generates XML-aware injection payloads.

SOAP/WSDL Testing

$ waftester soap --wsdl https://legacy.example.com/service?wsdl --list

  Service: LegacyBillingService
  Port:    BillingPort (SOAP 1.1)
  Operations:
    CreateInvoice    (5 parameters)
    GetInvoice       (1 parameter)
    SearchCustomers  (3 parameters)
    ProcessPayment   (4 parameters)

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

  [fuzzing] CreateInvoice ........................ 3 findings
  [fuzzing] SearchCustomers ...................... 5 findings
  [fuzzing] ProcessPayment ....................... 1 finding

  XML injection:  4 bypasses
  XPath injection: 3 bypasses
  XXE attempts:    2 bypasses

GraphQL

WAFtester discovers GraphQL endpoints via introspection, maps the schema, and tests queries, mutations, and subscriptions for injection vulnerabilities.

GraphQL Testing

$ waftester discover -u https://target.com --graphql

  GraphQL endpoint: https://target.com/graphql
  Introspection:    enabled
  Types:            42 (12 queries, 8 mutations, 3 subscriptions)

$ waftester scan -u https://target.com/graphql -types graphql --smart

  [scanning] query { user(id: "...") }  ......... 2 findings
  [scanning] mutation { createPost(...) } ........ 3 findings
  [scanning] query { search(term: "...") } ....... 4 findings

  Injection via nested queries:   3 bypasses
  Batch query abuse:              2 bypasses
  Field suggestion leak:          1 finding

Introspection Discovery

Automatically maps queries, mutations, and subscriptions from the schema. Tests each argument for injection.

Depth + Complexity Attacks

Tests for query depth abuse, batch queries, alias-based DoS, and circular fragment references.

Spec Scanning Flags

Fine-tune spec scanning with endpoint filtering, intensity levels, variable substitution, and scan configuration overrides.

Flag	Default	Effect
--spec	—	Path to API spec file (auto-detected format)
--spec-url	—	URL to fetch spec from remotely
--env	—	Postman environment file for variable substitution
--var	—	Variable override `key=value` (repeatable)
--group	all	Scan only endpoints in these tags/groups/folders
--skip-group	—	Exclude endpoints in these tags/groups
--path	—	Filter endpoints by path glob
--intensity	normal	Scan depth: quick, normal, deep, paranoid
--dry-run	false	Show scan plan without executing
--yes / -y	false	Skip confirmation prompt
--scan-config	—	Path to per-endpoint override config

Per-Endpoint Overrides

Create a .waftester-spec.yaml to skip health checks, increase intensity on auth endpoints, or limit payloads per path.

.waftester-spec.yaml

endpoints:
  - path: "/api/health"
    skip: true

  - path: "/api/auth/**"
    intensity: deep
    scan_types: [sqli, xss, brokenauth]

  - path: "/api/users/*"
    max_payloads: 50
    skip_types: [info, techdetect]

  - path: "/api/admin/**"
    skip: true

Auto-Loaded

 $ waftester scan --spec openapi.yaml -u https://api.example.com

Picks up .waftester-spec.yaml from the current directory.

Explicit Path

 $ waftester scan --spec openapi.yaml --scan-config ./configs/spec.yaml

Share scan configs across teams via version control.

Combining Spec + Scan Control Flags

All 13 scan control flags work with spec scanning. Rate-limit production targets, filter by severity, stop on first finding, and include evidence.

Combined Spec + Scan Flags

# Spec scan with severity filter — only critical/high
$ waftester scan --spec openapi.yaml -u https://api.example.com \
    -msev critical,high

# Production audit: spec + stealth + rate limiting
$ waftester scan --spec openapi.yaml -u https://api.example.com \
    --intensity deep \
    -rl 10 -rlph -rr \
    -msev critical,high \
    --tamper-profile=stealth \
    -format sarif -o audit.sarif

# Spec scan that stops on first vulnerability
$ waftester scan --spec openapi.yaml -u https://api.example.com \
    -sof

# Postman collection with all controls
$ waftester scan --spec collection.json \
    --env staging.postman_environment.json \
    --var "api_key=test-key" \
    --group "Users,Orders" \
    -r 3 -sof -fsev info \
    -format json -o results.json

Flag	Alias	Effect
--match-severity	-msev	Only report findings at these severities
--filter-severity	-fsev	Exclude findings at these severities
--stop-on-first	-sof	Stop after first vulnerability found
--rate-limit-per-host	-rlph	Per-host rate limiting
--retries	-r	Retry failed requests N times
--respect-robots	-rr	Respect robots.txt exclusions
--include-evidence	-ie	Include request/response evidence in output

Format & Protocol Support

Format / Protocol	Command	Auto-Discovery	Schema-Aware
OpenAPI 3.x	scan --spec openapi.yaml	Yes	Yes
Swagger 2.0	scan --spec swagger.json	Yes	Yes
Postman v2.x	scan --spec collection.json --env env.json	Yes	Yes
HAR v1.2	scan --spec recording.har	Yes	Yes (from traffic)
AsyncAPI 2.x	scan --spec asyncapi.yaml	Yes	Yes
GraphQL	scan -u url -types graphql	Yes (introspection)	Yes
gRPC	grpc -u host:port --fuzz	Yes (reflection)	Yes (protobuf)
SOAP	soap --wsdl url --fuzz	Yes (WSDL)	Yes (XML Schema)
WebSocket	scan -u ws://url -types websocket	Yes	Partial
HTTP/REST	scan -u url --smart	Yes (crawl + JS)	Yes (auto-calibrate)

MCP Tools for Spec Scanning

9 MCP tools give AI agents full access to spec scanning — from validation to intelligence analysis — through a structured, typed interface.

Parsing & Validation

validate_spec — Parse and validate without scanning
list_spec_endpoints — Extract endpoints with group filtering
describe_spec_auth — Describe auth schemes in spec
export_spec — Export parsed spec as normalized JSON

Planning & Scanning

plan_spec — Generate intelligent scan plan
preview_spec_scan — Preview scan plan as table
scan_spec — Execute spec-driven scan (async)

Analysis

spec_intelligence — Run 8-layer intelligence analysis
compare_baselines — Diff findings between scans

Workflow

Checkpoint + resume for long scans
Correlation IDs for WAF log matching
Baseline comparison for regression testing

From Spec to CI in 3 Commands

API security testing becomes a CI job. Update your spec, push, and WAFtester tests every endpoint automatically.

1 Test locally against your spec

terminal

$ waftester scan --spec openapi.yaml -u https://staging-api.example.com -format sarif -o results.sarif

2 Generate your CI pipeline

terminal

$ waftester cicd -p github-actions -u '${{ secrets.API_URL }}' --openapi openapi.yaml

3 Results appear in GitHub Security

.github/workflows/api-security.yml

name: API Security Test
on:
  push:
    paths: ['openapi.yaml', 'swagger.json', '*.postman_collection.json']

jobs:
  api-security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: waftester/waftester-action@v1
        with:
          target: ${{ secrets.API_URL }}
          spec: openapi.yaml
          format: sarif
          output: results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Why API Teams Choose WAFtester

7 Spec Formats, One Command

OpenAPI, Swagger, Postman, HAR, AsyncAPI, GraphQL, gRPC. One unified --spec flag handles all of them. Format auto-detected from content.

Schema-Driven Payloads

WAFtester reads your spec and generates payloads that respect parameter types, required fields, and content types. No wasted requests on invalid inputs.

Postman Workflow

Export your Postman collection, point WAFtester at it with --env for variable substitution, and scan every endpoint your QA team already defined.

HAR-Based Discovery

No spec? Record browser traffic with DevTools, export HAR, and scan. Every AJAX call, API fetch, and WebSocket message becomes a test target.

Coverage Reporting

Know exactly which endpoints were tested, which parameters were fuzzed, and which ones your WAF missed. Per-endpoint, per-parameter visibility.

Spec-Change Triggers

Trigger API security tests when your spec changes. New endpoint? It gets tested on the next push. Removed a parameter? Coverage adjusts automatically.

For quick API testing commands, see the API Testing cheat sheet. To automate API security testing with AI, see AI & MCP Agents. For CI/CD pipeline integration, see the CI/CD guide.

Ready to Try It?

One command to install. One command to scan. Real results in seconds.

$ npm install -g @waftester/cli

Get Started View on GitHub