PentestCode

AI-Powered Autonomous Penetration Testing Agent

The #1 Open-Source AI Security Testing Tool for Ethical Hackers, Bug Bounty Hunters & Security Researchers

Visit Landing Page | Documentation

---

Multi-Agent AI Architecture · Persistent Engagement State · 20+ LLM Providers · 18 Pentest Tools · 19 Knowledge Packs

---

GitHub Action

Run AI-powered penetration tests directly in your CI/CD pipeline.

Quick Start

- name: Run PentestCode Scan
  uses: ganeshkrishnareddy/pentestcode@main
  with:
    target: ${{ secrets.STAGING_URL }}
    mode: quick
    api-key: ${{ secrets.OPENAI_API_KEY }}

Full Configuration

- name: Run PentestCode Scan
  uses: ganeshkrishnareddy/pentestcode@main
  with:
    target: https://staging.example.com
    mode: full
    output-format: sarif
    scan-depth: 4
    tools: nmap,sqlmap,nuclei
    llm-provider: openai
    llm-model: gpt-4
    api-key: ${{ secrets.OPENAI_API_KEY }}
    fail-on-critical: true
    upload-results: true

- name: Upload SARIF to GitHub Security
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: pentest-results/report.sarif

GitHub Action Marketplace

Inputs

Input	Required	Default	Description
target	Yes	-	Target URL or IP to test
mode	No	quick	Scan mode: quick, full, stealth
output-format	No	json	Output: json, markdown, sarif
scan-depth	No	2	Depth 1-5 (1=shallow, 5=deep)
tools	No	all	Tools: nmap,sqlmap,nikto,nuclei or all
llm-provider	No	openai	LLM: openai, anthropic, google
llm-model	No	gpt-4	Model to use
api-key	Yes	-	API key for LLM provider
fail-on-critical	No	false	Fail if critical vulns found
upload-results	No	true	Upload results as artifact

Outputs

Output	Description
results	Path to results file
critical-count	Number of critical vulnerabilities
high-count	Number of high vulnerabilities
summary	Scan summary message

CI/CD Integration Examples

GitHub Actions - Security Scan on Push

name: Security Scan
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  pentest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run PentestCode
        uses: ganeshkrishnareddy/pentestcode@main
        with:
          target: ${{ vars.STAGING_URL }}
          mode: quick
          api-key: ${{ secrets.OPENAI_API_KEY }}
          
      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: pentest-results/report.sarif

Nightly Deep Scan

name: Nightly Security Audit
on:
  schedule:
    - cron: '0 2 * * *'

jobs:
  deep-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Run PentestCode Full Scan
        uses: ganeshkrishnareddy/pentestcode@main
        with:
          target: ${{ secrets.PRODUCTION_URL }}
          mode: full
          scan-depth: 5
          tools: all
          output-format: sarif
          api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          llm-provider: anthropic
          llm-model: claude-sonnet-4-20250514
          
      - name: Create Issue on Critical Findings
        if: steps.scan.outputs.critical-count > 0
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: `🚨 Critical vulnerabilities found: ${process.env.CRITICAL_COUNT}`,
              body: `PentestCode found critical vulnerabilities.\n\nSummary: ${process.env.SUMMARY}`,
              labels: ['security', 'critical']
            })

---

Support the Developer

Maintaining PentestCode requires continuous development, testing, and updates.

If you find this project useful, consider supporting its development.

Click here to donate via Razorpay

Every contribution helps improve PentestCode and keeps it free for the community.

Thank you for your support!

---

About

PentestCode is an AI-powered autonomous penetration testing agent that runs in your terminal. It is the ultimate offensive security tool for ethical hackers, bug bounty hunters, penetration testers, and security researchers.

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 experienced operator would.

Why PentestCode?

Feature	Benefit
AI-Powered	Uses LLMs (Claude, GPT-4, Gemini) to make intelligent decisions
Autonomous	Runs full pentest chains without human intervention
Multi-Agent	13 specialized agents working in parallel
Persistent State	Remembers everything across sessions
18+ Tools	nmap, nuclei, sqlmap, bloodhound, gobuster and more
19 Skills	Curated knowledge for every attack surface
20+ Providers	Works with any LLM provider
Self-Hosted	Your data never leaves your machine

---

Features

Multi-Agent AI System

• 13 specialized agents — recon, scanner, enumerator, exploiter, identity, infrastructure, webapp, post-exploit, exploit-dev, critic, reporter, and more
• Strategist-coordinator model — based on HPTSA research for 4.3x improvement over single agents
• Parallel execution — multiple agents work simultaneously for faster results

Persistent 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
• Attack paths — cost-based Dijkstra + Yen's K-shortest routes through the relationship graph
• AD domain model — domain controllers, trusts, admins, password policy, GPOs

18 Built-in Pentest Tools

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

19 Curated Knowledge Packs

• 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

20+ LLM Providers

Provider	Provider	Provider
Anthropic	OpenAI	Google
Azure	AWS Bedrock	Ollama
Groq	Mistral	DeepSeek
xAI	OpenRouter	LM Studio

---

Architecture

                      PENTEST (LEAD)
                      Coordinator
                            |
        +--------+----------+----------+--------+--------+
        v        v          v          v        v        v
     RECON    SCANNER   EXPLOITER  IDENTITY  POST-    WEBAPP
      AGENT    AGENT      AGENT      AGENT   EXPLOIT   AGENT
        |        |          |          |        |        |
        v        v          v          v        v        v
    INFRA-    EXPLOIT     CRITIC    REPORT-  ADMIN-   WEB-
    STRUCT      DEV                  ER       ID       APP

The lead agent breaks the engagement into tasks and dispatches 13 specialist subagents in parallel — each with its own system prompt, tool permissions, and domain knowledge.

---

Full Attack Chain

One instruction in, a complete penetration test out:

you: "pentest 10.10.10.5, goal is domain admin"

Stage	What the Agent Does	Tools Used
1	Scan — Finds open ports and parses results	nmap, masscan
2	Recognize — Identifies services and attack surfaces	Service detection
3	Enumerate — Deep enumeration of services	smbclient, ldapsearch, gobuster
4	Attack — Exploits vulnerabilities	Custom exploits, Metasploit
5	Spray — Tests credentials across services	CrackMapExec, NetExec
6	Exploit — Gains initial foothold	WinRM, SSH, RDP
7	Post-Exploit — Dumps hashes, extracts secrets	Mimikatz, secretsdump
8	Report — Documents everything with evidence	Custom reports

---

Installation

One-Line Install (Recommended)

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

Package Manager

# npm
npm install -g @ganeshkrishnareddy/pentestcode

# yarn
yarn global add @ganeshkrishnareddy/pentestcode

# pnpm
pnpm add -g @ganeshkrishnareddy/pentestcode

# bun
bun add -g @ganeshkrishnareddy/pentestcode

From Source

git clone https://github.com/ganeshkrishnareddy/pentestcode.git
cd pentestcode
bun install
bun run build --single --skip-embed-web-ui

Download Binary

Platform	Architecture	Download
Linux	x64	pentestcode-linux-x64.tar.gz
Linux	ARM64	pentestcode-linux-arm64.tar.gz
macOS	ARM64	pentestcode-darwin-arm64.zip
macOS	x64	pentestcode-darwin-x64.zip
Windows	x64	pentestcode-windows-x64.exe

---

Quick Start

# 1. Authenticate with your LLM provider
pentestcode auth login

# 2. Start an interactive session
pentestcode

# 3. One-shot mode
pentestcode --prompt "scan 10.10.10.0/24 and enumerate all services"

# 4. Run a full pentest
pentestcode --prompt "pentest 10.10.10.5, goal is domain admin"

---

Commands

Slash Commands

Command	Description	Example
/status	Engagement dashboard — hosts, vulns, creds, phase	/status
/targets	Host and service table	/targets
/vulns	Findings by severity	/vulns
/creds	Discovered credentials	/creds
/scope	View/edit target scope	/scope 10.10.10.0/24
/phase	Phase management	/phase enumerate
/mode	Switch auto / free / guided	/mode auto
/pause	Pause on findings	/pause always
/report	Generate a pentest report	/report

Execution Modes

Mode	Description	Best For
auto	Runs through pentest phases autonomously	Full engagements
free	No phase structure; responds to your requests	CTFs, specific tasks
guided	Step by step; proposes each action	Learning, sensitive targets

---

Examples

Bug Bounty

pentestcode --prompt "find SQL injection and XSS on https://target.com"

Network Assessment

pentestcode --prompt "full network pentest of 192.168.1.0/24, escalate to domain admin"

CTF Challenge

pentestcode --prompt "solve the HackTheBox challenge at 10.10.10.5, flag is root.txt"

---

Configuration

Config lives at .pentestcode/pentestcode.jsonc:

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

---

Tech Stack

Technology	Purpose
TypeScript	Core language
Bun	Runtime and bundler
Effect	Functional effect system
React	TUI and web interface
SQLite	Persistent state storage

Supported Platforms: Linux, macOS, Windows

---

Use Cases

Use Case	Description
Penetration Testing	Full methodology from recon to reporting for corporate networks
CTF Competitions	Flag tracking, objective management, multi-target coordination
Bug Bounty	Web app testing, API security, recon automation
Vulnerability Research	Systematic enumeration and validation of CVEs
Infrastructure Security	Network service auditing, default-credential checks
Security Education	Learn offensive security techniques with AI guidance
Red Team Operations	Advanced persistent threat simulation
Blue Team Testing	Test defenses against AI-powered attacks

---

Roadmap

• Cloud provider integration (AWS, Azure, GCP)
• Mobile application testing
• IoT device enumeration
• Custom tool plugin system
• Collaborative multi-user engagements
• AI-generated remediation plans

---

Contributing

We welcome contributions! Here's how you can help:

1. Report Bugs — Found a bug? Open an issue
2. Suggest Features — Have an idea? Request a feature
3. Submit PRs — Want to contribute? Check out our contributing guidelines
4. Star the Repo — Love the project? Give us a star

---

Author

P Ganesh Krishna Reddy

Platform	Link
Email	pganeshkrishnareddy@gmail.com
GitHub	github.com/ganeshkrishnareddy
LinkedIn	linkedin.com/in/pganeshkrishnareddy
Website	pganeshkrishnareddy.vercel.app
Support	Donate via Razorpay

---

License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Acknowledgements

Built on OpenCode · Powered by Antigravity · Created by P Ganesh Krishna Reddy