clawsec 0.0.1

package/dist/src/engine/llm-client.js

@@ -0,0 +1,506 @@
+/**
+ * LLM Client for analyzing ambiguous security detections
+ *
+ * This module provides an LLM client that analyzes ambiguous detections
+ * to determine if they're true threats. Used when the HybridAnalyzer
+ * sets requiresLLM = true for cases with ambiguous confidence (0.5-0.8).
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/** Default timeout for LLM requests (30 seconds) */
+export const DEFAULT_LLM_TIMEOUT_MS = 30000;
+/** Default TTL for LLM response cache (5 minutes - longer than detection cache) */
+export const DEFAULT_LLM_CACHE_TTL_MS = 5 * 60 * 1000;
+/** Maximum cache size for LLM responses */
+export const MAX_LLM_CACHE_SIZE = 500;
+// ============================================================================
+// Cache for LLM Responses
+// ============================================================================
+/**
+ * Generic in-memory cache for LLM responses
+ */
+export class LLMResponseCache {
+    cache;
+    defaultTtl;
+    constructor(defaultTtlMs = DEFAULT_LLM_CACHE_TTL_MS) {
+        this.cache = new Map();
+        this.defaultTtl = defaultTtlMs;
+    }
+    /**
+     * Generate a cache key from the request
+     */
+    generateKey(request) {
+        const keyData = {
+            category: request.detection.category,
+            reason: request.detection.reason,
+            toolName: request.context.toolName,
+            toolInput: request.context.toolInput,
+        };
+        return JSON.stringify(keyData);
+    }
+    /**
+     * Get a cached result
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        if (this.isExpired(entry)) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    /**
+     * Set a cached result
+     */
+    set(key, result, ttl) {
+        if (this.cache.size >= MAX_LLM_CACHE_SIZE) {
+            this.evictExpired();
+            if (this.cache.size >= MAX_LLM_CACHE_SIZE) {
+                this.evictOldest(Math.floor(MAX_LLM_CACHE_SIZE * 0.1));
+            }
+        }
+        const entry = {
+            value: result,
+            createdAt: Date.now(),
+            ttl: ttl ?? this.defaultTtl,
+        };
+        this.cache.set(key, entry);
+    }
+    /**
+     * Check if a key exists and is not expired
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        if (this.isExpired(entry)) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Clear all entries
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get cache size
+     */
+    size() {
+        return this.cache.size;
+    }
+    isExpired(entry) {
+        return Date.now() - entry.createdAt >= entry.ttl;
+    }
+    evictExpired() {
+        const now = Date.now();
+        for (const [key, entry] of this.cache) {
+            if (now - entry.createdAt >= entry.ttl) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    evictOldest(count) {
+        const entries = Array.from(this.cache.entries()).sort((a, b) => a[1].createdAt - b[1].createdAt);
+        for (let i = 0; i < Math.min(count, entries.length); i++) {
+            this.cache.delete(entries[i][0]);
+        }
+    }
+}
+// ============================================================================
+// Prompt Generation
+// ============================================================================
+/**
+ * Build a prompt for LLM analysis of a security detection
+ */
+export function buildAnalysisPrompt(request) {
+    const { detection, context } = request;
+    const toolInputStr = JSON.stringify(context.toolInput, null, 2);
+    let prompt = `You are a security analyst reviewing a potentially suspicious action by an AI agent.
+
+## Detection Details
+- **Category**: ${detection.category}
+- **Severity**: ${detection.severity}
+- **Confidence**: ${(detection.confidence * 100).toFixed(0)}%
+- **Reason**: ${detection.reason}
+
+## Tool Call Context
+- **Tool Name**: ${context.toolName}
+- **Tool Input**:
+\`\`\`json
+${toolInputStr}
+\`\`\``;
+    if (context.url) {
+        prompt += `\n- **URL**: ${context.url}`;
+    }
+    if (context.toolOutput) {
+        const truncatedOutput = context.toolOutput.length > 500
+            ? context.toolOutput.substring(0, 500) + '...'
+            : context.toolOutput;
+        prompt += `\n- **Tool Output** (truncated):\n\`\`\`\n${truncatedOutput}\n\`\`\``;
+    }
+    if (detection.metadata) {
+        prompt += `\n- **Additional Metadata**: ${JSON.stringify(detection.metadata)}`;
+    }
+    prompt += `
+
+## Your Task
+Analyze this detection and determine if this represents a real security threat or a false positive.
+
+Consider:
+1. Is the detected action genuinely dangerous or malicious?
+2. Could this be a legitimate use case that triggered a false positive?
+3. What is the potential impact if this action is allowed?
+4. Are there any contextual clues that suggest benign intent?
+
+## Response Format
+Respond with a JSON object in the following format:
+\`\`\`json
+{
+  "determination": "threat" | "safe" | "uncertain",
+  "confidence": 0.0 to 1.0,
+  "reasoning": "Brief explanation of your analysis",
+  "suggestedAction": "block" | "confirm" | "allow"
+}
+\`\`\`
+
+Guidelines for determination:
+- "threat": Clear evidence of malicious or dangerous intent
+- "safe": Clear evidence this is a legitimate, safe operation
+- "uncertain": Cannot determine with confidence; err on the side of caution
+
+Guidelines for suggestedAction:
+- "block": For clear threats or high-risk uncertain cases
+- "confirm": When user confirmation would be helpful
+- "allow": Only for clearly safe operations`;
+    return prompt;
+}
+/**
+ * Parse LLM response to extract structured result
+ */
+export function parseAnalysisResponse(response) {
+    // Try to extract JSON from the response
+    const jsonMatch = response.match(/```json\s*([\s\S]*?)\s*```/);
+    const jsonStr = jsonMatch ? jsonMatch[1] : response;
+    try {
+        const parsed = JSON.parse(jsonStr.trim());
+        // Validate and normalize the response
+        const determination = normalizeDetermination(parsed.determination);
+        const confidence = normalizeConfidence(parsed.confidence);
+        const reasoning = typeof parsed.reasoning === 'string' ? parsed.reasoning : 'No reasoning provided';
+        const suggestedAction = normalizeSuggestedAction(parsed.suggestedAction, determination);
+        return {
+            determination,
+            confidence,
+            reasoning,
+            suggestedAction,
+        };
+    }
+    catch {
+        // If parsing fails, return uncertain result
+        return {
+            determination: 'uncertain',
+            confidence: 0.5,
+            reasoning: 'Failed to parse LLM response',
+            suggestedAction: 'confirm',
+        };
+    }
+}
+function normalizeDetermination(value) {
+    if (value === 'threat' || value === 'safe' || value === 'uncertain') {
+        return value;
+    }
+    return 'uncertain';
+}
+function normalizeConfidence(value) {
+    if (typeof value === 'number' && value >= 0 && value <= 1) {
+        return value;
+    }
+    return 0.5;
+}
+function normalizeSuggestedAction(value, determination) {
+    if (value === 'block' || value === 'confirm' || value === 'allow') {
+        return value;
+    }
+    // Default based on determination
+    switch (determination) {
+        case 'threat':
+            return 'block';
+        case 'safe':
+            return 'allow';
+        case 'uncertain':
+            return 'confirm';
+    }
+}
+/**
+ * Real LLM client that uses OpenClaw API
+ */
+export class OpenClawLLMClient {
+    api;
+    model;
+    timeoutMs;
+    cache;
+    cacheTtlMs;
+    constructor(api, config) {
+        this.api = api;
+        this.model = config.llmConfig.model;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_LLM_TIMEOUT_MS;
+        this.cacheTtlMs = config.cacheTtlMs ?? DEFAULT_LLM_CACHE_TTL_MS;
+        this.cache = config.enableCache !== false ? new LLMResponseCache(this.cacheTtlMs) : null;
+    }
+    isAvailable() {
+        return this.api.isAvailable();
+    }
+    async analyze(request) {
+        // Check cache first
+        if (this.cache) {
+            const cacheKey = this.cache.generateKey(request);
+            const cached = this.cache.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+        }
+        try {
+            const prompt = buildAnalysisPrompt(request);
+            const response = await this.api.complete(prompt, {
+                model: this.model,
+                timeout: this.timeoutMs,
+            });
+            const result = parseAnalysisResponse(response);
+            // Cache the result
+            if (this.cache) {
+                const cacheKey = this.cache.generateKey(request);
+                this.cache.set(cacheKey, result);
+            }
+            return result;
+        }
+        catch (error) {
+            // Return uncertain on error
+            return {
+                determination: 'uncertain',
+                confidence: 0.5,
+                reasoning: `LLM analysis failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                suggestedAction: 'confirm',
+            };
+        }
+    }
+    /**
+     * Clear the response cache
+     */
+    clearCache() {
+        this.cache?.clear();
+    }
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        return {
+            size: this.cache?.size() ?? 0,
+            enabled: this.cache !== null,
+        };
+    }
+}
+/**
+ * Mock LLM client for testing
+ * Provides deterministic responses based on detection characteristics
+ */
+export class MockLLMClient {
+    available;
+    responseDelay;
+    cache;
+    customResponses;
+    constructor(options) {
+        this.available = options?.available ?? true;
+        this.responseDelay = options?.responseDelay ?? 0;
+        this.cache = options?.enableCache !== false ? new LLMResponseCache(options?.cacheTtlMs) : null;
+        this.customResponses = new Map();
+    }
+    isAvailable() {
+        return this.available;
+    }
+    /**
+     * Set availability for testing
+     */
+    setAvailable(available) {
+        this.available = available;
+    }
+    /**
+     * Set a custom response for a specific category
+     */
+    setCustomResponse(category, response) {
+        this.customResponses.set(category, response);
+    }
+    async analyze(request) {
+        if (!this.available) {
+            return {
+                determination: 'uncertain',
+                confidence: 0.5,
+                reasoning: 'LLM client unavailable',
+                suggestedAction: 'confirm',
+            };
+        }
+        // Check cache first
+        if (this.cache) {
+            const cacheKey = this.cache.generateKey(request);
+            const cached = this.cache.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+        }
+        // Simulate processing time
+        if (this.responseDelay > 0) {
+            await new Promise((resolve) => setTimeout(resolve, this.responseDelay));
+        }
+        // Check for custom response
+        const customResponse = this.customResponses.get(request.detection.category);
+        if (customResponse) {
+            if (this.cache) {
+                const cacheKey = this.cache.generateKey(request);
+                this.cache.set(cacheKey, customResponse);
+            }
+            return customResponse;
+        }
+        // Generate deterministic response based on detection
+        const result = this.generateMockResponse(request);
+        // Cache the result
+        if (this.cache) {
+            const cacheKey = this.cache.generateKey(request);
+            this.cache.set(cacheKey, result);
+        }
+        return result;
+    }
+    /**
+     * Generate a mock response based on detection characteristics
+     */
+    generateMockResponse(request) {
+        const { detection, context } = request;
+        // High confidence detections are treated as threats
+        if (detection.confidence >= 0.75) {
+            return {
+                determination: 'threat',
+                confidence: 0.85,
+                reasoning: `High confidence ${detection.category} detection confirms threat`,
+                suggestedAction: 'block',
+            };
+        }
+        // Low confidence detections are treated as safe
+        if (detection.confidence < 0.55) {
+            return {
+                determination: 'safe',
+                confidence: 0.7,
+                reasoning: `Low confidence ${detection.category} detection likely false positive`,
+                suggestedAction: 'allow',
+            };
+        }
+        // Category-specific logic for mid-range confidence
+        switch (detection.category) {
+            case 'purchase':
+                // Purchase in known checkout flows is more likely a threat
+                if (context.url?.includes('checkout') || context.url?.includes('pay')) {
+                    return {
+                        determination: 'threat',
+                        confidence: 0.8,
+                        reasoning: 'Checkout or payment URL indicates real purchase attempt',
+                        suggestedAction: 'block',
+                    };
+                }
+                break;
+            case 'destructive':
+                // Destructive commands in test directories might be safe
+                if (JSON.stringify(context.toolInput).includes('test')) {
+                    return {
+                        determination: 'safe',
+                        confidence: 0.65,
+                        reasoning: 'Command appears to target test files/directories',
+                        suggestedAction: 'confirm',
+                    };
+                }
+                break;
+            case 'secrets':
+                // Secrets in env.example files are usually safe
+                if (JSON.stringify(context.toolInput).includes('example')) {
+                    return {
+                        determination: 'safe',
+                        confidence: 0.75,
+                        reasoning: 'Secret appears to be in example/template file',
+                        suggestedAction: 'allow',
+                    };
+                }
+                break;
+            case 'exfiltration':
+                // Exfiltration to localhost is usually safe
+                if (context.url?.includes('localhost') || context.url?.includes('127.0.0.1')) {
+                    return {
+                        determination: 'safe',
+                        confidence: 0.8,
+                        reasoning: 'Target is localhost, likely development/testing',
+                        suggestedAction: 'allow',
+                    };
+                }
+                break;
+        }
+        // Default uncertain response for ambiguous cases
+        return {
+            determination: 'uncertain',
+            confidence: 0.6,
+            reasoning: `Unable to definitively classify ${detection.category} detection`,
+            suggestedAction: 'confirm',
+        };
+    }
+    /**
+     * Clear the response cache
+     */
+    clearCache() {
+        this.cache?.clear();
+    }
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        return {
+            size: this.cache?.size() ?? 0,
+            enabled: this.cache !== null,
+        };
+    }
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Create an LLM client
+ *
+ * @param config - LLM client configuration
+ * @param api - Optional OpenClaw API instance (if available, creates real client)
+ * @returns LLM client instance
+ */
+export function createLLMClient(config, api) {
+    // If API is provided and available, use real client
+    if (api && api.isAvailable()) {
+        return new OpenClawLLMClient(api, config);
+    }
+    // Otherwise return mock client
+    return new MockLLMClient({
+        enableCache: config.enableCache,
+        cacheTtlMs: config.cacheTtlMs,
+    });
+}
+/**
+ * Create a mock LLM client for testing
+ */
+export function createMockLLMClient(options) {
+    return new MockLLMClient(options);
+}
+/**
+ * Create an unavailable LLM client (always returns uncertain)
+ */
+export function createUnavailableLLMClient() {
+    return new MockLLMClient({ available: false });
+}
+//# sourceMappingURL=llm-client.js.map

package/dist/src/engine/llm-client.js.map

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

package/dist/src/engine/types.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Hybrid Detection Engine Types
+ * Type definitions for the main detection engine that orchestrates all detectors
+ */
+import type { Severity, ClawsecConfig } from '../config/index.js';
+/**
+ * Actions that can be returned by the analyzer
+ * Note: This extends the config Action type with 'allow' for analysis results
+ */
+export type AnalysisAction = 'allow' | 'block' | 'confirm' | 'warn' | 'log';
+/**
+ * Threat categories that can be detected
+ */
+export type ThreatCategory = 'purchase' | 'website' | 'destructive' | 'secrets' | 'exfiltration';
+/**
+ * Detection context provided to the engine
+ */
+export interface ToolCallContext {
+    /** Name of the tool being invoked */
+    toolName: string;
+    /** Input parameters to the tool */
+    toolInput: Record<string, unknown>;
+    /** URL being accessed (for browser/navigation tools) */
+    url?: string;
+    /** Output from the tool (for post-execution scanning like secrets) */
+    toolOutput?: string;
+}
+/**
+ * Individual detection result
+ */
+export interface Detection {
+    /** Category of threat detected */
+    category: ThreatCategory;
+    /** Severity level */
+    severity: Severity;
+    /** Confidence score from 0 to 1 */
+    confidence: number;
+    /** Human-readable reason for the detection */
+    reason: string;
+    /** Additional metadata about the detection */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of the analysis
+ */
+export interface AnalysisResult {
+    /** Recommended action to take */
+    action: AnalysisAction;
+    /** All detections found across all enabled detectors */
+    detections: Detection[];
+    /** Highest severity detection (if any) */
+    primaryDetection?: Detection;
+    /** True if the result needs LLM analysis for ambiguous cases */
+    requiresLLM: boolean;
+    /** True if the result was retrieved from cache */
+    cached: boolean;
+    /** Analysis duration in milliseconds */
+    durationMs?: number;
+}
+/**
+ * Cache entry for storing analysis results
+ */
+export interface CacheEntry<T> {
+    /** The cached value */
+    value: T;
+    /** Timestamp when the entry was created */
+    createdAt: number;
+    /** Time-to-live in milliseconds */
+    ttl: number;
+}
+/**
+ * Cache interface for detection results
+ */
+export interface DetectionCache {
+    /** Get a cached result by key */
+    get(key: string): AnalysisResult | undefined;
+    /** Set a cached result */
+    set(key: string, result: AnalysisResult, ttl?: number): void;
+    /** Check if a key exists and is not expired */
+    has(key: string): boolean;
+    /** Clear all entries */
+    clear(): void;
+    /** Delete a specific entry */
+    delete(key: string): boolean;
+    /** Get the number of entries */
+    size(): number;
+}
+/**
+ * Configuration for the analyzer
+ */
+export interface AnalyzerConfig {
+    /** The Clawsec configuration */
+    config: ClawsecConfig;
+    /** Enable caching (default: true) */
+    enableCache?: boolean;
+    /** Cache TTL in milliseconds (default: 5 minutes) */
+    cacheTtlMs?: number;
+    /** Optional LLM client for analyzing ambiguous detections */
+    llmClient?: LLMClient;
+}
+/**
+ * LLM analysis result determination
+ */
+export type LLMDetermination = 'threat' | 'safe' | 'uncertain';
+/**
+ * LLM analysis suggested action
+ */
+export type LLMSuggestedAction = 'block' | 'confirm' | 'allow';
+/**
+ * Result of LLM analysis
+ */
+export interface LLMAnalysisResult {
+    /** Determination of the threat level */
+    determination: LLMDetermination;
+    /** Confidence in the determination (0-1) */
+    confidence: number;
+    /** Reasoning behind the determination */
+    reasoning: string;
+    /** Suggested action based on analysis */
+    suggestedAction: LLMSuggestedAction;
+}
+/**
+ * Request to analyze a detection with LLM
+ */
+export interface LLMAnalysisRequest {
+    /** The detection to analyze */
+    detection: Detection;
+    /** Context of the tool call that triggered the detection */
+    context: ToolCallContext;
+}
+/**
+ * Interface for LLM clients (minimal for avoiding circular deps)
+ */
+export interface LLMClient {
+    /** Analyze a detection and determine if it's a real threat */
+    analyze(request: LLMAnalysisRequest): Promise<LLMAnalysisResult>;
+    /** Check if the LLM client is available and configured */
+    isAvailable(): boolean;
+}
+/**
+ * Main analyzer interface
+ */
+export interface Analyzer {
+    /** Analyze a tool call and return the result */
+    analyze(context: ToolCallContext): Promise<AnalysisResult>;
+    /** Clear the detection cache */
+    clearCache(): void;
+    /** Get cache statistics */
+    getCacheStats(): {
+        size: number;
+        enabled: boolean;
+    };
+}
+/**
+ * Severity weights for sorting (higher = more severe)
+ */
+export declare const SEVERITY_WEIGHTS: Record<Severity, number>;
+/**
+ * Compare two severities
+ * @returns negative if a < b, 0 if equal, positive if a > b
+ */
+export declare function compareSeverity(a: Severity, b: Severity): number;
+//# sourceMappingURL=types.d.ts.map