PentestGPT-MCP

KO | EN

gitlite — search

#javascript #ai #llm #golang #rust #linux #macos #java #windows #awesome #awesome-list #vue #openai #open-source

(★ 17)

An automated pentesting agent that thinks with an LLM and acts with MCP.

PentestGPT-MCP Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# PentestGPT-MCP

This project is an advanced penetration testing tool based on the original "PentestGPT" paper. It extends the core capabilities by integrating with Model Context Protocol servers (MCPs) to perform automated, LLM-driven security assessments.

It is based on the PentestGPT project.
* Original GitHub Repository: https://github.com/GreyDGL/PentestGPT
* Original Research Paper (USENIX Security '24): https://www.usenix.org/conference/usenixsecurity24/presentation/deng

[🇰🇷 Read this in Korean](./README-kr.md)

## Features

- **Dynamic MCP Server Integration**: Connects to various tool servers running locally or remotely via a flexible `mcp_servers.json` configuration file.
- **Automated Task Execution (`auto` mode)**: Automatically executes LLM-suggested tasks using tools provided by a connected MCP server.
- **Interactive "Human-in-the-Loop" Mode**: Supports user confirmation before each tool execution, enhancing safety and control during automated scans.
- **Flexible Model Support**: Works with a wide range of LLM providers, including OpenAI (GPT series) and Google (Gemini series).

## Installation

### 1. Clone the Repository and Set Up a Virtual Environment

```bash
git clone https://github.com/your-username/PentestGPT-MCP.git
cd PentestGPT-MCP
python -m venv venv
source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
```

### 2. Install Dependencies

Install the required Python packages from `requirements.txt`.

```bash
pip install -r requirements.txt
```

### 3. Configure API Keys

PentestGPT-MCP requires API keys to interact with Large Language Models. Set the appropriate environment variables for the model you wish to use.

**For OpenAI (e.g., gpt-4o):**
```bash
export OPENAI_API_KEY="your-openai-api-key"
```

**For Google (e.g., Gemini):**
```bash
export GOOGLE_API_KEY="your-google-api-key"
```

### 4. Set Up MCP Servers

The tool manages connections to MCP servers through a central JSON configuration file.

**1. Copy the Example Configuration**

Copy the example file from the `config/` directory to the project root.

```bash
cp config/mcp_servers.json.example ./mcp_servers.json
```

**2. Edit the Configuration File**

Open `mcp_servers.json` and customize it to match your environment.

**Configuration Example:**
```json
{
    "mcpServers": {
        "pentest-tools": {
            "command": "python",
            "args": [
                "mcp_servers/pentest_tools_server.py"
            ]
        },
        "kali_mcp": {
            "command": "python3",
            "args": [
                "/absolute/path/to/mcp_server.py",
                "http://LINUX_IP:5000/"
            ]
        }
    }
}
```

**Configuration Structure:**
- **`mcpServers`**: The root object containing all server configurations.
- **`"server-name"`**: A unique, user-defined name for each server (e.g., `"pentest-tools"`).
- **`command`**: The command to execute the server (e.g., `python`, `python3`, `node`).
- **`args`**: An array of arguments to pass to the command. The first argument is typically the path to the server script.

**Important**: The default `mcp_servers/pentest_tools_server.py` assumes that tools like `nmap` and `dirb` are installed and available in the system's PATH. It is highly recommended to run this in an environment where these tools are present, such as Kali Linux.

## Usage

### 1. Running PentestGPT-MCP

Start the application from the project root directory.

```bash
python main.py
```

You can use several command-line arguments to customize the session:

- **Change Models**:
  ```bash
  python main.py --reasoning gpt-4o --parsing gpt-4o
  ```
- **List Available Models**:
  ```bash
  python main.py --models
  ```
- **Specify a Custom MCP Config Path**:
  ```bash
  python main.py --mcp-config /path/to/your/mcp_servers.json
  ```

### 2. Basic Workflow

1.  **Provide Initial Information**: When prompted, briefly describe the penetration testing target and objective.
    ```
    Please describe the penetration testing task in one line...
    > Penetration test on the web server at http://10.0.2.15
    ```

2.  **Get Task Suggestions (`next` or `todo`)**:
    -   **`next`**: Input the results from a manual scan or any text you want to analyze. PentestGPT will process the input and suggest the next steps in the Penetration Testing Tree (PTT).
    -   **`todo`**: Ask PentestGPT to recommend the next task based on the current PTT.

3.  **Execute Automated Tasks (`auto`)**:
    -   Type `auto` at the prompt to execute the most recently suggested task via an MCP server.
    -   You will be asked to select which configured MCP server to use for the task.
    -   Choose the interactive mode (`y`) to review and confirm each tool command before execution, ensuring a safe and controlled process.

### Command Reference

-   `next`: Submit test results for analysis and receive suggestions for the next task.
-   `todo`: Ask for a recommendation on what to do next.
-   `more`: Request a more detailed explanation of the current task.
-   `auto`: Automatically execute the latest suggested task using a connected MCP server.
-   `discuss`: Engage in a free-form conversation with PentestGPT.
-   `quit`: End the current session (you will be prompted to save the session before exiting).

PentestGPT-MCP

PentestGPT-MCP Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

PentestGPT-MCP

PentestGPT-MCP Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README