kali-pentest-mcp-server-v2

Yash-Pandey007/kali-pentest-mcp-server-v2

3.2

If you are the rightful owner of kali-pentest-mcp-server-v2 and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Kali Pentest MCP Server is a production-ready Model Context Protocol server designed for secure and authorized penetration testing in controlled environments.

Tools
7
Resources
0
Prompts
0

Kali Pentest MCP Server

A Model Context Protocol (MCP) server that provides secure access to penetration testing tools through a standardized interface. Designed to run in a hardened Kali Linux container with comprehensive security controls.

Features

  • MCP Protocol: Full Model Context Protocol 2025-06-18 implementation
  • Security Tools: nmap, nikto, sqlmap, and target validation utilities
  • Docker Security: Hardened container with capability-based security model
  • Input Validation: Comprehensive validation for IP addresses, domains, and URLs
  • Command Safety: Shell injection protection via parameterized commands
  • Testing Suite: Complete test coverage including MCP protocol validation
  • Client Integration: Ready for Claude Desktop, Cursor, and other MCP clients

Project Structure

kali-pentest-mcp-server/
├── mcp_server.py            # MCP protocol server implementation
├── kali_pentest_server.py   # Core penetration testing logic
├── requirements.txt         # Runtime dependencies
├── requirements-dev.txt     # Development dependencies
├── Dockerfile              # Container build configuration
├── docker-compose.yml      # Container orchestration
├── pytest.ini             # Test configuration
├── test_mcp.py             # MCP server validation test
├── test_mcp_tools.py       # MCP tools validation test
├── test_simple.py          # Simple MCP initialization test
├── tests/                  # Comprehensive test suite
│   ├── __init__.py
│   ├── conftest.py        # Test fixtures
│   ├── test_server.py     # Core server tests
│   ├── test_dockerfile.py # Docker configuration tests
│   ├── test_docker_compose.py # Docker Compose tests
│   ├── test_integration.py # Integration tests
│   └── test_security_tools.py # Security tool mocking tests
├── MCP_USAGE_GUIDE.md     # Client integration guide
├── CHANGELOG.md           # Version history
├── LICENSE               # MIT License
└── README.md             # This file

Quick Start

Prerequisites

  • Python 3.11+
  • Docker & Docker Compose
  • Git

Development Setup

  1. Clone the repository:

    git clone <repository-url>
cd kali-pentest-mcp-server

  2. Set up Python environment:

    python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -r requirements-dev.txt

  3. Run tests:

    pytest

  4. Test the MCP server:

    # Test MCP server initialization
python test_simple.py

# Test CLI interface (dry-run mode)
python kali_pentest_server.py --dry-run nmap 127.0.0.1
python kali_pentest_server.py --dry-run nikto https://example.com
python kali_pentest_server.py --dry-run sqlmap https://example.com/test?id=1

Docker Usage

The server runs in a hardened Kali Linux container with security-focused configuration.

Quick Start with Docker Compose (Recommended)
# Build and start the container
docker-compose build
docker-compose up -d

# Execute commands in the container
docker-compose exec kali-pentest-mcp python kali_pentest_server.py --dry-run nmap target.example.com

# View logs
docker-compose logs -f

# Stop the service
docker-compose down
Manual Docker Build
# Build the image
docker build -t kali-pentest-mcp:latest .

# Run with required capabilities
docker run -it --rm \
  --name kali-pentest-mcp \
  --cap-add=NET_RAW \
  --cap-add=NET_ADMIN \
  -v $(pwd)/scans:/app/scans \
  -v $(pwd)/reports:/app/reports \
  -v $(pwd)/logs:/app/logs \
  kali-pentest-mcp:latest

Note: On Windows PowerShell, replace $(pwd) with ${PWD}. On Windows CMD, use %cd%.

MCP Tools and Example Results

Available MCP Tools

The server provides these tools through the MCP protocol:

  1. nmap_scan: Network scanning with multiple scan types

    • Parameters: target, scan_type (basic/ports/services/stealth), extra_args
    • Returns: Formatted scan results with command details

  2. nikto_scan: Web vulnerability scanning

    • Parameters: url, extra_args
    • Returns: Vulnerability assessment results

  3. sqlmap_scan: SQL injection testing

    • Parameters: url, test_level (basic/thorough/aggressive), extra_args
    • Returns: SQL injection test results

  4. validate_target: Target validation and reachability check

    • Parameters: target
    • Returns: Validation results for IP/domain/URL

Example Nmap Scan Results

When you run an nmap scan through the MCP interface, you'll get comprehensive results:

Scan Results for [REDACTED TARGET]

The nmap scan has completed successfully. Here's what was discovered:

Host Status: The target is up and responding (21ms latency)

Open Ports and Services:

1. Port 80: Microsoft IIS 10.0 web server
2. Port 135: Microsoft Windows RPC
3. Port 139: NetBIOS Session Service
4. Port 445: Microsoft Directory Services (SMB)
5. Port 8080: Apache 2.4.58 with OpenSSL 3.1.3 and PHP 8.2.12
6. Port 3306: MariaDB database (10.3.23 or earlier)

Operating System: Windows

Key Findings:

• This appears to be a Windows machine running a development environment (possibly XAMPP or similar)
• Multiple web servers detected (IIS on port 80, Apache on port 8080)
• Database service exposed (MariaDB on port 3306)
• SMB/NetBIOS services available for potential enumeration
• The combination suggests a local development setup rather than a production server
MCP Client Integration

For MCP client configuration (Claude Desktop, Cursor, etc.), add this to your client's MCP settings:

Option 1: Direct Python execution (for development):

{
  "mcpServers": {
    "kali-pentest": {
      "command": "python",
      "args": ["C:\\path\\to\\kali-pentest-mcp-server\\mcp_server.py"],
      "cwd": "C:\\path\\to\\kali-pentest-mcp-server"
    }
  }
}

Option 2: Docker execution (recommended for production):

{
  "mcpServers": {
    "kali-pentest": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--cap-add=NET_RAW", "--cap-add=NET_ADMIN",
        "-v", "./scans:/app/scans",
        "-v", "./reports:/app/reports", 
        "-v", "./logs:/app/logs",
        "kali-pentest-mcp:latest",
        "python", "mcp_server.py"
      ]
    }
  }
}

Note: Volume paths are relative to the MCP client's working directory. Use absolute paths for more predictable behavior. For Windows paths, use double backslashes in JSON.

Docker Security Features
  • Non-root execution: Runs as pentester user (UID 1000)
  • Network capabilities: Only NET_RAW and NET_ADMIN for scanning
  • Resource limits: CPU and memory constraints via docker-compose
  • Volume isolation: Scans, reports, and logs in separate volumes
  • SUID hardening: Unnecessary SUID binaries removed

MCP Server Validation

Testing MCP Protocol Implementation

Validate that your MCP server is working correctly:

# Test MCP server initialization
python test_simple.py

# Test MCP tools list (if you need to debug tools/list)
python test_mcp_tools.py

# Basic MCP communication test
python test_mcp.py

A successful test will show:

✅ MCP Server Response:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "experimental": {},
      "tools": {
        "listChanged": false
      }
    },
    "serverInfo": {
      "name": "kali-pentest",
      "version": "1.0.0"
    }
  }
}

🎉 MCP Server initialized successfully!
Server: kali-pentest v1.0.0

✅ MCP server is ready for production use!

Testing

The project includes a comprehensive test suite:

Test Categories

  1. Unit Tests (test_server.py):

    • Input validation functions
    • Command builders
    • Error handling
    • CLI interface

  2. Security Tool Tests (test_security_tools.py):

    • Mocked nmap, nikto, and sqlmap execution
    • Realistic tool output simulation
    • Error scenario testing
    • Command construction validation

  3. Integration Tests (test_integration.py):

    • End-to-end workflows
    • Multi-tool scenarios
    • Timeout handling
    • Error propagation

  4. Docker Tests (test_dockerfile.py, test_docker_compose.py):

    • Container configuration validation
    • Security settings verification
    • Volume mount testing

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=kali_pentest_server

# Run specific test file
pytest tests/test_server.py

# Run with verbose output
pytest -v

# Run tests matching a pattern
pytest -k "test_nmap"

Test Coverage

The test suite provides comprehensive coverage including:

  • Input validation (IP, domain, URL)
  • Command construction and safety
  • Tool execution mocking
  • Error handling and timeouts
  • Docker configuration validation
  • CLI interface testing
  • Integration workflows

Security Considerations

Container Security

  • Non-root user: Container runs as pentester user
  • Capability management: Only necessary network capabilities granted
  • SUID removal: Unnecessary SUID binaries removed
  • Resource limits: CPU and memory constraints applied

Code Security

  • No shell injection: Uses parameterized command execution
  • Input validation: Strict validation of all inputs
  • Timeout protection: All operations have configurable timeouts
  • Error handling: Comprehensive error handling and logging

Testing Security

  • Mocked execution: Tests never run actual security tools
  • Isolated environment: Tests run in controlled environment
  • No network access: Tests don't make external connections

Architecture

Core Components

  1. PentestServer Class: Main server logic

    • Input validation methods
    • Command builders (pure functions)
    • Execution wrapper with timeout
    • High-level tool interfaces

  2. CommandResult: Data structure for command results

    • Command arguments
    • Standard output/error
    • Return code

  3. CLI Interface: Command-line entry point

    • Dry-run mode for safe testing
    • Tool-specific argument parsing
    • JSON output for tool integration

Design Principles

  • Testability: Dependency injection for easy mocking
  • Safety: No shell=True, parameterized commands only
  • Modularity: Separate validation, building, and execution
  • Error handling: Comprehensive error reporting

Development

Code Quality

The project uses several tools for code quality:

# Format code
black kali_pentest_server.py tests/

# Lint code
flake8 kali_pentest_server.py tests/

# Type checking
mypy kali_pentest_server.py

Adding New Tools

To add a new security tool:

  1. Add a static command builder method
  2. Add validation logic if needed
  3. Add a high-level interface method
  4. Create comprehensive tests with mocked output
  5. Update the CLI interface if desired

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request

Legal Notice

FOR AUTHORIZED TESTING ONLY

This tool is intended solely for authorized penetration testing and security research. Users are responsible for:

  • Obtaining proper authorization before scanning
  • Complying with applicable laws and regulations
  • Using the tool ethically and responsibly

Unauthorized scanning or testing may violate laws and regulations.

License

See LICENSE file for details.