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