sovr-mcp-proxy 7.0.0 → 7.1.0

package/dist/mcpProxyInterceptor.mjs

@@ -0,0 +1,552 @@
+// src/mcpProxyInterceptor.ts
+var SlidingWindowRateLimiter = class {
+  windows = /* @__PURE__ */ new Map();
+  windowSizeMs = 6e4;
+  // 1 minute
+  check(key, limit) {
+    const now = Date.now();
+    const cutoff = now - this.windowSizeMs;
+    const timestamps = this.windows.get(key) || [];
+    const recent = timestamps.filter((t) => t > cutoff);
+    this.windows.set(key, recent);
+    return recent.length < limit;
+  }
+  record(key) {
+    const timestamps = this.windows.get(key) || [];
+    timestamps.push(Date.now());
+    this.windows.set(key, timestamps);
+  }
+  getCount(key) {
+    const now = Date.now();
+    const cutoff = now - this.windowSizeMs;
+    const timestamps = this.windows.get(key) || [];
+    return timestamps.filter((t) => t > cutoff).length;
+  }
+  cleanup() {
+    const now = Date.now();
+    const cutoff = now - this.windowSizeMs;
+    for (const [key, timestamps] of this.windows) {
+      const recent = timestamps.filter((t) => t > cutoff);
+      if (recent.length === 0) {
+        this.windows.delete(key);
+      } else {
+        this.windows.set(key, recent);
+      }
+    }
+  }
+};
+function matchGlob(pattern, text) {
+  const regex = new RegExp(
+    "^" + pattern.replace(/\*/g, ".*").replace(/\?/g, ".") + "$"
+  );
+  return regex.test(text);
+}
+function evaluateCondition(condition, args) {
+  const value = getNestedValue(args, condition.field);
+  switch (condition.operator) {
+    case "exists":
+      return value !== void 0 && value !== null;
+    case "not-exists":
+      return value === void 0 || value === null;
+    case "equals":
+      return value === condition.value;
+    case "contains":
+      return typeof value === "string" && value.includes(String(condition.value));
+    case "matches":
+      return typeof value === "string" && new RegExp(String(condition.value)).test(value);
+    case "gt":
+      return typeof value === "number" && value > Number(condition.value);
+    case "lt":
+      return typeof value === "number" && value < Number(condition.value);
+    default:
+      return false;
+  }
+}
+function getNestedValue(obj, path) {
+  return path.split(".").reduce((current, key) => {
+    if (current && typeof current === "object" && key in current) {
+      return current[key];
+    }
+    return void 0;
+  }, obj);
+}
+function applyTransform(args, transform) {
+  const result = JSON.parse(JSON.stringify(args));
+  const parts = transform.field.split(".");
+  const lastKey = parts.pop();
+  let target = result;
+  for (const part of parts) {
+    if (target[part] && typeof target[part] === "object") {
+      target = target[part];
+    } else {
+      return result;
+    }
+  }
+  switch (transform.type) {
+    case "redact":
+      target[lastKey] = "[REDACTED]";
+      break;
+    case "mask":
+      if (typeof target[lastKey] === "string") {
+        const val = target[lastKey];
+        target[lastKey] = val.slice(0, 2) + "*".repeat(Math.max(val.length - 4, 0)) + val.slice(-2);
+      }
+      break;
+    case "replace":
+      target[lastKey] = transform.replacement ?? "";
+      break;
+    case "remove":
+      delete target[lastKey];
+      break;
+  }
+  return result;
+}
+var HIGH_RISK_TOOLS = /* @__PURE__ */ new Set([
+  "bash",
+  "shell",
+  "exec",
+  "run_command",
+  "execute",
+  "write_file",
+  "delete_file",
+  "move_file",
+  "sql_query",
+  "database_query",
+  "send_email",
+  "send_message",
+  "deploy",
+  "publish",
+  "payment",
+  "transfer",
+  "checkout"
+]);
+var DANGEROUS_ARG_PATTERNS = [
+  /rm\s+-rf/i,
+  /DROP\s+TABLE/i,
+  /DELETE\s+FROM/i,
+  /TRUNCATE/i,
+  /sudo\s+/i,
+  /chmod\s+777/i,
+  /curl\s+.*\|\s*sh/i,
+  /eval\s*\(/i,
+  /exec\s*\(/i,
+  /password|secret|token|api.?key/i
+];
+function calculateRiskScore(toolName, args) {
+  let score = 0;
+  if (HIGH_RISK_TOOLS.has(toolName.toLowerCase())) {
+    score += 30;
+  }
+  const argsStr = JSON.stringify(args);
+  for (const pattern of DANGEROUS_ARG_PATTERNS) {
+    if (pattern.test(argsStr)) {
+      score += 20;
+    }
+  }
+  if (argsStr.length > 5e3) {
+    score += 10;
+  }
+  const pipeCount = (argsStr.match(/\|/g) || []).length;
+  if (pipeCount > 2) {
+    score += 15;
+  }
+  return Math.min(score, 100);
+}
+var McpProxyInterceptor = class {
+  config;
+  rateLimiter;
+  stats;
+  auditLog = [];
+  maxAuditLogSize = 1e4;
+  activeCalls = 0;
+  cleanupInterval = null;
+  constructor(config = {}) {
+    this.config = {
+      mode: config.mode ?? "block",
+      maxConcurrent: config.maxConcurrent ?? 50,
+      rateLimits: config.rateLimits ?? {},
+      globalRateLimit: config.globalRateLimit ?? 200,
+      toolPolicies: config.toolPolicies ?? [],
+      enableSemanticAnalysis: config.enableSemanticAnalysis ?? false,
+      onApprovalRequired: config.onApprovalRequired,
+      onAuditEvent: config.onAuditEvent,
+      upstreamTimeout: config.upstreamTimeout ?? 3e4,
+      maxRetries: config.maxRetries ?? 2
+    };
+    this.rateLimiter = new SlidingWindowRateLimiter();
+    this.stats = {
+      totalCalls: 0,
+      allowed: 0,
+      blocked: 0,
+      approvalRequested: 0,
+      rateLimited: 0,
+      errors: 0,
+      avgLatencyMs: 0,
+      callsByTool: {},
+      blocksByPolicy: {},
+      riskDistribution: { safe: 0, suspicious: 0, dangerous: 0, critical: 0 }
+    };
+    this.cleanupInterval = setInterval(() => {
+      this.rateLimiter.cleanup();
+      this.trimAuditLog();
+    }, 6e4);
+  }
+  /**
+   * Intercept a tool call — the core entry point.
+   * Returns the decision and optionally transformed arguments.
+   */
+  async intercept(toolName, args) {
+    const startTime = Date.now();
+    const callId = `ic_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    this.stats.totalCalls++;
+    this.stats.callsByTool[toolName] = (this.stats.callsByTool[toolName] || 0) + 1;
+    if (this.activeCalls >= this.config.maxConcurrent) {
+      const decision2 = {
+        action: "block",
+        reason: `Concurrency limit exceeded (${this.config.maxConcurrent})`,
+        riskScore: 0
+      };
+      this.stats.blocked++;
+      this.emitAudit(callId, "block", toolName, args, decision2, Date.now() - startTime);
+      return { id: callId, timestamp: startTime, toolName, arguments: args, matchedPolicies: [], decision: decision2 };
+    }
+    if (!this.rateLimiter.check("__global__", this.config.globalRateLimit)) {
+      const decision2 = {
+        action: "block",
+        reason: `Global rate limit exceeded (${this.config.globalRateLimit}/min)`,
+        riskScore: 0
+      };
+      this.stats.rateLimited++;
+      this.emitAudit(callId, "rate-limited", toolName, args, decision2, Date.now() - startTime);
+      return { id: callId, timestamp: startTime, toolName, arguments: args, matchedPolicies: [], decision: decision2 };
+    }
+    const toolLimit = this.config.rateLimits[toolName];
+    if (toolLimit && !this.rateLimiter.check(`tool:${toolName}`, toolLimit)) {
+      const decision2 = {
+        action: "block",
+        reason: `Tool rate limit exceeded for '${toolName}' (${toolLimit}/min)`,
+        riskScore: 0
+      };
+      this.stats.rateLimited++;
+      this.emitAudit(callId, "rate-limited", toolName, args, decision2, Date.now() - startTime);
+      return { id: callId, timestamp: startTime, toolName, arguments: args, matchedPolicies: [], decision: decision2 };
+    }
+    const matchedPolicies = this.config.toolPolicies.filter((p) => matchGlob(p.toolPattern, toolName)).filter((p) => {
+      if (!p.conditions || p.conditions.length === 0) return true;
+      return p.conditions.every((c) => evaluateCondition(c, args));
+    }).sort((a, b) => b.priority - a.priority);
+    const riskScore = calculateRiskScore(toolName, args);
+    let decision;
+    if (matchedPolicies.length > 0) {
+      const topPolicy = matchedPolicies[0];
+      switch (topPolicy.action) {
+        case "block":
+          decision = {
+            action: "block",
+            reason: topPolicy.description,
+            triggeringPolicy: topPolicy,
+            riskScore
+          };
+          this.stats.blocked++;
+          this.stats.blocksByPolicy[topPolicy.description] = (this.stats.blocksByPolicy[topPolicy.description] || 0) + 1;
+          break;
+        case "require-approval":
+          decision = {
+            action: "require-approval",
+            reason: topPolicy.description,
+            triggeringPolicy: topPolicy,
+            riskScore
+          };
+          this.stats.approvalRequested++;
+          if (this.config.onApprovalRequired) {
+            const call = {
+              id: callId,
+              timestamp: startTime,
+              toolName,
+              arguments: args,
+              matchedPolicies,
+              decision
+            };
+            try {
+              const approval = await this.config.onApprovalRequired(call);
+              if (approval.approved) {
+                decision = { action: "allow", reason: `Approved by ${approval.approver || "human"}`, riskScore };
+                this.emitAudit(callId, "approval-granted", toolName, args, decision, Date.now() - startTime);
+              } else {
+                decision = { action: "block", reason: `Denied by ${approval.approver || "human"}: ${approval.reason || "no reason"}`, riskScore };
+                this.emitAudit(callId, "approval-denied", toolName, args, decision, Date.now() - startTime);
+              }
+            } catch (err) {
+              decision = { action: "block", reason: "Approval system unavailable (fail-closed)", riskScore };
+              this.stats.errors++;
+            }
+          }
+          break;
+        case "transform":
+          let transformed = { ...args };
+          for (const transform of topPolicy.transforms || []) {
+            transformed = applyTransform(transformed, transform);
+          }
+          decision = {
+            action: "transform",
+            reason: topPolicy.description,
+            triggeringPolicy: topPolicy,
+            riskScore,
+            transformedArguments: transformed
+          };
+          this.stats.allowed++;
+          break;
+        case "allow":
+        default:
+          decision = {
+            action: "allow",
+            reason: topPolicy.description,
+            triggeringPolicy: topPolicy,
+            riskScore
+          };
+          this.stats.allowed++;
+          break;
+      }
+    } else {
+      switch (this.config.mode) {
+        case "block":
+          decision = {
+            action: "block",
+            reason: "No matching policy (default deny)",
+            riskScore
+          };
+          this.stats.blocked++;
+          break;
+        case "warn":
+          decision = {
+            action: "allow",
+            reason: "No matching policy (warn mode \u2014 allowed with warning)",
+            riskScore
+          };
+          this.stats.allowed++;
+          break;
+        case "audit":
+          decision = {
+            action: "allow",
+            reason: "No matching policy (audit mode \u2014 allowed, logged)",
+            riskScore
+          };
+          this.stats.allowed++;
+          break;
+      }
+    }
+    this.rateLimiter.record("__global__");
+    this.rateLimiter.record(`tool:${toolName}`);
+    if (riskScore < 25) this.stats.riskDistribution.safe++;
+    else if (riskScore < 50) this.stats.riskDistribution.suspicious++;
+    else if (riskScore < 75) this.stats.riskDistribution.dangerous++;
+    else this.stats.riskDistribution.critical++;
+    const duration = Date.now() - startTime;
+    this.stats.avgLatencyMs = (this.stats.avgLatencyMs * (this.stats.totalCalls - 1) + duration) / this.stats.totalCalls;
+    const eventType = decision.action === "allow" || decision.action === "transform" ? "allow" : "block";
+    this.emitAudit(callId, eventType, toolName, args, decision, duration);
+    return {
+      id: callId,
+      timestamp: startTime,
+      toolName,
+      arguments: args,
+      matchedPolicies,
+      decision
+    };
+  }
+  /**
+   * Wrap an upstream tool call with interception.
+   * If allowed, executes the upstream function; if blocked, returns error.
+   */
+  async wrapToolCall(toolName, args, upstream) {
+    const intercepted = await this.intercept(toolName, args);
+    if (intercepted.decision.action === "block" || intercepted.decision.action === "require-approval") {
+      return {
+        intercepted,
+        error: `SOVR blocked: ${intercepted.decision.reason}`
+      };
+    }
+    const finalArgs = intercepted.decision.transformedArguments || args;
+    this.activeCalls++;
+    try {
+      const result = await Promise.race([
+        upstream(finalArgs),
+        new Promise(
+          (_, reject) => setTimeout(() => reject(new Error("Upstream timeout")), this.config.upstreamTimeout)
+        )
+      ]);
+      return { result, intercepted };
+    } catch (err) {
+      this.stats.errors++;
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      this.emitAudit(
+        intercepted.id,
+        "error",
+        toolName,
+        args,
+        intercepted.decision,
+        0,
+        errorMsg
+      );
+      return { intercepted, error: errorMsg };
+    } finally {
+      this.activeCalls--;
+    }
+  }
+  /** Get current statistics */
+  getStats() {
+    return { ...this.stats };
+  }
+  /** Get recent audit log */
+  getAuditLog(limit = 100) {
+    return this.auditLog.slice(-limit);
+  }
+  /** Export audit log as CSV */
+  exportAuditCSV() {
+    const headers = ["id", "timestamp", "type", "toolName", "decision", "riskScore", "reason", "duration", "error"];
+    const rows = this.auditLog.map((e) => [
+      e.id,
+      new Date(e.timestamp).toISOString(),
+      e.type,
+      e.toolName,
+      e.decision.action,
+      e.decision.riskScore,
+      `"${e.decision.reason.replace(/"/g, '""')}"`,
+      e.duration ?? "",
+      e.error ? `"${e.error.replace(/"/g, '""')}"` : ""
+    ].join(","));
+    return [headers.join(","), ...rows].join("\n");
+  }
+  /** Add a policy at runtime */
+  addPolicy(policy) {
+    this.config.toolPolicies.push(policy);
+    this.config.toolPolicies.sort((a, b) => b.priority - a.priority);
+  }
+  /** Remove policies matching a pattern */
+  removePolicies(toolPattern) {
+    const before = this.config.toolPolicies.length;
+    this.config.toolPolicies = this.config.toolPolicies.filter((p) => p.toolPattern !== toolPattern);
+    return before - this.config.toolPolicies.length;
+  }
+  /** Reset statistics */
+  resetStats() {
+    this.stats = {
+      totalCalls: 0,
+      allowed: 0,
+      blocked: 0,
+      approvalRequested: 0,
+      rateLimited: 0,
+      errors: 0,
+      avgLatencyMs: 0,
+      callsByTool: {},
+      blocksByPolicy: {},
+      riskDistribution: { safe: 0, suspicious: 0, dangerous: 0, critical: 0 }
+    };
+  }
+  /** Cleanup resources */
+  destroy() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+  // ─── Private ─────────────────────────────────────────────────────────────
+  emitAudit(id, type, toolName, args, decision, duration, error) {
+    const event = {
+      id,
+      timestamp: Date.now(),
+      type,
+      toolName,
+      arguments: args,
+      decision,
+      duration,
+      error
+    };
+    this.auditLog.push(event);
+    this.config.onAuditEvent?.(event);
+  }
+  trimAuditLog() {
+    if (this.auditLog.length > this.maxAuditLogSize) {
+      this.auditLog = this.auditLog.slice(-this.maxAuditLogSize);
+    }
+  }
+};
+var PRESET_POLICIES = {
+  /** Block all destructive file operations */
+  noDestructiveFiles: {
+    toolPattern: "*",
+    action: "block",
+    conditions: [
+      { field: "command", operator: "matches", value: "rm\\s+-rf|rmdir|del\\s+/|Remove-Item" }
+    ],
+    priority: 100,
+    description: "Block destructive file deletion commands"
+  },
+  /** Block all database write operations */
+  readOnlyDatabase: {
+    toolPattern: "*sql*",
+    action: "block",
+    conditions: [
+      { field: "query", operator: "matches", value: "INSERT|UPDATE|DELETE|DROP|TRUNCATE|ALTER|CREATE" }
+    ],
+    priority: 90,
+    description: "Block database write operations (read-only mode)"
+  },
+  /** Require approval for payment operations */
+  approvePayments: {
+    toolPattern: "*payment*",
+    action: "require-approval",
+    priority: 95,
+    description: "Require human approval for payment operations"
+  },
+  /** Redact secrets in tool arguments */
+  redactSecrets: {
+    toolPattern: "*",
+    action: "transform",
+    conditions: [
+      { field: "command", operator: "matches", value: "password|secret|token|api.?key" }
+    ],
+    transforms: [
+      { field: "password", type: "redact" },
+      { field: "secret", type: "redact" },
+      { field: "token", type: "mask" }
+    ],
+    priority: 80,
+    description: "Redact sensitive values in tool arguments"
+  },
+  /** Rate limit shell commands */
+  rateLimitShell: {
+    toolPattern: "bash",
+    action: "rate-limit",
+    priority: 70,
+    description: "Rate limit shell command execution"
+  },
+  /** Allow read-only operations */
+  allowReadOnly: {
+    toolPattern: "*",
+    action: "allow",
+    conditions: [
+      { field: "command", operator: "matches", value: "^(ls|cat|head|tail|grep|find|echo|pwd|whoami|date|wc)\\b" }
+    ],
+    priority: 60,
+    description: "Allow read-only shell commands"
+  }
+};
+function createSecureInterceptor(overrides = {}) {
+  return new McpProxyInterceptor({
+    mode: "block",
+    maxConcurrent: 20,
+    globalRateLimit: 100,
+    rateLimits: { bash: 30, shell: 30, exec: 30 },
+    toolPolicies: Object.values(PRESET_POLICIES),
+    enableSemanticAnalysis: false,
+    upstreamTimeout: 3e4,
+    maxRetries: 2,
+    ...overrides
+  });
+}
+export {
+  McpProxyInterceptor,
+  PRESET_POLICIES,
+  createSecureInterceptor
+};

package/dist/semanticAnalyzer.d.mts

@@ -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 };