@vulcn/engine 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -124,6 +124,10 @@ interface PluginHooks {
     onRecordStep?: (step: Step, ctx: RecordContext) => Promise<Step>;
     /** Called when recording ends, can transform session */
     onRecordEnd?: (session: Session, ctx: RecordContext) => Promise<Session>;
+    /** Called once when a scan starts (before any session is executed) */
+    onScanStart?: (ctx: ScanContext) => Promise<void>;
+    /** Called once when a scan ends (after all sessions have executed) */
+    onScanEnd?: (result: RunResult, ctx: ScanContext) => Promise<RunResult>;
     /** Called when run starts */
     onRunStart?: (ctx: RunContext$1) => Promise<void>;
     /** Called before each payload is injected, can transform payload */
@@ -206,6 +210,17 @@ interface RunContext$1 extends PluginContext {
     /** Whether running headless */
     headless: boolean;
 }
+/**
+ * Context for scan-level hooks (wraps all sessions)
+ */
+interface ScanContext extends PluginContext {
+    /** All sessions in this scan */
+    sessions: Session[];
+    /** Whether running headless */
+    headless: boolean;
+    /** Total sessions count */
+    sessionCount: number;
+}
 /**
  * Context for detection hooks
  */
@@ -450,6 +465,8 @@ interface CrawlOptions {
     pageTimeout?: number;
     /** Only crawl pages under the same origin (default: true) */
     sameOrigin?: boolean;
+    /** Playwright storage state JSON for authenticated crawling */
+    storageState?: string;
     /** Callback when a page is crawled */
     onPageCrawled?: (url: string, formsFound: number) => void;
 }
@@ -655,6 +672,23 @@ declare class DriverManager {
      * via the onPageReady callback, ensuring plugins get a real page object.
      */
     execute(session: Session, pluginManager: PluginManager, options?: RunOptions): Promise<RunResult>;
+    /**
+     * Execute multiple sessions with a shared browser (scan-level orchestration).
+     *
+     * This is the preferred entry point for running a full scan. It:
+     * 1. Launches ONE browser for the entire scan
+     * 2. Passes the browser to each session's runner via options.browser
+     * 3. Each session creates its own context (lightweight, isolated cookies)
+     * 4. Aggregates results across all sessions
+     * 5. Closes the browser once at the end
+     *
+     * This is 5-10x faster than calling execute() per session because
+     * launching a browser takes 2-3 seconds.
+     */
+    executeScan(sessions: Session[], pluginManager: PluginManager, options?: RunOptions): Promise<{
+        results: RunResult[];
+        aggregate: RunResult;
+    }>;
     /**
      * Validate driver structure
      */
@@ -669,4 +703,215 @@ declare class DriverManager {
  */
 declare const driverManager: DriverManager;
 
-export { type CrawlOptions, type CustomPayload, type CustomPayloadFile, DRIVER_API_VERSION, type DetectContext, type DriverLogger, DriverManager, type DriverSource, type EngineInfo, type Finding, type LoadedDriver, type LoadedPlugin as LoadedPluginInfo, PLUGIN_API_VERSION, type PayloadCategory, type PayloadSource, type PluginConfig, type PluginContext, type PluginHooks, type PluginLogger, PluginManager, type RunContext$1 as PluginRunContext, type PluginSource, type RecordContext, type RecordOptions, type RecorderDriver, type RecordingHandle, type RunContext, type RunOptions, type RunResult, type RunnerDriver, type RuntimePayload, type Session, type Step, type VulcnConfig, type VulcnDriver, type VulcnPlugin, driverManager, pluginManager };
+/**
+ * Vulcn Auth Module
+ *
+ * Handles credential encryption/decryption and auth state management.
+ *
+ * Security:
+ * - AES-256-GCM encryption for credentials at rest
+ * - PBKDF2 key derivation from passphrase
+ * - Reads passphrase from VULCN_KEY env var (CI/CD) or interactive prompt
+ * - Auth state (cookies, localStorage) encrypted separately
+ */
+/** Form-based login credentials */
+interface FormCredentials {
+    type: "form";
+    username: string;
+    password: string;
+    /** Custom login URL (if different from target) */
+    loginUrl?: string;
+    /** Custom CSS selector for username field */
+    userSelector?: string;
+    /** Custom CSS selector for password field */
+    passSelector?: string;
+}
+/** Header-based authentication (API keys, Bearer tokens) */
+interface HeaderCredentials {
+    type: "header";
+    headers: Record<string, string>;
+}
+/** All credential types */
+type Credentials = FormCredentials | HeaderCredentials;
+/** Auth configuration for a scan */
+interface AuthConfig {
+    /** Auth strategy */
+    strategy: "storage-state" | "header";
+    /** Login page URL */
+    loginUrl?: string;
+    /** Text that appears when logged in (e.g., "Logout") */
+    loggedInIndicator?: string;
+    /** Text that appears when logged out (e.g., "Sign In") */
+    loggedOutIndicator?: string;
+    /** Session expiry detection rules */
+    sessionExpiry?: {
+        /** HTTP status codes that indicate session expired */
+        statusCodes?: number[];
+        /** URL pattern that indicates redirect to login */
+        redirectPattern?: string;
+        /** Page content that indicates session expired */
+        pageContent?: string;
+    };
+}
+/**
+ * Encrypt data with AES-256-GCM.
+ *
+ * @param data - Plaintext data to encrypt
+ * @param passphrase - Passphrase for key derivation
+ * @returns JSON string of EncryptedData
+ */
+declare function encrypt(data: string, passphrase: string): string;
+/**
+ * Decrypt data encrypted with encrypt().
+ *
+ * @param encrypted - JSON string from encrypt()
+ * @param passphrase - Passphrase used during encryption
+ * @returns Decrypted plaintext
+ * @throws Error if passphrase is wrong or data is tampered
+ */
+declare function decrypt(encrypted: string, passphrase: string): string;
+/**
+ * Encrypt credentials to a storable string.
+ */
+declare function encryptCredentials(credentials: Credentials, passphrase: string): string;
+/**
+ * Decrypt credentials from a stored string.
+ */
+declare function decryptCredentials(encrypted: string, passphrase: string): Credentials;
+/**
+ * Encrypt browser storage state (cookies, localStorage, etc.).
+ * The state is the JSON output from Playwright's context.storageState().
+ */
+declare function encryptStorageState(storageState: string, passphrase: string): string;
+/**
+ * Decrypt browser storage state.
+ */
+declare function decryptStorageState(encrypted: string, passphrase: string): string;
+/**
+ * Get passphrase from environment or throw.
+ *
+ * In CI/CD, set VULCN_KEY env var.
+ * In interactive mode, the CLI should prompt and pass the value here.
+ */
+declare function getPassphrase(interactive?: string): string;
+
+/**
+ * Vulcn Session Format v2
+ *
+ * Directory-based session format: `.vulcn/` or `<name>.vulcn/`
+ *
+ * Structure:
+ *   manifest.yml          - scan config, session list, auth config
+ *   auth/config.yml       - login strategy, indicators
+ *   auth/state.enc        - encrypted storageState (cookies/localStorage)
+ *   sessions/*.yml        - individual session files (one per form)
+ *   requests/*.json       - captured HTTP metadata (for Tier 1 fast scan)
+ */
+
+/** Manifest file schema (manifest.yml) */
+interface ScanManifest {
+    /** Format version */
+    version: "2";
+    /** Human-readable scan name */
+    name: string;
+    /** Target URL */
+    target: string;
+    /** When the scan was recorded */
+    recordedAt: string;
+    /** Driver name */
+    driver: string;
+    /** Driver configuration */
+    driverConfig: Record<string, unknown>;
+    /** Auth configuration (optional) */
+    auth?: {
+        strategy: string;
+        configFile?: string;
+        stateFile?: string;
+        loggedInIndicator?: string;
+        loggedOutIndicator?: string;
+        reAuthOn?: Array<Record<string, unknown>>;
+    };
+    /** Session file references */
+    sessions: SessionRef[];
+    /** Scan configuration */
+    scan?: {
+        tier?: "auto" | "http-only" | "browser-only";
+        parallel?: number;
+        timeout?: number;
+    };
+}
+/** Reference to a session file within the manifest */
+interface SessionRef {
+    /** Relative path to session file */
+    file: string;
+    /** Whether this session has injectable inputs */
+    injectable?: boolean;
+}
+/** HTTP request metadata for Tier 1 fast scanning */
+interface CapturedRequest {
+    /** Request method */
+    method: string;
+    /** Full URL */
+    url: string;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Form data (for POST) */
+    body?: string;
+    /** Content type */
+    contentType?: string;
+    /** Which form field is injectable */
+    injectableField?: string;
+    /** Session name this request belongs to */
+    sessionName: string;
+}
+/**
+ * Load a v2 session directory into Session[] ready for execution.
+ *
+ * @param dirPath - Path to the .vulcn/ directory
+ * @returns Array of sessions with manifest metadata attached
+ */
+declare function loadSessionDir(dirPath: string): Promise<{
+    manifest: ScanManifest;
+    sessions: Session[];
+    authConfig?: AuthConfig;
+}>;
+/**
+ * Check if a path is a v2 session directory.
+ */
+declare function isSessionDir(path: string): boolean;
+/**
+ * Check if a path looks like a v2 session directory (by extension).
+ */
+declare function looksLikeSessionDir(path: string): boolean;
+/**
+ * Save sessions to a v2 session directory.
+ *
+ * Creates the directory structure:
+ *   <dirPath>/
+ *   ├── manifest.yml
+ *   ├── sessions/
+ *   │   ├── <session-name>.yml
+ *   │   └── ...
+ *   └── requests/   (if HTTP metadata provided)
+ *       └── ...
+ */
+declare function saveSessionDir(dirPath: string, options: {
+    name: string;
+    target: string;
+    driver: string;
+    driverConfig: Record<string, unknown>;
+    sessions: Session[];
+    authConfig?: AuthConfig;
+    encryptedState?: string;
+    requests?: CapturedRequest[];
+}): Promise<void>;
+/**
+ * Read encrypted auth state from a session directory.
+ */
+declare function readAuthState(dirPath: string): Promise<string | null>;
+/**
+ * Read captured HTTP requests from a session directory.
+ */
+declare function readCapturedRequests(dirPath: string): Promise<CapturedRequest[]>;
+
+export { type AuthConfig, type CapturedRequest, type CrawlOptions, type Credentials, type CustomPayload, type CustomPayloadFile, DRIVER_API_VERSION, type DetectContext, type DriverLogger, DriverManager, type DriverSource, type EngineInfo, type Finding, type FormCredentials, type HeaderCredentials, type LoadedDriver, type LoadedPlugin as LoadedPluginInfo, PLUGIN_API_VERSION, type PayloadCategory, type PayloadSource, type PluginConfig, type PluginContext, type PluginHooks, type PluginLogger, PluginManager, type RunContext$1 as PluginRunContext, type PluginSource, type RecordContext, type RecordOptions, type RecorderDriver, type RecordingHandle, type RunContext, type RunOptions, type RunResult, type RunnerDriver, type RuntimePayload, type ScanContext, type ScanManifest, type Session, type SessionRef, type Step, type VulcnConfig, type VulcnDriver, type VulcnPlugin, decrypt, decryptCredentials, decryptStorageState, driverManager, encrypt, encryptCredentials, encryptStorageState, getPassphrase, isSessionDir, loadSessionDir, looksLikeSessionDir, pluginManager, readAuthState, readCapturedRequests, saveSessionDir };

package/dist/index.js

@@ -243,6 +243,109 @@ var DriverManager = class {
     }
     return result;
   }
+  /**
+   * Execute multiple sessions with a shared browser (scan-level orchestration).
+   *
+   * This is the preferred entry point for running a full scan. It:
+   * 1. Launches ONE browser for the entire scan
+   * 2. Passes the browser to each session's runner via options.browser
+   * 3. Each session creates its own context (lightweight, isolated cookies)
+   * 4. Aggregates results across all sessions
+   * 5. Closes the browser once at the end
+   *
+   * This is 5-10x faster than calling execute() per session because
+   * launching a browser takes 2-3 seconds.
+   */
+  async executeScan(sessions, pluginManager2, options = {}) {
+    if (sessions.length === 0) {
+      const empty = {
+        findings: [],
+        stepsExecuted: 0,
+        payloadsTested: 0,
+        duration: 0,
+        errors: ["No sessions to execute"]
+      };
+      return { results: [], aggregate: empty };
+    }
+    const startTime = Date.now();
+    const results = [];
+    const allFindings = [];
+    let totalSteps = 0;
+    let totalPayloads = 0;
+    const allErrors = [];
+    const firstDriver = this.getForSession(sessions[0]);
+    let sharedBrowser = null;
+    if (firstDriver.name === "browser") {
+      try {
+        const driverPkg = "@vulcn/driver-browser";
+        const { launchBrowser } = await import(
+          /* @vite-ignore */
+          driverPkg
+        );
+        const browserType = sessions[0].driverConfig.browser ?? "chromium";
+        const headless = options.headless ?? true;
+        const result = await launchBrowser({
+          browser: browserType,
+          headless
+        });
+        sharedBrowser = result.browser;
+      } catch {
+      }
+    }
+    try {
+      await pluginManager2.callHook("onScanStart", async (hook, ctx) => {
+        const scanCtx = {
+          ...ctx,
+          sessions,
+          headless: options.headless ?? true,
+          sessionCount: sessions.length
+        };
+        await hook(scanCtx);
+      });
+      for (const session of sessions) {
+        const sessionOptions = {
+          ...options,
+          ...sharedBrowser ? { browser: sharedBrowser } : {}
+        };
+        const result = await this.execute(
+          session,
+          pluginManager2,
+          sessionOptions
+        );
+        results.push(result);
+        allFindings.push(...result.findings);
+        totalSteps += result.stepsExecuted;
+        totalPayloads += result.payloadsTested;
+        allErrors.push(...result.errors);
+      }
+    } finally {
+      if (sharedBrowser && typeof sharedBrowser.close === "function") {
+        await sharedBrowser.close();
+      }
+    }
+    const aggregate = {
+      findings: allFindings,
+      stepsExecuted: totalSteps,
+      payloadsTested: totalPayloads,
+      duration: Date.now() - startTime,
+      errors: allErrors
+    };
+    let finalAggregate = aggregate;
+    finalAggregate = await pluginManager2.callHookPipe(
+      "onScanEnd",
+      finalAggregate,
+      async (hook, value, ctx) => {
+        const scanCtx = {
+          ...ctx,
+          sessions,
+          headless: options.headless ?? true,
+          sessionCount: sessions.length
+        };
+        return await hook(value, scanCtx);
+      }
+    );
+    return { results, aggregate: finalAggregate };
+  }
   /**
    * Validate driver structure
    */
@@ -616,12 +719,269 @@ var PluginManager = class {
   }
 };
 var pluginManager = new PluginManager();
+
+// src/auth.ts
+import {
+  randomBytes,
+  createCipheriv,
+  createDecipheriv,
+  pbkdf2Sync
+} from "crypto";
+var ALGORITHM = "aes-256-gcm";
+var KEY_LENGTH = 32;
+var IV_LENGTH = 16;
+var SALT_LENGTH = 32;
+var PBKDF2_ITERATIONS = 1e5;
+var PBKDF2_DIGEST = "sha512";
+function deriveKey(passphrase, salt) {
+  return pbkdf2Sync(
+    passphrase,
+    salt,
+    PBKDF2_ITERATIONS,
+    KEY_LENGTH,
+    PBKDF2_DIGEST
+  );
+}
+function encrypt(data, passphrase) {
+  const salt = randomBytes(SALT_LENGTH);
+  const iv = randomBytes(IV_LENGTH);
+  const key = deriveKey(passphrase, salt);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  let encrypted = cipher.update(data, "utf8", "hex");
+  encrypted += cipher.final("hex");
+  const tag = cipher.getAuthTag();
+  const payload = {
+    version: 1,
+    salt: salt.toString("hex"),
+    iv: iv.toString("hex"),
+    tag: tag.toString("hex"),
+    data: encrypted,
+    iterations: PBKDF2_ITERATIONS
+  };
+  return JSON.stringify(payload);
+}
+function decrypt(encrypted, passphrase) {
+  const payload = JSON.parse(encrypted);
+  if (payload.version !== 1) {
+    throw new Error(`Unsupported encryption version: ${payload.version}`);
+  }
+  const salt = Buffer.from(payload.salt, "hex");
+  const iv = Buffer.from(payload.iv, "hex");
+  const tag = Buffer.from(payload.tag, "hex");
+  const key = deriveKey(passphrase, salt);
+  const decipher = createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(tag);
+  let decrypted = decipher.update(payload.data, "hex", "utf8");
+  decrypted += decipher.final("utf8");
+  return decrypted;
+}
+function encryptCredentials(credentials, passphrase) {
+  return encrypt(JSON.stringify(credentials), passphrase);
+}
+function decryptCredentials(encrypted, passphrase) {
+  const json = decrypt(encrypted, passphrase);
+  return JSON.parse(json);
+}
+function encryptStorageState(storageState, passphrase) {
+  return encrypt(storageState, passphrase);
+}
+function decryptStorageState(encrypted, passphrase) {
+  return decrypt(encrypted, passphrase);
+}
+function getPassphrase(interactive) {
+  if (interactive) return interactive;
+  const envKey = process.env.VULCN_KEY;
+  if (envKey) return envKey;
+  throw new Error(
+    "No passphrase provided. Set VULCN_KEY environment variable or pass --passphrase."
+  );
+}
+
+// src/session.ts
+import { readFile as readFile2, writeFile, mkdir, readdir } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { join, basename } from "path";
+import { parse as parse2, stringify as stringify2 } from "yaml";
+async function loadSessionDir(dirPath) {
+  const manifestPath = join(dirPath, "manifest.yml");
+  if (!existsSync2(manifestPath)) {
+    throw new Error(
+      `No manifest.yml found in ${dirPath}. Is this a v2 session directory?`
+    );
+  }
+  const manifestYaml = await readFile2(manifestPath, "utf-8");
+  const manifest = parse2(manifestYaml);
+  if (manifest.version !== "2") {
+    throw new Error(
+      `Unsupported session format version: ${manifest.version}. Expected "2".`
+    );
+  }
+  let authConfig;
+  if (manifest.auth?.configFile) {
+    const authPath = join(dirPath, manifest.auth.configFile);
+    if (existsSync2(authPath)) {
+      const authYaml = await readFile2(authPath, "utf-8");
+      authConfig = parse2(authYaml);
+    }
+  }
+  const sessions = [];
+  for (const ref of manifest.sessions) {
+    if (ref.injectable === false) continue;
+    const sessionPath = join(dirPath, ref.file);
+    if (!existsSync2(sessionPath)) {
+      console.warn(`Session file not found: ${sessionPath}, skipping`);
+      continue;
+    }
+    const sessionYaml = await readFile2(sessionPath, "utf-8");
+    const sessionData = parse2(sessionYaml);
+    const session = {
+      name: sessionData.name ?? basename(ref.file, ".yml"),
+      driver: manifest.driver,
+      driverConfig: {
+        ...manifest.driverConfig,
+        startUrl: resolveUrl(
+          manifest.target,
+          sessionData.page
+        )
+      },
+      steps: sessionData.steps ?? [],
+      metadata: {
+        recordedAt: manifest.recordedAt,
+        version: "2",
+        manifestDir: dirPath
+      }
+    };
+    sessions.push(session);
+  }
+  return { manifest, sessions, authConfig };
+}
+function isSessionDir(path) {
+  return existsSync2(join(path, "manifest.yml"));
+}
+function looksLikeSessionDir(path) {
+  return path.endsWith(".vulcn") || path.endsWith(".vulcn/");
+}
+async function saveSessionDir(dirPath, options) {
+  await mkdir(join(dirPath, "sessions"), { recursive: true });
+  const sessionRefs = [];
+  for (const session of options.sessions) {
+    const safeName = slugify(session.name);
+    const fileName = `sessions/${safeName}.yml`;
+    const sessionPath = join(dirPath, fileName);
+    const startUrl = session.driverConfig.startUrl;
+    const page = startUrl ? startUrl.replace(options.target, "").replace(/^\//, "/") : void 0;
+    const sessionData = {
+      name: session.name,
+      ...page ? { page } : {},
+      steps: session.steps
+    };
+    await writeFile(sessionPath, stringify2(sessionData), "utf-8");
+    const hasInjectable = session.steps.some(
+      (s) => s.type === "browser.input" && s.injectable !== false
+    );
+    sessionRefs.push({
+      file: fileName,
+      injectable: hasInjectable
+    });
+  }
+  if (options.authConfig) {
+    await mkdir(join(dirPath, "auth"), { recursive: true });
+    await writeFile(
+      join(dirPath, "auth", "config.yml"),
+      stringify2(options.authConfig),
+      "utf-8"
+    );
+  }
+  if (options.encryptedState) {
+    await mkdir(join(dirPath, "auth"), { recursive: true });
+    await writeFile(
+      join(dirPath, "auth", "state.enc"),
+      options.encryptedState,
+      "utf-8"
+    );
+  }
+  if (options.requests && options.requests.length > 0) {
+    await mkdir(join(dirPath, "requests"), { recursive: true });
+    for (const req of options.requests) {
+      const safeName = slugify(req.sessionName);
+      await writeFile(
+        join(dirPath, "requests", `${safeName}.json`),
+        JSON.stringify(req, null, 2),
+        "utf-8"
+      );
+    }
+  }
+  const manifest = {
+    version: "2",
+    name: options.name,
+    target: options.target,
+    recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    driver: options.driver,
+    driverConfig: options.driverConfig,
+    ...options.authConfig ? {
+      auth: {
+        strategy: options.authConfig.strategy,
+        configFile: "auth/config.yml",
+        stateFile: options.encryptedState ? "auth/state.enc" : void 0,
+        loggedInIndicator: options.authConfig.loggedInIndicator,
+        loggedOutIndicator: options.authConfig.loggedOutIndicator
+      }
+    } : {},
+    sessions: sessionRefs,
+    scan: {
+      tier: "auto",
+      parallel: 1,
+      timeout: 12e4
+    }
+  };
+  await writeFile(join(dirPath, "manifest.yml"), stringify2(manifest), "utf-8");
+}
+async function readAuthState(dirPath) {
+  const statePath = join(dirPath, "auth", "state.enc");
+  if (!existsSync2(statePath)) return null;
+  return readFile2(statePath, "utf-8");
+}
+async function readCapturedRequests(dirPath) {
+  const requestsDir = join(dirPath, "requests");
+  if (!existsSync2(requestsDir)) return [];
+  const files = await readdir(requestsDir);
+  const requests = [];
+  for (const file of files) {
+    if (!file.endsWith(".json")) continue;
+    const content = await readFile2(join(requestsDir, file), "utf-8");
+    requests.push(JSON.parse(content));
+  }
+  return requests;
+}
+function resolveUrl(target, page) {
+  if (!page) return target;
+  if (page.startsWith("http")) return page;
+  const base = target.replace(/\/$/, "");
+  const path = page.startsWith("/") ? page : `/${page}`;
+  return `${base}${path}`;
+}
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+}
 export {
   DRIVER_API_VERSION,
   DriverManager,
   PLUGIN_API_VERSION,
   PluginManager,
+  decrypt,
+  decryptCredentials,
+  decryptStorageState,
   driverManager,
-  pluginManager
+  encrypt,
+  encryptCredentials,
+  encryptStorageState,
+  getPassphrase,
+  isSessionDir,
+  loadSessionDir,
+  looksLikeSessionDir,
+  pluginManager,
+  readAuthState,
+  readCapturedRequests,
+  saveSessionDir
 };
 //# sourceMappingURL=index.js.map