@vulcn/engine 0.5.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.8.0
+
+### Minor Changes
+
+- 15d8504: ### Authenticated Scanning
+
+  End-to-end support for scanning applications behind login pages.
+
+  #### `@vulcn/engine`
+  - **Credential encryption module** (`src/auth.ts`): AES-256-GCM encryption/decryption for credentials and Playwright storage state, with PBKDF2 key derivation (600k iterations)
+  - **Auth types**: `FormCredentials`, `HeaderCredentials`, `AuthConfig` with session expiry detection config
+  - **Scan-level hooks**: `onScanStart` / `onScanEnd` — fire once per scan wrapping all sessions, with `ScanContext` providing full session list and scan metadata
+  - **`onScanEnd` result transformation**: uses `callHookPipe` so plugins can transform the aggregate `RunResult` (e.g. deduplication, risk scoring)
+  - **v2 session format**: `.vulcn/` directory structure with manifest, encrypted auth state, and config alongside session files
+  - **`CrawlOptions.storageState`**: pass authenticated browser state (cookies + localStorage) to the crawler
+  - **New exports**: `ScanContext`, `encryptCredentials`, `decryptCredentials`, `encryptStorageState`, `decryptStorageState`, `getPassphrase`
+
+  #### `@vulcn/driver-browser`
+  - **Authenticated crawling**: `crawlAndBuildSessions` accepts `storageState` via `CrawlOptions` and injects it into the Playwright browser context
+  - **Authenticated scanning**: `BrowserRunner` reads `storageState` from `RunOptions` and applies it to the scanner's browser context
+  - **Login form auto-detection**: `performLogin` navigates to the login URL, auto-detects username/password fields, fills credentials, and submits
+  - **Storage state capture**: after successful login, captures full browser storage state (cookies, localStorage, sessionStorage)
+
+  #### `vulcn` (CLI)
+  - **`vulcn store`**: new command to encrypt and save credentials (form-based or header-based) to `.vulcn/auth.enc`
+  - **`vulcn crawl --creds`**: decrypt credentials → perform login → capture storage state → crawl all authenticated pages
+  - **`vulcn run --creds`**: decrypt credentials → perform login → inject storage state into scanner browser context → run all payloads authenticated
+  - **Auth state persistence**: crawl saves encrypted auth state + config alongside sessions in the output directory
+
+## 0.7.0
+
+### Minor Changes
+
+- 458572e: ### @vulcn/engine
+  - **`addFinding` on PluginContext**: Plugins now have `ctx.addFinding()` to report findings through the proper callback chain. This ensures consumers are notified via `onFinding` and findings survive timeouts. Plugins should use this instead of `ctx.findings.push()`.
+  - **`onPageReady` callback**: New `RunOptions.onPageReady` callback fires after the driver creates the browser page. The engine uses this to defer `onRunStart` plugin hooks until the page is ready, so plugins receive a real page object (not `null`).
+  - **`onBeforeClose` hook**: New plugin lifecycle hook called before the browser is closed. Plugins can flush in-flight async work here (e.g., pending response handlers that need browser access).
+  - **`onBeforeClose` callback**: New `RunOptions.onBeforeClose` callback fires before browser teardown, triggering plugin `onBeforeClose` hooks.
+
+  ### @vulcn/driver-browser
+  - **`onPageReady` signal**: Runner now calls `ctx.options.onPageReady(page)` after creating the browser page, enabling plugins to attach event listeners before any navigation occurs.
+  - **`onBeforeClose` signal**: Runner now calls `ctx.options.onBeforeClose(page)` before `browser.close()`, giving plugins time to drain pending async work.
+  - **Payload interleaving**: Payloads are now ordered round-robin across categories (e.g., `[sqli1, xss1, sqli2, xss2, ...]`) instead of sequentially. This ensures faster category coverage and earlier dedup early-breaks on slow SPAs.
+  - **Extended dedup early-break**: The per-step category dedup now treats any finding (dialog, console, or reflection) as confirmation, not just dialog-based detections. One confirmed finding per category per step is sufficient.
+
+  ### @vulcn/plugin-passive
+  - **Uses `ctx.addFinding()`**: All findings are now reported through the proper callback chain instead of pushing to `ctx.findings` directly. This fixes passive findings being invisible to `onFinding` consumers.
+  - **Cross-session dedup**: `reportedFindings` is no longer cleared between sessions, so the same passive finding (e.g., "Missing CSP" on the same origin) is reported once per scan, not once per crawled form.
+  - **Async handler drain**: Response handlers are tracked as promises and drained in the new `onBeforeClose` hook, preventing findings from being lost when the browser closes before async `response.allHeaders()` calls complete.
+
 ## 0.5.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -34,8 +34,21 @@ __export(index_exports, {
   DriverManager: () => DriverManager,
   PLUGIN_API_VERSION: () => PLUGIN_API_VERSION,
   PluginManager: () => PluginManager,
+  decrypt: () => decrypt,
+  decryptCredentials: () => decryptCredentials,
+  decryptStorageState: () => decryptStorageState,
   driverManager: () => driverManager,
-  pluginManager: () => pluginManager
+  encrypt: () => encrypt,
+  encryptCredentials: () => encryptCredentials,
+  encryptStorageState: () => encryptStorageState,
+  getPassphrase: () => getPassphrase,
+  isSessionDir: () => isSessionDir,
+  loadSessionDir: () => loadSessionDir,
+  looksLikeSessionDir: () => looksLikeSessionDir,
+  pluginManager: () => pluginManager,
+  readAuthState: () => readAuthState,
+  readCapturedRequests: () => readCapturedRequests,
+  saveSessionDir: () => saveSessionDir
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -197,23 +210,17 @@ var DriverManager = class {
   /**
    * Execute a session
    * Invokes plugin hooks (onRunStart, onRunEnd) around the driver runner.
+   * Plugin onRunStart is deferred until the driver signals the page is ready
+   * via the onPageReady callback, ensuring plugins get a real page object.
    */
   async execute(session, pluginManager2, options = {}) {
     const driver = this.getForSession(session);
     const findings = [];
     const logger = this.createLogger(driver.name);
-    const ctx = {
-      session,
-      pluginManager: pluginManager2,
-      payloads: pluginManager2.getPayloads(),
-      findings,
-      addFinding: (finding) => {
-        findings.push(finding);
-        pluginManager2.addFinding(finding);
-        options.onFinding?.(finding);
-      },
-      logger,
-      options
+    const addFinding = (finding) => {
+      findings.push(finding);
+      pluginManager2.addFinding(finding);
+      options.onFinding?.(finding);
     };
     const pluginCtx = {
       session,
@@ -223,21 +230,57 @@ var DriverManager = class {
       engine: { version: "0.3.0", pluginApiVersion: 1 },
       payloads: pluginManager2.getPayloads(),
       findings,
+      addFinding,
       logger,
       fetch: globalThis.fetch
     };
-    for (const loaded of pluginManager2.getPlugins()) {
-      if (loaded.enabled && loaded.plugin.hooks?.onRunStart) {
-        try {
-          await loaded.plugin.hooks.onRunStart({
-            ...pluginCtx,
-            config: loaded.config
-          });
-        } catch (err) {
-          logger.warn(`Plugin ${loaded.plugin.name} onRunStart failed: ${err}`);
+    const ctx = {
+      session,
+      pluginManager: pluginManager2,
+      payloads: pluginManager2.getPayloads(),
+      findings,
+      addFinding,
+      logger,
+      options: {
+        ...options,
+        // Provide onPageReady callback — fires plugin onRunStart hooks
+        // with the real page object once the driver has created it
+        onPageReady: async (page) => {
+          pluginCtx.page = page;
+          for (const loaded of pluginManager2.getPlugins()) {
+            if (loaded.enabled && loaded.plugin.hooks?.onRunStart) {
+              try {
+                await loaded.plugin.hooks.onRunStart({
+                  ...pluginCtx,
+                  config: loaded.config
+                });
+              } catch (err) {
+                logger.warn(
+                  `Plugin ${loaded.plugin.name} onRunStart failed: ${err}`
+                );
+              }
+            }
+          }
+        },
+        // Fires before browser closes — lets plugins flush pending async work
+        onBeforeClose: async (_page) => {
+          for (const loaded of pluginManager2.getPlugins()) {
+            if (loaded.enabled && loaded.plugin.hooks?.onBeforeClose) {
+              try {
+                await loaded.plugin.hooks.onBeforeClose({
+                  ...pluginCtx,
+                  config: loaded.config
+                });
+              } catch (err) {
+                logger.warn(
+                  `Plugin ${loaded.plugin.name} onBeforeClose failed: ${err}`
+                );
+              }
+            }
+          }
         }
       }
-    }
+    };
     let result = await driver.runner.execute(session, ctx);
     for (const loaded of pluginManager2.getPlugins()) {
       if (loaded.enabled && loaded.plugin.hooks?.onRunEnd) {
@@ -254,6 +297,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
    */
@@ -528,6 +674,9 @@ var PluginManager = class {
       engine: engineInfo,
       payloads: this.sharedPayloads,
       findings: this.sharedFindings,
+      addFinding: (finding) => {
+        this.sharedFindings.push(finding);
+      },
       logger: this.createLogger("plugin"),
       fetch: globalThis.fetch
     };
@@ -624,13 +773,265 @@ var PluginManager = class {
   }
 };
 var pluginManager = new PluginManager();
+
+// src/auth.ts
+var import_node_crypto = require("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 (0, import_node_crypto.pbkdf2Sync)(
+    passphrase,
+    salt,
+    PBKDF2_ITERATIONS,
+    KEY_LENGTH,
+    PBKDF2_DIGEST
+  );
+}
+function encrypt(data, passphrase) {
+  const salt = (0, import_node_crypto.randomBytes)(SALT_LENGTH);
+  const iv = (0, import_node_crypto.randomBytes)(IV_LENGTH);
+  const key = deriveKey(passphrase, salt);
+  const cipher = (0, import_node_crypto.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 = (0, import_node_crypto.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
+var import_promises2 = require("fs/promises");
+var import_node_fs2 = require("fs");
+var import_node_path3 = require("path");
+var import_yaml3 = require("yaml");
+async function loadSessionDir(dirPath) {
+  const manifestPath = (0, import_node_path3.join)(dirPath, "manifest.yml");
+  if (!(0, import_node_fs2.existsSync)(manifestPath)) {
+    throw new Error(
+      `No manifest.yml found in ${dirPath}. Is this a v2 session directory?`
+    );
+  }
+  const manifestYaml = await (0, import_promises2.readFile)(manifestPath, "utf-8");
+  const manifest = (0, import_yaml3.parse)(manifestYaml);
+  if (manifest.version !== "2") {
+    throw new Error(
+      `Unsupported session format version: ${manifest.version}. Expected "2".`
+    );
+  }
+  let authConfig;
+  if (manifest.auth?.configFile) {
+    const authPath = (0, import_node_path3.join)(dirPath, manifest.auth.configFile);
+    if ((0, import_node_fs2.existsSync)(authPath)) {
+      const authYaml = await (0, import_promises2.readFile)(authPath, "utf-8");
+      authConfig = (0, import_yaml3.parse)(authYaml);
+    }
+  }
+  const sessions = [];
+  for (const ref of manifest.sessions) {
+    if (ref.injectable === false) continue;
+    const sessionPath = (0, import_node_path3.join)(dirPath, ref.file);
+    if (!(0, import_node_fs2.existsSync)(sessionPath)) {
+      console.warn(`Session file not found: ${sessionPath}, skipping`);
+      continue;
+    }
+    const sessionYaml = await (0, import_promises2.readFile)(sessionPath, "utf-8");
+    const sessionData = (0, import_yaml3.parse)(sessionYaml);
+    const session = {
+      name: sessionData.name ?? (0, import_node_path3.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 (0, import_node_fs2.existsSync)((0, import_node_path3.join)(path, "manifest.yml"));
+}
+function looksLikeSessionDir(path) {
+  return path.endsWith(".vulcn") || path.endsWith(".vulcn/");
+}
+async function saveSessionDir(dirPath, options) {
+  await (0, import_promises2.mkdir)((0, import_node_path3.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 = (0, import_node_path3.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 (0, import_promises2.writeFile)(sessionPath, (0, import_yaml3.stringify)(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 (0, import_promises2.mkdir)((0, import_node_path3.join)(dirPath, "auth"), { recursive: true });
+    await (0, import_promises2.writeFile)(
+      (0, import_node_path3.join)(dirPath, "auth", "config.yml"),
+      (0, import_yaml3.stringify)(options.authConfig),
+      "utf-8"
+    );
+  }
+  if (options.encryptedState) {
+    await (0, import_promises2.mkdir)((0, import_node_path3.join)(dirPath, "auth"), { recursive: true });
+    await (0, import_promises2.writeFile)(
+      (0, import_node_path3.join)(dirPath, "auth", "state.enc"),
+      options.encryptedState,
+      "utf-8"
+    );
+  }
+  if (options.requests && options.requests.length > 0) {
+    await (0, import_promises2.mkdir)((0, import_node_path3.join)(dirPath, "requests"), { recursive: true });
+    for (const req of options.requests) {
+      const safeName = slugify(req.sessionName);
+      await (0, import_promises2.writeFile)(
+        (0, import_node_path3.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 (0, import_promises2.writeFile)((0, import_node_path3.join)(dirPath, "manifest.yml"), (0, import_yaml3.stringify)(manifest), "utf-8");
+}
+async function readAuthState(dirPath) {
+  const statePath = (0, import_node_path3.join)(dirPath, "auth", "state.enc");
+  if (!(0, import_node_fs2.existsSync)(statePath)) return null;
+  return (0, import_promises2.readFile)(statePath, "utf-8");
+}
+async function readCapturedRequests(dirPath) {
+  const requestsDir = (0, import_node_path3.join)(dirPath, "requests");
+  if (!(0, import_node_fs2.existsSync)(requestsDir)) return [];
+  const files = await (0, import_promises2.readdir)(requestsDir);
+  const requests = [];
+  for (const file of files) {
+    if (!file.endsWith(".json")) continue;
+    const content = await (0, import_promises2.readFile)((0, import_node_path3.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);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   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.cjs.map