@vulcn/driver-browser 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { RecordOptions, RecordingHandle, Session, RunContext, RunResult, CrawlOptions, VulcnDriver } from '@vulcn/engine';
-import { Browser } from 'playwright';
+import { RecordOptions, RecordingHandle, Session, RunContext, RunResult, CapturedRequest, CrawlOptions, Finding, PayloadCategory, RuntimePayload, FormCredentials, VulcnDriver } from '@vulcn/engine';
+import { Browser, Page, BrowserContext } from 'playwright';
 
 /**
  * Browser Recorder Implementation
@@ -32,33 +32,31 @@ declare class BrowserRecorder {
  *
  * Replays browser sessions with security payloads.
  * Uses plugin hooks for detection.
+ *
+ * v2: Persistent browser with in-page payload cycling.
+ *   - ONE browser for the entire scan (not per-session)
+ *   - Uses page.goBack() between payloads instead of full page.goto()
+ *   - Falls back to full navigation when goBack() fails
+ *   - 5-10x faster on SPAs, same speed on simple sites
  */
 
 /**
  * Browser Runner - replays sessions with payloads
+ *
+ * Supports two modes:
+ * 1. Self-managed browser: launches its own browser (backward compat)
+ * 2. Shared browser: receives a browser instance via RunOptions
+ *
+ * In both modes, payload cycling uses goBack() for speed.
  */
 declare class BrowserRunner {
     /**
-     * Execute a session with security payloads
-     */
-    static execute(session: Session, ctx: RunContext): Promise<RunResult>;
-    /**
-     * Replay session steps with payload injected at target step
+     * Execute a session with security payloads.
      *
-     * IMPORTANT: We replay ALL steps, not just up to the injectable step.
-     * The injection replaces the input value, but subsequent steps (like
-     * clicking submit) must still execute so the payload reaches the server
-     * and gets reflected back in the response.
+     * If ctx.options.browser is provided, reuses that browser (persistent mode).
+     * Otherwise, launches and closes its own browser (standalone mode).
      */
-    private static replayWithPayload;
-    /**
-     * Check for payload reflection in page content
-     */
-    private static checkReflection;
-    /**
-     * Determine severity based on vulnerability category
-     */
-    private static getSeverity;
+    static execute(session: Session, ctx: RunContext): Promise<RunResult>;
 }
 
 /**
@@ -105,6 +103,7 @@ declare function checkBrowsers(): Promise<{
  * - Links to follow for deeper crawling
  *
  * Outputs Session[] that are directly compatible with BrowserRunner.
+ * Also generates CapturedRequest[] metadata for Tier 1 HTTP fast scanning.
  *
  * This is the "auto-record" mode — instead of a human clicking around,
  * the crawler automatically discovers injection points.
@@ -123,12 +122,171 @@ interface BrowserCrawlConfig {
         height: number;
     };
 }
+/** Result from crawling — sessions for browser replay + requests for HTTP scanning */
+interface CrawlResult {
+    sessions: Session[];
+    capturedRequests: CapturedRequest[];
+}
 /**
  * Crawl a URL and generate sessions.
  *
  * This is called by the browser driver's recorder.crawl() method.
+ * Returns both Session[] for Tier 2 browser replay and
+ * CapturedRequest[] for Tier 1 HTTP fast scanning.
+ */
+declare function crawlAndBuildSessions(config: BrowserCrawlConfig, options?: CrawlOptions): Promise<CrawlResult>;
+
+/**
+ * HTTP Scanner — Tier 1 Fast Scan
+ *
+ * Replays captured HTTP requests via fetch() instead of Playwright.
+ * Substitutes security payloads into injectable form fields and checks
+ * the response body for payload reflection or error patterns.
+ *
+ * Speed: ~50ms per payload (vs 2-5s for browser replay)
+ *
+ * Catches:
+ *   - Reflected XSS (payload appears in response body)
+ *   - Error-based SQLi (SQL error patterns in response)
+ *   - Server-side reflection of any payload
+ *
+ * Misses:
+ *   - DOM-based XSS (requires JS execution)
+ *   - Client-side state bugs
+ *   - CSP-blocked attacks
+ *
+ * When reflection IS found, the finding is marked as `needsBrowserConfirmation`
+ * so the caller can escalate to Tier 2 for execution-based proof.
+ */
+
+interface HttpScanResult {
+    /** Total HTTP requests sent */
+    requestsSent: number;
+    /** How long the scan took (ms) */
+    duration: number;
+    /** Findings from reflection detection */
+    findings: Finding[];
+    /** Requests where reflection was found — should be escalated to Tier 2 */
+    reflectedRequests: ReflectedRequest[];
+}
+interface ReflectedRequest {
+    /** Original captured request */
+    request: CapturedRequest;
+    /** Payload that caused reflection */
+    payload: string;
+    /** Category of the payload */
+    category: PayloadCategory;
+}
+interface HttpScanOptions {
+    /** Request timeout in ms (default: 10000) */
+    timeout?: number;
+    /** Max concurrent requests (default: 10) */
+    concurrency?: number;
+    /** Cookie header to send with requests (for auth) */
+    cookies?: string;
+    /** Extra headers to send */
+    headers?: Record<string, string>;
+    /** Callback for progress reporting */
+    onProgress?: (completed: number, total: number) => void;
+}
+/**
+ * Run Tier 1 HTTP-level scan on captured requests.
+ *
+ * For each CapturedRequest × each payload:
+ *   1. Substitute the payload into the injectable field
+ *   2. Send via fetch()
+ *   3. Check response body for reflection patterns
+ *   4. If reflected, add finding + mark for Tier 2 escalation
+ */
+declare function httpScan(requests: CapturedRequest[], payloads: RuntimePayload[], options?: HttpScanOptions): Promise<HttpScanResult>;
+/**
+ * Convert discovered forms into CapturedRequest metadata.
+ *
+ * Called by the crawler after form discovery. Each injectable form
+ * produces one CapturedRequest per injectable input field.
+ */
+declare function buildCapturedRequests(forms: Array<{
+    pageUrl: string;
+    action: string;
+    method: string;
+    inputs: Array<{
+        name: string;
+        injectable: boolean;
+        type: string;
+    }>;
+    sessionName: string;
+}>): CapturedRequest[];
+
+/**
+ * Login Form Auto-Detection & Auth Replay
+ *
+ * Detects login forms on a page and fills them with credentials.
+ * After login, captures the browser storage state (cookies + localStorage)
+ * for re-use in subsequent scans.
+ *
+ * Detection strategy:
+ * 1. Find forms with a password input (strongest signal)
+ * 2. Find username field via heuristics (name, id, autocomplete, type)
+ * 3. Find submit button
+ * 4. Fall back to custom selectors from credentials
+ */
+
+interface LoginForm {
+    /** Username input selector */
+    usernameSelector: string;
+    /** Password input selector */
+    passwordSelector: string;
+    /** Submit button selector (may be null if not found) */
+    submitSelector: string | null;
+    /** Whether the form was detected automatically */
+    autoDetected: boolean;
+}
+interface LoginResult {
+    /** Whether login succeeded */
+    success: boolean;
+    /** Message for logging */
+    message: string;
+    /** Playwright storage state JSON (cookies + localStorage) */
+    storageState?: string;
+}
+/**
+ * Auto-detect a login form on the current page.
+ *
+ * Strategy:
+ * 1. Find `<form>` elements containing an `input[type="password"]`
+ * 2. Within that form, find the username field using heuristics
+ * 3. Find the submit button
+ *
+ * Falls back to page-wide search if no enclosing <form> is found.
+ */
+declare function detectLoginForm(page: Page): Promise<LoginForm | null>;
+/**
+ * Perform login using detected form or custom selectors.
+ *
+ * Flow:
+ * 1. Navigate to login URL (or target URL)
+ * 2. Detect login form (or use custom selectors from credentials)
+ * 3. Fill username + password
+ * 4. Submit form
+ * 5. Wait for navigation
+ * 6. Check for logged-in indicator
+ * 7. Capture storage state
+ */
+declare function performLogin(page: Page, context: BrowserContext, credentials: FormCredentials, options: {
+    targetUrl: string;
+    loggedInIndicator?: string;
+    loggedOutIndicator?: string;
+}): Promise<LoginResult>;
+/**
+ * Check if the current session is still alive.
+ *
+ * Used during long-running scans to detect session expiry
+ * and trigger re-authentication.
  */
-declare function crawlAndBuildSessions(config: BrowserCrawlConfig, options?: CrawlOptions): Promise<Session[]>;
+declare function checkSessionAlive(page: Page, config: {
+    loggedInIndicator?: string;
+    loggedOutIndicator?: string;
+}): Promise<boolean>;
 
 /**
  * @vulcn/driver-browser
@@ -334,4 +492,4 @@ type BrowserStep = z.infer<typeof BrowserStepSchema>;
  */
 declare const browserDriver: VulcnDriver;
 
-export { BROWSER_STEP_TYPES, type BrowserConfig, BrowserRecorder, BrowserRunner, type BrowserStep, BrowserStepSchema, type BrowserStepType, checkBrowsers, configSchema, crawlAndBuildSessions, browserDriver as default, installBrowsers, launchBrowser };
+export { BROWSER_STEP_TYPES, type BrowserConfig, BrowserRecorder, BrowserRunner, type BrowserStep, BrowserStepSchema, type BrowserStepType, type CrawlResult, type HttpScanOptions, type HttpScanResult, type LoginForm, type LoginResult, type ReflectedRequest, buildCapturedRequests, checkBrowsers, checkSessionAlive, configSchema, crawlAndBuildSessions, browserDriver as default, detectLoginForm, httpScan, installBrowsers, launchBrowser, performLogin };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { RecordOptions, RecordingHandle, Session, RunContext, RunResult, CrawlOptions, VulcnDriver } from '@vulcn/engine';
-import { Browser } from 'playwright';
+import { RecordOptions, RecordingHandle, Session, RunContext, RunResult, CapturedRequest, CrawlOptions, Finding, PayloadCategory, RuntimePayload, FormCredentials, VulcnDriver } from '@vulcn/engine';
+import { Browser, Page, BrowserContext } from 'playwright';
 
 /**
  * Browser Recorder Implementation
@@ -32,33 +32,31 @@ declare class BrowserRecorder {
  *
  * Replays browser sessions with security payloads.
  * Uses plugin hooks for detection.
+ *
+ * v2: Persistent browser with in-page payload cycling.
+ *   - ONE browser for the entire scan (not per-session)
+ *   - Uses page.goBack() between payloads instead of full page.goto()
+ *   - Falls back to full navigation when goBack() fails
+ *   - 5-10x faster on SPAs, same speed on simple sites
  */
 
 /**
  * Browser Runner - replays sessions with payloads
+ *
+ * Supports two modes:
+ * 1. Self-managed browser: launches its own browser (backward compat)
+ * 2. Shared browser: receives a browser instance via RunOptions
+ *
+ * In both modes, payload cycling uses goBack() for speed.
  */
 declare class BrowserRunner {
     /**
-     * Execute a session with security payloads
-     */
-    static execute(session: Session, ctx: RunContext): Promise<RunResult>;
-    /**
-     * Replay session steps with payload injected at target step
+     * Execute a session with security payloads.
      *
-     * IMPORTANT: We replay ALL steps, not just up to the injectable step.
-     * The injection replaces the input value, but subsequent steps (like
-     * clicking submit) must still execute so the payload reaches the server
-     * and gets reflected back in the response.
+     * If ctx.options.browser is provided, reuses that browser (persistent mode).
+     * Otherwise, launches and closes its own browser (standalone mode).
      */
-    private static replayWithPayload;
-    /**
-     * Check for payload reflection in page content
-     */
-    private static checkReflection;
-    /**
-     * Determine severity based on vulnerability category
-     */
-    private static getSeverity;
+    static execute(session: Session, ctx: RunContext): Promise<RunResult>;
 }
 
 /**
@@ -105,6 +103,7 @@ declare function checkBrowsers(): Promise<{
  * - Links to follow for deeper crawling
  *
  * Outputs Session[] that are directly compatible with BrowserRunner.
+ * Also generates CapturedRequest[] metadata for Tier 1 HTTP fast scanning.
  *
  * This is the "auto-record" mode — instead of a human clicking around,
  * the crawler automatically discovers injection points.
@@ -123,12 +122,171 @@ interface BrowserCrawlConfig {
         height: number;
     };
 }
+/** Result from crawling — sessions for browser replay + requests for HTTP scanning */
+interface CrawlResult {
+    sessions: Session[];
+    capturedRequests: CapturedRequest[];
+}
 /**
  * Crawl a URL and generate sessions.
  *
  * This is called by the browser driver's recorder.crawl() method.
+ * Returns both Session[] for Tier 2 browser replay and
+ * CapturedRequest[] for Tier 1 HTTP fast scanning.
+ */
+declare function crawlAndBuildSessions(config: BrowserCrawlConfig, options?: CrawlOptions): Promise<CrawlResult>;
+
+/**
+ * HTTP Scanner — Tier 1 Fast Scan
+ *
+ * Replays captured HTTP requests via fetch() instead of Playwright.
+ * Substitutes security payloads into injectable form fields and checks
+ * the response body for payload reflection or error patterns.
+ *
+ * Speed: ~50ms per payload (vs 2-5s for browser replay)
+ *
+ * Catches:
+ *   - Reflected XSS (payload appears in response body)
+ *   - Error-based SQLi (SQL error patterns in response)
+ *   - Server-side reflection of any payload
+ *
+ * Misses:
+ *   - DOM-based XSS (requires JS execution)
+ *   - Client-side state bugs
+ *   - CSP-blocked attacks
+ *
+ * When reflection IS found, the finding is marked as `needsBrowserConfirmation`
+ * so the caller can escalate to Tier 2 for execution-based proof.
+ */
+
+interface HttpScanResult {
+    /** Total HTTP requests sent */
+    requestsSent: number;
+    /** How long the scan took (ms) */
+    duration: number;
+    /** Findings from reflection detection */
+    findings: Finding[];
+    /** Requests where reflection was found — should be escalated to Tier 2 */
+    reflectedRequests: ReflectedRequest[];
+}
+interface ReflectedRequest {
+    /** Original captured request */
+    request: CapturedRequest;
+    /** Payload that caused reflection */
+    payload: string;
+    /** Category of the payload */
+    category: PayloadCategory;
+}
+interface HttpScanOptions {
+    /** Request timeout in ms (default: 10000) */
+    timeout?: number;
+    /** Max concurrent requests (default: 10) */
+    concurrency?: number;
+    /** Cookie header to send with requests (for auth) */
+    cookies?: string;
+    /** Extra headers to send */
+    headers?: Record<string, string>;
+    /** Callback for progress reporting */
+    onProgress?: (completed: number, total: number) => void;
+}
+/**
+ * Run Tier 1 HTTP-level scan on captured requests.
+ *
+ * For each CapturedRequest × each payload:
+ *   1. Substitute the payload into the injectable field
+ *   2. Send via fetch()
+ *   3. Check response body for reflection patterns
+ *   4. If reflected, add finding + mark for Tier 2 escalation
+ */
+declare function httpScan(requests: CapturedRequest[], payloads: RuntimePayload[], options?: HttpScanOptions): Promise<HttpScanResult>;
+/**
+ * Convert discovered forms into CapturedRequest metadata.
+ *
+ * Called by the crawler after form discovery. Each injectable form
+ * produces one CapturedRequest per injectable input field.
+ */
+declare function buildCapturedRequests(forms: Array<{
+    pageUrl: string;
+    action: string;
+    method: string;
+    inputs: Array<{
+        name: string;
+        injectable: boolean;
+        type: string;
+    }>;
+    sessionName: string;
+}>): CapturedRequest[];
+
+/**
+ * Login Form Auto-Detection & Auth Replay
+ *
+ * Detects login forms on a page and fills them with credentials.
+ * After login, captures the browser storage state (cookies + localStorage)
+ * for re-use in subsequent scans.
+ *
+ * Detection strategy:
+ * 1. Find forms with a password input (strongest signal)
+ * 2. Find username field via heuristics (name, id, autocomplete, type)
+ * 3. Find submit button
+ * 4. Fall back to custom selectors from credentials
+ */
+
+interface LoginForm {
+    /** Username input selector */
+    usernameSelector: string;
+    /** Password input selector */
+    passwordSelector: string;
+    /** Submit button selector (may be null if not found) */
+    submitSelector: string | null;
+    /** Whether the form was detected automatically */
+    autoDetected: boolean;
+}
+interface LoginResult {
+    /** Whether login succeeded */
+    success: boolean;
+    /** Message for logging */
+    message: string;
+    /** Playwright storage state JSON (cookies + localStorage) */
+    storageState?: string;
+}
+/**
+ * Auto-detect a login form on the current page.
+ *
+ * Strategy:
+ * 1. Find `<form>` elements containing an `input[type="password"]`
+ * 2. Within that form, find the username field using heuristics
+ * 3. Find the submit button
+ *
+ * Falls back to page-wide search if no enclosing <form> is found.
+ */
+declare function detectLoginForm(page: Page): Promise<LoginForm | null>;
+/**
+ * Perform login using detected form or custom selectors.
+ *
+ * Flow:
+ * 1. Navigate to login URL (or target URL)
+ * 2. Detect login form (or use custom selectors from credentials)
+ * 3. Fill username + password
+ * 4. Submit form
+ * 5. Wait for navigation
+ * 6. Check for logged-in indicator
+ * 7. Capture storage state
+ */
+declare function performLogin(page: Page, context: BrowserContext, credentials: FormCredentials, options: {
+    targetUrl: string;
+    loggedInIndicator?: string;
+    loggedOutIndicator?: string;
+}): Promise<LoginResult>;
+/**
+ * Check if the current session is still alive.
+ *
+ * Used during long-running scans to detect session expiry
+ * and trigger re-authentication.
  */
-declare function crawlAndBuildSessions(config: BrowserCrawlConfig, options?: CrawlOptions): Promise<Session[]>;
+declare function checkSessionAlive(page: Page, config: {
+    loggedInIndicator?: string;
+    loggedOutIndicator?: string;
+}): Promise<boolean>;
 
 /**
  * @vulcn/driver-browser
@@ -334,4 +492,4 @@ type BrowserStep = z.infer<typeof BrowserStepSchema>;
  */
 declare const browserDriver: VulcnDriver;
 
-export { BROWSER_STEP_TYPES, type BrowserConfig, BrowserRecorder, BrowserRunner, type BrowserStep, BrowserStepSchema, type BrowserStepType, checkBrowsers, configSchema, crawlAndBuildSessions, browserDriver as default, installBrowsers, launchBrowser };
+export { BROWSER_STEP_TYPES, type BrowserConfig, BrowserRecorder, BrowserRunner, type BrowserStep, BrowserStepSchema, type BrowserStepType, type CrawlResult, type HttpScanOptions, type HttpScanResult, type LoginForm, type LoginResult, type ReflectedRequest, buildCapturedRequests, checkBrowsers, checkSessionAlive, configSchema, crawlAndBuildSessions, browserDriver as default, detectLoginForm, httpScan, installBrowsers, launchBrowser, performLogin };