### Install Legacy Version

Source: https://github.com/greydgl/pentestgpt/blob/main/README.md

Instructions for installing and running the archived v0.15 version of PentestGPT which supports multiple LLM providers.

```bash
cd legacy && pip install -e . && pentestgpt --reasoning gpt-4o
```

--------------------------------

### Install and Configure PentestGPT

Source: https://github.com/greydgl/pentestgpt/blob/main/README.md

Commands to clone the repository, build the Docker environment, and perform initial configuration.

```bash
git clone --recurse-submodules https://github.com/GreyDGL/PentestGPT.git
cd PentestGPT
make install
make config
make connect
```

--------------------------------

### Generate CTF System Prompts

Source: https://context7.com/greydgl/pentestgpt/llms.txt

Illustrates how to retrieve and customize system prompts for Capture The Flag (CTF) challenges using the 'pentestgpt.prompts.pentesting' module. It shows how to get the base prompt and append custom instructions for specific scenarios. No external dependencies beyond the 'pentestgpt' library.

```python
from pentestgpt.prompts.pentesting import get_ctf_prompt, CTF_SYSTEM_PROMPT

# Get base CTF system prompt
base_prompt = CTF_SYSTEM_PROMPT
print(f"Prompt length: {len(base_prompt)} chars")

# Get prompt with custom instructions appended
custom_prompt = get_ctf_prompt(
    custom_instruction="This is a web challenge. The flag format is FLAG{...}. "
                       "Focus on SQL injection and authentication bypass."
)

# The prompt includes:
# - CTF methodology (recon, vuln discovery, exploitation, flag extraction)
# - Category-specific guidance (Web, PWN, Crypto, Forensics, Reversing)
# - Flag pattern recognition (flag{}, HTB{}, CTF{}, 32-char hex)
# - Fallback strategies for when stuck
# - Persistence directives (never give up until flags captured)
# - Tool recommendations (nmap, gobuster, sqlmap, etc.)

print(custom_prompt[:500])
```

--------------------------------

### Run PentestGPT Benchmarks

Source: https://github.com/greydgl/pentestgpt/blob/main/README.md

Executes the standalone benchmark runner to validate the installation and agent performance.

```bash
cd benchmark/standalone-xbow-benchmark-runner
python3 run_benchmarks.py --range 1-1 --pattern-flag
```

--------------------------------

### Run PentestGPT Benchmarks with Standalone Runner

Source: https://context7.com/greydgl/pentestgpt/llms.txt

Provides command-line examples for executing the standalone benchmark runner against the XBOW validation suite. It covers running specific ranges or IDs, all benchmarks, custom timeouts, resuming interrupted runs, retrying failures, and using different models. Requires Python 3 and the benchmark runner script.

```bash
cd benchmark/standalone-xbow-benchmark-runner

# Run specific range of benchmarks
python3 run_benchmarks.py --range 1-10 --pattern-flag

# Run specific benchmark IDs
python3 run_benchmarks.py --ids 1,5,10,25 --pattern-flag

# Run all 104 benchmarks
python3 run_benchmarks.py --all --pattern-flag

# Custom timeout (30 minutes per benchmark)
python3 run_benchmarks.py --range 1-10 --timeout 1800 --pattern-flag

# Resume interrupted run
python3 run_benchmarks.py --range 1-50 --resume --pattern-flag

# Retry only failed benchmarks from last run
python3 run_benchmarks.py --retry-failed --pattern-flag

# Retry failed from specific run directory
python3 run_benchmarks.py --retry-failed ./logs/benchmark_run_20250115_120000 --pattern-flag

# Use different model
python3 run_benchmarks.py --range 1-10 --model opus --pattern-flag

# Dry run to preview execution
python3 run_benchmarks.py --dry-run --range 1-5
```

--------------------------------

### Run PentestGPT TUI Application

Source: https://context7.com/greydgl/pentestgpt/llms.txt

Shows how to launch the PentestGPT Textual-based TUI for interactive pentesting. It covers starting a new session with specific targets and instructions, or creating a custom application instance. Dependencies include the 'pentestgpt' and 'textual' libraries.

```python
import asyncio
from pentestgpt.interface.tui import run_tui, PentestGPTApp

# Run TUI with target
async def start_tui():
    await run_tui(
        target="10.10.11.234",
        custom_instruction="WordPress with outdated plugins",
        model="claude-sonnet-4-5-20250929",
        debug=True,
        resume_session=None  # Or session ID to resume
    )

# Or create app directly for customization
async def custom_tui():
    app = PentestGPTApp(
        target="10.10.11.234",
        custom_instruction="Focus on web exploitation",
        model=None,  # Use default
        debug=False,
        resume_session="abc12345"
    )
    await app.run_async()

# Keyboard shortcuts in TUI:
# F1        - Help screen
# Ctrl+P    - Pause/Resume agent
# Ctrl+Q    - Quit confirmation
# Ctrl+C    - Quit
# Up/Down   - Scroll activity feed
# PgUp/PgDn - Fast scroll
# Enter     - Send instruction (when paused)

asyncio.run(start_tui())
```

--------------------------------

### Manage asciinema recordings

Source: https://github.com/greydgl/pentestgpt/blob/main/demo/README.md

Commands to install the asciinema CLI tool, play local recording files, and upload them to the asciinema service. These commands require Python and pip to be installed on the system.

```bash
# Install asciinema
pip install asciinema

# Play a recording
asciinema play demo/install.cast
asciinema play demo/demo.cast

# Upload recordings
asciinema upload demo/install.cast
asciinema upload demo/demo.cast
```

--------------------------------

### Docker Compose Configuration (docker-compose.yml)

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/README.md

Example of a `docker-compose.yml` file used to define the containerized environment for a specific benchmark challenge. This file specifies services, images, ports, and volumes.

```yaml
version: "3.7"
services:
  app: # Example service name
    build: ./challenge
    ports:
      - "8001:80"
    environment:
      - FLAG=HTB{...}
```

--------------------------------

### Initialize Benchmark Runner

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/standalone-xbow-benchmark-runner/README.md

Prepares the benchmark runner script by navigating to the directory and setting the necessary execution permissions.

```bash
cd PentestGPT/benchmark/standalone-xbow-benchmark-runner
chmod +x run_benchmarks.py
```

--------------------------------

### Execute Benchmarks via CLI

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/standalone-xbow-benchmark-runner/USAGE.md

Demonstrates various ways to run benchmarks, including range selection, specific IDs, resumption of interrupted tasks, and timeout adjustments.

```bash
# Run a single benchmark
python3 run_benchmarks.py --range 1-1

# Run a range of benchmarks
python3 run_benchmarks.py --range 1-5

# Run specific benchmarks by ID
python3 run_benchmarks.py --ids 1,5,10,15,20

# Run with resumption
python3 run_benchmarks.py --range 1-50 --resume

# Run with extended timeout
python3 run_benchmarks.py --range 1-10 --timeout 1800
```

--------------------------------

### Execute Benchmarks via CLI

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/standalone-xbow-benchmark-runner/README.md

Demonstrates how to run benchmarks using different selection strategies and configuration flags. These commands are executed via the run_benchmarks.py script.

```bash
# Run benchmarks 1-10
python run_benchmarks.py --range 1-10

# Run specific benchmarks
python run_benchmarks.py --ids 1,5,10,25

# Run all 104 benchmarks
python run_benchmarks.py --all
```

--------------------------------

### Manage Docker Environment

Source: https://context7.com/greydgl/pentestgpt/llms.txt

Commands to build, run, and maintain the PentestGPT containerized environment. Includes repository cloning, configuration, and lifecycle management.

```bash
git clone --recurse-submodules https://github.com/GreyDGL/PentestGPT.git
cd PentestGPT
make install
make config
make connect
pentestgpt --target 10.10.11.234
make stop
make clean-docker
```

--------------------------------

### Execute Benchmarks with Flag Validation Modes

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/standalone-xbow-benchmark-runner/README.md

Demonstrates how to run benchmarks using different flag validation strategies: standard verification, accepting any flag, or enforcing pattern-based validation.

```bash
python3 run_benchmarks.py --range 1-10
python3 run_benchmarks.py --range 1-10 --any-flag
python3 run_benchmarks.py --range 1-10 --pattern-flag
```

--------------------------------

### Verify Docker Container Prerequisites

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/standalone-xbow-benchmark-runner/README.md

Checks if the required PentestGPT Docker container is correctly initialized and accessible for the benchmark runner.

```bash
docker ps -a | grep pentestgpt
```

--------------------------------

### Manage PentestGPT Configuration

Source: https://context7.com/greydgl/pentestgpt/llms.txt

Shows how to load and customize PentestGPT configurations using Pydantic models. This allows for programmatic control over LLM settings, working directories, and operational modes.

```python
from pentestgpt.core.config import PentestGPTConfig, load_config
from pathlib import Path

# Load config from environment with overrides
config = load_config(
    target="10.10.11.234",
    llm_model="claude-sonnet-4-5-20250929",
    custom_instruction="Focus on web vulnerabilities",
    working_directory=Path("/workspace"),
    verbose=True
)

# Access configuration properties
print(f"Target: {config.target}")
print(f"Model: {config.llm_model}")
print(f"Working directory: {config.working_directory}")
print(f"Permission mode: {config.permission_mode}")

# Create config directly with Pydantic validation
custom_config = PentestGPTConfig(
    target="https://ctf.example.com",
    llm_model="claude-opus-4-20250514",
    max_iterations=500,
    interface_mode="cli"  # "tui" or "cli"
)
```

--------------------------------

### Execute Benchmarks with Custom Output

Source: https://context7.com/greydgl/pentestgpt/llms.txt

Run the benchmark suite using a specific output directory and pattern flag. This is useful for tracking results across multiple test iterations.

```bash
python3 run_benchmarks.py --range 1-10 --output-dir ./my_results --pattern-flag
```

--------------------------------

### Verify Benchmark Prerequisites

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/standalone-xbow-benchmark-runner/USAGE.md

Checks if the required PentestGPT Docker container is present and verifies the availability of benchmark files in the directory.

```bash
# Check PentestGPT container exists
docker ps -a | grep pentestgpt

# Check benchmarks are available
ls ../xbow-validation-benchmarks/benchmarks/ | head
```

--------------------------------

### Execute PentestGPT CLI Commands

Source: https://context7.com/greydgl/pentestgpt/llms.txt

Demonstrates various ways to invoke the PentestGPT command-line interface, including interactive TUI mode, non-interactive automation, session management, and debugging options.

```bash
# Interactive TUI mode (default) - HTB machine
pentestgpt --target 10.10.11.234

# Web challenge with context hints
pentestgpt --target https://ctf.example.com/challenge1 --instruction "WordPress site, focus on plugin vulnerabilities"

# Non-interactive mode for automation
pentestgpt --target challenge.htb --non-interactive

# Custom model selection
pentestgpt --target 10.10.11.50 --model claude-opus-4-20250514

# Resume previous session
pentestgpt --target 10.10.11.234 --resume

# Resume specific session by ID
pentestgpt --target 10.10.11.234 --session-id abc12345

# List available sessions
pentestgpt --target 10.10.11.234 --list-sessions

# Raw debugging mode with streaming output
pentestgpt --target 10.10.11.100 --raw --debug

# Disable telemetry
pentestgpt --target 10.10.11.234 --no-telemetry
```

--------------------------------

### Execute PentestGPT Scans

Source: https://github.com/greydgl/pentestgpt/blob/main/README.md

Demonstrates running the tool in interactive TUI mode, non-interactive mode, and with specific target instructions.

```bash
pentestgpt --target 10.10.11.234
pentestgpt --target 10.10.11.100 --non-interactive
pentestgpt --target 10.10.11.50 --instruction "WordPress site, focus on plugin vulnerabilities"
```

--------------------------------

### Benchmark Suite Directory Structure

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/README.md

Illustrates the standard file and directory layout for a benchmark suite, including metadata, container configuration, and challenge/solution code.

```tree
benchmark/
├── <benchmark-suite-name>/
│   ├── <BENCHMARK-ID>/
│   │   ├── benchmark.json        # Metadata (name, tags, level, port)
│   │   ├── docker-compose.yml    # Container configuration
│   │   ├── challenge/            # Vulnerable application code
│   │   └── solution/             # Reference solution (optional)
│   └── ...
└── standalone-<suite>-runner/    # Automated runner (optional)
```

--------------------------------

### Monitor and Debug Benchmarks

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/standalone-xbow-benchmark-runner/USAGE.md

Provides commands for real-time log monitoring, checking Docker container status, and manually testing individual components like the output parser.

```bash
# Watch logs in real-time
tail -f logs/benchmark_run_*/detailed.log

# Test parser
python3 tests/test_output_parser.py

# Manual Docker lifecycle check
cd ../xbow-validation-benchmarks/benchmarks/XBEN-001-24
make build
docker compose up -d --wait
docker compose down
```

--------------------------------

### Advanced Benchmark Configuration

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/standalone-xbow-benchmark-runner/README.md

Shows advanced usage including custom timeouts, resuming interrupted runs, and model selection. These options allow for fine-tuned control over the execution environment.

```bash
# Custom timeout (30 minutes)
python run_benchmarks.py --range 1-10 --timeout 1800

# Resume interrupted run
python run_benchmarks.py --range 1-50 --resume

# Use Claude Opus
python run_benchmarks.py --range 1-10 --model opus
```

--------------------------------

### Execute XBOW Benchmarks

Source: https://github.com/greydgl/pentestgpt/blob/main/README.md

Commands to run the PentestGPT validation benchmark suite. Supports running specific ranges, all tests, retrying failures, or performing a dry run.

```bash
cd benchmark/standalone-xbow-benchmark-runner
python3 run_benchmarks.py --range 1-10 --pattern-flag
python3 run_benchmarks.py --all --pattern-flag
python3 run_benchmarks.py --retry-failed
python3 run_benchmarks.py --dry-run --range 1-5
```

--------------------------------

### Retry Failed Benchmark Runs

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/standalone-xbow-benchmark-runner/README.md

Shows how to re-run previously failed benchmarks from the most recent session or a specific log directory, with an option to preview the action via dry-run.

```bash
python3 run_benchmarks.py --retry-failed
python3 run_benchmarks.py --retry-failed logs/benchmark_run_20251216_141221
python3 run_benchmarks.py --retry-failed --dry-run
```

--------------------------------

### Interact with Claude Code Backend

Source: https://context7.com/greydgl/pentestgpt/llms.txt

Demonstrates how to connect to, send queries to, and process responses from the Claude Code backend. It covers session management, message types (TEXT, TOOL_START, TOOL_RESULT, RESULT), and resuming previous sessions. Requires the 'pentestgpt' library.

```python
import asyncio
from pentestgpt.core.backend import (
    AgentBackend,
    ClaudeCodeBackend,
    AgentMessage,
    MessageType
)

async def use_claude_backend():
    # Create Claude Code backend
    backend = ClaudeCodeBackend(
        working_directory="/workspace",
        system_prompt="You are a CTF solver. Find and capture flags.",
        model="claude-sonnet-4-5-20250929",
        permission_mode="bypassPermissions"
    )

    try:
        # Connect to Claude Code CLI
        await backend.connect()
        print(f"Connected, session: {backend.session_id}")

        # Send a query
        await backend.query("Scan target 10.10.11.234 and enumerate services")

        # Process streaming messages
        async for msg in backend.receive_messages():
            if msg.type == MessageType.TEXT:
                print(f"Agent: {msg.content}")
            elif msg.type == MessageType.TOOL_START:
                print(f"Tool started: {msg.tool_name}")
                print(f"Args: {msg.tool_args}")
            elif msg.type == MessageType.TOOL_RESULT:
                print(f"Tool result: {msg.content}")
            elif msg.type == MessageType.RESULT:
                cost = msg.metadata.get("cost_usd", 0)
                print(f"Completed. Cost: ${cost:.4f}")

        # Resume a previous session
        if backend.supports_resume:
            success = await backend.resume("previous_session_id")
            print(f"Resume success: {success}")

    finally:
        await backend.disconnect()

asyncio.run(use_claude_backend())
```

--------------------------------

### Configure Model Selection

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/standalone-xbow-benchmark-runner/USAGE.md

Allows switching between different Claude models (opus, sonnet, haiku) to balance performance, cost, and accuracy for specific benchmark levels.

```bash
# Run with specific model
python3 run_benchmarks.py --range 1-1 --model opus
python3 run_benchmarks.py --range 1-1 --model sonnet
python3 run_benchmarks.py --range 1-1 --model haiku
```

--------------------------------

### Docker Compose Configuration

Source: https://context7.com/greydgl/pentestgpt/llms.txt

Infrastructure definition for running PentestGPT with persistent volumes and environment variables for API authentication.

```yaml
services:
  pentestgpt:
    build: .
    container_name: pentestgpt
    volumes:
      - ./workspace:/workspace
      - claude-config:/home/pentester/.claude
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
    stdin_open: true
    tty: true

volumes:
  claude-config:
```

--------------------------------

### Orchestrate Agent Sessions

Source: https://context7.com/greydgl/pentestgpt/llms.txt

Demonstrates how to use the AgentController to manage the lifecycle of a penetration testing session, including running tasks, state monitoring, and injecting instructions.

```python
import asyncio
from pentestgpt.core.config import load_config
from pentestgpt.core.controller import AgentController, AgentState

async def run_pentest_session():
    # Configure the agent
    config = load_config(
        target="10.10.11.234",
        custom_instruction="HTB machine, likely web-based initial foothold"
    )

    # Create controller
    controller = AgentController(config)

    # Check current state
    print(f"Initial state: {controller.state")  # AgentState.IDLE

    # Build task description
    task = f"Solve this CTF challenge and capture the flag(s): {config.target}"

    # Run the agent
    result = await controller.run(task)

    if result["success"]:
        print(f"Flags found: {result['flags_found']}")
        print(f"Session ID: {result['session_id']}")
        print(f"Cost: ${result['cost_usd']:.4f}")
    else:
        print(f"Error: {result['error']}")

    return result

# Pause/resume control (typically called from TUI)
async def control_agent(controller: AgentController):
    # Pause at next safe point
    if controller.state == AgentState.RUNNING:
        controller.pause()

    # Resume with optional instruction
    if controller.state == AgentState.PAUSED:
        controller.resume(instruction="Try SQL injection on login form")

    # Inject instruction during execution
    controller.inject("Focus on privilege escalation via SUID binaries")

    # Stop the agent
    controller.stop()

asyncio.run(run_pentest_session())
```

--------------------------------

### Configure Claude Model Selection

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/standalone-xbow-benchmark-runner/README.md

Allows users to specify which Claude model (Sonnet, Opus, or Haiku) to utilize for the benchmark execution, impacting performance and cost.

```bash
python3 run_benchmarks.py --range 1-10 --model sonnet
python3 run_benchmarks.py --range 1-10 --model opus
python3 run_benchmarks.py --range 1-10 --model haiku
```

--------------------------------

### Benchmark Metadata Structure (benchmark.json)

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/README.md

Defines the schema for the `benchmark.json` file, which contains essential metadata for each benchmark, such as name, description, difficulty level, tags, and network port.

```json
{
  "name": "XBEN-001-24",
  "description": "SQL Injection vulnerability",
  "level": 1,
  "tags": ["sqli", "web"],
  "port": 8001,
  "flag_format": "HTB{...}"
}
```

--------------------------------

### Manage Flag Validation Modes

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/standalone-xbow-benchmark-runner/USAGE.md

Configures how the benchmark tool validates captured flags, supporting standard matching, any-flag detection, or strict pattern-based validation.

```bash
# Standard mode: Exact flag matching
python3 run_benchmarks.py --range 1-10

# Any-flag mode: Accept any detected flag
python3 run_benchmarks.py --range 1-10 --any-flag

# Pattern-flag mode: Only accept flags with strict format
python3 run_benchmarks.py --range 1-10 --pattern-flag
```

--------------------------------

### Convenience Function for Quick Execution

Source: https://context7.com/greydgl/pentestgpt/llms.txt

This function provides a high-level interface for running penetration tests. It includes automatic session management and retry logic for robust execution.

```APIDOC
## Convenience Function for Quick Execution

### Description
High-level function for running penetration tests with automatic session management and retry logic.

### Method
Asynchronous Function Call

### Endpoint
`run_pentest()`

### Parameters
#### Function Parameters
- **target** (string) - Required - The target IP address or hostname for the penetration test.
- **custom_instruction** (string) - Optional - Specific instructions to guide the penetration test.
- **model** (string) - Optional - The AI model to use for the test (e.g., "claude-sonnet-4-5-20250929").
- **working_dir** (string) - Optional - The directory for storing temporary files and results.
- **debug** (boolean) - Optional - Enables debug logging.
- **resume_session** (string) - Optional - The ID of a previous session to resume.

### Request Example
```python
import asyncio
from pentestgpt.core.agent import run_pentest

async def solve_ctf_challenge():
    result = await run_pentest(
        target="10.10.11.234",
        custom_instruction="WordPress site with vulnerable plugin",
        model="claude-sonnet-4-5-20250929",
        working_dir="/workspace",
        debug=True
    )
    # ... process result ...

asyncio.run(solve_ctf_challenge())
```

### Response
#### Success Response (200)
- **success** (boolean) - True if the test was successful, False otherwise.
- **flags_found** (array) - A list of dictionaries, each containing 'flag' and 'context' of found flags.
- **cost_usd** (float) - The total cost of the test in USD.
- **session_id** (string) - The ID of the current session.

#### Error Response
- **success** (boolean) - False.
- **error** (string) - Description of the error.

#### Response Example (Success)
```json
{
  "success": true,
  "flags_found": [
    {
      "flag": "HTB{example_flag}",
      "context": "Found in /root/flag.txt"
    }
  ],
  "cost_usd": 1.2345,
  "session_id": "sess_abcdef12345"
}
```

#### Response Example (Failure)
```json
{
  "success": false,
  "error": "Target unreachable: Connection timed out."
}
```
```

--------------------------------

### PentestGPT Session Management

Source: https://context7.com/greydgl/pentestgpt/llms.txt

File-based session persistence system for saving and resuming penetration testing sessions using the `pentestgpt.core.session` module. It stores session metadata, flags found, cost tracking, and user instructions. Key operations include creating, updating status, adding flags and instructions, tracking costs, saving, listing, loading, and deleting sessions.

```python
from pentestgpt.core.session import SessionStore, SessionInfo, SessionStatus

# Initialize session store (uses ~/.pentestgpt/sessions/ by default)
sessions = SessionStore()

# Create a new session
session = sessions.create(
    target="10.10.11.234",
    task="Solve HTB machine and capture both flags",
    model="claude-sonnet-4-5-20250929"
)
print(f"Created session: {session.session_id}")

# Update session status
sessions.update_status(SessionStatus.RUNNING)

# Add found flags
sessions.add_flag(
    flag="user_flag_abc123",
    context="Found in /home/user/user.txt after SSH access"
)

# Track user instructions
sessions.add_instruction("Focus on kernel exploit for root")

# Track costs
sessions.add_cost(0.42)

# Save session (automatically called by update methods)
sessions.save()

# List all sessions
all_sessions = sessions.list_sessions()
for s in all_sessions:
    print(f"{s.session_id}: {s.target} - {s.status.value} ({len(s.flags_found)} flags)")

# List sessions for specific target
target_sessions = sessions.list_sessions(target="10.10.11.234")

# Get most recent session
latest = sessions.get_latest(target="10.10.11.234")
if latest:
    print(f"Latest session: {latest.session_id}")
    print(f"Status: {latest.status.value}")
    print(f"Flags: {latest.flags_found}")
    print(f"Cost: ${latest.total_cost_usd:.4f}")

# Load specific session
loaded = sessions.load("abc12345")
if loaded:
    print(f"Loaded: {loaded.to_dict()}")

# Delete session
sessions.delete("abc12345")
```

--------------------------------

### Cite PentestGPT

Source: https://github.com/greydgl/pentestgpt/blob/main/README.md

BibTeX citation format for referencing the PentestGPT research paper in academic work.

```bibtex
@inproceedings{299699,
  author = {Gelei Deng and Yi Liu and Víctor Mayoral-Vilches and Peng Liu and Yuekang Li and Yuan Xu and Tianwei Zhang and Yang Liu and Martin Pinzger and Stefan Rass},
  title = {{PentestGPT}: Evaluating and Harnessing Large Language Models for Automated Penetration Testing},
  booktitle = {33rd USENIX Security Symposium (USENIX Security 24)},
  year = {2024},
  isbn = {978-1-939133-44-1},
  address = {Philadelphia, PA},
  pages = {847--864},
  url = {https://www.usenix.org/conference/usenixsecurity24/presentation/deng},
  publisher = {USENIX Association},
  month = aug
}
```

--------------------------------

### Retry Failed Benchmarks

Source: https://github.com/greydgl/pentestgpt/blob/main/benchmark/standalone-xbow-benchmark-runner/USAGE.md

Automates the process of identifying and re-running failed benchmarks from previous logs, with options for dry-runs and specific log directory targeting.

```bash
# Automatically find and retry from last run
python3 run_benchmarks.py --retry-failed

# Preview what will be retried
python3 run_benchmarks.py --retry-failed --dry-run

# Retry from a specific log directory
python3 run_benchmarks.py --retry-failed logs/benchmark_run_20251215_172437
```

--------------------------------

### PentestGPT Event Bus System

Source: https://context7.com/greydgl/pentestgpt/llms.txt

A thread-safe publish/subscribe event bus for decoupled communication within PentestGPT, particularly between the TUI and the agent. It uses a singleton pattern for consistent event routing. Key functionalities include subscribing to various event types (STATE_CHANGED, FLAG_FOUND, TOOL, MESSAGE, COMMAND, INPUT), emitting events, and unsubscribing. The EventBus is part of the pentestgpt.core.events module.

```python
from pentestgpt.core.events import EventBus, EventType, Event

# Get singleton instance
events = EventBus.get()

# Subscribe to events
def on_state_change(event: Event):
    state = event.data.get("state")
    details = event.data.get("details", "")
    print(f"Agent state: {state} - {details}")

def on_flag_found(event: Event):
    flag = event.data.get("flag")
    context = event.data.get("context", "")
    print(f"FLAG CAPTURED: {flag}")

def on_tool_execution(event: Event):
    status = event.data.get("status")  # "start" or "complete"
    name = event.data.get("name")
    args = event.data.get("args", {{}})
    print(f"Tool {name}: {status} - {args}")

# Register handlers
events.subscribe(EventType.STATE_CHANGED, on_state_change)
events.subscribe(EventType.FLAG_FOUND, on_flag_found)
events.subscribe(EventType.TOOL, on_tool_execution)
events.subscribe(EventType.MESSAGE, lambda e: print(f"Message: {e.data.get('text')}"))

# Emit events (typically from agent)
events.emit_state("running", "Connecting to Claude Code")
events.emit_message("Starting reconnaissance...", msg_type="info")
events.emit_tool(status="start", name="Bash", args={"command": "nmap -sV 10.10.11.234"})
events.emit_flag("HTB{example_flag_here}", context="Found in /root/root.txt")

# Emit user commands (from TUI to agent)
events.emit_command("pause")
events.emit_input("Try different port for reverse shell")

# Unsubscribe when done
events.unsubscribe(EventType.FLAG_FOUND, on_flag_found)

# Reset for testing
EventBus.reset()
```

--------------------------------

### Execute Penetration Tests with PentestGPT

Source: https://context7.com/greydgl/pentestgpt/llms.txt

High-level Python function for running penetration tests. It handles automatic session management and includes retry logic. Dependencies include asyncio and the pentestgpt.core.agent module. It takes target, custom instructions, model, working directory, and debug flags as input, and returns a dictionary indicating success or failure, along with found flags, cost, and session ID.

```python
import asyncio
from pentestgpt.core.agent import run_pentest

async def solve_ctf_challenge():
    # Basic usage
    result = await run_pentest(
        target="10.10.11.234",
        custom_instruction="WordPress site with vulnerable plugin",
        model="claude-sonnet-4-5-20250929",
        working_dir="/workspace",
        debug=True
    )

    if result["success"]:
        for flag_data in result["flags_found"]:
            print(f"Flag: {flag_data['flag']}")
            print(f"Context: {flag_data['context'][:100]}...")
        print(f"Total cost: ${result['cost_usd']:.4f}")
        print(f"Session: {result['session_id']}")
    else:
        print(f"Failed: {result['error']}")

# Resume a previous session
async def resume_session():
    result = await run_pentest(
        target="10.10.11.234",
        resume_session="abc12345"  # Session ID to resume
    )
    return result

asyncio.run(solve_ctf_challenge())
```

--------------------------------

### Configure Local LLM Routing

Source: https://context7.com/greydgl/pentestgpt/llms.txt

JSON configuration for routing requests to local LLM servers via an OpenAI-compatible API. Defines base URLs and model selection for different agent tasks.

```json
{
  "localLLM": {
    "api_base_url": "http://host.docker.internal:1234/v1",
    "models": ["openai/gpt-oss-20b", "qwen/qwen3-coder-30b"]
  },
  "router": {
    "default": "openai/gpt-oss-20b",
    "background": "openai/gpt-oss-20b",
    "think": "qwen/qwen3-coder-30b",
    "longContext": "qwen/qwen3-coder-30b",
    "webSearch": "openai/gpt-oss-20b"
  }
}
```

--------------------------------

### Session Management

Source: https://context7.com/greydgl/pentestgpt/llms.txt

Manages file-based persistence for penetration testing sessions, storing metadata, found flags, cost tracking, and user instructions.

```APIDOC
## Session Management

### Description
File-based session persistence system for saving and resuming penetration testing sessions. Stores session metadata, flags found, cost tracking, and user instructions.

### Method
Session Store Operations

### Endpoint
`SessionStore` class

### Parameters
#### SessionStore Methods
- **__init__(path=None)**: Initializes the session store. Uses `~/.pentestgpt/sessions/` by default.
- **create(**target**, **task**, **model**, **custom_instruction**=None, **working_dir**=None)**: Creates and returns a new session.
- **update_status(**session_id**, **status**)**: Updates the status of a specific session.
- **add_flag(**session_id**, **flag**, **context**)**: Adds a found flag to a session.
- **add_instruction(**session_id**, **instruction**)**: Adds a user instruction to a session.
- **add_cost(**session_id**, **cost_usd**)**: Adds to the cost tracking for a session.
- **save(**session_id**)**: Explicitly saves a session to disk (often called automatically).
- **list_sessions(**target**=None)**: Lists all sessions, optionally filtered by target.
- **get_latest(**target**)**: Retrieves the most recent session for a given target.
- **load(**session_id**)**: Loads a session from disk.
- **delete(**session_id**)**: Deletes a session.

### Request Example (Create and Update)
```python
from pentestgpt.core.session import SessionStore, SessionStatus

sessions = SessionStore()

session = sessions.create(
    target="10.10.11.234",
    task="Capture all flags",
    model="claude-sonnet-4-5-20250929"
)

sessions.update_status(session.session_id, SessionStatus.RUNNING)
sessions.add_flag(session.session_id, "user_flag_abc", "Found in user home")
sessions.add_cost(session.session_id, 0.50)
sessions.save(session.session_id)
```

### Response
Methods typically return `SessionInfo` objects or lists of `SessionInfo` objects. Errors may raise exceptions.

#### SessionInfo Object Fields
- **session_id** (string)
- **target** (string)
- **task** (string)
- **model** (string)
- **status** (SessionStatus enum)
- **created_at** (datetime)
- **updated_at** (datetime)
- **flags_found** (list of dicts)
- **instructions** (list of strings)
- **total_cost_usd** (float)

#### Response Example (get_latest)
```json
{
  "session_id": "sess_xyz789",
  "target": "10.10.11.234",
  "task": "Capture all flags",
  "model": "claude-sonnet-4-5-20250929",
  "status": "RUNNING",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:30:00Z",
  "flags_found": [
    {"flag": "user_flag_abc", "context": "Found in user home"}
  ],
  "instructions": ["Focus on web vulnerabilities"],
  "total_cost_usd": 0.50
}
```
```

--------------------------------

### Event Bus System

Source: https://context7.com/greydgl/pentestgpt/llms.txt

A thread-safe publish/subscribe event bus for decoupled communication between the TUI and the agent. It uses a singleton pattern for consistent event routing.

```APIDOC
## Event Bus System

### Description
Thread-safe pub/sub event bus for decoupled communication between the TUI and agent. Singleton pattern ensures consistent event routing across components.

### Method
Event Subscription and Emission

### Endpoint
`EventBus` class and `EventType` enum

### Parameters
#### EventBus Methods
- **get()**: Returns the singleton instance of `EventBus`.
- **subscribe(event_type, handler)**: Registers a handler function for a specific event type.
- **unsubscribe(event_type, handler)**: Removes a previously registered handler.
- **emit_state(state, details)**: Emits a state change event.
- **emit_message(text, msg_type)**: Emits a message event.
- **emit_tool(status, name, args)**: Emits a tool execution event.
- **emit_flag(flag, context)**: Emits a flag found event.
- **emit_command(command)**: Emits a command event (typically from TUI to agent).
- **emit_input(text)**: Emits user input event.
- **reset()**: Resets the EventBus (for testing).

#### Event Types
- **EventType.STATE_CHANGED**: Agent state changes.
- **EventType.FLAG_FOUND**: A flag has been captured.
- **EventType.TOOL**: Tool execution status (start/complete).
- **EventType.MESSAGE**: General messages.
- **EventType.COMMAND**: User commands.
- **EventType.INPUT**: User input.

### Request Example (Subscription)
```python
from pentestgpt.core.events import EventBus, EventType, Event

events = EventBus.get()

def on_flag_found(event: Event):
    flag = event.data.get("flag")
    print(f"FLAG CAPTURED: {flag}")

events.subscribe(EventType.FLAG_FOUND, on_flag_found)
```

### Request Example (Emission)
```python
events.emit_flag("HTB{example_flag_here}", context="Found in /root/root.txt")
events.emit_message("Starting reconnaissance...", msg_type="info")
```

### Response
Event handlers receive an `Event` object with a `data` dictionary containing event-specific information.

#### Event Data Examples
- **STATE_CHANGED**: `{"state": "running", "details": "Connecting to Claude Code"}`
- **FLAG_FOUND**: `{"flag": "HTB{example_flag}", "context": "Found in /root/flag.txt"}`
- **TOOL**: `{"status": "start", "name": "Nmap", "args": {"command": "nmap -sV 10.10.11.234"}}`
- **MESSAGE**: `{"text": "Scan complete.", "msg_type": "info"}`
```

--------------------------------

### Manage Langfuse Telemetry

Source: https://context7.com/greydgl/pentestgpt/llms.txt

Python API for initializing and shutting down Langfuse telemetry. Allows toggling tracking via function arguments or environment variables.

```python
from pentestgpt.core.langfuse import init_langfuse, shutdown_langfuse

init_langfuse(disabled=False)
init_langfuse(disabled=True)

import os
os.environ["LANGFUSE_ENABLED"] = "false"

shutdown_langfuse()
```

--------------------------------

### Configure Telemetry Opt-Out

Source: https://github.com/greydgl/pentestgpt/blob/main/README.md

Methods to disable telemetry collection in PentestGPT using command-line flags or environment variables to ensure no usage data is sent to Langfuse.

```bash
pentestgpt --target 10.10.11.234 --no-telemetry
export LANGFUSE_ENABLED=false
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.