Kali MCP Pentest Server

# Kali MCP Pentest Server A Model Context Protocol (MCP) server that provides access to essential penetration testing tools through a standardized interface. Built on Kali Linux and designed for integration with AI assistants and automation platforms. ## Overview This project packages 8 essential security testing tools into an MCP server running in a containerized Kali Linux environment. It uses the FastMCP framework to expose security tools with proper input validation, timeout handling, and safety controls. ## Available Tools The server provides the following security testing tools via MCP: | Tool | Purpose | Parameter | Example Command | |------|---------|-----------|-----------------| | `nmap_scan` | Network port scanning | `target` (hostname/IP) | `nmap -Pn <target>` | | `nikto_scan` | Web server vulnerability scanning | `target` (hostname/IP) | `nikto -h <target>` | | `sqlmap_scan` | SQL injection testing | `target` (URL) | `sqlmap -u <target> --batch` | | `wpscan_scan` | WordPress security scanning | `target` (WordPress URL) | `wpscan --url <target>` | | `dirb_scan` | Directory/file enumeration | `target` (URL) | `dirb <target>` | | `searchsploit_query` | Exploit database search | `query` (search term) | `searchsploit <query>` | | `ping_scan` | Network connectivity test | `target` (hostname/IP) | `ping -c 4 <target>` | | `traceroute_scan` | Network path tracing | `target` (hostname/IP) | `traceroute <target>` | ## Architecture - **Base**: Kali Linux (`kalilinux/kali-rolling`) Docker container - **Framework**: FastMCP for MCP protocol implementation - **Transport**: StreamableHTTP (supports SSE and HTTP endpoints) - **Security**: Non-root execution with minimal required capabilities - **Dependencies**: Python virtual environment with required packages ## Quick Start ### Using Docker Compose (Recommended) ```bash # Start the server docker compose up -d # View logs docker compose logs -f # Stop the server docker compose down ``` ### Using Docker ```bash # Build the image docker build -t kali-mcp-server . # Run the container docker run -p 8080:8080 \ --cap-add=NET_RAW \ --cap-add=NET_ADMIN \ --cap-add=NET_BIND_SERVICE \ kali-mcp-server ``` ### Using Pre-built Image ```bash # Pull and run the latest image from GitHub Container Registry docker run -p 8080:8080 \ --cap-add=NET_RAW \ --cap-add=NET_ADMIN \ --cap-add=NET_BIND_SERVICE \ ghcr.io/andrew-stclair/kali-mcp-server/kali-mcp-server:latest ``` ## MCP Integration ### Protocol Details - **Server Name**: `kali-mcp-pentest-server` - **Transport**: StreamableHTTP - **Host**: `0.0.0.0` - **Port**: `8080` - **Endpoints**: - MCP Protocol: `http://localhost:8080/mcp` - Server-Sent Events: `http://localhost:8080/sse` - Status Check: `http://localhost:8080/` ### Client Configuration For MCP clients like N8N: ```json { "serverUrl": "http://localhost:8080", "transport": "http", "mcpPath": "/mcp" } ``` ### Testing MCP Connection ```bash # Check server status curl http://localhost:8080/ # Connect to SSE endpoint for session info curl -H "Accept: text/event-stream" http://localhost:8080/sse ``` ## Security Features ### Input Validation - Sanitizes all user inputs to prevent command injection - Blocks dangerous characters: `;&|$`\`\\n\\r` - Validates tool names against allowed list ### Runtime Security - Runs as non-root user (`kaliuser`) - Uses Python virtual environment for dependency isolation - Required Linux capabilities: `NET_RAW`, `NET_ADMIN`, `NET_BIND_SERVICE` - Tool execution timeout: 120 seconds ### Tool Restrictions - Only whitelisted tools can be executed - Fixed command-line arguments prevent arbitrary command execution - Subprocess isolation with proper error handling ## Development ### Local Development ```bash # Create virtual environment python3 -m venv venv source venv/bin/activate # Install dependencies pip install -r requirements.txt # Run the server python main.py ``` ### Dependencies - `fastapi` - Web framework - `uvicorn` - ASGI server - `python-multipart` - Form data handling - `mcp>=1.15.0` - Model Context Protocol implementation ### Container Build Process The Dockerfile performs these steps: 1. Starts with Kali Linux rolling release 2. Installs security tools and Python dependencies 3. Creates non-root user with sudo privileges 4. Sets up proper file ownership and capabilities 5. Creates Python virtual environment 6. Installs Python packages in isolated environment 7. Exposes port 8080 and runs the MCP server ## CI/CD Pipeline The GitHub Actions workflow (`.github/workflows/docker-build.yml`): - **Triggers**: Push to `main` branch, pull requests - **Build**: Multi-architecture (linux/amd64, linux/arm64) - **Registry**: GitHub Container Registry (`ghcr.io`) - **Deployment**: Automatic on merge to `main` ## Security Considerations ⚠️ **Educational Use Only**: This tool is intended for learning and authorized testing only. ### Important Notes - Always obtain proper authorization before testing targets - Use only on systems you own or have explicit permission to test - The container requires elevated network capabilities for certain tools - Input validation helps prevent command injection but shouldn't be your only security layer - Monitor logs for suspicious activity ### Capabilities Required The container needs these Linux capabilities: - `NET_RAW`: For raw socket operations (nmap, ping) - `NET_ADMIN`: For network administration tasks - `NET_BIND_SERVICE`: For binding to privileged ports if needed ## License This project is for educational purposes. Users are responsible for compliance with applicable laws and regulations.