# Fuzzer — HTTP/AI Adversarial Testing Tool

CLI fuzzer for authorized security testing of HTTP endpoints and AI/LLM APIs. Put `{{FUZZ}}` anywhere in a request and it handles the rest: auth flows, payload delivery, response analysis, and reporting.

## Install

```bash
pip install requests pyyaml
```

## Quick Start

```bash
# Generate starter configs
python fuzzer.py --gen-templates configs

# Run against a target
python fuzzer.py -c configs/simple_post.yml -w wordlists/payloads.txt -o results.log

# Single payload
python fuzzer.py -u https://api.example.com/query -b '{"q": "{{FUZZ}}"}' -p "test payload"
```

## Placeholders

| Placeholder | Replaced with |
|---|---|
| `{{FUZZ}}` | Each payload from your wordlist |
| `{{AUTH}}` | Bearer token after the auth step runs |
| `{{KEY}}` | Any key from your vars file — `{{TOKEN}}`, `{{USERNAME}}`, etc. |

Put them anywhere: URL, headers, body.

## Config File

```yaml
name: "My Test"

auth:
  url: "https://auth.example.com/oauth2/token"
  token_field: "access_token"
  cache: 280

request:
  url: "https://api.example.com/v1/query"
  method: POST
  headers:
    Authorization: "Bearer {{AUTH}}"
    Content-Type: "application/json"
  body: '{"prompt": "{{FUZZ}}"}'
  fuzz_encoding: json

settings:
  timeout: 30
  delay: 0.1
```

## Vars File

A flat `KEY=VALUE` file. Keeps credentials out of configs.

```env
TOKEN=your-token-here
USERNAME=testuser
PASS=testpass
```

Pass with `-e configs/vars.env` or let it auto-discover `vars.env`.

## Key Flags

```
-w FILE        Wordlist (one payload per line)
-p TEXT        Single payload
-c FILE        Config file
-u URL         Target URL (CLI mode)
-b BODY        Request body template
-H 'Name: V'  Add header (repeatable)
-e FILE        Vars file
-o FILE        Output log (default: fuzzer_output.log)
--threads N    Concurrent workers (default: 1)
--delay N      Seconds between requests
--proxy URL    Route through proxy (e.g. Burp: http://127.0.0.1:8080)
--skip N       Skip first N payloads (resume)
--max N        Stop after N payloads
--report FILE  Write HTML/JSON/CSV report
--debug        Show full request/response exchange
```

## Wordlist Organization

Any flat text file works as a wordlist (one payload per line, `#` for comments). You can organize them by category or test type manually — the fuzzer takes one wordlist at a time via `-w`.

## Authentication

Supports OAuth2 client credentials, session/cookie auth, API key headers, and custom auth flows. The `{{AUTH}}` placeholder is auto-filled after each auth cycle, and tokens are cached for the duration specified in `auth.cache`.

See `configs/oauth2.yml` and `configs/session_auth.yml` for examples.

## Response Flagging

Flag responses by status code, body content, or size:

```bash
--flag-status 200 403       # Flag these status codes
--flag-contains "error"     # Flag responses containing text
--flag-not-contains "deny"  # Flag responses missing text
--flag-size-min 1000        # Flag responses over 1000 bytes
```

Flagged responses are highlighted in terminal output and separated in reports.

## Log Analysis

Analyze an existing log file without re-running the fuzzer:

```bash
python fuzzer.py --analyze results.log
python fuzzer.py --analyze results.log --analyze-html report.html
```

## Multi-Turn Sequences

Chain requests for conversation-based testing:

```bash
python fuzzer.py --sequences configs/sequences_example.json --sequence "jailbreak-chain" -c configs/simple_post.yml
```

## Other Features

- **OpenAPI discovery**: `--openapi spec.yaml` — parse endpoints, auto-generate configs
- **Burp import**: `--burp-import burp-export.xml` — use a Burp-captured request as the target
- **Payload mutation**: `--mutate encoding` — auto-generate encoding variants (base64, URL, unicode, etc.)
- **Combinator**: `--prefix-file p.txt --suffix-file s.txt --combine` — combine prefix+payload+suffix
- **Checkpoint/resume**: saves state automatically, `--skip N` to resume
- **Deduplication**: `--dedupe-file results.log` — remove duplicate responses from a log
- **Jitter**: `--jitter` — randomize timing between requests
- **UA rotation**: `--rotate-ua` — cycle User-Agent headers

## Authorization

For authorized security testing only. Always obtain written scope authorization before testing any system you don't own.