MCP Kali Pentest - Autonomous Penetration Testing Framework

A comprehensive, AI-powered automated penetration testing framework integrated with LM Studio for autonomous decision-making. This MCP server provides 80+ professional-grade security testing tools with intelligent automation across 17 specialized categories.

Features

🎯 Autonomous Testing

AI-powered decision making using LM Studio
Automatic target reconnaissance
Intelligent vulnerability prioritization
Self-guided exploitation path selection
Continuous learning from findings

🛠️ Comprehensive Tool Suite (80+ Tools)

📡 Reconnaissance & OSINT (11 tools)

Nmap, Masscan - Port scanning
Amass, theHarvester - Subdomain enumeration
Recon-ng - OSINT framework
Shodan - IoT device search
WhatWeb, Wafw00f - Technology fingerprinting

🌐 Web Application Testing (17 tools)

Nikto, Nuclei, WPScan, Joomscan, Droopescan
Burp Suite Pro API, OWASP ZAP
SQLMap, Commix, XSStrike - Exploitation
Gobuster, Dirb, DirBuster, Wfuzz, FFUF

📻 Wireless Security (5 tools)

Aircrack-ng suite, Wifite, Reaver
Bettercap, Kismet

🔓 Brute Force & Authentication (6 tools)

Hydra, CrackMapExec, Medusa, Patator

🔐 Password Cracking (4 tools)

John the Ripper, Hashcat, Ophcrack

💥 Exploitation (5 tools)

Metasploit Framework, SearchSploit

👻 Post-Exploitation (6 tools)

Mimikatz, BloodHound, PowerShell Empire
LinPEAS, WinPEAS, CrackMapExec

🎣 Social Engineering (3 tools)

SET, GoPhish, King Phisher

📱 Mobile Security (4 tools)

MobSF, Drozer, Frida

🔌 API Testing (4 tools)

Postman/Newman, GraphQL Scanner

🔍 Digital Forensics (4 tools)

Volatility, Autopsy, Binwalk

🔬 Reverse Engineering (5 tools)

Ghidra, Radare2, IDA Pro

☁️ Cloud Security (5 tools)

Scout Suite, CloudFox, Pacu

🐳 Container Security (4 tools)

Trivy, Docker Bench Security

🌐 Network Analysis (6 tools)

tcpdump, Wireshark, SNMP, enum4linux

🤖 Autonomous Testing (4 tools)

AI-powered pentesting, Smart suggestions

🤖 AI-Powered Features

Automatic scan result analysis
Intelligent next-step suggestions
Vulnerability prioritization
Risk assessment
Executive report generation
Custom attack plan creation

📊 Professional Reporting

JSON, HTML, Markdown, and PDF formats
Executive summaries
Risk assessments
Remediation recommendations
OWASP mapping
Timeline visualization

Prerequisites

System Requirements

Kali Linux (recommended) or any Debian-based Linux with security tools
Python 3.9 or higher
LM Studio (or compatible OpenAI API endpoint)
Minimum 4GB RAM
20GB free disk space

Required Tools

Most tools come pre-installed on Kali Linux:

# Verify tools are installed
which nmap nikto sqlmap metasploit gobuster nuclei hydra john hashcat

# Install missing tools
sudo apt update
sudo apt install -y nmap nikto sqlmap metasploit-framework gobuster \
    hydra john hashcat sslscan enum4linux smbclient snmp \
    tcpdump wireshark-cli wpscan nuclei ffuf

Installation

1. Clone the Repository

git clone https://github.com/yourusername/mcpkali.git
cd mcpkali

2. Create Virtual Environment

python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Set Up LM Studio

Download and install LM Studio
Load a model (recommended: Mistral 7B, Llama 2, or similar)
Start the local server (Server tab → Start Server)
Verify it's running at http://localhost:1234

5. Configure the Server

# Copy example config
cp config.json config.local.json

# Edit configuration
nano config.local.json

Update the LM Studio settings:

{
  "lm_studio": {
    "base_url": "http://localhost:1234/v1",
    "model": "your-model-name"
  }
}

6. Create Required Directories

sudo mkdir -p /var/log/mcpkali
sudo mkdir -p /var/lib/mcpkali/{reports,sessions}
sudo chown -R $USER:$USER /var/log/mcpkali /var/lib/mcpkali

Usage

Start the MCP Server

python3 server.py

Basic Examples

1. Autonomous Pentest

{
  "tool": "start_autonomous_pentest",
  "arguments": {
    "target": "192.168.1.100",
    "scope": ["192.168.1.100", "192.168.1.101"],
    "depth": "vulnerability_scan",
    "rules_of_engagement": {
      "allow_exploitation": false,
      "rate_limit": true
    }
  }
}

2. Network Reconnaissance

{
  "tool": "nmap_scan",
  "arguments": {
    "target": "example.com",
    "scan_type": "full",
    "scripts": ["vuln", "default"]
  }
}

3. Web Application Scanning

{
  "tool": "vulnerability_assessment",
  "arguments": {
    "target": "https://example.com",
    "assessment_type": "web"
  }
}

4. Get AI Suggestions

{
  "tool": "get_ai_suggestion",
  "arguments": {
    "session_id": "pentest_20241105_120000",
    "context": "Found open ports 80, 443, 22. What should I do next?"
  }
}

5. Generate Report

{
  "tool": "generate_report",
  "arguments": {
    "session_id": "pentest_20241105_120000",
    "format": "html"
  }
}

MCP Integration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "kali-pentest": {
      "command": "python3",
      "args": ["/path/to/mcpkali/server.py"],
      "env": {
        "PYTHONPATH": "/path/to/mcpkali"
      }
    }
  }
}

Other MCP Clients

Use standard MCP protocol to connect:

from mcp import ClientSession
from mcp.client.stdio import stdio_client

async with stdio_client(["python3", "server.py"]) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        # Use the tools

Configuration

Security Settings

Important: Configure appropriate security settings in config.json:

{
  "pentest": {
    "rules_of_engagement": {
      "allow_exploitation": false,  // Only enable with proper authorization
      "allow_post_exploitation": false,
      "max_brute_force_attempts": 100,
      "rate_limit": true
    }
  }
}

LM Studio Settings

{
  "lm_studio": {
    "temperature": 0.7,  // Higher = more creative, Lower = more focused
    "max_tokens": 2000,  // Maximum response length
    "timeout": 120       // Request timeout in seconds
  }
}

Tool Configuration

Enable/disable specific tools:

{
  "tools": {
    "nmap": { "enabled": true },
    "sqlmap": { "enabled": true },
    "hydra": { "enabled": false }  // Disable if not needed
  }
}

Autonomous Mode

The autonomous mode allows the AI to make decisions and run tests automatically:

Phases

Reconnaissance
- Port scanning
- Service detection
- OS fingerprinting
- DNS enumeration
- Web technology detection
Vulnerability Identification
- Service-specific vulnerability scans
- Web application testing
- SSL/TLS analysis
- Known exploit searches
- CVE matching
Exploitation (if authorized)
- Safe exploitation attempts
- Proof-of-concept generation
- Risk assessment
Post-Exploitation (if authorized)
- Privilege escalation
- Lateral movement analysis
- Data exfiltration testing

Depth Levels

reconnaissance - Information gathering only
vulnerability_scan - Find vulnerabilities (recommended)
exploitation - Attempt safe exploits (requires authorization)
post_exploitation - Full pentest (requires explicit authorization)

API Reference

Tools

See API.md for complete tool documentation.

Resources

pentest://session/{session_id} - Get session data
pentest://report/{report_id} - Get report

Safety and Legal Considerations

⚠️ Important Warnings

Authorization Required: Only test systems you own or have explicit written permission to test
Rules of Engagement: Always define clear RoE before testing
Responsible Disclosure: Report vulnerabilities responsibly
Data Protection: Handle discovered data carefully
Legal Compliance: Ensure compliance with local laws

Recommended Practices

Start with reconnaissance-only mode
Use VPN/isolated network for testing
Keep detailed logs
Review AI suggestions before execution
Implement rate limiting
Test in non-production environments first

Troubleshooting

LM Studio Connection Issues

# Check if LM Studio is running
curl http://localhost:1234/v1/models

# Check server logs
tail -f /var/log/mcpkali/server.log

Permission Issues

# Ensure tools have proper permissions
sudo chmod +x $(which nmap sqlmap metasploit)

# Some tools require root
sudo setcap cap_net_raw,cap_net_admin,cap_net_bind_service+eip $(which nmap)

Tool Not Found

# Install missing tool
sudo apt install -y <tool-name>

# Update tool database
sudo updatedb

Development

Adding New Tools

Add tool function to tools.py
Register tool in server.py handle_list_tools()
Add route in handle_call_tool()
Update documentation

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Add tests for new features
Submit a pull request

Architecture

┌─────────────────────────────────────────────┐
│           MCP Client (Claude, etc.)          │
└─────────────────┬───────────────────────────┘
                  │ MCP Protocol
┌─────────────────▼───────────────────────────┐
│            server.py (MCP Server)            │
│  ┌─────────────────────────────────────┐    │
│  │   Tool Registry & Request Handler    │    │
│  └─────────────────────────────────────┘    │
└─────┬──────────────────┬───────────────┬────┘
      │                  │               │
┌─────▼─────┐   ┌───────▼──────┐  ┌────▼─────┐
│LM Studio  │   │Pentest Engine│  │   Tools   │
│  Client   │   │   (Reports)  │  │ (Kali)    │
└───────────┘   └──────────────┘  └───────────┘
      │                                  │
┌─────▼─────┐                    ┌──────▼──────┐
│LM Studio  │                    │  Kali Tools  │
│   API     │                    │nmap, sqlmap,│
│(localhost)│                    │nikto, etc.  │
└───────────┘                    └─────────────┘

Performance

Concurrent scan limit: 3 (configurable)
Average scan time: 5-30 minutes depending on depth
Memory usage: 500MB-2GB depending on tools
LM Studio inference: 2-10 seconds per decision

Roadmap

License

MIT License - See LICENSE file

Disclaimer

This tool is for authorized security testing only. Misuse of this tool may violate laws. The authors assume no liability for illegal use.

Credits

Built with:

MCP (Model Context Protocol)
LM Studio
Kali Linux Tools
Python asyncio

Support

Acknowledgments

Thanks to the security community and open-source tool developers who make projects like this possible.

Remember: With great power comes great responsibility. Use ethically and legally.