# 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**
