pentestcode is a terminal-based multi-agent AI system that automates authorized penetration testing from recon to reporting, backed by a persistent, queryable engagement state shared across specialist agents.
| Tool | s0ld13rr/pentestcode — multi-agent AI penetration testing system with persistent engagement state, written in TypeScript |
| Category | AI-driven security automation / offensive security tooling |
| Primary Use | Automating authorized pentest engagements — recon, scanning, enumeration, exploitation, and reporting — coordinated through a shared engagement state with 13 specialist agents |
| Safe Use | For authorized penetration tests, lab environments, CTF/HTB boxes, and bug bounty programs within defined scope; /scope and scope_check enforce target boundaries |
| Telemetry Note | Drives loud, well-logged tooling (nmap, gobuster, NetExec-style spraying, Kerberos roasting) that leaves distinctive authentication failure, scan, and enumeration patterns in SIEM, domain controller, and EDR telemetry; all activity is also self-documented in a local findings.md evidence log |
pentestcode is an autonomous penetration testing agent that runs in the terminal and tries to behave like a human operator deciding what to do next. Point it at a target, give it a goal, and it runs tools, parses their output, updates a structured model of the engagement, and chooses the next action based on what it has learned. It is explicitly a hard fork of OpenCode (MIT-licensed), stripped of the code-editing focus and rebuilt around offensive security workflows. The README is candid about maturity — the project self-describes as beta, holding up on real engagements and CTFs but with rough edges expected. At roughly 795 stars and an MIT license, it is one of the more substantive attempts to turn an LLM coding agent chassis into a pentest orchestration platform.
The headline architectural claim is the strategist-coordinator model, which the README credits to HPTSA research (arXiv 2410.02246), citing a 4.3× improvement over a single agent. In practice this means a lead agent, pentest, breaks the engagement into tasks and dispatches parallel specialist subagents: thirteen in all — recon, scanner, enumerator, exploiter, identity (AD/Kerberos), infrastructure (SNMP/IPMI/databases), webapp (OWASP Top 10), post-exploit, exploit-dev, critic (a false-positive checker), reporter, plus hidden agents for context compression and session management. Each subagent has its own system prompt, tool permissions, and domain knowledge. This separation matters analytically: instead of one bloated context window trying to be everything, the system trades context efficiency for specialization, with the critic agent acting as an internal QA layer against hallucinated findings.
The second pillar is shared memory — a single structured engagement state that every agent reads from and writes to. The state schema the README describes is genuinely detailed: hosts and services with ports, versions, and banners; vulnerabilities tracked with severity, status (suspected / confirmed / exploited), evidence chains, and confidence scores; credentials with type and what they unlock; access records mapping who holds shell, RDP, or DB sessions at what privilege; an entity relationship graph with typed edges like EXPLOITED_VIA, CREDENTIAL_FROM, ADMIN_OF, and PIVOT_TO; a full AD domain model covering trusts, admins, password policy, and GPOs; and network segments with pivot hosts. When the scanner finds a port, the enumerator sees it immediately. State also survives session termination — close the terminal, return the next day, and the engagement resumes.
Perhaps the most interesting technical detail is attack-path computation. pentestcode runs cost-based Dijkstra plus Yen's K-shortest routes over the relationship graph to suggest attack paths, exposed through the attack_path_suggest tool. This is essentially the BloodHound approach to graph reasoning, generalized beyond AD to the entire engagement model. Combined with state_query (20+ query types) and state_update (30+ mutation types, batch mode), the state layer functions as a live, queryable knowledge base rather than a chat transcript — the fundamental weakness of prompt-in-a-window pentest attempts.
The tool layer contains 18 built-in pentest tools beyond bash, and the design decision here is worth noting: parser tools are mandatory. After running nmap, the agent must pipe output through nmap_parse rather than grepping XML by hand, ensuring findings reach structured state. The same pattern applies to nuclei_parse, cme_parse (NetExec output updating creds/access/hosts), gobuster_parse, bloodhound_parse (SharpHound JSON into the AD model), and sqlmap_parse for injection points. Analytical tools include xss_detect for reflected/stored XSS, jwt_analyze checking alg:none, weak HMAC, and expiry, cred_spray planning sprays across all discovered services, scope_check for CIDR/wildcard validation, tunnel_manage for SSH/chisel/ligolo planning, and report_gen for markdown/JSON deliverables.
Knowledge is layered through what the project calls skills — nineteen curated markdown packs loaded on demand so they consume context only when relevant. These split into six phase checklists, nine service-knowledge packs (SMB, SSH, FTP, DNS, databases, web servers, mail, Docker/K8s, CI/CD), and four playbooks covering infrastructure, Active Directory, web application, and cloud testing. Because skills are plain markdown, operators can extend the system by dropping a SKILL.md into the skills directory with no code changes — a smart, low-friction customization surface that also lets organizations encode their own methodologies and rules of engagement.
Human oversight is handled through slash commands and autonomy modes. /status, /targets, /vulns, /creds, /scope, /phase, /report give live visibility into the engagement, while /mode switches between three postures: auto (fully autonomous phase execution with spawned subagents), free (no phase structure, which the README notes bypasses scope checks — a flag worth internalizing for governance), and guided (each proposed action awaits approval). Modes compose with pause behavior — auto plus pause always yields autonomous execution that halts at every finding for human review, a sensible default for real authorized engagements where accountability matters.
Installation is straightforward and self-contained: the binary ships without requiring Bun, Node, or any runtime, targeting Linux and macOS on x64 and arm64. Options include npm install -g pentestcode-ai, the curl install script, an AUR package (paru -S pentestcode-bin) for Arch users, and building from source with bun install and bun run build --single --skip-embed-web-ui. Configuration lives in .pentestcode/pentestcode.jsonc, where you set the provider and model; provider support spans twenty-plus backends via ai-sdk, including Anthropic, OpenAI, Google, Azure, AWS Bedrock, Ollama, Together, Groq, Fireworks, DeepSeek, and Mistral — so self-hosted inference is viable for sensitive engagements where findings should not leave the network.
The README's worked example illustrates the intended chain on a lab target: nmap -sS -p- output parsed into state, ports 88 and 389 recognized as a Domain Controller, parallel enumeration across SMB, LDAP, and HTTP, and progression through credential discovery, spraying across SMB/WinRM/LDAP/RDP, and post-exploitation — every step recorded with an evidence chain. Operationally, this is the kind of behavior defenders should understand: the tool is methodical where humans get lazy, spraying every credential against every service on every host without forgetting. For blue teams, that translates into dense, uniform authentication-failure patterns, systematic service sweeps, and enumeration noise that stands out in SIEM correlation — which is exactly the telemetry value of studying tools like this in a lab.
Where does this fit in an authorized workflow? The README positions it across penetration testing, CTF competitions (with flag tracking and multi-target coordination), bug bounty, vulnerability research, and infrastructure auditing. The sensible posture is to treat it as a junior operator that never forgets: run it guided or with pause on findings, keep /scope tight, and validate everything through the critic agent's output and your own review of findings.md — the human-readable evidence log you can tail -f to watch the engagement unfold in real time. The codebase itself is TypeScript on the Effect library, with architecture documented in CLAUDE.md for anyone auditing what the agents actually do. As a demonstration of where agentic offensive tooling is heading — persistent state, graph reasoning, and specialist decomposition — pentestcode is one of the clearest open implementations available for study in authorized lab environments.
s0ld13rr/pentestcode.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.