SETUP.md•6.71 kB
# 🔧 MCPPentestBOT - Quick Setup Guide
Get MCPPentestBOT up and running in minutes with this streamlined setup guide.
---
## 📋 Prerequisites
### Required Software
- **Python 3.8+** - [Download](https://www.python.org/downloads/)
- **Security Tools**: nmap, nikto, openssl
- **LLM API Key**: Azure OpenAI, Claude, or GitHub Copilot
### Platform-Specific Requirements
- **Windows**: WSL (Windows Subsystem for Linux)
- **Linux/macOS**: Native terminal
---
## 🚀 Quick Installation
### Step 1: Install Python
**Verify Python Installation:**
```bash
python --version # Should be 3.8 or higher
```
**Install if needed:**
- **Windows**: [python.org](https://www.python.org/downloads/) (✅ Check "Add to PATH")
- **macOS**: `brew install python3`
- **Linux**: `sudo apt install python3 python3-pip`
---
### Step 2: Install WSL (Windows Only)
**Open PowerShell as Administrator:**
```powershell
wsl --install
```
**After restart, open Ubuntu from Start Menu and complete setup.**
---
### Step 3: Install Security Tools
**Windows (in WSL):**
```bash
wsl
sudo apt update
sudo apt install -y nmap nikto openssl
exit
```
**macOS:**
```bash
brew install nmap nikto openssl
```
**Linux:**
```bash
sudo apt update
sudo apt install -y nmap nikto openssl
```
**Verify Installation:**
```bash
nmap --version
nikto -Version
openssl version
```
---
### Step 4: Clone & Setup Project
```bash
# Clone repository
git clone https://github.com/yourusername/MCPPentestBOT.git
cd MCPPentestBOT
# Create virtual environment (recommended)
python -m venv venv
# Activate virtual environment
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
```
---
### Step 5: Configure LLM Provider
**Create `config.py` from template:**
```bash
cp config.example.py config.py
```
**Edit `config.py` with your credentials:**
**Option A: Azure OpenAI**
```python
AZURE_CONFIG = {
"api_key": "your-api-key-here",
"endpoint": "https://your-resource.openai.azure.com/",
"api_version": "2024-02-15-preview",
"deployment_name": "gpt-4"
}
LLM_PROVIDER = "azure"
```
**Option B: Claude (Anthropic)**
```python
CLAUDE_CONFIG = {
"api_key": "your-claude-api-key",
"model": "claude-3-5-sonnet-20241022"
}
LLM_PROVIDER = "claude"
```
**Option C: GitHub Copilot**
```python
COPILOT_CONFIG = {
"api_key": "your-github-token",
"base_url": "https://api.githubcopilot.com",
"model": "gpt-4"
}
LLM_PROVIDER = "copilot"
```
---
### Step 6: First Run
```bash
python llm_client.py
```
**Expected Output:**
```
═══════════════════════════════════════════════════════
🛡️ MCPPentestBOT - Professional Security Analysis
═══════════════════════════════════════════════════════
✅ Loaded 6 security tools
💬 Ready for security analysis!
👤 You:
```
**Test with:**
```
Check SSL certificate for github.com
```
---
## 🐛 Quick Troubleshooting
### Issue: "Azure OpenAI initialization failed"
**Fix:** Check `config.py` credentials and ensure endpoint ends with `/`
### Issue: "nmap: command not found"
**Fix:** Install tools in WSL (Windows) or your system:
```bash
wsl sudo apt install -y nmap nikto openssl # Windows
```
### Issue: "ModuleNotFoundError: No module named 'openai'"
**Fix:** Install dependencies:
```bash
pip install -r requirements.txt
```
### Issue: Tool execution fails
**Fix:** Test tool manually:
```bash
wsl nmap -F github.com # Windows
nmap -F github.com # Linux/macOS
```
### Issue: Permission denied
**Fix:** Some scans need elevated privileges:
```bash
sudo python llm_client.py # Use with caution
```
---
## 📂 Project Structure
```
MCPPentestBOT/
├── llm_client.py # Main application
├── config.py # Your LLM credentials (create this)
├── config.example.py # Configuration template
├── requirements.txt # Python dependencies
├── tools/ # Security tool implementations
│ ├── nmap_scan.py
│ ├── ssl_check.py
│ ├── nikto_scan.py
│ ├── http_headers.py
│ ├── ping_sweep.py
│ └── port_check.py
└── README.md # Project overview
```
---
## ✅ Setup Checklist
- [ ] Python 3.8+ installed and in PATH
- [ ] WSL installed (Windows users)
- [ ] Security tools installed (nmap, nikto, openssl)
- [ ] Repository cloned
- [ ] Dependencies installed (`pip install -r requirements.txt`)
- [ ] `config.py` created with valid API credentials
- [ ] Successfully ran `python llm_client.py`
- [ ] Completed test scan
---
## 🎯 Available Commands
Once running, try these commands:
| Command | Description |
|---------|-------------|
| `Check SSL for github.com` | SSL/TLS certificate analysis |
| `Scan ports on example.com` | Port scanning |
| `Check headers for mysite.com` | HTTP security headers |
| `Run Nikto on example.com` | Web vulnerability scan |
| `Find hosts on 192.168.1.0/24` | Network discovery |
| `Is port 443 open on github.com?` | Port connectivity test |
| `help` | Show available commands |
| `quit` | Exit application |
---
## 🔒 Important Security Notes
**⚠️ Legal Requirements:**
- ✅ Only scan systems you own
- ✅ Get written permission for third-party systems
- ✅ Follow responsible disclosure practices
- ❌ Never scan without authorization
**Safe Test Targets:**
- `scanme.nmap.org` - Official nmap test server
- `github.com` - Public HTTPS site
- Your own local servers
---
## 🌟 Quick Tips
1. **Virtual Environment**: Always activate venv before running
```bash
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
```
2. **API Keys**: Never commit `config.py` to Git (already in `.gitignore`)
3. **Faster Scans**: For quick tests, specify port ranges:
```
Scan ports 80,443 on example.com
```
4. **Proxy Setup**: If behind corporate proxy, add to `config.py`:
```python
PROXY = {"http": "http://proxy:8080", "https": "http://proxy:8080"}
```
---
## 📞 Need Help?
- 📖 **Documentation**: [README.md](README.md)
- 🐛 **Issues**: [GitHub Issues](https://github.com/kannanprabu/MCPPentestBOT/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/kannanprabu/MCPPentestBOT/discussions)
---
<div align="center">
**🎉 Setup Complete!**
You're ready to start security testing with AI-powered assistance.
*Always test responsibly and ethically.*
</div>