llm-trust-guard 4.0.0

package/dist/guards/circuit-breaker.js

@@ -0,0 +1,347 @@
+"use strict";
+/**
+ * CircuitBreaker (L13)
+ *
+ * Prevents cascade failures in agentic workflows.
+ * Implements the circuit breaker pattern for LLM operations.
+ *
+ * Threat Model:
+ * - ASI08: Cascading Failures
+ * - Runaway agent behavior
+ * - Resource exhaustion via retries
+ *
+ * Protection Capabilities:
+ * - Failure rate monitoring
+ * - Automatic circuit opening
+ * - Graceful degradation
+ * - Recovery detection
+ * - Rollback triggers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreaker = void 0;
+class CircuitBreaker {
+    constructor(config = {}) {
+        // Per-circuit state tracking
+        this.circuits = new Map();
+        this.config = {
+            failureThreshold: config.failureThreshold ?? 50,
+            minimumRequests: config.minimumRequests ?? 5,
+            windowSize: config.windowSize ?? 60 * 1000, // 1 minute
+            recoveryTimeout: config.recoveryTimeout ?? 30 * 1000, // 30 seconds
+            successThreshold: config.successThreshold ?? 3,
+            autoRecover: config.autoRecover ?? true,
+            maxConsecutiveFailures: config.maxConsecutiveFailures ?? 5,
+            onOpen: config.onOpen,
+            onClose: config.onClose,
+            onHalfOpen: config.onHalfOpen,
+        };
+    }
+    /**
+     * Check if operation should be allowed through circuit
+     */
+    check(circuitId, requestId) {
+        const reqId = requestId || `cb-${Date.now()}`;
+        const circuit = this.getOrCreateCircuit(circuitId);
+        // Clean old data outside window
+        this.cleanupWindow(circuit);
+        switch (circuit.state) {
+            case "closed":
+                return {
+                    allowed: true,
+                    state: "closed",
+                    reason: "Circuit is closed, operation allowed",
+                    request_id: reqId,
+                    stats: { ...circuit.stats },
+                    fallback_recommended: false,
+                };
+            case "open":
+                // Check if recovery timeout has passed
+                if (circuit.openedAt && Date.now() - circuit.openedAt >= this.config.recoveryTimeout) {
+                    if (this.config.autoRecover) {
+                        this.transitionToHalfOpen(circuitId, circuit);
+                        return {
+                            allowed: true,
+                            state: "half-open",
+                            reason: "Circuit is half-open, testing recovery",
+                            request_id: reqId,
+                            stats: { ...circuit.stats },
+                            fallback_recommended: true,
+                        };
+                    }
+                }
+                const retryAfter = circuit.openedAt
+                    ? Math.max(0, this.config.recoveryTimeout - (Date.now() - circuit.openedAt))
+                    : this.config.recoveryTimeout;
+                return {
+                    allowed: false,
+                    state: "open",
+                    reason: "Circuit is open, operation blocked",
+                    request_id: reqId,
+                    stats: { ...circuit.stats },
+                    fallback_recommended: true,
+                    retry_after: retryAfter,
+                };
+            case "half-open":
+                // Allow limited requests in half-open state
+                return {
+                    allowed: true,
+                    state: "half-open",
+                    reason: "Circuit is half-open, testing recovery",
+                    request_id: reqId,
+                    stats: { ...circuit.stats },
+                    fallback_recommended: true,
+                };
+            default:
+                return {
+                    allowed: false,
+                    state: "open",
+                    reason: "Unknown circuit state",
+                    request_id: reqId,
+                    stats: { ...circuit.stats },
+                    fallback_recommended: true,
+                };
+        }
+    }
+    /**
+     * Record operation result
+     */
+    recordResult(circuitId, result) {
+        const circuit = this.getOrCreateCircuit(circuitId);
+        const now = Date.now();
+        circuit.requestTimestamps.push(now);
+        circuit.stats.totalRequests++;
+        if (result.success) {
+            circuit.stats.successfulRequests++;
+            circuit.stats.consecutiveSuccesses++;
+            circuit.stats.consecutiveFailures = 0;
+            circuit.stats.lastSuccess = now;
+            // Check for recovery in half-open state
+            if (circuit.state === "half-open") {
+                if (circuit.stats.consecutiveSuccesses >= this.config.successThreshold) {
+                    this.closeCircuit(circuitId, circuit);
+                }
+            }
+        }
+        else {
+            circuit.stats.failedRequests++;
+            circuit.stats.consecutiveFailures++;
+            circuit.stats.consecutiveSuccesses = 0;
+            circuit.stats.lastFailure = now;
+            circuit.failureTimestamps.push(now);
+            // Check for circuit opening conditions
+            if (circuit.state === "closed" || circuit.state === "half-open") {
+                // Check consecutive failures
+                if (circuit.stats.consecutiveFailures >= this.config.maxConsecutiveFailures) {
+                    this.openCircuit(circuitId, circuit);
+                    return;
+                }
+                // Check failure rate
+                const windowedFailures = this.countInWindow(circuit.failureTimestamps);
+                const windowedRequests = this.countInWindow(circuit.requestTimestamps);
+                if (windowedRequests >= this.config.minimumRequests) {
+                    const failureRate = (windowedFailures / windowedRequests) * 100;
+                    circuit.stats.failureRate = failureRate;
+                    if (failureRate >= this.config.failureThreshold) {
+                        this.openCircuit(circuitId, circuit);
+                    }
+                }
+            }
+        }
+        // Update failure rate
+        const windowedFailures = this.countInWindow(circuit.failureTimestamps);
+        const windowedRequests = this.countInWindow(circuit.requestTimestamps);
+        circuit.stats.failureRate = windowedRequests > 0
+            ? (windowedFailures / windowedRequests) * 100
+            : 0;
+    }
+    /**
+     * Record a successful operation
+     */
+    recordSuccess(circuitId, duration) {
+        this.recordResult(circuitId, { success: true, duration: duration ?? 0 });
+    }
+    /**
+     * Record a failed operation
+     */
+    recordFailure(circuitId, error, duration) {
+        this.recordResult(circuitId, {
+            success: false,
+            duration: duration ?? 0,
+            error,
+        });
+    }
+    /**
+     * Get current state of a circuit
+     */
+    getState(circuitId) {
+        return this.circuits.get(circuitId)?.state ?? "closed";
+    }
+    /**
+     * Get stats for a circuit
+     */
+    getStats(circuitId) {
+        const circuit = this.circuits.get(circuitId);
+        return circuit ? { ...circuit.stats } : null;
+    }
+    /**
+     * Get all circuit IDs
+     */
+    getCircuitIds() {
+        return [...this.circuits.keys()];
+    }
+    /**
+     * Force open a circuit
+     */
+    forceOpen(circuitId) {
+        const circuit = this.getOrCreateCircuit(circuitId);
+        this.openCircuit(circuitId, circuit);
+    }
+    /**
+     * Force close a circuit
+     */
+    forceClose(circuitId) {
+        const circuit = this.getOrCreateCircuit(circuitId);
+        this.closeCircuit(circuitId, circuit);
+    }
+    /**
+     * Reset a circuit to initial state
+     */
+    reset(circuitId) {
+        this.circuits.delete(circuitId);
+    }
+    /**
+     * Reset all circuits
+     */
+    resetAll() {
+        this.circuits.clear();
+    }
+    /**
+     * Execute operation with circuit breaker protection
+     */
+    async execute(circuitId, operation, fallback) {
+        const checkResult = this.check(circuitId);
+        if (!checkResult.allowed) {
+            if (fallback) {
+                try {
+                    const result = await fallback();
+                    return { result, fallbackUsed: true };
+                }
+                catch (err) {
+                    return {
+                        fallbackUsed: true,
+                        error: `Circuit open and fallback failed: ${err}`,
+                    };
+                }
+            }
+            return {
+                fallbackUsed: false,
+                error: checkResult.reason,
+            };
+        }
+        const startTime = Date.now();
+        try {
+            const result = await operation();
+            this.recordSuccess(circuitId, Date.now() - startTime);
+            return { result, fallbackUsed: false };
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            this.recordFailure(circuitId, error, Date.now() - startTime);
+            // Try fallback if available and circuit is now recommending it
+            const newCheck = this.check(circuitId);
+            if (newCheck.fallback_recommended && fallback) {
+                try {
+                    const result = await fallback();
+                    return { result, fallbackUsed: true };
+                }
+                catch (fallbackErr) {
+                    return {
+                        fallbackUsed: true,
+                        error: `Primary failed: ${error}. Fallback also failed.`,
+                    };
+                }
+            }
+            return { fallbackUsed: false, error };
+        }
+    }
+    /**
+     * Health check across all circuits
+     */
+    healthCheck() {
+        const circuitStatuses = [];
+        let openCircuits = 0;
+        for (const [id, circuit] of this.circuits) {
+            const status = {
+                id,
+                state: circuit.state,
+                failureRate: circuit.stats.failureRate,
+            };
+            circuitStatuses.push(status);
+            if (circuit.state === "open") {
+                openCircuits++;
+            }
+        }
+        return {
+            healthy: openCircuits === 0,
+            circuits: circuitStatuses,
+            openCircuits,
+        };
+    }
+    getOrCreateCircuit(circuitId) {
+        let circuit = this.circuits.get(circuitId);
+        if (!circuit) {
+            circuit = {
+                state: "closed",
+                stats: {
+                    totalRequests: 0,
+                    successfulRequests: 0,
+                    failedRequests: 0,
+                    consecutiveFailures: 0,
+                    consecutiveSuccesses: 0,
+                    failureRate: 0,
+                    stateChangedAt: Date.now(),
+                },
+                requestTimestamps: [],
+                failureTimestamps: [],
+            };
+            this.circuits.set(circuitId, circuit);
+        }
+        return circuit;
+    }
+    openCircuit(circuitId, circuit) {
+        circuit.state = "open";
+        circuit.openedAt = Date.now();
+        circuit.stats.stateChangedAt = Date.now();
+        if (this.config.onOpen) {
+            this.config.onOpen(circuitId, { ...circuit.stats });
+        }
+    }
+    closeCircuit(circuitId, circuit) {
+        circuit.state = "closed";
+        circuit.openedAt = undefined;
+        circuit.stats.stateChangedAt = Date.now();
+        circuit.stats.consecutiveFailures = 0;
+        if (this.config.onClose) {
+            this.config.onClose(circuitId, { ...circuit.stats });
+        }
+    }
+    transitionToHalfOpen(circuitId, circuit) {
+        circuit.state = "half-open";
+        circuit.stats.stateChangedAt = Date.now();
+        circuit.stats.consecutiveSuccesses = 0;
+        if (this.config.onHalfOpen) {
+            this.config.onHalfOpen(circuitId);
+        }
+    }
+    cleanupWindow(circuit) {
+        const cutoff = Date.now() - this.config.windowSize;
+        circuit.requestTimestamps = circuit.requestTimestamps.filter((t) => t > cutoff);
+        circuit.failureTimestamps = circuit.failureTimestamps.filter((t) => t > cutoff);
+    }
+    countInWindow(timestamps) {
+        const cutoff = Date.now() - this.config.windowSize;
+        return timestamps.filter((t) => t > cutoff).length;
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/guards/circuit-breaker.js.map

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

package/dist/guards/code-execution-guard.d.ts

@@ -0,0 +1,114 @@
+/**
+ * CodeExecutionGuard (L11)
+ *
+ * Validates and sandboxes agent-generated code before execution.
+ * Prevents RCE (Remote Code Execution) attacks via malicious code generation.
+ *
+ * Threat Model:
+ * - ASI05: Unexpected Code Execution (RCE)
+ * - Code injection via LLM outputs
+ * - Sandbox escape attempts
+ *
+ * Protection Capabilities:
+ * - Static code analysis for dangerous patterns
+ * - Import/require blocklist enforcement
+ * - System call detection
+ * - Resource limit enforcement
+ * - Language-specific security rules
+ */
+export interface CodeExecutionGuardConfig {
+    /** Allowed programming languages */
+    allowedLanguages?: string[];
+    /** Blocked imports/modules */
+    blockedImports?: string[];
+    /** Blocked function calls */
+    blockedFunctions?: string[];
+    /** Maximum code length in characters */
+    maxCodeLength?: number;
+    /** Maximum execution time in milliseconds */
+    maxExecutionTime?: number;
+    /** Allow network access */
+    allowNetwork?: boolean;
+    /** Allow file system access */
+    allowFileSystem?: boolean;
+    /** Allow shell/subprocess execution */
+    allowShell?: boolean;
+    /** Allow environment variable access */
+    allowEnvAccess?: boolean;
+    /** Custom dangerous patterns */
+    customPatterns?: Array<{
+        name: string;
+        pattern: RegExp;
+        severity: number;
+    }>;
+    /** Risk threshold for blocking (0-100) */
+    riskThreshold?: number;
+}
+export interface CodeAnalysisResult {
+    allowed: boolean;
+    reason: string;
+    violations: string[];
+    request_id: string;
+    code_analysis: {
+        language: string;
+        length: number;
+        dangerous_imports: string[];
+        dangerous_functions: string[];
+        system_calls: string[];
+        network_access: boolean;
+        file_access: boolean;
+        shell_access: boolean;
+        env_access: boolean;
+        risk_score: number;
+        complexity_score: number;
+    };
+    sanitized_code?: string;
+    sandbox_config?: SandboxConfig;
+    recommendations: string[];
+}
+export interface SandboxConfig {
+    timeout: number;
+    memoryLimit: number;
+    allowedSyscalls: string[];
+    networkPolicy: "none" | "localhost" | "allowlist";
+    filesystemPolicy: "none" | "readonly" | "temponly";
+    envVars: Record<string, string>;
+}
+export declare class CodeExecutionGuard {
+    private config;
+    private readonly DANGEROUS_PATTERNS;
+    private readonly DEFAULT_BLOCKED_IMPORTS;
+    private readonly DEFAULT_BLOCKED_FUNCTIONS;
+    constructor(config?: CodeExecutionGuardConfig);
+    /**
+     * Analyze code for dangerous patterns before execution
+     */
+    analyze(code: string, language: string, requestId?: string): CodeAnalysisResult;
+    /**
+     * Validate code structure (syntax check simulation)
+     */
+    validateSyntax(code: string, language: string): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Generate secure sandbox configuration
+     */
+    generateSandboxConfig(needsNetwork: boolean, needsFileSystem: boolean, needsShell: boolean, needsEnv: boolean): SandboxConfig;
+    /**
+     * Sanitize code by removing dangerous patterns
+     */
+    sanitizeCode(code: string, language: string): string;
+    /**
+     * Get allowed languages
+     */
+    getAllowedLanguages(): string[];
+    /**
+     * Add custom dangerous pattern
+     */
+    addDangerousPattern(language: string, name: string, pattern: RegExp, severity: number): void;
+    private calculateComplexity;
+    private getAllowedSyscalls;
+    private generateRecommendations;
+}
+//# sourceMappingURL=code-execution-guard.d.ts.map

package/dist/guards/code-execution-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-execution-guard.d.ts","sourceRoot":"","sources":["../../src/guards/code-execution-guard.ts"],"names":[],"mappings":"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"}