@vulcn/engine 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Page, Browser } from 'playwright';
+import { Page, Dialog, ConsoleMessage, Request, Response, Browser } from 'playwright';
 import { z } from 'zod';
 
 declare const StepSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
@@ -417,6 +417,53 @@ declare function parseSession(yaml: string): Session;
  */
 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;
@@ -432,7 +479,7 @@ interface RunnerOptions {
     onFinding?: (finding: Finding) => void;
 }
 interface Finding {
-    type: "xss" | "sqli" | "ssrf" | "path-traversal" | "custom";
+    type: PayloadCategory;
     severity: "critical" | "high" | "medium" | "low" | "info";
     title: string;
     description: string;
@@ -440,6 +487,8 @@ interface Finding {
     payload: string;
     url: string;
     evidence?: string;
+    /** Plugin-specific metadata */
+    metadata?: Record<string, unknown>;
 }
 interface RunResult {
     findings: Finding[];
@@ -449,6 +498,302 @@ interface RunResult {
     errors: string[];
 }
 
+/**
+ * Vulcn Plugin System Types
+ * @module @vulcn/engine/plugin
+ */
+
+/**
+ * Plugin API version - plugins declare compatibility
+ */
+declare const PLUGIN_API_VERSION = 1;
+/**
+ * Plugin source types for identification
+ */
+type PluginSource = "builtin" | "npm" | "local" | "custom";
+/**
+ * Main plugin interface
+ */
+interface VulcnPlugin {
+    /** Unique plugin name (e.g., "@vulcn/plugin-payloads") */
+    name: string;
+    /** Plugin version (semver) */
+    version: string;
+    /** Plugin API version this plugin targets */
+    apiVersion?: number;
+    /** Human-readable description */
+    description?: string;
+    /** Lifecycle hooks */
+    hooks?: PluginHooks;
+    /**
+     * Payloads provided by this plugin (Loaders)
+     * Can be static array or async function for lazy loading
+     */
+    payloads?: RuntimePayload[] | (() => Promise<RuntimePayload[]>);
+    /**
+     * Zod schema for plugin configuration validation
+     */
+    configSchema?: z.ZodSchema;
+}
+/**
+ * Plugin lifecycle hooks
+ */
+interface PluginHooks {
+    /**
+     * Called when plugin is loaded, before any operation
+     * Use for setup, loading payloads, etc.
+     */
+    onInit?: (ctx: PluginContext) => Promise<void>;
+    /**
+     * Called when plugin is unloaded/cleanup
+     */
+    onDestroy?: (ctx: PluginContext) => Promise<void>;
+    /** Called when recording starts */
+    onRecordStart?: (ctx: RecordContext) => Promise<void>;
+    /** Called for each recorded step, can transform */
+    onRecordStep?: (step: Step, ctx: RecordContext) => Promise<Step>;
+    /** Called when recording ends, can transform session */
+    onRecordEnd?: (session: Session, ctx: RecordContext) => Promise<Session>;
+    /** Called when run starts */
+    onRunStart?: (ctx: RunContext) => Promise<void>;
+    /** Called before each payload is injected, can transform payload */
+    onBeforePayload?: (payload: string, step: Step, ctx: RunContext) => 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>;
+    /** Called on page load/navigation */
+    onPageLoad?: (page: Page, ctx: DetectContext) => Promise<Finding[]>;
+    /** Called when JavaScript alert/confirm/prompt appears */
+    onDialog?: (dialog: Dialog, ctx: DetectContext) => Promise<Finding | null>;
+    /** Called on console.log/warn/error */
+    onConsoleMessage?: (msg: ConsoleMessage, ctx: DetectContext) => Promise<Finding | null>;
+    /** Called on network request */
+    onNetworkRequest?: (request: Request, ctx: DetectContext) => Promise<Finding | null>;
+    /** Called on network response */
+    onNetworkResponse?: (response: Response, ctx: DetectContext) => Promise<Finding | null>;
+}
+/**
+ * Logger interface for plugins
+ */
+interface PluginLogger {
+    debug: (msg: string, ...args: unknown[]) => void;
+    info: (msg: string, ...args: unknown[]) => void;
+    warn: (msg: string, ...args: unknown[]) => void;
+    error: (msg: string, ...args: unknown[]) => void;
+}
+/**
+ * Engine information exposed to plugins
+ */
+interface EngineInfo {
+    version: string;
+    pluginApiVersion: number;
+}
+/**
+ * Base context available to all plugin hooks
+ */
+interface PluginContext {
+    /** Plugin-specific config from vulcn.config.yml */
+    config: Record<string, unknown>;
+    /** Engine information */
+    engine: EngineInfo;
+    /** Shared payload registry - loaders add payloads here */
+    payloads: RuntimePayload[];
+    /** Shared findings collection - detectors add findings here */
+    findings: Finding[];
+    /** Scoped logger */
+    logger: PluginLogger;
+    /** Fetch API for network requests */
+    fetch: typeof fetch;
+}
+/**
+ * Context for recording phase hooks
+ */
+interface RecordContext extends PluginContext {
+    /** Starting URL */
+    startUrl: string;
+    /** Browser type being used */
+    browser: BrowserType;
+    /** Playwright page instance */
+    page: Page;
+}
+/**
+ * Context for running phase hooks
+ */
+interface RunContext extends PluginContext {
+    /** Session being executed */
+    session: Session;
+    /** Playwright page instance */
+    page: Page;
+    /** Browser type being used */
+    browser: BrowserType;
+    /** Whether running headless */
+    headless: boolean;
+}
+/**
+ * Context for detection hooks
+ */
+interface DetectContext extends RunContext {
+    /** Current step being tested */
+    step: Step;
+    /** Current payload set being tested */
+    payloadSet: RuntimePayload;
+    /** Actual payload value injected */
+    payloadValue: string;
+    /** Step ID for reporting */
+    stepId: string;
+}
+/**
+ * Plugin configuration in vulcn.config.yml
+ */
+interface PluginConfig {
+    /** Plugin name/path */
+    name: string;
+    /** Plugin-specific configuration */
+    config?: Record<string, unknown>;
+    /** Whether plugin is enabled (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Vulcn configuration file schema
+ */
+interface VulcnConfig {
+    /** Config version */
+    version: string;
+    /** Plugins to load */
+    plugins?: PluginConfig[];
+    /** Global settings */
+    settings?: {
+        browser?: BrowserType;
+        headless?: boolean;
+        timeout?: number;
+    };
+}
+/**
+ * Loaded plugin instance with resolved config
+ */
+interface LoadedPlugin {
+    /** Plugin definition */
+    plugin: VulcnPlugin;
+    /** Resolved configuration */
+    config: Record<string, unknown>;
+    /** Source of the plugin */
+    source: PluginSource;
+    /** Whether plugin is enabled */
+    enabled: boolean;
+}
+
+/**
+ * Vulcn Plugin Manager
+ * Handles plugin loading, lifecycle, and hook execution
+ */
+
+/**
+ * Plugin Manager - loads, configures, and orchestrates plugins
+ */
+declare class PluginManager {
+    private plugins;
+    private config;
+    private initialized;
+    /**
+     * Shared context passed to all plugins
+     */
+    private sharedPayloads;
+    private sharedFindings;
+    /**
+     * Load configuration from vulcn.config.yml
+     */
+    loadConfig(configPath?: string): Promise<VulcnConfig>;
+    /**
+     * Load all plugins from config
+     */
+    loadPlugins(): Promise<void>;
+    /**
+     * Load a single plugin
+     */
+    private loadPlugin;
+    /**
+     * Validate plugin structure
+     */
+    private validatePlugin;
+    /**
+     * Add a plugin programmatically (for testing or dynamic loading)
+     */
+    addPlugin(plugin: VulcnPlugin, config?: Record<string, unknown>): void;
+    /**
+     * Initialize all plugins (call onInit hooks)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Destroy all plugins (call onDestroy hooks)
+     */
+    destroy(): Promise<void>;
+    /**
+     * Get all loaded payloads
+     */
+    getPayloads(): RuntimePayload[];
+    /**
+     * Get all collected findings
+     */
+    getFindings(): Finding[];
+    /**
+     * Add a finding (used by detectors)
+     */
+    addFinding(finding: Finding): void;
+    /**
+     * Add payloads (used by loaders)
+     */
+    addPayloads(payloads: RuntimePayload[]): void;
+    /**
+     * Clear findings (for new run)
+     */
+    clearFindings(): void;
+    /**
+     * Get loaded plugins
+     */
+    getPlugins(): LoadedPlugin[];
+    /**
+     * Check if a plugin is loaded by name
+     */
+    hasPlugin(name: string): boolean;
+    /**
+     * Create base context for plugins
+     */
+    createContext(pluginConfig: Record<string, unknown>): PluginContext;
+    /**
+     * Create scoped logger for a plugin
+     */
+    private createLogger;
+    /**
+     * Call a hook on all plugins sequentially
+     */
+    callHook<K extends keyof PluginHooks>(hookName: K, executor: (hook: NonNullable<PluginHooks[K]>, ctx: PluginContext) => Promise<unknown>): Promise<void>;
+    /**
+     * Call a hook and collect results
+     */
+    callHookCollect<K extends keyof PluginHooks, R>(hookName: K, executor: (hook: NonNullable<PluginHooks[K]>, ctx: PluginContext) => Promise<R | R[] | null>): Promise<R[]>;
+    /**
+     * Call a hook that transforms a value through the pipeline
+     */
+    callHookPipe<T>(hookName: keyof PluginHooks, initial: T, executor: (hook: NonNullable<PluginHooks[typeof hookName]>, value: T, ctx: PluginContext) => Promise<T>): Promise<T>;
+}
+/**
+ * Default shared plugin manager instance
+ */
+declare const pluginManager: PluginManager;
+
+/**
+ * Recorder - captures browser interactions as a replayable session
+ * v0.2.0: Plugin hooks for recording customization
+ */
+
+/**
+ * Configuration for the recorder
+ */
+interface RecorderConfig {
+    /** Plugin manager to use (defaults to shared instance) */
+    pluginManager?: PluginManager;
+}
 /**
  * Active recording session handle
  */
@@ -462,53 +807,70 @@ interface RecordingSession {
 }
 /**
  * Recorder - captures browser interactions as a replayable session
+ *
+ * Uses plugin hooks for:
+ * - onRecordStart: Called when recording starts
+ * - onRecordStep: Called for each step, can transform
+ * - onRecordEnd: Called when recording ends, can transform session
  */
 declare class Recorder {
     /**
      * Start a new recording session
      * Opens a browser window for the user to interact with
      */
-    static start(startUrl: string, options?: RecorderOptions): Promise<RecordingSession>;
+    static start(startUrl: string, options?: RecorderOptions, config?: RecorderConfig): Promise<RecordingSession>;
+    /**
+     * Transform a step through plugin hooks
+     * Returns null if the step should be filtered out
+     */
+    private static transformStep;
     private static attachListeners;
     private static injectRecordingScript;
 }
 
 /**
- * Built-in security payloads
- */
-type PayloadCategory = "xss" | "sqli" | "ssrf" | "path-traversal";
-type PayloadName = "xss-basic" | "xss-event" | "xss-svg" | "sqli-basic" | "sqli-error" | "sqli-blind";
-interface Payload {
-    name: PayloadName;
-    category: PayloadCategory;
-    payloads: string[];
-    detectPatterns: RegExp[];
-    description: string;
-}
-declare const BUILTIN_PAYLOADS: Record<PayloadName, Payload>;
-/**
- * Get payloads by name
- */
-declare function getPayload(name: PayloadName): Payload | undefined;
-/**
- * Get all payload names
- */
-declare function getPayloadNames(): PayloadName[];
-/**
- * Get payloads by category
+ * Runner - replays sessions with security payloads
+ * v0.2.0: Plugin-based architecture for extensibility
  */
-declare function getPayloadsByCategory(category: PayloadCategory): Payload[];
 
+interface RunnerConfig {
+    /** Plugin manager to use (defaults to shared instance) */
+    pluginManager?: PluginManager;
+}
 /**
  * Runner - replays sessions with security payloads
+ *
+ * Uses plugin hooks for:
+ * - Payload loading (onInit)
+ * - Payload transformation (onBeforePayload)
+ * - Vulnerability detection (onAfterPayload, onDialog, onConsoleMessage, etc.)
+ * - Results processing (onRunEnd)
  */
 declare class Runner {
     /**
-     * Execute a session with security payloads
+     * Execute a session with security payloads from plugins
+     *
+     * @param session - The recorded session to replay
+     * @param options - Runner configuration
+     * @param config - Plugin manager configuration
+     */
+    static execute(session: Session, options?: RunnerOptions, config?: RunnerConfig): Promise<RunResult>;
+    /**
+     * Execute with explicit payloads (legacy API, for backwards compatibility)
+     */
+    static executeWithPayloads(session: Session, payloads: RuntimePayload[], options?: RunnerOptions): Promise<RunResult>;
+    /**
+     * Replay session steps with payload injected at target step
      */
-    static execute(session: Session, payloadNames: PayloadName[], options?: RunnerOptions): Promise<RunResult>;
     private static replayWithPayload;
-    private static checkForVulnerability;
+    /**
+     * Basic reflection check - fallback when no detection plugin is loaded
+     */
+    private static checkReflection;
+    /**
+     * Determine severity based on vulnerability category
+     */
+    private static getSeverity;
 }
 
 interface LaunchOptions {
@@ -543,4 +905,4 @@ declare function checkBrowsers(): Promise<{
     playwrightWebkit: boolean;
 }>;
 
-export { BUILTIN_PAYLOADS, type BrowserLaunchResult, BrowserNotFoundError, type BrowserType, type Finding, type LaunchOptions, type Payload, type PayloadCategory, type PayloadName, Recorder, type RecorderOptions, type RecordingSession, type RunResult, Runner, type RunnerOptions, type Session, SessionSchema, type Step, StepSchema, checkBrowsers, createSession, getPayload, getPayloadNames, getPayloadsByCategory, installBrowsers, launchBrowser, parseSession, serializeSession };
+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 };