# 🐉 Kali MCP Server - Web Penetration Testing

A **Model Context Protocol (MCP)** server built on Kali Linux Docker container, providing AI-assisted web penetration testing tools with proper input sanitization and formatted output.

![Security](https://img.shields.io/badge/Security-Pentest-red)
![Docker](https://img.shields.io/badge/Docker-Kali%20Linux-blue)
![MCP](https://img.shields.io/badge/MCP-FastMCP-green)

---

## 🚀 Features

### Security Tools Included

| Tool | Purpose | Category |
|------|---------|----------|
| **Nmap** | Port scanning, service detection, OS fingerprinting | Network |
| **Nikto** | Web server vulnerability scanning | Web Vuln |
| **SQLMap** | SQL injection testing | Web Vuln |
| **WPScan** | WordPress security assessment | CMS |
| **DIRB** | Directory brute-forcing | Discovery |
| **Gobuster** | Fast directory/DNS/vhost enumeration | Discovery |
| **FFUF** | Web fuzzing | Discovery |
| **SearchSploit** | Exploit database search | Research |
| **SSLScan** | SSL/TLS analysis | Crypto |
| **WhatWeb** | Web technology identification | Recon |
| **WAFW00F** | WAF detection | Recon |
| **Nuclei** | Template-based vulnerability scanning | Web Vuln |

### Key Features

- ✅ **Non-root execution** with proper network capabilities
- ✅ **Input sanitization** to prevent command injection
- ✅ **Formatted output** for easy reading
- ✅ **Async execution** for non-blocking operations
- ✅ **Output persistence** for report generation
- ✅ **Rate limiting** to prevent abuse
- ✅ **Docker isolation** for security

---

## 📦 Installation

### Prerequisites

- Docker Engine 20.10+
- Docker Compose v2.0+
- 4GB RAM minimum (8GB recommended)
- 10GB disk space

### Quick Start

```bash
# Clone or download the project
cd kali-mcp-server

# Build the Docker image
docker-compose build

# Start the server
docker-compose up -d

# Check logs
docker-compose logs -f

# Verify it's running
curl http://localhost:8010/health
```

### Build Only

```bash
docker build -t kali-mcp-server:latest .
```

### Run Manually

```bash
docker run -d \
  --name kali-mcp \
  --cap-add NET_RAW \
  --cap-add NET_ADMIN \
  -p 8010:8010 \
  -v kali-outputs:/app/outputs \
  kali-mcp-server:latest
```

---

## 🔧 Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_HOST` | `0.0.0.0` | Server bind address |
| `MCP_PORT` | `8010` | Server port |
| `DEBUG` | `false` | Enable debug logging |
| `DEFAULT_TIMEOUT` | `300` | Default tool timeout (seconds) |
| `MAX_TIMEOUT` | `3600` | Maximum allowed timeout |
| `WPSCAN_API_TOKEN` | - | WPScan vulnerability database API token |

### Claude Desktop Integration

Add to your Claude Desktop config (`~/.config/claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "kali-pentest": {
      "url": "http://localhost:8010/sse"
    }
  }
}
```

Or for Docker execution:

```json
{
  "mcpServers": {
    "kali-pentest": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--cap-add=NET_RAW",
        "--cap-add=NET_ADMIN",
        "-p", "8010:8010",
        "kali-mcp-server:latest"
      ]
    }
  }
}
```

---

## 🛠️ Available Tools

### 1. Network Scanning

#### `nmap_scan`
```python
nmap_scan(
    target="192.168.1.1",           # IP, hostname, or CIDR
    ports="80,443,8080",            # Port specification
    scan_type="version",            # default, syn, connect, udp, version, aggressive, vuln
    scripts="http-enum,ssl-enum",   # NSE scripts
    timing=3,                       # 0-5 (paranoid to insane)
    timeout=600
)
```

### 2. Web Vulnerability Scanning

#### `nikto_scan`
```python
nikto_scan(
    target="http://example.com",
    port=80,
    ssl=False,
    tuning="123bde",    # Test categories
    timeout=600
)
```

#### `sqlmap_scan`
```python
sqlmap_scan(
    target_url="http://example.com/page?id=1",
    data="username=admin",          # POST data
    parameter="id",                 # Specific param to test
    level=3,                        # 1-5
    risk=2,                         # 1-3
    technique="BEUST",              # Injection techniques
    dbms="mysql",                   # Target DBMS
    tables=True,                    # Enumerate tables
    timeout=600
)
```

#### `wpscan_scan`
```python
wpscan_scan(
    target="http://wordpress-site.com",
    enumerate="vp,vt,u",            # plugins, themes, users
    plugins_detection="aggressive",
    api_token="your_token"
)
```

### 3. Directory Discovery

#### `dirb_scan`
```python
dirb_scan(
    target="http://example.com",
    wordlist="big",                 # common, big, small
    extensions="php,html,txt",
    recursive=True,
    timeout=600
)
```

#### `gobuster_scan`
```python
gobuster_scan(
    target="http://example.com",
    mode="dir",                     # dir, dns, vhost
    wordlist="medium",
    extensions="php,html",
    threads=40,
    timeout=600
)
```

#### `ffuf_fuzz`
```python
ffuf_fuzz(
    target="http://example.com/FUZZ",
    wordlist="common",
    method="GET",
    headers="X-Custom:value",
    filter_code="404,500",
    threads=50
)
```

### 4. Information Gathering

#### `whatweb_scan`
```python
whatweb_scan(
    target="http://example.com",
    aggression=3                    # 1-4
)
```

#### `wafw00f_detect`
```python
wafw00f_detect(
    target="http://example.com",
    list_all=True
)
```

#### `sslscan_scan`
```python
sslscan_scan(
    target="example.com",
    port=443,
    show_certs=True
)
```

### 5. Exploit Research

#### `searchsploit_search`
```python
searchsploit_search(
    search_term="apache 2.4.49",
    exact_match=False,
    exclude="dos,windows"
)
```

### 6. Vulnerability Scanning

#### `nuclei_scan`
```python
nuclei_scan(
    target="http://example.com",
    templates="cves,vulnerabilities",
    severity="high,critical",
    tags="rce,sqli",
    rate_limit=150
)
```

---

## 🔒 Security Considerations

### Input Sanitization

All inputs are validated and sanitized:

- **Targets**: Validated as IP, CIDR, hostname, or URL
- **Ports**: Validated format, range checks
- **Parameters**: Regex filtering, dangerous character removal
- **Paths**: Allowed directory whitelist

### Dangerous Patterns Blocked

```
; | & ` $ ( ) { } > < || && ../ %00 \n \r
```

### Non-Root Execution

The container runs as `pentester` user (UID 1000) with limited capabilities:

```yaml
cap_add:
  - NET_RAW           # Required for SYN scans
  - NET_ADMIN         # Network configuration
  - NET_BIND_SERVICE  # Bind to low ports
```

---

## 📋 Web Pentest Workflow

### Recommended Scanning Order

```
1. Reconnaissance
   ├── whatweb_scan          # Identify technologies
   ├── wafw00f_detect        # Check for WAF
   └── nmap_scan (ports)     # Open ports/services

2. Discovery
   ├── gobuster_scan (dir)   # Directory enumeration
   ├── gobuster_scan (dns)   # Subdomain enumeration
   └── ffuf_fuzz             # Parameter fuzzing

3. Vulnerability Assessment
   ├── nikto_scan            # General web vulnerabilities
   ├── nuclei_scan           # Template-based scanning
   ├── sslscan_scan          # SSL/TLS issues
   └── wpscan_scan           # If WordPress detected

4. Targeted Testing
   ├── sqlmap_scan           # SQL injection
   └── searchsploit_search   # Find exploits

5. Reporting
   └── Review /app/outputs   # All scan results saved
```

---

## 📁 Project Structure

```
kali-mcp-server/
├── Dockerfile              # Kali Linux container setup
├── docker-compose.yml      # Orchestration
├── requirements.txt        # Python dependencies
├── README.md              # This file
├── src/
│   ├── __init__.py
│   ├── main.py            # FastMCP server & tools
│   ├── validators.py      # Input sanitization
│   ├── formatters.py      # Output formatting
│   └── config.py          # Settings management
├── config/
│   └── claude_desktop_config.json
├── scripts/               # Helper scripts
└── wordlists/            # Custom wordlists
```

---

## 🐛 Troubleshooting

### Container Won't Start

```bash
# Check logs
docker-compose logs kali-mcp

# Verify capabilities
docker run --rm --cap-add NET_RAW kali-mcp-server nmap --version
```

### Scans Timing Out

```bash
# Increase timeout
docker-compose exec kali-mcp env DEFAULT_TIMEOUT=900

# Or pass timeout parameter
nmap_scan(target="...", timeout=900)
```

### Permission Denied

```bash
# Ensure proper capabilities
docker run --cap-add NET_RAW --cap-add NET_ADMIN ...
```

### Tool Not Found

```bash
# Enter container and verify
docker-compose exec kali-mcp which nmap nikto sqlmap
```

---

## 📜 License

MIT License - Use responsibly and only on authorized systems.

---

## ⚠️ Legal Disclaimer

This tool is for **authorized security testing only**. Unauthorized access to computer systems is illegal. Always:

1. Get written permission before testing
2. Define scope clearly
3. Document all activities
4. Report findings responsibly

The authors assume no liability for misuse of this tool.

---

## 🤝 Contributing

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

---

## 📞 Support

For issues and feature requests, open a GitHub issue with:

- Environment details
- Steps to reproduce
- Expected vs actual behavior
- Relevant logs