pentestcode-ai-pentest-agent

# PentestCode AI Pentest Agent > Skill by [ara.so](https://ara.so) — Security Skills collection. PentestCode is an AI penetration testing agent that runs in your terminal with a multi-agent architecture. It maintains persistent engagement state, coordinates 13 specialized security agents, and automates reconnaissance through post-exploitation workflows. Built on TypeScript with Effect library. ## Installation ```bash # Quick install (self-contained binary) curl -fsSL https://raw.githubusercontent.com/s0ld13rr/pentestcode/main/install.sh | bash # Pin specific version PENTESTCODE_VERSION=0.1.7 curl -fsSL https://raw.githubusercontent.com/s0ld13rr/pentestcode/main/install.sh | bash # Custom install directory PENTESTCODE_INSTALL=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/s0ld13rr/pentestcode/main/install.sh | bash # From source (requires Bun) bun install bun run build --single --skip-embed-web-ui # Binary at packages/opencode/dist/pentestcode-<os>-<arch>/bin/pentestcode ``` ## Authentication & Configuration ```bash # Configure LLM provider (required first step) pentestcode auth login # Configuration file: .pentestcode/pentestcode.jsonc ``` Example configuration: ```jsonc { "provider": { "anthropic": { "model": "claude-sonnet-4-20250514", "apiKey": "${ANTHROPIC_API_KEY}" } }, "mode": "auto", // auto, free, or guided "pauseOnFindings": "checkpoint", // never, always, checkpoint "scope": { "targets": ["10.10.10.0/24"], "exclude": ["10.10.10.1"] } } ``` Supported providers: Anthropic, OpenAI, Google, Azure, AWS Bedrock, Ollama, Together, Groq, Fireworks, DeepSeek, Mistral. ## Core Usage Patterns ### Interactive Session ```bash # Launch interactive mode pentestcode # Inside session you: "pentest 10.10.10.5, goal is domain admin" you: "scan 192.168.1.0/24 and enumerate all services" you: "spray credentials across SMB and WinRM" ``` ### One-Shot Execution ```bash # Execute single command and exit pentestcode --prompt "scan 10.10.10.0/24 and enumerate all services" # With custom config pentestcode --config custom.jsonc --prompt "pentest 10.10.11.23" ``` ### CTF Mode ```bash pentestcode --prompt "HTB box 10.10.11.45, find user.txt and root.txt" ``` ## Slash Commands ```bash # Engagement dashboard /status # View discovered hosts and services /targets # Show vulnerabilities by severity /vulns # List discovered credentials /creds # View/edit target scope /scope add 10.10.10.0/24 /scope exclude 10.10.10.1 /scope list # Phase management /phase # Show current phase /phase recon # Jump to phase # Switch operational modes /mode auto # Autonomous execution /mode free # No phase structure /mode guided # Step-by-step approval # Pause behavior /pause never # Run continuously /pause always # Stop at every finding /pause checkpoint # Stop at phase boundaries # Generate report /report ``` ## Multi-Agent Architecture PentestCode uses 13 specialized agents coordinated by a strategist: ```typescript // Agent types and their roles: // - pentest: Lead strategist/coordinator // - recon: Passive information gathering // - scanner: Active service discovery // - enumerator: Service enumeration // - exploiter: Vulnerability exploitation // - identity: AD/Kerberos attacks // - infrastructure: SNMP/IPMI/databases // - webapp: OWASP Top 10 testing // - post-exploit: Post-exploitation tasks // - exploit-dev: Exploit development // - critic: False positive checking // - reporter: Report generation // - (hidden): context compression, session management ``` Agents spawn in parallel and share engagement state: ```bash # Scanner finds open ports → state updated # Enumerator sees new services immediately → spawns parallel enumeration # Exploiter receives vuln data → begins exploitation ``` ## Built-in Tools ### Parser Tools (Mandatory Usage) ```bash # nmap_parse - Parse nmap XML into engagement state nmap -sS -sV -p- 10.10.10.5 -oX scan.xml # Agent must use: nmap_parse scan.xml # nuclei_parse - Parse Nuclei JSON findings nuclei -u https://target.com -json -o nuclei.json # Agent must use: nuclei_parse nuclei.json # cme_parse - Parse NetExec/CrackMapExec output netexec smb 10.10.10.0/24 -u users.txt -p passwords.txt > cme.log # Agent must use: cme_parse cme.log # gobuster_parse - Parse directory brute output gobuster dir -u https://target.com -w wordlist.txt -o gobuster.txt # Agent must use: gobuster_parse gobuster.txt # bloodhound_parse - Parse SharpHound JSON # Agent must use: bloodhound_parse bloodhound.json # sqlmap_parse - Parse sqlmap output # Agent must use: sqlmap_parse sqlmap.log ``` ### Analysis Tools ```bash # xss_detect - Analyze HTTP responses for XSS # Input: response body, reflected parameters # Output: XSS vulnerability classification # jwt_analyze - JWT security analysis # Checks: alg:none, weak HMAC, expiry, claims # scope_check - Validate targets against scope # Returns: in_scope boolean, CIDR/wildcard matching ``` ### Tactical Tools ```bash # cred_spray - Plan credential spray # Inputs: credentials list, discovered services # Output: spray plan across SMB/WinRM/RDP/LDAP/SSH # attack_path_suggest - Graph-based attack path finding # Algorithm: Dijkstra + Yen's K-shortest paths # Output: Ranked paths to objective # tunnel_manage - Manage pivot tunnels # Supports: SSH, chisel, ligolo # Tracks: Live sessions, tunnel topology ``` ### State Management Tools ```typescript // state_update - Record findings (30+ mutation types) // Usage patterns: // Add host state_update({ type: "add_host", ip: "10.10.10.5", hostname: "dc01.corp.local", os: "Windows Server 2019" }) // Add service state_update({ type: "add_service", host: "10.10.10.5", port: 445, protocol: "tcp", service: "microsoft-ds", version: "Windows Server 2019" }) // Add vulnerability state_update({ type: "add_vuln", host: "10.10.10.5", title: "SMB Signing Not Required", severity: "medium", confidence: 0.9, evidence: "nmap output shows signing disabled" }) // Add credential state_update({ type: "add_cred", username: "administrator", password: "P@ssw0rd", type: "plaintext", domain: "CORP", valid_for: ["smb://10.10.10.5", "winrm://10.10.10.5"] }) // Batch updates state_update([ { type: "add_host", ip: "10.10.10.6" }, { type: "add_service", host: "10.10.10.6", port: 80 } ]) ``` ```typescript // state_query - Query engagement state (20+ query types) // Get all hosts state_query({ type: "hosts" }) // Get services on specific host state_query({ type: "services", host: "10.10.10.5" }) // Get vulnerabilities by severity state_query({ type: "vulns", severity: "critical" }) // Get all credentials state_query({ type: "creds" }) // Get access paths state_query({ type: "access", host: "10.10.10.5" }) // Get AD domain model state_query({ type: "ad_domain" }) // Check attack paths to objective state_query({ type: "attack_paths", source: "10.10.10.5", target: "domain_admin" }) ``` ## Engagement State Structure The engagement state persists at `.pentestcode/state.json`: ```typescript interface EngagementState { // Hosts & services hosts: Array<{ ip: string; hostname?: string; os?: string; ports: Array<{ port: number; protocol: "tcp" | "udp"; state: "open" | "closed" | "filtered"; service?: string; version?: string; banner?: string; }>; }>; // Vulnerabilities vulns: Array<{ id: string; host: string; title: string; severity: "critical" | "high" | "medium" | "low" | "info"; status: "suspected" | "confirmed" | "exploited"; confidence: number; // 0.0-1.0 evidence: string[]; cve?: string; }>; // Credentials creds: Array<{ username: string; password?: string; hash?: string; type: "plaintext" | "ntlm" | "aes256" | "rc4" | "ssh_key"; domain?: string; valid_for: string[]; // URLs where cred works }>; // Access gained access: Array<{ host: string; type: "shell" | "rdp" | "winrm" | "ssh" | "db" | "smb"; username: string; privilege: "user" | "admin" | "system"; }>; // Relationships (entity graph) relationships: Array<{ from: string; to: string; type: "EXPLOITED_VIA" | "CREDENTIAL_FROM" | "ADMIN_OF" | "PIVOT_TO"; cost: number; // For path finding }>; // Active Directory model ad_domain?: { name: string; domain_controllers: string[]; domain_admins: string[]; password_policy: object; trusts: Array<{ domain: string; type: string }>; }; // Current phase phase: "recon" | "scan" | "enumerate" | "exploit" | "post-exploit" | "report"; // Objectives (for CTF/goal-oriented tests) objectives: Array<{ id: string; description: string; status: "pending" | "complete"; flag?: string; }>; } ``` ## Real Workflow Example ```bash # 1. Start engagement pentestcode you: "pentest 10.10.10.5, goal is domain admin" # Agent flow: # - Spawns scanner agent → runs nmap # - Parses XML with nmap_parse → populates hosts/services in state # - Recognizes ports 88 (Kerberos) + 389 (LDAP) → identifies DC # - Spawns 3 parallel enumerators: SMB, LDAP, HTTP # - SMB enumerator finds null session → writable share # - LDAP enumerator extracts user list → updates state # - HTTP enumerator runs gobuster → finds admin portal # - Identity agent runs AS-REP roast → gets hash # - Exploiter runs hashcat → cracks password # - Post-exploit agent sprays cred across all services # - WinRM access gained → spawns shell # - Dumps SAM/LSA → extracts domain admin hash # - Updates state with EXPLOITED_VIA relationships # - Generates findings.md with evidence chain # 2. Check progress /status # Shows: 1 DC, 7 services, 12 vulns, 3 creds, WinRM access # 3. View findings /vulns # Lists vulnerabilities by severity with evidence # 4. Review credentials /creds # Shows cracked passwords and where they work # 5. Generate report /report # Creates markdown pentest report with timeline ``` ## Skills System PentestCode loads knowledge packs on demand: ```bash # Skills directory: .pentestcode/skills/ # Phase checklists (6 files) PHASE_RECON.md PHASE_SCAN.md PHASE_ENUMERATE.md PHASE_EXPLOIT.md PHASE_POST_EXPLOIT.md PHASE_REPORT.md # Service knowledge (9 files) SERVICE_SMB.md SERVICE_SSH.md SERVICE_HTTP.md SERVICE_DNS.md SERVICE_DATABASES.md # ... etc # Playbooks (4 files) PLAYBOOK_INFRASTRUCTURE.md PLAYBOOK_ACTIVE_DIRECTORY.md PLAYBOOK_WEB_APPLICATION.md PLAYBOOK_CLOUD.md ``` Add custom skills by creating `SKILL_NAME.md`: ```markdown # Custom Skill: Internal App Testing ## Tools - Custom scanner at /opt/internal-scanner - Credential wordlist at /wordlists/internal.txt ## Workflow 1. Run internal-scanner against target 2. Parse output with custom parser 3. ... ``` Skills are plain markdown — no code changes needed. ## Mode-Specific Patterns ### Auto Mode (Autonomous) ```bash pentestcode --prompt "pentest 10.10.10.0/24" # Agent: # - Plans full engagement # - Spawns subagents as needed # - Progresses through phases automatically # - Stops at checkpoints for review (if pause=checkpoint) ``` ### Free Mode (Unrestricted) ```bash pentestcode /mode free you: "scan this random IP I found: 8.8.8.8" # Agent: # - Bypasses scope checks # - No phase structure # - Responds to direct requests # - Useful for ad-hoc testing ``` ### Guided Mode (Step-by-Step) ```bash pentestcode /mode guided you: "pentest 10.10.10.5" # Agent proposes: "Run nmap -sS -sV -p- 10.10.10.5?"