Kali MCP Server

# Kali MCP Server A production-quality MCP (Model Context Protocol) server that exposes 20+ Kali Linux security tools through an AI-friendly interface, enabling AI assistants to perform penetration testing and security assessments in a controlled, structured manner. ## ⚠️ LEGAL NOTICE **This tool is intended for AUTHORIZED security testing only.** - You MUST have explicit written permission to test any systems - Unauthorized access to computer systems is ILLEGAL - Users are responsible for ensuring proper authorization - The authors assume NO LIABILITY for misuse of this tool By using this tool, you acknowledge that you have proper authorization and accept full responsibility for your actions. ## Features - **20+ Security Tools** across multiple categories - **Type-safe** using TypeScript and Zod validation - **Safe execution** with command allowlists, timeouts, and output limits - **Input validation** to prevent command injection - **Rate limiting** to prevent abuse - **Structured output** with proper error handling - **MCP-compliant** for seamless AI integration ## Supported Tools ### Network Tools (6) - **nmap** - Network port scanning and service detection - **nmap discover** - Host discovery on networks - **masscan** - High-speed port scanner - **netdiscover** - ARP reconnaissance - **tcpdump** - Packet capture - **tshark** - Wireshark CLI for packet analysis ### Web Security Tools (7) - **gobuster dir** - Directory/file enumeration - **gobuster dns** - Subdomain enumeration - **sqlmap** - SQL injection testing - **nikto** - Web server scanner - **wpscan** - WordPress security scanner - **ffuf** - Web fuzzer - **nuclei** - Template-based vulnerability scanner ### Password Tools (3) - **hydra** - Network login brute-forcer - **john** - John the Ripper password cracker - **hashcat** - Advanced password recovery ### Exploitation Tools (3) - **searchsploit** - Exploit database search - **searchsploit examine** - View exploit details - **msfvenom** - Metasploit payload generator ## Installation ### Prerequisites 1. **Kali Linux** (or any Linux distribution with security tools installed) 2. **Node.js** 18+ and npm 3. **Security tools** installed on your system ### Install Security Tools (Kali Linux) ```bash sudo apt update sudo apt install -y \ nmap masscan netdiscover tcpdump tshark \ gobuster sqlmap nikto wpscan ffuf nuclei \ hydra john hashcat \ exploitdb metasploit-framework ``` ### Install MCP Server ```bash cd kali-mcp-server npm install npm run build ``` ## Usage ### Running the Server ```bash # Start the server npm start # Or run directly node dist/index.js ``` ### Testing with MCP Inspector ```bash # Launch the MCP Inspector for interactive testing npm run inspector # Or npx @modelcontextprotocol/inspector node dist/index.js ``` ### Integrating with Claude Desktop Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): ```json { "mcpServers": { "kali-security": { "command": "node", "args": ["/path/to/kali-mcp-server/dist/index.js"] } } } ``` ## Tool Reference ### Network Tools #### kali_network_nmap_scan Perform network port scanning using Nmap. **Example:** ```json { "target": "192.168.1.1", "ports": "22,80,443", "scan_type": "tcp_syn", "timing": "normal", "service_version": true } ``` **Parameters:** - `target` (required): IP, hostname, or CIDR range - `ports` (optional): Port specification (default: top 1000) - `scan_type`: tcp_syn, tcp_connect, udp, ack, null, fin, xmas - `timing`: paranoid, sneaky, polite, normal, aggressive, insane - `os_detection`: Enable OS detection (requires root) - `service_version`: Probe for service versions - `script_scan`: NSE scripts to run - `aggressive`: Enable aggressive scan - `timeout`: Timeout in seconds (default: 300) #### kali_network_nmap_discover Discover live hosts on a network. **Example:** ```json { "network": "192.168.1.0/24", "method": "ping", "timeout": 120 } ``` ### Web Tools #### kali_web_gobuster_dir Enumerate directories and files on web servers. **Example:** ```json { "url": "https://example.com", "wordlist": "/usr/share/wordlists/dirb/common.txt", "extensions": "php,html,txt", "threads": 10 } ``` #### kali_web_sqlmap_test Automated SQL injection testing. **Example:** ```json { "url": "https://example.com/page?id=1", "level": 1, "risk": 1, "batch": true } ``` **WARNING:** Only use on systems you have authorization to test. ### Password Tools #### kali_password_hydra_brute Fast network login brute-forcer. **Example:** ```json { "target": "192.168.1.1", "service": "ssh", "username": "admin", "password_list": "/usr/share/wordlists/rockyou.txt", "threads": 16 } ``` **WARNING:** Only use on systems you have authorization to test. ### Exploitation Tools #### kali_exploit_searchsploit_search Search the Exploit Database. **Example:** ```json { "query": "apache 2.4", "platform": "linux" } ``` Or search by CVE: ```json { "cve": "CVE-2021-44228" } ``` #### kali_exploit_msfvenom_generate Generate custom payloads. **Example:** ```json { "payload": "linux/x64/shell_reverse_tcp", "lhost": "192.168.1.100", "lport": 4444, "format": "elf" } ``` ## Security Features ### Command Allowlist Only pre-approved commands can be executed. The server maintains a strict allowlist of permitted security tools. ### Input Validation All inputs are validated before execution: - IP addresses and CIDR ranges - Hostnames and URLs - Port numbers and ranges - File paths (no directory traversal) - No shell metacharacters ### Output Sanitization Sensitive information is automatically redacted from output: - Passwords - API keys - Tokens - Secrets ### Execution Limits - **Timeouts**: Configurable per tool (default: 5 minutes) - **Output size**: Maximum 10MB per command - **Rate limiting**: 10 commands per minute, 100 per hour ### Process Isolation All commands are executed in isolated child processes with: - Separate stdout/stderr capture - Graceful timeout handling - Resource cleanup ## Configuration ### Environment Variables Customize tool paths using environment variables: ```bash export NMAP_PATH=/usr/bin/nmap export GOBUSTER_PATH=/usr/bin/gobuster export SQLMAP_PATH=/usr/bin/sqlmap # ... etc ``` ### Wordlist Paths Default wordlists (Kali Linux): - `/usr/share/wordlists/rockyou.txt` - `/usr/share/wordlists/dirb/common.txt` - `/usr/share/seclists/Discovery/Web-Content/common.txt` ## Error Handling The server provides detailed, actionable error messages: ``` ❌ Command failed: nmap -sS 192.168.1.1 🔢 Exit code: 1 📋 Error output: You requested a scan type which requires root privileges. Possible causes: - TCP SYN scan requires root/sudo - Try using scan_type="tcp_connect" instead - Run the server with sudo (not recommended) Suggested actions: 1. Use tcp_connect scan type (doesn't require root) 2. Grant CAP_NET_RAW capability to nmap 3. Check permissions and try again ``` ## Troubleshooting ### Tools Not Found If tools are not in your PATH: ```bash # Check if tool is installed which nmap # Install missing tools sudo apt install nmap # Or set custom path export NMAP_PATH=/custom/path/to/nmap ``` ### Permission Errors Some tools require root privileges: - nmap TCP SYN scan (-sS) - masscan - tcpdump/tshark - netdiscover **Solutions:** 1. Use non-privileged alternatives (e.g., nmap TCP connect scan) 2. Grant specific capabilities: `sudo setcap cap_net_raw+ep /usr/bin/nmap` 3. Run server with sudo (not recommended for security reasons) ### Timeout Issues If scans are timing out: ```json { "target": "192.168.1.1", "ports": "1-65535", "timeout": 1800 // Increase to 30 minutes } ``` ## Development ### Project Structure ``` kali-mcp-server/ ├── src/ │ ├── index.ts # Main server │ ├── types.ts # Type definitions │ ├── constants.ts # Configuration │ ├── utils/ │ │ ├── executor.ts # Command execution │ │ ├── validator.ts # Input validation │ │ ├── formatter.ts # Output formatting │ │ └── parser.ts # Output parsing │ ├── tools/ │ │ ├── network.ts # Network tool handlers │ │ ├── web.ts # Web tool handlers │ │ ├── password.ts # Password tool handlers │ │ └── exploit.ts # Exploit tool handlers │ └── schemas/ │ ├── network.schemas.ts │ ├── web.schemas.ts │ ├── password.schemas.ts │ └── exploit.schemas.ts └── dist/ # Compiled output ``` ### Adding New Tools 1. Define Zod schema in `src/schemas/[category].schemas.ts` 2. Implement tool handler in `src/tools/[category].ts` 3. Register tool in `src/index.ts` 4. Add to `ALLOWED_COMMANDS` in `src/constants.ts` **Example:** ```typescript // 1. Schema export const MyToolSchema = z.object({ target: z.string().describe("Target to scan"), option: z.boolean().default(false), }); // 2. Handler export async function myTool(input: MyToolInput): Promise<ToolResult> { const args = [input.target]; if (input.option) args.push("--option"); const result = await executeCommand("mytool", args); return formatExecutionResult(result); } // 3. Register in index.ts { name: "kali_category_mytool_action", description: "Description of what it does", inputSchema: zodToJsonSchema(MyToolSchema), } // 4. Add to ALLOWED_COMMANDS export const ALLOWED_COMMANDS = new Set([ // ... existing commands "mytool", ]); ``` ### Running Tests ```bash npm run build npm start ``` Test with MCP Inspector: ```bash npm run inspector ``` ## Common Workflows ### 1. Network Reconnaissance ``` 1. Discover hosts: kali_network_nmap_discover 2. Port scan: kali_network_nmap_scan 3. Service detection: kali_network_nmap_scan with service_version=true 4. Vulnerability scan: kali_network_nmap_scan with script_scan="vuln" ``` ### 2. Web Application Testing ``` 1. Directory enumeration: kali_web_gobuster_dir 2. Subdomain discovery: kali_web_gobuster_dns 3. Vulnerability scanning: kali_web_nikto_scan 4. SQL injection testing: kali_web_sqlmap_test ``` ### 3. Password Assessment ``` 1. Network brute force: kali_password_hydra_brute 2. Hash identification: Manual analysis 3. Hash cracking: kali_password_john_crack or kali_password_hashcat_crack ``` ### 4. Exploit Research ``` 1. Search exploits: kali_exploit_searchsploit_search 2. Examine exploit: kali_exploit_searchsploit_examine 3. Generate payload: kali_exploit_msfvenom_generate ``` ## Performance Tips 1. **Use appropriate timing**: Balance speed vs stealth 2. **Limit port ranges**: Scan only necessary ports 3. **Use wordlists wisely**: Smaller wordlists for faster results 4. **Adjust threads**: More threads = faster, but more resource-intensive 5. **Set realistic timeouts**: Complex scans need more time ## Contributing Contributions are welcome! Please ensure: - All inputs are validated - Commands are in the allowlist - Error messages are actionable - Documentation is updated - Security best practices are followed ## License MIT License - See LICENSE file for details ## Acknowledgments - Kali Linux team for the excellent security distribution - Anthropic for the Model Context Protocol - Security tool authors: nmap, gobuster, sqlmap, hydra, john, hashcat, and many more ## Disclaimer This tool is provided for educational and authorized security testing purposes only. The authors are not responsible for any misuse or damage caused by this tool. Always ensure you have proper authorization before testing any systems. --- **Version:** 1.0.0 **Last Updated:** 2025-11-29