Skip to content
akha-security
foxss
Public

About

XSS Recon Framework

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Latest commit

 

History

13 Commits

Folders and files

Repository files navigation

logo

FOXss — XSS Recon Framework

Bug bounty focused XSS recon pipeline: subdomains → live hosts → URLs → filtering → JS/DOM analysis → report

Low-noise recon • High-signal output • Shareable report • Burp Suite Integration

What is FOXss?

FOXss is a Python-based recon orchestrator built for XSS hunting.
Instead of dumping millions of URLs, FOXss tries to output actionable artifacts:

  • Live subdomains (httpx)
  • Collected URLs from multiple sources:
    • Katana (active crawling with form-fill + known-files)
    • GAU (4 providers: wayback, commoncrawl, otx, urlscan)
    • Waybackurls (all versions)
    • Urlfinder (aggressive mode with status filtering)
  • Cleanly separated files:
    • XSS candidates (query-string URLs)
    • JS URLs
    • Endpoints (no query)
  • JavaScript/DOM analysis
    • extracts hidden endpoints (absolute + relative paths)
    • flags basic DOM sink / secret-like patterns
  • Generates a modern white-themed HTML report (xss_report.html) with inline CSS/JS
  • JSON export for automation and CI/CD pipelines
  • Burp Suite integration via proxy support
  • Resumable scans with continue mode
  • Flexible filtering with exclude/include patterns

✨ Key Features

  • 🎯 13+ CLI Options - Verbose, silent, proxy, threads, timeout, and more
  • 🔄 Resume Scans - Continue interrupted scans with -c flag
  • 📊 JSON Export - API-friendly output for automation
  • 🔐 Burp Suite - Proxy support for manual analysis
  • 🎨 Beautiful Terminal UI - Progress bars, statistics, and colored output
  • ⚡ Smart Auto-scaling - Adapts thread counts based on target size
  • 🎯 URL Filtering - Exclude/include patterns for targeted scanning
  • 🚀 Skip Options - Skip crawling or JS analysis for faster runs
  • 📈 Comprehensive Stats - Detailed summary at the end of each scan

FOXss is an automation framework; the external tools do the heavy lifting.

Quick Start

# Install
git clone https://github.com/caneraktas1337/foxss.git
cd foxss
pip install .
# Uninstall

sudo pip uninstall -y foxss 2>/dev/null; sudo pip3 uninstall -y foxss 2>/dev/null; sudo python3 -m pip uninstall -y foxss 2>/dev/null; sudo rm -f $(command -v foxss 2>/dev/null); sudo find / -iname "*foxss*" -exec rm -rf {} + 2>/dev/null
# Run
foxss scan example.com
# Open report
xdg-open recon_example.com/xss_report.html 2>/dev/null || open recon_example.com/xss_report.html

Installation

Requirements

  • Python: >= 3.8
  • Go: recommended (for installing/maintaining Go-based recon tools)
  • OS: Linux/macOS recommended

Install FOXss

pip install .

Developer / editable mode

pip install -e .

Auto-install missing tools

FOXss can attempt to install missing tools via Go:

foxss --install-deps

Note: this relies on go install ...@latest and expects a working Go environment.

External Tools

FOXss expects these tools to exist in your $PATH:

Category Tool Purpose
Subdomain subfinder subdomain discovery
Subdomain samoscout extra discovery
Probing httpx live subdomain probing
Crawling katana crawling + endpoints
URLs gau historical URLs
URLs waybackurls Wayback URLs
URLs urlfinder passive URL discovery (scope-aware)
Runtime curl JS fetch (range-limited)

Optional: add dalfox in your workflow to validate findings on xss_candidates.txt / xss_endpoints.txt.

Usage

Basic Scan

foxss scan example.com

Advanced Options

# Verbose mode with custom output directory
foxss scan example.com -v -o my_scan

# Burp Suite integration (proxy)
foxss scan example.com -p http://127.0.0.1:8080

# Silent mode with JSON export
foxss scan example.com -s -j

# Continue previous scan
foxss scan example.com -c

# Exclude certain URL patterns
foxss scan example.com -e ".*\.pdf,.*admin.*"

# Fast scan (skip JS analysis)
foxss scan example.com --skip-js

# Custom threads and timeout
foxss scan example.com -t 50 --timeout 30

# API-only scan
foxss scan example.com -i ".*/api/.*"

All Available Options

Usage: foxss scan <target> [OPTIONS]

OUTPUT OPTIONS:
  -o, --output DIR      Custom output directory (default: recon_<target>)
  -j, --json            Export results to JSON format

SCANNING OPTIONS:
  -v, --verbose         Enable verbose/debug output
  -s, --silent          Silent mode (minimal output)
  -c, --continue        Continue previous scan (resume)

FILTERING OPTIONS:
  -e, --exclude REGEX   Exclude URL patterns (comma-separated)
  -i, --include REGEX   Include only URL patterns (comma-separated)

NETWORK OPTIONS:
  -p, --proxy URL       HTTP proxy (e.g., http://127.0.0.1:8080)
  -t, --threads NUM     Override default thread count
  --timeout SEC         Override default timeout (seconds)

ADVANCED OPTIONS:
  --skip-crawling       Skip URL crawling phase
  --skip-js             Skip JavaScript analysis
  --only-new            Only scan new URLs/subdomains

GLOBAL OPTIONS:
  -h, --help            Show this help message
  --install-deps        Auto-install missing tools

Complete Usage Examples

Bug Bounty Workflow:

# 1. Initial discovery
foxss scan target.com -o initial_scan

# 2. Deep analysis with Burp
foxss scan target.com -v -p http://127.0.0.1:8080 -o deep_scan

# 3. Continue if interrupted
foxss scan target.com -c

# 4. Export for reporting
foxss scan target.com -j -o final_report

CI/CD Pipeline:

foxss scan target.com -s -j --skip-js -o /builds/results

Quick Recon:

foxss scan target.com -s --skip-js

Output

FOXss creates a workspace per target:

recon_example.com/
├── subdomains.txt              # discovered subdomains
├── active_subdomains.txt       # live subdomains (httpx probed)
├── urls.txt                    # collected URLs
├── urls_filtered.txt           # filtered URLs (non-static)
├── new_urls.txt                # new URLs (not in history)
├── endpoints.txt               # unique endpoints (no query)
├── endpoint_paths.txt          # unique paths
├── xss_candidates.txt          # URLs with query strings ⭐
├── active_urls.txt             # active/live URLs (curl probed)
├── active_urls_status.txt      # URLs with status codes
├── xss_endpoints.txt           # endpoint patterns (FUZZ placeholders)
├── xss_endpoints_qs.txt        # endpoints with query strings
├── xss_endpoints_new.txt       # new endpoint patterns
├── xss_high_risk.txt           # high-risk XSS candidates ⭐
├── xss_parameters.txt          # unique parameter names
├── js_urls.txt                 # JavaScript files
├── js_endpoints.txt            # endpoints extracted from JS
├── js_xss_candidates.txt       # XSS candidates from JS ⭐
├── js_sinks.txt                # DOM XSS sinks found ⭐
├── js_secrets.txt              # secrets/tokens found ⭐
├── hidden_params.txt           # hidden parameter candidates
├── xss_reflections.txt         # reflection test results ⭐
├── xss_report.html             # HTML report (shareable) 📊
├── scan_results.json           # JSON export (with -j flag) 📊
└── tmp/                        # temporary files

Priority Files (Start Here ⭐)

  1. xss_high_risk.txt → High-impact parameter patterns
  2. xss_candidates.txt → Best starting point for XSS testing
  3. js_xss_candidates.txt → XSS candidates from JavaScript
  4. js_sinks.txt → Potential DOM XSS vulnerabilities
  5. xss_reflections.txt → URLs where input is reflected
  6. xss_report.html → Visual overview of all findings

JSON Export Structure

When using -j or --json flag, a scan_results.json file is created:

{
  "scan_info": {
    "target": "example.com",
    "scan_date": "2025-12-21 14:30:00",
    "output_directory": "recon_example.com"
  },
  "statistics": {
    "subdomains": 1234,
    "active_subdomains": 567,
    "urls_total": 45678,
    "xss_candidates": 234,
    "js_sinks": 12
  },
  "files": {
    "xss_candidates": "path/to/xss_candidates.txt",
    "html_report": "path/to/xss_report.html"
  },
  "results": {
    "high_risk_xss": [...],
    "js_sinks": [...],
    "js_secrets": [...]
  }
}

Configuration (Environment Variables)

FOXss is configurable via environment variables:

Performance / concurrency

Variable Default Description
PARALLEL_JOBS 12 parallel URL checks / curl jobs
FOXSS_HTTPX_THREADS 60 httpx threads
FOXSS_HTTPX_SUB_CHUNK 5000 lines per chunk when probing subdomains
FOXSS_HTTPX_TIMEOUT 7 httpx timeout (seconds)
FOXSS_HTTPX_RETRIES 2 httpx retries
FOXSS_KATANA_WORKERS 3 katana concurrent workers per host
FOXSS_KATANA_DEPTH 4 katana crawl depth
FOXSS_GAU_WORKERS 6 gau concurrent workers
FOXSS_GAU_TIMEOUT 60 gau timeout (seconds)
FOXSS_WAYBACK_WORKERS 6 wayback concurrent workers
FOXSS_WAYBACK_TIMEOUT 60 wayback timeout (seconds)
FOXSS_URLFINDER_WORKERS 6 urlfinder concurrent workers
FOXSS_URLFINDER_TIMEOUT 20 urlfinder timeout (seconds)

JS analysis limits

Variable Default Description
JS_MAX_FILES 120 max JS files to download/analyze
HVT_MAX_URLS 80 max "high-value target" URLs considered

Headers / evasion

Variable Default Description
FOXSS_UA random preset custom User-Agent
FOXSS_XFF random IP custom X-Forwarded-For
FOXSS_PROXY none HTTP proxy URL

Output control

Variable Description
FOXSS_VERBOSE Enable verbose/debug output (0/1)
FOXSS_SILENT Enable silent mode (0/1)
NO_COLOR Disable colored output

Blind XSS integration (optional)

Variable Description
BLIND_XSS_DOMAIN your blind XSS domain
COLLAB_DOMAIN alias/alternative var

Examples

High-performance scan:

export FOXSS_HTTPX_THREADS=80
export FOXSS_KATANA_WORKERS=8
export PARALLEL_JOBS=30
foxss scan example.com

Conservative scan (slow targets):

export FOXSS_HTTPX_THREADS=20
export FOXSS_HTTPX_TIMEOUT=15
export FOXSS_KATANA_WORKERS=2
foxss scan example.com

With proxy:

export FOXSS_PROXY=http://127.0.0.1:8080
foxss scan example.com

Screenshots

1 2

Troubleshooting

1) httpx slows down / crashes on huge lists

  • Reduce threads: 
    export FOXSS_HTTPX_THREADS=20
  • Reduce chunk size: 
    export FOXSS_HTTPX_SUB_CHUNK=1500
  • Keep output directory on a local SSD (avoid slow network drives).

2) urlfinder returns few/no results

  • Some programs block passive collectors; rely more on katana + gau + waybackurls.
  • Lower urlfinder chunk size: 
    export FOXSS_URLFINDER_CHUNK=10

3) Report looks unstyled / "plain HTML"

FOXss embeds inline CSS/JS into xss_report.html. If it looks unstyled:

  • ensure the scan finished cleanly (report not truncated)
  • open with a browser, not a text viewer

4) Too many URLs / noisy output

Start from:

  • xss_candidates.txt
  • xss_high_risk.txt
  • js_xss_candidates.txt

Contributing

PRs/issues are welcome.

When opening an issue, please include:

  • tool versions (httpx -version, katana -version, etc.)
  • a small sample of problematic input/output
  • OS + Python version

Legal / Responsible Use

Use FOXss only on targets you own or where you have explicit permission.
You are responsible for following program rules and applicable laws.

License

See LICENSE.

Author

Caner Aktaş
X (Twitter): @caneraktas_
GitHub: @caneraktas1337

Links

🦊 FOXss v1.0.0 - Hunt smart. Ship clean reports.

Made with ❤️ for the bug bounty community

About

XSS Recon Framework

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages