Pentestcode AI Agent

PentestCode

<p align="center"> <img src="https://github.com/s0ld13rr/pentestcode/raw/main/.github/logo.png" alt="PentestCode" width="480" /> </p> <p align="center"> <strong>AI penetration testing agent in your terminal.</strong><br> Multi-agent architecture &bull; Engagement state tracking &bull; 20+ LLM providers </p> <p align="center"> <a href="https://github.com/s0ld13rr/pentestcode/releases/latest"><img src="https://img.shields.io/github/v/release/s0ld13rr/pentestcode?style=flat-square&color=red" alt="Release"></a> <a href="https://github.com/s0ld13rr/pentestcode/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a> <a href="https://github.com/s0ld13rr/pentestcode"><img src="https://img.shields.io/github/stars/s0ld13rr/pentestcode?style=flat-square" alt="Stars"></a> </p>

---

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

<details> <summary>Other options</summary>

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

</details>

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.

Disclaimer

This tool is provided for authorized security testing, education, and research purposes only. The author assumes no responsibility for any unauthorized or illegal use of this software. Users are solely responsible for ensuring they have proper authorization before testing any systems. Misuse of this tool may violate applicable laws and regulations.

License

MIT — see LICENSE.

---

<p align="center"> Hard fork of <a href="https://github.com/anomalyco/opencode">OpenCode</a> &bull; Built for offensive security &bull; Self-hosted & open source </p>