PentestCode

---

PentestCode is an autonomous pentesting agent for your terminal. Point it at a target and it runs the tools, reads the output, updates its picture of the network, and decides what to do next — the way an operator would. A hard fork of OpenCode (MIT), stripped of the code-editing focus and rebuilt for offensive security.

Beta — it holds up on real engagements and CTFs, but expect rough edges. File an issue when something breaks; that's what makes it better.

What it does

One instruction in, a full attack chain out:

you: "pentest 10.10.10.5, goal is domain admin"

Stage	What the agent does
Scan	nmap -sS -p- finds 7 open ports and parses the XML straight into engagement state
Recognize	Ports 88 + 389 → Domain Controller. Fans out three enumerators in parallel (SMB, LDAP, HTTP)
Enumerate	Null SMB session → writable share. LDAP → user list. Gobuster → web dirs
Attack	AS-REP roast → crackable hash → first valid credential
Spray	That credential sprayed across SMB, WinRM, LDAP and RDP on every known host
Exploit	WinRM foothold → post-exploit agent dumps SAM / LSA / DPAPI
Result	Domain admin hash in hand — every step recorded with its evidence chain

It's methodical where people get lazy: it sprays every credential against every service on every host, and it doesn't forget to check things. Everything it learns lands in a structured state you can query mid-run with /status, /vulns, or /creds.

Install

npm install -g pentestcode-ai

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

A single self-contained binary — no Bun, Node, or runtime to install. Linux and macOS, x64 and arm64.

Arch Linux (AUR):

paru -S pentestcode-bin

Pin version:

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

Custom directory:

PENTESTCODE_INSTALL=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/s0ld13rr/pentestcode/main/install.sh | bash

From source:

bun install
bun run build --single --skip-embed-web-ui
# binary at packages/opencode/dist/pentestcode-<os>-<arch>/bin/pentestcode

Quick start

pentestcode auth login          # connect your LLM provider
pentestcode                     # interactive session
pentestcode --prompt "scan 10.10.10.0/24 and enumerate all services"   # one-shot

Works with 20+ providers through ai-sdk — Anthropic, OpenAI, Google, Azure, AWS Bedrock, Ollama, and more.

How it works

Two things separate PentestCode from a pentester prompt pasted into a chat window: a team of agents and a memory they share.

A team, not a monologue

The design follows the strategist-coordinator model from HPTSA research — a 4.3× improvement over a single agent:

                    ┌─────────────┐
                    │   pentest   │  strategist / coordinator
                    │   (lead)    │  plans, dispatches, tracks state
                    └──────┬──────┘
           ┌───────┬───────┼───────┬───────┐
           ▼       ▼       ▼       ▼       ▼
        ┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐
        │recon ││scan- ││explo-││iden- ││post- │
        │      ││ner   ││iter  ││tity  ││explo │  ... + 7 more
        └──────┘└──────┘└──────┘└──────┘└──────┘

The lead agent (pentest) breaks the engagement into tasks and dispatches specialist subagents in parallel — each with its own system prompt, tool permissions, and domain knowledge. 13 agents in all: recon, scanner, enumerator, exploiter, identity (AD/Kerberos), infrastructure (SNMP/IPMI/databases), webapp (OWASP Top 10), post-exploit, exploit-dev, critic (false-positive checker), reporter, plus hidden agents for context compression and session management.

A memory they all share

When the scanner finds a port, the enumerator sees it instantly — because every agent reads from and writes to one structured engagement state:

• Hosts & services — IP, hostname, OS, ports, service versions, banners
• Vulnerabilities — severity, status (suspected / confirmed / exploited), evidence chain, confidence score
• Credentials — username, hash/password, type, domain, what they unlock
• Access — who holds shell/RDP/DB on which host, at what privilege level
• Relationships — an entity graph (EXPLOITED_VIA, CREDENTIAL_FROM, ADMIN_OF, PIVOT_TO, …)
• AD domain model — domain controllers, trusts, admins, password policy, GPOs
• Network segments — VLANs, reachable networks, pivot hosts
• Attack paths — cost-based Dijkstra + Yen's K-shortest routes through the relationship graph

State survives the session: close the terminal, come back tomorrow, and the agent resumes where it stopped. Alongside it, a human-readable findings.md logs every vulnerability, credential, and access gain with timestamps — tail -f it to watch the engagement unfold.

Tools

18 built-in pentest tools beyond bash. Parser tools are mandatory: after running nmap the agent must pipe the output through nmap_parse rather than grep the XML by hand, so every finding reaches the engagement state.

Tool	What it does
nmap_parse	Parse nmap XML → auto-populate hosts/services
nuclei_parse	Parse Nuclei JSON → create vulns with severity
cme_parse	Parse NetExec output → update creds/access/hosts
gobuster_parse	Parse dir brute output → classify findings
bloodhound_parse	Parse SharpHound JSON → populate AD model
sqlmap_parse	Parse sqlmap output → extract injection points
xss_detect	Analyze responses for reflected/stored XSS
jwt_analyze	Decode JWT, check alg:none/weak HMAC/expiry
cred_spray	Plan credential spray across all discovered services
scope_check	CIDR/wildcard scope validation
attack_path_suggest	Cost-based path finding through the relationship graph
tunnel_manage	Plan SSH/chisel/ligolo tunnels, track live sessions
phase_control	Phase management with quality gates
report_gen	Generate markdown/JSON pentest reports
state_update	Record findings (30+ mutation types, batch mode)
state_query	Query engagement state (20+ query types)

Skills

19 curated knowledge packs, loaded on demand so they cost context only when relevant:

• Phase checklists (6) — what to do in each pentest phase
• Service knowledge (9) — SMB, SSH, FTP, DNS, databases, web servers, mail, Docker/K8s, CI/CD
• Playbooks (4) — infrastructure, Active Directory, web application, cloud

Skills are plain markdown. Add your own by dropping a SKILL.md into the skills directory — no code changes needed.

Commands & modes

Drive a live session with slash commands:

Command	What it does
/status	Engagement dashboard — hosts, vulns, creds, phase
/targets	Host & service table
/vulns	Findings by severity
/creds	Discovered credentials
/scope	View/edit target scope
/phase	Phase management
/mode	Switch auto / free / guided
/pause	Pause on findings (never / always / checkpoint)
/report	Generate a pentest report

And set how much rope the agent gets:

• auto — runs through the pentest phases autonomously, spawning subagents as needed
• free — no phase structure; responds to your requests directly (bypasses scope checks)
• guided — step by step; proposes each action and waits for approval

Modes combine with pause behavior — auto + pause always gives you autonomous execution that stops at every finding for review.

Use cases

One toolkit across offensive security:

• Penetration testing — full methodology from recon to reporting
• CTF competitions — flag tracking, objective management, multi-target coordination
• Bug bounty — web app testing, API security, recon automation
• Vulnerability research — systematic enumeration and validation
• Infrastructure security — network service auditing, default-credential checks

Configuration

Config lives at .pentestcode/pentestcode.jsonc:

{
  "provider": {
    "anthropic": {
      "model": "claude-sonnet-4-20250514"
    }
  }
}

Providers: Anthropic, OpenAI, Google, Azure, AWS Bedrock, Ollama, Together, Groq, Fireworks, DeepSeek, Mistral, and more via ai-sdk.

Contributing

Bug reports from real usage are the most valuable thing you can send. Run PentestCode on a CTF box, an HTB machine, or an authorized pentest, and when something goes wrong — it loops, misses an obvious path, chokes on tool output, or wastes tokens — open an issue with:

1. What you were testing (target type, not sensitive details)
2. What went wrong
3. The findings.md and/or relevant session output

Feature requests and PRs are welcome too. The codebase is TypeScript on the Effect library — see CLAUDE.md for architecture.

License

MIT — see LICENSE.

---