The Problem

Security teams need a repeatable, AI‑driven workflow for black‑box testing that can launch real pentesting tools (nmap, metasploit, sqlmap, etc.) without writing custom glue code. Existing scripts are ad‑hoc; teams spend time wiring LLM calls to command‑line utilities and handling output parsing.

What This Does

PentestAgent provides an extensible framework that lets an LLM orchestrate native security tools inside Docker or a local shell. The core lives under pentestagent/ with 84 source files, most of them Python. Key pieces:

  • CLI/TUI – pentestagent/interface/main.py (entry point) and pentestagent/interface/tui.py implement the command‑line UI and the interactive terminal UI.
  • Agent abstractions – pentestagent/agents/base_agent.py defines the base BaseAgent class; pentestagent/agents/crew/ adds multi‑agent orchestration.
  • Tool registry – pentestagent/tools/registry.py discovers and validates tool definitions (Tool, ToolSchema).
  • Runtime – pentestagent/runtime/runtime.py and pentestagent/runtime/docker_runtime.py manage execution environments (local vs Docker).
  • LLM integration – pentestagent/llm/llm.py wraps LiteLLM‑compatible providers; calls appear in 21 functions that hit the model.
  • MCP (Message Control Protocol) – a lightweight RPC layer (pentestagent/mcp/) lets the UI talk to worker processes.

The repository ships Docker assets (Dockerfile, docker-compose.yml, plus a Kali profile) and a full test suite (125 test files) that validates command parsing, workspace handling, and state transitions.

How It Is Wired

Execution starts at pentestagent/interface/main.py:main (line 1213), invoked via python -m pentestagent or the pentestagent console script. The call flow is:

  1. main → initialize (_initialize) builds the runtime (build_agent_components) and loads configuration (pentestagent/config/settings.py).
  2. Component creation calls pentestagent/tools/registry._make_tool (38 calls) and pentestagent/llm/_make_llm (25 calls).
  3. The UI selects a mode (/assist, /agent, /crew, /interact) and hands the user prompt to AgentMessage handling, which routes through WorkspaceManager (50 call sites) and AgentStateManager (45 sites).
  4. The core loop (_run_loop) repeatedly calls transition_to, notify, and AgentMessage (8‑6 calls each) and eventually invokes the LLM (_add_system → model inference).
  5. Tool execution is performed by pentestagent/runtime/runtime.run or docker_runtime.run, which spawn subprocesses (os.fork in main → handle_mcp_command).
  6. Files are read/written by many modules (e.g., WorkspaceManager._safe_mkdir, mcp/transport.connect, knowledge/rag.index). Network calls occur in runtime/docker_runtime.start (outbound HTTP to Docker daemon) and mcp/transport.send.

Blast‑radius hubs – pentestagent/tools/registry.py, pentestagent/runtime/__init__.py, and pentestagent/config/constants.py are imported by >13 other modules, making any change there propagate widely. The import graph contains 16 circular dependencies, notably among tools/__init__, runtime/__init__, and tools/registry, which increase cognitive load and risk of breakage.

How To Use It

# Clone the upstream repo
git clone https://github.com/moses-y/pentestagent
cd pentestagent

# Create a venv and install editable deps (includes all optional extras)
./scripts/setup.sh          # Linux/macOS
# or on Windows:
.\scripts\setup.ps1

# Copy the example env and add your API key
cp .env.example .env
# edit .env → set ANTHROPIC_API_KEY or OPENAI_API_KEY and PENTESTAGENT_MODEL

# Run the TUI (local tools)
pentestagent                 # launches the terminal UI
# or run inside Docker for isolation
docker compose up --build    # builds both base and Kali profiles
docker compose run pentestagent   # starts the UI inside the container

The CLI also accepts a target: pentestagent -t 10.0.0.5. Use /assist <task> for a single‑shot LLM call, /agent <task> for autonomous execution, or /crew <task> to spawn specialized worker agents.

Real‑World Use

A red‑team can script a full engagement:

pentestagent -t 10.10.14.23 <<EOF
/crew reconnaissance
/crew exploit
/crew post‑exploitation
EOF

The orchestrator (pentestagent/agents/crew/orchestrator.py) spawns workers that run nmap, sqlmap, and msfconsole inside the Kali container, feeds results back to the LLM, and iteratively refines the attack plan without manual copy‑paste.

Code Health & Issues

Measured findings (static analysis)

  • HIGH – Import cycles (14 files) – e.g., tools/registry.py, runtime/__init__.py, tools/__init__.py. Break by extracting shared types or deferring imports.
  • HIGH – Deep nesting (max depth 7 in 20 files) – tools/registry.py, agents/base_agent.py. Refactor with early returns.
  • HIGH – Oversized files (4 > 700 LOC) – runtime/runtime.py, agents/base_agent.py. Split by responsibility.
  • MED – Broad exception handling (15 files) – workspaces/manager.py, interface/notifier.py. Catch specific exceptions.
  • MED – Hub modules (5 files) – tools/registry.py, runtime/__init__.py, config/constants.py. Keep stable, move volatile logic elsewhere.
  • HIGH – Duplicated code blocks (≈40 repeats across 6 files) – consolidate into shared helpers.

Code‑health audit

  • HIGH – GitHub Actions pinned to tags – replace @vN with commit SHA.
  • HIGH – No lockfile – generate and commit poetry.lock/requirements.txt.
  • HIGH – Docker privileged mode & host networking – remove privileged: true, publish needed ports explicitly.
  • HIGH – continue-on-error on correctness steps – delete or separate advisory jobs.
  • HIGH – Secret baked into Dockerfile (ENV TOKENIZERS_PARALLELISM) – use BuildKit secrets.
  • MED – Base image not pinned by digest – use python:3.14-slim@sha256:<digest>.
  • MED – No dependency‑vulnerability scan – add dependency-review-action or osv-scanner.
  • MED – Checkout persists token – set persist-credentials: false.
  • LOW – Missing workflow timeout – add timeout-minutes to each job.

No critical findings, but the high‑severity items affect reproducibility, security, and maintainability.

The Bottom Line

PentestAgent delivers a functional, Docker‑enabled AI‑driven pentesting loop with a solid test suite, but the codebase suffers from import cycles, oversized modules, and several security‑hardening gaps in its CI/CD and container configuration. It is suitable for teams that can allocate effort to refactor the hub modules and tighten the build pipeline before using it in production.