@vulcn/driver-browser 0.1.0

package/dist/index.cjs

@@ -0,0 +1,756 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BROWSER_STEP_TYPES: () => BROWSER_STEP_TYPES,
+  BrowserRecorder: () => BrowserRecorder,
+  BrowserRunner: () => BrowserRunner,
+  BrowserStepSchema: () => BrowserStepSchema,
+  checkBrowsers: () => checkBrowsers,
+  configSchema: () => configSchema,
+  default: () => index_default,
+  installBrowsers: () => installBrowsers,
+  launchBrowser: () => launchBrowser
+});
+module.exports = __toCommonJS(index_exports);
+var import_zod = require("zod");
+
+// src/browser.ts
+var import_playwright = require("playwright");
+var import_node_child_process = require("child_process");
+var import_node_util = require("util");
+var execAsync = (0, import_node_util.promisify)(import_node_child_process.exec);
+var BrowserNotFoundError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BrowserNotFoundError";
+  }
+};
+async function launchBrowser(options = {}) {
+  const browserType = options.browser ?? "chromium";
+  const headless = options.headless ?? false;
+  if (browserType === "chromium") {
+    try {
+      const browser = await import_playwright.chromium.launch({
+        channel: "chrome",
+        headless
+      });
+      return { browser, channel: "chrome" };
+    } catch {
+    }
+    try {
+      const browser = await import_playwright.chromium.launch({
+        channel: "msedge",
+        headless
+      });
+      return { browser, channel: "msedge" };
+    } catch {
+    }
+    try {
+      const browser = await import_playwright.chromium.launch({ headless });
+      return { browser, channel: "chromium" };
+    } catch {
+      throw new BrowserNotFoundError(
+        "No Chromium browser found. Install Chrome or run: vulcn install chromium"
+      );
+    }
+  }
+  if (browserType === "firefox") {
+    try {
+      const browser = await import_playwright.firefox.launch({ headless });
+      return { browser, channel: "firefox" };
+    } catch {
+      throw new BrowserNotFoundError(
+        "Firefox not found. Run: vulcn install firefox"
+      );
+    }
+  }
+  if (browserType === "webkit") {
+    try {
+      const browser = await import_playwright.webkit.launch({ headless });
+      return { browser, channel: "webkit" };
+    } catch {
+      throw new BrowserNotFoundError(
+        "WebKit not found. Run: vulcn install webkit"
+      );
+    }
+  }
+  throw new BrowserNotFoundError(`Unknown browser type: ${browserType}`);
+}
+async function installBrowsers(browsers = ["chromium"]) {
+  const browserArg = browsers.join(" ");
+  await execAsync(`npx playwright install ${browserArg}`);
+}
+async function checkBrowsers() {
+  const results = {
+    systemChrome: false,
+    systemEdge: false,
+    playwrightChromium: false,
+    playwrightFirefox: false,
+    playwrightWebkit: false
+  };
+  try {
+    const browser = await import_playwright.chromium.launch({
+      channel: "chrome",
+      headless: true
+    });
+    await browser.close();
+    results.systemChrome = true;
+  } catch {
+  }
+  try {
+    const browser = await import_playwright.chromium.launch({
+      channel: "msedge",
+      headless: true
+    });
+    await browser.close();
+    results.systemEdge = true;
+  } catch {
+  }
+  try {
+    const browser = await import_playwright.chromium.launch({ headless: true });
+    await browser.close();
+    results.playwrightChromium = true;
+  } catch {
+  }
+  try {
+    const browser = await import_playwright.firefox.launch({ headless: true });
+    await browser.close();
+    results.playwrightFirefox = true;
+  } catch {
+  }
+  try {
+    const browser = await import_playwright.webkit.launch({ headless: true });
+    await browser.close();
+    results.playwrightWebkit = true;
+  } catch {
+  }
+  return results;
+}
+
+// src/recorder.ts
+var BrowserRecorder = class _BrowserRecorder {
+  /**
+   * Start a new recording session
+   */
+  static async start(config, _options = {}) {
+    const { startUrl, browser: browserType, viewport, headless } = config;
+    if (!startUrl) {
+      throw new Error("startUrl is required for browser recording");
+    }
+    const { browser } = await launchBrowser({
+      browser: browserType,
+      headless
+    });
+    const context = await browser.newContext({ viewport });
+    const page = await context.newPage();
+    await page.goto(startUrl);
+    const startTime = Date.now();
+    const steps = [];
+    let stepCounter = 0;
+    const generateStepId = () => {
+      stepCounter++;
+      return `step_${String(stepCounter).padStart(3, "0")}`;
+    };
+    steps.push({
+      id: generateStepId(),
+      type: "browser.navigate",
+      url: startUrl,
+      timestamp: 0
+    });
+    _BrowserRecorder.attachListeners(page, steps, startTime, generateStepId);
+    return {
+      async stop() {
+        const session = {
+          name: `Recording ${(/* @__PURE__ */ new Date()).toISOString()}`,
+          driver: "browser",
+          driverConfig: {
+            browser: browserType,
+            viewport,
+            startUrl
+          },
+          steps,
+          metadata: {
+            recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            version: "1"
+          }
+        };
+        await browser.close();
+        return session;
+      },
+      async abort() {
+        await browser.close();
+      },
+      getSteps() {
+        return [...steps];
+      },
+      addStep(step) {
+        steps.push({
+          ...step,
+          id: generateStepId(),
+          timestamp: Date.now() - startTime
+        });
+      }
+    };
+  }
+  /**
+   * Attach event listeners to the page
+   */
+  static attachListeners(page, steps, startTime, generateStepId) {
+    const getTimestamp = () => Date.now() - startTime;
+    const addStep = (step) => {
+      steps.push({
+        ...step,
+        id: generateStepId(),
+        timestamp: getTimestamp()
+      });
+    };
+    page.on("framenavigated", (frame) => {
+      if (frame === page.mainFrame()) {
+        const url = frame.url();
+        const lastStep = steps[steps.length - 1];
+        if (steps.length > 0 && lastStep?.type === "browser.navigate" && lastStep.url === url) {
+          return;
+        }
+        addStep({
+          type: "browser.navigate",
+          url
+        });
+      }
+    });
+    page.exposeFunction(
+      "__vulcn_record",
+      async (event) => {
+        switch (event.type) {
+          case "click": {
+            const data = event.data;
+            addStep({
+              type: "browser.click",
+              selector: data.selector,
+              position: { x: data.x, y: data.y }
+            });
+            break;
+          }
+          case "input": {
+            const data = event.data;
+            addStep({
+              type: "browser.input",
+              selector: data.selector,
+              value: data.value,
+              injectable: data.injectable
+            });
+            break;
+          }
+          case "keypress": {
+            const data = event.data;
+            addStep({
+              type: "browser.keypress",
+              key: data.key,
+              modifiers: data.modifiers
+            });
+            break;
+          }
+        }
+      }
+    );
+    page.on("load", async () => {
+      await _BrowserRecorder.injectRecordingScript(page);
+    });
+    _BrowserRecorder.injectRecordingScript(page);
+  }
+  /**
+   * Inject the recording script into the page
+   */
+  static async injectRecordingScript(page) {
+    await page.evaluate(`
+      (function() {
+        if (window.__vulcn_injected) return;
+        window.__vulcn_injected = true;
+
+        var textInputTypes = ['text', 'password', 'email', 'search', 'url', 'tel', 'number'];
+
+        function getSelector(el) {
+          if (el.id) {
+            return '#' + CSS.escape(el.id);
+          }
+          if (el.name) {
+            var tag = el.tagName.toLowerCase();
+            var nameSelector = tag + '[name="' + el.name + '"]';
+            if (document.querySelectorAll(nameSelector).length === 1) {
+              return nameSelector;
+            }
+          }
+          if (el.dataset && el.dataset.testid) {
+            return '[data-testid="' + el.dataset.testid + '"]';
+          }
+          if (el.tagName === 'INPUT' && el.type && el.name) {
+            var inputSelector = 'input[type="' + el.type + '"][name="' + el.name + '"]';
+            if (document.querySelectorAll(inputSelector).length === 1) {
+              return inputSelector;
+            }
+          }
+          if (el.className && typeof el.className === 'string') {
+            var classes = el.className.trim().split(/\\s+/).filter(function(c) { return c.length > 0; });
+            if (classes.length > 0) {
+              var classSelector = el.tagName.toLowerCase() + '.' + classes.map(function(c) { return CSS.escape(c); }).join('.');
+              if (document.querySelectorAll(classSelector).length === 1) {
+                return classSelector;
+              }
+            }
+          }
+          var path = [];
+          var current = el;
+          while (current && current !== document.body) {
+            var tag = current.tagName.toLowerCase();
+            var parent = current.parentElement;
+            if (parent) {
+              var siblings = Array.from(parent.children).filter(function(c) { return c.tagName === current.tagName; });
+              if (siblings.length > 1) {
+                var index = siblings.indexOf(current) + 1;
+                tag = tag + ':nth-of-type(' + index + ')';
+              }
+            }
+            path.unshift(tag);
+            current = parent;
+          }
+          return path.join(' > ');
+        }
+
+        function getInputType(el) {
+          if (el.tagName === 'INPUT') return el.type || 'text';
+          if (el.tagName === 'TEXTAREA') return 'textarea';
+          if (el.tagName === 'SELECT') return 'select';
+          return null;
+        }
+
+        function isTextInjectable(el) {
+          var inputType = getInputType(el);
+          if (!inputType) return false;
+          if (inputType === 'textarea') return true;
+          if (inputType === 'select') return false;
+          return textInputTypes.indexOf(inputType) !== -1;
+        }
+
+        document.addEventListener('click', function(e) {
+          var target = e.target;
+          window.__vulcn_record({
+            type: 'click',
+            data: {
+              selector: getSelector(target),
+              x: e.clientX,
+              y: e.clientY
+            }
+          });
+        }, true);
+
+        document.addEventListener('change', function(e) {
+          var target = e.target;
+          if ('value' in target) {
+            var inputType = getInputType(target);
+            window.__vulcn_record({
+              type: 'input',
+              data: {
+                selector: getSelector(target),
+                value: target.value,
+                inputType: inputType,
+                injectable: isTextInjectable(target)
+              }
+            });
+          }
+        }, true);
+
+        document.addEventListener('keydown', function(e) {
+          if (e.ctrlKey || e.metaKey || e.altKey) {
+            var modifiers = [];
+            if (e.ctrlKey) modifiers.push('ctrl');
+            if (e.metaKey) modifiers.push('meta');
+            if (e.altKey) modifiers.push('alt');
+            if (e.shiftKey) modifiers.push('shift');
+
+            window.__vulcn_record({
+              type: 'keypress',
+              data: {
+                key: e.key,
+                modifiers: modifiers
+              }
+            });
+          }
+        }, true);
+      })();
+    `);
+  }
+};
+
+// src/runner.ts
+var BrowserRunner = class _BrowserRunner {
+  /**
+   * Execute a session with security payloads
+   */
+  static async execute(session, ctx) {
+    const config = session.driverConfig;
+    const browserType = config.browser ?? "chromium";
+    const viewport = config.viewport ?? {
+      width: 1280,
+      height: 720
+    };
+    const startUrl = config.startUrl;
+    const headless = ctx.options.headless ?? true;
+    const startTime = Date.now();
+    const errors = [];
+    let payloadsTested = 0;
+    const payloads = ctx.payloads;
+    if (payloads.length === 0) {
+      return {
+        findings: [],
+        stepsExecuted: session.steps.length,
+        payloadsTested: 0,
+        duration: Date.now() - startTime,
+        errors: [
+          "No payloads loaded. Add a payload plugin or configure payloads."
+        ]
+      };
+    }
+    const { browser } = await launchBrowser({
+      browser: browserType,
+      headless
+    });
+    const context = await browser.newContext({ viewport });
+    const page = await context.newPage();
+    const eventFindings = [];
+    let currentPayloadInfo = null;
+    const dialogHandler = async (dialog) => {
+      if (currentPayloadInfo) {
+        const message = dialog.message();
+        if (message.includes("vulcn") || message === currentPayloadInfo.payloadValue) {
+          eventFindings.push({
+            type: "xss",
+            severity: "high",
+            title: "XSS Confirmed - Dialog Triggered",
+            description: `JavaScript dialog was triggered by payload injection`,
+            stepId: currentPayloadInfo.stepId,
+            payload: currentPayloadInfo.payloadValue,
+            url: page.url(),
+            evidence: `Dialog message: ${message}`,
+            metadata: {
+              dialogType: dialog.type(),
+              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"
+            }
+          });
+        }
+      }
+    };
+    page.on("dialog", dialogHandler);
+    page.on("console", consoleHandler);
+    try {
+      const injectableSteps = session.steps.filter(
+        (step) => step.type === "browser.input" && step.injectable !== false
+      );
+      const allPayloads = [];
+      for (const payloadSet of payloads) {
+        for (const value of payloadSet.payloads) {
+          allPayloads.push({ payloadSet, value });
+        }
+      }
+      for (const injectableStep of injectableSteps) {
+        for (const { payloadSet, value } of allPayloads) {
+          try {
+            currentPayloadInfo = {
+              stepId: injectableStep.id,
+              payloadSet,
+              payloadValue: value
+            };
+            await _BrowserRunner.replayWithPayload(
+              page,
+              session,
+              injectableStep,
+              value,
+              startUrl
+            );
+            const reflectionFinding = await _BrowserRunner.checkReflection(
+              page,
+              injectableStep,
+              payloadSet,
+              value
+            );
+            const allFindings = [...eventFindings];
+            if (reflectionFinding) {
+              allFindings.push(reflectionFinding);
+            }
+            for (const finding of allFindings) {
+              ctx.addFinding(finding);
+            }
+            eventFindings.length = 0;
+            payloadsTested++;
+            ctx.options.onStepComplete?.(injectableStep.id, payloadsTested);
+          } catch (err) {
+            errors.push(`${injectableStep.id}: ${String(err)}`);
+          }
+        }
+      }
+    } finally {
+      page.off("dialog", dialogHandler);
+      page.off("console", consoleHandler);
+      currentPayloadInfo = null;
+      await browser.close();
+    }
+    return {
+      findings: ctx.findings,
+      stepsExecuted: session.steps.length,
+      payloadsTested,
+      duration: Date.now() - startTime,
+      errors
+    };
+  }
+  /**
+   * Replay session steps with payload injected at target step
+   */
+  static async replayWithPayload(page, session, targetStep, payloadValue, startUrl) {
+    await page.goto(startUrl, { waitUntil: "domcontentloaded" });
+    for (const step of session.steps) {
+      const browserStep = step;
+      try {
+        switch (browserStep.type) {
+          case "browser.navigate":
+            await page.goto(browserStep.url, { waitUntil: "domcontentloaded" });
+            break;
+          case "browser.click":
+            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 });
+            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 (step.id === targetStep.id) {
+        await page.waitForTimeout(100);
+        break;
+      }
+    }
+  }
+  /**
+   * 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)
+        };
+      }
+    }
+    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;
+  }
+  /**
+   * 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";
+    }
+  }
+};
+
+// src/index.ts
+var configSchema = import_zod.z.object({
+  /** Starting URL for recording */
+  startUrl: import_zod.z.string().url().optional(),
+  /** Browser type */
+  browser: import_zod.z.enum(["chromium", "firefox", "webkit"]).default("chromium"),
+  /** Viewport size */
+  viewport: import_zod.z.object({
+    width: import_zod.z.number().default(1280),
+    height: import_zod.z.number().default(720)
+  }).default({ width: 1280, height: 720 }),
+  /** Run headless */
+  headless: import_zod.z.boolean().default(false)
+});
+var BROWSER_STEP_TYPES = [
+  "browser.navigate",
+  "browser.click",
+  "browser.input",
+  "browser.keypress",
+  "browser.scroll",
+  "browser.wait"
+];
+var BrowserStepSchema = import_zod.z.discriminatedUnion("type", [
+  import_zod.z.object({
+    id: import_zod.z.string(),
+    type: import_zod.z.literal("browser.navigate"),
+    url: import_zod.z.string(),
+    timestamp: import_zod.z.number()
+  }),
+  import_zod.z.object({
+    id: import_zod.z.string(),
+    type: import_zod.z.literal("browser.click"),
+    selector: import_zod.z.string(),
+    position: import_zod.z.object({ x: import_zod.z.number(), y: import_zod.z.number() }).optional(),
+    timestamp: import_zod.z.number()
+  }),
+  import_zod.z.object({
+    id: import_zod.z.string(),
+    type: import_zod.z.literal("browser.input"),
+    selector: import_zod.z.string(),
+    value: import_zod.z.string(),
+    injectable: import_zod.z.boolean().default(true),
+    timestamp: import_zod.z.number()
+  }),
+  import_zod.z.object({
+    id: import_zod.z.string(),
+    type: import_zod.z.literal("browser.keypress"),
+    key: import_zod.z.string(),
+    modifiers: import_zod.z.array(import_zod.z.string()).optional(),
+    timestamp: import_zod.z.number()
+  }),
+  import_zod.z.object({
+    id: import_zod.z.string(),
+    type: import_zod.z.literal("browser.scroll"),
+    selector: import_zod.z.string().optional(),
+    position: import_zod.z.object({ x: import_zod.z.number(), y: import_zod.z.number() }),
+    timestamp: import_zod.z.number()
+  }),
+  import_zod.z.object({
+    id: import_zod.z.string(),
+    type: import_zod.z.literal("browser.wait"),
+    duration: import_zod.z.number(),
+    timestamp: import_zod.z.number()
+  })
+]);
+var recorderDriver = {
+  async start(config, options) {
+    const parsedConfig = configSchema.parse(config);
+    return BrowserRecorder.start(parsedConfig, options);
+  }
+};
+var runnerDriver = {
+  async execute(session, ctx) {
+    return BrowserRunner.execute(session, ctx);
+  }
+};
+var browserDriver = {
+  name: "browser",
+  version: "0.1.0",
+  apiVersion: 1,
+  description: "Browser recording driver using Playwright",
+  configSchema,
+  stepTypes: [...BROWSER_STEP_TYPES],
+  recorder: recorderDriver,
+  runner: runnerDriver
+};
+var index_default = browserDriver;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BROWSER_STEP_TYPES,
+  BrowserRecorder,
+  BrowserRunner,
+  BrowserStepSchema,
+  checkBrowsers,
+  configSchema,
+  installBrowsers,
+  launchBrowser
+});
+//# sourceMappingURL=index.cjs.map