Skip to content

User Guide

Jump to bottom
blackbuble edited this page Oct 30, 2026 · 2 revisions

User Guide — PentestAI

Complete guide from installation to reporting. Divided by level: junior, mid, and advanced.

Table of Contents

  1. Installation
  2. First Configuration
  3. Core Concepts
  4. First Session — Junior Mode
  5. Real Engagement — Mid Mode
  6. Senior Workflow — Advanced Mode
  7. Full Command Reference
  8. Common Scenarios

Installation

Option 1: Auto Setup (recommended)

Works on Linux and macOS. Requires Python 3.11+.

git clone https://github.com/blackbuble/pentestai.git
cd pentestai
bash setup.sh

What setup.sh does:

  1. Checks Python 3.11+ is installed
  2. Creates a virtual environment (.venv/)
  3. Installs 12 core dependencies (~30 seconds)
  4. Adds pentestai-activate alias to your shell

After setup:

source .venv/bin/activate
pentestai guided             # interactive wizard
pentestai autopilot http://target.com --report report.html

Add extras later without reinstalling:

pip install -e ".[ai]"      # LLM-powered analysis
pip install -e ".[full]"    # everything (38 deps)

Available extras: ai, memory, api, browser, infra, tui, full.

Option 2: Docker (full stack)

Use this if you want Metasploit, Neo4j, and Qdrant included — no Python setup needed.

git clone https://github.com/blackbuble/pentestai.git
cd pentestai
cp .env.example .env                    # set ANTHROPIC_API_KEY
docker compose --profile msf up -d
docker attach pentestai-pentestai-1     # detach: Ctrl-p Ctrl-q

The image ships nmap, sqlmap, nikto, gobuster, ffuf, hydra, whatweb, msfconsole, Node.js, and Python.

Full Docker guide (reset, rebuild, update, API mode): Deployment.

Run

pentestai                    # interactive CLI shell
pentestai autopilot URL      # autonomous scan
pentestai guided             # step-by-step wizard
pentestai --api              # API server on :8080

First Configuration

Fastest way — one env var

export ANTHROPIC_API_KEY=sk-ant-...
python3 __main__.py

PentestAI automatically detects the available providers from env vars. No additional configuration is needed.

For WorkBuddy or other custom endpoints:

export CUSTOM_LLM_BASE_URL=https://api.workbuddy.ai/v1
export CUSTOM_LLM_API_KEY=<key>
export CUSTOM_LLM_MODEL=<model>

See LLM_AGENTS.md for the full list of all supported providers.

Full setup — .env file

cp .env.example .env
nano .env

Minimum contents:

ANTHROPIC_API_KEY=sk-ant-...
REPORT_AUTHOR=Your Name
REPORT_COMPANY=Company

Verify the LLM is configured

PentestAI> llm

Expected output:

  Model: Claude Sonnet (anthropic)
  Tier:  complex
  Status: ✅ configured

If it is empty, run llm add for the interactive wizard.

Core Concepts

Skill Mode

PentestAI has three modes that change how the AI behaves:

Mode Suitable for Behaviour
junior Learning pentest, first time using a tool Verbose, guided, explanation of every step
mid Already familiar with tools, learning methodology Balanced, explanations of the important parts
advanced Senior pentester, tools memorized Silent except findings, autonomous 
PentestAI> mode junior    # switch to junior
PentestAI> mode advanced  # switch to advanced
PentestAI> mode           # show current mode

Default: junior. Override via env: export PENTESTAI_MODE=advanced

Session

Every engagement is one session. A session stores: target, findings, services, credentials, notes, evidence, and history.

PentestAI> session new htb-lame     # start a new session
PentestAI> session save             # save progress
PentestAI> session load htb-lame    # resume the previous session
PentestAI> session list             # list all sessions

Scope

Must be set before testing begins. PentestAI blocks every action outside the scope.

PentestAI> scope add 10.10.10.0/24
PentestAI> scope add 10.10.10.3
PentestAI> scope add htb.local
PentestAI> scope show

Engagement Brief

Set at the start of an engagement to enforce client-specific rules:

PentestAI> brief set

The wizard will ask: client name, engagement type, emergency contact, no brute force?, notify before exploit?, production systems?

First Session — Junior Mode

Suitable for: learning, practice on DVWA/HTB.

Setup

PentestAI> mode junior
PentestAI> session new practice-dvwa
PentestAI> scope add 127.0.0.1
PentestAI> target 127.0.0.1

Recon

PentestAI> recon

In junior mode, PentestAI will:

  • Run nmap and show the output with explanations
  • Probe HTTP and detect technologies
  • Analyze the results with AI and explain what was found
  • Suggest the next steps

View Results

PentestAI> services        # all discovered services
PentestAI> findings        # discovered vulnerabilities
PentestAI> pending         # what has not been followed up

Ask the AI

PentestAI> ask "which service from the earlier scan looks most interesting?"
PentestAI> ask "how do I exploit Samba 3.0.20?"

Report

PentestAI> report quick    # without AI, straight from the data
PentestAI> report          # with AI analysis (requires an LLM)

Real Engagement — Mid Mode

Suitable for: internal pentest, bug bounty, client engagements.

Setup Engagement

PentestAI> mode mid
PentestAI> session new engagement-acme-2026
PentestAI> brief set

Fill in the brief:

Client name: AcmeCorp
Type: external
Emergency contact: 081234567890
No brute force: y
Notify before exploit: y
Report deadline: 2026-11-30

Set Scope

PentestAI> scope add 203.0.113.0/24
PentestAI> scope add acme.com
PentestAI> scope add *.acme.com

Staged Recon

PentestAI> recon 203.0.113.10
PentestAI> scan web http://203.0.113.10
PentestAI> enum dirs http://203.0.113.10

When You Find Something Outside the Scope

PentestAI> expand 203.0.114.5 "trust relationship discovered during AD enumeration"
# → Request created with an ID, e.g. [a3f8e2b1]
# Contact the client for approval
PentestAI> scope approve a3f8e2b1

Attach Evidence to a Finding

PentestAI> findings
# → [HIGH] SQLi in /login.php  (id: 8f3a)
PentestAI> evidence attach 8f3a sqlmap_output
# → Paste output, Ctrl+D
# → ✅ Evidence attached. Hash: a3f8e2b1c9d4f7e0

Generate Report

PentestAI> validate            # mark candidates vs validated findings
PentestAI> poc                 # generate PoC for all findings
PentestAI> report              # HTML with AI analysis
PentestAI> report docx         # Word for the client
PentestAI> report sarif        # SARIF for CI / code scanning
PentestAI> report all          # every format, including PDF
PentestAI> evidence export     # ZIP bundle of all evidence

Senior Workflow — Advanced Mode

Suitable for: senior pentester, red team, complex engagements.

Quick Setup

export PENTESTAI_MODE=advanced
export ANTHROPIC_API_KEY=sk-ant-...
python3 __main__.py
PentestAI> session new htb-lame
PentestAI> scope add 10.10.10.0/24
PentestAI> target 10.10.10.3
PentestAI> brief set

Autonomous Recon

Advanced mode: the agent runs silently, reporting only findings.

PentestAI> react 10.10.10.3 "find entry points, prioritize RCE"

Minimal output — only findings appear:

[CRITICAL] CVE-2007-2447 Samba 3.0.20 usermap_script — 10.10.10.3:445

Full Kill Chain

PentestAI> chain 10.10.10.3

Runs 6 phases: RECON → ENUMERATION → WEB_TESTING → EXPLOITATION → POST_EXPLOIT → REPORTING. In advanced mode there are no phase gates — the agent proceeds directly.

Pending Check

PentestAI> pending

Check what has not been followed up: suspicious services not yet enumerated, interesting endpoints not yet tested, credentials not yet tried on other services, Critical findings without evidence.

Plugin Mode

If you need a custom tool:

PentestAI> plugin list
PentestAI> plugin enable my_custom_scanner

Full Command Reference

Target & Scope

target <ip|host>                    Set the session's main target
scope add <ip/cidr|domain>          Add to scope
scope show                          Show active scope
scope off / on                      Disable/enable enforcement
expand <target> <reason>            Formal scope expansion request
scope approve <ref>                 Approve pending expansion
scope deny <ref> [reason]           Deny pending expansion

Reconnaissance

recon [target] [deep]               Nmap + HTTP + AI analysis
scan web [url]                      Nikto web scan
scan sql [url]                      SQLMap injection test
enum dirs [url]                     Gobuster directory enumeration
auto ["objective"]                  AI-planned scan with an objective

Findings & Evidence

findings                            List all findings
findings add                        Add a finding manually
services                            List discovered services
endpoints                           List discovered endpoints
pending                             What has not been followed up
evidence attach <id> [label]        Attach evidence to a finding
evidence verify [id]                Verify integrity hash
evidence export                     Export ZIP bundle of all evidence
evidence fp <id>                    Mark finding as false positive
note <text>                         Add a session note

Engagement Management

brief                               Show the current brief
brief set                           Interactive setup wizard
brief no-brute-force                Add a no brute force constraint
brief production <ip>               Mark an IP as production
brief contact <name/phone>          Set emergency contact

Report

report                              HTML + AI analysis
report quick                        HTML without AI
report docx                         Word (.docx) for the client
report sarif [all]                  SARIF 2.1.0 (validated only by default)
report pdf                          HTML → PDF (Playwright/Chromium)
report all                          HTML + Markdown + SARIF + DOCX + PDF
poc                                 Generate PoC for all findings
validate                            Run the exploit-validation gate
validate <id>                       Approve one finding manually

Browser

browser <url>                       Open a page in headless Chromium
browser shot <url> [path]           Full-page screenshot
browser text|html <url>             Extract rendered text/HTML
browser login <url> [sel...]        Log in using TEST_ACCOUNT_A_*
browser close                       Close the browser

MCP

mcp list                            Configured MCP servers
mcp tools <server>                  Tools exposed by a server
mcp call <server> <tool> <json>     Invoke an MCP tool
mcp close [server]                  Stop one server or all

Session

session                             Current session info
session new [name]                  Start a new session
session save [name]                 Save to disk
session load <name>                 Load a saved session
session list                        List all sessions
history                             Command history
tools                               Binary tools status

LLM

llm                                 Status and active model
llm add                             Add a model (wizard)
llm remove <model>                  Remove a model
llm routing on|off                  Toggle tier-based routing
llm tier <model> <tier>             Change tier (simple/medium/complex/all)
llm test                            Test connection for all models

Skill Mode

mode                                Show current mode + comparison table
mode junior                         Verbose, guided, phase gates ON
mode mid                            Balanced
mode advanced                       Silent, autonomous, phase gates OFF

Autonomous Agent

autonomy [guided|semi|auto]         Get/set autonomy level
react [target] ["objective"]        ReAct agent loop
chain [target]                      Full kill chain (6 phases)
bizlogic <url>                      Business logic tests
benchmark [profile]                 CTF/HTB benchmark (junior/mid mode)

Memory & Knowledge

memory status                       Memory system status
memory graph [ip]                   Attack graph for host
search <query>                      Search the knowledge base
ask <question>                      Ask the AI about the current session

Phase 6

orchestrate [target] [--seq]            Multi-agent: recon+web+infra+report parallel
ptes                                    Generate PTES report (JSON + Markdown)
iso27001                                Generate ISO 27001 risk register (JSON)
marketplace [search|install|info|...]   Plugin marketplace

System

plugin list                         List available plugins
plugin enable/disable <name>        Toggle plugin
clear                               Clear screen
help                                Show help
quit / exit                         Save and exit

Common Scenarios

HTB / CTF

export ANTHROPIC_API_KEY=sk-ant-...
export PENTESTAI_MODE=advanced
# Connect the VPN first: openvpn lab.ovpn

python3 __main__.py
PentestAI> session new htb-machine-name
PentestAI> scope add 10.10.10.0/24
PentestAI> target 10.10.10.3
PentestAI> react "enumerate all services, find RCE vector"

Local DVWA (without HTB, without VPN)

docker run -d -p 18080:80 vulnerables/web-dvwa
export ANTHROPIC_API_KEY=sk-ant-...

python3 __main__.py
PentestAI> mode junior
PentestAI> session new dvwa-practice
PentestAI> scope add 127.0.0.1
PentestAI> target http://localhost:18080
PentestAI> recon
PentestAI> scan web http://localhost:18080
PentestAI> scan sql http://localhost:18080/vulnerabilities/sqli/?id=1

Bug Bounty

PentestAI> mode mid
PentestAI> session new bugbounty-target-2026
PentestAI> scope add target.com
PentestAI> scope add *.target.com
PentestAI> brief no-brute-force       # usually prohibited in bug bounties
PentestAI> recon target.com
PentestAI> auto "find XSS, IDOR, and auth bypasses in target.com"

Internal Pentest with a Client

PentestAI> mode mid
PentestAI> session new internal-acme-2026-10
PentestAI> brief set                  # fill in complete client data
PentestAI> scope add 192.168.0.0/16   # internal network
PentestAI> brief production 192.168.1.1  # router, do not touch

# After testing is complete:
PentestAI> poc                        # capture all evidence
PentestAI> report docx                # Word report for the client
PentestAI> evidence export            # ZIP bundle for the attachment

API Server (integration with other systems)

python3 __main__.py --api
# → http://localhost:8080
# → Docs: http://localhost:8080/docs
# Create an API key
curl -X POST http://localhost:8080/api/v1/auth/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-automation"}'

# Create a session and start a scan
curl -X POST http://localhost:8080/api/v1/sessions \
  -H "X-API-Key: psk_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "automated-scan", "target": "10.0.0.1"}'

Phase 6 — Multi-Agent & Professional Reporting

Multi-Agent Orchestration

orchestrate runs four sub-agents in parallel (or sequentially with --seq):

PentestAI> orchestrate 10.10.10.3

Execution order:

  1. ReconSubAgent — nmap + http probe + subdomain + cert scan (sequential, provides data for the other agents)
  2. WebSubAgent + InfraSubAgent — run in parallel in advanced/mid mode
  3. ReportSubAgent — tag all findings + generate HTML + Word report

In junior mode: there is a phase gate approval before every transition. In advanced mode: fully autonomous, no interruptions.

PentestAI> orchestrate 10.10.10.3        # parallel (default)
PentestAI> orchestrate 10.10.10.3 --seq  # sequential

PTES Report

Report format follows the Penetration Testing Execution Standard:

PentestAI> ptes

Output: two files in reports/output/:

  • *_ptes.json — machine-readable, can be imported into SIEM/ticketing
  • *_ptes.md — Markdown ready to send to the client

Contains: per-finding phase mapping (Phase 2/4/5/6), business impact, overall risk rating, executive summary.

ISO 27001 Risk Register

Export findings as an ISO 27001 Annex A risk register:

PentestAI> iso27001

Output: *_iso27001.json with risk scoring (likelihood × impact), ISO Annex A control mapping, treatment status, residual risk.

Plugin Marketplace

Discover and install community plugins:

PentestAI> marketplace                        # list all plugins
PentestAI> marketplace search active          # search "active directory"
PentestAI> marketplace install ad-suite       # install the plugin
PentestAI> marketplace info ad-suite          # plugin details
PentestAI> marketplace installed              # already installed
PentestAI> marketplace fetch                  # refresh from GitHub

Plugins are installed into the plugins/ directory and their checksum is verified before execution.

Tips

Test before an engagement:

PentestAI> llm test           # make sure the LLM is connected
PentestAI> tools              # check which binaries are available

Save often:

PentestAI> session save

Sessions are saved automatically on quit, but a manual save is safer.

If you get stuck:

PentestAI> pending            # check what has not been followed up
PentestAI> ask "at this point, what should I try?"

Change mode mid-engagement: The mode can be changed at any time without losing session data.

PentestAI> mode advanced      # switch to autonomous
PentestAI> react              # let the AI continue
PentestAI> mode mid           # return to manual afterwards

Home

Getting Started

Core

Scanning

Reporting

Project

Clone this wiki locally