Skip to content

README.md

Latest commit

 

History

History
443 lines (346 loc) · 16.8 KB

README.md

File metadata and controls

443 lines (346 loc) · 16.8 KB

Python AI License Bug Bounty 

   _____ _   _          _____ _      _    _ _    _ _   _ _______ ______ _____
  / ____| \ | |   /\   |_   _| |    | |  | | |  | | \ | |__   __|  ____|  __ \
 | (___ |  \| |  /  \    | | | |    | |__| | |  | |  \| |  | |  | |__  | |__) |
  \___ \| . ` | / /\ \   | | | |    |  __  | |  | | . ` |  | |  |  __| |  _  /
  ____) | |\  |/ ____ \ _| |_| |____| |  | | |__| | |\  |  | |  | |____| | \ \
 |_____/|_| \_/_/    \_\_____|______|_|  |_|\____/|_| \_|  |_|  |______|_|  \_\

🐌 Hunt Smarter, Not Harder 🎯

AI-Powered Bug Bounty Hunting Automation Platform
Let AI do the heavy lifting while you collect the bounties.

Features • Quick Start • Usage • Architecture • Tools

🔥 What is SnailHunter?

SnailHunter is a fully automated bug bounty hunting platform that combines traditional security tools with AI-powered analysis. It orchestrates reconnaissance, discovery, vulnerability scanning, false positive filtering, and generates submission-ready reports.

┌────────────────────────────────────────────────────────────────────────────┐
│                                                                            │
│   TARGET  ──►  RECON  ──►  DISCOVERY  ──►  SCAN  ──►  VALIDATE  ──►  📝   │
│                                                                            │
│   example.com   🔍         🗺️              🎯         🤖           REPORT  │
│                                                                            │
└────────────────────────────────────────────────────────────────────────────┘

Why SnailHunter?

Problem SnailHunter Solution
🔄 Manual tool orchestration Automated 6-stage pipeline
🚨 False positive overload AI-powered FP filtering with confidence scores
📝 Report writing takes forever Auto-generated submission-ready reports
🔗 Missing vulnerability chains AI detects SSRF→RCE, XSS→ATO patterns
⏰ Wasted time on duplicates Smart deduplication and chain detection

✨ Features

🎯 Full Pipeline Automation

# One command. Full scan. Reports generated.
snailhunter scan example.com -p "HackerOne Program"

🤖 AI-Powered Analysis

  • False Positive Filtering - Confidence scoring (0-100%)
  • Vulnerability Chaining - Detects exploitable chains automatically
  • CVSS v3.1 Calculation - With full justification
  • Report Enhancement - Business impact framing

🔧 Tool Integration

Orchestrates best-in-class security tools:

Tool Purpose Status
Nuclei Template-based scanning ✅ Integrated
SQLMap SQL injection ✅ Integrated
Dalfox XSS scanning ✅ Integrated
ffuf Content discovery ✅ Integrated
httpx HTTP probing ✅ Integrated
subfinder Subdomain enum ✅ Integrated

📊 Beautiful CLI Output

┌─────────────────────────────────────────────────────────────────┐
│ 🎯 Hunt Results                                                 │
├─────────────────────────────────────────────────────────────────┤
│ 📊 Statistics                                                   │
│    ├── Duration: 142.3s                                         │
│    ├── Targets scanned: 47                                      │
│    └── Total findings: 12                                       │
│                                                                 │
│ 🔥 Severity Breakdown                                           │
│    ├── Critical: 2                                              │
│    ├── High: 4                                                  │
│    └── Medium: 6                                                │
│                                                                 │
│ ⛓️  Vulnerability Chains                                        │
│    └── Cloud Takeover Chain (critical)                          │
└─────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│ 🎉 NICE! High-value findings detected!                          │
│ Review the reports and prepare your submissions.                 │
└──────────────────────────────────────────────────────────────────┘

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/SnailSploit/TheMothership.git
cd TheMothership

# Install SnailHunter
pip install -e .

# Set up your API key (for AI features)
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY or OPENAI_API_KEY

# Check tool status
snailhunter tools

Install External Tools

# Go-based tools (requires Go 1.21+)
go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
go install github.com/projectdiscovery/httpx/cmd/httpx@latest
go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install github.com/ffuf/ffuf/v2@latest
go install github.com/hahwul/dalfox/v2@latest

# Python tools
pip install sqlmap

First Hunt

# Full automated scan
snailhunter scan bugcrowd-target.com -p "Target Program"

# View results
ls ./output/

📖 Usage

Full Pipeline Scan

# Basic scan
snailhunter scan example.com

# With program name (for report metadata)
snailhunter scan example.com -p "HackerOne - Example"

# Focus on critical/high severity
snailhunter scan example.com --severity critical,high

# With specific Nuclei tags
snailhunter scan example.com --tags cve,rce,sqli

# Passive only (no active scanning)
snailhunter scan example.com --passive-only

# Skip reconnaissance (direct scanning)
snailhunter scan https://api.example.com --skip-recon

# JSON output for scripting
snailhunter scan example.com --json

Individual Stages

# Reconnaissance only
snailhunter recon example.com
snailhunter recon example.com --passive -o recon.json

# Content discovery
snailhunter discover https://example.com
snailhunter discover https://example.com -i thorough

# Validate findings file
snailhunter validate findings.json --threshold 0.7

# Generate report for a finding
snailhunter report FINDING_ID -f hackerone -o report.md

Management Commands

# View configuration
snailhunter config

# Check installed tools
snailhunter tools

# View scan history
snailhunter history -n 20

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              SNAILHUNTER                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────┐   ┌─────────┐   ┌───────────┐   ┌─────────┐   ┌────────────┐  │
│  │  SCOPE  │──►│  RECON  │──►│ DISCOVERY │──►│ SCANNING│──►│ VALIDATION │  │
│  └─────────┘   └─────────┘   └───────────┘   └─────────┘   └────────────┘  │
│       │             │              │              │              │          │
│       ▼             ▼              ▼              ▼              ▼          │
│   Parse scope   Subdomains    Directories    Nuclei        AI FP Filter    │
│   HackerOne     Live hosts    Parameters     SQLMap        Chain detect    │
│   Bugcrowd      Tech stack    API endpoints  Dalfox        CVSS scoring    │
│                                                                    │        │
│                                                                    ▼        │
│                                                            ┌────────────┐   │
│                                                            │ REPORTING  │   │
│                                                            └────────────┘   │
│                                                                    │        │
│                                                                    ▼        │
│                                                            Markdown/JSON    │
│                                                            HackerOne fmt    │
│                                                            Bugcrowd fmt     │
│                                                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│  TOOLS         │  AI PROVIDERS    │  STORAGE       │  OUTPUT               │
│  ───────────   │  ─────────────   │  ───────       │  ──────               │
│  Nuclei        │  Anthropic       │  SQLite        │  Markdown reports     │
│  SQLMap        │  OpenAI          │  JSON files    │  JSON exports         │
│  Dalfox        │  Ollama          │                │  Platform formats     │
│  ffuf          │                  │                │                       │
│  httpx         │                  │                │                       │
│  subfinder     │                  │                │                       │
└─────────────────────────────────────────────────────────────────────────────┘

Pipeline Stages

Stage Description Tools Used
1. Scope Parse program rules, extract targets Custom parser
2. Recon Subdomain enum, live host detection, tech fingerprinting subfinder, httpx
3. Discovery Content discovery, parameter mining, API detection ffuf, custom
4. Scanning Vulnerability scanning with multiple tools nuclei, sqlmap, dalfox
5. Validation AI-powered FP filtering, chain detection, CVSS Claude/GPT
6. Reporting Generate submission-ready reports AI-enhanced

🔧 Configuration

Environment Variables

# LLM Provider (anthropic, openai, ollama)
SNAILHUNTER_LLM_PROVIDER=anthropic

# API Keys
SNAILHUNTER_ANTHROPIC_API_KEY=sk-ant-...
SNAILHUNTER_OPENAI_API_KEY=sk-...

# Model selection
SNAILHUNTER_LLM_MODEL=claude-sonnet-4-20250514

# Rate limiting (requests per second)
SNAILHUNTER_RATE_LIMIT_REQUESTS_PER_SECOND=10

# Database path
SNAILHUNTER_DB_PATH=./data/snailhunter.db

# Logging
SNAILHUNTER_LOG_LEVEL=INFO

Using with Ollama (Local AI)

# Start Ollama
ollama serve

# Pull a model
ollama pull llama3

# Configure SnailHunter
export SNAILHUNTER_LLM_PROVIDER=ollama
export SNAILHUNTER_LLM_MODEL=llama3
export SNAILHUNTER_OLLAMA_BASE_URL=http://localhost:11434

# Run without cloud AI
snailhunter scan example.com

📁 Project Structure

TheMothership/
├── src/snailhunter/
│   ├── cli.py              # 🖥️  CLI with rich output
│   ├── core/
│   │   ├── pipeline.py     # 🔄 Main orchestrator
│   │   ├── config.py       # ⚙️  Settings management
│   │   └── state.py        # 💾 SQLite persistence
│   ├── stages/
│   │   ├── scope.py        # 📋 Scope parsing
│   │   ├── recon.py        # 🔍 Reconnaissance
│   │   ├── discovery.py    # 🗺️  Content discovery
│   │   ├── scanning.py     # 🎯 Vulnerability scanning
│   │   ├── validation.py   # 🤖 AI validation
│   │   └── reporting.py    # 📝 Report generation
│   ├── tools/
│   │   ├── nuclei.py       # Nuclei wrapper
│   │   ├── sqlmap.py       # SQLMap wrapper
│   │   ├── dalfox.py       # Dalfox wrapper
│   │   ├── ffuf.py         # ffuf wrapper
│   │   ├── httpx_tool.py   # httpx wrapper
│   │   └── subfinder.py    # subfinder wrapper
│   ├── ai/
│   │   ├── llm.py          # 🧠 LLM abstraction
│   │   └── prompts/        # 📜 AI prompt templates
│   └── models/
│       ├── finding.py      # Finding dataclass
│       └── target.py       # Target dataclass
├── tests/                  # 🧪 Test suite
├── pyproject.toml          # 📦 Package config
├── .env.example            # 🔐 Environment template
└── CLAUDE.md               # 🤖 AI assistant guide

🎯 Vulnerability Coverage

Web Application

  • SQL Injection (Boolean, Error, Union, Time-based, Stacked)
  • Cross-Site Scripting (Reflected, Stored, DOM-based)
  • Server-Side Request Forgery (SSRF)
  • XML External Entity (XXE)
  • Remote Code Execution (RCE)
  • Local/Remote File Inclusion (LFI/RFI)
  • Insecure Direct Object Reference (IDOR)
  • Open Redirect
  • CORS Misconfiguration
  • Security Misconfigurations

Cloud

  • AWS Metadata SSRF (169.254.169.254)
  • S3 Bucket Misconfigurations
  • Azure Blob Storage Exposure
  • GCP Service Account Leaks

Vulnerability Chains Detected

Chain Pattern
Cloud Takeover SSRF → Metadata → IAM Keys → Full Access
Account Takeover XSS → Cookie Theft → Session Hijack
Privilege Escalation IDOR → Admin Access → User Data
OAuth Bypass Open Redirect → OAuth Flow → Token Theft

🧪 Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src/snailhunter --cov-report=html

# Type checking
mypy src/

# Linting
ruff check src/
ruff format src/

⚠️ Legal & Ethics

SnailHunter is for authorized security testing only.

  • ✅ Only test targets you have explicit permission to test
  • ✅ Respect program scope and exclusions
  • ✅ Follow responsible disclosure practices
  • ✅ Use rate limiting to avoid service disruption
  • ❌ Never test without authorization
  • ❌ Never exceed program scope
  • ❌ Never use for malicious purposes

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing)
  3. Make your changes
  4. Run tests (pytest)
  5. Commit (git commit -m 'Add amazing feature')
  6. Push (git push origin feature/amazing)
  7. Open a Pull Request

📜 License

MIT License - See LICENSE for details.

Built with 🐌 by SnailSploit
Hunt slow, strike fast.