PentesterFlow: AI Pentesting Agent That Waits for Your Approval

Here's what happens when I try to use general-purpose AI coding assistants for security testing: I ask Claude or ChatGPT to help find vulnerabilities in an API, and it immediately starts hallucinating issues. "This endpoint is vulnerable to SQL injection" — but when I test the payload, it's not. "This looks like an IDOR" — but the access control actually works correctly. I spend more time validating false positives than I save from automation. The AI doesn't understand the difference between "this pattern often indicates a vulnerability" and "this specific instance is exploitable with evidence."

PentesterFlow is a terminal-based AI agent built specifically for authorized penetration testing and bug hunting, with one critical difference: it requires human approval before sensitive actions and validates findings with real evidence before reporting them. It walks through reconnaissance, enumeration, validation, and reporting while keeping the analyst in control. Instead of "this looks vulnerable," it says "I reproduced this IDOR with request A and response B — here's the curl command to verify it yourself." It integrates with real pentest tools (Burp Suite, shell commands, HTTP requests), saves confirmed findings with proof-of-concept, and learns from each engagement to improve future sessions.

I haven't installed it yet, but the problem it solves is too familiar: AI agents that rush to conclusions in security work are worse than useless — they create false confidence and waste time. If PentesterFlow enforces the discipline I should be applying manually (validate before claiming, evidence before reporting, human approval before destructive actions), it's worth testing on authorized targets.

What PentesterFlow Actually Is

PentesterFlow is a command-line AI agent (Node.js/TypeScript) designed specifically for offensive security work. It provides:

• Structured pentest workflow: Scope → Recon → Enumeration → Validation → Coverage → Reporting → Learning, with each phase building on the previous.
• Security-specific skills: Pre-built playbooks for IDOR, SSRF, SSTI, JWT abuse, GraphQL vulnerabilities, race conditions, subdomain takeovers, Supabase security, and deserialization flaws.
• Human-in-the-loop controls: Permission prompts for shell commands, HTTP requests, file operations, and destructive actions. Allow once, allow for this session, or deny.
• Evidence-based reporting: The confirm_finding tool only saves vulnerabilities with request/response proof, impact analysis, and reproduction steps.
• Real tool integration: Shell/Bash execution, HTTP client, Burp Suite bridge for captured traffic, browser capture, file operations, and MCP (Model Context Protocol) support.
• Continuous learning: Automatically saves successful workflows, mistakes, coverage gaps, and useful patterns to local intelligence files that improve future engagements.
• Session management: Resume previous assessments with full context, memory compaction for long engagements, and automatic snapshots every 5 minutes.

It works with local models (Ollama, LM Studio) or hosted APIs (OpenAI, Gemini, Kimi, Groq, DeepSeek, OpenRouter) — your choice based on privacy needs and model performance.

The Core Workflow: Why Structure Matters for Security Testing

General AI agents approach tasks linearly: you give a prompt, they try to solve it immediately. For security work, that's dangerous. You need:

1. Scope definition first: What's the target? What's authorized? What credentials do I have? What's off-limits?
2. Reconnaissance before testing: Map the attack surface — hosts, endpoints, technologies, APIs, parameters — before throwing payloads.
3. Enumeration before exploitation: Understand authentication states, roles, input validation, and normal behavior before looking for bypasses.
4. Validation before reporting: Reproduce the issue deterministically with evidence. A 200 OK response isn't a vulnerability; a 200 OK that returns another user's data is.
5. Coverage tracking: Did I test endpoint X with vulnerability class Y? What's untested? What should I try next?
6. Evidence-backed findings: Save confirmed issues with PoC, impact, remediation, and copy-pasteable reproduction commands.
7. Learning for next time: What worked? What didn't? What should I remember for similar targets?

PentesterFlow enforces this structure. You can't skip to "find SQL injection" without setting scope. The agent won't report an IDOR without request/response evidence. The /next command asks "what should I test next based on coverage gaps?" instead of repeating tests or missing entire attack surfaces.

The Skills System: Security-Specific Playbooks

PentesterFlow includes pre-built "skills" — Markdown playbooks that package methodology, payloads, tool constraints, and verification steps for specific vulnerability classes. Built-in skills include:

• recon: Subdomain enumeration, technology fingerprinting, content discovery, attack surface mapping.
• webvuln: IDOR, broken access control, injection, authentication bypass, session logic flaws.
• ssrf: Filter bypasses, metadata service access (AWS, GCP, Azure), internal network reachability, blind SSRF.
• ssti: Template engine fingerprinting (Jinja2, Twig, ERB, etc.), escalation paths, sandbox escapes.
• jwt: Algorithm confusion (none, HS256→RS256), kid parameter abuse, weak secrets, signature validation bypasses.
• graphql: Introspection, authorization gaps, batching attacks, depth/cost abuse.
• race: Time-of-check-time-of-use (TOCTOU) issues, limit bypass, concurrent request races.
• takeover: Dangling DNS records, unclaimed cloud resources (S3, Azure Blob, etc.).
• supabase: Row-Level Security (RLS) bypass, anonymous access mistakes, policy gaps.
• deserialize: Unsafe deserialization sinks (Python pickle, Java, .NET), gadget chain testing.

Each skill is a structured prompt that tells the agent:

• What methodology to follow (e.g., for SSRF: enumerate endpoints → test localhost → test metadata services → test internal IPs → validate blind SSRF)
• What payloads to try (known bypass patterns, encoding tricks, protocol handlers)
• What tools are allowed (HTTP requests yes, shell commands only with approval)
• What evidence is required before confirming a finding (response showing internal data, not just a timeout)

You load a skill with /webvuln or /ssrf, and the agent follows that playbook instead of guessing. This is the difference between "try random SSRF payloads" and "systematically test localhost, then 169.254.169.254, then internal RFC1918 ranges, documenting each response."

Human-in-the-Loop: The Permission System

PentesterFlow gates sensitive actions behind approval prompts:

• Shell commands: Every shell or BashTool call shows the exact command and waits for approval. You can allow once, allow for this session, or deny. Dangerous patterns (recursive deletes, system modifications, network scans without context) are blocked or flagged.
• HTTP requests: Every http call shows method, URL, headers, and body before execution. For in-scope requests, you can auto-approve. For out-of-scope or unusual requests, you review manually.
• File operations: file_write, file_edit, and sensitive path access require approval. High-risk local paths (system directories, credentials) are protected.
• Evidence collection: Browser/Burp traffic ingestion and finding confirmation are logged and auditable.

There's a --yolo flag for lab environments (CTFs, intentionally vulnerable apps) where you trust the agent fully and don't want interruptions. For production penetration tests or bug bounties, you keep permissions on.

This is the critical safety layer that general AI agents lack. Without it, an agent could run curl -X DELETE https://api.target.com/admin/users/all because it misunderstood the task. With human-in-the-loop, you see the command, recognize the mistake, and deny it before it executes.

Burp Suite Integration: Real-World Tool Workflow

One of the more practical features: PentesterFlow integrates with Burp Suite, the standard web security testing proxy. The workflow:

1. You browse the target app manually or run an automated crawler in Burp.
2. Burp captures all HTTP traffic (requests, responses, cookies, headers).
3. You select interesting requests in Burp and send them to PentesterFlow.
4. PentesterFlow ingests the traffic and makes it queryable via browser_capture_* tools.
5. The agent can ask "show me all POST requests to /api/" or "find requests with JWT tokens" and get real captured data, not hypothetical endpoints.
6. When the agent confirms a finding, it can export it back to Burp as an issue with full request/response evidence.

This bridges the gap between manual testing (you control the proxy, see everything) and AI assistance (the agent analyzes patterns, suggests tests, validates findings). You're not blindly trusting the AI to discover endpoints — you're feeding it real traffic you've already captured and asking it to find issues in that specific dataset.

The Burp bridge runs locally (pentesterflow --burp) and listens on http://127.0.0.1:9999 by default. The companion Burp extension sends requests to this listener. All communication is local; no external services involved.

Continuous Learning: Improving Across Engagements

PentesterFlow includes a local learning system that saves useful knowledge without manual memory management:

What It Learns

• User preferences and working style (how you like findings formatted, which tools you prefer).
• Successful workflows (the sequence of steps that found a specific vulnerability class).
• Mistakes and failed assumptions ("tried X for SSRF, didn't work, Y worked instead").
• Coverage gaps ("tested all GET endpoints but missed POST endpoints").
• Tool/config patterns that worked well (specific curl flags, header combinations).
• Finding patterns and evidence requirements ("for IDOR, always test cross-account access with two different user tokens").

Where It Stores Knowledge

• Project intelligence: ./.pentesterflow/intelligence/scenarios.jsonl — lessons specific to this engagement/workspace.
• Personal intelligence: ~/.pentesterflow/intelligence/scenarios.jsonl — reusable lessons across all future projects.

How It Works

• Learning runs in the background after completed turns and memory compactions.
• Retrieval is silent — relevant memories are injected as hidden context when applicable.
• Duplicates are deduplicated before reaching the model.
• Secrets are redacted before storage (API keys, tokens, passwords).
• Learning failures are logged but not shown as user errors.

This means the second time you test a Supabase app, the agent already knows "check anonymous access to tables" and "test RLS policies with different roles" without you re-explaining. The third time you find a JWT algorithm confusion bug, the agent remembers the verification steps and evidence requirements. Knowledge accumulates silently, making future engagements faster.

Session Memory and Resume

Long penetration tests can take days or weeks. PentesterFlow supports:

• Session persistence: Every session is saved to ~/.pentesterflow/sessions/*.json with full conversation history, compacted memory, target state, and coverage tracking.
• Resume with recap: pentesterflow --resume <session-id> loads the session and shows a recap of what was tested, what was found, and what's next.
• Memory compaction: /compact summarizes the session into persistent facts, reducing context size while preserving key information.
• Context snapshots: Every 5 minutes during active sessions, PentesterFlow writes a redacted context snapshot (no secrets) for recovery if the session crashes.
• Saved facts: Type #<text> to save a durable fact that survives compaction and persists across sessions. Example: #the /api/orders endpoint is vulnerable to IDOR on the id parameter.

This is critical for real-world engagements where you can't finish in one sitting. You test for 3 hours, save the session, resume the next day, and the agent remembers what it tested, what it found, and what's left to cover.

Evidence-Based Findings: No Hallucinations Allowed

The confirm_finding tool is PentesterFlow's core validation mechanism. It only saves a finding if:

• The vulnerability was reproduced with a deterministic request.
• The response proves the issue (e.g., returns another user's data for IDOR, executes template code for SSTI, reaches internal metadata for SSRF).
• A curl command or equivalent is provided for manual reproduction.
• Impact and remediation are documented.

Findings are saved to ./findings/<slug>.md with:

• Title and severity (critical, high, medium, low, info).
• Affected URL, method, parameter, and payload.
• Response excerpt proving the issue.
• Impact analysis (what can an attacker do with this?).
• Remediation recommendations.
• Copy-pasteable curl reproduction command.
• Raw request material for Burp issue import.

This is the anti-hallucination defense. The agent can't report "suspected SQL injection" without running a payload and seeing database errors or data exfiltration. It can't claim "possible SSRF" without getting a 200 OK from localhost or a metadata endpoint. Every finding requires evidence, and that evidence is saved alongside the report for manual verification.

Potential Rough Edges (From the Docs)

I haven't tested this yet, but based on the README and my experience with security tools, here are the likely friction points:

• Authorized use only: This tool can run destructive commands, make HTTP requests, and modify files. Using it on systems you don't have written authorization to test is illegal and unethical. The tool doesn't enforce authorization — you do. If you misuse it, that's on you, not the tool.
• False negatives: The human-in-the-loop model and evidence requirements reduce false positives, but they might increase false negatives. If the agent doesn't think to test a specific payload or endpoint, it won't find the vulnerability. Coverage tracking helps, but it's not exhaustive.
• Model quality variance: The agent's effectiveness depends heavily on the underlying LLM. A weak model (small local model, outdated API model) will miss patterns, make poor decisions, or require excessive hand-holding. A strong model (GPT-4, Claude Opus, Qwen 2.5 Coder 32B) will be much more effective.
• Learning curve: Understanding skills, session management, memory compaction, coverage tracking, and the permission system requires upfront investment. This isn't "install and go" — it's a power tool that requires learning.
• Cost for API models: Running long engagements with GPT-4 or Claude Opus burns API credits. A week-long pentest could cost $50-$200 in API calls depending on usage. Local models (Ollama) avoid this but require capable hardware (16GB+ RAM, ideally GPU).
• Burp integration setup: The Burp bridge requires installing a companion Burp extension and configuring the local listener. That's extra setup compared to standalone CLI tools.

Use Cases Where PentesterFlow Makes Sense

Based on the feature set, here are scenarios where PentesterFlow's structured approach is worth the complexity:

Bug Bounty Hunting

You're testing a web app for a bug bounty program. You need to:

• Map the entire API surface (hundreds of endpoints).
• Test each endpoint for multiple vulnerability classes (IDOR, injection, SSRF, etc.).
• Track what you've tested to avoid redundant work.
• Validate findings with proof before submitting to the program.
• Save evidence and reproduction steps for the report.

PentesterFlow automates the mechanical parts (enumeration, payload testing, coverage tracking) while keeping you in control of validation and reporting. The learning system improves over multiple programs — it remembers which payloads work for which vulnerability classes and which endpoints tend to be vulnerable.

Penetration Testing Engagements

You're hired to test a client's application over 2 weeks. You need to:

• Follow a structured methodology (OWASP, PTES, etc.).
• Document every test (what you tested, when, what the result was).
• Provide evidence-backed findings with PoC and remediation.
• Resume testing across multiple sessions (you can't finish in one day).
• Deliver a professional report at the end.

PentesterFlow's skills align with standard methodologies. Session management and memory compaction handle multi-day engagements. The confirm_finding tool generates report-ready markdown with evidence. Coverage tracking ensures you didn't miss critical areas. The audit trail (session logs, finding reports, context snapshots) supports professional deliverables.

Security Research and Learning

You're learning offensive security and want to practice on intentionally vulnerable apps (DVWA, bWAPP, HackTheBox, TryHackMe). You want:

• Guided methodology (what to test, in what order).
• Feedback on whether you found the vulnerability correctly (evidence required).
• Reusable knowledge for future challenges.
• Understanding of security tool workflows (Burp, curl, shell commands).

PentesterFlow's skills teach methodology by example. The evidence requirements teach you to validate findings properly. The learning system captures patterns you discover. The --yolo flag skips permission prompts in lab environments where safety isn't a concern. It's a learning aid that enforces good habits.

Red Team Operations

You're on a red team testing internal applications with authorization. You need:

• Stealth and control (no accidental DoS, no alerting blue team unnecessarily).
• Evidence for debrief (what you accessed, how, when).
• Methodology adherence (client wants to see you followed a framework).
• Integration with existing tools (Burp, custom scripts, shell access).

PentesterFlow's human-in-the-loop model prevents accidental destructive actions. The audit trail provides evidence for debrief. Skills document methodology. Tool integration (shell, HTTP, Burp, MCP) works with existing workflows. The learning system captures TTPs (tactics, techniques, procedures) for future operations.

How It Compares to General AI Coding Assistants for Security

Using ChatGPT or Claude for security testing:

• No structured methodology — you guide every step manually.
• Hallucinated findings — "this looks vulnerable" without evidence.
• No tool integration — you copy-paste curl commands, run them yourself, paste results back.
• No session persistence — every conversation starts fresh.
• No evidence collection — findings are just text, no proof.
• No safety controls — if you ask it to run a destructive command, it gives you the command without warning.

Using PentesterFlow:

• Structured workflow enforced — scope, recon, enumeration, validation, coverage, reporting, learning.
• Evidence-required findings — can't report without request/response proof.
• Native tool integration — shell, HTTP, Burp, browser capture, file ops, all built-in.
• Session persistence and resume — multi-day engagements supported.
• Markdown findings with PoC — report-ready output.
• Human-in-the-loop safety — approval required for sensitive actions.

The tradeoff: PentesterFlow is more complex to set up and learn, but it's purpose-built for security work. General AI is simpler but not safe or effective for penetration testing without heavy manual oversight.

Ethical and Legal Warnings

The README is explicit about this, and I need to reinforce it: use PentesterFlow only on systems where you have explicit written authorization to perform security testing. The tool can:

• Run shell commands that could damage systems.
• Make HTTP requests that could trigger rate limits, account lockouts, or legal alerts.
• Modify files on your local system.
• Ingest and process captured traffic (potential PII, credentials, sensitive data).

Unauthorized security testing is illegal in most jurisdictions (Computer Fraud and Abuse Act in the US, Computer Misuse Act in the UK, similar laws worldwide). It doesn't matter if you "didn't mean harm" or "were just learning" — accessing systems without authorization is a crime.

PentesterFlow is a tool for:

• Authorized penetration testing engagements (you have a signed contract).
• Bug bounty programs (you're within scope per the program's rules).
• Your own systems (you own them or have explicit permission from the owner).
• Intentionally vulnerable training labs (DVWA, HackTheBox, etc. designed for testing).

It is not for:

• Testing production systems you don't have authorization for.
• "Responsible disclosure" without prior authorization (contact the vendor first, get permission).
• Testing competitors' systems to find weaknesses.
• Any activity where you're not 100% certain you have legal authority.

The human-in-the-loop permission system is a safety mechanism, not a legal defense. If you approve a destructive action on an unauthorized system, you're liable, not the tool.

Why This Bookmark Is High-Priority

Last month I was testing a web app for a bug bounty and found what looked like an IDOR: I could access /api/orders/1234 with my auth token and get order details. I changed the ID to 1235 and got a different order. I spent 30 minutes writing up the finding, including screenshots and curl commands. Then, during final validation, I realized both orders belonged to my account — the app let one user have multiple orders, and I was just viewing my own data. Not an IDOR, just normal functionality. I wasted 30 minutes on a false positive because I didn't validate properly.

If I'd been using PentesterFlow, the confirm_finding tool would have required me to prove the issue with evidence: "show me the request that returns another user's order, not just a different order ID." I would have caught the mistake before writing the report. That's the value: enforcement of validation discipline I know I should follow but sometimes skip when I'm moving fast.

I'm bookmarking PentesterFlow at the top of my "test on next authorized engagement" list. If the skills system, human-in-the-loop controls, and evidence-based findings deliver on the promise — fewer false positives, better coverage, reusable knowledge — it becomes a standard tool for any pentest or bug bounty work. If the overhead (setup, learning, permission prompts) outweighs the quality improvement, I'll use it selectively for complex targets and stick with manual testing for simple ones.

The Test Plan

Here's how I'll validate PentesterFlow:

1. Install and setup: Download the binary, configure a local model (Ollama with Qwen 2.5 Coder 32B), verify tools are registered.
2. Test on a lab app: Use DVWA or a HackTheBox machine with --yolo mode. Follow the /webvuln skill, verify it finds known issues, check if findings have proper evidence.
3. Test human-in-the-loop: Disable YOLO mode, give it a task that requires shell commands or HTTP requests, verify permission prompts appear and are clear about what's being executed.
4. Test Burp integration: Capture traffic from a test app in Burp, send requests to PentesterFlow, verify the agent can query and analyze captured traffic.
5. Test session resume: Start a test, save the session, resume the next day, verify context is preserved and recap is useful.
6. Test learning system: Run multiple tests, check ./.pentesterflow/intelligence/scenarios.jsonl and ~/.pentesterflow/intelligence/scenarios.jsonl, verify useful patterns are saved.
7. Test on a bug bounty program: Use it on an authorized in-scope target (small program, limited scope), measure whether it finds real issues, whether findings have proper evidence, and whether false positives are reduced vs. manual testing.
8. Evaluate cost: Track API usage (if using hosted models) or resource usage (if using local models) to determine cost per engagement.

If tests 1-6 work smoothly and test 7 shows improved efficiency or quality vs. manual testing, PentesterFlow moves from "Bookmarked" to "Using" and becomes part of my standard workflow for authorized security testing. If the learning curve is too steep or the overhead doesn't pay off in reduced false positives and better coverage, I'll use it selectively for complex multi-day engagements but not for quick bug bounty checks.