/docs/docker-dev-plan.md

Docker runtime status

Status: 2026-07-12

This document describes the repository as it exists now. It replaces the original implementation plan, whose phase matrix and in-repo benchmark paths are obsolete.

Current image responsibility

pentestgpt:latest is a disposable pentest-tool and provider-CLI environment. It contains:

• Ubuntu 24.04, Python 3.12, Node 20, uv, Claude Code, and Codex;
• common network/pentest tools such as nmap, gobuster, dirb, netcat, curl, DNS utilities, jq, and ripgrep;
• the root pentestgpt_legacy package;
• the old root unified_agent compatibility copy;
• persistent Claude and Codex authentication helpers.

It deliberately excludes benchmark fixtures/results, credentials, workspaces, and run artifacts.

The maintained pentestgpt_agent nested project is not baked into this image. Consequently, make docker-run deliberately fails fast with a wiring diagnostic instead of invoking an absent CLI. The temporary qualification runner in pentestgpt_agent/scripts/run_xbow.py works around this by building the framework and external wrapper wheels on the host, then installing those wheels into an isolated container environment.

Repository ownership

PentestGPT/          image, auth helpers, framework source, legacy client
UnifedAgentWrapper/  canonical provider-wrapper package
xbow-benchmark/      Docker-network targets, scheduling, scoring, reports

The benchmark harness no longer belongs under this repository. Run benchmark commands from ../xbow-benchmark; do not add result JSONL or target orchestration here.

Persistent provider login

Authentication state lives in named volumes and is never copied into image layers:

pentestgpt-claude -> /home/pentester/.claude
pentestgpt-codex  -> /home/pentester/.codex

The providers require different setup paths:

• Claude uses a long-lived setup-token, stored as .claude/oauth_token and exported as CLAUDE_CODE_OAUTH_TOKEN by the entrypoint.
• Codex performs its own in-container OAuth login. Its callback is forwarded through a socat hop; host auth.json must not be copied because ChatGPT refresh tokens rotate.

Useful commands:

make docker-build
make docker-login
make docker-auth-status
ROUNDTRIP=1 make docker-auth-status   # spends a minimal provider call
make docker-shell
make docker-down                      # keeps auth volumes
make docker-nuke                      # deliberately removes auth volumes

The auth-status check is advisory by default. Named volumes are credentials and must be protected like a logged-in workstation.

Isolation contract

Both PentestGPT roles use provider FULL_ACCESS. The container or dedicated attack box is therefore the blast radius and security boundary. A deployment must:

• contain only authorized target routes;
• avoid mounting unrelated source, home directories, tokens, or host sockets;
• mount run state only when persistence is required;
• treat traces and SQLite state as sensitive;
• tear down the environment after the assessment.

The tool image runs as pentester, which has passwordless sudo. It is isolation from the developer host only when mounts, capabilities, devices, and networking are deliberately constrained.

Framework-image decision still open

There are two reasonable future shapes:

1. Build framework and unified-agent wheels outside Docker, then copy them into a dedicated runtime image. This matches the proven qualification runner and preserves exact package hashes.
2. Publish both packages and install pinned releases during the Docker build.

Do not copy the root unified_agent/ directory into the maintained framework. It is version 0.1-era compatibility code; the agent requires the pinned external 0.2 package.

Whichever shape is selected must make these checks true in a fresh container:

pentestgpt-agent --help
python -c "import pentestgpt_agent, unified_agent; print(unified_agent.__version__)"

Only after that should make docker-run be advertised as supported.

Build cleanup opportunities

These are independent of framework design:

• remove apt-get upgrade for faster, more reproducible builds;
• install socat in the main apt layer;
• combine global npm installs;
• use BuildKit cache mounts for apt, npm, and uv;
• install from lockfiles/wheels before copying frequently changing source;
• remove the root unified_agent copy and its SDK dependencies when the public-package cleanup is performed.

Benchmark handoff

The sibling benchmark repository is host-driven: it starts each authorized XBOW fixture, attaches a fresh tool container to the target network, records one result, and tears the target down. Claude jobs may share their token volume; Codex jobs should remain serialized unless refresh-token safety is demonstrated.

Its framework variant is still pending rewire to the renamed pentestgpt_agent. The working wheel build/install sequence in pentestgpt_agent/scripts/run_xbow.py is the implementation reference for that transfer.