# pentestcode **Repository Path**: ctkqiang/pentestcode ## Basic Information - **Project Name**: pentestcode - **Description**: PentestCode - Multi-agent AI penetration testing system with persistent engagement state, strategic coordination, and parallel autonomous operations. - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-03 - **Last Updated**: 2026-09-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # PentestCode

PentestCode

AI penetration testing agent in your terminal.
Multi-agent architecture • Engagement state tracking • 20+ LLM providers

Release License Stars

--- **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](https://github.com/anomalyco/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](https://github.com/s0ld13rr/pentestcode/issues) 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 ```bash 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.
Other options **Pin version:** ```bash PENTESTCODE_VERSION=0.1.7 curl -fsSL https://raw.githubusercontent.com/s0ld13rr/pentestcode/main/install.sh | bash ``` **Custom directory:** ```bash PENTESTCODE_INSTALL=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/s0ld13rr/pentestcode/main/install.sh | bash ``` **From source:** ```bash bun install bun run build --single --skip-embed-web-ui # binary at packages/opencode/dist/pentestcode--/bin/pentestcode ```
## Quick start ```bash 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](https://github.com/vercel/ai) — 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](https://arxiv.org/abs/2410.02246) — 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`: ```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](https://github.com/vercel/ai). ## 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](CLAUDE.md) for architecture. ## License MIT — see [LICENSE](LICENSE). ---

Hard fork of OpenCode • Built for offensive security • Self-hosted & open source