cbrowser 18.3.10 → 18.3.11

package/dist/security/audit-wrapper.js

@@ -0,0 +1,433 @@
+/**
+ * CBrowser - Cognitive Browser Automation
+ * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
+ * Learn more at https://cbrowser.ai - MIT License
+ */
+/**
+ * Tool Invocation Audit Wrapper for CBrowser MCP Server
+ *
+ * Provides comprehensive audit logging for all MCP tool invocations.
+ * Captures tool name, parameters (with sensitive value redaction),
+ * timing, results, and links to triggered actions.
+ *
+ * Usage:
+ *   import { wrapToolHandler, createAuditContext } from "./security/audit-wrapper.js";
+ *
+ *   const auditContext = createAuditContext();
+ *   const wrappedHandler = wrapToolHandler(originalHandler, "tool_name", auditContext);
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+// Sensitive parameter patterns - values matching these will be redacted
+const SENSITIVE_PATTERNS = [
+    /password/i,
+    /secret/i,
+    /token/i,
+    /key/i,
+    /credential/i,
+    /auth/i,
+    /apikey/i,
+    /api_key/i,
+    /bearer/i,
+    /private/i,
+    /passphrase/i,
+    /pin/i,
+    /ssn/i,
+    /credit/i,
+    /card/i,
+];
+// Tool zone classifications for security audit categorization
+// Green: Read-only, safe operations
+// Yellow: Potentially modifying state
+// Red: Sensitive operations (credentials, payments)
+// Black: Should not happen in normal operation
+const TOOL_ZONES = {
+    // Green zone - read-only operations
+    screenshot: "green",
+    status: "green",
+    extract: "green",
+    analyze_page: "green",
+    agent_ready_audit: "green",
+    empathy_audit: "green",
+    list_sessions: "green",
+    list_baselines: "green",
+    list_cognitive_personas: "green",
+    persona_traits_list: "green",
+    persona_values_lookup: "green",
+    persona_trait_lookup: "green",
+    visual_baseline: "green",
+    heal_stats: "green",
+    stealth_status: "green",
+    stealth_check: "green",
+    browser_health: "green",
+    perf_baseline: "green",
+    ab_comparison: "green",
+    coverage_map: "green",
+    compare_personas_init: "green",
+    compare_personas_complete: "green",
+    competitive_benchmark: "green",
+    cross_browser_diff: "green",
+    // Yellow zone - state-modifying operations
+    navigate: "yellow",
+    click: "yellow",
+    smart_click: "yellow",
+    fill: "yellow",
+    scroll: "yellow",
+    hover: "yellow",
+    assert: "yellow",
+    save_session: "yellow",
+    load_session: "yellow",
+    delete_session: "yellow",
+    reset_browser: "yellow",
+    browser_recover: "yellow",
+    dismiss_overlay: "yellow",
+    stealth_enable: "yellow",
+    stealth_disable: "yellow",
+    stealth_diagnose: "yellow",
+    cognitive_journey_init: "yellow",
+    cognitive_journey_update_state: "yellow",
+    cognitive_journey_autonomous: "yellow",
+    find_element_by_intent: "yellow",
+    nl_test_inline: "yellow",
+    nl_test_file: "yellow",
+    generate_tests: "yellow",
+    repair_test: "yellow",
+    detect_flaky_tests: "yellow",
+    chaos_test: "yellow",
+    responsive_test: "yellow",
+    cross_browser_test: "yellow",
+    visual_regression: "yellow",
+    perf_regression: "yellow",
+    hunt_bugs: "yellow",
+    // Persona creation - yellow (creates persistent data)
+    persona_create_start: "yellow",
+    persona_create_submit_traits: "yellow",
+    persona_create_from_description: "yellow",
+    persona_create_questionnaire_start: "yellow",
+    persona_create_questionnaire_answer: "yellow",
+    persona_questionnaire_build: "yellow",
+    persona_questionnaire_get: "yellow",
+    persona_category_guidance: "yellow",
+    persona_create_cancel: "yellow",
+    compare_personas: "yellow",
+    // Red zone - sensitive operations
+    set_api_key: "red",
+    clear_api_key: "red",
+    ask_user: "red", // Can be used for phishing
+    // Marketing tools - yellow (external integrations)
+    marketing_audience_discover: "yellow",
+    marketing_campaign_create: "yellow",
+    marketing_campaign_run: "yellow",
+    marketing_campaign_report_result: "yellow",
+    marketing_compete: "yellow",
+    marketing_discover_status: "yellow",
+    marketing_funnel_analyze: "yellow",
+    marketing_influence_matrix: "yellow",
+    marketing_lever_analysis: "yellow",
+    marketing_personas_list: "yellow",
+    list_influence_patterns: "yellow",
+    // Cloudflare/anti-detection - yellow
+    cloudflare_detect: "yellow",
+    cloudflare_wait: "yellow",
+};
+/**
+ * Create an audit context for tool wrapping
+ *
+ * @param options Optional configuration
+ * @returns AuditContext instance
+ */
+export function createAuditContext(options) {
+    const dataDir = process.env.CBROWSER_DATA_DIR || join(homedir(), ".cbrowser");
+    const auditDir = options?.auditDir || join(dataDir, "audit");
+    // Ensure audit directory exists
+    if (!existsSync(auditDir)) {
+        mkdirSync(auditDir, { recursive: true });
+    }
+    return {
+        sessionId: options?.sessionId || randomUUID().slice(0, 8),
+        auditDir,
+        enabled: options?.enabled ?? (process.env.CBROWSER_AUDIT_ENABLED !== "false"),
+        includeStackTraces: options?.includeStackTraces ?? false,
+        actionsTriggered: new Map(),
+    };
+}
+/**
+ * Redact sensitive values from parameters
+ *
+ * @param params The parameters object to redact
+ * @returns Copy of params with sensitive values replaced with "[REDACTED]"
+ */
+export function redactSensitiveParams(params) {
+    const redacted = {};
+    for (const [key, value] of Object.entries(params)) {
+        // Check if key matches sensitive pattern
+        const isSensitive = SENSITIVE_PATTERNS.some((pattern) => pattern.test(key));
+        // Process arrays and objects recursively (even if key is sensitive)
+        // This allows nested structures to have their own sensitive fields redacted
+        if (Array.isArray(value)) {
+            // Handle arrays - check each element recursively
+            redacted[key] = value.map((item) => {
+                if (typeof item === "object" && item !== null) {
+                    return redactSensitiveParams(item);
+                }
+                // Redact primitive values in arrays if parent key is sensitive
+                return isSensitive ? "[REDACTED]" : item;
+            });
+        }
+        else if (typeof value === "object" && value !== null) {
+            // Recursively redact nested objects
+            redacted[key] = redactSensitiveParams(value);
+        }
+        else if (isSensitive && value !== undefined && value !== null) {
+            // Redact primitive sensitive values
+            redacted[key] = "[REDACTED]";
+        }
+        else {
+            redacted[key] = value;
+        }
+    }
+    return redacted;
+}
+/**
+ * Get the zone classification for a tool
+ *
+ * @param toolName The name of the tool
+ * @returns ActionZone classification
+ */
+export function getToolZone(toolName) {
+    return TOOL_ZONES[toolName] || "yellow"; // Default to yellow for unknown tools
+}
+/**
+ * Get the audit log file path for the current date
+ *
+ * @param auditDir The audit directory path
+ * @returns Path to the tool invocations audit file
+ */
+function getAuditFilePath(auditDir) {
+    const date = new Date().toISOString().split("T")[0];
+    return join(auditDir, `tool-invocations-${date}.json`);
+}
+/**
+ * Write an audit entry to the log file
+ *
+ * @param entry The audit entry to write
+ * @param auditDir The audit directory path
+ */
+function writeAuditEntry(entry, auditDir) {
+    const filePath = getAuditFilePath(auditDir);
+    let entries = [];
+    if (existsSync(filePath)) {
+        try {
+            entries = JSON.parse(readFileSync(filePath, "utf-8"));
+        }
+        catch {
+            // If file is corrupted, start fresh
+            entries = [];
+        }
+    }
+    entries.push(entry);
+    writeFileSync(filePath, JSON.stringify(entries, null, 2));
+}
+/**
+ * Wrap a tool handler with audit logging
+ *
+ * This wraps any MCP tool handler to automatically:
+ * - Generate a unique request ID
+ * - Log the tool name and (redacted) parameters
+ * - Time the execution
+ * - Capture success/failure status
+ * - Write to the audit log
+ *
+ * @param handler The original tool handler function
+ * @param toolName The name of the tool being wrapped
+ * @param context The audit context
+ * @returns A wrapped handler with identical signature
+ *
+ * @example
+ * ```typescript
+ * const context = createAuditContext();
+ *
+ * server.tool(
+ *   "navigate",
+ *   "Navigate to a URL",
+ *   { url: z.string().url() },
+ *   wrapToolHandler(
+ *     async ({ url }) => {
+ *       await browser.navigate(url);
+ *       return { content: [{ type: "text", text: "Navigated" }] };
+ *     },
+ *     "navigate",
+ *     context
+ *   )
+ * );
+ * ```
+ */
+export function wrapToolHandler(handler, toolName, context) {
+    return async (params) => {
+        // Skip logging if disabled
+        if (!context.enabled) {
+            return handler(params);
+        }
+        const requestId = randomUUID();
+        const startTime = Date.now();
+        const zone = getToolZone(toolName);
+        // Initialize actions tracking for this request
+        context.actionsTriggered.set(requestId, []);
+        let result = "success";
+        let error;
+        try {
+            const response = await handler(params);
+            return response;
+        }
+        catch (err) {
+            result = "failure";
+            error = err instanceof Error ? err.message : String(err);
+            if (context.includeStackTraces && err instanceof Error && err.stack) {
+                error = `${error}\n${err.stack}`;
+            }
+            throw err;
+        }
+        finally {
+            const duration = Date.now() - startTime;
+            const actionsTriggered = context.actionsTriggered.get(requestId) || [];
+            context.actionsTriggered.delete(requestId);
+            const entry = {
+                timestamp: new Date().toISOString(),
+                sessionId: context.sessionId,
+                requestId,
+                tool: toolName,
+                parameters: redactSensitiveParams(params),
+                zone,
+                result,
+                duration,
+                error,
+                actionsTriggered,
+            };
+            try {
+                writeAuditEntry(entry, context.auditDir);
+            }
+            catch (writeErr) {
+                // Don't let audit logging failures break tool execution
+                console.error(`[CBrowser Audit] Failed to write audit entry: ${writeErr instanceof Error ? writeErr.message : String(writeErr)}`);
+            }
+        }
+    };
+}
+/**
+ * Link an action to the current tool invocation
+ *
+ * Call this from within browser actions to link them to the triggering tool call.
+ *
+ * @param context The audit context
+ * @param requestId The request ID of the tool invocation
+ * @param actionId The ID of the triggered action (from AuditEntry)
+ */
+export function linkActionToInvocation(context, requestId, actionId) {
+    const actions = context.actionsTriggered.get(requestId);
+    if (actions) {
+        actions.push(actionId);
+    }
+}
+/**
+ * Create a wrapper factory for a specific audit context
+ *
+ * This is useful when registering many tools with the same context.
+ *
+ * @param context The audit context
+ * @returns A function that wraps handlers with the given context
+ *
+ * @example
+ * ```typescript
+ * const context = createAuditContext();
+ * const wrap = createWrapperFactory(context);
+ *
+ * server.tool("navigate", "...", schema, wrap(navigateHandler, "navigate"));
+ * server.tool("click", "...", schema, wrap(clickHandler, "click"));
+ * ```
+ */
+export function createWrapperFactory(context) {
+    return (handler, toolName) => wrapToolHandler(handler, toolName, context);
+}
+/**
+ * Read audit entries for a specific date
+ *
+ * @param auditDir The audit directory path
+ * @param date ISO date string (YYYY-MM-DD) or Date object
+ * @returns Array of tool invocation entries
+ */
+export function readAuditEntries(auditDir, date) {
+    const dateStr = date
+        ? typeof date === "string"
+            ? date
+            : date.toISOString().split("T")[0]
+        : new Date().toISOString().split("T")[0];
+    const filePath = join(auditDir, `tool-invocations-${dateStr}.json`);
+    if (!existsSync(filePath)) {
+        return [];
+    }
+    try {
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get audit statistics for a date range
+ *
+ * @param auditDir The audit directory path
+ * @param startDate Start date (inclusive)
+ * @param endDate End date (inclusive), defaults to today
+ * @returns Audit statistics
+ */
+export function getAuditStats(auditDir, startDate, endDate) {
+    const end = endDate || new Date();
+    const start = startDate || new Date(end.getTime() - 7 * 24 * 60 * 60 * 1000); // Default to last 7 days
+    const stats = {
+        totalInvocations: 0,
+        successCount: 0,
+        failureCount: 0,
+        blockedCount: 0,
+        byTool: {},
+        byZone: { green: 0, yellow: 0, red: 0, black: 0 },
+        avgDuration: 0,
+        sessions: [],
+    };
+    let totalDuration = 0;
+    const sessionsSet = new Set();
+    // Iterate through dates in range
+    const current = new Date(start);
+    while (current <= end) {
+        const entries = readAuditEntries(auditDir, current);
+        for (const entry of entries) {
+            stats.totalInvocations++;
+            totalDuration += entry.duration;
+            sessionsSet.add(entry.sessionId);
+            // Count by result
+            switch (entry.result) {
+                case "success":
+                    stats.successCount++;
+                    break;
+                case "failure":
+                    stats.failureCount++;
+                    break;
+                case "blocked":
+                    stats.blockedCount++;
+                    break;
+            }
+            // Count by tool
+            stats.byTool[entry.tool] = (stats.byTool[entry.tool] || 0) + 1;
+            // Count by zone
+            stats.byZone[entry.zone]++;
+        }
+        current.setDate(current.getDate() + 1);
+    }
+    stats.avgDuration = stats.totalInvocations > 0
+        ? Math.round(totalDuration / stats.totalInvocations)
+        : 0;
+    stats.sessions = Array.from(sessionsSet);
+    return stats;
+}
+//# sourceMappingURL=audit-wrapper.js.map

package/dist/security/audit-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-wrapper.js","sourceRoot":"","sources":["../../src/security/audit-wrapper.ts"],"names":[],"mappings":"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"}

package/dist/security/description-scanner.d.ts

@@ -0,0 +1,132 @@
+/**
+ * CBrowser - Cognitive Browser Automation
+ * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
+ * Learn more at https://cbrowser.ai - MIT License
+ */
+import type { ToolDefinition } from "./tool-pinning.js";
+/**
+ * Severity levels for scan issues
+ * - info: Informational, not necessarily problematic
+ * - warning: Potentially suspicious, warrants review
+ * - critical: Highly likely malicious, should be blocked
+ */
+export type ScanSeverity = "info" | "warning" | "critical";
+/**
+ * A single issue detected in a tool description
+ */
+export interface ScanIssue {
+    /** Pattern category that matched (e.g., "cross_tool_instruction") */
+    pattern: string;
+    /** Severity level of this issue */
+    severity: ScanSeverity;
+    /** The actual text that matched the pattern */
+    match: string;
+    /** Character position in the description where match was found */
+    position?: number;
+}
+/**
+ * Result of scanning a single tool's description
+ */
+export interface ToolScanResult {
+    /** Name of the tool that was scanned */
+    toolName: string;
+    /** Overall status based on highest severity issue found */
+    status: "clean" | "warning" | "critical";
+    /** List of issues found in the description */
+    issues: ScanIssue[];
+}
+/**
+ * Result of scanning all tools on an MCP server
+ */
+export interface ServerScanResult {
+    /** Name of the server that was scanned */
+    serverName: string;
+    /** Total number of tools scanned */
+    toolCount: number;
+    /** Overall status based on worst tool status */
+    status: "clean" | "warning" | "critical";
+    /** List of tools that had issues (excludes clean tools) */
+    issues: ToolScanResult[];
+}
+/**
+ * Summary of scanning multiple MCP servers
+ */
+export interface ScanSummary {
+    /** Results for each server scanned */
+    servers: ServerScanResult[];
+    /** Aggregate statistics */
+    summary: {
+        /** Total tools scanned across all servers */
+        total: number;
+        /** Tools with no issues */
+        clean: number;
+        /** Tools with warning-level issues */
+        warning: number;
+        /** Tools with critical-level issues */
+        critical: number;
+    };
+}
+/**
+ * Scan a single tool's description for injection patterns.
+ *
+ * @param name - The tool's name
+ * @param description - The tool's description text
+ * @returns Scan result with status and any issues found
+ *
+ * @example
+ * ```typescript
+ * const result = scanToolDescription("navigate", "Navigate to a URL");
+ * if (result.status !== "clean") {
+ *   console.warn("Issues found:", result.issues);
+ * }
+ * ```
+ */
+export declare function scanToolDescription(name: string, description: string): ToolScanResult;
+/**
+ * Scan an array of tool definitions for injection patterns.
+ *
+ * @param tools - Array of tool definitions to scan
+ * @param serverName - Name of the server (optional, defaults to "unknown")
+ * @returns Server scan result with aggregate status
+ *
+ * @example
+ * ```typescript
+ * const tools = [
+ *   { name: "navigate", description: "Navigate to URL", schema: {} },
+ *   { name: "click", description: "Click element", schema: {} },
+ * ];
+ * const result = scanToolDefinitions(tools, "cbrowser");
+ * console.log("Server status:", result.status);
+ * ```
+ */
+export declare function scanToolDefinitions(tools: ToolDefinition[], serverName?: string): ServerScanResult;
+/**
+ * Scan MCP configuration file for all registered servers.
+ * Currently this function parses the config but cannot actually
+ * scan tool descriptions without starting the servers.
+ *
+ * @param configPath - Path to claude_desktop_config.json
+ * @returns Scan summary with results for each server
+ *
+ * @example
+ * ```typescript
+ * const summary = scanMcpConfig("~/.config/claude/claude_desktop_config.json");
+ * console.log("Total issues:", summary.summary.critical + summary.summary.warning);
+ * ```
+ */
+export declare function scanMcpConfig(configPath: string): ScanSummary;
+/**
+ * Get a formatted report of scan results.
+ *
+ * @param result - Server scan result to format
+ * @returns Human-readable report string
+ */
+export declare function formatScanReport(result: ServerScanResult): string;
+/**
+ * Quick check if a description is safe (no critical issues).
+ *
+ * @param description - Description text to check
+ * @returns true if no critical issues found
+ */
+export declare function isDescriptionSafe(description: string): boolean;
+//# sourceMappingURL=description-scanner.d.ts.map

package/dist/security/description-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"description-scanner.d.ts","sourceRoot":"","sources":["../../src/security/description-scanner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqBH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMxD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,QAAQ,EAAE,YAAY,CAAC;IACvB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC;IACzC,8CAA8C;IAC9C,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC;IACzC,2DAA2D;IAC3D,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,2BAA2B;IAC3B,OAAO,EAAE;QACP,6CAA6C;QAC7C,KAAK,EAAE,MAAM,CAAC;QACd,2BAA2B;QAC3B,KAAK,EAAE,MAAM,CAAC;QACd,sCAAsC;QACtC,OAAO,EAAE,MAAM,CAAC;QAChB,uCAAuC;QACvC,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AA+ND;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,cAAc,CAgChB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,EAAE,EACvB,UAAU,GAAE,MAAkB,GAC7B,gBAAgB,CAwBlB;AAgBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CAgD7D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CA2BjE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAG9D"}