# 🐉 Pentest-MCP: Autonomous Penetration Testing Agent [![Kali Linux](https://img.shields.io/badge/Kali-2024.4-blue?logo=kalilinux)](https://www.kali.org/) [![MCP Protocol](https://img.shields.io/badge/MCP-2024--11--05-orange)](https://modelcontextprotocol.io/) [![HexStrike AI](https://img.shields.io/badge/HexStrike-AI%20Integrated-red)](https://github.com/0x4m4/hexstrike-ai) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) **A production-grade Model Context Protocol (MCP) server for autonomous penetration testing, featuring intelligent tool routing and the "Blood-Red" HexStrike AI engine.** --- ## � Table of Contents - [🐉 Pentest-MCP: Autonomous Penetration Testing Agent](#-pentest-mcp-autonomous-penetration-testing-agent) - [� Table of Contents](#-table-of-contents) - [�🚀 Overview](#-overview) - [✨ Features](#-features) - [🏗️ Architecture](#️-architecture) - [📋 Prerequisites](#-prerequisites) - [⚙️ Installation](#️-installation) - [Step 1: Clone the Repository](#step-1-clone-the-repository) - [Step 2: Understand the Docker Base Images](#step-2-understand-the-docker-base-images) - [Step 3: Build and Start the Environment](#step-3-build-and-start-the-environment) - [Step 4: Verify Running Containers](#step-4-verify-running-containers) - [🔌 Connecting Your AI](#-connecting-your-ai) - [Claude Desktop](#claude-desktop) - [Cline (VS Code Extension)](#cline-vs-code-extension) - [⚡ Usage](#-usage) - [Example Prompts](#example-prompts) - [📂 Project Structure](#-project-structure) - [🙏 Credits \& Acknowledgements](#-credits--acknowledgements) - [⚖️ License \& Disclaimer](#️-license--disclaimer) - [⚠️ Legal Disclaimer](#️-legal-disclaimer) --- ## �🚀 Overview This project provides a fully dockerized **autonomous pentesting environment** that exposes powerful security tools to AI agents (like Claude, Cline, or your own LLM) via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). It integrates **Kali Linux** tools with **HexStrike AI**, a specialized offensive intelligence engine that manages 150+ tools, optimizing parameters and strategies in real-time. --- ## ✨ Features | Category | Capabilities | | :---------------------------- | :------------------------------------------------------------------------- | | **Autonomous Recon** | Smart sub-domain enumeration, technology detection, attack surface mapping | | **Intelligent Exploitation** | Auto-routing complex tasks (SQLi, XSS) to HexStrike for deep analysis | | **AngularJS Sandbox Escapes** | Specialized payloads for modern web framework exploitation | | **Stateful Operations** | Persistent sessions for multi-step exploits (Store-then-Deliver attacks) | | **Universal Bridge** | Works with any MCP-compliant client (Claude Desktop, VS Code/Cline, Zed) | | **150+ Security Tools** | Nmap, SQLMap, Nikto, Masscan, Gobuster, Hydra, and more via HexStrike | --- ## 🏗️ Architecture The system uses a **Unified Gateway** architecture: ``` ┌─────────────────┐ ┌──────────────────┐ ┌────────────────────┐ │ AI Client │ ───▶ │ kali-mcp │ ───▶ │ hexstrike-mcp │ │ (Claude/Cline) │ │ (Gateway) │ │ (150+ Tools) │ └─────────────────┘ └──────────────────┘ └────────────────────┘ │ ▼ ┌──────────────────┐ │ Local Kali │ │ Tools (Fallback)│ └──────────────────┘ ``` 1. **AI Client** sends request to `kali-mcp`. 2. **ToolExecutor** analyzes the request. 3. If complex (e.g., `sqlmap`) → Routes to **HexStrike AI** container. 4. If simple or HexStrike unavailable → Executes locally on Kali. --- ## 📋 Prerequisites - **Docker**: v20.10+ - **Docker Compose**: v2.0+ - **Python**: 3.10+ (for local test scripts) - **Git**: For cloning the repository --- ## ⚙️ Installation ### Step 1: Clone the Repository ```bash git clone https://github.com/Vasanthadithya-Mundrathi/Pentest-MCP.git cd Pentest-MCP ``` ### Step 2: Understand the Docker Base Images This project uses the following Docker images: | Container | Base Image | Purpose | | :-------------- | :-------------------------------------------------------------------------- | :------------------------------- | | `kali-mcp` | [`kalilinux/kali-rolling`](https://hub.docker.com/r/kalilinux/kali-rolling) | MCP Server, core security tools | | `hexstrike-mcp` | [`kalilinux/kali-rolling`](https://hub.docker.com/r/kalilinux/kali-rolling) | HexStrike AI engine (150+ tools) | > **Note**: The `kalilinux/kali-rolling` image is the official, minimal Kali Linux Docker image. It does not include a GUI. For more information, see the [Official Kali Linux Docker Documentation](https://www.kali.org/docs/containers/official-kali-cloud-images/). ### Step 3: Build and Start the Environment ```bash docker-compose up -d --build ``` *This command builds both containers and starts them in the background.* ### Step 4: Verify Running Containers ```bash docker ps ``` You should see two containers running: - `kali-mcp` on port `8000` - `hexstrike-mcp` on port `8001` (internal: `8888`) --- ## 🔌 Connecting Your AI ### Claude Desktop Add this to your `claude_desktop_config.json`: - **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "kali-mcp": { "command": "docker", "args": ["exec", "-i", "kali-mcp", "python3", "/app/stdio_bridge.py"] } } } ``` ### Cline (VS Code Extension) 1. Open Cline Settings → **MCP Servers** tab. 2. Click "Edit MCP Settings". 3. Paste the configuration above. For more details, see **[CONNECT_LOCALLY.md](./CONNECT_LOCALLY.md)**. --- ## ⚡ Usage Once connected, your AI assistant has access to these tools: | Tool | Description | | :------------------------------- | :------------------------------------ | | `recon_target` | Full network & web reconnaissance | | `web_exploit` | Targeted XSS/SQLi/CSTI exploitation | | `run_command_sync` | Quick shell commands (`ls`, `whoami`) | | `start_job` / `check_job_status` | Long-running background scans | ### Example Prompts ``` "Use kali-mcp to scan example.com for vulnerabilities." "Run web_recon on https://target.com and identify all parameters." "Test https://target.com?search=test for XSS vulnerabilities." ``` For a complete guide, see **[MCP_SETUP_GUIDE.md](./MCP_SETUP_GUIDE.md)**. --- ## 📂 Project Structure ``` Pentest-MCP/ ├── README.md # You are here ├── MCP_SETUP_GUIDE.md # Detailed usage guide ├── CONNECT_LOCALLY.md # AI client connection instructions ├── docker-compose.yml # Container orchestration ├── kali/ # Kali MCP server source │ ├── Dockerfile │ ├── mcp_server.py # FastAPI MCP server │ ├── stdio_bridge.py # MCP stdio protocol handler │ └── skills/ # Autonomous skill modules │ ├── recon_skill.py │ ├── web_recon_skill.py │ ├── web_exploitation_skill.py │ └── tool_executor.py # Intelligent routing ├── hexstrike/ # HexStrike AI integration │ └── Dockerfile ├── docs/ # Additional documentation └── tests/ # Test scripts and utilities ``` --- ## 🙏 Credits & Acknowledgements This project stands on the shoulders of giants: - **[HexStrike AI](https://github.com/0x4m4/hexstrike-ai)** by [@0x4m4](https://github.com/0x4m4): The "Blood-Red" offensive intelligence engine providing 150+ integrated security modules. - **[Kali Linux](https://www.kali.org/)** by Offensive Security: The industry-standard penetration testing distribution. - **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)**: The open standard enabling AI-tool interoperability. - **[PortSwigger Web Security Academy](https://portswigger.net/web-security)**: For providing the labs used to test and validate exploitation payloads. --- ## ⚖️ License & Disclaimer **License**: [MIT License](./LICENSE) ### ⚠️ Legal Disclaimer **FOR EDUCATIONAL AND AUTHORIZED PENTESTING PURPOSES ONLY.** This tool is designed for security professionals, ethical hackers, and researchers. You are solely responsible for your actions. Use of this tool against targets without prior mutual consent is illegal. The authors assume absolutely no liability for misuse or any damages that may arise. By using this software, you agree to: 1. Obtain proper authorization before testing any system. 2. Comply with all applicable local, state, national, and international laws. 3. Use this tool responsibly and ethically. --- *Built with ❤️ by Vasanthadithya*