Operator
144 lines
4.2 KiB
Markdown
144 lines
4.2 KiB
Markdown
# 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.
|