Skip to content

quickstart.md

Latest commit

 

History

History
206 lines (151 loc) · 4.39 KB

quickstart.md

File metadata and controls

206 lines (151 loc) · 4.39 KB
Raw

Quick Start Guide

Get started with Fray in 5 minutes!

🚀 Installation

Option 1: Install from PyPI (Recommended)

pip install fray

Option 2: Clone from GitHub

git clone https://github.com/dalisecurity/fray.git
cd fray

📋 Prerequisites

  • Python 3.8+
  • No additional dependencies required (uses standard library only!)

🎯 Usage

Detect WAF Vendor

fray detect https://example.com

Test with Specific Category

# Test XSS payloads
fray test https://example.com -c xss --max 10

# Test SQL injection
fray test https://example.com -c sqli --max 10

# Test SSRF
fray test https://example.com -c ssrf --max 10

List Available Payload Categories

fray payloads

Legacy CLI (also works)

python3 waf_tester.py -i
python3 waf_tester.py -t https://example.com -p payloads/xss/basic.json
python3 waf_tester.py -t https://example.com -p payloads/xss/basic.json --max 10

📊 Understanding Results

Output Example

[1/10] BLOCKED  | Status: 403 | basic script tag
[2/10] BLOCKED  | Status: 403 | img onerror
[3/10] PASSED   | Status: 200 | benign input
  • BLOCKED (Red): WAF detected and blocked the payload
  • PASSED (Green): Payload was not blocked
  • Status: HTTP response code (403 = blocked, 200 = passed)

Report File

After testing, a JSON report is generated:

{
  "target": "https://example.com",
  "timestamp": "2026-02-28T15:30:00",
  "summary": {
    "total": 100,
    "blocked": 98,
    "passed": 2,
    "block_rate": "98.00%"
  },
  "results": [...]
}

🎓 Common Use Cases

1. Quick WAF Check

fray detect https://your-site.com

2. Quick XSS Test

fray test https://your-site.com -c xss --max 10

3. Multi-Vector Test

# Test XSS
fray test https://your-site.com -c xss -o xss_results.json

# Test SQLi
fray test https://your-site.com -c sqli -o sqli_results.json

# Test SSRF
fray test https://your-site.com -c ssrf -o ssrf_results.json

4. Comprehensive Test (all categories)

fray test https://your-site.com --max 20

⚙️ Advanced Options

fray test --help

Options:

  • -c, --category: Payload category (e.g. xss, sqli, ssrf)
  • -p, --payload-file: Specific payload file to use
  • -m, --max: Maximum number of payloads to test
  • -d, --delay: Delay between requests (default: 0.5s)
  • -t, --timeout: Request timeout (default: 8s)
  • -o, --output: Output results JSON file

🔒 Important Notes

Authorization Required

ONLY test systems you own or have explicit permission to test!

Unauthorized testing is:

  • ✗ Illegal
  • ✗ Unethical
  • ✗ May result in criminal charges

Responsible Use

  • Get written permission before testing
  • Follow bug bounty program rules
  • Respect rate limits
  • Don't cause harm or disruption

🐛 Troubleshooting

Connection Errors

# Increase timeout
fray test https://example.com -c xss --timeout 15

Rate Limiting

# Increase delay between requests
fray test https://example.com -c xss --delay 2

SSL Certificate Errors

The tool automatically ignores SSL certificate validation for testing purposes.

📚 Payload Categories

Available payload files:

XSS

  • payloads/xss/basic.json - 412 basic XSS payloads
  • payloads/xss/svg_based.json - 175 SVG-based XSS
  • payloads/xss/encoded.json - 12 encoded XSS
  • payloads/xss/obfuscated.json - 3 obfuscated XSS
  • payloads/xss/mutation.json - 4 mutation XSS
  • payloads/xss/dom_based.json - 24 DOM-based XSS
  • payloads/xss/polyglot.json - 1 polyglot XSS

Other

  • payloads/sqli/general.json - 13 SQL injection
  • payloads/ssrf/general.json - 7 SSRF payloads
  • payloads/xxe/general.json - 3 XXE payloads
  • payloads/ssti/general.json - 8 SSTI payloads

🎬 Video Tutorial

Coming soon! Check the repository for updates.

💬 Getting Help

🚀 Next Steps

  1. ✅ Run your first test in interactive mode
  2. 📖 Read the full documentation
  3. 🔬 Explore the methodology
  4. 🤝 Contribute your own payloads

Happy (ethical) testing! 🎯