Bug Bounty MCP Server

# Bug Bounty MCP Server - Complete Documentation ## Table of Contents 1. [Overview](#overview) 2. [Installation](#installation) 3. [Configuration](#configuration) 4. [Available Tools](#available-tools) 5. [Usage Examples](#usage-examples) 6. [Troubleshooting](#troubleshooting) 7. [Contributing](#contributing) ## Overview The Bug Bounty MCP Server is a comprehensive Model Context Protocol (MCP) server designed specifically for bug bounty hunting and security research. It provides 28+ automated reconnaissance and vulnerability assessment tools through a unified interface. ### Key Features - **28+ Security Tools**: Comprehensive coverage from reconnaissance to vulnerability scanning - **Scope Validation**: Automatic target validation against program scope - **Caching System**: Intelligent caching to avoid duplicate work - **Audit Logging**: Complete audit trail of all testing activities - **Multiple Platforms**: Support for HackerOne, Bugcrowd, Intigriti, YesWeHack - **Active & Passive Recon**: Both passive and active reconnaissance capabilities - **Traffic Interception**: Real-time HTTP/HTTPS traffic analysis with mitmproxy ### Architecture ``` Bug Bounty MCP Server ├── Management Tools (5) # Program management, scope validation ├── Reconnaissance (14) # Subdomain enum, port scanning, tech detection ├── Vulnerability Scanning (3) # Nuclei, XSS, SSL analysis ├── Fuzzing Tools (2) # Path and parameter fuzzing ├── Traffic Analysis (3) # Proxy interception, traffic analysis, API extraction └── Reporting (3) # Generate reports, export findings ``` ## Installation ### Prerequisites - Python 3.8+ - Go 1.19+ (for reconnaissance tools) - Linux/macOS (Ubuntu 20.04+ recommended) - 4GB+ RAM, 10GB+ disk space ### Quick Installation ```bash # Clone repository git clone https://github.com/your-org/bug-bounty-mcp.git cd bug-bounty-mcp # Complete installation (dependencies + tools) ./setup.sh install # Start the server ./setup.sh start ``` ### Manual Installation ```bash # 1. Install Python dependencies ./setup.sh install-deps # 2. Install reconnaissance tools ./setup.sh install-tools # 3. Setup configuration ./setup.sh setup # 4. Test installation ./setup.sh test ``` ### Tool Installation Details The installation script automatically installs these tools: **Go Tools:** - Amass (advanced subdomain enumeration) - Subfinder (fast subdomain discovery) - GoSpider (web crawling) - Katana (JavaScript-focused crawling) - GoWitness (web screenshot tool) - truffleHog (secret scanning) **System Tools:** - Masscan (fast port scanner) - requires sudo - LDAP Utils (Active Directory enumeration) - requires sudo - mitmproxy (HTTP/HTTPS traffic interception) - requires pip **Python Tools:** - theHarvester (email harvesting) - cloud_enum (cloud asset discovery) - mitmproxy (proxy and traffic analysis) ## Configuration ### Program Configuration Configure bug bounty programs in `config/programs.yaml`: ```yaml programs: intigriti-showpad: name: "Showpad" platform: "intigriti" scope_domains: - "*.showpad.com" - "*.showpad.biz" scope_ips: [] out_of_scope: [] url: "https://app.intigriti.com/programs/showpad" ``` ### Tool Configuration Configure tool settings in `config/tools.yaml`: ```yaml tools: nuclei: templates_path: "./data/nuclei-templates" rate_limit: 150 subfinder: config_path: "~/.config/subfinder/config.yaml" wordlists: subdomains: "./data/payloads/subdomains.txt" directories: "./data/payloads/directories.txt" ``` ## Available Tools ### Management Tools (5) 1. **add_program** - Add new bug bounty program with scope 2. **list_programs** - List all configured programs 3. **get_program_scope** - Get detailed scope information 4. **validate_target** - Validate if target is in scope 5. **get_statistics** - Get scan statistics and metrics ### Reconnaissance Tools (14) 1. **subdomain_enum** - Basic subdomain enumeration (subfinder) 2. **advanced_subdomain_enum** - Advanced enumeration (amass) 3. **port_scan** - Port scanning with nmap 4. **technology_detection** - Detect web technologies 5. **dns_enumeration** - DNS record enumeration 6. **web_crawl** - Web crawling (gospider + katana) 7. **network_scan** - Fast network scanning (masscan) 8. **api_discovery** - API endpoint discovery 9. **screenshot_recon** - Visual reconnaissance (gowitness) 10. **git_recon** - Git repository discovery and secret scanning 11. **cloud_asset_enum** - Cloud asset enumeration (AWS/Azure/GCP) 12. **cert_transparency_search** - Certificate transparency logs 13. **email_harvest** - Email harvesting (theHarvester) 14. **ldap_enum** - LDAP/Active Directory enumeration ### Vulnerability Scanning Tools (3) 1. **nuclei_scan** - Comprehensive vulnerability scanning 2. **xss_scan** - Cross-Site Scripting detection 3. **ssl_analysis** - SSL/TLS configuration analysis ### Fuzzing Tools (2) 1. **path_fuzzing** - Directory and file fuzzing 2. **parameter_fuzzing** - HTTP parameter fuzzing ### Traffic Analysis Tools (3) 1. **start_traffic_intercept** - Start mitmproxy for HTTP/HTTPS traffic capture 2. **analyze_traffic_flows** - Analyze captured traffic flows and patterns 3. **extract_api_endpoints** - Extract API endpoints from captured traffic ### Reporting Tools (3) 1. **generate_report** - Generate comprehensive reports 2. **export_findings** - Export findings in various formats 3. **get_statistics** - Get detailed statistics ## Usage Examples ### Complete Program Assessment ```python # 1. Add program await add_program( program_name="Example Corp", platform="hackerone", scope_domains=["*.example.com"], url="https://hackerone.com/example" ) # 2. Reconnaissance subdomains = await subdomain_enum(program_id="example", domain="example.com") advanced_subs = await advanced_subdomain_enum(program_id="example", domain="example.com") ports = await port_scan(program_id="example", target="example.com") # 3. Web crawling crawl_results = await web_crawl( program_id="example", url="https://example.com", depth=3, js_analysis=True ) # 4. Vulnerability scanning nuclei_results = await nuclei_scan(program_id="example", target="https://example.com") xss_results = await xss_scan(program_id="example", url="https://example.com") # 5. Generate report report = await generate_report( program_id="example", scan_ids=["scan1", "scan2", "scan3"], format="markdown" ) ``` ### Quick Reconnaissance ```python # Fast subdomain discovery subdomains = await subdomain_enum( program_id="example", domain="example.com", method="all" ) # Technology detection tech = await technology_detection(url="https://example.com") # Screenshot for visual analysis screenshots = await screenshot_recon( program_id="example", urls=["https://example.com", "https://app.example.com"] ) ``` ### Active Reconnaissance ```python # Advanced subdomain enumeration with wordlist advanced_subs = await advanced_subdomain_enum( program_id="example", domain="example.com", mode="active", wordlist="/path/to/wordlist.txt" ) # Fast network scanning network_hosts = await network_scan( program_id="example", cidr="10.0.0.0/24", ports="1-1000", rate=1000 ) # Git repository reconnaissance git_repos = await git_recon( program_id="example", company_name="Example Corp", scan_repos=True ) ``` ### Traffic Analysis and Interception ```python # Start traffic interception with mitmproxy proxy_session = await start_traffic_intercept( program_id="example", listen_host="127.0.0.1", listen_port=8080, mode="regular", save_flows=True ) # Analyze captured traffic traffic_analysis = await analyze_traffic_flows( program_id="example", flow_file="~/.mitmproxy/flows/example_*.mitm", analyze_headers=True, detect_sensitive_data=True ) # Extract API endpoints from traffic api_endpoints = await extract_api_endpoints( program_id="example", flow_file="~/.mitmproxy/flows/example_*.mitm", group_by_path=True ) ``` ## Troubleshooting ### Common Issues **1. Tools not found in PATH** ```bash # Add Go bin to PATH export PATH=$PATH:~/go/bin # Verify tools are installed ./setup.sh verify ``` **2. Permission denied for masscan** ```bash # Masscan requires root privileges sudo apt-get install masscan ``` **3. Import errors** ```bash # Ensure virtual environment is activated source venv/bin/activate # Reinstall dependencies pip install -e . ``` **4. Nuclei templates not found** ```bash # Download nuclei templates nuclei -update-templates ``` ### Performance Optimization **Memory Usage:** - Reduce concurrent scans: Set lower rate limits - Clear cache regularly: `./setup.sh clean` - Use targeted scans instead of broad sweeps **Network Performance:** - Adjust rate limits in tool configuration - Use VPS with good bandwidth for large scans - Enable caching to avoid duplicate work ### Debugging **Enable debug logging:** ```python import logging logging.basicConfig(level=logging.DEBUG) ``` **Check audit logs:** ```bash # View recent activity tail -f logs/audit.log # Check specific program activity grep "program_id:example" logs/audit.log ``` ## Security Considerations ### Scope Validation - All tools automatically validate targets against program scope - Out-of-scope targets are rejected with clear error messages - Wildcard domains are properly handled (*.example.com) ### Rate Limiting - Built-in rate limiting to avoid overwhelming targets - Configurable delays between requests - Respect robots.txt and security.txt ### Data Privacy - Scan results are stored locally only - No data is transmitted to external services (except public APIs) - Audit logs track all testing activities ### Responsible Disclosure - Always follow program rules and scope - Report findings through proper channels - Document and preserve evidence appropriately ## Contributing ### Development Setup ```bash # Clone repository git clone https://github.com/your-org/bug-bounty-mcp.git cd bug-bounty-mcp # Create development environment python3 -m venv dev-env source dev-env/bin/activate pip install -e ".[dev]" # Run tests python -m pytest tests/ # Code formatting black src/ isort src/ ``` ### Adding New Tools 1. **Create tool implementation** in `src/bugbounty_mcp/tools/` 2. **Add parser method** in `src/bugbounty_mcp/utils/parser.py` 3. **Register tool** in `src/bugbounty_mcp/server.py` 4. **Add tests** in `tests/` 5. **Update documentation** ### Code Standards - Follow PEP 8 style guidelines - Include type hints for all functions - Add comprehensive docstrings - Write unit tests for new functionality - Use async/await patterns for I/O operations ### Submitting Changes 1. Fork the repository 2. Create feature branch: `git checkout -b feature-name` 3. Make changes with tests 4. Run code quality checks: `black`, `isort`, `flake8` 5. Submit pull request with detailed description ## License This project is licensed under the MIT License. See LICENSE file 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 --- **Note**: This tool is intended for authorized security testing only. Always ensure you have proper authorization before testing any targets. The authors are not responsible for any misuse of this software.