Kali Linux MCP Server

# Kali Linux MCP Server (Dockerized) A dockerized Model Context Protocol (MCP) server that provides secure access to Kali Linux security tools for defensive security and authorized penetration testing. ## Features ### Network Scanning - **nmap_scan**: Network discovery and port scanning - **gobuster_dir**: Directory and file enumeration ### Web Application Testing - **wpscan_scan**: WordPress security scanning - **sqlmap_test**: SQL injection testing - **dirb_scan**: Web content discovery ### System Enumeration - **enum4linux_scan**: SMB/NetBIOS enumeration - **searchsploit_query**: Exploit database search ### Credential Testing - **crackmapexec_smb**: SMB credential testing - **john_crack**: Password cracking with John the Ripper - **hashcat_crack**: GPU-accelerated password cracking ### Utilities - **netcat_connect**: Network connectivity testing - **bloodhound_py**: Active Directory enumeration ## Security Features - **Input Sanitization**: All inputs are validated against strict patterns - **Network Restrictions**: Configurable allowed target networks - **Non-root Execution**: Runs with minimal privileges using Linux capabilities - **Timeout Protection**: Commands have configurable execution limits - **Output Limiting**: Response sizes are capped for safety ## Docker Installation & Usage ### Prerequisites - Docker and Docker Compose installed - Sufficient disk space for Kali Linux image ### Quick Start ```bash # Build and start the container (MCP server starts automatically) docker compose up --build # Or run in background docker compose up -d --build # The MCP server runs inside the container with STDIO transport # Integration with Claude Desktop uses a wrapper script ``` ### Container Usage ```bash # View server logs docker compose logs -f kali-mcp-container # Access the running container (for debugging/development) docker compose exec kali-mcp-container bash # The MCP server is already running automatically # Check server status inside container: # ps aux | grep python ``` ### Container Management ```bash # Stop the container and MCP server docker compose down # View real-time server logs docker compose logs -f kali-mcp-container # Restart the container docker compose restart # Rebuild container (after code changes) docker compose build --no-cache # For development: override auto-start to get shell access # Temporarily modify docker-compose.yml: command: /bin/bash ``` ### Claude Desktop Integration (Automatic) ```bash # The MCP server uses STDIO transport for Claude Desktop # Integration happens via the wrapper script # Container starts automatically when you run: docker compose up -d --build # Check if container is running: docker compose ps | grep kali-mcp-container ``` ## Configuration ### Environment Variables - `MCP_HOST`: Server host (default: 127.0.0.1) - `MCP_PORT`: Server port (default: 8000) - `MCP_MAX_EXEC_TIME`: Command timeout in seconds (default: 300) - `MCP_OUTPUT_LIMIT`: Maximum output size in bytes (default: 10000) - `MCP_ALLOWED_NETWORKS`: Comma-separated list of allowed target networks - `WPSCAN_API_TOKEN`: Optional WPScan API token for vulnerability data ### Network Restrictions For production use, configure `MCP_ALLOWED_NETWORKS` to restrict scanning targets: ```bash # Example: Only allow internal networks MCP_ALLOWED_NETWORKS=192.168.0.0/16,10.0.0.0/8,172.16.0.0/12 ``` ## Usage Examples (Inside Container) ### Automatic Server Startup ```bash # The MCP server starts automatically when you run: docker compose up --build # Server is available at localhost:8000 # No manual startup required! # To verify server is running: docker compose logs kali-mcp-container ``` ### Testing Tools Directly (Optional) ```bash # Access container for direct tool testing docker compose exec kali-mcp-container bash # Inside container: nmap --version gobuster version wpscan --version ls /usr/share/wordlists/ ``` ### MCP Tool Usage (via Claude Desktop) Once connected to Claude Desktop, you can use tools like: ``` # Network scanning nmap_scan("192.168.1.1", scan_type="basic") # Directory enumeration gobuster_dir("http://example.com") # WordPress scanning wpscan_scan("http://wordpress.example.com") # SQL injection testing sqlmap_test("http://example.com/page?id=1") ``` ## Claude Desktop Integration ### Configuration Steps 1. Start the containerized MCP server: ```bash docker compose up -d --build ``` 2. The integration uses a wrapper script (`kali_mcp_wrapper.py`) that connects Claude Desktop to the containerized server via STDIO transport. 3. Configure Claude Desktop: ```json { "mcpServers": { "kali-security": { "command": "python3", "args": ["/home/pellax/Documents/myfirstclaudecode/kali_mcp_wrapper.py"] } } } ``` 4. Restart Claude Desktop to load the configuration. ### Container Features - **Automatic startup**: MCP server starts when container boots - **Data persistence**: `./data` directory mounted from host - **Real-time logs**: `docker compose logs -f kali-mcp-container` - **Environment configuration**: All variables in docker-compose.yml - **Port mapping**: localhost:8000 automatically mapped ## Security Considerations ### Authorized Use Only This tool is designed for: - Authorized penetration testing - Security assessments - Educational purposes - Defensive security research ### Network Security - Configure network restrictions in production - Use firewall rules to limit access - Monitor tool usage and logs - Implement proper authentication ### User Permissions - Run as dedicated service user (not root) - Use Linux capabilities for network tools - Restrict file system access - Enable audit logging ## Requirements ### Host System - Docker and Docker Compose - 4GB+ free disk space for Kali image - Network access for tool downloads ### Container Environment - Kali Linux rolling base image - Python 3.8+ (included) - All Kali security tools (pre-installed) - Virtual environment with Python dependencies ### Python Dependencies (Auto-installed in container) - fastmcp >= 0.4.0 - pydantic >= 2.0.0 - Built-in Python modules (asyncio, subprocess, etc.) ## Development ### Project Structure ``` myfirstclaudecode/ ├── kali_mcp_server/ │ ├── __init__.py │ └── server.py # Main server implementation ├── kali_mcp_wrapper.py # Claude Desktop integration wrapper ├── Dockerfile # Container definition ├── docker-compose.yml # Container orchestration ├── start_server.sh # Container startup script ├── .dockerignore # Docker build exclusions ├── claude_desktop_config.md # Claude Desktop setup guide ├── demo_server.py # Demo/testing server ├── requirements.txt # Python dependencies ├── pyproject.toml # Package configuration ├── data/ # Persistent data directory └── README.md # This file ``` ### Wrapper Script Integration The `kali_mcp_wrapper.py` script enables Claude Desktop integration by: - Connecting to the running Docker container via `docker exec` - Providing STDIO transport bridge between Claude Desktop and the containerized MCP server - Automatically handling container communication and error reporting ### Adding New Tools 1. Add tool function with `@mcp.tool()` decorator 2. Implement input sanitization 3. Use `run_tool()` helper for execution 4. Add proper error handling 5. Update documentation ## License MIT License - See LICENSE file for details ## Disclaimer This software is provided for educational and authorized testing purposes only. Users are responsible for complying with applicable laws and regulations. The authors are not responsible for misuse of this tool.