# 🚀 Installation Guide - Bug Bounty Hunter MCP
Complete installation guide for Bug Bounty Hunter MCP.
---
## 📋 Prerequisites
### System Requirements
- **OS**: Linux (Kali, ParrotOS, Ubuntu) or macOS
- **Python**: 3.10 or higher
- **RAM**: 4GB minimum, 8GB recommended
- **Disk Space**: 10GB for tools and wordlists
### Required Skills
- Basic command line knowledge
- Understanding of web security concepts
- Familiarity with bug bounty methodology
---
## 🔧 Installation Methods
### Method 1: Quick Install (Recommended)
```bash
# Clone repository
git clone https://github.com/yourusername/bugbounty-hunter-mcp.git
cd bugbounty-hunter-mcp
# Run installation script
chmod +x install.sh
./install.sh
```
### Method 2: Manual Installation
#### Step 1: Clone Repository
```bash
git clone https://github.com/yourusername/bugbounty-hunter-mcp.git
cd bugbounty-hunter-mcp
```
#### Step 2: Create Virtual Environment
```bash
python3 -m venv bb_venv
source bb_venv/bin/activate # On Linux/Mac
# bb_venv\Scripts\activate # On Windows
```
#### Step 3: Install Python Dependencies
```bash
pip install --upgrade pip
pip install -e .
```
#### Step 4: Configure Environment
```bash
cp .env.example .env
cp config.example.json config.json
# Edit configuration files
nano .env
nano config.json
```
---
## 🛠️ External Tools Installation
The MCP server integrates with many external security tools. Install the ones you need:
### Essential Tools (Highly Recommended)
#### Subdomain Enumeration
```bash
# Subfinder
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
# Amass
go install -v github.com/owasp-amass/amass/v4/...@master
# Assetfinder
go install -v github.com/tomnomnom/assetfinder@latest
```
#### HTTP Probing
```bash
# httpx
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
# httprobe
go install -v github.com/tomnomnom/httprobe@latest
```
#### Port Scanning
```bash
# Naabu
go install -v github.com/projectdiscovery/naabu/v2/cmd/naabu@latest
# Nmap (usually pre-installed on Kali)
sudo apt install nmap
# Masscan (optional)
sudo apt install masscan
```
#### Vulnerability Scanning
```bash
# Nuclei
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
nuclei -update-templates
# Nikto
sudo apt install nikto
# SQLMap
sudo apt install sqlmap
```
### Web Crawling & Content Discovery
```bash
# gospider
go install -v github.com/jaeles-project/gospider@latest
# katana
go install -v github.com/projectdiscovery/katana/cmd/katana@latest
# hakrawler
go install -v github.com/hakluke/hakrawler@latest
# waybackurls
go install -v github.com/tomnomnom/waybackurls@latest
# gau (GetAllUrls)
go install -v github.com/lc/gau/v2/cmd/gau@latest
```
### Fuzzing Tools
```bash
# ffuf
go install -v github.com/ffuf/ffuf/v2@latest
# gobuster
go install -v github.com/OJ/gobuster/v3@latest
# wfuzz
pip install wfuzz
# feroxbuster
cargo install feroxbuster
# Or on Kali: sudo apt install feroxbuster
```
### DNS Tools
```bash
# dnsx
go install -v github.com/projectdiscovery/dnsx/cmd/dnsx@latest
# dnsgen
pip install dnsgen
```
### Parameter Discovery
```bash
# Arjun
pip install arjun
# ParamSpider
git clone https://github.com/devanshbatham/ParamSpider
cd ParamSpider
pip install -r requirements.txt
```
### XSS Tools
```bash
# dalfox
go install -v github.com/hahwul/dalfox/v2@latest
# XSStrike
git clone https://github.com/s0md3v/XSStrike
cd XSStrike
pip install -r requirements.txt
```
### Authentication & JWT
```bash
# jwt_tool
pip install pyjwt
git clone https://github.com/ticarpi/jwt_tool
cd jwt_tool
pip install -r requirements.txt
```
### Cloud Security
```bash
# S3Scanner
pip install s3scanner
# Subjack (subdomain takeover)
go install -v github.com/haccer/subjack@latest
```
### Content Discovery
```bash
# git-dumper
pip install git-dumper
# DotGit
git clone https://github.com/davtur19/DotGit
cd DotGit
pip install -r requirements.txt
```
### SSL/TLS Testing
```bash
# testssl.sh
git clone https://github.com/drwetter/testssl.sh.git
cd testssl.sh
chmod +x testssl.sh
sudo ln -s $(pwd)/testssl.sh /usr/local/bin/testssl.sh
```
### CMS Scanners
```bash
# WPScan (WordPress)
sudo apt install wpscan
# Joomscan (Joomla)
git clone https://github.com/OWASP/joomscan
cd joomscan
perl joomscan.pl --update
```
### Additional Utilities
```bash
# unfurl (URL parsing)
go install -v github.com/tomnomnom/unfurl@latest
# qsreplace (query string replacement)
go install -v github.com/tomnomnom/qsreplace@latest
# anew (append unique lines)
go install -v github.com/tomnomnom/anew@latest
```
---
## 📦 Wordlists Installation
### SecLists (Comprehensive Wordlist Collection)
```bash
sudo apt install seclists
# Or manually:
git clone https://github.com/danielmiessler/SecLists.git /usr/share/wordlists/seclists
```
### Common Wordlist Locations
On Kali Linux, wordlists are typically in:
- `/usr/share/wordlists/`
- `/usr/share/seclists/`
- `/usr/share/dirb/wordlists/`
- `/usr/share/dirbuster/wordlists/`
Update `.env` file with your wordlist paths:
```bash
WORDLIST_DIR=/usr/share/wordlists
SUBDOMAIN_WORDLIST=/usr/share/seclists/Discovery/DNS/subdomains-top1million-5000.txt
DIRECTORY_WORDLIST=/usr/share/wordlists/dirb/common.txt
```
---
## 🎯 Go Environment Setup
Many tools require Go. If you don't have it:
```bash
# Download and install Go
wget https://go.dev/dl/go1.21.5.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.5.linux-amd64.tar.gz
# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH=$PATH:/usr/local/go/bin
export PATH=$PATH:$(go env GOPATH)/bin
# Reload shell
source ~/.bashrc # or source ~/.zshrc
```
---
## 🔐 API Keys Configuration (Optional)
Some features require API keys. Add them to `.env`:
```bash
# VirusTotal
VIRUSTOTAL_API_KEY=your_key_here
# Shodan
SHODAN_API_KEY=your_key_here
# SecurityTrails
SECURITYTRAILS_API_KEY=your_key_here
# Censys
CENSYS_API_ID=your_id
CENSYS_API_SECRET=your_secret
```
Get API keys from:
- **VirusTotal**: https://www.virustotal.com/gui/join-us
- **Shodan**: https://account.shodan.io/register
- **SecurityTrails**: https://securitytrails.com/
- **Censys**: https://censys.io/register
---
## 🔧 Rovo Dev Integration
### Add to Rovo Dev MCP Configuration
Create or edit `~/.rovodev/mcp.json`:
```json
{
"mcpServers": {
"bugbounty": {
"type": "stdio",
"command": "/full/path/to/bugbounty-hunter-mcp/bb_venv/bin/python",
"args": ["/full/path/to/bugbounty-hunter-mcp/bug_bounty_mcp.py"],
"env": {
"PYTHONUNBUFFERED": "1",
"PYTHONPATH": "/full/path/to/bugbounty-hunter-mcp"
}
}
}
}
```
Replace `/full/path/to/` with your actual path.
---
## ✅ Verification
### Test MCP Server
```bash
cd bugbounty-hunter-mcp
source bb_venv/bin/activate
python bug_bounty_mcp.py
```
### Test Tool Installation
```bash
# From Rovo Dev, ask:
"Validate all bug bounty tools"
# Or run directly:
python -c "
import asyncio
from src.utils.validators import validate_tool_installation
result = asyncio.run(validate_tool_installation())
print(f'Installed: {len(result[\"installed\"])}')
print(f'Missing: {len(result[\"missing\"])}')
"
```
---
## 🐛 Troubleshooting
### Issue: Go tools not found
```bash
# Ensure Go bin is in PATH
echo $PATH | grep go
export PATH=$PATH:$(go env GOPATH)/bin
```
### Issue: Permission denied
```bash
# Make scripts executable
chmod +x bug_bounty_mcp.py
chmod +x install.sh
```
### Issue: Module import errors
```bash
# Reinstall in development mode
pip install -e . --force-reinstall
```
### Issue: Tool X not working
```bash
# Check if tool is installed
which tool_name
# Check tool version
tool_name --version
# Reinstall specific tool
go install -v github.com/path/to/tool@latest
```
---
## 📊 Verify Installation
Run this command to check everything:
```bash
# Create test script
cat > test_installation.sh << 'EOF'
#!/bin/bash
echo "=== Bug Bounty Hunter MCP - Installation Check ==="
echo ""
echo "✓ Python Version:"
python3 --version
echo ""
echo "✓ Virtual Environment:"
which python
echo ""
echo "✓ Essential Tools:"
for tool in subfinder httpx naabu nuclei ffuf; do
if command -v $tool &> /dev/null; then
echo " ✓ $tool: $(which $tool)"
else
echo " ✗ $tool: NOT FOUND"
fi
done
echo ""
echo "✓ Python Packages:"
pip list | grep -E "fastmcp|httpx|pydantic"
echo ""
echo "✓ Configuration Files:"
ls -la .env config.json 2>/dev/null || echo " ✗ Configuration files missing"
echo ""
echo "=== Installation Check Complete ==="
EOF
chmod +x test_installation.sh
./test_installation.sh
```
---
## 🎓 Next Steps
1. ✅ Installation complete
2. 📝 Configure `.env` and `config.json`
3. 🔐 Add API keys (optional)
4. 🔗 Integrate with Rovo Dev
5. 🎯 Start hunting bugs!
---
## 📚 Additional Resources
- [Quick Start Guide](README.md#quick-start)
- [Tool Reference](docs/TOOLS.md)
- [Workflow Examples](docs/WORKFLOWS.md)
- [Troubleshooting Guide](docs/TROUBLESHOOTING.md)
---
## 🤝 Need Help?
- **Issues**: [GitHub Issues](https://github.com/yourusername/bugbounty-hunter-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/bugbounty-hunter-mcp/discussions)
- **Documentation**: [Wiki](https://github.com/yourusername/bugbounty-hunter-mcp/wiki)
---
**Installation complete! Happy bug hunting! 🎯🔐**