@vulcn/engine 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,86 @@
-import { Page, Dialog, ConsoleMessage, Request, Response, Browser } from 'playwright';
 import { z } from 'zod';
+import { Page, Dialog, ConsoleMessage, Request, Response, Browser } from 'playwright';
+
+/**
+ * Payload Types for Vulcn
+ * Core types used by the engine and plugins
+ */
+/**
+ * Valid payload categories
+ */
+type PayloadCategory = "xss" | "sqli" | "ssrf" | "xxe" | "command-injection" | "path-traversal" | "open-redirect" | "reflection" | "custom";
+/**
+ * Payload source types
+ */
+type PayloadSource = "builtin" | "custom" | "payloadbox" | "plugin";
+/**
+ * Runtime payload structure - used by plugins and the runner
+ */
+interface RuntimePayload {
+    /** Unique payload name */
+    name: string;
+    /** Vulnerability category */
+    category: PayloadCategory;
+    /** Human-readable description */
+    description: string;
+    /** Array of payload strings to inject */
+    payloads: string[];
+    /** Patterns to detect vulnerability (as RegExp) */
+    detectPatterns: RegExp[];
+    /** Where this payload came from */
+    source: PayloadSource;
+}
+/**
+ * Custom payload schema for YAML/JSON files (used by loader plugins)
+ */
+interface CustomPayload {
+    name: string;
+    category: PayloadCategory;
+    description?: string;
+    payloads: string[];
+    detectPatterns?: string[];
+}
+/**
+ * Custom payload file schema
+ */
+interface CustomPayloadFile {
+    version?: string;
+    payloads: CustomPayload[];
+}
+
+type BrowserType = "chromium" | "firefox" | "webkit";
+interface RecorderOptions {
+    browser?: BrowserType;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    headless?: boolean;
+}
+interface RunnerOptions {
+    browser?: BrowserType;
+    headless?: boolean;
+    onFinding?: (finding: Finding) => void;
+}
+interface Finding {
+    type: PayloadCategory;
+    severity: "critical" | "high" | "medium" | "low" | "info";
+    title: string;
+    description: string;
+    stepId: string;
+    payload: string;
+    url: string;
+    evidence?: string;
+    /** Plugin-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+interface RunResult$1 {
+    findings: Finding[];
+    stepsExecuted: number;
+    payloadsTested: number;
+    duration: number;
+    errors: string[];
+}
 
 declare const StepSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     id: z.ZodString;
@@ -137,7 +218,7 @@ declare const StepSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     timestamp: number;
     duration: number;
 }>]>;
-type Step = z.infer<typeof StepSchema>;
+type Step$1 = z.infer<typeof StepSchema>;
 declare const SessionSchema: z.ZodObject<{
     version: z.ZodDefault<z.ZodString>;
     name: z.ZodString;
@@ -395,7 +476,7 @@ declare const SessionSchema: z.ZodObject<{
     version?: string | undefined;
     browser?: "chromium" | "firefox" | "webkit" | undefined;
 }>;
-type Session = z.infer<typeof SessionSchema>;
+type Session$1 = z.infer<typeof SessionSchema>;
 /**
  * Create a new session object
  */
@@ -407,96 +488,15 @@ declare function createSession(options: {
         width: number;
         height: number;
     };
-}): Session;
+}): Session$1;
 /**
  * Parse a session from YAML string
  */
-declare function parseSession(yaml: string): Session;
+declare function parseSession(yaml: string): Session$1;
 /**
  * Serialize a session to YAML string
  */
-declare function serializeSession(session: Session): string;
-
-/**
- * Payload Types for Vulcn
- * Core types used by the engine and plugins
- */
-/**
- * Valid payload categories
- */
-type PayloadCategory = "xss" | "sqli" | "ssrf" | "xxe" | "command-injection" | "path-traversal" | "open-redirect" | "reflection" | "custom";
-/**
- * Payload source types
- */
-type PayloadSource = "builtin" | "custom" | "payloadbox" | "plugin";
-/**
- * Runtime payload structure - used by plugins and the runner
- */
-interface RuntimePayload {
-    /** Unique payload name */
-    name: string;
-    /** Vulnerability category */
-    category: PayloadCategory;
-    /** Human-readable description */
-    description: string;
-    /** Array of payload strings to inject */
-    payloads: string[];
-    /** Patterns to detect vulnerability (as RegExp) */
-    detectPatterns: RegExp[];
-    /** Where this payload came from */
-    source: PayloadSource;
-}
-/**
- * Custom payload schema for YAML/JSON files (used by loader plugins)
- */
-interface CustomPayload {
-    name: string;
-    category: PayloadCategory;
-    description?: string;
-    payloads: string[];
-    detectPatterns?: string[];
-}
-/**
- * Custom payload file schema
- */
-interface CustomPayloadFile {
-    version?: string;
-    payloads: CustomPayload[];
-}
-
-type BrowserType = "chromium" | "firefox" | "webkit";
-interface RecorderOptions {
-    browser?: BrowserType;
-    viewport?: {
-        width: number;
-        height: number;
-    };
-    headless?: boolean;
-}
-interface RunnerOptions {
-    browser?: BrowserType;
-    headless?: boolean;
-    onFinding?: (finding: Finding) => void;
-}
-interface Finding {
-    type: PayloadCategory;
-    severity: "critical" | "high" | "medium" | "low" | "info";
-    title: string;
-    description: string;
-    stepId: string;
-    payload: string;
-    url: string;
-    evidence?: string;
-    /** Plugin-specific metadata */
-    metadata?: Record<string, unknown>;
-}
-interface RunResult {
-    findings: Finding[];
-    stepsExecuted: number;
-    payloadsTested: number;
-    duration: number;
-    errors: string[];
-}
+declare function serializeSession(session: Session$1): string;
 
 /**
  * Vulcn Plugin System Types
@@ -551,17 +551,17 @@ interface PluginHooks {
     /** Called when recording starts */
     onRecordStart?: (ctx: RecordContext) => Promise<void>;
     /** Called for each recorded step, can transform */
-    onRecordStep?: (step: Step, ctx: RecordContext) => Promise<Step>;
+    onRecordStep?: (step: Step$1, ctx: RecordContext) => Promise<Step$1>;
     /** Called when recording ends, can transform session */
-    onRecordEnd?: (session: Session, ctx: RecordContext) => Promise<Session>;
+    onRecordEnd?: (session: Session$1, ctx: RecordContext) => Promise<Session$1>;
     /** Called when run starts */
-    onRunStart?: (ctx: RunContext) => Promise<void>;
+    onRunStart?: (ctx: RunContext$1) => Promise<void>;
     /** Called before each payload is injected, can transform payload */
-    onBeforePayload?: (payload: string, step: Step, ctx: RunContext) => Promise<string>;
+    onBeforePayload?: (payload: string, step: Step$1, ctx: RunContext$1) => Promise<string>;
     /** Called after payload injection, for detection */
     onAfterPayload?: (ctx: DetectContext) => Promise<Finding[]>;
     /** Called when run ends, can transform results */
-    onRunEnd?: (result: RunResult, ctx: RunContext) => Promise<RunResult>;
+    onRunEnd?: (result: RunResult$1, ctx: RunContext$1) => Promise<RunResult$1>;
     /** Called on page load/navigation */
     onPageLoad?: (page: Page, ctx: DetectContext) => Promise<Finding[]>;
     /** Called when JavaScript alert/confirm/prompt appears */
@@ -620,9 +620,9 @@ interface RecordContext extends PluginContext {
 /**
  * Context for running phase hooks
  */
-interface RunContext extends PluginContext {
+interface RunContext$1 extends PluginContext {
     /** Session being executed */
-    session: Session;
+    session: Session$1;
     /** Playwright page instance */
     page: Page;
     /** Browser type being used */
@@ -633,9 +633,9 @@ interface RunContext extends PluginContext {
 /**
  * Context for detection hooks
  */
-interface DetectContext extends RunContext {
+interface DetectContext extends RunContext$1 {
     /** Current step being tested */
-    step: Step;
+    step: Step$1;
     /** Current payload set being tested */
     payloadSet: RuntimePayload;
     /** Actual payload value injected */
@@ -782,6 +782,247 @@ declare class PluginManager {
  */
 declare const pluginManager: PluginManager;
 
+/**
+ * Vulcn Driver System
+ *
+ * Drivers handle recording and running sessions for different targets:
+ * - browser: Web applications (Playwright)
+ * - api: REST/HTTP APIs
+ * - cli: Command-line tools
+ *
+ * Each driver implements RecorderDriver and RunnerDriver interfaces.
+ */
+
+/**
+ * Current driver API version
+ */
+declare const DRIVER_API_VERSION = 1;
+/**
+ * Generic step - drivers define their own step types
+ */
+interface Step {
+    /** Unique step ID */
+    id: string;
+    /** Step type (namespaced, e.g., "browser.click", "api.request") */
+    type: string;
+    /** Timestamp when step was recorded */
+    timestamp: number;
+    /** Step-specific data */
+    [key: string]: unknown;
+}
+/**
+ * Generic session format
+ */
+interface Session {
+    /** Session name */
+    name: string;
+    /** Driver that recorded this session */
+    driver: string;
+    /** Driver-specific configuration */
+    driverConfig: Record<string, unknown>;
+    /** Recorded steps */
+    steps: Step[];
+    /** Session metadata */
+    metadata?: {
+        recordedAt?: string;
+        version?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Running context passed to drivers
+ */
+interface RunContext {
+    /** Session being executed */
+    session: Session;
+    /** Plugin manager for calling hooks */
+    pluginManager: PluginManager;
+    /** Available payloads */
+    payloads: RuntimePayload[];
+    /** Collected findings */
+    findings: Finding[];
+    /** Add a finding */
+    addFinding(finding: Finding): void;
+    /** Logger */
+    logger: DriverLogger;
+    /** Running options */
+    options: RunOptions;
+}
+/**
+ * Options for recording
+ */
+interface RecordOptions {
+    /** Driver-specific options */
+    [key: string]: unknown;
+}
+/**
+ * Options for running
+ */
+interface RunOptions {
+    /** Run headless (for visual drivers) */
+    headless?: boolean;
+    /** Callback for findings */
+    onFinding?: (finding: Finding) => void;
+    /** Callback for step completion */
+    onStepComplete?: (stepId: string, payloadCount: number) => void;
+    /** Driver-specific options */
+    [key: string]: unknown;
+}
+/**
+ * Run result
+ */
+interface RunResult {
+    /** All findings */
+    findings: Finding[];
+    /** Steps executed */
+    stepsExecuted: number;
+    /** Payloads tested */
+    payloadsTested: number;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Errors encountered */
+    errors: string[];
+}
+/**
+ * Driver logger
+ */
+interface DriverLogger {
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+}
+/**
+ * Recorder Driver Interface
+ *
+ * Implement this to add recording support for a target type.
+ */
+interface RecorderDriver {
+    /** Start recording and return control handle */
+    start(config: Record<string, unknown>, options: RecordOptions): Promise<RecordingHandle>;
+}
+/**
+ * Handle returned by RecorderDriver.start()
+ */
+interface RecordingHandle {
+    /** Stop recording and return the session */
+    stop(): Promise<Session>;
+    /** Abort recording without saving */
+    abort(): Promise<void>;
+    /** Get current steps (during recording) */
+    getSteps(): Step[];
+    /** Manually add a step */
+    addStep(step: Omit<Step, "id" | "timestamp">): void;
+}
+/**
+ * Runner Driver Interface
+ *
+ * Implement this to add running/replay support for a target type.
+ */
+interface RunnerDriver {
+    /** Execute a session with payloads */
+    execute(session: Session, ctx: RunContext): Promise<RunResult>;
+}
+/**
+ * Complete driver definition
+ */
+interface VulcnDriver {
+    /** Unique driver name (e.g., "browser", "api", "cli") */
+    name: string;
+    /** Driver version */
+    version: string;
+    /** Driver API version */
+    apiVersion?: number;
+    /** Human-readable description */
+    description?: string;
+    /** Configuration schema (Zod) */
+    configSchema?: z.ZodSchema;
+    /** Step types this driver handles */
+    stepTypes: string[];
+    /** Recorder implementation */
+    recorder: RecorderDriver;
+    /** Runner implementation */
+    runner: RunnerDriver;
+}
+/**
+ * Driver source for loading
+ */
+type DriverSource = "npm" | "local" | "builtin";
+/**
+ * Loaded driver with metadata
+ */
+interface LoadedDriver {
+    driver: VulcnDriver;
+    source: DriverSource;
+}
+
+/**
+ * Vulcn Driver Manager
+ *
+ * Handles driver loading, registration, and lifecycle.
+ * Drivers are loaded from npm packages or local files.
+ */
+
+/**
+ * Driver Manager - loads and manages recording/running drivers
+ */
+declare class DriverManager {
+    private drivers;
+    private defaultDriver;
+    /**
+     * Register a driver
+     */
+    register(driver: VulcnDriver, source?: DriverSource): void;
+    /**
+     * Load a driver from npm or local path
+     */
+    load(nameOrPath: string): Promise<void>;
+    /**
+     * Get a loaded driver by name
+     */
+    get(name: string): VulcnDriver | undefined;
+    /**
+     * Get the default driver
+     */
+    getDefault(): VulcnDriver | undefined;
+    /**
+     * Set the default driver
+     */
+    setDefault(name: string): void;
+    /**
+     * Check if a driver is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered drivers
+     */
+    list(): LoadedDriver[];
+    /**
+     * Get driver for a session
+     */
+    getForSession(session: Session): VulcnDriver;
+    /**
+     * Start recording with a driver
+     */
+    startRecording(driverName: string, config: Record<string, unknown>, options?: RecordOptions): Promise<RecordingHandle>;
+    /**
+     * Execute a session
+     */
+    execute(session: Session, pluginManager: PluginManager, options?: RunOptions): Promise<RunResult>;
+    /**
+     * Validate driver structure
+     */
+    private validateDriver;
+    /**
+     * Create a scoped logger for a driver
+     */
+    private createLogger;
+}
+/**
+ * Default driver manager instance
+ */
+declare const driverManager: DriverManager;
+
 /**
  * Recorder - captures browser interactions as a replayable session
  * v0.2.0: Plugin hooks for recording customization
@@ -799,9 +1040,9 @@ interface RecorderConfig {
  */
 interface RecordingSession {
     /** Stop recording and return the session */
-    stop(): Promise<Session>;
+    stop(): Promise<Session$1>;
     /** Get current recorded steps */
-    getSteps(): Step[];
+    getSteps(): Step$1[];
     /** Get the Playwright page (for advanced use) */
     getPage(): Page;
 }
@@ -854,11 +1095,11 @@ declare class Runner {
      * @param options - Runner configuration
      * @param config - Plugin manager configuration
      */
-    static execute(session: Session, options?: RunnerOptions, config?: RunnerConfig): Promise<RunResult>;
+    static execute(session: Session$1, options?: RunnerOptions, config?: RunnerConfig): Promise<RunResult$1>;
     /**
      * Execute with explicit payloads (legacy API, for backwards compatibility)
      */
-    static executeWithPayloads(session: Session, payloads: RuntimePayload[], options?: RunnerOptions): Promise<RunResult>;
+    static executeWithPayloads(session: Session$1, payloads: RuntimePayload[], options?: RunnerOptions): Promise<RunResult$1>;
     /**
      * Replay session steps with payload injected at target step
      */
@@ -905,4 +1146,4 @@ declare function checkBrowsers(): Promise<{
     playwrightWebkit: boolean;
 }>;
 
-export { type BrowserLaunchResult, BrowserNotFoundError, type BrowserType, type CustomPayload, type CustomPayloadFile, type DetectContext, type EngineInfo, type Finding, type LaunchOptions, type LoadedPlugin, PLUGIN_API_VERSION, type PayloadCategory, type PayloadSource, type PluginConfig, type PluginContext, type PluginHooks, type PluginLogger, PluginManager, type PluginSource, type RecordContext, Recorder, type RecorderOptions, type RecordingSession, type RunContext, type RunResult, Runner, type RunnerOptions, type RuntimePayload, type Session, SessionSchema, type Step, StepSchema, type VulcnConfig, type VulcnPlugin, checkBrowsers, createSession, installBrowsers, launchBrowser, parseSession, pluginManager, serializeSession };
+export { type BrowserLaunchResult, BrowserNotFoundError, type BrowserType, type CustomPayload, type CustomPayloadFile, DRIVER_API_VERSION, type DetectContext, type DriverLogger, DriverManager, type DriverSource, type EngineInfo, type Finding, type LaunchOptions, type Session$1 as LegacySession, type Step$1 as LegacyStep, type LoadedDriver, type LoadedPlugin as LoadedPluginInfo, PLUGIN_API_VERSION, type PayloadCategory, type PayloadSource, type PluginConfig, type PluginContext, type PluginHooks, type PluginLogger, PluginManager, type PluginSource, type RecordContext, type RecordOptions, Recorder, type RecorderDriver, type RecorderOptions, type RecordingHandle, type RecordingSession, type RunContext, type RunOptions, type RunResult, Runner, type RunnerDriver, type RunnerOptions, type RuntimePayload, type Session, SessionSchema, type Step, StepSchema, type VulcnConfig, type VulcnDriver, type VulcnPlugin, checkBrowsers, createSession, driverManager, installBrowsers, launchBrowser, parseSession, pluginManager, serializeSession };