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

Clone the repository
git clone https://github.com/your-org/kali-mcp-server.git cd kali-mcp-server
Build and run with Docker Compose
docker-compose up -d
Verify the installation
curl http://localhost:5000/health

Manual Docker Build

Build the Docker image
docker build -t kali-mcp-server .
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

Install dependencies
pip install -r requirements.txt
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

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
Use Nginx reverse proxy
docker-compose --profile production up -d
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

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
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

📈 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.