# MCP Kali Pentest - Autonomous Penetration Testing Framework

A comprehensive, AI-powered automated penetration testing framework integrated with LM Studio for autonomous decision-making. This MCP server provides **80+ professional-grade security testing tools** with intelligent automation across 17 specialized categories.

## Features

### 🎯 Autonomous Testing
- AI-powered decision making using LM Studio
- Automatic target reconnaissance
- Intelligent vulnerability prioritization
- Self-guided exploitation path selection
- Continuous learning from findings

### 🛠️ Comprehensive Tool Suite (80+ Tools)

**📡 Reconnaissance & OSINT (11 tools)**
- Nmap, Masscan - Port scanning
- Amass, theHarvester - Subdomain enumeration
- Recon-ng - OSINT framework
- Shodan - IoT device search
- WhatWeb, Wafw00f - Technology fingerprinting

**🌐 Web Application Testing (17 tools)**
- Nikto, Nuclei, WPScan, Joomscan, Droopescan
- Burp Suite Pro API, OWASP ZAP
- SQLMap, Commix, XSStrike - Exploitation
- Gobuster, Dirb, DirBuster, Wfuzz, FFUF

**📻 Wireless Security (5 tools)**
- Aircrack-ng suite, Wifite, Reaver
- Bettercap, Kismet

**🔓 Brute Force & Authentication (6 tools)**
- Hydra, CrackMapExec, Medusa, Patator

**🔐 Password Cracking (4 tools)**
- John the Ripper, Hashcat, Ophcrack

**💥 Exploitation (5 tools)**
- Metasploit Framework, SearchSploit

**👻 Post-Exploitation (6 tools)**
- Mimikatz, BloodHound, PowerShell Empire
- LinPEAS, WinPEAS, CrackMapExec

**🎣 Social Engineering (3 tools)**
- SET, GoPhish, King Phisher

**📱 Mobile Security (4 tools)**
- MobSF, Drozer, Frida

**🔌 API Testing (4 tools)**
- Postman/Newman, GraphQL Scanner

**🔍 Digital Forensics (4 tools)**
- Volatility, Autopsy, Binwalk

**🔬 Reverse Engineering (5 tools)**
- Ghidra, Radare2, IDA Pro

**☁️ Cloud Security (5 tools)**
- Scout Suite, CloudFox, Pacu

**🐳 Container Security (4 tools)**
- Trivy, Docker Bench Security

**🌐 Network Analysis (6 tools)**
- tcpdump, Wireshark, SNMP, enum4linux

**🤖 Autonomous Testing (4 tools)**
- AI-powered pentesting, Smart suggestions

### 🤖 AI-Powered Features
- Automatic scan result analysis
- Intelligent next-step suggestions
- Vulnerability prioritization
- Risk assessment
- Executive report generation
- Custom attack plan creation

### 📊 Professional Reporting
- JSON, HTML, Markdown, and PDF formats
- Executive summaries
- Risk assessments
- Remediation recommendations
- OWASP mapping
- Timeline visualization

## Prerequisites

### System Requirements
- Kali Linux (recommended) or any Debian-based Linux with security tools
- Python 3.9 or higher
- LM Studio (or compatible OpenAI API endpoint)
- Minimum 4GB RAM
- 20GB free disk space

### Required Tools
Most tools come pre-installed on Kali Linux:

```bash
# Verify tools are installed
which nmap nikto sqlmap metasploit gobuster nuclei hydra john hashcat

# Install missing tools
sudo apt update
sudo apt install -y nmap nikto sqlmap metasploit-framework gobuster \
    hydra john hashcat sslscan enum4linux smbclient snmp \
    tcpdump wireshark-cli wpscan nuclei ffuf
```

## Installation

### 1. Clone the Repository

```bash
git clone https://github.com/yourusername/mcpkali.git
cd mcpkali
```

### 2. Create Virtual Environment

```bash
python3 -m venv venv
source venv/bin/activate
```

### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

### 4. Set Up LM Studio

1. Download and install [LM Studio](https://lmstudio.ai/)
2. Load a model (recommended: Mistral 7B, Llama 2, or similar)
3. Start the local server (Server tab → Start Server)
4. Verify it's running at `http://localhost:1234`

### 5. Configure the Server

```bash
# Copy example config
cp config.json config.local.json

# Edit configuration
nano config.local.json
```

Update the LM Studio settings:
```json
{
  "lm_studio": {
    "base_url": "http://localhost:1234/v1",
    "model": "your-model-name"
  }
}
```

### 6. Create Required Directories

```bash
sudo mkdir -p /var/log/mcpkali
sudo mkdir -p /var/lib/mcpkali/{reports,sessions}
sudo chown -R $USER:$USER /var/log/mcpkali /var/lib/mcpkali
```

## Usage

### Start the MCP Server

```bash
python3 server.py
```

### Basic Examples

#### 1. Autonomous Pentest

```json
{
  "tool": "start_autonomous_pentest",
  "arguments": {
    "target": "192.168.1.100",
    "scope": ["192.168.1.100", "192.168.1.101"],
    "depth": "vulnerability_scan",
    "rules_of_engagement": {
      "allow_exploitation": false,
      "rate_limit": true
    }
  }
}
```

#### 2. Network Reconnaissance

```json
{
  "tool": "nmap_scan",
  "arguments": {
    "target": "example.com",
    "scan_type": "full",
    "scripts": ["vuln", "default"]
  }
}
```

#### 3. Web Application Scanning

```json
{
  "tool": "vulnerability_assessment",
  "arguments": {
    "target": "https://example.com",
    "assessment_type": "web"
  }
}
```

#### 4. Get AI Suggestions

```json
{
  "tool": "get_ai_suggestion",
  "arguments": {
    "session_id": "pentest_20241105_120000",
    "context": "Found open ports 80, 443, 22. What should I do next?"
  }
}
```

#### 5. Generate Report

```json
{
  "tool": "generate_report",
  "arguments": {
    "session_id": "pentest_20241105_120000",
    "format": "html"
  }
}
```

## MCP Integration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kali-pentest": {
      "command": "python3",
      "args": ["/path/to/mcpkali/server.py"],
      "env": {
        "PYTHONPATH": "/path/to/mcpkali"
      }
    }
  }
}
```

### Other MCP Clients

Use standard MCP protocol to connect:

```python
from mcp import ClientSession
from mcp.client.stdio import stdio_client

async with stdio_client(["python3", "server.py"]) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        # Use the tools
```

## Configuration

### Security Settings

**Important:** Configure appropriate security settings in `config.json`:

```json
{
  "pentest": {
    "rules_of_engagement": {
      "allow_exploitation": false,  // Only enable with proper authorization
      "allow_post_exploitation": false,
      "max_brute_force_attempts": 100,
      "rate_limit": true
    }
  }
}
```

### LM Studio Settings

```json
{
  "lm_studio": {
    "temperature": 0.7,  // Higher = more creative, Lower = more focused
    "max_tokens": 2000,  // Maximum response length
    "timeout": 120       // Request timeout in seconds
  }
}
```

### Tool Configuration

Enable/disable specific tools:

```json
{
  "tools": {
    "nmap": { "enabled": true },
    "sqlmap": { "enabled": true },
    "hydra": { "enabled": false }  // Disable if not needed
  }
}
```

## Autonomous Mode

The autonomous mode allows the AI to make decisions and run tests automatically:

### Phases

1. **Reconnaissance**
   - Port scanning
   - Service detection
   - OS fingerprinting
   - DNS enumeration
   - Web technology detection

2. **Vulnerability Identification**
   - Service-specific vulnerability scans
   - Web application testing
   - SSL/TLS analysis
   - Known exploit searches
   - CVE matching

3. **Exploitation** (if authorized)
   - Safe exploitation attempts
   - Proof-of-concept generation
   - Risk assessment

4. **Post-Exploitation** (if authorized)
   - Privilege escalation
   - Lateral movement analysis
   - Data exfiltration testing

### Depth Levels

- `reconnaissance` - Information gathering only
- `vulnerability_scan` - Find vulnerabilities (recommended)
- `exploitation` - Attempt safe exploits (requires authorization)
- `post_exploitation` - Full pentest (requires explicit authorization)

## API Reference

### Tools

See [API.md](API.md) for complete tool documentation.

### Resources

- `pentest://session/{session_id}` - Get session data
- `pentest://report/{report_id}` - Get report

## Safety and Legal Considerations

### ⚠️ Important Warnings

1. **Authorization Required**: Only test systems you own or have explicit written permission to test
2. **Rules of Engagement**: Always define clear RoE before testing
3. **Responsible Disclosure**: Report vulnerabilities responsibly
4. **Data Protection**: Handle discovered data carefully
5. **Legal Compliance**: Ensure compliance with local laws

### Recommended Practices

- Start with reconnaissance-only mode
- Use VPN/isolated network for testing
- Keep detailed logs
- Review AI suggestions before execution
- Implement rate limiting
- Test in non-production environments first

## Troubleshooting

### LM Studio Connection Issues

```bash
# Check if LM Studio is running
curl http://localhost:1234/v1/models

# Check server logs
tail -f /var/log/mcpkali/server.log
```

### Permission Issues

```bash
# Ensure tools have proper permissions
sudo chmod +x $(which nmap sqlmap metasploit)

# Some tools require root
sudo setcap cap_net_raw,cap_net_admin,cap_net_bind_service+eip $(which nmap)
```

### Tool Not Found

```bash
# Install missing tool
sudo apt install -y <tool-name>

# Update tool database
sudo updatedb
```

## Development

### Adding New Tools

1. Add tool function to `tools.py`
2. Register tool in `server.py` `handle_list_tools()`
3. Add route in `handle_call_tool()`
4. Update documentation

### Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

## Architecture

```
┌─────────────────────────────────────────────┐
│           MCP Client (Claude, etc.)          │
└─────────────────┬───────────────────────────┘
                  │ MCP Protocol
┌─────────────────▼───────────────────────────┐
│            server.py (MCP Server)            │
│  ┌─────────────────────────────────────┐    │
│  │   Tool Registry & Request Handler    │    │
│  └─────────────────────────────────────┘    │
└─────┬──────────────────┬───────────────┬────┘
      │                  │               │
┌─────▼─────┐   ┌───────▼──────┐  ┌────▼─────┐
│LM Studio  │   │Pentest Engine│  │   Tools   │
│  Client   │   │   (Reports)  │  │ (Kali)    │
└───────────┘   └──────────────┘  └───────────┘
      │                                  │
┌─────▼─────┐                    ┌──────▼──────┐
│LM Studio  │                    │  Kali Tools  │
│   API     │                    │nmap, sqlmap,│
│(localhost)│                    │nikto, etc.  │
└───────────┘                    └─────────────┘
```

## Performance

- Concurrent scan limit: 3 (configurable)
- Average scan time: 5-30 minutes depending on depth
- Memory usage: 500MB-2GB depending on tools
- LM Studio inference: 2-10 seconds per decision

## Roadmap

- [ ] Metasploit RPC integration
- [ ] Custom module support
- [ ] Web UI dashboard
- [ ] Distributed scanning
- [ ] Cloud integration (AWS, Azure, GCP)
- [ ] Container security scanning
- [ ] API security testing
- [ ] Mobile app testing
- [ ] Plugin system
- [ ] Real-time collaboration

## License

MIT License - See [LICENSE](LICENSE) file

## Disclaimer

This tool is for authorized security testing only. Misuse of this tool may violate laws. The authors assume no liability for illegal use.

## Credits

Built with:
- [MCP (Model Context Protocol)](https://github.com/anthropics/mcp)
- [LM Studio](https://lmstudio.ai/)
- Kali Linux Tools
- Python asyncio

## Support

- Issues: [GitHub Issues](https://github.com/yourusername/mcpkali/issues)
- Discussions: [GitHub Discussions](https://github.com/yourusername/mcpkali/discussions)
- Email: security@example.com

## Acknowledgments

Thanks to the security community and open-source tool developers who make projects like this possible.

---

**Remember: With great power comes great responsibility. Use ethically and legally.**