# PentestPilot

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

[![Made for Pentesters](https://img.shields.io/badge/made_for-pentesters-111827?style=for-the-badge)](#)
[![AI‑Ready](https://img.shields.io/badge/AI-Ready-10B981?style=for-the-badge)](#)
[![Resumeable Pipelines](https://img.shields.io/badge/Pipelines-Resumeable-2563EB?style=for-the-badge)](#)
[![Dashboard](https://img.shields.io/badge/Dashboard-Color%20%7C%20JSON-7C3AED?style=for-the-badge)](#)

## 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 <task> → 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/<target>/manifest.json
- Manage via bin/automation/manifest.py
  - init, set, get, addlist, show, task <name> 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
- See [HOWTO](HOWTO.md) for in-depth usage, recommended tools, pipeline semantics, dashboard legend, manifest schema, and examples.
- See [TOOLKIT](TOOLKIT.md) for a categorized command catalog with examples and links 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.