⚔️ BEATRIX CLI — The Black Mamba

"Revenge is a dish best served with a working PoC."

License: Source Available — Free for non-commercial use. Commercial use requires a separate license. See LICENSE.

A command-line bug bounty hunting framework. 32 scanner modules, 13 external tool integrations, full OWASP Top 10 coverage, 7-phase Kill Chain methodology, and AI-assisted analysis — all from your terminal. Targets can be domains, URLs, or raw IP addresses.

Globally installable on any Linux system. Call it from anywhere.

---

<img src="beatrix.gif" width="1920" alt="Demo GIF">

---

📖 The Manual

Beatrix ships with an interactive, comprehensive HTML manual covering every command, every module, all flags, presets, and real-world workflows:

beatrix manual

This opens the full manual in your default browser — no internet required. You can also open it directly at docs/manual/index.html.

---

Install (One Command)

git clone https://github.com/SudoPacman-Syuu/Beatrix.git && cd Beatrix && ./install.sh

That's it. The installer auto-detects your Python, picks the best install method, puts beatrix on your PATH, and automatically installs all 21 external security tools (nuclei, nmap, sqlmap, subfinder, ffuf, etc.).

Install Method Priority

The installer automatically selects the best method in this order:

1. uv (fastest, recommended) — auto-installed if missing
2. venv — Python built-in virtual environment at ~/.beatrix
3. pipx — isolated app install
4. pip --user — user-level fallback

# Using make
git clone https://github.com/SudoPacman-Syuu/Beatrix.git && cd Beatrix
make install

# Using uv directly
uv tool install .

# Using pipx
pipx install .

# Dedicated venv + symlink to /usr/local/bin
make install-venv

# For development
make install-dev

Customize the venv location: BEATRIX_VENV=~/my-venv ./install.sh

Uninstall

./uninstall.sh        # or: make uninstall

---

Quick Start

beatrix                              # show all commands
beatrix hunt example.com             # scan a domain
beatrix hunt 192.168.1.1             # scan an IP address
beatrix hunt -f targets.txt          # hunt all URLs from a file
beatrix strike api.com -m cors       # single module attack
beatrix help hunt                    # detailed command help
beatrix arsenal                      # full module reference

---

The Death List — Command Reference

| Command | Description | Example | |---------|-------------|---------| | hunt TARGET | Full vulnerability scan | beatrix hunt example.com or beatrix hunt 10.0.0.1 | | hunt -f FILE | Hunt targets from file | beatrix hunt -f targets.txt | | strike TARGET -m MOD | Single module attack | beatrix strike api.com -m cors | | probe TARGET | Quick alive check | beatrix probe example.com | | recon DOMAIN | Reconnaissance | beatrix recon example.com --deep | | batch FILE -m MOD | Mass scanning | beatrix batch targets.txt -m cors | | bounty-hunt TARGET | OWASP Top 10 pipeline | beatrix bounty-hunt https://api.com | | rapid | Multi-target quick sweep | beatrix rapid -d example.com | | haiku-hunt TARGET | AI-assisted hunting | beatrix haiku-hunt example.com | | ghost TARGET | AI autonomous pentester | beatrix ghost https://api.com | | github-recon ORG | GitHub secret scanner | beatrix github-recon acme-corp | | validate FILE | Validate findings | beatrix validate report.json | | mobile [sub] | Mobile traffic intercept | beatrix mobile intercept | | browser [sub] | Playwright browser scanning | beatrix browser scan https://app.com | | creds [sub] | Credential validation | beatrix creds validate jwt_secret TOKEN | | origin-ip DOMAIN | Origin IP behind CDN | beatrix origin-ip example.com | | inject TARGET | Deep parameter injection | beatrix inject https://api.com --deep | | polyglot [sub] | XSS polyglot generation | beatrix polyglot generate | | auth [sub] | Auth & auto-login | beatrix auth login example.com | | auth browser TARGET | Manual browser login | beatrix auth browser example.com | | auth sessions | Manage saved sessions | beatrix auth sessions --clear example.com | | config | Configuration | beatrix config --show | | list | List modules/presets | beatrix list --modules | | arsenal | Full module reference | beatrix arsenal | | help CMD | Detailed command help | beatrix help hunt | | manual | Open HTML manual in browser | beatrix manual | | setup | Install all external tools | beatrix setup |

---

Requirements

• Python 3.11+ (the installer checks this for you)
• Linux (Debian, Ubuntu, Fedora, Arch, etc.)
• 21 external tools are automatically installed by ./install.sh and beatrix setup

All external tools are installed automatically during setup. To reinstall or update them later:

beatrix setup            # install all missing tools
beatrix setup --check    # just show what's installed

Verify installation

beatrix --version
beatrix list --modules

---

Core Concepts

The Kill Chain

Every hunt follows the Cyber Kill Chain methodology:

1. 🛡️ CDN Bypass — Detects Cloudflare/Akamai/Fastly/CloudFront/Sucuri/Incapsula/PerimeterX/DataDome/Kasada via IP range + header fingerprinting. Discovers origin IPs through 6+ techniques (DNS history, crt.sh SSL certs, MX records, subdomain correlation, misconfiguration checks, WHOIS). If origin found, all network scans target the real server instead of CDN edge. Optional API keys (SecurityTrails, Censys, Shodan) via environment variables.
2. 🔍 Reconnaissance — Subdomain enum (subfinder, amass), crawling (katana, gospider, hakrawler, gau), full 65535-port TCP scan (nmap -sS -p-) against origin IP when available, service fingerprinting, NSE vuln/discovery/auth scripts, UDP top-50 scan, firewall fingerprinting + bypass testing (scapy), SSH deep audit (paramiko), JS analysis, endpoint probing, tech fingerprinting (whatweb, webanalyze), nuclei recon (fast tech/panel/WAF detection), nuclei network (protocol checks on non-HTTP services)
3. ⚔️ Weaponization — Subdomain takeover, error disclosure, cache poisoning, prototype pollution
4. 📦 Delivery — CORS, open redirects, OAuth redirect, HTTP smuggling, WebSocket testing
5. 💥 Exploitation — Injection (SQLi/XSS/CMDi) with response_analyzer behavioral detection and WAF bypass fallback (11 WAF profiles, profile-aware 3-strategy retry with adaptive learning), SSRF, IDOR, BAC, auth bypass, SSTI, XXE, deserialization, GraphQL, mass assignment, business logic, ReDoS, payment, nuclei exploit scan (CVEs, workflows, authenticated, interactsh OOB, WAF bypass: realistic UA, CDN-aware rate limiting, origin IP rewrite with TLS SNI), nuclei headless (DOM XSS, prototype pollution). SmartFuzzer runs ffuf-verified fuzzing with profile-targeted WAF encoding on parameterized URLs. Confirmed findings are escalated to deep exploitation tools (sqlmap, dalfox, commix, jwt_tool)
6. 🔧 Installation — File upload bypass, polyglot uploads, path traversal
7. 📡 Command & Control — OOB callback correlation via built-in PoCServer (pure asyncio HTTP server, auto-binds free port) or external interact.sh. Blind SSRF/XXE/RCE confirmation from callbacks registered during Phase 4. LocalPoCClient provides offset-based dedup polling.
8. 🎯 Objectives — VRT classification (Bugcrowd VRT + CVSS 3.1), exploit chain generation via PoCChainEngine (correlates ≥2 findings), finding aggregation, deduplication, impact assessment

Presets

| Preset | Description | Time | |--------|-------------|------| | quick | Surface scan, recon only | ~5 min | | standard | Balanced scan (default) | ~15 min | | full | Complete kill chain + full network recon | ~45–60 min | | stealth | Low-noise passive recon | ~10 min | | injection | Injection-focused testing | ~20 min | | api | API security testing | ~15 min |

beatrix hunt example.com --preset full
beatrix hunt example.com --preset injection

IP Address Targets

Beatrix fully supports scanning raw IP addresses (IPv4 and IPv6). When an IP target is detected, domain-only operations are automatically skipped:

• Skipped: Subdomain enumeration (subfinder, amass, crt.sh), origin IP discovery, GitHub recon, subdomain takeover checks
• Active: All HTTP-based scanners (injection, CORS, SSRF, IDOR, XXE, etc.), port scanning, service detection, firewall testing

# Scan a single IP
beatrix hunt 192.168.1.1

# Scan with full preset (includes nmap, SSH audit, firewall testing)
beatrix hunt 10.0.0.1 --preset full

# Strike a specific service on an IP
beatrix strike http://192.168.1.1:8080/api -m injection

# IP addresses also work in target files
echo "192.168.1.1
10.0.0.2
https://172.16.0.1:443" > targets.txt
beatrix hunt -f targets.txt

Scanner Modules (Arsenal)

Run beatrix arsenal for the full table. 32 registered modules across 5 kill chain phases:

Phase 1 — Reconnaissance:

| Module | What It Does | |--------|-------------| | origin_ip | CDN detection (Cloudflare/Akamai/Fastly/CloudFront/Sucuri/Incapsula/PerimeterX/DataDome/Kasada) + origin IP discovery via DNS history, SSL certs, MX records, subdomain correlation, misconfig checks | | crawl | Depth-limited spider with soft-404 detection, form/param extraction | | endpoint_prober | Probes 200+ common API/admin/debug paths | | js_analysis | Extracts API routes, secrets, source maps from JS bundles | | headers | CSP, HSTS, X-Frame-Options, security header analysis | | github_recon | GitHub org secret scanning, git history analysis | | nmap_nse | Full TCP 65535-port scan, service ID, NSE vuln/discovery/auth scripts, UDP top-50 | | ssh_auditor | SSH server fingerprint, weak KEX/cipher/MAC,