PentesterFlow/agent: a terminal agent that keeps the pentester in the approval loop
Agentic offensive-security in your terminal
At a glance
- What is it?
- PentesterFlow is a TypeScript CLI that drives an LLM through recon, enumeration and reporting against a scoped target, gating sensitive actions behind permission tiers. The design bet is that analyst approval, not model quality, is what makes agentic pentesting usable.
- Who is it for?
- Adopt PentesterFlow if you already run an authorized engagement and want reproducible curl-level evidence written to ./findings/<slug>.md rather than a chat transcript. Skip it if you need a multi-tenant platform with central audit storage, or if nobody on the team will review permission prompts.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 15 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap PentesterFlow targets: generic agents that cannot hold a scope
General-purpose coding agents can call a shell, so people already point them at web targets. The failure modes are predictable. The agent loses track of which host is in scope, invents a finding from a pattern match rather than a reproduced response, and forgets everything between sessions on a multi-week engagement. PentesterFlow is aimed at security engineers who hit those three problems and want the agent to stay inside an authorized boundary.
The README frames the audience directly: penetration testers and bug hunters doing authorized work. The warning block is not decorative. The agent can run shell commands, make HTTP requests, edit files and process captured traffic, and the README says so before anything else. That shapes who this is for. It is a tool for someone who already knows what an IDOR looks like and wants the mechanical parts (request construction, evidence capture, write-up) accelerated, not a tool that decides what to test.
The project's answer to hallucinated findings is procedural rather than architectural. The README states that confirm_finding should be used only after reproduction with request and response evidence. That is a convention the model is expected to follow, not a runtime guarantee. Treat it as a strong hint about how the skill playbooks are written, not as proof that every finding in ./findings/ was actually reproduced.
Plan, act, observe, verify: the loop and where the human sits
The agent loop the README names is plan, act, observe, verify, report, learn, with auto-continue and context compaction. Tools available to the loop include shell, HTTP, file tools, search, browser capture, Burp ingest, MCP, jobs and findings. Skills are Markdown playbooks, and a skill can be marked fork so a long playbook runs in a child context instead of filling the parent conversation.
The quickstart transcript shows the shape of a session. A target is set with /target, a request is issued, a skill forks, and the agent writes a finding to ./findings/idor-orders.md. The transcript also shows a shell call using curl with an Authorization header, which matches the curl-first, reproducible commands claim in the README. The intent is that the evidence file contains a command you can paste back into a terminal.
Human oversight is implemented as permission tiers: ask, auto-safe and yolo, plus allow-once or allow-session decisions and a plan mode. The tier names are self-describing, and the README does not publish a table of which tool calls each tier permits. That matters operationally. Before running auto-safe on a live target you would want to read the source to see whether HTTP requests to a scoped host are classified as safe by default. The material does not answer that, so I am not going to guess.
Context handling is the part that separates this from a chat window. Sessions are saved, context is compacted, snapshots are taken, and resuming shows a recap of persistent memory. The README describes this under continuous learning: a local project knowledge base and a personal knowledge base improve later sessions without retraining the model. The mechanism is retrieval from local files, not fine-tuning. That is a meaningful distinction because it means the learned state is inspectable and deletable.
Install and first run, with the exact commands
The installers pull a standalone binary for the platform and verify the published SHA-256 checksum when one is available. On macOS or Linux:
curl -fsSL https://raw.githubusercontent.com/PentesterFlow/agent/main/install.sh | sh
On Windows PowerShell:
irm https://raw.githubusercontent.com/PentesterFlow/agent/main/install.ps1 | iex
Both are pipe-to-shell installers, which is worth pausing on for a security tool. The README says checksums are verified when available, so the guarantee is conditional. If you care, download the asset for your platform from GitHub Releases (pentesterflow-darwin-arm64, pentesterflow-linux-x64, pentesterflow-windows-x64.exe and the arm64 variants) and check the digest yourself. The README notes the x64 standalone binaries are built with Bun's baseline runtime and do not require AVX2, which matters on older x86_64 hardware.
Pinning a version and an install directory uses two environment variables:
PENTESTERFLOW_VERSION=v0.1.6 PENTESTERFLOW_INSTALL_DIR="$HOME/.local/bin" sh -c "$(curl -fsSL https://raw.githubusercontent.com/PentesterFlow/agent/main/install.sh)"
Provider setup is interactive (/provider, /model list, /model <id>) or passed as flags. A local Ollama run looks like:
ollama pull qwen2.5-coder:32b pentesterflow --backend ollama --model qwen2.5-coder:32b
Hosted backends take an API key through the environment, for example GROQ_API_KEY=gsk_... pentesterflow --backend groq --model openai/gpt-oss-20b, or ANTHROPIC_API_KEY=sk-ant-... pentesterflow --backend anthropic --model claude-opus-4-8. There is also an OpenAI-compatible path with --base-url and --api-key, which is how you would point it at a self-hosted gateway. Resuming uses pentesterflow --resume <session-id>.
One inconsistency worth flagging: the README's sample transcript shows PF v0.3.0 while the most recent release listed for the repository is v0.1.20. Either the transcript was written against an unreleased build or the version string in the banner does not track the release tag. Neither reading is confirmed by the material, so verify the version the binary reports after install.
Evidence files and logs as the audit surface
Reporting writes confirmed findings to ./findings/<slug>.md with evidence, impact, a proof of concept and remediation, according to the README. Logs are JSON-lines and session files are described as stable. The combination is the project's audit story: a Markdown artifact a client can read, plus machine-readable logs a script can parse.
The honest limitation is that the finding file is only as good as the model's discipline. confirm_finding is a tool the agent is instructed to call after reproduction. Nothing in the README describes a verifier that re-runs the proof of concept before the file is written. So the review step is on you: open the finding, take the curl command it contains, run it, and check that the response still shows the behaviour. For an IDOR that means two accounts and two tokens, which is exactly the kind of setup the transcript shows being done by hand with a Bearer header. If your engagement cannot tolerate a false positive reaching a draft report, budget time for that pass on every finding.
Coverage tracking and /next are the other half of the reporting picture. The README lists coverage tracking, learned coverage gaps and captured-traffic queries as the mechanisms for large attack surfaces. The idea is that the agent knows which endpoints it has touched and can propose the next one. How coverage is computed (by path, by parameter, by response code) is not specified in the material.
Where PentesterFlow is the wrong tool
Three cases stand out.
First, unattended scanning. The permission tiers include yolo, but the entire pitch is analyst control. If your goal is to point something at a CIDR range and come back tomorrow, a conventional scanner is cheaper and more predictable. An LLM in the loop adds latency and non-determinism per request, and the README's own framing puts approval in the centre rather than at the edge.
Second, model quality. The agent's usefulness tracks the backend you attach. The README lists Ollama, LM Studio, Kimi, Groq, Gemini, Anthropic, OpenAI-compatible endpoints, OpenRouter, DeepSeek and a Naraya router. A small local model will follow a Markdown playbook less reliably than a large hosted one, and the failure will look like a missed vulnerability rather than an error message. There is no evaluation harness described in the material that would tell you which model is good enough for which skill.
Third, environments that need central control. Memory is local, sessions are local, findings are local files. That is good for a solo consultant on a laptop and awkward for a team that needs shared engagement state, role separation or a server-side audit trail. The README does not describe a hosted mode or a sync mechanism, so assume there is not one.
A fourth, smaller point: the agent runs shell commands after approval. On a workstation where the agent also has access to unrelated credentials, an approved command is a broad capability. The permission modal is the only boundary described.
How it differs from pointing a coding agent at a target
The obvious alternative is an existing terminal coding agent with a shell tool, driven by a prompt that says you are a pentester. The difference is not the model. It is the scaffolding around it: built-in skills for recon, web vulnerabilities, SSRF, SSTI, JWT, GraphQL, race conditions, subdomain takeover, Supabase and deserialization; a permission tier system with allow-once and allow-session; a Burp bridge and browser capture for ingesting real traffic; findings written to a fixed path with a fixed structure; and a local knowledge base that persists across sessions.
With a general coding agent you would assemble that yourself: write the playbooks, decide the approval policy, define the output format, and build the traffic-ingest path. That is not impossible, and if you already have a harness you like, the marginal value here is smaller. What you get from PentesterFlow is a pre-built set of security skills and a session model that assumes multi-week engagements rather than a single repository task.
The trade-off runs the other way too. A coding agent is a general tool with a large user base and fast iteration on the agent loop itself. PentesterFlow is narrower, which means the skills are more relevant but the loop improvements arrive on this project's schedule. The README does not describe a plugin API beyond custom plugins and MCP, so extending the skill set is the documented path for adding coverage.
Licence, maintenance and what a version bump costs you
The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. It also requires that you keep the licence and notice files and state significant changes if you redistribute a modified version. That last point is the one teams forget: if you fork the skills or patch the agent and ship it internally as a product, the notice obligations travel with it. This is a description of the licence text, not legal advice; get counsel to review your distribution model.
The release cadence visible in the material is fast. v0.1.18, v0.1.19 and v0.1.20 landed within roughly three days in June 2026, and the repository shows a push in late August 2026. Pre-1.0 version numbers plus that cadence means the CLI flags, config keys and session file format have not stabilised. The README documents --backend, --model, --base-url, --api-key and --resume, and the PENTESTERFLOW_VERSION and PENTESTERFLOW_INSTALL_DIR environment variables. Expect those to be the stable surface and treat session files, findings layout and skill Markdown as the parts most likely to shift.
Upgrade cost is mostly re-verification. Because the agent writes findings and logs you may be archiving per engagement, a format change mid-engagement is the real risk. Pin PENTESTERFLOW_VERSION per engagement rather than tracking latest, and keep the binary you validated for the duration of a client project.
Editorial conclusion
Adopt PentesterFlow if you already run an authorized engagement and want reproducible curl-level evidence written to ./findings/<slug>.md rather than a chat transcript. Skip it if you need a multi-tenant platform with central audit storage, or if nobody on the team will review permission prompts. Before trusting it, run one scoped target with the default ask tier, open a findings file, and confirm the command in it reproduces the same response.
Community notes