PentestPilot/README.md

PentestPilot

AI‑assisted pentest recon and orchestration toolkit with resumeable pipelines, a rich terminal dashboard, and tech‑aware routing.

Overview

Script‑driven toolkit to accelerate common OSCP/HTB workflows: discovery, web recon, AD, password hygiene, shells, tunnels, transfers, privilege escalation, post‑exploitation, reporting.

AI agents and orchestrators automate reconnaissance and organize results. Works with OpenAI (OPENAI_API_KEY) or local Ollama.

New? Start with HOWTO.md:1 for step‑by‑step usage, dashboard details, and resumeable pipelines.

Quick Start (Dashboard in ~3–5 minutes)

• Clone/open the repo and load the shell profile: echo "source $(pwd)/.zshrc.htb" >> ~/.zshrc && exec zsh
• Minimal deps (Debian/Ubuntu): sudo apt update && sudo apt install -y nmap curl jq ripgrep python3 tmux pipx install httpx-toolkit nuclei gowitness || true
• Create a target workspace: settarget target.htb
• Kick off one‑click recon (resume‑aware): agent full target.htb
• Watch progress: dashboard --compact (add --no-color if needed)
• Resume many later: resumeall (resumes incomplete pipelines for all targets) See HOWTO.md:1 for details, alternatives, and troubleshooting.

AI Setup

• OpenAI: export OPENAI_API_KEY=sk‑...
• Ollama: install and run ollama; optionally export OLLAMA_MODEL=llama3.1
• Test: ask.py "You online?"

Key Commands (aliases)

• nq | nf | nu → nmap quick/full/udp
• webrecon → focused web recon on detected web ports
• wideweb <hosts.txt> → httpx + screenshots + nuclei
• fullpipe <domain|hosts.txt> → chain DNS→httpx→nuclei→tech route (+WPScan)
• notesinit / notesattach → notes scaffolding
• agent → multi‑agent runner (web|full|notes|post|ad)

AI Orchestration

• bin/ai/agent_orchestrator.py
• agent web hosts.txt → httpx→nuclei→screenshots→AI plan (resume-aware; use --force to rerun)
  • agent full domain.tld → run full pipeline
  • agent notes $TARGET → init + attach notes
• agent post $TARGET → linux_loot + report pack (resume-aware)
  • agent ad $TARGET → enum4linux‑ng + smbmap + rpcclient
• Robust completion utils: bin/ai/_ai_utils.py (retries, provider fallback)
• Planning/Review tools: commands_planner.py, orchestrate_web.py, review_findings.py

State & Resume

• Target manifest at targets//manifest.json
• Manage via bin/automation/manifest.py
  • init, set, get, addlist, show, task start|ok|fail [meta], taskstatus, taskreset
• Pipelines update tasks with timestamps and metadata (dns, httpx, nuclei, techroute, wpscan, full_pipeline). Agents add web_* (httpx/nuclei/screenshots/plan), notes_* and post_* tasks, and ad_* tasks.

Features at a Glance

• Resumeable pipelines (agent full, resumeall) and color dashboard with severity bars + per‑phase durations
• Evidence‑first storage (httpx/nuclei JSON + summaries) to drive next actions
• Tech‑aware routing (WP/Drupal/Joomla/Jenkins/SonarQube/Magento/Jira/Confluence)
• AI helpers for planning and findings review (OpenAI or Ollama)
• QoL utilities: proxies, cleanup, tmux bootstrap, URL extraction

Dependencies

• Recommended: nmap, ffuf, httpx, nuclei, gobuster, gowitness, subfinder|amass, sqlmap, wpscan, droopescan, joomscan, magescan, impacket, ldap-utils, snmp, ripgrep, jq, python3 requests, socat, chisel

Documentation

• HOWTO.md:1 — in‑depth “how to” with recommended tools, pipeline semantics, dashboard legend, manifest schema, and examples.
• TOOLKIT.md:1 — command catalog grouped by category with references back to HOWTO.

Docs Index (quick links)

• HOWTO: Overview — HOWTO.md#overview
• Install & Setup — HOWTO.md#install--setup
• Core Env Vars — HOWTO.md#core-env-vars
• Target Workflow — HOWTO.md#target-workflow
• Automation & Orchestration — HOWTO.md#automation--orchestration
• Dashboard (Status & Evidence) — HOWTO.md#dashboard-status--evidence
• Manifest (State & Resume) — HOWTO.md#manifest-state--resume
• AI Integrations — HOWTO.md#ai-integrations
• Web Recon & Routing — HOWTO.md#web-recon--routing
• Active Directory & SMB — HOWTO.md#active-directory--smb
• Passwords & Wordlists — HOWTO.md#passwords--wordlists
• Shells, Transfers, Privesc — HOWTO.md#shells-transfers-privesc
• Tunnels & Port Forwards — HOWTO.md#tunnels--port-forwards
• QoL Utilities — HOWTO.md#qol-utilities
• Post‑Exploitation & Reporting — HOWTO.md#post-exploitation--reporting
• Troubleshooting — HOWTO.md#troubleshooting

Safety

• Intended for systems you have explicit permission to test. Scripts default to safe, passive checks unless you opt‑in to aggressive actions.