sovr-mcp-proxy 7.0.0 → 7.1.0

package/dist/semanticAnalyzer.d.ts

@@ -0,0 +1,133 @@
+/**
+ * SOVR Semantic Analyzer — Multi-Layer Intent Detection Engine
+ *
+ * P1-2: Goes beyond regex pattern matching to understand command INTENT.
+ *
+ * Three analysis layers (evidence-based first, LLM last):
+ *   Layer 1: Rule-based pattern matching (fast, deterministic)
+ *   Layer 2: Structural analysis (AST-like decomposition of commands)
+ *   Layer 3: LLM-as-Judge (optional, for ambiguous cases only)
+ *
+ * Design principle: "Evidence-based over LLM semantic" — per SOVR ADR.
+ * LLM is only used as a tiebreaker, never as the sole decision maker.
+ */
+interface SemanticAnalysisConfig {
+    /** Enable Layer 3 (LLM-as-Judge) */
+    enableLLM: boolean;
+    /** LLM provider function (optional) */
+    llmProvider?: LLMProvider;
+    /** Risk threshold to trigger LLM analysis (0-100) */
+    llmTriggerThreshold: number;
+    /** Maximum time for LLM analysis (ms) */
+    llmTimeout: number;
+    /** Custom intent rules */
+    customRules: IntentRule[];
+    /** Enable structural analysis */
+    enableStructural: boolean;
+    /** Sensitivity level */
+    sensitivity: 'low' | 'medium' | 'high' | 'paranoid';
+}
+interface LLMProvider {
+    analyze(prompt: string, timeout: number): Promise<LLMJudgment>;
+}
+interface LLMJudgment {
+    intent: string;
+    riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+    confidence: number;
+    reasoning: string;
+}
+interface IntentRule {
+    /** Rule ID */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Category of intent */
+    category: IntentCategory;
+    /** Patterns to match (any match triggers) */
+    patterns: IntentPattern[];
+    /** Risk level when matched */
+    riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+    /** Priority (higher = evaluated first) */
+    priority: number;
+    /** Whether this rule is a positive (allow) or negative (block) indicator */
+    polarity: 'positive' | 'negative';
+}
+interface IntentPattern {
+    /** Pattern type */
+    type: 'regex' | 'keyword' | 'structural' | 'sequence';
+    /** The pattern value */
+    value: string;
+    /** Where to look */
+    target: 'command' | 'arguments' | 'tool_name' | 'full_context';
+    /** Case sensitive */
+    caseSensitive?: boolean;
+}
+type IntentCategory = 'data_destruction' | 'data_exfiltration' | 'privilege_escalation' | 'code_execution' | 'network_access' | 'file_modification' | 'credential_access' | 'system_modification' | 'financial_operation' | 'communication' | 'read_only' | 'benign';
+interface AnalysisResult {
+    /** Overall risk level */
+    riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+    /** Overall risk score (0-100) */
+    riskScore: number;
+    /** Confidence in the analysis (0-1) */
+    confidence: number;
+    /** Detected intents */
+    intents: DetectedIntent[];
+    /** Layer results */
+    layers: {
+        rules: LayerResult;
+        structural: LayerResult;
+        llm?: LayerResult;
+    };
+    /** Recommended action */
+    recommendation: 'allow' | 'warn' | 'block' | 'require-approval';
+    /** Human-readable explanation */
+    explanation: string;
+    /** Analysis duration (ms) */
+    durationMs: number;
+}
+interface DetectedIntent {
+    category: IntentCategory;
+    description: string;
+    confidence: number;
+    source: 'rule' | 'structural' | 'llm';
+    evidence: string[];
+}
+interface LayerResult {
+    riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+    riskScore: number;
+    confidence: number;
+    findings: string[];
+}
+declare class SemanticAnalyzer {
+    private config;
+    private rules;
+    constructor(config?: Partial<SemanticAnalysisConfig>);
+    /**
+     * Analyze a tool call for security risks.
+     * Returns a comprehensive analysis result with multi-layer findings.
+     */
+    analyze(toolName: string, args: Record<string, unknown>): Promise<AnalysisResult>;
+    /** Quick synchronous check (Layer 1 only, for hot path) */
+    quickCheck(toolName: string, args: Record<string, unknown>): {
+        riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+        riskScore: number;
+        topFinding: string;
+    };
+    /** Add custom rules at runtime */
+    addRule(rule: IntentRule): void;
+    /** Get all active rules */
+    getRules(): IntentRule[];
+    private analyzeWithRules;
+    private extractCommand;
+    private getPatternTarget;
+    private riskLevelToScore;
+    private applySensitivity;
+    private collectIntents;
+    private combineResults;
+}
+/** Create a semantic analyzer with default settings */
+declare function createSemanticAnalyzer(overrides?: Partial<SemanticAnalysisConfig>): SemanticAnalyzer;
+/** Create a paranoid analyzer (highest sensitivity, all layers) */
+declare function createParanoidAnalyzer(llmProvider?: LLMProvider): SemanticAnalyzer;
+
+export { type AnalysisResult, type DetectedIntent, type IntentCategory, type IntentPattern, type IntentRule, type LLMJudgment, type LLMProvider, type LayerResult, type SemanticAnalysisConfig, SemanticAnalyzer, createParanoidAnalyzer, createSemanticAnalyzer };