Skip to content

README.md

Latest commit

 

History

History
215 lines (169 loc) · 7.49 KB

README.md

File metadata and controls

215 lines (169 loc) · 7.49 KB

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.