Skip to main content

​
Overview

The browser driver (@vulcn/driver-browser) enables security testing of web applications by recording and replaying browser interactions. It uses Playwright for browser automation.

​
Installation

npm install @vulcn/driver-browser
The browser driver is included with the vulcn CLI by default. You only need to install it separately for programmatic usage.

​
Configuration

OptionTypeDefaultDescription
startUrlstringrequiredURL to navigate to when recording starts
browser"chromium" | "firefox" | "webkit""chromium"Browser engine to use
viewport{ width: number, height: number }{ width: 1280, height: 720 }Browser viewport size
headlessbooleanfalseRun browser in headless mode

​
Example Configuration

# vulcn.config.yml
settings:
  driver: browser
  driverConfig:
    browser: chromium
    viewport:
      width: 1920
      height: 1080

​
Step Types

The browser driver defines the following step types:

​
browser.navigate

Navigate to a URL. 
- id: step_001
  type: browser.navigate
  url: https://example.com/login
  timestamp: 0

​
browser.click

Click on an element. 
- id: step_002
  type: browser.click
  selector: button[type="submit"]
  position:
    x: 150
    y: 300
  timestamp: 1000

​
browser.input

Type into a form field. This is the primary injection point for payloads. 
- id: step_003
  type: browser.input
  selector: input[name="username"]
  value: testuser
  injectable: true # Mark as payload injection point
  timestamp: 1500
Set injectable: true on input steps to mark them as payload injection points. During replay, Vulcn will inject security payloads into these fields.

​
browser.keypress

Press a key or key combination. 
- id: step_004
  type: browser.keypress
  key: Enter
  modifiers:
    - ctrl
  timestamp: 2000

​
browser.scroll

Scroll the page or an element. 
- id: step_005
  type: browser.scroll
  selector: .scrollable-container # Optional, defaults to window
  position:
    x: 0
    y: 500
  timestamp: 2500

​
browser.wait

Wait for a duration (useful for manual session editing). 
- id: step_006
  type: browser.wait
  duration: 1000 # milliseconds
  timestamp: 3000

​
Browser Support

The driver uses a smart fallback strategy:
  1. System Chrome - Uses your installed Chrome browser (zero download)
  2. System Edge - Falls back to Microsoft Edge if Chrome isn’t found
  3. Playwright Browsers - Uses Playwright’s bundled browsers as last resort
Check available browsers: 
vulcn doctor
Install Playwright browsers if needed: 
vulcn install chromium
vulcn install --all

​
Auto-Crawl

The browser driver supports auto-crawl — an automated mode that discovers forms, inputs, and injection points without manual recording. Think of it as a lightweight spider that generates sessions for you.

​
How it Works

  1. Opens a headless browser and navigates to the target URL
  2. Discovers all <form> elements and standalone inputs on the page
  3. Identifies injectable text-like inputs (text, search, url, email, tel, password, textarea)
  4. Finds submit triggers (submit buttons, untyped buttons, or falls back to Enter keypress)
  5. Follows same-origin links with configurable depth (BFS traversal)
  6. Generates a Session per discovered form with navigate → input → submit steps

​
Configuration

OptionTypeDefaultDescription
maxDepthnumber2Maximum link-following depth (0 = target URL only)
maxPagesnumber20Maximum number of pages to crawl
pageTimeoutnumber10000Page load timeout in milliseconds
sameOriginbooleantrueOnly follow links to the same origin

​
CLI Usage

# Auto-crawl instead of manual recording
vulcn record https://example.com --auto

# With depth control
vulcn record https://example.com --auto --depth 3 --max-pages 50

​
Programmatic Usage

import { DriverManager } from "@vulcn/engine";
import browserDriver from "@vulcn/driver-browser";

const manager = new DriverManager();
manager.register(browserDriver);

// Auto-discover forms
const sessions = await manager.crawl(
  "browser",
  {
    startUrl: "https://example.com",
    browser: "chromium",
    headless: true,
  },
  {
    maxDepth: 2,
    maxPages: 20,
  },
);

console.log(`Found ${sessions.length} injectable forms`);

// Execute each session with payloads
for (const session of sessions) {
  const result = await manager.execute(session, pluginManager);
  console.log(`${session.name}: ${result.findings.length} findings`);
}

​
Direct Access

You can also use the crawler directly without going through the engine: 
import { crawlAndBuildSessions } from "@vulcn/driver-browser";

const sessions = await crawlAndBuildSessions(
  { startUrl: "https://example.com", headless: true },
  { maxDepth: 1, maxPages: 5 },
);
Auto-crawl generates sessions with injectable: true on all discovered text inputs. During replay, Vulcn injects payloads into these fields and triggers the form submission.

​
Programmatic Usage

​
Recording

import browserDriver from "@vulcn/driver-browser";

// Start recording
const handle = await browserDriver.recorder.start(
  {
    startUrl: "https://example.com",
    browser: "chromium",
    headless: false,
  },
  {},
);

// Wait for user interaction...

// Stop and get session
const session = await handle.stop();
console.log(session.steps);

​
Running

import { driverManager, pluginManager } from "@vulcn/engine";
import browserDriver from "@vulcn/driver-browser";
import payloadsPlugin from "@vulcn/plugin-payloads";

// Register driver and plugins
driverManager.register(browserDriver);
pluginManager.addPlugin(payloadsPlugin);
await pluginManager.initialize();

// Execute session
const result = await driverManager.execute(session, pluginManager, {
  headless: true,
  onFinding: (finding) => console.log("Found:", finding.title),
});

console.log(`Found ${result.findings.length} vulnerabilities`);

​
Detection

During replay, the browser driver monitors for:
  • JavaScript Dialogs - alert(), confirm(), prompt() triggered by payloads
  • Console Messages - console.log() outputs matching payload markers
  • Payload Reflection - Payload strings appearing in page content
These detections are enhanced when combined with detection plugins: 
plugins:
  - name: "@vulcn/plugin-detect-xss"
  - name: "@vulcn/plugin-detect-reflection"

​
Example Session

Complete recorded session example: 
name: Login Form Test
driver: browser
driverConfig:
  browser: chromium
  startUrl: https://vulnerable-app.example.com/login
  viewport:
    width: 1280
    height: 720
steps:
  - id: step_001
    type: browser.navigate
    url: https://vulnerable-app.example.com/login
    timestamp: 0

  - id: step_002
    type: browser.input
    selector: "#username"
    value: admin
    injectable: true
    timestamp: 1200

  - id: step_003
    type: browser.input
    selector: "#password"
    value: password123
    injectable: true
    timestamp: 2400

  - id: step_004
    type: browser.click
    selector: button[type="submit"]
    timestamp: 3000

metadata:
  recordedAt: "2026-02-06T12:00:00Z"
  version: "1"

Plugin System

Learn how to add detection plugins for comprehensive vulnerability scanning