DOCSEARCHbyAlgolia
Submit Docs

WAF Bypass Tool Documentation

repository·master·Indexed 23 days ago

https://github.com/nemesida-waf/waf-bypass

An open-source security analysis tool by nemesida-waf designed to test Web Application Firewalls (WAF) for False Positives and False Negatives using customizable payloads. It features a CLI for scanning target hosts, support for Docker and pipx installation, and a flexible payload system targeting various HTTP zones such as URL, ARGS, BODY, and COOKIE. The tool provides detailed results in JSON format and can generate cURL commands for reproducing bypassed requests.

Tokens
2K
Snippets
3
Records
7
Agent score
31%

What's inside WAF Bypass Tool

  1. How to write custom payloads

    master

    Custom payloads are defined in JSON files and placed in the /payload/ directory (or a subdirectory within it). You can target specific parts of an HTTP request using 'zones'.

    Supported Zones

    • URL: Request path
    • ARGS: Query parameters
    • BODY: Request body
    • COOKIE: Cookies
    • USER-AGENT: User-Agent header
    • REFERER: Referer header
    • HEADER: Custom headers
    • METHOD: HTTP method

    Special Features

    • Randomization: Use the %RND% suffix to generate a random 6-character alphanumeric string (e.g., param=%RND%).
    • Encoding: For ARGS, BODY, COOKIE, and HEADER zones, you can specify encoding types like Base64, HTML-ENTITY, or UTF-16. Multiple values are space-separated (e.g., Base64 UTF-16).
    • JSON Body: Use the JSON key to specify the request body should be in JSON format.
    • Blocking Logic: Use the BLOCKED key to specify if the request should be blocked (for False Negative testing) or not (for False Positive testing).

    Directory-Specific Rules

    • API Directory: Payloads here automatically include the Content-Type: application/json header.
    • MFD (multipart/form-data) Directory: Requires a BODY (required) and an optional BOUNDARY. If BOUNDARY is provided, the BODY must follow RFC formatting to allow multiple payloads separated by the boundary.

  2. Install and run WAF Bypass Tool via pipx

    master

    You can install the tool globally using pipx directly from the GitHub repository.

    # Install via git
pipx install git+https://github.com/nemesida-waf/waf-bypass.git

# Run the installed binary
<pipx bin dir>/waf-bypass

  3. Install and run WAF Bypass Tool from source

    master

    To run the tool directly from the source code, clone the repository, install the requirements, and execute main.py.

    # Clone the repository
git clone https://github.com/nemesida-waf/waf_bypass.git /opt/waf-bypass/

# Install dependencies
python3 -m pip install -r /opt/waf-bypass/requirements.txt

# Run the CLI
python3 /opt/waf-bypass/main.py --host='example.com'
    # git clone https://github.com/nemesida-waf/waf_bypass.git /opt/waf-bypass/

# python3 -m pip install -r /opt/waf-bypass/requirements.txt

# python3 /opt/waf-bypass/main.py --host='example.com'

  4. Install and run WAF Bypass Tool via Docker

    master

    The easiest way to run the tool is using Docker. You can pull the latest image from Docker Hub and run it by specifying the target host.

    # Pull the image
docker pull nemesida/waf-bypass

# Run the scan against a host
docker run nemesida/waf-bypass --host='example.com'
    # docker pull nemesida/waf-bypass

# docker run nemesida/waf-bypass --host='example.com'

  5. Use the WAF Bypass CLI

    master

    The main.py script provides a command-line interface to run WAF bypass scans against a target host. You can specify a target host, configure a proxy, add custom HTTP headers, set a User-Agent, and define which HTTP status codes indicate a WAF block.

    Basic Usage

    python3 main.py --host=example.com:80 --proxy='http://1.2.3.4:3128'

    Command Line Options

    OptionDescription
    --host=HOSTMandatory. The target host (e.g., example.com:80). If no schema is provided, http:// is prepended automatically.
    --proxy=PROXYMandatory. The proxy server URL (e.g., --proxy='http://1.2.3.4:3128').
    --header='NAME: VALUE'Add an HTTP header to all requests. Can be used multiple times.
    --user-agent='UA'Set the HTTP User-Agent. Note: payloads may override this.
    --block-code=CODEDefine HTTP status codes that signify a WAF block (e.g., --block-code=222). Default is 403. Can be used multiple times.
    --threads=NNumber of parallel scan threads. Default is 4.
    --timeout=NRequest processing timeout in seconds. Default is 30.
    --json-formatDisplay the final results in JSON format.
    --detailsDisplay False Positive and False Negative payloads.
    --no-progressDisable the progress bar display.
    --curl-replayDisplay the cURL command required to reproduce False Positives, False Negatives, or Failed requests.
    --exclude-dir='DIR1,DIR2'Exclude specific payload directories (e.g., SQLi,XSS). Directories are treated case-insensitively.

  6. WAF Bypass Tool CLI options reference

    master

    The CLI provides several options to customize the scan behavior, authentication, and output format.

    | Option | Description | |---|---|--host| The target host to scan (required).| | --proxy='URL'| Specify a proxy to connect to instead of the host directly.|--header 'Key: Value'| HTTP header to send with all requests (can be used multiple times for auth).| | --user-agent 'String'| Set the HTTP User-Agent (unless overridden by a payload).| | --block-code='CODE'| HTTP status code expected when WAF blocks (default: 403). Can be used multiple times.|--threads=N| Number of parallel scan threads (default: 10).| | --timeout=N| Request processing timeout in seconds (default: 30).| | --exclude-dir='DIR1,DIR2'| Exclude specific payload directories (e.g., 'SQLi,XSS').| | --json-format| Output results in JSON format (useful for integrations).|--details| Display False Positive and False Negative payloads (incompatible with --json-format).| | --no-progress| Disable the progress bar.|--curl-replay| Display cURL commands to reproduce failed/bypassed requests (incompatible with --json-format).|

  7. Understand the JSON output format

    master

    When using the --json-format option, the tool produces a structured JSON object containing scan configuration and results. This format is designed for integration with security platforms.

    Key fields include:

    • TARGET: The host scanned.
    • FAILED: Requests that failed processing (includes error messages).
    • PASSED: Requests that were not blocked.
    • FALSED: Requests that resulted in False Positives.
    • BYPASSED: Requests that resulted in False Negatives.
    • CURL: cURL commands to reproduce specific requests.
    {
  "TARGET": "https://example.com",
  "PROXY": {},
  "HEADERS": {
    "User-Agent": ""
  },
  "BLOCK-CODE": [
    ...
  ],
  "THREADS": 50,
  "TIMEOUT": 30,
  "EXCLUDE-DIR": [
    ...
  ],
  "FAILED": {
    "MFD/7.json": {
      "BODY": "WBHTTPSConnectionPool(host='example.com', port=443): Read timed out. (read timeout=1)"
    }
  },
  "PASSED": {
    "UWA/3.json": {
      "URL": "403 RESPONSE CODE"
    }
  },
  "FALSED": {
    ...
  },
  "BYPASSED": {
    "UWA/26.json": {
      "URL": "200 RESPONSE CODE"
    }
  },
  "TestRequest": {
    "FAILED": {},
    "FALSED": {
        "UWA/3.json": {
        "URL": "403 RESPONSE CODE"
        }
    }
  },
  "CURL": {
    "FALSED": {},
    "BYPASSED": {
    "UWA/26.json": {
      "URL": "curl -X GET -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate' -H 'Connection: keep-alive' -H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36' 'https://example.com/do.php#.png'"
    }
    }
  }
}