PentesterFlow/agent

PentesterFlow – Human‑in‑the‑Loop Agentic AI CLI for Pen‑Testing

What it is – An open‑source terminal‑based assistant that lets a security analyst drive an LLM‑powered “agent” through a penetration‑testing engagement. The agent can plan, call real security tools (curl, shell, Burp, file utilities, etc.), and ask the analyst for approval before performing any potentially destructive action. All interactions are logged, evidence is saved, and the session can be resumed later.

Why it matters – Generic AI agents often hallucinate findings, lose context over long engagements, and hide what they actually do. PentesterFlow tackles these problems by:

• Keeping the human in control with permission tiers (ask, auto-safe, yolo).
• Showing every tool call (e.g., the exact curl command) and storing request/response evidence.
• Persisting “memory” across sessions so the model remembers project‑specific facts without needing to be retrained.
• Providing built‑in, security‑focused skills (recon, IDOR, SSRF, JWT, GraphQL, etc.) that act as structured playbooks.

How you use it

1. Install – Run the one‑liner install script (or download a pre‑built binary) for macOS, Linux, or Windows. The script verifies the SHA‑256 checksum.

   curl -fsSL https://raw.githubusercontent.com/PentesterFlow/agent/main/install.sh | sh
   

2. Start the CLI – pentesterflow launches an OpenTUI chat interface.
3. Configure a model – Use /provider or pass --backend/--model flags. It works with local models via Ollama/LM Studio and with hosted APIs (OpenAI‑compatible, Anthropic, Gemini, Groq, Kimi, DeepSeek, etc.).
4. Set the target – /target https://app.example.com.
5. Give an objective – e.g., test the orders API for broken access control. The agent will:
   • Plan a series of steps.
   • Call tools (HTTP requests, shell commands, Burp ingest, file edits).
   • Pause for your approval on any “sensitive” action.
   • Record evidence and, once you confirm a finding, write a Markdown report under ./findings/.
6. Resume later – pentesterflow --resume <session‑id> loads the saved JSON session, shows a recap, and continues where you left off.

Key features

Feature	What you get
Agent loop	Plan → act → observe → verify → report → learn, with optional auto‑continue.
Model flexibility	Supports Ollama, LM Studio, Kimi, Groq, OpenRouter, DeepSeek, Gemini, Anthropic, and any OpenAI‑compatible endpoint.
Tool suite	Shell/Bash, HTTP client, file read/write, grep/glob, web fetch/search, Burp bridge, browser capture, coverage tracking, background jobs, and extensible plugins.
Skills (playbooks)	Ready‑made markdown‑based methodologies for recon, web vulns, SSRF, SSTI, JWT, GraphQL, race conditions, etc.; can be forked into child agents to keep the main context lean.
Permission tiers	ask (prompt before each risky call), auto-safe (auto‑approve safe calls), yolo (auto‑approve everything – lab only).
Transparent execution	Every command is displayed, copy‑pasteable, and logged in JSON‑lines format.
Continuous learning	After each turn the system silently stores useful facts, successful workflows, and mistakes in ./.pentesterflow/intelligence/ (project) and ~/.pentesterflow/intelligence/ (personal). These are injected as hidden context in future sessions.
Session memory & resume	Full conversation, compacted memory, target state, and periodic snapshots stored under ~/.pentesterflow/sessions/.
Reporting	Confirmed findings are written as Markdown (./findings/<slug>.md) with PoC, impact, remediation, and attached request/response evidence. Export to SARIF via /report.
Burp integration	Companion bridge lets you push selected Burp requests into the CLI and pull back confirmed findings.
Browser capture / MCP	Ingest captured browser traffic as structured data for the agent to query.

Security model – The tool can execute arbitrary shell commands and edit files, but it never does so without explicit user consent (unless you enable the risky yolo mode). Secrets are redacted before being written to any persistent memory file. The README stresses that the software must only be used on systems where you have explicit authorization.

Typical workflow example

$ pentesterflow
> /target https://app.example.com
> test the orders API for broken access control

[Agent] plans: enumerate /orders endpoints → try IDOR → confirm finding

[Tool] http GET https://app.example.com/api/v1/orders/1043
[Tool] shell curl ... (awaiting approval)
> approve

[Agent] confirms high‑severity IDOR, writes ./findings/idor-orders.md

Ready – qwen3:14b – app.example.com

Who it’s for – Security engineers, bug bounty hunters, or red‑team members who want LLM assistance while retaining full auditability and control.

---

All information above is taken directly from the repository’s README; no additional features have been inferred.