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

1. Download and install LM Studio
2. Load a model (recommended: Mistral 7B, Llama 2, or similar)
3. Start the local server (Server tab → Start Server)
4. 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

1. Reconnaissance

   • Port scanning
   • Service detection
   • OS fingerprinting
   • DNS enumeration
   • Web technology detection

2. Vulnerability Identification

   • Service-specific vulnerability scans
   • Web application testing
   • SSL/TLS analysis
   • Known exploit searches
   • CVE matching

3. Exploitation (if authorized)

   • Safe exploitation attempts
   • Proof-of-concept generation
   • Risk assessment

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

1. Authorization Required: Only test systems you own or have explicit written permission to test
2. Rules of Engagement: Always define clear RoE before testing
3. Responsible Disclosure: Report vulnerabilities responsibly
4. Data Protection: Handle discovered data carefully
5. 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

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

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. 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

• Metasploit RPC integration
• Custom module support
• Web UI dashboard
• Distributed scanning
• Cloud integration (AWS, Azure, GCP)
• Container security scanning
• API security testing
• Mobile app testing
• Plugin system
• Real-time collaboration

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

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: security@example.com

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.