compliance-scanner-agent/docs/features/pentest.md

# AI Pentest

The AI Pentest module provides autonomous, LLM-driven penetration testing against your DAST targets. It orchestrates a chain of security tools guided by AI reasoning to discover vulnerabilities that traditional scanning may miss.

## Overview

Navigate to **Pentest** in the sidebar to see the pentest dashboard.

The dashboard shows:

- Total pentest sessions run
- Aggregate finding counts with severity breakdown
- Tool invocation statistics and success rates
- Session cards with status, target, strategy, and finding count

## Starting a Pentest Session

Click **New Pentest** on the dashboard to open the 4-step onboarding wizard:

### Step 1 — Target & Scope

- **App URL** — enter manually or select from existing DAST targets (dropdown)
- **Git Repository URL** — enter manually or select from tracked repositories (dropdown). If an SSH URL is selected, the deploy key is displayed for easy copy
- **Branch / Commit** — auto-populated when you click **Lookup** for a tracked repo
- **App Type** and **Rate Limit**

### Step 2 — Authentication

- **None** — unauthenticated testing
- **Manual Credentials** — provide username/password (encrypted at rest with AES-256-GCM)
- **Auto-Register** — the orchestrator uses the browser tool (headless Chrome) to discover the registration page and create a test account:
  - **Registration URL** (optional) — auto-discovered via Playwright if omitted
  - **Verification Email** (optional) — override the agent's default mailbox. Uses plus-addressing (`base+sessionid@domain`) and polls IMAP for verification links
  - **IMAP Settings** — collapsible section to override host/port/credentials

### Step 3 — Strategy & Instructions

| Strategy | Description |
|----------|-------------|
| **Comprehensive** | Full-spectrum test covering recon, API analysis, injection testing, auth checks, and more |
| **Quick** | Focus on common/high-impact vulnerabilities with minimal tool invocations |
| **Targeted** | SAST-guided — prioritize areas where static analysis found issues |
| **Aggressive** | Maximum payloads, attempt full exploitation |
| **Stealth** | Minimal noise, passive analysis, targeted probes |

- **Initial Instructions** — free-text guidance for the AI
- **Scope Exclusions** — paths to skip
- **Max Duration**, **Tester Name/Email**, **Destructive Tests** toggle

### Step 4 — Disclaimer & Confirm

Review the configuration summary and accept the authorization disclaimer.

The wizard can be closed at any time via the **X** button (top-right corner) or by clicking outside the modal.

::: tip Architecture Deep-Dive
See [Pentest Orchestration Architecture](./pentest-architecture.md) for details on how the LLM loop works, what context is passed, and how findings are correlated to source code.
:::

The AI orchestrator will autonomously select and execute security tools in phases, using the output of each phase to inform the next.

## Session View

Click any session card to open the detailed session view. It shows:

### Summary Cards

- **Findings** — total vulnerabilities discovered
- **Exploitable** — confirmed-exploitable findings
- **Tool Invocations** — total tools executed
- **Success Rate** — percentage of tools that completed successfully

### Severity Distribution

A bar showing the breakdown of findings by severity level (Critical, High, Medium, Low, Info).

### Findings Tab

Lists all discovered vulnerabilities with:

- Severity badge and title
- Vulnerability type and exploitability status
- HTTP method and endpoint
- CWE identifier
- Description and remediation recommendation
- Correlated SAST finding references (when available)

### Attack Chain Tab

A visual DAG (directed acyclic graph) showing the sequence of tools executed during the pentest. Nodes are grouped into phases:

- **Phase-based layout** — tools are organized top-down by execution phase (reconnaissance, analysis, testing, exploitation, etc.)
- **Category icons** — each tool displays an icon indicating its category (recon, XSS, SQLi, SSRF, auth, headers, cookies, TLS, CORS, etc.)
- **Status indicators** — color-coded status dots (green = completed, yellow = running, red = failed)
- **Finding badges** — red badge showing the number of findings produced by each tool
- **Interactive** — hover for details, click to select, scroll to zoom, drag to pan

### Pausing, Resuming & Stopping

- **Pause** — click the **Pause** button on a running session to suspend the orchestrator loop. The session status changes to `paused` and the LLM stops iterating. SSE clients receive a `paused` event.
- **Resume** — click **Resume** on a paused session to continue from where it left off. The status returns to `running` and a `resumed` event is broadcast.
- **Stop** — click **Stop** to permanently halt the session. This marks it as `failed` with reason "Stopped by user".

## Exporting Reports

Click **Export Report** on any session to generate a professional pentest report.

### Export Process

1. Enter an **encryption password** (minimum 8 characters)
2. Click **Export** to generate and download the report

The export produces a **password-protected ZIP archive** (AES-256 encryption) that can be opened with any standard archive tool (7-Zip, WinRAR, macOS Archive Utility, etc.).

### Archive Contents

| File | Description |
|------|-------------|
| `report.html` | Professional HTML report with executive summary, methodology, tools, findings with recommendations, and attack chain timeline |
| `findings.json` | Raw findings data in JSON format for programmatic processing |
| `attack-chain.json` | Raw attack chain data showing tool execution sequence and relationships |

### Report Features

The HTML report includes:

- Company logo and CONFIDENTIAL banner
- Requester information
- Executive summary with overall risk rating
- Severity distribution chart
- Methodology and tools section
- Detailed findings with severity, CWE, endpoint, evidence, remediation guidance, and linked SAST references
- Attack chain timeline
- Print-friendly layout (dark theme on screen, light theme for print)

### Integrity Verification

After export, the dashboard displays the **SHA-256 checksum** of the archive with a copy-to-clipboard button. Use this to verify the archive has not been tampered with after distribution.

::: warning
Only run pentests against applications you own or have explicit written authorization to test. AI-driven pentesting sends real attack payloads that may trigger alerts or cause unintended side effects.
:::