AI Pentest Agents Part 2: Inside PentestCode's Coordinator and Engagement State

Part 1 of this series placed PentestCode in the “autonomous multi-agent swarm” category, alongside PentAGI, NodeZero, and XBOW, and against the raw tool-calling approach this site tried in AI Part 7. This part is a straight read of what PentestCode actually is, from its own README rather than the press coverage of it — because the coverage summarizes the architecture, and the architecture is the interesting part.

What it’s a fork of, and what that buys it

PentestCode is a hard fork of OpenCode, a terminal-based AI coding agent, rebuilt for offensive security. That lineage matters practically: it ships as a self-contained binary —

curl -fsSL https://raw.githubusercontent.com/s0ld13rr/pentestcode/main/install.sh | bash

— with no Bun, Node, or other runtime required, working on Linux and macOS across x64 and arm64. That’s a meaningfully different installation story from PentAGI, which is covered in Part 4 of this series and needs Docker with root or docker.sock access before it runs at all. PentestCode inherits OpenCode’s plumbing for talking to an LLM provider (20+ supported, including Anthropic, OpenAI, Azure, AWS Bedrock, and Ollama for local models) and its terminal-agent UX, then replaces the coding-specific tools and prompts with pentest-specific ones.

The strategist-coordinator design

The architecture is a single lead agent, pentest, that plans and dispatches work, sitting above thirteen agents total:

                    ┌─────────────┐
                    │   pentest   │  strategist / coordinator
                    └──────┬──────┘
           ┌───────┬───────┼───────┬───────┐
        ┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐
        │recon ││scan- ││explo-││iden- ││post- │
        │      ││ner   ││iter  ││tity  ││explo │  ... + 7 more
        └──────┘└──────┘└──────┘└──────┘└──────┘

recon, scanner, enumerator, exploiter, identity (Active Directory/Kerberos specifically), infrastructure (SNMP, IPMI, and databases), webapp (OWASP Top 10), post-exploit, exploit-dev, critic (explicitly a false-positive checker), and reporter, plus hidden agents for context compression and session management. Each subagent gets its own system prompt and its own tool permissions rather than sharing one undifferentiated toolset, and the coordinator spawns them in parallel — the worked example in both the README and the press coverage has the scanner finding ports 88 and 389 open, recognizing that combination as a Domain Controller, and immediately spawning three enumerators at once against SMB, LDAP, and HTTP rather than working the list serially.

The design is credited to HPTSA research (Hierarchical Planning and Task-decomposition for Autonomous agents), with the README citing a 4.3x improvement over single-agent approaches. That figure is PentestCode’s own claim rather than something I’ve independently verified against a benchmark suite — worth flagging plainly, since PentestGPT in Part 3 of this series publishes its own benchmark numbers against a public suite, and the comparison between “here’s our claimed multiplier” and “here’s our score on someone else’s 104-scenario test” is itself informative about how mature each project’s evaluation culture is.

Engagement state: the actual differentiator

The README is explicit that this, not the agent count, is what separates PentestCode from “a pentester prompt pasted into ChatGPT.” Everything discovered gets recorded in a structured store covering hosts and services (IP, hostname, OS, ports, service versions, banners), vulnerabilities (severity, status — suspected, confirmed, exploited — evidence chain, confidence score), credentials (username, hash or password, type, domain, what it’s valid for), access (who has shell, RDP, or database access on which host, at what privilege level), an entity-relationship graph (EXPLOITED_VIA, CREDENTIAL_FROM, ADMIN_OF, PIVOT_TO), an Active Directory domain model (domain controllers, trusts, admins, password policy, GPOs), network segments (VLANs, reachable networks, pivot hosts), and an attack path computed with cost-based Dijkstra plus Yen’s K-shortest-paths over that relationship graph.

Two consequences follow directly from that design. First, state persists across sessions — close the terminal, come back the next day, and the agent picks up from where the engagement state left off, rather than re-deriving context from scratch. Second, and more interesting operationally: parser tools are mandatory. After running nmap, the agent is required to pipe the output through a dedicated nmap_parse tool rather than reading the raw XML itself and updating state from its own reading of it. That’s a deliberate constraint against exactly the failure mode AI Part 7 surfaced — a model narrating its own actions instead of having a structured, checkable record of them. PentestCode doesn’t fully close that gap (the model still decides what the parsed output means), but forcing every finding through a parser before it can land in state is a real, concrete mitigation that the raw tool-calling approach in Part 7 didn’t have at all.

The eighteen tools

Beyond bash, PentestCode ships parsers for six external tools’ output (nmap_parse, nuclei_parse, cme_parse for NetExec, gobuster_parse, bloodhound_parse for SharpHound JSON, sqlmap_parse), analysis tools (xss_detect, jwt_analyze for decoding JWTs and flagging alg:none/weak-HMAC/expiry issues), planning tools (cred_spray, scope_check for CIDR/wildcard validation, attack_path_suggest, tunnel_manage for planning SSH/Chisel/ligolo-ng tunnels — the exact tools this site’s own Pivoting and Tunneling series covered — and phase_control), and output tools (report_gen, state_update with over 30 mutation types in batch mode, state_query with over 20 query types).

Skills, modes, and the honest limitations section

Nineteen “skill packs” — plain markdown files, no code required to add your own — extend domain knowledge on demand: six phase checklists, nine service-knowledge files (SMB, SSH, FTP, DNS, databases, web servers, mail, Docker/Kubernetes, CI/CD), and four playbooks (infrastructure, Active Directory, web application, cloud). Three operating modes control how much autonomy the agent actually exercises: auto runs the full methodology unattended, free bypasses scope checks and responds directly to ad-hoc requests, and guided proposes each action and waits for approval — and these compose with a pause setting (never/always/checkpoint), so auto plus pause always gives you autonomous execution that still stops for review at every finding.

What I find most credible about the project is its own limitations section, which reads like something an actual practitioner wrote rather than marketing copy: token-hungry ($5–50 per real engagement, worse with verbose scans), prone to re-running tools it’s already run despite wordlist tracking and state diffs, no GUI and no Burp Suite integration, quality varies significantly by LLM provider (its own ranking: Claude Opus/Sonnet, then GPT-4o, then local models, in that order for multi-agent coordination), and — the line that matters most for Part 6 of this series — “not stealthy” by default, with no OPSEC consideration built in, fine for authorized tests and unsuitable for red-team stealth work.

That last admission is the thread Part 6 picks up: if the tool itself says it doesn’t think about being quiet, what does that noise actually look like on a wire, and can a defender tell it apart from a human operator doing the same job.