fray 3.2.0

Open-source WAF Security Testing Platform — 5,500+ attack payloads, 25 WAF fingerprints, beautiful CLI output

Fray

🌐 Language: English | 日本語

⚔️ Open-source WAF security testing toolkit — scan, detect, test, report

FOR AUTHORIZED SECURITY TESTING ONLY — Only test systems you own or have explicit written permission to test.

---

Why Fray?

Most payload collections are static text files. Fray is a complete workflow:

• fray scan — Auto crawl → param discovery → payload injection (new)
• fray recon — 21 automated checks (TLS, headers, DNS, CORS, params, JS, history, GraphQL, API, Host injection, admin panels)
• fray detect — Fingerprint 25 WAF vendors
• fray test — 5,500+ payloads across 24 OWASP categories (incl. prototype pollution)
• fray report — HTML & Markdown reports
• Zero dependencies — pure Python stdlib, pip install fray and go

Who Uses Fray?

• Bug Bounty Hunters — Discover hidden params, old endpoints, bypass WAFs, file reports
• Pentesters — Full recon + automated scan with client-ready HTML reports
• Blue Teams — Validate WAF rules, regression test after config changes
• DevSecOps — CI/CD pipeline WAF testing, fail builds on bypasses
• Security Researchers — Find WAF bypasses, contribute payloads
• Students — Interactive CTF tutorials, learn attack vectors hands-on

---

Quick Start

pip install fray

fray demo                                        # Try it now — WAF detect + XSS scan
fray scan https://example.com                    # Auto scan (crawl + inject)
fray recon https://example.com                   # Reconnaissance
fray test https://example.com --smart            # Smart payload testing
fray detect https://example.com                  # WAF detection
fray explain CVE-2021-44228                      # CVE intelligence
fray report -i results.json -o report.html       # Generate report

---

Demo

fray demo detects the WAF, crawls the target, and injects XSS payloads. ↩ REFLECTED = payload confirmed in response body. Found 9 XSS bypasses in 28 seconds.

---

fray scan — Automated Attack Surface Mapping

One command: crawl your target, discover injection points, test payloads, report results.

fray scan https://example.com -c xss -m 3 -w 4

──────────────────── Crawling https://example.com ────────────────────
  [  1] https://example.com
  [  2] https://example.com/search
  [  3] https://example.com/guestbook.php
  ✓ Crawled 10 pages, found 7 injection points (3 forms, 1 JS endpoints)

──────────────────────── Payload Injection ───────────────────────────
  [1/7] POST /guestbook.php ?name= (form)
      BLOCKED   403 │ <script>alert(1)</script>
      PASSED    200 │ <img src=x onerror=alert(1)>    ↩ REFLECTED
  [2/7] GET  /search ?q= (form)
      BLOCKED   403 │ <script>alert(1)</script>
      PASSED    200 │ <img src=x onerror=alert(1)>    ↩ REFLECTED

╭──────────── Scan Summary ────────────╮
│ Total Tested      21                 │
│ Blocked           15  (71.4%)        │
│ Passed             6                 │
│ Reflected          4  ← confirmed    │
╰──────────────────────────────────────╯

Reflected payloads are highlighted with ↩ REFLECTED — confirmed injection where the payload appears verbatim in the response body.

What it does:

1. Crawls — BFS spider, follows same-origin links, seeds from robots.txt + sitemap.xml
2. Discovers — Extracts params from URLs, HTML forms, and JavaScript API calls
3. Injects — Tests each parameter with payloads from your chosen category
4. Detects reflection — Confirms when payloads appear verbatim in the response body
5. Auto-backoff — Handles 429 rate limits with exponential backoff

# Scope-restricted scan (bug bounty)
fray scan https://target.com --scope scope.txt -w 4

# Authenticated scan with stealth
fray scan https://app.target.com --cookie "session=abc" --stealth

# Deep scan with SQLi payloads
fray scan https://target.com -c sqli --depth 5 --max-pages 100

# JSON output for CI pipelines
fray scan https://target.com --json -o results.json

Full scan options + examples →

---

fray recon — 21 Automated Checks

fray recon https://example.com
fray recon https://example.com --js       # JS endpoint extraction
fray recon https://example.com --history  # Historical URL discovery
fray recon https://example.com --params   # Parameter brute-force mining

Check	What It Finds
Parameter Discovery	Query strings, form inputs, JS API endpoints
Parameter Mining	Brute-force 136 common param names, detect hidden ?id=, ?file=, ?redirect=
JS Endpoint Extraction	LinkFinder-style: hidden APIs, hostnames, cloud buckets (S3/GCS/Azure), API keys, secrets
Historical URLs	Old endpoints via Wayback Machine, sitemap.xml, robots.txt
GraphQL Introspection	Probe 10 common endpoints, detect exposed schema (types, fields, mutations)
API Discovery	Swagger/OpenAPI specs, /api/v1/, /api-docs, health endpoints — exposes every route & param
Host Header Injection	Password reset poisoning, cache poisoning, SSRF via Host: / X-Forwarded-Host manipulation
Admin Panel Discovery	70 paths: /admin, /wp-admin, /phpmyadmin, /actuator, /console, debug tools
TLS	Version, cipher, cert expiry
Security Headers	HSTS, CSP, X-Frame-Options (scored)
Cookies	HttpOnly, Secure, SameSite flags
Fingerprinting	WordPress, PHP, Node.js, nginx, Apache, Java, .NET
DNS	A/CNAME/MX/TXT, CDN detection, SPF/DMARC
CORS	Wildcard, reflected origin, credentials misconfig
Rate Limit Fingerprint	Map threshold (req/s before 429), burst limit, lockout duration, safe delay
WAF Detection Mode	Signature vs anomaly vs hybrid — body diff, timing diff, header diff
WAF Rule Gap Analysis	Cross-reference vendor against known bypasses, detection gaps, technique matrix

Plus: 28 exposed file probes (.env, .git, phpinfo, actuator) · subdomains via crt.sh

--js parses inline and external JavaScript files — LinkFinder-style extraction of fetch(), axios, XMLHttpRequest calls, full absolute URLs, internal hostnames/subdomains, cloud storage buckets (AWS S3, GCS, Azure Blob, Firebase, DO Spaces), and leaked secrets (AWS keys, Google API keys, GitHub tokens, Stripe keys, Slack webhooks, JWTs, Bearer tokens, generic API keys).

--history queries Wayback Machine CDX API, sitemap.xml, and robots.txt Disallow paths. Old endpoints often have weaker WAF rules.

--params brute-forces 136 common parameter names against discovered endpoints. Detects hidden params by response diff (status, size, reflection). Risk-rated: HIGH (SSRF/LFI/injection), MEDIUM (XSS/IDOR).

GraphQL introspection runs automatically during full recon. Probes /graphql, /api/graphql, /v1/graphql, /graphiql, /playground, etc.

API discovery probes 30+ common paths: swagger.json, openapi.json, /api-docs, /swagger-ui/, versioned API roots. Parses specs to extract every endpoint, method, and auth scheme.

New to Fray? Run fray help for a friendly guide to every command.

Recon guide →

---

fray test --smart — Adaptive Payload Selection

Runs recon first, then recommends payloads based on detected stack:

fray test https://example.com --smart

  Stack:   wordpress (100%), nginx (70%)

  Recommended:
    1. sqli            (1200 payloads)
    2. xss             (800 payloads)
    3. path_traversal  (400 payloads)

  [Y] Run recommended  [A] Run all  [N] Cancel  [1,3] Pick:

OWASP coverage →

---

fray detect — 25 WAF Vendors

fray detect https://example.com

Cloudflare, AWS WAF, Akamai, Imperva, F5 BIG-IP, Fastly, Azure WAF, Google Cloud Armor, Sucuri, Fortinet, Wallarm, Vercel, and 13 more.

Detection signatures →

---

Key Features

Feature	How	Example
Scope Enforcement	Restrict to permitted domains/IPs/CIDRs	--scope scope.txt
Concurrent Scanning	Parallelize crawl + injection (~3x faster)	-w 4
Stealth Mode	Randomized UA, jitter, throttle — one flag	--stealth
Authenticated Scanning	Cookie, Bearer, custom headers	--cookie "session=abc"
CI/CD	GitHub Actions with PR comments + fail-on-bypass	fray ci init

Auth guide → · Scan options → · CI guide →

---

5,500+ Payloads · 24 Categories · 120 CVEs

Category	Count	Category	Count
XSS	867	SSRF	167
SQLi	456	SSTI	98
Command Injection	234	XXE	123
Path Traversal	189	AI/LLM Prompt Injection	370

fray explain log4shell    # CVE intelligence with payloads
fray explain results.json # Human-readable findings: impact, remediation, next steps
fray payloads             # List all 24 payload categories

Payload database → · CVE coverage →

---

AI-Ready Output — --ai Flag

fray scan target.com --ai           # LLM-optimized JSON for AI agents
fray test target.com -c xss --ai    # Pipe into any AI workflow
fray recon target.com --ai           # Structured recon for Claude, GPT, etc.

# Example pipeline:
fray scan target.com --ai | ai analyze

Output: structured JSON with technologies, vulnerabilities (CWE-tagged, confidence-scored), security posture, and suggested next actions — ready for direct LLM consumption.

Attack Surface Graph

fray graph example.com          # Visual tree of the entire attack surface
fray graph example.com --deep   # + JS endpoints + Wayback historical URLs
fray graph example.com --json   # Machine-readable graph

Output:

🌐 example.com
├── 📂 Subdomains (8)
│   ├── 🔗 api.example.com
│   ├── 🔗 admin.example.com
│   └── 🔗 cdn.example.com
├── 🛡️ WAF: Cloudflare
├── 📂 Technologies
│   ├── ⚙️ nginx (95%)
│   └── ⚙️ wordpress (70%)
├── 📂 Admin Panels (2)
│   └── 📍 /admin/ [200] OPEN
├── 📍 GraphQL: /graphql (introspection OPEN)
├── 📂 Exposed Files (3)
│   ├── 📄 .env
│   └── 📄 .git/config
└── 📂 Recommended Attacks
    ├── ⚔️ xss
    └── ⚔️ sqli

Aggregates all 21 recon checks into a single tree view — subdomains (crt.sh), DNS, WAF/CDN, technologies, admin panels, API endpoints, GraphQL, exposed files, CORS issues, parameters, and recommended attack categories.

SARIF Output — GitHub Security Tab

fray scan target.com --sarif -o results.sarif    # SARIF 2.1.0 from scan
fray test target.com -c xss --sarif -o results.sarif  # SARIF from test

# Upload to GitHub:
gh code-scanning upload-sarif --sarif results.sarif

Fray findings appear directly in GitHub's Security tab alongside CodeQL and Semgrep. Each finding includes CWE tags, severity levels, and payload details.

Diff — Visual Regression Testing

fray diff before.json after.json        # Color-coded visual diff
fray diff before.json after.json --json # Machine-readable diff

Git-style visual output: regressions in red (- BLOCKED → + BYPASS), improvements in green (- BYPASS → + BLOCKED), with per-category breakdown table. Exit code 1 on regressions — perfect for CI/CD gates.

MCP Server — AI Integration

pip install 'fray[mcp]'

Claude Desktop — One-Liner Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "fray": {
      "command": "python",
      "args": ["-m", "fray.mcp_server"]
    }
  }
}

Restart Claude Desktop. Ask: "What XSS payloads bypass Cloudflare?" → Fray's 10 MCP tools are called directly.

10 MCP Tools

Tool	What it does
list_payload_categories	List all 24 attack categories
get_payloads	Retrieve payloads by category
search_payloads	Full-text search across 5,500+ payloads
get_waf_signatures	WAF fingerprints for 25 vendors
get_cve_details	CVE lookup with payloads and severity
suggest_payloads_for_waf	Best bypass payloads for a specific WAF
analyze_scan_results	Risk assessment from scan/test JSON
generate_bypass_strategy	Mutation strategies for blocked payloads
explain_vulnerability	Beginner-friendly payload explanation
create_custom_payload	Generate payloads from natural language

Claude Code guide → · ChatGPT guide → · mcp.json →

---

Project Structure

fray/
├── fray/
│   ├── cli.py              # CLI entry point
│   ├── scanner.py           # Auto scan: crawl → inject
│   ├── recon.py             # 14-check reconnaissance
│   ├── detector.py          # WAF detection (25 vendors)
│   ├── tester.py            # Payload testing engine
│   ├── reporter.py          # HTML + Markdown reports
│   ├── mcp_server.py        # MCP server for AI assistants
│   └── payloads/            # 5,500+ payloads (22 categories)
├── tests/                   # 624 tests
├── docs/                    # 30 guides
├── mcp.json                 # MCP manifest (tools, inputs, outputs)
├── smithery.yaml            # Smithery.ai registry manifest
└── pyproject.toml           # pip install fray

---

Roadmap

• Auto scan: crawl → discover → inject (fray scan)
• Reflected payload detection (confirmed injection)
• Scope file enforcement + concurrent workers
• 14-check reconnaissance, smart mode, WAF detection
• HTML/Markdown reports, MCP server
• HackerOne API integration (auto-submit findings)
• Web-based report dashboard
• ML-based payload effectiveness scoring

---

Contributing

See CONTRIBUTING.md.

Legal

MIT License — See LICENSE. Only test systems you own or have explicit authorization to test.

Security issues: [e-mail] · SECURITY.md

---

📖 All Documentation (30 guides) · PyPI · Issues · Discussions