Skip to content
Back to search

autopentest-ai

Agentic Pentesting MCP server that discovers, exploits, and reports web application vulnerabilities.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bhavsec--autopentest-ai/badge.svg)](/listings/bhavsec--autopentest-ai)

HTML

<a href="/listings/bhavsec--autopentest-ai"><img src="/api/listings/bhavsec--autopentest-ai/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- [Docker](https://docs.docker.com/get-docker/) (Docker Desktop on macOS/Windows, Docker Engine on Linux) - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) with an active Anthropic API key - [uv](https://docs.astral.sh/uv/) (Python package manager for the MCP server) - [Node.js](https://nodejs.org/) (for Playwright MCP server) - **Optional:** [Burp Suite Professional](https://portswigger.net/burp/pro) for passive traffic monitoring

Installation

# 1. Clone the repository
git clone https://github.com/bhavsec/autopentest-ai.git
cd autopentest-ai

# 2. Install Python dependencies for the MCP server
cd server && uv sync && cd ..

# 3. Build Docker image and start the tools container
make setup

That's it. All 27 security tools are now installed and ready inside the Docker container.

Verify Installation

# Check all tools are installed
make verify-tools

# Expected output:
# [+] nuclei: installed
# [+] httpx: installed
# [+] katana: installed
# ... (27 tools total)

Start Testing

# Launch Claude Code in the project directory
claude

Then tell Claude what to test:

Run a full WSTG assessment against https://target.example.com

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,157 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="https://img.shields.io/badge/OWASP_WSTG-109_Tests-blue?style=for-the-badge" alt="WSTG Tests">
  3. <img src="https://img.shields.io/badge/PortSwigger-31_Technique_Guides-FF6633?style=for-the-badge" alt="PortSwigger Guides">
  4. <img src="https://img.shields.io/badge/MCP_Tools-68+-00B4D8?style=for-the-badge" alt="MCP Tools">
  5. <img src="https://img.shields.io/badge/Security_Tools-27-orange?style=for-the-badge" alt="Security Tools">
  6. <img src="https://img.shields.io/badge/WAF_Bypass-12_Vendors-red?style=for-the-badge" alt="WAF Bypass">
  7. <img src="https://img.shields.io/badge/Zero_False_Positives-Evidence_Based-brightgreen?style=for-the-badge" alt="Evidence Based">
  8. <img src="https://img.shields.io/badge/License-Apache_2.0-green?style=for-the-badge" alt="License">
  9. </p>
  10. # AutoPentest
  11. **An agentic pentesting MCP server that automates web application penetration testing using the full OWASP Web Security Testing Guide and PortSwigger Web Security Academy technique references.**
  12. Point it at a target — it crawls your app, maps every endpoint, then spawns role-specialized agents (Scout, Analyzer, Exploiter, Reporter) to test for XSS, SQLi, SSRF, SSTI, IDOR and more. No false positives — every finding is backed by real, reproducible evidence with quality gates enforcing proof at every phase. Includes 31 PortSwigger technique guides, adaptive WAF evasion for 12 vendors, cross-phase vulnerability chaining, and risk-weighted endpoint prioritization. Run it with Claude Code, the API, or go fully offline using Ollama models.
  13. > **Think of it as:** A senior pentester's methodology encoded into an MCP server — 109 OWASP tests, 31 PortSwigger attack technique guides, 68+ MCP tools, 27 security tools, 4 specialized agent roles, 7 structured phases, automated quality assurance, and a zero-context final review.
  14. ---
  15. <p align="center">
  16. <img src="cli-output.gif" alt="AutoPentest CLI Output" width="800">
  17. </p>
  18. ## Table of Contents
  19. - [Why AutoPentest?](#why-autopentest)
  20. - [Architecture](#architecture)
  21. - [Features](#features)
  22. - [Agent Role System](#agent-role-system)
  23. - [Quick Start](#quick-start)
  24. - [Usage](#usage)
  25. - [Testing Phases](#testing-phases)
  26. - [Security Tools](#security-tools)
  27. - [WSTG Knowledge Base](#wstg-knowledge-base)
  28. - [PortSwigger Technique Guides](#portswigger-technique-guides)
  29. - [Quality Assurance System](#quality-assurance-system)
  30. - [Benchmarking](#benchmarking)
  31. - [Example Report](#example-report)
  32. - [Configuration](#configuration)
  33. - [Multi-Domain Testing](#multi-domain-testing)
  34. - [Crash Recovery](#crash-recovery)
  35. - [Project Structure](#project-structure)
  36. - [Requirements](#requirements)
  37. - [FAQ](#faq)
  38. - [Disclaimer](#disclaimer)
  39. ---
  40. ## Why AutoPentest?
  41. Manual penetration testing is thorough but slow. Automated scanners are fast but shallow. AutoPentest bridges the gap:
  42. | Capability | Manual Pentest | Automated Scanner | AutoPentest |
  43. |------------|:-:|:-:|:-:|
  44. | Full OWASP WSTG coverage | Depends on tester | Partial | **109 tests** |
  45. | Business logic testing | Yes | No | **Yes** |
  46. | Multi-step exploitation | Yes | Limited | **Yes** |
  47. | Vulnerability chaining | Yes | No | **Yes** |
  48. | Evidence-based findings | Yes | Template output | **Reproducible curl commands** |
  49. | Consistent quality | Varies | Yes | **Phase gates + Final Judge** |
  50. | Speed | Days | Minutes | **Hours** |
  51. | Cross-domain auth (SSO/OIDC) | Manual setup | Usually fails | **Automated handling** |
  52. ---
  53. ## Architecture
  54. ```
  55. ┌─────────────────────────────────────────────────────────────┐
  56. │ LLM Orchestrator (Claude) │
  57. │ │
  58. │ Reads CLAUDE.md workflow, manages phases, │
  59. │ spawns role-specialized subagents │
  60. └──────────┬──────────┬──────────┬──────────┬─────────────────┘
  61. │ │ │ │
  62. ┌─────▼────┐ ┌───▼─────┐ ┌──▼───────┐ ┌▼─────────┐
  63. │ Scout │ │Analyzer │ │Exploiter │ │ Reporter │
  64. │ (recon) │ │ (vuln │ │ (proof) │ │ (QA / │
  65. │ │ │ disc.) │ │ │ │ judge) │
  66. └──────────┘ └─────────┘ └──────────┘ └──────────┘
  67. │ │ │ │
  68. │ MCP │ │ MCP │
  69. ▼ ▼ ▼ ▼
  70. ┌──────────────────────────┐ ┌──────────────────────┐
  71. │ WSTG MCP Server │ │ Playwright MCP │
  72. │ (68+ tools) │ │ (Browser Testing) │
  73. │ │ │ │
  74. │ ◦ 109 WSTG tests │ │ ◦ DOM XSS proof │
  75. │ ◦ 31 technique guides │ │ ◦ Clickjacking │
  76. │ ◦ Task tree │ │ ◦ JS-rendered auth │
  77. │ ◦ Knowledge graph │ └──────────────────────┘
  78. │ ◦ WAF evasion │
  79. │ ◦ Tool output parser │
  80. │ ◦ Results verification │ docker exec
  81. │ ◦ Context compression │ │
  82. │ ◦ Endpoint priority │ ▼
  83. │ ◦ Quality gates │ ┌──────────────────────┐
  84. │ ◦ Report generation │ │ autopentest-tools │
  85. └──────────────────────────┘ │ (Docker Container) │
  86. │ │
  87. │ 27 security tools: │
  88. │ nuclei, sqlmap, │
  89. │ dalfox, katana, │
  90. │ ffuf, nmap ... │
  91. │ │
  92. │ Burp proxy │
  93. │ passthrough │
  94. └──────────────────────┘
  95. ```
  96. **How it works:**
  97. 1. **Claude Code** reads `CLAUDE.md` for the complete pentest methodology and orchestrates the 7-phase workflow
  98. 2. **Role-specialized subagents** (Scout, Analyzer, Exploiter, Reporter) execute focused tasks with dedicated prompt templates, tool guidance, and anti-patterns
  99. 3. **WSTG MCP Server** (68+ tools) provides OWASP test procedures, 31 PortSwigger technique guides, hierarchical task tree, knowledge graph, WAF evasion, endpoint prioritization, results verification, context compression, quality gates, and report generation
  100. 4. **Docker Container** runs all 27 security tools — traffic optionally routes through Burp Suite for passive monitoring
  101. 5. **Playwright MCP** handles browser-based testing (DOM XSS, clickjacking, JS-rendered login pages)
  102. ---
  103. ## Features
  104. ### Comprehensive OWASP Coverage
  105. - **109 WSTG test cases** across 12 categories — from information gathering to API testing
  106. - Each test includes step-by-step CLI procedures, context-specific payloads, detection criteria, and severity rubrics
  107. - Tests are prioritized (MUST/SHOULD) with conditional triggers so nothing relevant is skipped
  108. ### 31 PortSwigger Attack Technique Guides
  109. - Sourced from [PortSwigger Web Security Academy](https://portswigger.net/web-security) — detection methods, exploitation techniques, payloads, cheat sheets, and WAF bypass patterns
  110. - Organized by vulnerability class (SQLi, XSS, SSRF, JWT, OAuth, etc.) for direct use during testing
  111. - Integrated into every testing phase — agents automatically load the relevant technique guide before testing each vulnerability class
  112. - Database/platform-specific payload tables (Oracle vs MySQL vs PostgreSQL vs MSSQL for SQLi, Jinja2 vs Twig vs Freemarker for SSTI, etc.)
  113. - WAF bypass patterns organized by bypass level (basic → intermediate → advanced)
  114. ### 27 Pre-Configured Security Tools
  115. - All tools pre-installed in a single Docker image — `make setup` and you're ready
  116. - Tools organized by phase: discovery, injection testing, authentication, cryptography, API testing
  117. - Automatic Burp Suite proxy integration for passive traffic monitoring
  118. ### Structured 7-Phase Workflow
  119. - **Phase 0:** Application Discovery & Mapping
  120. - **Phase 1:** Information Gathering & Reconnaissance
  121. - **Phase 2:** Configuration & Deployment Testing
  122. - **Phase 3:** Identity, Authentication, Authorization & Session Management
  123. - **Phase 4:** Input Validation Testing (pipelined XSS/SQLi/SSRF pipelines)
  124. - **Phase 5:** Error Handling, Cryptography, Business Logic, Client-Side & API Testing
  125. - **Phase 6:** Coverage Verification & Reporting
  126. - **Phase 7:** Final Judge Review & Remediation
  127. ### Quality Assurance System
  128. - **Automated phase gates** — each phase must pass quality checks before proceeding
  129. - **Quality Reviewer** subagent at every phase transition identifies gaps and suggests improvements
  130. - **Final Judge** — a zero-context agent reviews the entire engagement cold, like an external QA reviewer
  131. - **Exhaustion gates** — "not vulnerable" requires proof of sufficient testing effort (minimum techniques and bypass attempts)
  132. ### Evidence-Based Findings
  133. - Every finding requires reproducible curl commands and full request/response evidence
  134. - **Three-tier classification:** EXPLOITED (proven impact), POTENTIAL (blocked by control), FALSE_POSITIVE (control holds)
  135. - **Anti-hallucination framework** — "no exploit = no finding" enforced at every level
  136. - Evidence checklists per vulnerability class verified before any finding is logged
  137. ### Role-Specialized Subagents
  138. - **4 dedicated roles** with focused prompt templates, tool guidance, and anti-patterns:
  139. - **Scout** — reconnaissance only, maps attack surface without sending payloads (Phase 0-1)
  140. - **Analyzer** — identifies potential sinks with canary/witness payloads, builds exploitation queues (Phase 2-5 analysis)
  141. - **Exploiter** — consumes Analyzer output, proves exploitation with evidence, logs confirmed findings (Phase 4 exploitation)
  142. - **Reporter** — quality review and Final Judge, reviews data without sending requests (QA + post-report)
  143. - Validation checkpoint between analysis and exploitation prevents wasted effort
  144. - Each role has explicit allowed/restricted tool lists and input/output contracts
  145. ### Pipelined Exploitation (Phase 4)
  146. - 3 independent **two-stage pipelines** run in parallel: XSS, Injection (SQLi/CMDi), SSRF/SSTI
  147. - Each pipeline: Analyzer (discover → analyze → queue) → validation checkpoint → Exploiter (exploit → log)
  148. - Each pipeline loads its PortSwigger technique guide for detection methods, cheat sheets, and WAF bypass patterns
  149. - WAF intelligence shared across all pipelines
  150. - Context-aware witness payloads for 13 sink types
  151. ### Adaptive WAF Evasion
  152. - **Automatic WAF fingerprinting** from response headers, body, and status codes — identifies 12 WAF vendors (Cloudflare, AWS WAF, Akamai, Imperva, ModSecurity, F5, FortiWeb, Sucuri, Barracuda, Wordfence, NAXSI, Citrix)
  153. - **Vendor-specific bypass payloads** organized by complexity level (basic → intermediate → advanced)
  154. - WAF intelligence shared across all agents via deliverable system
  155. - Agents automatically identify WAF on first block response and switch to tailored bypass payloads
  156. ### Cross-Phase Knowledge Graph
  157. - **Entity-relationship graph** tracks endpoints, parameters, technologies, findings, cookies, domains, and user roles
  158. - **Automated vulnerability chaining** via BFS path finding with 7 predefined chain patterns:
  159. - XSS + missing CSP, XSS + weak cookie (no HttpOnly), Open redirect + OAuth callback
  160. - IDOR + admin role, SSRF + cloud metadata, No lockout + no MFA, CORS + sensitive endpoint
  161. - Severity upgrades when chaining materially increases impact
  162. - Populated throughout testing, queried after Phase 4 for chain discovery
  163. ### Hierarchical Task Tree
  164. - Persistent tree structure (phases as branches, tests as leaves) prevents LLM depth-first bias and context loss
  165. - Main agent maintains strategic macro view; subagents update only their assigned leaf nodes
  166. - Auto-propagation: when all children complete, parent auto-completes
  167. - Phase-level completion percentages for informed decision-making
  168. ### Endpoint Risk Prioritization
  169. - Score and sort endpoints by risk for prioritized testing — highest risk tested first
  170. - Scoring factors: parameter count, technology risk indicators, taint chain confidence, tool convergence, auth requirements, injectable parameter names
  171. - Integrated into Phase 0 endpoint map generation
  172. ### Tool Output Parsing
  173. - **13 built-in parsers** for common CLI tools (nmap, nuclei, sqlmap, ffuf, httpx, whatweb, testssl, nikto, dalfox, katana, gau, wapiti, commix)
  174. - Condenses raw tool output 3-5x while preserving key findings, endpoints, and errors
  175. - Configurable verbosity: summary (~15 lines), detailed (~50 lines), full (complete parsed output)
  176. ### CLI Tool Results Verification
  177. - Automatic validation of CLI tool output quality — detects empty output, proxy errors, permission issues, and suspicious results
  178. - **10 per-tool validators** (nmap, nuclei, sqlmap, ffuf, feroxbuster, testssl, dalfox, wapiti, katana, httpx) with corrected command suggestions
  179. - When a tool produces empty or suspicious output, the validator suggests fixes (e.g., add `-Pn` for nmap, remove proxy env vars, try different flags)
  180. - Integrated into the tool execution workflow — agents call `verify_tool_result()` after every CLI tool run
  181. ### Progressive Context Compression
  182. - **Phase summaries** (~500-800 words) auto-generated when phase gates pass — capturing findings, coverage, tool results, and attack surface in compressed form
  183. - Prevents context degradation in long-running engagements by replacing raw historical data with structured summaries
  184. - `get_engagement_summary()` combines all phase summaries into a single overview for injecting into new subagent prompts
  185. - Summaries stored as deliverables — accessible by any downstream agent without requiring full engagement history
  186. ### Counterfactual Analysis (Second-Pass Discovery)
  187. - After an Analyzer completes with vulnerabilities found, a **second Analyzer** is spawned with instructions to "assume those vulns are patched"
  188. - The counterfactual Analyzer searches for **additional** vulnerabilities: different endpoints, different parameters, different injection contexts, logic flaws
  189. - Results are appended to the existing exploitation queue (automatic merge with deduplication by endpoint+parameter and auto-incrementing IDs)
  190. - Based on PenHeal ablation research showing +71% vulnerability coverage with counterfactual prompting
  191. ### Multi-Domain Support
  192. - Automatic SSO/OAuth/OIDC/SAML detection and handling
  193. - Per-domain scope registration, crawling, and testing
  194. - Cookie jar management for cross-domain session persistence
  195. - 6-level authentication failure escalation (alternative grants → PKCE → headless browser → token extraction → user provision → unauthenticated)
  196. ### Crash-Safe Engagement Management
  197. - Append-only `findings.md` and `progress.log` survive crashes
  198. - Git workspace checkpointing with rollback capability
  199. - **Auto-resume on interruption** — `resume-prompt.md` auto-generated at every checkpoint with full context (target, credentials, current phase, remaining tests, scope). Paste into a new session to continue exactly where you left off
  200. - Mid-phase checkpoint granularity — tracks which tests within a phase are completed, not just phase-level state
  201. - Full audit trail of every MCP tool call with timestamps
  202. ### Professional Reporting
  203. - Markdown reports with executive summary, findings by severity, test coverage matrix, and tool coverage
  204. - Per-category coverage percentages and gap analysis
  205. - Vulnerability chaining analysis documented
  206. - Final Judge observations and quality notes included
  207. ---
  208. ## Agent Role System
  209. AutoPentest uses 4 specialized agent roles instead of generic subagents. Each role has a dedicated prompt template with focused tool guidance, input/output contracts, and anti-patterns.
  210. | Role | Template | Purpose | Phases |
  211. |------|----------|---------|--------|
  212. | **Scout** | `templates/agent-roles/scout.md` | Reconnaissance and attack surface mapping | Phase 0-1, source code discovery |
  213. | **Analyzer** | `templates/agent-roles/analyzer.md` | Vulnerability discovery with canary/witness payloads | Phase 2-5 analysis |
  214. | **Exploiter** | `templates/agent-roles/exploiter.md` | Exploitation proof with evidence | Phase 4 exploitation |
  215. | **Reporter** | `templates/agent-roles/reporter.md` | Quality review and Final Judge | Phase transitions, post-report |
  216. ### How the Pipeline Works
  217. Phase 4 (highest-impact testing) uses a two-stage pipeline per vulnerability class:
  218. ```
  219. ┌──────────────────────────────────────────────────────────────┐
  220. │ Pipeline 1: XSS │
  221. │ │
  222. │ Analyzer (75 turns) Exploiter (75 turns) │
  223. │ ┌─────────────────────┐ ┌─────────────────────┐ │
  224. │ │ Discover endpoints │ │ Load Analyzer queue │ │
  225. │ │ Send canary payloads│─────▶│ Attempt exploitation│ │
  226. │ │ Build exploit queue │ gate │ Prove impact │ │
  227. │ │ Save deliverable │ │ Log findings │ │
  228. │ └─────────────────────┘ └─────────────────────┘ │
  229. │ ▲ │
  230. │ validate_exploitation_queue() │
  231. └──────────────────────────────────────────────────────────────┘
  232. ```
  233. Three pipelines (XSS, Injection, SSRF/SSTI) run in parallel. The validation checkpoint between Analyzer and Exploiter ensures only well-formed exploitation queues proceed.
  234. ### Role Boundaries
  235. Each role has explicit tool restrictions enforced through prompts:
  236. - **Scouts** cannot call `log_finding()` or send attack payloads
  237. - **Analyzers** can log configuration findings (missing headers, weak cookies) but not injection-class findings
  238. - **Exploiters** cannot create new queues — they consume what the Analyzer produced
  239. - **Reporters** cannot send HTTP requests to the target — they review data only
  240. For CTF challenges and small apps (<3 input endpoints), a legacy monolithic pipeline is available as a fallback.
  241. ---
  242. ## Quick Start
  243. ### Prerequisites
  244. - [Docker](https://docs.docker.com/get-docker/) (Docker Desktop on macOS/Windows, Docker Engine on Linux)
  245. - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) with an active Anthropic API key
  246. - [uv](https://docs.astral.sh/uv/) (Python package manager for the MCP server)
  247. - [Node.js](https://nodejs.org/) (for Playwright MCP server)
  248. - **Optional:** [Burp Suite Professional](https://portswigger.net/burp/pro) for passive traffic monitoring
  249. ### Installation
  250. ```bash
  251. # 1. Clone the repository
  252. git clone https://github.com/bhavsec/autopentest-ai.git
  253. cd autopentest-ai
  254. # 2. Install Python dependencies for the MCP server
  255. cd server && uv sync && cd ..
  256. # 3. Build Docker image and start the tools container
  257. make setup
  258. ```
  259. That's it. All 27 security tools are now installed and ready inside the Docker container.
  260. ### Verify Installation
  261. ```bash
  262. # Check all tools are installed
  263. make verify-tools
  264. # Expected output:
  265. # [+] nuclei: installed
  266. # [+] httpx: installed
  267. # [+] katana: installed
  268. # ... (27 tools total)
  269. ```
  270. ### Start Testing
  271. ```bash
  272. # Launch Claude Code in the project directory
  273. claude
  274. ```
  275. Then tell Claude what to test:
  276. ```
  277. Run a full WSTG assessment against https://target.example.com
  278. ```
  279. ---
  280. ## Usage
  281. ### Option A: Interactive Mode
  282. Launch Claude Code and provide the target:
  283. ```
  284. Run a full pentest against https://app.example.com
  285. Credentials: admin / P@ssw0rd123
  286. ```
  287. Claude will ask for any missing information (like credentials) and begin the 7-phase workflow.
  288. ### Option B: Config-Driven Mode (Recommended)
  289. Create a YAML config file for repeatable, consistent assessments:
  290. ```yaml
  291. # configs/my-target.yaml
  292. target:
  293. url: https://app.example.com
  294. scope:
  295. - app.example.com
  296. - api.example.com
  297. exclude:
  298. - cdn.example.com
  299. authentication:
  300. login_type: form
  301. login_url: https://app.example.com/login
  302. credentials:
  303. username: testuser@example.com
  304. password: secret123
  305. login_flow:
  306. - "Type $username into the email field"
  307. - "Type $password into the password field"
  308. - "Click the 'Sign In' button"
  309. success_condition:
  310. type: url_contains
  311. value: "/dashboard"
  312. rules:
  313. avoid:
  314. - description: "Do not test logout"
  315. type: path
  316. url_path: "/logout"
  317. focus:
  318. - description: "Prioritize API endpoints"
  319. type: path
  320. url_path: "/api"
  321. reporting:
  322. tester_name: "Security Team"
  323. ```
  324. Then in Claude Code:
  325. ```
  326. Load the config from configs/my-target.yaml and run the pentest
  327. ```
  328. ### Option C: Targeted Testing
  329. Run specific WSTG tests against specific endpoints:
  330. ```
  331. Run WSTG-INPV-05 (SQL Injection) against https://app.example.com/search?q=
  332. ```
  333. ```
  334. Test https://app.example.com for CORS misconfiguration (WSTG-CONF-13)
  335. ```
  336. ```
  337. Run all authentication tests (WSTG-ATHN) against https://app.example.com
  338. ```
  339. ### Option D: Resume an Interrupted Engagement
  340. ```
  341. Resume engagement pentest-2026-02-11-myapp
  342. ```
  343. ---
  344. ## Testing Phases
  345. ### Phase 0: Application Discovery & Mapping
  346. The critical foundation phase. Claude autonomously:
  347. 1. **Pre-flight checks** — verifies target reachability, detects redirects and cross-domain auth
  348. 2. **Launches 10+ background tools** in parallel (katana, ffuf, nuclei, whatweb, gau, nmap, feroxbuster, wapiti, httpx)
  349. 3. **Recursive crawling** — follows links to depth 2-3, parses HTML/JS for endpoints
  350. 4. **Directory brute-forcing** — common paths + technology-specific wordlists
  351. 5. **Tool result ingestion** — reads all background tool outputs and merges into unified endpoint map
  352. 6. **Builds structured endpoint inventory** with parameters, auth requirements, and priority rankings
  353. **Output:** A complete endpoint map organized by domain, ready for systematic testing.
  354. ### Phase 1-2: Reconnaissance & Configuration
  355. - Server fingerprinting, technology detection, metadata review
  356. - Security header analysis (HSTS, CSP, CORS, X-Frame-Options)
  357. - TLS configuration testing, admin interface discovery
  358. - HTTP methods testing, file extension handling
  359. ### Phase 3: Authentication, Authorization & Session Management
  360. - **Role/privilege lattice** built before testing (maps guards, middleware, and bypass tests)
  361. - IDOR testing with multiple alternate IDs per endpoint
  362. - CSRF testing on every state-changing endpoint
  363. - Session fixation, hijacking, and token analysis
  364. - JWT vulnerability testing (if applicable)
  365. - OAuth/OIDC weakness testing (if applicable)
  366. ### Phase 4: Input Validation (Highest Impact)
  367. Three independent two-stage pipelines run in parallel, each using the Analyzer→Exploiter role split:
  368. | Pipeline | Vulnerability Classes | Tools | Technique Guides |
  369. |----------|----------------------|-------|-----------------|
  370. | XSS Pipeline | Reflected XSS, Stored XSS, DOM XSS | dalfox, Playwright | XSS, DOM |
  371. | Injection Pipeline | SQL Injection, Command Injection, NoSQL Injection | sqlmap, commix, nosqli | SQLI, CMDI, NOSQLI |
  372. | SSRF/SSTI Pipeline | SSRF, SSTI, Path Traversal | sstimap, ssrfmap | SSRF, SSTI, PTRAV |
  373. Each pipeline: **Analyzer** (discover → analyze → build exploitation queue) → validation checkpoint → **Exploiter** (attempt exploitation → prove impact → log findings). WAF evasion intelligence is shared across all pipelines.
  374. ### Phase 5: Error Handling, Crypto, Business Logic, Client-Side & APIs
  375. - Stack trace and error message disclosure
  376. - TLS/SSL testing via testssl.sh
  377. - Business logic bypass (workflow circumvention, request forgery)
  378. - Client-side testing (clickjacking, open redirects, DOM manipulation)
  379. - GraphQL and REST API testing
  380. - Vulnerability chaining analysis across all findings
  381. ### Phase 6: Reporting
  382. - Coverage verification (test coverage + tool coverage)
  383. - Finding deduplication and severity calibration
  384. - Markdown report generation with executive summary, findings, coverage matrices
  385. ### Phase 7: Final Judge Review
  386. A zero-context agent reviews the entire engagement cold — no knowledge of testing decisions or difficulties. It examines:
  387. - **Coverage integrity** — rubber-stamped tests, missing endpoints
  388. - **N/A cascade detection** — categories with excessive "not applicable" markings
  389. - **Finding quality** — evidence completeness, severity consistency, chaining opportunities
  390. - **Tool utilization** — tools run but output never reviewed, lazy skip reasons
  391. - **Missed attack surface** — untested endpoints, untested parameters, untested domains
  392. The verdict (PASS/CONDITIONAL_PASS/FAIL) triggers specific remediation actions before the report is delivered.
  393. ---
  394. ## Security Tools
  395. ### Discovery & Reconnaissance (Phase 0)
  396. | Tool | Purpose | Key Flags |
  397. |------|---------|-----------|
  398. | **katana** | Web crawler with JS rendering | `-jc` for JavaScript crawling |
  399. | **httpx** | HTTP probing, tech detection | `-tech-detect -status-code -title` |
  400. | **ffuf** | Directory/parameter fuzzing | `-w wordlist -mc all -fc 404` |
  401. | **feroxbuster** | Recursive directory enumeration | `--smart --auto-tune` |
  402. | **nuclei** | Template-based vuln scanner | `-t cves/ -t misconfigurations/` |
  403. | **nikto** | Web server misconfiguration | `-Tuning 1234567890` |
  404. | **whatweb** | Technology fingerprinting | `--aggression 3` |
  405. | **nmap** | Port and service scanning | `-sV -sC --top-ports 1000` |
  406. | **gau** | Historical URL discovery | `--blacklist png,jpg,gif` |
  407. | **subfinder** | Subdomain enumeration | `-silent -all` |
  408. ### Injection Testing (Phase 4)
  409. | Tool | Purpose | Key Flags |
  410. |------|---------|-----------|
  411. | **sqlmap** | SQL injection (all techniques) | `--batch --risk 3 --level 5` |
  412. | **dalfox** | XSS scanning & exploitation | `--skip-bav --deep-domxss` |
  413. | **commix** | Command injection | `--batch --all` |
  414. | **sstimap** | Server-Side Template Injection | `-u <url>` |
  415. | **ssrfmap** | SSRF exploitation | `-r request.txt` |
  416. | **nosqli** | NoSQL injection | `-u <url>` |
  417. | **crlfuzz** | CRLF injection / HTTP splitting | `-u <url>` |
  418. | **smuggler** | HTTP request smuggling | `-u <url>` |
  419. ### Authentication & Session (Phase 3)
  420. | Tool | Purpose | Key Flags |
  421. |------|---------|-----------|
  422. | **hydra** | Credential brute-force | `-L users.txt -P pass.txt` |
  423. | **jwt_tool** | JWT token analysis & exploitation | `-t <token> -M at` |
  424. ### Cryptography & APIs (Phase 5)
  425. | Tool | Purpose | Key Flags |
  426. |------|---------|-----------|
  427. | **testssl.sh** | TLS/SSL configuration testing | `--severity HIGH --sneaky` |
  428. | **graphql-cop** | GraphQL security testing | `-t <url>` |
  429. | **websocat** | WebSocket testing | `ws://<url>` |
  430. ### Infrastructure (Phase 2)
  431. | Tool | Purpose |
  432. |------|---------|
  433. | **corscanner** | CORS misconfiguration scanning |
  434. | **dnsreaper** | Subdomain takeover detection |
  435. ### Browser Automation
  436. | Tool | Purpose |
  437. |------|---------|
  438. | **Playwright** | DOM XSS proof, clickjacking, JS-rendered login, client-side storage inspection |
  439. ---
  440. ## WSTG Knowledge Base
  441. 109 test cases across 12 OWASP categories, each with CLI-specific procedures:
  442. | Code | Category | Tests | Examples |
  443. |------|----------|:-----:|---------|
  444. | **INFO** | Information Gathering | 10 | Search engine discovery, server fingerprinting, metadata review |
  445. | **CONF** | Configuration & Deployment | 14 | Security headers, CORS, CSP, HSTS, admin interfaces |
  446. | **IDNT** | Identity Management | 5 | Role definitions, registration, account enumeration |
  447. | **ATHN** | Authentication | 11 | Default creds, lockout, auth bypass, MFA, password policy |
  448. | **ATHZ** | Authorization | 5 | Directory traversal, auth bypass, privilege escalation, IDOR |
  449. | **SESS** | Session Management | 11 | Cookie attributes, CSRF, session fixation/hijacking, JWT |
  450. | **INPV** | Input Validation | 20 | XSS, SQLi, CMDi, SSTI, SSRF, path traversal, XXE, LDAP |
  451. | **ERRH** | Error Handling | 2 | Error messages, stack traces |
  452. | **CRYP** | Cryptography | 4 | TLS config, padding oracle, weak encryption |
  453. | **BUSL** | Business Logic | 10 | Workflow bypass, request forgery, file upload, rate limits |
  454. | **CLNT** | Client-Side | 14 | DOM XSS, clickjacking, open redirects, WebSockets, storage |
  455. | **APIT** | API Testing | 3 | GraphQL, REST, SOAP |
  456. Each test file includes:
  457. - Step-by-step CLI procedures (curl commands, tool invocations)
  458. - Payloads organized by bypass level (basic, intermediate, advanced)
  459. - Detection criteria with severity assessment rubrics
  460. - Remediation guidance with references
  461. ---
  462. ## PortSwigger Technique Guides
  463. 31 attack technique reference guides sourced from [PortSwigger Web Security Academy](https://portswigger.net/web-security), organized by vulnerability class for direct use during real pentesting engagements.
  464. ### What's Included
  465. | Code | Category | WSTG Mapping | Key Content |
  466. |------|----------|-------------|-------------|
  467. | **SQLI** | SQL Injection | INPV-05 | UNION/blind/error/time-based/OOB techniques, database-specific cheat sheets (Oracle, MySQL, PostgreSQL, MSSQL), WAF bypass |
  468. | **XSS** | Cross-Site Scripting | INPV-01, INPV-02, CLNT-01 | Reflected/stored/DOM contexts, tag & event handler payloads, CSP bypass, filter evasion |
  469. | **CMDI** | OS Command Injection | INPV-12 | Separator characters, blind techniques (time-delay, OOB), OS-specific payloads |
  470. | **SSTI** | Server-Side Template Injection | INPV-18 | Jinja2/Twig/Freemarker/Velocity/ERB detection & exploitation, sandbox escapes |
  471. | **SSRF** | Server-Side Request Forgery | INPV-19 | URL scheme tricks, IP obfuscation, DNS rebinding, cloud metadata, filter bypass |
  472. | **PTRAV** | Path Traversal | INPV-04 | Encoding variations, null byte injection, wrapper bypass |
  473. | **XXE** | XML External Entities | INPV-07 | File retrieval, SSRF via XXE, blind XXE with OOB, parameter entities |
  474. | **AUTHN** | Authentication | ATHN-01 to ATHN-07 | Brute force, 2FA bypass, password reset poisoning, credential stuffing |
  475. | **AUTHZ** | Access Control | ATHZ-01 to ATHZ-04 | IDOR, privilege escalation, horizontal/vertical bypass, referer-based controls |
  476. | **JWT** | JSON Web Tokens | SESS-10 | Algorithm confusion (none/HS256→RS256), kid injection, JWK/JKU exploitation |
  477. | **OAUTH** | OAuth 2.0 | ATHZ-05 | Authorization code theft, open redirect, scope upgrade, CSRF on OAuth flows |
  478. | **CSRF** | Cross-Site Request Forgery | SESS-05 | Token bypass, SameSite bypass, referer validation bypass |
  479. | **SMUGGLE** | HTTP Request Smuggling | INPV-15 | CL.TE, TE.CL, TE.TE, HTTP/2 downgrade, request tunneling |
  480. | **DOM** | DOM-Based Vulnerabilities | CLNT-01 | Sources/sinks, DOM clobbering, prototype pollution gadgets |
  481. | **CORS** | Cross-Origin Resource Sharing | CONF-13, CLNT-07 | Origin reflection, null origin, subdomain trust exploitation |
  482. | **NOSQLI** | NoSQL Injection | INPV-05 | MongoDB operator injection, JavaScript injection, blind extraction |
  483. | **GRAPHQL** | GraphQL | APIT-01 | Introspection, field suggestion, batching attacks, authorization bypass |
  484. | **RACE** | Race Conditions | BUSL-04 | Limit overrun, TOCTOU, single-endpoint races, last-frame sync |
  485. | **UPLOAD** | File Upload | BUSL-08, BUSL-09 | Extension bypass, content-type manipulation, web shells, polyglot files |
  486. | **HOST** | Host Header Injection | INPV-17 | Password reset poisoning, cache poisoning, routing-based SSRF |
  487. Plus 11 more: CLICK, WS, CACHEPOIS, CACHEDEC, DESER, INFO, BUSL, PROTO, API, LLM, SKILLS.
  488. ### How They're Used
  489. Technique guides are integrated into every testing phase via the `get_technique_guide()` MCP tool:
  490. ```
  491. Phase 2 → CORS guide for CONF-13 testing
  492. Phase 3 → AUTHN, AUTHZ, CSRF, JWT, OAUTH guides for auth/session testing
  493. Phase 4 → SQLI, XSS, CMDI, SSTI, SSRF, PTRAV, XXE guides for input validation
  494. Phase 5 → DOM, CLICK, GRAPHQL, RACE, UPLOAD guides for client-side & business logic
  495. ```
  496. Each parallel testing agent automatically loads its relevant technique guide before testing, providing:
  497. - **Detection payloads** — what to inject to identify the vulnerability
  498. - **Exploitation techniques** — organized by attack method with step-by-step procedures
  499. - **Cheat sheets** — database/platform-specific syntax tables for quick reference
  500. - **WAF bypass patterns** — encoding, obfuscation, and filter evasion strategies
  501. ### Adding Custom Guides
  502. See [`docs/adding-knowledge-base-resources.md`](docs/adding-knowledge-base-resources.md) for instructions on adding new technique guides to the knowledge base.
  503. ---
  504. ## Quality Assurance System
  505. AutoPentest has a multi-layered QA system that prevents shallow testing:
  506. ### 1. Phase Gates (Automated)
  507. After each phase, `phase_gate_check()` validates:
  508. - All MUST-priority tests were executed
  509. - Minimum coverage thresholds are met
  510. - Tool coverage is adequate
  511. - No critical gaps exist
  512. **Blocked phases cannot proceed** until all issues are resolved.
  513. ### 2. Quality Reviewer (Per-Phase)
  514. A subagent spawned at every phase transition that:
  515. - Checks for 16 known anti-patterns (rubber-stamping, N/A cascades, finding inflation)
  516. - Identifies untested endpoints and parameters
  517. - Suggests vulnerability chaining opportunities
  518. - Recommends alternative approaches for blocked tests
  519. ### 3. Final Judge (Post-Report)
  520. A zero-context agent that reviews the completed engagement with fresh eyes:
  521. - Analyzes coverage integrity across all domains
  522. - Detects N/A cascades and their root causes
  523. - Validates finding quality and evidence completeness
  524. - Identifies missed attack surface
  525. - Issues a verdict: **PASS**, **CONDITIONAL_PASS**, or **FAIL**
  526. ### 4. Exhaustion Gates
  527. Marking a vulnerability as "not exploitable" requires proof of effort:
  528. | Vuln Class | Min Techniques | Min Bypass Attempts |
  529. |------------|:-:|:-:|
  530. | XSS | 3 | 5 |
  531. | SQL Injection | 3 | 5 |
  532. | Command Injection | 3 | 5 |
  533. | SSTI | 2 | 3 |
  534. | SSRF | 3 | 5 |
  535. | Path Traversal | 3 | 5 |
  536. ### 5. Evidence Checklists
  537. Before logging any finding, evidence requirements are verified:
  538. - Reproducible curl command
  539. - Full HTTP request and response
  540. - Proof of actual exploitation (not theoretical impact)
  541. - Correct classification tier (EXPLOITED vs POTENTIAL)
  542. ### 6. Live Engagement Logging
  543. Every MCP tool call is automatically logged to `engagements/<eid>/logs.txt` with full arguments, results, and execution duration. Run `tail -f logs.txt` in a separate terminal to watch all agent activity in real time. 100% coverage via automatic tool wrapper — no manual instrumentation needed.
  544. ### 7. Phase Gate Timing
  545. Phase gates enforce minimum 60-second intervals between calls (15s in CTF mode), preventing premature phase completion. Inter-gate work verification warns if fewer than 3 work events occur between consecutive gates.
  546. ---
  547. ## Benchmarking
  548. AutoPentest includes integration with the [XBOW Validation Benchmarks](https://github.com/xbow-engineering/validation-benchmarks) — 104 CTF-style Docker challenges used as the industry standard for benchmarking AI pentest agents.
  549. ### Benchmark Scores (Reference)
  550. | Agent | Score | Source |
  551. |-------|:-----:|--------|
  552. | Shannon | 96.2% | KeygraphHQ (2024) |
  553. | PentestGPT | 86.5% | USENIX Sec 2024 |
  554. ### Usage
  555. ```bash
  556. # Setup (one-time)
  557. cd benchmarks/xbow && make setup
  558. # Solve with AutoPentest (MCP server + CLAUDE.md + CTF mode)
  559. make solve ID=XBEN-001-24
  560. # Solve with raw Claude (baseline — no MCP, no methodology)
  561. make solve ID=XBEN-001-24 RAW=1
  562. # Solve by vulnerability tag
  563. make solve-tag TAG=sqli
  564. # Solve all 104 challenges
  565. make solve-all
  566. # Full baseline run for comparison
  567. make solve-all RAW=1
  568. # Score the latest run
  569. make score
  570. # Compare autopentest vs raw runs side-by-side
  571. make compare
  572. ```
  573. The solver has two modes:
  574. - **autopentest** (default): Runs Claude Code from the project root, loading `.mcp.json` (MCP server with 68+ tools) and `CLAUDE.md` (pentest methodology). Measures AutoPentest's full capability.
  575. - **raw** (`RAW=1`): Runs bare Claude Code with no MCP server or methodology. Baseline for measuring AutoPentest's value-add over raw LLM capability.
  576. Each challenge is a Docker Compose app with a flag injected at build time. Flag extraction from Claude's output determines pass/fail. Results are scored per-challenge, per-tag, and per-difficulty-level.
  577. ### CTF Mode
  578. For CTF challenges and small apps, enable CTF mode for relaxed quality gates:
  579. ```yaml
  580. mode: ctf
  581. target:
  582. url: https://target.com
  583. ```
  584. CTF mode reduces phase gate timing (15s vs 60s), skips QA Reviewer requirements, and halves completion thresholds — while maintaining finding quality and evidence standards.
  585. ---
  586. ## Example Report
  587. A complete example report from a pentest against [PortSwigger's Gin & Juice Shop](https://ginandjuice.shop) (a deliberately vulnerable application) is included in the repository:
  588. **[View Full Report](engagements/pentest-2026-ginandjuice/report.md)**
  589. ### What the Report Includes
  590. The report demonstrates AutoPentest's output against a real target with 23 findings across all severity levels:
  591. | Severity | Count | Examples |
  592. |----------|:-----:|---------|
  593. | Critical | 2 | UNION-based SQL injection with full data extraction, access control bypass via X-Original-URL header |
  594. | High | 5 | Reflected XSS via JS string escape bypass, IDOR on order details, XXE with local file read, DOM XSS via prototype pollution |
  595. | Medium | 6 | Missing security headers, no account lockout, missing CSP, CRLF injection, DOM-based open redirect |
  596. | Low | 5 | Infrastructure info disclosure, EOL AngularJS, insecure ALB cookies, weak TLS config |
  597. | Informational | 5 | Consolidated duplicates and secondary evidence for primary findings |
  598. ### Report Structure
  599. ```
  600. 1. Executive Summary — Target scope, finding summary, domain architecture
  601. 2. Detailed Findings — Each finding with description, evidence (curl commands), and remediation
  602. 3. Vulnerability Chaining — Cross-finding analysis (e.g., XSS + no CSP = severity upgrade)
  603. 4. Test Coverage Matrix — Per-category WSTG coverage (100% across 12 categories)
  604. 5. Tool Coverage Matrix — 27/27 tools tracked, 8 actively run
  605. ```
  606. ### Sample Finding (SQL Injection)
  607. From the report — a Critical SQL injection finding with full exploitation evidence:
  608. ```
  609. FINDING-017: SQL Injection in /catalog category parameter — Full Data Extraction
  610. Severity: Critical
  611. WSTG Reference: WSTG-INPV-05
  612. The category parameter is vulnerable to UNION-based SQL injection.
  613. The attacker can:
  614. 1. Inject a single quote to cause a 500 error (confirming injection)
  615. 2. Use UNION SELECT with 8 columns to extract arbitrary data
  616. 3. Enumerate tables: PRODUCTS, TRACKING, USERS
  617. 4. Extract credentials from the USERS table
  618. Evidence (reproducible curl command):
  619. curl -sk "https://ginandjuice.shop/catalog?category='+UNION+SELECT+1,USERNAME,PASSWORD,
  620. 1,1,USERNAME,1,USERNAME+FROM+USERS+LIMIT+10--"
  621. ```
  622. Every finding includes reproducible curl commands, full request/response evidence, and actionable remediation guidance.
  623. ---
  624. ## Configuration
  625. ### Engagement Config (YAML)
  626. Config-driven pentests skip interactive questions and ensure consistency:
  627. ```yaml
  628. target:
  629. url: https://app.example.com
  630. scope: [app.example.com, api.example.com]
  631. authentication:
  632. login_type: sso # form | sso | api | manual | none
  633. login_url: https://app.example.com/login
  634. credentials:
  635. username: testuser
  636. password: secret123
  637. sso:
  638. provider: keycloak # keycloak | auth0 | okta | azure_ad
  639. auth_domain: auth.example.com
  640. realm: myrealm
  641. client_id: my-app
  642. rules:
  643. avoid:
  644. - { type: path, url_path: "/logout", description: "Skip logout" }
  645. - { type: endpoint, method: DELETE, url_path: "/api/admin/*", description: "No destructive admin ops" }
  646. focus:
  647. - { type: path, url_path: "/api", description: "Prioritize API" }
  648. reporting:
  649. tester_name: "Security Team"
  650. ```
  651. ### MCP Server Configuration
  652. The `.mcp.json` file registers two MCP servers:
  653. ```json
  654. {
  655. "mcpServers": {
  656. "wstg-pentest": {
  657. "command": "uv",
  658. "args": ["--directory", "./server", "run", "server.py"]
  659. },
  660. "playwright": {
  661. "command": "npx",
  662. "args": ["-y", "@playwright/mcp"]
  663. }
  664. }
  665. }
  666. ```
  667. ### Burp Suite Integration (Optional)
  668. For passive traffic monitoring through Burp Suite Professional:
  669. 1. Start Burp Suite and enable the proxy on **all interfaces** (`0.0.0.0:8080`)
  670. 2. The Docker container automatically routes traffic through `host.docker.internal:8080`
  671. 3. All HTTP requests appear in Burp's proxy history for manual review
  672. ---
  673. ## Multi-Domain Testing
  674. AutoPentest has first-class support for applications with multiple domains (e.g., a SPA frontend + API backend + SSO provider):
  675. ### Automatic Detection
  676. During Phase 0, AutoPentest detects cross-domain authentication by following login redirects:
  677. ```
  678. app.example.com → redirects to → auth.example.com/login
  679. → after login → app.example.com/callback
  680. ```
  681. All domains are automatically registered in scope with their type (app, auth_provider, api, cdn).
  682. ### Per-Domain Testing
  683. Every WSTG test is evaluated per domain — not just the primary:
  684. - Discovery tools (katana, ffuf, nuclei) run against **all** domains
  685. - Input validation tools (sqlmap, dalfox) target endpoints on **every** domain with server-side processing
  686. - A test is "not applicable" only when **no** domain has the tested feature
  687. ### Cross-Domain Authentication
  688. Supported SSO protocols:
  689. - **OAuth 2.0 / OIDC** (Authorization Code, PKCE, Password Grant, Client Credentials)
  690. - **SAML** (SP-initiated flow)
  691. - **Keycloak**, **Auth0**, **Okta**, **Azure AD**
  692. - **Custom SSO** (redirect chain following with cookie jar)
  693. Authentication escalation procedure (6 levels) ensures testing can proceed even with complex auth flows.
  694. ---
  695. ## Crash Recovery
  696. AutoPentest is designed to survive interruptions:
  697. ### Automatic Checkpointing
  698. - Phase gates auto-save checkpoints on PASS
  699. - `git_checkpoint()` creates git snapshots of the engagement workspace
  700. - Append-only logs (`findings.md`, `progress.log`) survive crashes
  701. ### Auto-Resume via resume-prompt.md (Recommended)
  702. Every checkpoint and phase gate automatically generates `engagements/<eid>/resume-prompt.md` — a complete, self-contained prompt with everything a fresh session needs:
  703. - Target URL, authentication credentials, and scope domains
  704. - Current phase and which specific tests remain (mid-phase precision)
  705. - Cookie jar status and re-authentication instructions
  706. - Avoid/focus rules and endpoint map references
  707. **To resume after an interruption:**
  708. 1. Open a new Claude Code session
  709. 2. Paste the contents of `engagements/<eid>/resume-prompt.md`
  710. 3. Claude picks up exactly where it left off — no manual context needed
  711. ### Resume from Checkpoint (Alternative)
  712. ```
  713. Resume engagement pentest-2026-02-11-myapp
  714. ```
  715. This restores:
  716. - All findings and test tracking data
  717. - Coverage statistics and phase gate results
  718. - Scope registrations and deliverables
  719. - Mid-phase remaining tests (not just phase-level state)
  720. - Instructions for what to do next
  721. ### Manual Checkpoints
  722. Save at any time:
  723. ```
  724. Save a checkpoint before starting Phase 4 exploitation
  725. ```
  726. ### Rollback on Failure
  727. If a phase produces bad results, roll back to the previous checkpoint:
  728. ```
  729. Roll back the engagement to the last checkpoint
  730. ```
  731. ---
  732. ## Project Structure
  733. ```
  734. autopentest-ai/
  735. ├── CLAUDE.md # Master pentest workflow (drives Claude Code)
  736. ├── .mcp.json # MCP server configuration
  737. ├── Dockerfile # Multi-stage Docker build (27 tools)
  738. ├── docker-compose.yml # Docker Compose alternative
  739. ├── Makefile # setup, start, stop, verify-tools, shell
  740. │
  741. ├── server/
  742. │ ├── server.py # FastMCP server (68+ MCP tools)
  743. │ ├── task_tree.py # Hierarchical task tree (6 MCP tools)
  744. │ ├── tool_parsers.py # Tool output parsing (2 MCP tools, 13 parsers)
  745. │ ├── endpoint_priority.py # Endpoint risk prioritization (2 MCP tools)
  746. │ ├── waf_evasion.py # Adaptive WAF evasion (3 MCP tools, 12 vendors)
  747. │ ├── knowledge_graph.py # Cross-phase knowledge graph (5 MCP tools)
  748. │ ├── tool_verification.py # CLI tool results verification (1 MCP tool, 10 validators)
  749. │ ├── context_compression.py # Progressive context compression (2 MCP tools)
  750. │ └── pyproject.toml # Python dependencies
  751. │
  752. ├── knowledge-base/
  753. │ ├── web-security-testing-guide/ # OWASP WSTG knowledge base (109 test procedures)
  754. │ │ ├── 01-information-gathering/ # 10 tests (WSTG-INFO-01 → 10)
  755. │ │ ├── 02-configuration/ # 14 tests (WSTG-CONF-01 → 14)
  756. │ │ ├── 03-identity-management/ # 5 tests (WSTG-IDNT-01 → 05)
  757. │ │ ├── 04-authentication/ # 11 tests (WSTG-ATHN-01 → 11)
  758. │ │ ├── 05-authorization/ # 5 tests (WSTG-ATHZ-01 → 05)
  759. │ │ ├── 06-session-management/ # 11 tests (WSTG-SESS-01 → 11)
  760. │ │ ├── 07-input-validation/ # 20 tests (WSTG-INPV-01 → 20)
  761. │ │ ├── 08-error-handling/ # 2 tests (WSTG-ERRH-01 → 02)
  762. │ │ ├── 09-cryptography/ # 4 tests (WSTG-CRYP-01 → 04)
  763. │ │ ├── 10-business-logic/ # 10 tests (WSTG-BUSL-01 → 10)
  764. │ │ ├── 11-client-side/ # 14 tests (WSTG-CLNT-01 → 14)
  765. │ │ └── 12-api-testing/ # 3 tests (WSTG-APIT-01 → 03)
  766. │ └── portswigger-academy/ # 31 PortSwigger attack technique guides
  767. │ ├── sql-injection.md # UNION, blind, error-based, OOB, WAF bypass
  768. │ ├── cross-site-scripting.md # Reflected, stored, DOM, CSP bypass, filter evasion
  769. │ ├── ssrf.md # URL schemes, cloud metadata, DNS rebinding
  770. │ ├── ssti.md # Jinja2, Twig, Freemarker sandbox escapes
  771. │ ├── jwt.md # Algorithm confusion, kid injection, JWK exploitation
  772. │ ├── oauth.md # Auth code theft, redirect exploitation, scope upgrade
  773. │ └── ... (31 total) # One per vulnerability class
  774. │
  775. ├── templates/ # Testing guides and procedures
  776. │ ├── input-validation-guide.md # Phase 4 step-by-step procedures
  777. │ ├── testing-strategies.md # Test matrices, chaining, parallel strategy
  778. │ ├── cli-tools-guide.md # Tool setup and Docker management
  779. │ ├── tools.md # Per-tool command reference
  780. │ ├── quality-gates.md # Phase quality checklists and anti-patterns
  781. │ ├── cross-domain-auth-guide.md # SSO/OIDC/SAML procedures
  782. │ ├── source-code-analysis.md # Security-focused code review template
  783. │ ├── pipelined-testing.md # Phase 4 pipelined exploitation strategy
  784. │ ├── agent-roles/ # Role-specialized subagent templates
  785. │ │ ├── README.md # Role index and selection guide
  786. │ │ ├── scout.md # Reconnaissance role (Phase 0-1)
  787. │ │ ├── analyzer.md # Vulnerability discovery role (Phase 2-5)
  788. │ │ ├── exploiter.md # Exploitation proof role (Phase 4)
  789. │ │ └── reporter.md # QA review + Final Judge role
  790. │ ├── shared/
  791. │ │ ├── honesty-framework.md # Anti-hallucination guardrails
  792. │ │ ├── exploit-classification.md # Three-tier finding classification
  793. │ │ ├── reproducibility.md # Evidence format requirements
  794. │ │ └── scope-rules.md # Avoid/focus rule templates
  795. │ └── wordlists/ # Tech-specific fuzzing wordlists
  796. │
  797. ├── benchmarks/
  798. │ └── xbow/ # XBOW benchmark suite (104 CTF challenges)
  799. │ ├── runner.py # Challenge orchestration
  800. │ ├── solver.py # Automated solver (Claude Code CLI)
  801. │ ├── Makefile # solve, solve-all, score, compare
  802. │ └── results/ # Run reports
  803. │
  804. ├── docs/
  805. │ ├── ROADMAP.md # Competitive analysis + improvement roadmap
  806. │ └── adding-knowledge-base-resources.md # Guide for adding new technique guides
  807. │
  808. ├── configs/
  809. │ ├── example-config.yaml # Example engagement configuration
  810. │ └── config-schema.md # YAML schema documentation
  811. │
  812. ├── scripts/
  813. │ ├── install-tools.sh # Docker build + container start
  814. │ ├── browser-auth.py # Headless Chromium auth (JS-rendered logins)
  815. │ ├── pkce-auth.py # OAuth 2.0 PKCE flow automation
  816. │ └── status.sh # Engagement status dashboard
  817. │
  818. └── engagements/ # Runtime output (git-ignored)
  819. └── <engagement-id>/
  820. ├── logs.txt # Live engagement log (tail -f to watch)
  821. ├── findings.md # Append-only findings log
  822. ├── progress.log # Timestamped event log
  823. ├── resume-prompt.md # Auto-resume prompt (paste into new session)
  824. ├── report.md # Final pentest report
  825. ├── cookies.txt # Cross-domain cookie jar
  826. └── tool-output/ # Raw CLI tool outputs
  827. ```
  828. ---
  829. ## Requirements
  830. | Requirement | Version | Notes |
  831. |-------------|---------|-------|
  832. | Docker | 20.10+ | Docker Desktop on macOS/Windows |
  833. | Claude Code | Latest | `npm install -g @anthropic-ai/claude-code` |
  834. | uv | 0.1+ | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
  835. | Node.js | 18+ | For Playwright MCP server |
  836. | Python | 3.10+ | Managed by uv (no manual install needed) |
  837. | Burp Suite Pro | Latest | **Optional** — for passive traffic monitoring |
  838. **Supported platforms:** macOS (Apple Silicon & Intel), Linux (x86_64 & ARM64)
  839. ---
  840. ## FAQ
  841. **Q: Does this replace a human penetration tester?**
  842. No. AutoPentest automates the systematic, methodology-driven parts of a pentest. It excels at coverage (ensuring nothing is missed) and consistency (every test follows the same procedure). However, complex business logic, creative exploitation chains, and context-dependent risk assessment still benefit from human expertise. Think of it as a force multiplier.
  843. **Q: How long does a full assessment take?**
  844. It depends on the application's size and complexity. A typical medium-sized web app (50-100 endpoints) takes a few hours. Multi-domain applications with SSO take longer. The pipelined Phase 4 architecture parallelizes the most time-intensive testing.
  845. **Q: Can I run this without Burp Suite?**
  846. Yes. Burp Suite is optional and used only for passive traffic monitoring. All HTTP requests go through `docker exec curl` and all security tools run inside the Docker container. Without Burp, you lose the ability to review traffic in Burp's proxy history, but all testing functionality works.
  847. **Q: What are the PortSwigger technique guides?**
  848. 31 attack reference guides covering detection, exploitation techniques, payloads, cheat sheets, and WAF bypass patterns — sourced from PortSwigger Web Security Academy. During testing, agents automatically load the relevant guide (e.g., the SQLi guide when testing for SQL injection) for comprehensive technique and payload reference. See [`docs/adding-knowledge-base-resources.md`](docs/adding-knowledge-base-resources.md) to add your own guides.
  849. **Q: How do I add custom wordlists or payloads?**
  850. Place wordlists in `templates/wordlists/` and they'll be available inside the Docker container via the volume mount. The WSTG test files in `knowledge-base/` can also be customized with additional payloads. To add new attack technique guides, follow the instructions in [`docs/adding-knowledge-base-resources.md`](docs/adding-knowledge-base-resources.md).
  851. **Q: Can I test applications behind a VPN?**
  852. Yes. The Docker container inherits your host's network (on Linux with `--network host`) or reaches the host via `host.docker.internal` (on macOS/Windows). If your VPN is running on the host, the container can reach VPN-protected targets.
  853. **Q: What happens if a pentest is interrupted (crash, usage limit, timeout)?**
  854. AutoPentest automatically generates a `resume-prompt.md` file at every checkpoint with everything needed to continue. Open a new Claude Code session, paste the contents of `engagements/<eid>/resume-prompt.md`, and testing resumes exactly where it left off — including mid-phase progress, credentials, scope, and remaining tests.
  855. **Q: What about rate limiting?**
  856. AutoPentest includes three-tier error classification (Transient/Rate Limit/Permanent) with automatic backoff. If the target rate-limits requests, tools automatically slow down. You can also set avoid rules in the config to skip specific endpoints.
  857. **Q: What are the agent roles?**
  858. AutoPentest uses 4 specialized roles (Scout, Analyzer, Exploiter, Reporter) instead of generic subagents. Each role has a dedicated prompt template with focused tool guidance, restricted tool lists, and anti-patterns. This prevents agents from conflating reconnaissance, analysis, exploitation, and reporting — improving focus and failure isolation. See [`templates/agent-roles/README.md`](templates/agent-roles/README.md) for the full role index.
  859. **Q: How does WAF evasion work?**
  860. When a payload gets blocked (403, block page), AutoPentest automatically fingerprints the WAF vendor from response characteristics, then loads vendor-specific bypass payloads organized by complexity level. 12 WAF vendors are supported (Cloudflare, AWS WAF, Akamai, Imperva, ModSecurity, F5, and more). WAF intelligence is shared across all agents via the deliverable system.
  861. **Q: What is counterfactual analysis?**
  862. After the first analysis pass finds vulnerabilities, AutoPentest can spawn a second Analyzer that assumes all known vulnerabilities are patched. This forces the agent to look for different attack vectors — different endpoints, parameters, injection contexts, and logic flaws. The results are merged into the existing exploitation queue with automatic deduplication. This technique is based on academic research (PenHeal ablation study) showing +71% vulnerability coverage improvement.
  863. **Q: How does results verification work?**
  864. When CLI tools (nmap, nuclei, sqlmap, etc.) produce empty or suspicious output, the `verify_tool_result()` tool detects common issues (proxy errors, permission denied, wrong flags) and suggests corrected commands. This prevents agents from silently counting broken tool runs as "completed" — a common failure mode in automated pentesting.
  865. **Q: How does vulnerability chaining work?**
  866. The knowledge graph tracks entities (endpoints, parameters, findings, cookies, domains) and relationships discovered during testing. After Phase 4, `find_chains()` uses BFS to discover multi-hop attack paths and checks 7 predefined chain patterns (e.g., XSS + missing CSP, SSRF + cloud metadata, IDOR + admin role). Chains that increase impact trigger automatic severity upgrades.
  867. ---
  868. ## Disclaimer
  869. **This tool is intended for authorized security testing only.** Only use AutoPentest against applications you have explicit permission to test. Unauthorized access to computer systems is illegal. The authors are not responsible for any misuse of this tool.
  870. Always ensure you have:
  871. - Written authorization from the application owner
  872. - A clearly defined scope of what can and cannot be tested
  873. - An understanding of the testing environment (production vs staging)
  874. - Appropriate avoid rules configured for destructive or sensitive endpoints
  875. ---
  876. <p align="center">
  877. Built with <a href="https://modelcontextprotocol.io">Model Context Protocol</a>
  878. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.