BugAI - Modular Bug Hunting Framework

A professional-grade, modular, high-performance bug hunting framework for penetration testers and bug bounty hunters.

🎯 Features

• Modular Pipeline Engine - Independent, skipable stages with parallel execution
• Structured Data Flow - Central ScanContext object replaces file-based passing
• Intelligent Prioritization - Score targets based on patterns, parameters, and sensitive paths
• Advanced Filtering - Categorize URLs into XSS, SQLi, Redirect, and IDOR candidates
• JavaScript Analysis - Extract endpoints and secrets from JS files
• Targeted Testing - Run tools only on relevant data
• Multiple Scan Modes - Quick, Full, and Recon-only scans
• Enhanced Reporting - JSON, HTML reports with hacker-oriented CLI summary

📁 Project Structure

bugai/
├── cli/                          # CLI entry points
│   ├── bugai_cli.py              # Standalone CLI
│   └── bugai_ui.py               # Interactive UI
├── core/                         # Core framework
│   ├── pipeline.py               # Pipeline orchestrator
│   ├── context.py                 # ScanContext (structured state)
│   ├── config.py                 # Config loader
│   ├── analyzer.py               # Risk scoring
│   ├── prioritizer.py            # Target prioritization
│   ├── tools/                    # Tool execution
│   │   ├── runner.py             # Timeout, retry, logging
│   │   └── registry.py           # Tool registry
│   └── stages/                   # Pipeline stages
│       ├── recon.py               # Subdomain enumeration
│       ├── live_hosts.py          # Live host detection
│       ├── url_collection.py      # URL gathering
│       ├── js_analysis.py         # JS endpoint extraction
│       ├── param_discovery.py     # Parameter extraction
│       ├── filtering.py           # URL categorization
│       ├── vuln_testing.py        # Vulnerability scanning
│       ├── infra_scan.py          # Port scanning
│       └── reporting.py           # Report generation
├── reports/                      # Output directory
├── config.yaml                   # Configuration file
└── bugai                         # Launcher script

🚀 Quick Start

Installation

# Clone the repository
cd bugai

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install security tools (optional - BugAI will detect available tools)
./bugai

Basic Usage

# Interactive UI
./bugai

# CLI scan (full mode)
./bugai --cli example.com

# Quick scan (skip slow tools)
./bugai --cli example.com -m quick

# Recon only
./bugai --cli example.com -m recon_only

# Save results
./bugai --cli example.com -o results.json

Scan Modes

1. Full Scan - Runs all stages and tools
2. Quick Scan - Skips amass and nmap for faster results
3. Recon Only - Discovery only, no vulnerability testing

⚙️ Configuration

Edit config.yaml to customize:

• Threads: Number of parallel workers
• Timeouts: Per-tool timeout values
• Tool arguments: Customize how tools are invoked
• Filtering patterns: Define what makes a URL a candidate
• Prioritization rules: Define high/medium/low patterns

🔧 Integrated Tools

BugAI integrates 16 security tools:

• Recon: subfinder, amass
• Live Hosts: httpx
• URL Collection: gau, katana, waybackurls
• Parameters: paramspider
• Vulnerabilities: nuclei, sqlmap, dalfox
• Infrastructure: nmap
• Specialized: testssl.sh, corsy, linkfinder, secretfinder, ffuf

📊 Output

BugAI generates:

1. JSON Report - Machine-readable results
2. HTML Report - Human-readable web report
3. CLI Summary - Hacker-oriented terminal output with:
   • High-priority targets
   • Suggested manual tests
   • Vulnerability summary
   • Statistics

🎯 Pipeline Stages

1. Recon → Subdomain enumeration
2. Live Hosts → Filter alive web servers
3. URL Collection → Gather endpoints
4. JS Analysis → Extract JS endpoints/secrets
5. Param Discovery → Extract URL parameters
6. Filtering → Categorize URLs
7. Prioritization → Score and prioritize
8. Vuln Testing → Targeted vulnerability scans
9. Infra Scan → Port scanning
10. Reporting → Generate reports

💡 Tips

• Use quick mode for initial reconnaissance
• Review high-priority targets for manual testing
• Customize config.yaml to enable/disable specific tools
• Check tool status in the interactive UI
• Use saved JSON files to resume analysis

📝 License

MIT License

⚠️ Disclaimer

Use only on targets you have permission to test. The authors are not responsible for misuse.