PyFuzz

PyFuzz is an intelligent API security testing tool with token handling, header mutation, and bypass testing capabilities. Designed for discovering hidden endpoints and testing authentication/authorization mechanisms.

🔍 Features

• Payload Fuzzing - Automatic JSON/SQL/XSS/command injection payload variations
• Vulnerability Detection - IDOR, privilege escalation, auth bypass, sensitive data exposure
• Token Handling - Bearer tokens, API keys, and custom authorization headers
• Header Mutation - Automatic header fuzzing for bypass testing (X-Forwarded-For, X-Original-URL, etc.)
• Random User-Agent - Rotate user agents and referers to evade detection
• HTTP Method Selection - Support for GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
• Rate Limiting - Configurable requests per second (default: 5 req/sec)
• Path Traversal Protection - Automatically skips unsafe wordlist entries
• Session Logging - UTC timestamps, session IDs, and tool/version metadata in all logs
• Multiple Output Options - Save results to file, quiet/verbose modes
• Progress Tracking - Real-time progress bar (can be disabled)
• Smart Retry Logic - Handles timeouts, connection errors, and 429 rate limits

---

⚙️ Installation & Usage

1. Clone the Repository

git clone https://github.com/Kushal-39/PyFuzz----simple-python-api-fuzzer
cd PyFuzz----simple-python-api-fuzzer

2. Install Dependencies

pip install requests tqdm

3. Run the Script

Basic Usage

python fuzz.py -u https://example.com/api

Custom HTTP Method

python fuzz.py -u https://example.com/api --method POST

With Authentication

python fuzz.py -u https://example.com/api --token YOUR_TOKEN --method POST

With Header Mutation (Bypass Testing)

python fuzz.py -u https://example.com/api --mutate-headers --random-agent -v

With Vulnerability Detection

python fuzz.py -u https://example.com/api --detect-flaws --test-idor --method POST

With Payload Fuzzing

python fuzz.py -u https://example.com/api --payload-fuzz --detect-flaws --method POST

Full Security Test

python fuzz.py -u https://example.com/api \
  --token YOUR_TOKEN \
  --mutate-headers \
  --random-agent \
  --payload-fuzz \
  --detect-flaws \
  --test-idor \
  --method POST \
  --rate-limit 2 \
  -o results.txt

Command Line Arguments

Basic Options:

• -u, --url: Target URL (required, must include http:// or https://)
• -w, --wordlist: Custom wordlist file (default: apiroutes.txt)
• --method: HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
• --timeout: Request timeout in seconds (default: 3)
• --rate-limit: Maximum requests per second (default: 5)

Authentication:

• --token: Authorization token (automatically formatted with Bearer prefix)
• --token-type: Token type for Authorization header (default: Bearer)
• --api-key: API key for X-API-Key header

Header Options:

• --header: Custom header in format "Key: Value" (repeatable)
• --mutate-headers: Enable header mutation for bypass testing
• --random-agent: Use random User-Agent for each request
• --user-agent: Custom User-Agent string

Security Testing:

• --payload-fuzz: Enable payload fuzzing with injection patterns
• --detect-flaws: Enable auth/logic flaw detection
• --test-idor: Test for IDOR vulnerabilities by varying IDs

Output Options:

• -o, --output: Save results to file
• -v, --verbose: Enable verbose output (debug logging)
• -q, --quiet: Quiet mode (only show results)
• --no-progress: Disable progress bar
• -h, --help: Show help message

Get Help

python fuzz.py --help

---

🧪 Example Output

Basic Scan

PyFuzz v1.0.0 | Session: 123e4567-e89b-12d3-a456-426614174000 | UTC: 2025-12-10T12:00:00Z
2025-12-10T12:00:00Z [PyFuzz 1.0.0] [session:123e4567...] INFO - Target URL: https://example.com/api
2025-12-10T12:00:00Z [PyFuzz 1.0.0] [session:123e4567...] INFO - HTTP Method: POST
Scanning: 100%|████████████████████████| 50/50 [00:10<00:00, 5.00word/s]

[+] Working endpoint: https://example.com/api/users
    Status code: 200 | Response size: 284 bytes
    Response: {'message': 'Success', 'users': [...]}

2025-12-10T12:00:10Z [PyFuzz 1.0.0] [session:123e4567...] INFO - Found 1 working endpoints

With Vulnerability Detection

PyFuzz v1.0.0 | Session: 707d9b14-3d3d-4f39-8c22-49dfd936d23e | UTC: 2025-12-10T15:54:53Z
2025-12-10T15:54:53Z [PyFuzz 1.0.0] [session:707d9b14...] INFO - Auth/logic flaw detection enabled
2025-12-10T15:54:53Z [PyFuzz 1.0.0] [session:707d9b14...] INFO - IDOR vulnerability testing enabled
Scanning: 100%|████████████████████████| 35/35 [01:39<00:00, 2.85s/test]

[+] Working endpoint: http://localhost:5555/api/profile
    Status code: 200 | Response size: 105 bytes
    Payload: {'id': 1, 'user_id': 1, '_idor_test': 1}
    ⚠️  VULNERABILITIES DETECTED (5):
        - Admin access detected (field: is_admin, indicator: admin)
        - Sensitive data exposure: api_key, token
        - Privilege escalation: Admin flag set to true
        - IDOR confirmed: User 1 data accessible
        - Possible IDOR: ID 1 found in response
    Response preview: {'api_key': 'secret_key_12345', 'is_admin': True, 'token': '...', 'user_id': 1}

[+] Working endpoint: http://localhost:5555/login
    Status code: 403 | Response size: 55 bytes
    ⚠️  VULNERABILITIES DETECTED (1):
        - Auth bypass detected: 3 success indicators in denied response
    Response preview: {'authenticated': True, 'success': True, 'token': 'abc123'}

2025-12-10T15:56:32Z [PyFuzz 1.0.0] [session:707d9b14...] WARNING - ⚠️  Total vulnerabilities detected: 6
2025-12-10T15:56:32Z [PyFuzz 1.0.0] [session:707d9b14...] INFO - Found 2 working endpoints

---

🔒 Security Testing Features

Vulnerability Detection (--detect-flaws) identifies:

• Admin/privileged access without proper authentication
• Sensitive data exposure (passwords, API keys, tokens, PII)
• Privilege escalation vulnerabilities (role manipulation)
• Authentication bypass patterns
• Success indicators in denied responses (403/401)

IDOR Testing (--test-idor) detects:

• Insecure Direct Object References
• Unauthorized access to other users' data
• Edge case handling (negative IDs, zero, large numbers)
• PII exposure through IDOR
• ID enumeration vulnerabilities

Payload Fuzzing (--payload-fuzz) tests:

• JSON payload variations (type confusion, role manipulation)
• SQL injection patterns (UNION, OR 1=1, admin'--, etc.)
• XSS payloads (script tags, event handlers)
• Command injection attempts
• Boolean-based logic bypass
• Admin/privileged role injection

Header Mutation (--mutate-headers) enables:

• IP-based access control bypass (X-Forwarded-For, X-Real-IP, X-Client-IP)
• URL rewriting vulnerabilities (X-Original-URL, X-Rewrite-URL)
• Host header injection (X-Forwarded-Host, X-Host)
• Authentication/authorization bypasses

Token Handling supports:

• Bearer tokens for OAuth/JWT authentication
• API key authentication
• Custom authorization schemes
• Multiple custom headers per request

---

⚠️ Disclaimer

This tool is intended for educational and ethical security research only.
Do not use it on systems without explicit permission. Unauthorized use may violate legal and ethical guidelines.

---

🪪 License

This project is open-source under the GPL 3.0 License.