@vulcn/engine 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # 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

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);
 
@@ -284,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
    */
@@ -657,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