@vulcn/driver-browser 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { RecordOptions, RecordingHandle, Session, RunContext, RunResult, CrawlOptions, FormCredentials, VulcnDriver } from '@vulcn/engine';
+import { RecordOptions, RecordingHandle, Session, RunContext, RunResult, CapturedRequest, CrawlOptions, Finding, PayloadCategory, RuntimePayload, FormCredentials, VulcnDriver } from '@vulcn/engine';
 import { Browser, Page, BrowserContext } from 'playwright';
 
 /**
@@ -103,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.
@@ -121,12 +122,100 @@ 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<Session[]>;
+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
@@ -403,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, type LoginForm, type LoginResult, checkBrowsers, checkSessionAlive, configSchema, crawlAndBuildSessions, browserDriver as default, detectLoginForm, installBrowsers, launchBrowser, performLogin };
+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,5 +1,5 @@
 import { z } from 'zod';
-import { RecordOptions, RecordingHandle, Session, RunContext, RunResult, CrawlOptions, FormCredentials, VulcnDriver } from '@vulcn/engine';
+import { RecordOptions, RecordingHandle, Session, RunContext, RunResult, CapturedRequest, CrawlOptions, Finding, PayloadCategory, RuntimePayload, FormCredentials, VulcnDriver } from '@vulcn/engine';
 import { Browser, Page, BrowserContext } from 'playwright';
 
 /**
@@ -103,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.
@@ -121,12 +122,100 @@ 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<Session[]>;
+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
@@ -403,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, type LoginForm, type LoginResult, checkBrowsers, checkSessionAlive, configSchema, crawlAndBuildSessions, browserDriver as default, detectLoginForm, installBrowsers, launchBrowser, performLogin };
+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.js

@@ -778,6 +778,248 @@ function interleavePayloads(payloads) {
   return result;
 }
 
+// src/http-scanner.ts
+async function httpScan(requests, payloads, options = {}) {
+  const timeout = options.timeout ?? 1e4;
+  const concurrency = options.concurrency ?? 10;
+  const start = Date.now();
+  const findings = [];
+  const reflectedRequests = [];
+  let requestsSent = 0;
+  const tasks = [];
+  for (const request of requests) {
+    if (!request.injectableField) continue;
+    for (const payloadSet of payloads) {
+      for (const value of payloadSet.payloads) {
+        tasks.push({ request, payloadSet, value });
+      }
+    }
+  }
+  const totalTasks = tasks.length;
+  if (totalTasks === 0) {
+    return { requestsSent: 0, duration: 0, findings, reflectedRequests };
+  }
+  for (let i = 0; i < tasks.length; i += concurrency) {
+    const batch = tasks.slice(i, i + concurrency);
+    const results = await Promise.allSettled(
+      batch.map(async ({ request, payloadSet, value }) => {
+        try {
+          const body = await sendPayload(request, value, {
+            timeout,
+            cookies: options.cookies,
+            headers: options.headers
+          });
+          requestsSent++;
+          const finding = checkHttpReflection(body, request, payloadSet, value);
+          if (finding) {
+            findings.push(finding);
+            reflectedRequests.push({
+              request,
+              payload: value,
+              category: payloadSet.category
+            });
+          }
+        } catch {
+          requestsSent++;
+        }
+      })
+    );
+    const completed = Math.min(i + batch.length, totalTasks);
+    options.onProgress?.(completed, totalTasks);
+    for (const result of results) {
+      if (result.status === "rejected") {
+      }
+    }
+  }
+  return {
+    requestsSent,
+    duration: Date.now() - start,
+    findings,
+    reflectedRequests
+  };
+}
+async function sendPayload(request, payload, options) {
+  const { method, url, headers, body, contentType, injectableField } = request;
+  const reqHeaders = {
+    ...headers,
+    ...options.headers ?? {}
+  };
+  if (options.cookies) {
+    reqHeaders["Cookie"] = options.cookies;
+  }
+  delete reqHeaders["content-length"];
+  delete reqHeaders["Content-Length"];
+  let requestUrl = url;
+  let requestBody;
+  if (method.toUpperCase() === "GET") {
+    requestUrl = injectIntoUrl(url, injectableField, payload);
+  } else {
+    requestBody = injectIntoBody(body, contentType, injectableField, payload);
+    if (contentType) {
+      reqHeaders["Content-Type"] = contentType;
+    } else {
+      reqHeaders["Content-Type"] = "application/x-www-form-urlencoded";
+    }
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeout);
+  try {
+    const response = await fetch(requestUrl, {
+      method: method.toUpperCase(),
+      headers: reqHeaders,
+      body: requestBody,
+      signal: controller.signal,
+      redirect: "follow"
+    });
+    return await response.text();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function injectIntoUrl(url, field, payload) {
+  try {
+    const parsed = new URL(url);
+    parsed.searchParams.set(field, payload);
+    return parsed.toString();
+  } catch {
+    const separator = url.includes("?") ? "&" : "?";
+    return `${url}${separator}${encodeURIComponent(field)}=${encodeURIComponent(payload)}`;
+  }
+}
+function injectIntoBody(body, contentType, field, payload) {
+  if (!body) {
+    return `${encodeURIComponent(field)}=${encodeURIComponent(payload)}`;
+  }
+  const ct = (contentType ?? "").toLowerCase();
+  if (ct.includes("application/json")) {
+    return injectIntoJson(body, field, payload);
+  }
+  if (ct.includes("multipart/form-data")) {
+    return injectIntoMultipart(body, field, payload);
+  }
+  return injectIntoFormUrlEncoded(body, field, payload);
+}
+function injectIntoFormUrlEncoded(body, field, payload) {
+  const params = new URLSearchParams(body);
+  params.set(field, payload);
+  return params.toString();
+}
+function injectIntoJson(body, field, payload) {
+  try {
+    const parsed = JSON.parse(body);
+    if (typeof parsed === "object" && parsed !== null) {
+      parsed[field] = payload;
+      return JSON.stringify(parsed);
+    }
+  } catch {
+  }
+  const escaped = field.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const regex = new RegExp(`("${escaped}"\\s*:\\s*)"[^"]*"`, "g");
+  const replaced = body.replace(regex, `$1"${payload}"`);
+  if (replaced !== body) return replaced;
+  return body;
+}
+function injectIntoMultipart(body, field, payload) {
+  const escaped = field.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const regex = new RegExp(
+    `(Content-Disposition:\\s*form-data;\\s*name="${escaped}"\\r?\\n\\r?\\n)[^\\r\\n-]*`,
+    "i"
+  );
+  return body.replace(regex, `$1${payload}`);
+}
+function checkHttpReflection(responseBody, request, payloadSet, payloadValue) {
+  for (const pattern of payloadSet.detectPatterns) {
+    if (pattern.test(responseBody)) {
+      return {
+        type: payloadSet.category,
+        severity: getSeverity2(payloadSet.category),
+        title: `${payloadSet.category.toUpperCase()} reflection detected (HTTP)`,
+        description: `Payload pattern was reflected in HTTP response body. Needs browser confirmation for execution proof.`,
+        stepId: `http-${request.sessionName}`,
+        payload: payloadValue,
+        url: request.url,
+        evidence: responseBody.match(pattern)?.[0]?.slice(0, 200),
+        metadata: {
+          detectionMethod: "tier1-http",
+          needsBrowserConfirmation: true,
+          requestMethod: request.method,
+          injectableField: request.injectableField
+        }
+      };
+    }
+  }
+  if (responseBody.includes(payloadValue)) {
+    return {
+      type: payloadSet.category,
+      severity: "medium",
+      title: `Potential ${payloadSet.category.toUpperCase()} \u2014 payload reflected in HTTP response`,
+      description: `Payload was reflected in HTTP response without encoding. Escalate to browser for execution proof.`,
+      stepId: `http-${request.sessionName}`,
+      payload: payloadValue,
+      url: request.url,
+      metadata: {
+        detectionMethod: "tier1-http",
+        needsBrowserConfirmation: true,
+        requestMethod: request.method,
+        injectableField: request.injectableField
+      }
+    };
+  }
+  return void 0;
+}
+function getSeverity2(category) {
+  switch (category) {
+    case "sqli":
+    case "command-injection":
+    case "xxe":
+      return "critical";
+    case "xss":
+    case "ssrf":
+    case "path-traversal":
+      return "high";
+    case "open-redirect":
+      return "medium";
+    default:
+      return "medium";
+  }
+}
+function buildCapturedRequests(forms) {
+  const requests = [];
+  for (const form of forms) {
+    const injectableInputs = form.inputs.filter((i) => i.injectable);
+    if (injectableInputs.length === 0) continue;
+    let actionUrl;
+    try {
+      actionUrl = new URL(form.action, form.pageUrl).toString();
+    } catch {
+      actionUrl = form.pageUrl;
+    }
+    const method = (form.method || "GET").toUpperCase();
+    for (const input of injectableInputs) {
+      const formParams = new URLSearchParams();
+      for (const inp of form.inputs) {
+        formParams.set(inp.name || inp.type, inp.injectable ? "test" : "");
+      }
+      const request = {
+        method,
+        url: method === "GET" ? actionUrl : actionUrl,
+        headers: {
+          "User-Agent": "Vulcn/1.0 (Security Scanner)",
+          Accept: "text/html,application/xhtml+xml,*/*"
+        },
+        ...method !== "GET" ? {
+          body: formParams.toString(),
+          contentType: "application/x-www-form-urlencoded"
+        } : {},
+        injectableField: input.name || input.type,
+        sessionName: form.sessionName
+      };
+      requests.push(request);
+    }
+  }
+  return requests;
+}
+
 // src/crawler.ts
 var INJECTABLE_INPUT_TYPES = /* @__PURE__ */ new Set([
   "text",
@@ -864,7 +1106,20 @@ async function crawlAndBuildSessions(config, options = {}) {
   console.log(
     `[crawler] Complete: ${visited.size} page(s), ${allForms.length} form(s)`
   );
-  return buildSessions(allForms);
+  const sessions = buildSessions(allForms);
+  const capturedRequests = buildCapturedRequests(
+    allForms.filter((f) => f.inputs.some((i) => i.injectable)).map((form, idx) => ({
+      pageUrl: form.pageUrl,
+      action: form.action,
+      method: form.method,
+      inputs: form.inputs,
+      sessionName: sessions[idx]?.name ?? `form-${idx + 1}`
+    }))
+  );
+  console.log(
+    `[crawler] Generated ${sessions.length} session(s), ${capturedRequests.length} HTTP request(s) for Tier 1`
+  );
+  return { sessions, capturedRequests };
 }
 async function discoverForms(page, pageUrl) {
   const forms = [];
@@ -1377,7 +1632,7 @@ var recorderDriver = {
   },
   async crawl(config, options) {
     const parsedConfig = configSchema.parse(config);
-    return crawlAndBuildSessions(
+    const result = await crawlAndBuildSessions(
       {
         startUrl: parsedConfig.startUrl ?? "",
         browser: parsedConfig.browser,
@@ -1386,6 +1641,7 @@ var recorderDriver = {
       },
       options
     );
+    return result.sessions;
   }
 };
 var runnerDriver = {
@@ -1409,12 +1665,14 @@ export {
   BrowserRecorder,
   BrowserRunner,
   BrowserStepSchema,
+  buildCapturedRequests,
   checkBrowsers,
   checkSessionAlive,
   configSchema,
   crawlAndBuildSessions,
   index_default as default,
   detectLoginForm,
+  httpScan,
   installBrowsers,
   launchBrowser,
   performLogin