# Bug Bounty MCP Server

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

## 🚀 Quick Start

```bash
# 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

```bash
# 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

```python
# 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](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](CONTRIBUTING.md) for guidelines.

## 📄 License

MIT License - see [LICENSE](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**