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

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

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.

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):

export OPENAI_API_KEY="your-openai-api-key"

For Google (e.g., Gemini):

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.

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:

{
    "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.

python main.py

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

• Change Models:

  python main.py --reasoning gpt-4o --parsing gpt-4o
  

• List Available Models:

  python main.py --models
  

• Specify a Custom MCP Config Path:

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