PentesterFlow
A human-controlled terminal agent for authorized penetration testing and evidence-backed vulnerability reporting.
The README clearly enumerates external effects from shell, HTTP, file mutation, Burp/MCP, logging, and persistent storage, and says sensitive actions require allow-once or session approval by default. It also gives unusually clear data paths, remote-provider flows, hidden memory injection, and debug-log sensitivity. Deductions apply because the tool surface remains broad and YOLO mode bypasses some approvals; secret redaction and sensitive-path protection are asserted without implementation evidence; dependencies use broad ranges and workflow actions are pinned only to major versions; and offensive actions have no general undo or recovery mechanism. Repository, package, and license metadata provide attribution, but the publisher is unknown and no definite copyright owner is stated. Nothing supplied demonstrates malware, credential theft, covert exfiltration, or destructive defaults without consent.
The README, package metadata, and CI/release workflows are broadly consistent about Node 20+, build commands, platform artifacts, and quality gates. CI covers Node 20/22 on Linux and macOS. Deductions reflect the 0.1.0-dev package version versus a v0.1.6 installation example, the absence of ordinary Windows CI beyond cross-compilation, and no fallback matrix for unavailable model providers, Burp, or MCP. Failure handling is documented only in fragments—learning failures are logged, debug logs are available, and release checks emit errors—without a systematic catalog of user-facing errors and recovery actions.
The intended audience, authorized-testing scenarios, engagement lifecycle, model backends, operating systems, architectures, skill coverage, and extension directories are described thoroughly, supporting full environment-fit and audience scores. Deductions apply because capability boundaries are mainly documentary, while natural-language routing, broad skills, and silent memory retrieval can make triggering ambiguous. Beyond /target, plan-only mode, approvals, and step limits, the evidence does not show strict target allowlists, network boundaries, or detailed trigger-resolution rules.
The README has strong information architecture and makes installation, quickstart, commands, tools, data locations, development, and contribution guidance easy to find. Installer, checksum, direct-download, and cross-platform notes are substantial. Apache-2.0 metadata matches a complete LICENSE, justifying full license credit. Deductions apply because there is no dedicated FAQ or comprehensive troubleshooting section, limitations are scattered across warnings and provider notes, browser-ingest is deprecated, and version examples conflict with package metadata. Releases generate numbered versions and notes, but no repository changelog is supplied. Maintenance is represented only by generic issue/PR links and automation, with no named maintainer, security-reporting route, or explicit support responsibility.
The proposed outputs—copyable curl commands, Markdown findings, raw request evidence, coverage state, logs, and resumable sessions—are directly usable in penetration-testing work, justifying full output-usability credit. Combining planning, tools, evidence, reporting, Burp, and learning plausibly adds value over a generic terminal assistant, but the core effectiveness claims are supported mostly by README assertions rather than supplied code or tests. Local-model support and cheap-model hints may reduce cost, yet no latency, resource, token-cost, error-cost, or benefit benchmarks are given, so cost-benefit is not fully established.
Installation, licensing, build, CI, release artifacts, and checksum claims are traceable across package metadata and workflows; the README also provides concrete commands, paths, and output formats. Deductions apply because key behavioral claims—approval enforcement, redaction, catastrophic-command blocking, finding confirmation, and memory retrieval—lack accompanying implementation or test files, so cross-source corroboration mainly covers engineering and release mechanics. The documentation sometimes distinguishes normative intent with “should” and explicitly flags debug-log risk, but most capabilities are presented as established behavior without consistently separating verified behavior, design intent, and effectiveness claims.
- The agent can execute shell commands, send network requests, modify files, and process authenticated traffic. Use it only against explicitly authorized, tightly scoped targets, and keep YOLO mode disabled.
- Remote model providers may receive prompts, target details, and tool context. Review each provider's data policy and use isolated test credentials before sending sensitive engagement data.
- Sessions, personal memory, Burp captures, findings, and full debug logs may contain sensitive target material. Restrict access, inspect stored content, and define retention and deletion procedures despite the stated redaction.
- The curl and PowerShell installation forms execute remote scripts. Pin a version, inspect the installer first, and independently verify release checksums.
- This was a static review limited to the supplied README, license, package metadata, and workflows. The program was not run, and approval, redaction, command blocking, and finding-confirmation behavior were not independently verified.
What does this agent do, and when should you use it?
PentesterFlow is an open-source terminal assistant for authorized penetration tests and bug-bounty investigations, spanning reconnaissance, enumeration, validation, evidence collection, and reporting. Its agent loop plans against a scoped target and invokes shell, HTTP, file, search, browser-capture, and Burp-related tools, with approval gates for sensitive actions. It can use Ollama, LM Studio, Kimi, Groq, Gemini, OpenRouter, DeepSeek, or OpenAI-compatible endpoints, allowing either local or hosted models. Confirmed issues are written as Markdown under ./findings/<slug>.md, while coverage records, sessions, context snapshots, and JSON Lines logs support longer engagements. The operational boundary is the user's terminal and local workspace: once approved, it can execute commands, reach targets over the network, edit files, and process captured traffic, so it is appropriate only for systems covered by explicit authorization.
The analyst sets an authorized target with /target and describes an objective such as mapping an API or testing access control. The agent can load Markdown playbooks including recon, webvuln, ssrf, ssti, jwt, graphql, race, takeover, supabase, and deserialize, then invoke shell/BashTool, http, GlobTool, GrepTool, web_fetch, web_search, browser_capture_*, and file tools. The coverage tool records tested endpoint, parameter, and vulnerability-class combinations, while /next proposes work for remaining gaps. A candidate issue is expected to be reproduced with request-and-response evidence before confirm_finding writes its severity, impact, remediation, evidence, and copyable curl command to ./findings/<slug>.md. Sessions persist under ~/.pentesterflow/sessions/*.json, and /compact, /memory, /snapshot, plus background continuous learning preserve context across extended assessments. With --burp enabled, a local listener accepts Burp or browser capture data; the separate pentesterflow-browser-mcp binary exposes the same captured information to compatible MCP clients.
- A penetration tester conducting an authorized web or API engagement who wants one terminal workflow from reconnaissance through evidence-backed reporting, without giving up approval over sensitive commands.
- A bug-bounty researcher validating IDOR, JWT, SSRF, SSTI, GraphQL, or race-condition candidates and needing reproducible requests and responses for a submission.
- A security team running a multi-session assessment that needs saved sessions, compacted memory, context snapshots, and coverage tracking to resume without rebuilding context.
- A Burp Suite user who wants to send selected requests to a terminal agent for analysis and import confirmed findings back as Burp issues.
- A team with tighter data-boundary requirements that wants to run Ollama or LM Studio locally while retaining the option to switch to hosted or OpenAI-compatible model endpoints.
What are this agent's strengths and limitations?
- The workflow is security-specific, with built-in playbooks ranging from reconnaissance to deserialization testing and coverage-driven suggestions through /next.
- Human approval is the default, supplemented by allow-once and allow-session decisions, sensitive-path protection, and blocking of catastrophic shell-command patterns.
- Its evidence model favors auditability: visible tool calls, reproducible commands, deterministic output paths, and findings containing proof, impact, remediation, and curl reproduction steps.
- Support for several local and hosted backends plus OpenAI-compatible APIs reduces dependence on a single model provider.
- Burp integration, browser capture, MCP access, persisted sessions, snapshots, and local memory make it suitable for longer investigations built around existing traffic.
- After approval, the agent can run shell commands, make network requests, and edit files; incorrect scoping or approval decisions can affect both the workstation and the target.
- Hosted backends require provider credentials and network access and may incur usage charges; no pricing or spending controls are documented in the supplied material.
- Continuous learning, sessions, findings, and logs persist target context locally. Full debug logs may contain command output and copied request material and therefore require careful handling.
- Provider behavior is not entirely uniform: Groq uses a compact prompt and lower compaction threshold, LM Studio needs stop-token and template-marker protections, and --no-stream exists for SSE or tool-call issues.
- The Burp workflow depends on the companion PentesterFlow Burp Integration, while MCP-based browser access requires the separate pentesterflow-browser-mcp binary.
How do you install or deploy this agent?
On macOS or Linux:
curl -fsSL https://raw.githubusercontent.com/PentesterFlow/agent/main/install.sh | shOn Windows PowerShell:
irm https://raw.githubusercontent.com/PentesterFlow/agent/main/install.ps1 | iexThe installers download the matching standalone binary and verify its published SHA-256 checksum when available. GitHub Releases also provides macOS arm64/x64, Linux arm64/x64, and Windows x64 binaries. Development from source requires Node.js 20+:
npm install
npm run dev -- --version
npm run typecheck
npm run lint
npm run test
npm run buildA supported model backend is also required for first use. The documented local Ollama path is:
ollama pull qwen2.5-coder:32bpentesterflow
How do you use this agent?
Start pentesterflow, then use /provider to select a backend, API key, and model. Local Ollama or LM Studio setups do not inherently require a hosted-provider key; the documented Kimi, Groq, OpenRouter, DeepSeek, and Gemini examples use MOONSHOT_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, DEEPSEEK_API_KEY, and GEMINI_API_KEY respectively. A minimal interactive workflow is:
/provider
/target https://app.example.com
map the authenticated API surface and test for IDORA backend can also be selected at launch:
pentesterflow --backend ollama --model qwen2.5-coder:32bFor an OpenAI-compatible service:
pentesterflow --backend openai-compat --base-url https://api.example.com/v1 --api-key sk-...
Resume with pentesterflow --resume <session-id>. Start the Burp bridge with pentesterflow --burp or pentesterflow --burp 9999; its default listener is http://127.0.0.1:9999. Operate only against explicitly authorized targets, and avoid --yolo outside labs because it automatically approves non-sensitive tool calls.