# 🎯 Bug Bounty Hunter MCP
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
**Professional Bug Bounty Hunter MCP Server** with 50+ integrated security tools for comprehensive web application security testing and bug bounty hunting.
---
## 🚀 Features
### 🔍 Reconnaissance (15 tools)
- **Subdomain Enumeration**: subfinder, amass, assetfinder, DNS bruteforce
- **Port Scanning**: nmap, masscan, naabu integration
- **HTTP Probing**: httpx with technology detection
- **DNS Enumeration**: Comprehensive DNS record queries
- **Technology Detection**: CMS, frameworks, servers
- **Wayback Machine**: Archive URL discovery
- **Certificate Transparency**: Subdomain discovery via CT logs
### 🕷️ Web Crawling & Spidering (3 tools)
- **Web Crawler**: Deep crawling with endpoint extraction
- **JavaScript Analysis**: Extract endpoints and secrets from JS files
- **Parameter Discovery**: Find hidden parameters
### 🔐 Vulnerability Scanning (8 tools)
- **Nuclei**: Template-based vulnerability scanning
- **XSS Scanner**: Reflected, stored, and DOM-based XSS
- **SQL Injection**: Automated SQLi detection with sqlmap
- **SSRF Scanner**: Server-Side Request Forgery testing
- **CORS Misconfiguration**: CORS security testing
### 🧪 Fuzzing & Brute-Force (4 tools)
- **Directory Fuzzing**: ffuf/gobuster integration
- **Parameter Fuzzing**: Hidden parameter discovery
- **Subdomain Bruteforce**: DNS-based subdomain enumeration
- **VHost Fuzzing**: Virtual host discovery
### 📡 API Testing (4 tools)
- **API Discovery**: Automatic endpoint detection
- **Swagger/OpenAPI Parser**: Documentation analysis
- **GraphQL Testing**: Introspection and mutation testing
- **Rate Limit Testing**: API rate limiting analysis
### 💉 Injection Attacks (5 tools)
- **Command Injection**: OS command injection testing
- **XXE Injection**: XML External Entity testing
- **SSTI Scanner**: Server-Side Template Injection
- **LDAP Injection**: LDAP injection testing
- **NoSQL Injection**: MongoDB, CouchDB injection testing
### 🔓 Access Control (3 tools)
- **IDOR Scanner**: Insecure Direct Object Reference testing
- **Path Traversal**: Directory traversal testing
- **LFI/RFI Scanner**: File inclusion vulnerability testing
### 🔑 Authentication & Session (3 tools)
- **JWT Analyzer**: JWT token security analysis
- **Session Analysis**: Session management testing
- **OAuth Tester**: OAuth implementation testing
### ☁️ Cloud Security (3 tools)
- **S3 Bucket Scanner**: AWS S3 security testing
- **Subdomain Takeover**: Takeover vulnerability detection
- **Cloud Metadata**: AWS/Azure/GCP metadata testing
### 📝 Content Discovery (3 tools)
- **Sensitive Files**: Backup and config file discovery
- **Git Exposure**: .git directory enumeration
- **Robots/Sitemap**: robots.txt and sitemap.xml analysis
### 🌐 SSL/TLS (2 tools)
- **SSL/TLS Scanner**: Comprehensive SSL/TLS testing
- **Certificate Transparency**: CT log queries
### 🔧 Automation & Workflows (3 tools)
- **Full Reconnaissance**: Complete recon workflow
- **Web Vulnerability Scan**: Automated web app scanning
- **API Security Test**: Comprehensive API testing
### 📊 Reporting (2 tools)
- **Report Generation**: Professional bug bounty reports (Markdown, HTML, JSON, PDF)
- **Tool Validation**: Check installed security tools
---
## 📊 Total Tools: 50+ MCP Tools
---
## 🛠️ Installation
### Prerequisites
- Python 3.10 or higher
- Kali Linux, ParrotOS, or similar security-focused OS (recommended)
### Quick Install
```bash
# Clone the repository
git clone https://github.com/yourusername/bugbounty-hunter-mcp.git
cd bugbounty-hunter-mcp
# Create virtual environment
python3 -m venv bb_venv
source bb_venv/bin/activate
# Install the package
pip install -e .
```
### Install External Tools (Optional but Recommended)
```bash
# Subdomain enumeration
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/owasp-amass/amass/v4/...@master
go install -v github.com/tomnomnom/assetfinder@latest
# HTTP probing
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
# Port scanning
go install -v github.com/projectdiscovery/naabu/v2/cmd/naabu@latest
# Web crawling
go install -v github.com/jaeles-project/gospider@latest
go install -v github.com/projectdiscovery/katana/cmd/katana@latest
# Fuzzing
go install -v github.com/ffuf/ffuf/v2@latest
go install -v github.com/OJ/gobuster/v3@latest
# Nuclei
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
nuclei -update-templates
# XSS
go install -v github.com/hahwul/dalfox/v2@latest
# SQLMap (usually pre-installed on Kali)
sudo apt install sqlmap
# Parameter discovery
go install -v github.com/s0md3v/Arjun@latest
# JWT
pip install jwt_tool
# Git dumper
pip install git-dumper
```
---
## 🚀 Quick Start
### 1. Basic Setup
```bash
# Activate virtual environment
source bb_venv/bin/activate
# Copy example config
cp .env.example .env
cp config.example.json config.json
# Edit configuration
nano .env
```
### 2. Start MCP Server
```bash
python bug_bounty_mcp.py
```
### 3. Use with Rovo Dev
Add to `~/.rovodev/mcp.json`:
```json
{
"mcpServers": {
"bugbounty": {
"type": "stdio",
"command": "/path/to/bugbounty-hunter-mcp/bb_venv/bin/python",
"args": ["/path/to/bugbounty-hunter-mcp/bug_bounty_mcp.py"],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}
```
---
## 💡 Usage Examples
### Example 1: Full Reconnaissance
```python
# Ask Rovo Dev:
"Run full reconnaissance on example.com"
# This will execute:
full_reconnaissance(
domain="example.com",
deep_scan=False
)
```
### Example 2: Subdomain Enumeration
```python
# Ask Rovo Dev:
"Enumerate subdomains for bugcrowd.com using all tools"
# This will execute:
subdomain_enumeration(
domain="bugcrowd.com",
tools=["subfinder", "amass", "assetfinder"],
passive_only=False
)
```
### Example 3: XSS Testing
```python
# Ask Rovo Dev:
"Test https://example.com/search?q=test for XSS"
# This will execute:
xss_scanner(
url="https://example.com/search?q=test",
parameters=[],
payload_type="all"
)
```
### Example 4: API Security Testing
```python
# Ask Rovo Dev:
"Test the API at https://api.example.com"
# This will execute:
api_security_test(
api_url="https://api.example.com",
documentation_url=""
)
```
### Example 5: Nuclei Vulnerability Scan
```python
# Ask Rovo Dev:
"Run nuclei scan on https://example.com for critical and high severity"
# This will execute:
nuclei_scan(
target="https://example.com",
templates=["all"],
severity=["critical", "high"],
rate_limit=150
)
```
---
## 📋 Tool Categories
### Reconnaissance
```
subdomain_enumeration()
port_scan()
http_probe()
dns_enumeration()
technology_detection()
wayback_urls()
certificate_transparency()
```
### Web Crawling
```
web_crawler()
javascript_analysis()
parameter_discovery()
```
### Vulnerability Scanning
```
nuclei_scan()
xss_scanner()
sql_injection_scan()
ssrf_scanner()
cors_misconfiguration()
```
### Fuzzing
```
directory_fuzzing()
parameter_fuzzing()
subdomain_bruteforce()
vhost_fuzzing()
```
### API Testing
```
api_discovery()
swagger_parser()
graphql_testing()
api_rate_limit_test()
```
### Injection Attacks
```
command_injection_test()
xxe_injection_test()
ssti_scanner()
ldap_injection_test()
nosql_injection_test()
```
### Access Control
```
idor_scanner()
path_traversal_test()
lfi_rfi_scanner()
```
### Authentication
```
jwt_analyzer()
session_analysis()
oauth_tester()
```
### Cloud Security
```
s3_bucket_scanner()
subdomain_takeover_check()
cloud_metadata_test()
```
### Content Discovery
```
sensitive_file_scanner()
git_exposure_scanner()
robots_sitemap_analyzer()
```
### SSL/TLS
```
ssl_tls_scanner()
certificate_transparency()
```
### Automation
```
full_reconnaissance()
web_vulnerability_scan()
api_security_test()
generate_report()
validate_tools()
```
---
## 🔧 Configuration
### Environment Variables (.env)
```bash
# API Keys (optional)
VIRUSTOTAL_API_KEY=your_key
SHODAN_API_KEY=your_key
SECURITYTRAILS_API_KEY=your_key
# Callback URLs for OOB testing
CALLBACK_URL=https://your-server.com/callback
BURP_COLLABORATOR=your-collaborator.burpcollaborator.net
# Rate limiting
DEFAULT_RATE_LIMIT=150
THREADS=50
# Output
OUTPUT_DIR=./results
REPORT_FORMAT=markdown
# Security
DRY_RUN=false
VERBOSE=true
```
### Configuration File (config.json)
```json
{
"recon": {
"subdomain_tools": ["subfinder", "amass", "assetfinder"],
"port_scan_tool": "naabu",
"http_probe_tool": "httpx"
},
"fuzzing": {
"wordlist_dir": "/usr/share/wordlists",
"default_extensions": ["php", "html", "js", "txt"],
"threads": 50
},
"vuln_scan": {
"nuclei_templates": "/root/nuclei-templates",
"severity_filter": ["critical", "high", "medium"]
},
"reporting": {
"format": "markdown",
"include_screenshots": true,
"auto_submit": false
}
}
```
---
## 📚 Documentation
- [Installation Guide](docs/INSTALL.md)
- [Tool Reference](docs/TOOLS.md)
- [Workflow Examples](docs/WORKFLOWS.md)
- [API Documentation](docs/API.md)
- [Contributing Guide](CONTRIBUTING.md)
---
## 🎯 Bug Bounty Workflow
### Phase 1: Reconnaissance
1. `subdomain_enumeration()` - Find all subdomains
2. `certificate_transparency()` - Check CT logs
3. `port_scan()` - Scan for open ports
4. `http_probe()` - Identify live web services
5. `technology_detection()` - Detect technologies
### Phase 2: Content Discovery
6. `web_crawler()` - Crawl the application
7. `directory_fuzzing()` - Find hidden directories
8. `parameter_discovery()` - Discover parameters
9. `wayback_urls()` - Check archived URLs
10. `sensitive_file_scanner()` - Find sensitive files
### Phase 3: Vulnerability Scanning
11. `nuclei_scan()` - Run template-based scans
12. `xss_scanner()` - Test for XSS
13. `sql_injection_scan()` - Test for SQLi
14. `ssrf_scanner()` - Test for SSRF
15. `cors_misconfiguration()` - Check CORS
### Phase 4: Deep Testing
16. `api_discovery()` - Find APIs
17. `graphql_testing()` - Test GraphQL
18. `jwt_analyzer()` - Analyze tokens
19. `idor_scanner()` - Test for IDOR
20. `path_traversal_test()` - Test file access
### Phase 5: Reporting
21. `generate_report()` - Create professional report
---
## 🔒 Security & Ethics
### ⚠️ Important Notice
This tool is designed for:
- **Authorized bug bounty programs**
- **Security assessments with permission**
- **Educational purposes in controlled environments**
**DO NOT:**
- Use on systems without permission
- Violate bug bounty program rules
- Exceed authorized scope
- Cause service disruption
### Responsible Disclosure
Always follow responsible disclosure practices:
1. Report vulnerabilities through proper channels
2. Give vendors time to patch
3. Don't publicly disclose without permission
4. Follow bug bounty program rules
---
## 🤝 Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
### Ways to Contribute
- Add new security tools
- Improve existing tools
- Fix bugs
- Add documentation
- Share workflows
- Report issues
---
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
---
## 🙏 Acknowledgments
Built on top of amazing open-source security tools:
- ProjectDiscovery (subfinder, httpx, nuclei, etc.)
- OWASP (ZAP, Amass)
- sqlmap team
- ffuf, gobuster, and many more
---
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/yourusername/bugbounty-hunter-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/bugbounty-hunter-mcp/discussions)
- **Twitter**: [@yourusername](https://twitter.com/yourusername)
---
## 🎓 Learn More
- [Bug Bounty Platforms](https://github.com/topics/bug-bounty)
- [Web Security Academy](https://portswigger.net/web-security)
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [HackerOne Resources](https://www.hackerone.com/resources)
---
**Made with ❤️ for the bug bounty community**
🎯 Happy Hunting! 🔐