Fray

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

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

Auth guide → · Scan options → · CI guide →

5,500+ Payloads · 24 Categories · 120 CVEs

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

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: [email protected] · SECURITY.md

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