PentestGPT

The autonomous pentest run operates under several strict logical invariants to ensure deterministic state and valid evidence:

Evidence and Observation Rules

• Canonical Observations: Must be an exact contiguous slice from a non-structured receipt. Only CRLF/LF transport normalization is allowed.
• Evidence Validity: Operational failures (provider, transport, or validation errors) never promote partial output to evidence.
• Truncation: If a grounding receipt is oversized, it is reduced to an exact 4,000-character suffix and committed as progress. Truncation can never be used to complete a task.
• Negative Evidence: Completed commands with non-zero exit statuses remain eligible as evidence because negative results are valid findings.

Task and State Rules

• Task Uniqueness: At most one task/attempt is active; the task, attempt, lease revision, and trace episode identity must agree.
• Retry Logic: A 'no-action' retry creates a new attempt and episode. An 'actionful' attempt is never replayed.
• Dependency Management: Basis-producing tasks are dependencies (except for RECOVER). EXPLOIT tasks must cite the newest completed TEST observation on the exact same target string.
• Isolation: Every episode is fresh (resume = null). The deployment environment serves as the isolation boundary; the Memory Kernel is a logical authority, not a sandbox.
• Security: Target-derived evidence, diagnostics, and files are treated as untrusted data and are never used as agent instructions.

The autonomous framework, located in pentestgpt_agent/, operates on a two-role loop designed for deterministic execution and memory authority. The loop consists of a Supervisor and an Executor:

1. Supervisor: Analyzes the current state and either chooses a single task (via a TaskLease) or proposes completion.
2. Executor: Performs the leased task and returns a typed result.

Key Architectural Principles:

• Roles: Both roles use fresh provider sessions with FULL_ACCESS. Isolation is managed by the deployment environment, not by internal sandboxing.
• Memory: SQLite is the canonical source of truth for memory. Provider transcripts are treated as diagnostic traces, not memory.
• Determinism: Scope validation, leases, evidence provenance, retries, and canonical state are managed by deterministic code rather than LLM reasoning.
• No RAG/Parallelism: The current design does not use an always-on judge, RAG service, speculative backlog, or parallel scheduler.

RunSnapshot -> Supervisor -> compile_plan -> one TaskLease
                                             |
TraceStore <- EpisodeRunner <- Executor <----+
     |                              |
     +---- compile_execution -------+
                    |
               MemoryKernel

The PentestGPT Agent operates as a durable loop using a SQLite backend to manage state.

Runtime Flow

1. Supervisor: Proposes at most one new task and selects exactly one ready task or completion.
2. Executor: Receives one leased task with an explicit task kind and a bounded provider turn budget.
3. Commit: The system atomically commits the attempt, observation, and transition.

Memory and Traces

• SQLite: Stores runs, typed tasks, attempts, observations, and transitions.
• Observations: Must be an exact contiguous slice of a command or tool receipt. Oversized receipts are truncated to a 4,000-character suffix.
• Episode Files: Each episode directory contains:
  • input.json: Role input, prompt/schema hashes, and provider policy.
  • events.jsonl: Chronological normalized tool, command, file, and terminal events.
  • output.json: Normalized result, usage, cost, duration, and failure.

Security Model

Both the Supervisor and Executor have FULL_ACCESS filesystem and process permissions. The framework relies on deployment isolation (e.g., an isolated, disposable container or VM) rather than in-process sandboxing. The surrounding environment is the defined blast radius.

The autonomous pentest process uses a specific set of roles and terms to manage the agentic loop. Understanding these is critical for interpreting logs, traces, and the state of an assessment:

Core Roles

• Supervisor: A full-access reasoning agent that proposes and selects tasks. Its tool activity is diagnostic.
• Executor: A full-access agent that performs a single leased task and proposes a result based on a trace.
• Memory Kernel: A deterministic SQLite authority that validates and commits state (not an agent).
• Provider Adapter: The unified-agent module that interfaces with external models (like Claude Code or Codex) and normalizes events.

Execution Concepts

• Decision Cycle: One Supervisor decision followed by one leased task (and its bounded sequence of attempts).
• Agent Episode: One bounded, fresh invocation of either a Supervisor or Executor.
• Task: A durable, typed unit of work defined by a target, objective, completion condition, basis, and dependencies.
• Attempt: A single execution of a task.
• Retry: A new attempt for the same task following a safely replayable 'no-action' operational failure.

Data and Evidence

• Action Receipt: A runtime-observed command/tool action and its result.
• Evidence: The exact target output captured by an eligible action receipt. Note that a command with a non-zero exit status is considered valid negative evidence.
• Observation: A bounded slice of a receipt including its run/task/attempt/episode/sequence identity.
• Finding: A security-relevant claim supported by an evidence chain (Note: structured findings are not yet implemented).
• Diagnostic: Operational or progress information used to avoid repeating failures; diagnostics can never be used as evidence.

The pentestgpt:latest Docker image provides a disposable pentest-tool and provider-CLI environment containing Ubuntu 24.04, Python 3.12, Node 20, and common tools like nmap, gobuster, and jq.

Note: The pentestgpt_agent project is not baked into this image. Running make docker-run will fail if the agent wiring is not configured.

Use the following Makefile commands to manage the lifecycle and authentication of the container:

• make docker-build: Builds the Docker image.
• make docker-login: Handles provider authentication.
• make docker-auth-status: Checks the current authentication status (advisory).
• ROUNDTRIP=1 make docker-auth-status: Performs a minimal provider call to verify authentication.
• make docker-shell: Drops into a shell inside the container.
• make docker-down: Stops the container but preserves authentication volumes.
• make docker-nuke: Stops the container and removes all authentication volumes.