CoM-Fuzzer-public/README.md

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

pip install requests pyyaml

Quick Start

# 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

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.

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:

--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:

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:

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.