@vulcn/driver-browser 0.2.0 → 0.3.0

package/dist/index.js

@@ -368,9 +368,12 @@ var BrowserRecorder = class _BrowserRecorder {
 };
 
 // src/runner.ts
-var BrowserRunner = class _BrowserRunner {
+var BrowserRunner = class {
   /**
-   * Execute a session with security payloads
+   * Execute a session with security payloads.
+   *
+   * If ctx.options.browser is provided, reuses that browser (persistent mode).
+   * Otherwise, launches and closes its own browser (standalone mode).
    */
   static async execute(session, ctx) {
     const config = session.driverConfig;
@@ -396,83 +399,39 @@ var BrowserRunner = class _BrowserRunner {
         ]
       };
     }
-    const { browser } = await launchBrowser({
-      browser: browserType,
-      headless
-    });
-    const context = await browser.newContext({ viewport });
+    const sharedBrowser = ctx.options.browser;
+    const ownBrowser = sharedBrowser ? null : (await launchBrowser({ browser: browserType, headless })).browser;
+    const browser = sharedBrowser ?? ownBrowser;
+    const storageState = ctx.options.storageState;
+    const contextOptions = { viewport };
+    if (storageState) {
+      contextOptions.storageState = JSON.parse(storageState);
+    }
+    const context = await browser.newContext(contextOptions);
     const page = await context.newPage();
     await ctx.options.onPageReady?.(page);
     const eventFindings = [];
     let currentPayloadInfo = null;
-    const dialogHandler = async (dialog) => {
-      if (currentPayloadInfo) {
-        const message = dialog.message();
-        const dialogType = dialog.type();
-        if (dialogType !== "beforeunload") {
-          eventFindings.push({
-            type: "xss",
-            severity: "high",
-            title: `XSS Confirmed - ${dialogType}() triggered`,
-            description: `JavaScript ${dialogType}() dialog was triggered by payload injection. Message: "${message}"`,
-            stepId: currentPayloadInfo.stepId,
-            payload: currentPayloadInfo.payloadValue,
-            url: page.url(),
-            evidence: `Dialog type: ${dialogType}, Message: ${message}`,
-            metadata: {
-              dialogType,
-              dialogMessage: message,
-              detectionMethod: "dialog"
-            }
-          });
-        }
-      }
-      try {
-        await dialog.dismiss();
-      } catch {
-      }
-    };
-    const consoleHandler = async (msg) => {
-      if (currentPayloadInfo && msg.type() === "log") {
-        const text = msg.text();
-        if (text.includes("vulcn") || text.includes(currentPayloadInfo.payloadValue)) {
-          eventFindings.push({
-            type: "xss",
-            severity: "high",
-            title: "XSS Confirmed - Console Output",
-            description: `JavaScript console.log was triggered by payload injection`,
-            stepId: currentPayloadInfo.stepId,
-            payload: currentPayloadInfo.payloadValue,
-            url: page.url(),
-            evidence: `Console output: ${text}`,
-            metadata: {
-              consoleType: msg.type(),
-              detectionMethod: "console"
-            }
-          });
-        }
-      }
-    };
+    const dialogHandler = createDialogHandler(
+      page,
+      eventFindings,
+      () => currentPayloadInfo
+    );
+    const consoleHandler = createConsoleHandler(
+      eventFindings,
+      () => currentPayloadInfo
+    );
     page.on("dialog", dialogHandler);
     page.on("console", consoleHandler);
     try {
       const injectableSteps = session.steps.filter(
         (step) => step.type === "browser.input" && step.injectable !== false
       );
-      const allPayloads = [];
-      const payloadsByCategory = payloads.map(
-        (ps) => ps.payloads.map((value) => ({ payloadSet: ps, value }))
-      );
-      const maxLen = Math.max(...payloadsByCategory.map((c) => c.length));
-      for (let i = 0; i < maxLen; i++) {
-        for (const category of payloadsByCategory) {
-          if (i < category.length) {
-            allPayloads.push(category[i]);
-          }
-        }
-      }
+      const allPayloads = interleavePayloads(payloads);
       const confirmedTypes = /* @__PURE__ */ new Set();
       for (const injectableStep of injectableSteps) {
+        let isFirstPayload = true;
+        let formPageUrl = null;
         for (const { payloadSet, value } of allPayloads) {
           const stepTypeKey = `${injectableStep.id}::${payloadSet.category}`;
           if (confirmedTypes.has(stepTypeKey)) {
@@ -484,14 +443,35 @@ var BrowserRunner = class _BrowserRunner {
               payloadSet,
               payloadValue: value
             };
-            await _BrowserRunner.replayWithPayload(
-              page,
-              session,
-              injectableStep,
-              value,
-              startUrl
-            );
-            const reflectionFinding = await _BrowserRunner.checkReflection(
+            if (isFirstPayload) {
+              await replayWithPayload(
+                page,
+                session,
+                injectableStep,
+                value,
+                startUrl
+              );
+              isFirstPayload = false;
+              formPageUrl = startUrl;
+            } else {
+              const cycled = await cyclePayload(
+                page,
+                session,
+                injectableStep,
+                value,
+                formPageUrl ?? startUrl
+              );
+              if (!cycled) {
+                await replayWithPayload(
+                  page,
+                  session,
+                  injectableStep,
+                  value,
+                  startUrl
+                );
+              }
+            }
+            const reflectionFinding = await checkReflection(
               page,
               injectableStep,
               payloadSet,
@@ -517,6 +497,7 @@ var BrowserRunner = class _BrowserRunner {
             ctx.options.onStepComplete?.(injectableStep.id, payloadsTested);
           } catch (err) {
             errors.push(`${injectableStep.id}: ${String(err)}`);
+            isFirstPayload = true;
           }
         }
       }
@@ -525,7 +506,10 @@ var BrowserRunner = class _BrowserRunner {
       page.off("console", consoleHandler);
       currentPayloadInfo = null;
       await ctx.options.onBeforeClose?.(page);
-      await browser.close();
+      await context.close();
+      if (ownBrowser) {
+        await ownBrowser.close();
+      }
     }
     return {
       findings: ctx.findings,
@@ -535,136 +519,264 @@ var BrowserRunner = class _BrowserRunner {
       errors
     };
   }
-  /**
-   * Replay session steps with payload injected at target step
-   *
-   * 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.
-   */
-  static async replayWithPayload(page, session, targetStep, payloadValue, startUrl) {
-    await page.goto(startUrl, { waitUntil: "domcontentloaded" });
-    let injected = false;
-    for (const step of session.steps) {
-      const browserStep = step;
-      try {
-        switch (browserStep.type) {
-          case "browser.navigate":
-            if (injected && browserStep.url.includes("sid=")) {
-              continue;
-            }
-            await page.goto(browserStep.url, { waitUntil: "domcontentloaded" });
-            break;
-          case "browser.click":
-            if (injected) {
-              await Promise.all([
-                page.waitForNavigation({
-                  waitUntil: "domcontentloaded",
-                  timeout: 5e3
-                }).catch(() => {
-                }),
-                page.click(browserStep.selector, { timeout: 5e3 })
-              ]);
-            } else {
-              await page.click(browserStep.selector, { timeout: 5e3 });
-            }
-            break;
-          case "browser.input": {
-            const value = step.id === targetStep.id ? payloadValue : browserStep.value;
-            await page.fill(browserStep.selector, value, { timeout: 5e3 });
-            if (step.id === targetStep.id) {
-              injected = true;
-            }
-            break;
+};
+function createDialogHandler(page, eventFindings, getPayloadInfo) {
+  return async (dialog) => {
+    const info = getPayloadInfo();
+    if (info) {
+      const message = dialog.message();
+      const dialogType = dialog.type();
+      if (dialogType !== "beforeunload") {
+        eventFindings.push({
+          type: "xss",
+          severity: "high",
+          title: `XSS Confirmed - ${dialogType}() triggered`,
+          description: `JavaScript ${dialogType}() dialog was triggered by payload injection. Message: "${message}"`,
+          stepId: info.stepId,
+          payload: info.payloadValue,
+          url: page.url(),
+          evidence: `Dialog type: ${dialogType}, Message: ${message}`,
+          metadata: {
+            dialogType,
+            dialogMessage: message,
+            detectionMethod: "dialog"
           }
-          case "browser.keypress": {
-            const modifiers = browserStep.modifiers ?? [];
-            for (const mod of modifiers) {
-              await page.keyboard.down(
-                mod
-              );
-            }
-            await page.keyboard.press(browserStep.key);
-            for (const mod of modifiers.reverse()) {
-              await page.keyboard.up(
-                mod
-              );
-            }
-            break;
+        });
+      }
+    }
+    try {
+      await dialog.dismiss();
+    } catch {
+    }
+  };
+}
+function createConsoleHandler(eventFindings, getPayloadInfo) {
+  return async (msg) => {
+    const info = getPayloadInfo();
+    if (info && msg.type() === "log") {
+      const text = msg.text();
+      if (text.includes("vulcn") || text.includes(info.payloadValue)) {
+        eventFindings.push({
+          type: "xss",
+          severity: "high",
+          title: "XSS Confirmed - Console Output",
+          description: `JavaScript console.log was triggered by payload injection`,
+          stepId: info.stepId,
+          payload: info.payloadValue,
+          url: "",
+          evidence: `Console output: ${text}`,
+          metadata: {
+            consoleType: msg.type(),
+            detectionMethod: "console"
           }
-          case "browser.scroll":
-            if (browserStep.selector) {
-              await page.locator(browserStep.selector).evaluate((el, pos) => {
-                el.scrollTo(pos.x, pos.y);
-              }, browserStep.position);
-            } else {
-              await page.evaluate((pos) => {
-                window.scrollTo(pos.x, pos.y);
-              }, browserStep.position);
-            }
-            break;
-          case "browser.wait":
-            await page.waitForTimeout(browserStep.duration);
-            break;
-        }
-      } catch {
+        });
       }
     }
+  };
+}
+async function cyclePayload(page, session, targetStep, payloadValue, formPageUrl) {
+  try {
+    await page.goBack({ waitUntil: "domcontentloaded", timeout: 5e3 });
+    const targetSelector = targetStep.selector;
+    const formPresent = await page.waitForSelector(targetSelector, { timeout: 3e3 }).then(() => true).catch(() => false);
+    if (!formPresent) {
+      await page.goto(formPageUrl, {
+        waitUntil: "domcontentloaded",
+        timeout: 5e3
+      });
+      const formPresentAfterNav = await page.waitForSelector(targetSelector, { timeout: 3e3 }).then(() => true).catch(() => false);
+      if (!formPresentAfterNav) {
+        return false;
+      }
+    }
+    await page.fill(targetSelector, payloadValue, { timeout: 5e3 });
+    await replayStepsAfter(page, session, targetStep);
     await page.waitForTimeout(500);
+    return true;
+  } catch {
+    return false;
   }
-  /**
-   * Check for payload reflection in page content
-   */
-  static async checkReflection(page, step, payloadSet, payloadValue) {
-    const content = await page.content();
-    for (const pattern of payloadSet.detectPatterns) {
-      if (pattern.test(content)) {
-        return {
-          type: payloadSet.category,
-          severity: _BrowserRunner.getSeverity(payloadSet.category),
-          title: `${payloadSet.category.toUpperCase()} vulnerability detected`,
-          description: `Payload pattern was reflected in page content`,
-          stepId: step.id,
-          payload: payloadValue,
-          url: page.url(),
-          evidence: content.match(pattern)?.[0]?.slice(0, 200)
-        };
+}
+async function replayWithPayload(page, session, targetStep, payloadValue, startUrl) {
+  await page.goto(startUrl, { waitUntil: "domcontentloaded" });
+  let injected = false;
+  for (const step of session.steps) {
+    const browserStep = step;
+    try {
+      switch (browserStep.type) {
+        case "browser.navigate":
+          if (injected && browserStep.url.includes("sid=")) {
+            continue;
+          }
+          await page.goto(browserStep.url, { waitUntil: "domcontentloaded" });
+          break;
+        case "browser.click":
+          if (injected) {
+            await Promise.all([
+              page.waitForNavigation({
+                waitUntil: "domcontentloaded",
+                timeout: 5e3
+              }).catch(() => {
+              }),
+              page.click(browserStep.selector, { timeout: 5e3 })
+            ]);
+          } else {
+            await page.click(browserStep.selector, { timeout: 5e3 });
+          }
+          break;
+        case "browser.input": {
+          const value = step.id === targetStep.id ? payloadValue : browserStep.value;
+          await page.fill(browserStep.selector, value, { timeout: 5e3 });
+          if (step.id === targetStep.id) {
+            injected = true;
+          }
+          break;
+        }
+        case "browser.keypress": {
+          const modifiers = browserStep.modifiers ?? [];
+          for (const mod of modifiers) {
+            await page.keyboard.down(
+              mod
+            );
+          }
+          await page.keyboard.press(browserStep.key);
+          for (const mod of modifiers.reverse()) {
+            await page.keyboard.up(mod);
+          }
+          break;
+        }
+        case "browser.scroll":
+          if (browserStep.selector) {
+            await page.locator(browserStep.selector).evaluate((el, pos) => {
+              el.scrollTo(pos.x, pos.y);
+            }, browserStep.position);
+          } else {
+            await page.evaluate((pos) => {
+              window.scrollTo(pos.x, pos.y);
+            }, browserStep.position);
+          }
+          break;
+        case "browser.wait":
+          await page.waitForTimeout(browserStep.duration);
+          break;
       }
+    } catch {
     }
-    if (content.includes(payloadValue)) {
+  }
+  await page.waitForTimeout(500);
+}
+async function replayStepsAfter(page, session, targetStep) {
+  let pastTarget = false;
+  for (const step of session.steps) {
+    if (step.id === targetStep.id) {
+      pastTarget = true;
+      continue;
+    }
+    if (!pastTarget) continue;
+    const browserStep = step;
+    try {
+      switch (browserStep.type) {
+        case "browser.navigate":
+          break;
+        case "browser.click":
+          await Promise.all([
+            page.waitForNavigation({
+              waitUntil: "domcontentloaded",
+              timeout: 5e3
+            }).catch(() => {
+            }),
+            page.click(browserStep.selector, { timeout: 5e3 })
+          ]);
+          break;
+        case "browser.input":
+          await page.fill(browserStep.selector, browserStep.value, {
+            timeout: 5e3
+          });
+          break;
+        case "browser.keypress": {
+          const modifiers = browserStep.modifiers ?? [];
+          for (const mod of modifiers) {
+            await page.keyboard.down(
+              mod
+            );
+          }
+          await page.keyboard.press(browserStep.key);
+          for (const mod of modifiers.reverse()) {
+            await page.keyboard.up(mod);
+          }
+          break;
+        }
+        case "browser.scroll":
+          break;
+        // skip scrolls in fast path
+        case "browser.wait":
+          break;
+      }
+    } catch {
+    }
+  }
+  await page.waitForTimeout(500);
+}
+async function checkReflection(page, step, payloadSet, payloadValue) {
+  const content = await page.content();
+  for (const pattern of payloadSet.detectPatterns) {
+    if (pattern.test(content)) {
       return {
         type: payloadSet.category,
-        severity: "medium",
-        title: `Potential ${payloadSet.category.toUpperCase()} - payload reflection`,
-        description: `Payload was reflected in page without encoding`,
+        severity: getSeverity(payloadSet.category),
+        title: `${payloadSet.category.toUpperCase()} vulnerability detected`,
+        description: `Payload pattern was reflected in page content`,
         stepId: step.id,
         payload: payloadValue,
-        url: page.url()
+        url: page.url(),
+        evidence: content.match(pattern)?.[0]?.slice(0, 200)
       };
     }
-    return void 0;
   }
-  /**
-   * Determine severity based on vulnerability category
-   */
-  static getSeverity(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";
+  if (content.includes(payloadValue)) {
+    return {
+      type: payloadSet.category,
+      severity: "medium",
+      title: `Potential ${payloadSet.category.toUpperCase()} - payload reflection`,
+      description: `Payload was reflected in page without encoding`,
+      stepId: step.id,
+      payload: payloadValue,
+      url: page.url()
+    };
+  }
+  return void 0;
+}
+function getSeverity(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 interleavePayloads(payloads) {
+  const result = [];
+  const payloadsByCategory = payloads.map(
+    (ps) => ps.payloads.map((value) => ({ payloadSet: ps, value }))
+  );
+  const maxLen = Math.max(...payloadsByCategory.map((c) => c.length));
+  for (let i = 0; i < maxLen; i++) {
+    for (const category of payloadsByCategory) {
+      if (i < category.length) {
+        result.push(category[i]);
+      }
     }
   }
-};
+  return result;
+}
 
 // src/crawler.ts
 var INJECTABLE_INPUT_TYPES = /* @__PURE__ */ new Set([
@@ -701,7 +813,8 @@ async function crawlAndBuildSessions(config, options = {}) {
     headless: config.headless ?? true
   });
   const context = await browser.newContext({
-    viewport: config.viewport ?? { width: 1280, height: 720 }
+    viewport: config.viewport ?? { width: 1280, height: 720 },
+    ...options.storageState ? { storageState: JSON.parse(options.storageState) } : {}
   });
   try {
     while (queue.length > 0 && visited.size < opts.maxPages) {
@@ -1016,6 +1129,182 @@ function normalizeUrl(url) {
   }
 }
 
+// src/auth.ts
+async function detectLoginForm(page) {
+  return page.evaluate(() => {
+    function findUsernameInput(container) {
+      const selectors = [
+        'input[autocomplete="username"]',
+        'input[autocomplete="email"]',
+        'input[type="email"]',
+        'input[name*="user" i]',
+        'input[name*="login" i]',
+        'input[name*="email" i]',
+        'input[id*="user" i]',
+        'input[id*="login" i]',
+        'input[id*="email" i]',
+        'input[name*="name" i]',
+        'input[type="text"]'
+      ];
+      for (const sel of selectors) {
+        const el = container.querySelector(sel);
+        if (el && el.type !== "password" && el.type !== "hidden") {
+          return el;
+        }
+      }
+      return null;
+    }
+    function findSubmitButton(container) {
+      const selectors = [
+        'button[type="submit"]',
+        'input[type="submit"]',
+        "button:not([type])",
+        'button[type="button"]'
+      ];
+      for (const sel of selectors) {
+        const el = container.querySelector(sel);
+        if (el) return el;
+      }
+      return null;
+    }
+    function getSelector(el) {
+      if (el.id) return `#${CSS.escape(el.id)}`;
+      if (el.getAttribute("name"))
+        return `${el.tagName.toLowerCase()}[name="${CSS.escape(el.getAttribute("name"))}"]`;
+      if (el.getAttribute("type") && el.tagName === "INPUT")
+        return `input[type="${el.getAttribute("type")}"]`;
+      const parent = el.parentElement;
+      if (!parent) return el.tagName.toLowerCase();
+      const siblings = Array.from(parent.children);
+      const index = siblings.indexOf(el) + 1;
+      return `${parent.tagName.toLowerCase()} > ${el.tagName.toLowerCase()}:nth-child(${index})`;
+    }
+    const forms = document.querySelectorAll("form");
+    for (const form of forms) {
+      const passwordInput2 = form.querySelector(
+        'input[type="password"]'
+      );
+      if (!passwordInput2) continue;
+      const usernameInput = findUsernameInput(form);
+      const submitButton = findSubmitButton(form);
+      return {
+        usernameSelector: usernameInput ? getSelector(usernameInput) : 'input[type="text"]',
+        passwordSelector: getSelector(passwordInput2),
+        submitSelector: submitButton ? getSelector(submitButton) : null,
+        autoDetected: true
+      };
+    }
+    const passwordInput = document.querySelector(
+      'input[type="password"]'
+    );
+    if (passwordInput) {
+      const usernameInput = findUsernameInput(document.body);
+      const submitButton = findSubmitButton(document.body);
+      return {
+        usernameSelector: usernameInput ? getSelector(usernameInput) : 'input[type="text"]',
+        passwordSelector: getSelector(passwordInput),
+        submitSelector: submitButton ? getSelector(submitButton) : null,
+        autoDetected: true
+      };
+    }
+    return null;
+  });
+}
+async function performLogin(page, context, credentials, options) {
+  const loginUrl = credentials.loginUrl ?? options.targetUrl;
+  await page.goto(loginUrl, { waitUntil: "domcontentloaded", timeout: 15e3 });
+  let usernameSelector;
+  let passwordSelector;
+  let submitSelector;
+  if (credentials.userSelector && credentials.passSelector) {
+    usernameSelector = credentials.userSelector;
+    passwordSelector = credentials.passSelector;
+    submitSelector = null;
+  } else {
+    const form = await detectLoginForm(page);
+    if (!form) {
+      return {
+        success: false,
+        message: `No login form detected on ${loginUrl}. Use --user-field and --pass-field to specify selectors.`
+      };
+    }
+    usernameSelector = form.usernameSelector;
+    passwordSelector = form.passwordSelector;
+    submitSelector = form.submitSelector;
+  }
+  try {
+    await page.fill(usernameSelector, credentials.username, { timeout: 5e3 });
+  } catch {
+    return {
+      success: false,
+      message: `Could not find username field: ${usernameSelector}`
+    };
+  }
+  try {
+    await page.fill(passwordSelector, credentials.password, { timeout: 5e3 });
+  } catch {
+    return {
+      success: false,
+      message: `Could not find password field: ${passwordSelector}`
+    };
+  }
+  try {
+    if (submitSelector) {
+      await Promise.all([
+        page.waitForNavigation({ waitUntil: "domcontentloaded", timeout: 1e4 }).catch(() => {
+        }),
+        page.click(submitSelector, { timeout: 5e3 })
+      ]);
+    } else {
+      await Promise.all([
+        page.waitForNavigation({ waitUntil: "domcontentloaded", timeout: 1e4 }).catch(() => {
+        }),
+        page.press(passwordSelector, "Enter")
+      ]);
+    }
+  } catch {
+    return {
+      success: false,
+      message: "Failed to submit login form"
+    };
+  }
+  await page.waitForTimeout(1e3);
+  const bodyText = await page.textContent("body").catch(() => "");
+  if (options.loggedOutIndicator && bodyText?.includes(options.loggedOutIndicator)) {
+    return {
+      success: false,
+      message: `Login failed \u2014 "${options.loggedOutIndicator}" still visible on page`
+    };
+  }
+  if (options.loggedInIndicator && !bodyText?.includes(options.loggedInIndicator)) {
+    return {
+      success: false,
+      message: `Login uncertain \u2014 "${options.loggedInIndicator}" not found on page`
+    };
+  }
+  const storageState = JSON.stringify(await context.storageState());
+  return {
+    success: true,
+    message: "Login successful",
+    storageState
+  };
+}
+async function checkSessionAlive(page, config) {
+  try {
+    const bodyText = await page.textContent("body");
+    if (!bodyText) return true;
+    if (config.loggedOutIndicator && bodyText.includes(config.loggedOutIndicator)) {
+      return false;
+    }
+    if (config.loggedInIndicator && !bodyText.includes(config.loggedInIndicator)) {
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/index.ts
 var configSchema = z.object({
   /** Starting URL for recording */
@@ -1121,10 +1410,13 @@ export {
   BrowserRunner,
   BrowserStepSchema,
   checkBrowsers,
+  checkSessionAlive,
   configSchema,
   crawlAndBuildSessions,
   index_default as default,
+  detectLoginForm,
   installBrowsers,
-  launchBrowser
+  launchBrowser,
+  performLogin
 };
 //# sourceMappingURL=index.js.map