s0ld13rr/pentestcode

PentestCode - Multi-agent AI penetration testing system with persistent engagement state, strategic coordination, and parallel autonomous operations.

What is PentestCode?

PentestCode is an autonomous penetration‑testing assistant that runs in your terminal. You give it a high‑level goal (e.g., “gain domain‑admin on 10.10.10.5”) and a team of AI‑driven agents orchestrates the whole attack chain for you – from scanning and enumeration to credential‑spraying, exploitation and post‑exploitation reporting. The project is a hard fork of the OpenCode code‑editing AI, repurposed for offensive security.

How it works

Component	Role
Lead “pentest” agent	Breaks the engagement into tasks, keeps the overall plan, and decides what to do next.
Specialist sub‑agents (recon, scanner, enumerator, exploiter, AD‑identity, web‑app, post‑exploit, etc.)	Run specific tools, parse their output, and feed results back into a shared engagement state.
Shared engagement state	A structured knowledge base that stores hosts, services, vulnerabilities, credentials, access levels, AD relationships, network segments, and computed attack paths. It persists across sessions.
LLM provider layer	Uses any of 20+ LLMs via Vercel’s `ai-sdk` (Anthropic, OpenAI, Google, Azure, Bedrock, Ollama, etc.) to generate prompts, interpret tool output, and decide next actions.

The agents communicate through this state, so when the scanner discovers a new port the enumerator can act on it immediately. A built‑in graph model lets the system compute cost‑optimal attack paths (Dijkstra + Yen’s K‑shortest). All actions are logged to a human‑readable findings.md file.

Key features

Multi‑agent architecture (13 agents) that runs tasks in parallel.
Persistent structured state (hosts, services, vulns, creds, relationships, AD model, network topology).
18 built‑in parsing tools (e.g., nmap_parse, bloodhound_parse, cme_parse) that automatically populate the state.
19 knowledge packs (skills) covering pentest phases, service specifics, and playbooks; they are plain markdown and can be extended by dropping a SKILL.md file.
Three operation modes – auto (full autonomous run), free (direct command response), guided (step‑by‑step approval).
Slash commands (/status, /vulns, /creds, /report, …) for live inspection and control.
Supports 20+ LLM providers via the ai-sdk.
Single‑binary distribution for Linux/macOS (x64 & arm64) with optional AUR package.

Installation

# npm (installs the CLI wrapper that pulls the binary)
npm install -g pentestcode-ai

# or one‑line script that downloads the pre‑built binary
curl -fsSL https://raw.githubusercontent.com/s0ld13rr/pentestcode/main/install.sh | bash

Arch Linux: paru -S pentestcode-bin

From source (requires Bun):

bun install
bun run build --single --skip-embed-web-ui   # binary ends up in packages/opencode/dist/…

Quick start

# Authenticate with your chosen LLM provider
pentestcode auth login

# Start an interactive session
pentestcode

# One‑shot command without entering the REPL
pentestcode --prompt "scan 10.10.10.0/24 and enumerate all services"

During a session you can query the live state:

/status – dashboard of hosts, vulns, creds, current phase
/vulns – list findings by severity
/creds – show discovered credentials
/report – generate a markdown/JSON pentest report

Typical workflow example

you: pentest 10.10.10.5, goal is domain admin

1️⃣ Scan → nmap -sS -p- → ports parsed into state
2️⃣ Recognize → identifies a Domain Controller (ports 88, 389)
3️⃣ Enumerate → SMB share list, LDAP user dump, Gobuster web dirs
4️⃣ Attack → AS‑REP roast → crackable hash → first credential
5️⃣ Spray → credential sprayed across SMB, WinRM, LDAP, RDP
6️⃣ Exploit → WinRM foothold → dump SAM/LSA/DPAPI
7️⃣ Result → domain‑admin hash, all steps logged

The agent repeats this loop for every discovered host until the goal is reached or you stop it.

Configuration

User‑specific settings live in ~/.pentestcode/pentestcode.jsonc. Example to select a model:

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

All providers supported by Vercel’s ai-sdk can be configured similarly.

Who should use it?

Professional pentesters who want an AI‑augmented assistant to automate repetitive phases while retaining control.
CTF participants looking for a tool that tracks flags, manages multi‑target engagements, and suggests next steps.
Bug‑bounty hunters who need fast reconnaissance and systematic enumeration.
Security researchers interested in experimenting with LLM‑driven attack automation.

Contributing & support

The project is in beta; bugs are expected. Contributions are welcome via GitHub issues (include target type, failure description, and findings.md excerpts) and pull requests. The codebase is written in TypeScript using the Effect library.