Bug Bounty MCP Server

A comprehensive Model Context Protocol (MCP) server for automated bug bounty hunting and security reconnaissance.

🚀 Quick Start

# Clone and install
git clone https://github.com/akinabudu/bug-bounty-mcp.git
cd bug-bounty-mcp

# Complete installation (dependencies + 25+ security tools)
./setup.sh install

# Start the MCP server
./setup.sh start

✨ Features

• 28+ Security Tools - Comprehensive reconnaissance to vulnerability scanning
• Automated Scope Validation - Never test out-of-scope targets
• Multiple Platforms - HackerOne, Bugcrowd, Intigriti, YesWeHack support
• Intelligent Caching - Avoid duplicate work with smart caching
• Complete Audit Trail - Track all testing activities
• Professional Reports - Generate detailed findings reports
• Traffic Interception - Real-time HTTP/HTTPS traffic analysis with mitmproxy

🛠️ Available Tools

Management (5 tools)

Program management, scope validation, statistics

Reconnaissance (14 tools)

• subdomain_enum - Fast subdomain discovery (subfinder)
• advanced_subdomain_enum - Advanced enumeration (amass)
• web_crawl - Web crawling (gospider + katana)
• network_scan - Fast network scanning (masscan)
• screenshot_recon - Visual reconnaissance (gowitness)
• git_recon - Git repository and secret scanning
• cloud_asset_enum - Cloud asset discovery (AWS/Azure/GCP)
• cert_transparency_search - Certificate transparency logs
• email_harvest - Email harvesting (theHarvester)
• ldap_enum - LDAP/Active Directory enumeration
• api_discovery - API endpoint discovery
• port_scan - Port scanning with nmap
• technology_detection - Web technology detection
• dns_enumeration - DNS record discovery

Vulnerability Scanning (3 tools)

• nuclei_scan - Comprehensive vulnerability scanning
• xss_scan - Cross-Site Scripting detection
• ssl_analysis - SSL/TLS configuration analysis

Fuzzing (2 tools)

• path_fuzzing - Directory and file fuzzing
• parameter_fuzzing - HTTP parameter fuzzing

Traffic Analysis (3 tools) NEW!

• start_traffic_intercept - Start mitmproxy for traffic capture
• analyze_traffic_flows - Analyze captured HTTP/HTTPS traffic
• extract_api_endpoints - Extract API endpoints from traffic

Reporting (3 tools)

• generate_report - Comprehensive reports
• export_findings - Export in multiple formats
• get_statistics - Detailed metrics

📋 Requirements

• Python 3.8+
• Go 1.19+ (for reconnaissance tools)
• Linux/macOS (Ubuntu 20.04+ recommended)
• 4GB+ RAM, 10GB+ disk space

🔧 Installation Options

# Full installation
./setup.sh install

# Install dependencies only
./setup.sh install-deps

# Install reconnaissance tools only  
./setup.sh install-tools

# Setup configuration
./setup.sh setup

# Test installation
./setup.sh test

# Verify tools are working
./setup.sh verify

# Clean temporary files
./setup.sh clean

🎯 Usage Example

# 1. Add bug bounty program
await add_program(
    program_name="Example Corp",
    platform="hackerone", 
    scope_domains=["*.example.com"]
)

# 2. Comprehensive reconnaissance
subdomains = await advanced_subdomain_enum(
    program_id="example",
    domain="example.com",
    mode="passive"
)

# 3. Web application testing
crawl_data = await web_crawl(
    program_id="example",
    url="https://example.com",
    depth=3,
    js_analysis=True
)

# 4. Vulnerability scanning  
vulns = await nuclei_scan(
    program_id="example",
    target="https://example.com"
)

# 5. Generate professional report
report = await generate_report(
    program_id="example",
    scan_ids=["scan1", "scan2"],
    format="markdown"
)

📖 Documentation

For complete documentation, see DOCUMENTATION.md:

• Installation Guide - Detailed setup instructions
• Configuration - Program and tool configuration
• Tool Reference - Complete tool documentation
• Usage Examples - Real-world usage patterns
• Troubleshooting - Common issues and solutions
• Contributing - Development and contribution guide

🔒 Security & Ethics

• Scope Validation: All tools automatically validate targets against program scope
• Rate Limiting: Built-in rate limiting to avoid overwhelming targets
• Audit Logging: Complete audit trail of all testing activities
• Responsible Disclosure: Always follow program rules and responsible disclosure

⚠️ Important: This tool is for authorized security testing only. Always ensure you have proper authorization before testing any targets.

📁 Project Structure

bug-bounty-mcp/
├── src/bugbounty_mcp/     # Main source code
├── config/                # Configuration files
├── data/                  # Nuclei templates, payloads
├── reports/               # Generated reports and findings
├── logs/                  # Audit logs and debugging
├── cache/                 # Cached scan results
├── setup.sh              # Installation and management script
├── DOCUMENTATION.md       # Complete documentation
└── README.md             # This file

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• ProjectDiscovery for excellent Go tools (subfinder, katana, nuclei)
• OWASP Amass team for advanced subdomain enumeration
• Security research community for tool development and feedback

---

Made with ❤️ for the bug bounty community