Kali MCP Server

A secure, production-ready Model Context Protocol (MCP) server that exposes Kali Linux security tools for use with Large Language Models (LLMs). This server provides both MCP and HTTP API interfaces, allowing LLMs to leverage powerful security tools in a controlled, sandboxed environment.

🚀 Features

Core Functionality

• Dual Interface: Both MCP and HTTP API support
• Tool Management: Dynamic tool discovery and metadata
• Security First: Comprehensive input validation and sandboxing
• Async Support: High-performance async/await implementation
• Production Ready: Docker, monitoring, logging, and health checks

Security Features

• Input Sanitization: Prevents command injection and path traversal
• Tool Whitelisting: Only approved tools can be executed
• Sandboxed Execution: Isolated environment for tool execution
• Resource Limits: Timeout and output size restrictions
• Audit Logging: Comprehensive security event logging

Supported Tools

The server supports a curated set of Kali Linux security tools:

Network Scanning & Enumeration

• nmap - Network mapper
• gobuster - Directory/file brute-forcer
• dirb - Web content scanner
• wfuzz - Web application fuzzer
• nikto - Web vulnerability scanner

Password Attacks

• hydra - Network login cracker
• john - Password cracker
• hashcat - Advanced password recovery
• medusa - Parallel login brute-forcer
• ncrack - Network authentication tool

Web Application Testing

• sqlmap - SQL injection tool
• cewl - Custom word list generator

Wireless Security

• aircrack-ng - Wireless security suite

Exploitation Framework

• metasploit-framework - Penetration testing platform

System & Network Utilities

• enum4linux - SMB enumeration
• smbclient - SMB client
• rpcclient - RPC client
• ldapsearch - LDAP search utility
• dig - DNS lookup utility
• nslookup - DNS lookup utility
• whois - WHOIS lookup
• traceroute - Network path tracer
• ping - Network connectivity test
• netstat - Network statistics
• ss - Socket statistics

📋 Prerequisites

• Docker and Docker Compose
• Python 3.8+ (for local development)
• Git

🛠️ Installation

Quick Start with Docker

1. Clone the repository

   git clone https://github.com/your-org/kali-mcp-server.git
   cd kali-mcp-server
   

2. Build and run with Docker Compose

   docker-compose up -d
   

3. Verify the installation

   curl http://localhost:5000/health
   

Manual Docker Build

1. Build the Docker image

   docker build -t kali-mcp-server .
   

2. Run the container

   docker run -d \
     --name kali-mcp-server \
     -p 5000:5000 \
     -p 8000:8000 \
     -e MAX_TIMEOUT=300 \
     -e DEFAULT_TIMEOUT=60 \
     kali-mcp-server
   

Local Development

1. Install dependencies

   pip install -r requirements.txt
   

2. Run the server

   python server.py
   

🔧 Configuration

Environment Variables

Variable	Default	Description
MAX_TIMEOUT	300	Maximum execution timeout (seconds)
DEFAULT_TIMEOUT	60	Default execution timeout (seconds)
MAX_OUTPUT_SIZE	1048576	Maximum output size (bytes)
ENABLE_HTTP	true	Enable HTTP API
ENABLE_HTTPS	false	Enable HTTPS
SSL_CERT	null	SSL certificate path
SSL_KEY	null	SSL private key path
LOG_LEVEL	INFO	Logging level
ENABLE_CORS	true	Enable CORS
WORKING_DIRECTORY	/tmp/kali-mcp	Working directory for tools
ENABLE_SANDBOX	true	Enable sandboxing
EXTRA_TOOLS	null	Comma-separated list of additional tools

Configuration File

The server supports YAML configuration files. See config.yaml for all available options.

📚 API Documentation

HTTP API Endpoints

Health Check

GET /health

Returns server health status.

List Available Tools

GET /tools

Returns a list of all available tools with metadata.

Get Tool Information

GET /tools/{tool_name}

Returns detailed information about a specific tool.

Execute Tool

POST /run
Content-Type: application/json

{
  "tool": "nmap",
  "args": "-sS -O 192.168.1.1",
  "timeout": 60,
  "working_dir": "/tmp/scan"
}

Get Metrics

GET /metrics

Returns server metrics and statistics.

MCP Tools

list_tools()

Returns a list of available tools.

get_tool_info(tool: str)

Returns detailed information about a specific tool.

run_tool(tool: str, args: str = None, timeout: int = None, working_dir: str = None)

Executes a tool with the specified arguments.

🔒 Security Considerations

Input Validation

• All tool names are validated against a whitelist
• Command arguments are sanitized to prevent injection
• File paths are sanitized to prevent directory traversal

Sandboxing

• Tools execute in isolated environments
• Dangerous environment variables are removed
• Working directories are restricted

Resource Limits

• Execution timeouts prevent hanging processes
• Output size limits prevent memory exhaustion
• CPU and memory limits via Docker

Audit Logging

• All tool executions are logged
• Security events are tracked
• Failed attempts are recorded

🧪 Testing

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=server --cov-report=html

# Run security tests only
pytest tests/test_security.py -v

# Run integration tests
pytest tests/test_server.py::TestIntegration -v

Test Categories

• Unit Tests: Individual function testing
• Security Tests: Security validation testing
• Integration Tests: End-to-end workflow testing
• API Tests: HTTP endpoint testing

🚀 Deployment

Production Deployment

1. Enable HTTPS

   # Generate SSL certificates
   openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
   
   # Update docker-compose.yml
   - ENABLE_HTTPS=true
   - SSL_CERT=/opt/certs/cert.pem
   - SSL_KEY=/opt/certs/key.pem
   

2. Use Nginx reverse proxy

   docker-compose --profile production up -d
   

3. Configure monitoring

   • Set up log aggregation
   • Configure alerting
   • Monitor resource usage

Docker Compose Profiles

• Default: Basic HTTP server
• Production: Includes Nginx reverse proxy with SSL

📊 Monitoring

Health Checks

• HTTP endpoint: GET /health
• Docker health check configured
• Metrics endpoint: GET /metrics

Logging

• Structured JSON logging
• Log rotation configured
• Security event logging

Metrics

• Tool execution counts
• Execution times
• Error rates
• Resource usage

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

Development Setup

# Clone and setup
git clone https://github.com/your-org/kali-mcp-server.git
cd kali-mcp-server

# Install development dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run tests
pytest

# Run linting
flake8 server.py tests/

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Documentation: Wiki
• Security: Security Policy

🔗 Related Projects

• Model Context Protocol
• FastMCP
• Kali Linux

📈 Roadmap

• [ ] Web UI for tool management
• [ ] Plugin system for custom tools
• [ ] Advanced monitoring dashboard
• [ ] Multi-tenant support
• [ ] Tool execution scheduling
• [ ] Result caching
• [ ] Integration with popular LLM frameworks

🙏 Acknowledgments

• Kali Linux team for the excellent security tools
• FastMCP team for the MCP framework
• The open-source community for inspiration and contributions

---

⚠️ Security Warning: This server provides access to powerful security tools. Use responsibly and ensure proper access controls are in place. Never expose this server to untrusted networks without proper authentication and authorization.