Blue Whale is a high-performance, autonomous vulnerability finding tool for web-apps. It combines a blazing-fast Go engine with a Python orchestrator to perform deep security auditing, including SPA emulation and privilege escalation testing.

• Blazing Fast Crawling & Fuzzing: High-concurrency Go engine for crawling and differential analysis.
• Advanced Headless Emulation: Playwright integration with stealth plugins to bypass WAFs/Captchas, execute active DOM payloads, and loot client-side storage.
• Dynamic Session Pivoting: Automatically detects leaked session tokens (like JWTs) and spawns isolated, authenticated contexts to test privilege escalation.
• Deep Deserialization & SSRF: Recursive serialization mutation for JSON/GraphQL and dynamic OAST redirects for infrastructure testing (e.g., AWS Metadata extraction).
• Payload Templates: Simple YAML files in engine/templates/ let you easily add new vulnerability patterns.
• WAF Evasion: Applies complex transform chains and automatically rotates User-Agents/headers to stay under the radar.

Note: For a complete breakdown of the system components and data flow, please read the System Architecture Guide.

• Python 3.11+
• Go 1.24+

1. Initialize Python Environment:

   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

2. Setup Playwright (for DOM XSS & Stealth testing):

   playwright install chromium

3. Build the Scanning Engine:

   python main.py bootstrap --force

Fastest way to start scanning a target:

python main.py scan --target http://example.com

• Aggressive: Higher speed and deeper testing.

  python main.py scan -t http://example.com --profile aggressive

• Stealth: Slower speed with randomized delays to bypass WAFs.

  python main.py scan -t http://example.com --profile stealth --evasion-level high

Test for credential stuffing on login forms and track privilege escalation:

python main.py scan -t http://example.com --brute-auth

Provide authorization tokens or session cookies:

python main.py scan -t http://example.com -H "Cookie: session=123"

Blue Whale is for authorized security testing only. Do not use it on systems you do not have explicit permission to test. The author is not responsible for any misuse or damage caused by this tool.