PentestCode
An autonomous multi-agent AI penetration testing system in your terminal, with persistent engagement state, strategic coordination, and parallel autonomous operations.
README claims scope_check, guided approval mode, pause policies, and mandatory parser pipelines, but no tool implementation or permission config is present in the supplied evidence, so least privilege is asserted without support (1). Guided mode and 'pause always' support user confirmation (2). Engagement state and findings.md give a fairly clear data-flow narrative (2). Credentials, hashes, and shell access are explicitly stored in state with no stated encryption, redaction, or access control (1). Heavy reliance on patched third-party packages and beta [email protected]; patches exist but no security audit evidence (2). Tools execute outward-facing actions (nmap, credential spraying, exploitation) against real targets, constrained only by an 'authorized testing' phrase; 'free' mode explicitly 'bypasses scope checks' — a concrete deduction (1). No rollback/undo mechanism documented (1). LICENSE properly acknowledges the OpenCode fork under MIT (2).
CI includes unit/e2e/typecheck workflows and the contract-identity tests are genuinely rigorous (2), but all visible tests target the client SDK; core pentest logic (state machine, parsers, scope enforcement) has no test evidence. Many beta/RC dependencies (effect beta, drizzle RC, solid-start from pkg.pr.new) pose real availability risk (1). Failure messaging has only indirect evidence via typed errors (1).
Clear multi-scenario audience: pentest, CTF, bug bounty, vuln research (2). Honest beta positioning, but destructive-action boundaries and technical enforcement of scope are absent from evidence, and free mode deliberately bypasses checks (1). Slash commands and mode semantics are documented but implementation is unverified (1). Linux/macOS, x64/arm64, 20+ providers (2).
Excellent README structure: install, quick start, architecture, tool tables, command tables, config, contributing (3). Multiple install paths with version pinning, but curl|bash with no checksums (2). Consistent naming (pentestcode-ai, directory names) (2). Config and usage examples but no FAQ (2). Beta disclaimer is honest limitation disclosure (2). Complete LICENSE with fork attribution (3). Release badge but no CHANGELOG file (1). Issue workflow and CI visible; publisher unverified (2).
findings.md, /status, /vulns, /creds, and report_gen provide structured usable output (2). Shared state + parser pipeline is real marginal value over a chat-window prompt, though the 4.3x figure cites external research, not this project's measurements (2). Single binary and multi-provider reduce friction, but token/traffic cost of autonomous spraying and parallel subagents is not estimated (2).
Architecture claims (13 agents, 18 tools, 19 skills, 30+ mutation types) are not traceable to implementation in the supplied files (1). The HPTSA citation and fork statement are externally checkable, but internal numbers have no source (1). README separates its own claims from external research (arxiv link, fork note) with little conflation (2).
- This is an autonomous offensive agent: nmap scans, credential spraying, and exploitation run against real targets — use only within documented written authorization.
- Free mode explicitly bypasses scope checks; combined with unsupervised auto mode this compounds risk. Prefer guided + pause always by default.
- Credentials, hashes, and shell access are stored in plaintext in local engagement state and findings.md; watch file permissions and disk residue.
- install.sh runs via curl|bash with no checksums; publisher identity is unverified — prefer building from source or pinning and verifying hashes.
- Many dependencies are beta/RC with local patches, creating supply-chain and stability risk; core pentest logic (parsers, scope checks) has no visible test coverage in the supplied evidence.
What does this agent do, and when should you use it?
PentestCode (GitHub: s0ld13rr/pentestcode, MIT license) is a terminal-based autonomous AI pentesting agent for offensive security, built as a hard fork of OpenCode (MIT) with the code-editing focus stripped out and rebuilt for penetration testing. It follows the strategist-coordinator model from HPTSA research: a lead agent (pentest) plans tasks and dispatches 13 specialist subagents in parallel — recon, scanner, enumerator, exploiter, identity (AD/Kerberos), infrastructure, webapp, post-exploit, exploit-dev, critic, reporter, and hidden session/context agents. All agents share one structured engagement state covering hosts and services, vulnerabilities with evidence chains, credentials, access, an entity relationship graph, an AD domain model, network segments, and cost-based attack paths (Dijkstra + Yen's K-shortest). Beyond bash it ships 18 purpose-built tools (nmap_parse, bloodhound_parse, cred_spray, attack_path_suggest, etc.) and 19 on-demand knowledge-pack skills. It ships as a single self-contained binary for Linux/macOS (x64/arm64), works with 20+ LLM providers via ai-sdk (Anthropic, OpenAI, Google, Ollama, and more), and is in beta.
Given one instruction (e.g. "pentest 10.10.10.5, goal is domain admin"), the lead agent drives a full attack chain: it runs nmap -sS -p- and pipes XML through nmap_parse straight into engagement state; recognizes a Domain Controller from ports 88+389 and fans out SMB, LDAP, and HTTP enumerators in parallel; performs AS-REP roasting for the first valid credential, then uses cred_spray to spray it across SMB, WinRM, LDAP, and RDP on every known host; after a WinRM foothold, the post-exploit agent dumps SAM/LSA/DPAPI. Findings are recorded via state_update (30+ mutation types) and queryable with state_query (20+ query types) or slash commands /status, /vulns, /creds; findings.md logs every vulnerability, credential, and access gain with timestamps, and report_gen produces markdown/JSON reports. bloodhound_parse populates the AD domain model, attack_path_suggest finds cost-based paths through the relationship graph, scope_check validates CIDR/wildcard scope, and tunnel_manage plans SSH/chisel/ligolo tunnels.
- Authorized pentesters running a full recon-to-report methodology on internal targets, with state resuming across sessions
- CTF players coordinating enumeration, attack chains, and flag tracking across multiple targets
- Bug bounty hunters automating web app and API security testing and recon
- Red teams and security researchers analyzing identity and attack paths in Active Directory environments (Kerberos, Bloodhound data)
- Infrastructure security teams auditing network services and checking default credentials
- Vulnerability researchers doing systematic enumeration and validation, with a critic agent filtering false positives
What are this agent's strengths and limitations?
- Multi-agent architecture with 13 specialist subagents operating in parallel, following the HPTSA research model cited as a 4.3x improvement over a single agent
- Structured engagement state persists across sessions and is shared by all agents — hosts, vulns, creds, access, and an entity relationship graph
- 18 mandatory parser tools (nmap_parse, cme_parse, etc.) force tool output into state instead of ad-hoc grepping
- Provider-agnostic via ai-sdk with 20+ LLM providers, distributed as a single self-contained binary with no runtime dependency
- 19 on-demand markdown skill packs, extensible by dropping a SKILL.md into the skills directory without code changes
- Beta software — the README explicitly warns of rough edges: looping, missing obvious paths, choking on tool output, wasting tokens
- Depends on external pentest tooling (nmap, Nuclei, NetExec, Gobuster, sqlmap, SharpHound, etc.) that you must install and configure yourself
- Requires your own LLM provider account and API spend; parallel multi-agent autonomy can consume significant tokens
- free mode bypasses scope checks and auto mode executes attacks autonomously — a real risk of out-of-scope actions unless tightly controlled
- Linux and macOS only, no native Windows support; no benchmark evidence or third-party audits documented in the README
How do you install or deploy this agent?
Via npm: npm install -g pentestcode-ai; or via the curl installer: curl -fsSL https://raw.githubusercontent.com/s0ld13rr/pentestcode/main/install.sh | bash. Pin a version with PENTESTCODE_VERSION=0.1.7 before the curl command, or choose a directory with PENTESTCODE_INSTALL=/usr/local/bin. From source: bun install && bun run build --single --skip-embed-web-ui; the binary lands at packages/opencode/dist/pentestcode-<os>-<arch>/bin/pentestcode. Requires Linux or macOS (x64/arm64); no Bun/Node runtime needed for the binary.
How do you use this agent?
Connect a provider first: pentestcode auth login (Anthropic, OpenAI, Google, Azure, AWS Bedrock, Ollama, and 20+ more). Then run pentestcode for an interactive session, or one-shot: pentestcode --prompt "scan 10.10.10.0/24 and enumerate all services". Configuration lives at .pentestcode/pentestcode.c, e.g. {"provider": {"anthropic": {"model": "claude-sonnet-4-20250514"}}}. During a session use /status, /targets, /vulns, /creds, /scope, /phase to inspect state; /mode switches auto (autonomous full engagement) / free (no phase structure, bypasses scope checks) / guided (proposes each action and waits for approval); /pause sets pause-on-findings behavior (never/always/checkpoint); /report generates a pentest report. Use only against authorized targets.
How does this agent compare with similar options?
It is a hard fork of OpenCode (MIT), stripped of its code-editing focus and rebuilt for offensive security; its multi-agent design cites the HPTSA research (arXiv:2410.02246) strategist-coordinator model, claimed as a 4.3x improvement over a single agent.