pentestMCP

[](https://mseep.ai/app/ram001-code-pentestmcp) [](https://mseep.ai/app/baf52bdd-53df-484e-9b56-2ee38c8f3027) # pentestMCP: AI-Powered Penetration Testing via MCP [](https://opensource.org/licenses/MIT) <!-- Example badges (replace placeholders/add relevant ones) --> <!-- [](https://travis-ci.com/Ram001-code/pentestMCP) --> <!-- [](https://github.com/Ram001-code/pentestMCP/issues) --> <!-- [](https://github.com/Ram001-code/pentestMCP/network) --> <!-- [](https://github.com/Ram001-code/pentestMCP/stargazers) --> **pentestMCP provides a powerful bridge between Large Language Models (LLMs) and practical penetration testing tools through the Model Context Protocol (MCP). This project functions as an MCP Server, exposing a curated suite of over 20 standard security assessment utilities (Nmap, Nuclei, ZAP, SQLMap, etc.) as callable 'tools'. This allows AI agents within MCP-compatible clients (like Claude Desktop or specific VS Code setups) to leverage these utilities for automated and interactive security analysis tasks.** The goal is to enable natural language control over complex security workflows, making pentesting capabilities more accessible and integrated into AI-driven environments. This work is inspired by [Laurie Kirk](https://github.com/LaurieWired/)'s [GhidraMCP](https://github.com/LaurieWired/GhidraMCP). --- ## Table of Contents - [Core Concepts & Architecture](#core-concepts--architecture) - [Key Features](#key-features) - [Prerequisites](#prerequisites) - [Installation & Setup](#installation--setup) - [Using Pre-built Docker Image (Recommended)](#using-pre-built-docker-image-recommended) - [Building Docker Image Locally](#building-docker-image-locally) - [Client Host Integration](#client-host-integration) - [Claude Desktop Integration](#claude-desktop-integration) - [VS Code Copilot Chat Integration](#vs-code-copilot-chat-integration) - [Tool Reference](#tool-reference) - [Security Considerations](#security-considerations) - [Contributing](#contributing) - [License](#license) - [Disclaimer](#disclaimer) - [Acknowledgements](#acknowledgements) --- ## Video Demo https://github.com/user-attachments/assets/930c879a-5cb4-478a-b033-f30df0e770a6 ## Core Concepts & Architecture pentestMCP strictly adheres to the MCP specification, functioning solely as an **MCP Server**. It does not embed or directly communicate with any specific LLM. The interaction flow is mediated by an MCP Client Host application: 1. **Client Host Application** (e.g., Claude Desktop, custom agent): Connects to pentestMCP (typically via `stdio` brokered by Docker), manages user interaction, and interfaces with a chosen LLM. 2. **LLM**: Receives user prompts and tool definitions (from pentestMCP via the Client Host). It decides which tools to invoke based on the context. 3. **pentestMCP Server (This Project)**: Runs within a Docker container. Listens for `tools/call` requests from the Client Host, executes the corresponding underlying tool (e.g., `nmap`), and returns the results. 4. **External Tools**: The actual command-line utilities encapsulated within the Docker image. The server is built using the Python MCP SDK (`mcp.server.fastmcp.FastMCP`) and features: * **Tool Discovery:** Utilizes Python type hints and docstrings for automatic MCP tool schema generation. * **Concurrency Control:** A `threading.Semaphore` limits simultaneous execution of resource-intensive scans. * **Asynchronous Scan Pattern:** Implements launch/fetch methods for long-running tasks (Nmap, Nuclei, SQLMap, Gobuster) to avoid blocking the MCP connection. ```mermaid sequenceDiagram participant User participant ClientHost as Client Host (Claude, VS Code) participant LLM participant PentestMCP as pentestMCP Server (Docker via stdio) participant ExtTool as External Tool (e.g., Nmap) User->>ClientHost: "Perform Nmap service scan on scanme.nmap.org" ClientHost->>PentestMCP: tools/list Request PentestMCP-->>ClientHost: List of Tools (including 'run_nmap_scan') ClientHost->>LLM: User Prompt + Available Tools Description LLM-->>ClientHost: Decision: Use 'run_nmap_scan', target='scanme.nmap.org', args='-sV' ClientHost->>PentestMCP: tools/call (name='run_nmap_scan', args={...}) Note over PentestMCP, ExtTool: pentestMCP executes 'nmap -sV scanme.nmap.org' internally PentestMCP-->>ClientHost: tools/call Result (pid, output_path for async or direct output) ClientHost->>LLM: Tool Execution Result LLM-->>ClientHost: Formulate Final Response ClientHost-->>User: "Nmap scan launched/completed. Results..." ``` ## Key Features * **Comprehensive Toolset:** Integrates over 20 essential penetration testing tools via MCP. * **Standardized Access:** Enables any MCP client supporting `stdio` server launching to utilize complex pentesting workflows. * **Non-Blocking Scans:** Efficiently handles long-running scans without locking up the interaction flow. * **Resource Management:** Implements basic concurrency limiting for scans. * **Portable & Reproducible:** Dockerized environment ensures all dependencies and tools are available consistently across platforms (Windows, macOS, Linux). * **Web Scanner Integration:** Provides direct control over OWASP ZAP Active Scan and AJAX Spider functionalities. ## Prerequisites * **Docker:** Requires Docker Desktop (Windows/macOS) or Docker Engine (Linux) to be installed and running. Ensure the Docker daemon is active. * **Git:** Needed only if building the image locally (`git clone` step). * **(Optional but Recommended) OWASP ZAP Instance:** For using ZAP-related tools (`run_zap_*`, `run_active_scan_*`, `run_ajax_*`). This ZAP instance needs to be running and network-accessible from *inside* the pentestMCP Docker container (see Client Host Integration section for configuration). ## Installation & Setup We recommend using the pre-built Docker image for the fastest and most reliable setup. ### 🐳 Using Pre-built Docker Image (Recommended) Using the pre-built image avoids local build times and ensures all tools (like gofang, nmap, and nuclei) are correctly installed without dependency issues. 1. **Pull the image from Docker Hub:** ```bash docker pull ramgameer/pentest-mcp:latest ``` > ℹ️ **Note:** Depending on your environment, you may need to authenticate or ensure the Docker daemon is running. --- ### 🛠️ Building Docker Image Locally > ⚠️ **IMPORTANT:** Building locally is currently most efficient and supported on **Linux** environments. If you wish to modify the server's code, use the absolute latest version, or the pre-built image is unavailable, you can build the Docker image locally. 1. **Clone the repository:** ```bash git clone https://github.com/ramkansal/pentestMCP.git cd pentestMCP ``` 2. **Build the Docker image:** ```bash docker build -t pentest-mcp-server:custom . ``` 3. **Install SecLists (Optional but highly recommended):** > 💡 **Tip:** Several tools (like Gobuster and Fuzzing utilities) rely on massive wordlists. You must clone the SecLists repo for these specific scans to function effectively. ```bash git clone https://github.com/danielmiessler/SecLists.git seclists ``` ## Client Host Integration pentestMCP runs inside Docker and communicates with the Client Host via `stdio`. You configure your host (e.g., Claude Desktop, VS Code) to launch the server using `docker run -i ...`. ### Claude Desktop Integration 1. **Locate/Create Config File:** * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` 2. **Edit Config:** Add/update the `mcpServers` section. Use the correct image name (`ramgameer/pentest-mcp:latest` or your custom tag) . ```json { "mcpServers": { "pentestMCP": { "command": "docker", "args": [ "run", "--rm", "-i", "ramgameer/pentest-mcp:latest" ] } } } ``` 3. **Restart Claude Desktop** fully. 4. **Verify:** Look for the <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg" style="display: inline; margin: 0; height: 1.3em;" /> icon. Clicking it should list the pentesting tools. 5. **Interact:** Ask Claude to use the tools (see examples in the draft). ### VS Code Copilot Chat Integration Integration requires configuring VS Code's settings to define the MCP server for Copilot Chat agents that support MCP. 1. **Install Prerequisite:** Ensure [Github Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) and relevant GitHub Copilot extensions are installed. 2. **Configure VS Code Settings:** Open your User or Workspace `settings.json` file (Command Palette: "Preferences: Open Settings (JSON)"). Add the MCP server configuration under the appropriate path (this path might change depending on the specific Copilot Chat agent implementation, check its documentation): ```json "pentest-mcp": { "type": "stdio", "command": "docker", "args": [ "run", "-i", "--rm", "ramgameer/pentest-mcp:latest" ] } ``` 3. **Reload VS Code / Agent:** Restart VS Code or use relevant commands to reload the Copilot agent's configuration for the changes to take effect. Consult the specific Copilot agent's documentation for details. 4. **Interact:** Use the Copilot Chat interface, potentially invoking tools via mentions if the agent supports it, or let the agent invoke them based on your prompts. ## Tool Reference The server exposes a variety of tools categorized by function: * **Reconnaissance & Enumeration:** * `run_subfinder`: Discovers subdomains using ProjectDiscovery's Subfinder. * `launch_nmap_scan` / `fetch_nmap_results`: Executes Nmap network scans and retrieves results asynchronously. * `run_gobuster_scan` / `check_gobuster_status`: Performs directory/file/DNS bruteforcing with Gobuster asynchronously. * `launch_gofang_scan` / `fetch_gofang_results`: Runs gofang, an all-in-one web crawler with extraction superpowers. * `run_harvester` / `check_harvester_status`: Runs theHarvester asynchronously for OSINT gathering (emails, hosts, ips). * `run_dig_tool`: Executes DNS `dig` queries. * `fetch_whois_data`: Retrieves WHOIS information for a domain. * `run_curl_tool`: Executes cURL commands for HTTP interaction. * **Vulnerability Scanning:** * `launch_nuclei_scan` / `fetch_nuclei_results`: Runs template-based vulnerability scans with ProjectDiscovery's Nuclei asynchronously. * **Web Application Analysis:** * `launch_arjun_scan` / `fetch_arjun_results`: Locates hidden HTTP parameters using Arjun. * **Exploitation Support:** * `run_searchsploit`: Searches the local Exploit-DB database using Searchsploit. * `run_sqlmap_tool` / `check_sqlmap_status`: Executes SQLmap for SQL injection testing asynchronously. * **Active Directory Analysis (`ad_*` tools):** * **Enumeration:** `ad_user_enum`, `ad_shares_enum`, `ad_smb_signing_check`, `ad_certipy_enum`, `ad_ldap_dump`, `ad_bloodhound_collect` * **Attacks/Coercion:** `ad_asreproast`, `ad_kerberoast`, `ad_password_spray`, `ad_coerce_petitpotam`, `ad_coerce_printerbug`, `ad_responder_poison`, `ad_relay_setup` * **Credential/Domain Operations:** `ad_check_credentials`, `ad_secrets_dump`, `ad_dcsync` ## Security Considerations * **Execution Permissions:** Tools run as `appuser` within Docker, but Docker itself runs with host privileges. Be cautious with tools that modify files or require elevated system access. * **Target Authorization:** **CRITICAL:** Only use these tools against systems for which you have explicit, prior, written authorization. Unauthorized scanning is illegal and unethical. * **Network Exposure:** If mapping ZAP's port (`-p 8888:8888`), ensure your host firewall restricts access if the machine is on an untrusted network. The configured ZAP API key provides control over the instance. * **Input Validation:** Although MCP provides structured input, the underlying tools might still be vulnerable to crafted arguments if not handled robustly within the Python wrapper functions. ## Contributing Contributions are highly encouraged! Fork the repository, create a feature branch, and submit a pull request. Please ensure adherence to ethical testing guidelines in all contributions. Bug reports and feature suggestions are welcome via GitHub Issues. ## License This project is distributed under the terms of the [MIT License](LICENSE). ## Disclaimer **This software is intended SOLELY for educational purposes and authorized, ethical security testing.** Any use against systems without explicit permission is strictly prohibited and illegal. The authors and contributors assume NO liability for misuse or damage resulting from this program. **Use at your own risk and ensure compliance with all applicable laws and agreements.** ## Acknowledgements Profound inspiration for this project comes from [Laurie Kirk](https://github.com/LaurieWired/)'s groundbreaking work on [GhidraMCP](https://github.com/LaurieWired/GhidraMCP).