Metadata-Version: 2.4
Name: iflow-mcp_ramkansal-pentestmcp
Version: 0.1.0
Summary: Penetration testing MCP server with security tools
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.26.0
Requires-Dist: psutil>=7.0.0
Requires-Dist: requests>=2.32.3
Description-Content-Type: text/markdown

[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/ram001-code-pentestmcp-badge.png)](https://mseep.ai/app/ram001-code-pentestmcp)

[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/baf52bdd-53df-484e-9b56-2ee38c8f3027)
# pentestMCP: AI-Powered Penetration Testing via MCP

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
<!-- Example badges (replace placeholders/add relevant ones) -->
<!-- [![Build Status](https://img.shields.io/travis/com/Ram001-code/pentestMCP.svg?style=flat-square)](https://travis-ci.com/Ram001-code/pentestMCP) -->
<!-- [![GitHub issues](https://img.shields.io/github/issues/Ram001-code/pentestMCP?style=flat-square)](https://github.com/Ram001-code/pentestMCP/issues) -->
<!-- [![GitHub forks](https://img.shields.io/github/forks/Ram001-code/pentestMCP?style=flat-square)](https://github.com/Ram001-code/pentestMCP/network) -->
<!-- [![GitHub stars](https://img.shields.io/github/stars/Ram001-code/pentestMCP?style=flat-square)](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

The recommended way to use pentestMCP is via the pre-built Docker image.

### Using Pre-built Docker Image (Recommended)

This avoids local build times and dependency issues.

1.  **Pull the image from Docker Hub:**
    ```bash
    docker pull ramgameer/pentest-mcp:latest
    ```
    *(This image name needs to exist on Docker Hub for this command to work)*

### Building Docker Image Locally
**(Before Installing, NOTE THAT THIS CODE WILL BE ONLY EFFICIENT IN LINUX ONLY)**

Use this option if you want to modify the code, use the absolute latest version, or the pre-built image is unavailable.

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. **NOTE: FOR SCANS THAT REQUIRE WORDLISTS, YOU MUST CLONE THE SECLISTS REPO AS FOLLOW**
    ```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.
    *   `run_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.
    *   `run_dig_tool`: Executes DNS `dig` queries.
    *   `fetch_whois_data`: Retrieves WHOIS information for a domain.
    *   `run_curl`: Executes cURL commands for HTTP interaction.
*   **Vulnerability Scanning:**
    *   `launch_nuclei_scan`/`fetch_nuclei_results`: Runs template-based vulnerability scans with ProjectDiscovery's Nuclei asynchronously.
    *   `run_wpscan`: Performs WordPress vulnerability scans using WPScan.
*   **Web Application Scanning (ZAP):**
    *   `run_zap_tool`: (Potentially a general ZAP command executor - verify implementation).
    *   `run_zap_active_scan`/`check_scan_status`/`active_scan_results`: Manages ZAP's active scanner.
    *   `run_ajax_spider`/`check_ajax_spider_status`/`get_ajax_spider_results`: Manages ZAP's AJAX Spider for SPAs.
*   **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.

## 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).
