mcp-rubber-duck 1.8.0 → 1.9.0

package/src/guardrails/plugins/pattern-blocker.ts

@@ -0,0 +1,190 @@
+import { BaseGuardrailPlugin } from './base-plugin.js';
+import { GuardrailPhase, GuardrailContext, GuardrailResult } from '../types.js';
+import { PatternBlockerConfig } from '../../config/types.js';
+
+interface PatternMatch {
+  pattern: string;
+  isRegex: boolean;
+  matchedText: string;
+  position: number;
+}
+
+/**
+ * Pattern blocker plugin - blocks or warns on specific patterns
+ */
+export class PatternBlockerPlugin extends BaseGuardrailPlugin {
+  name = 'pattern_blocker';
+  phases: GuardrailPhase[] = ['pre_request', 'pre_tool_input'];
+
+  private blockedPatterns: string[] = [];
+  private blockedPatternsRegex: RegExp[] = [];
+  private caseSensitive: boolean = false;
+  private actionOnMatch: 'block' | 'warn' | 'redact' = 'block';
+
+  async initialize(config: Record<string, unknown>): Promise<void> {
+    await super.initialize(config);
+
+    const typedConfig = config as Partial<PatternBlockerConfig>;
+    this.blockedPatterns = typedConfig.blocked_patterns ?? [];
+    this.caseSensitive = typedConfig.case_sensitive ?? false;
+    this.actionOnMatch = typedConfig.action_on_match ?? 'block';
+    this.priority = typedConfig.priority ?? 30;
+
+    // Compile regex patterns
+    this.blockedPatternsRegex = [];
+    for (const pattern of typedConfig.blocked_patterns_regex ?? []) {
+      try {
+        const flags = this.caseSensitive ? 'g' : 'gi';
+        this.blockedPatternsRegex.push(new RegExp(pattern, flags));
+      } catch (error) {
+        // Invalid regex, skip it
+      }
+    }
+  }
+
+  execute(phase: GuardrailPhase, context: GuardrailContext): Promise<GuardrailResult> {
+    if (!this.phases.includes(phase)) {
+      return Promise.resolve(this.allow(context));
+    }
+
+    // Get text to check based on phase
+    let textToCheck: string;
+    let fieldName: string;
+
+    if (phase === 'pre_request') {
+      textToCheck = context.prompt || '';
+      fieldName = 'prompt';
+    } else if (phase === 'pre_tool_input') {
+      textToCheck = JSON.stringify(context.toolArgs || {});
+      fieldName = 'toolArgs';
+    } else {
+      return Promise.resolve(this.allow(context));
+    }
+
+    // Find matches
+    const matches = this.findMatches(textToCheck);
+
+    if (matches.length === 0) {
+      return Promise.resolve(this.allow(context));
+    }
+
+    // Handle matches based on action
+    const matchSummary = matches.map((m) => m.pattern).join(', ');
+
+    if (this.actionOnMatch === 'block') {
+      this.addViolation(
+        context,
+        phase,
+        'blocked_pattern',
+        'error',
+        `Blocked patterns found: ${matchSummary}`,
+        { matches: matches.map((m) => ({ pattern: m.pattern, position: m.position })) }
+      );
+      return Promise.resolve(this.block(context, `Blocked pattern detected: ${matchSummary}`));
+    }
+
+    if (this.actionOnMatch === 'warn') {
+      this.addViolation(
+        context,
+        phase,
+        'blocked_pattern_warning',
+        'warning',
+        `Suspicious patterns found: ${matchSummary}`,
+        { matches: matches.map((m) => ({ pattern: m.pattern, position: m.position })) }
+      );
+      return Promise.resolve(this.allow(context));
+    }
+
+    if (this.actionOnMatch === 'redact') {
+      // Redact matches from text
+      let redactedText = textToCheck;
+      for (const match of matches) {
+        redactedText = redactedText.replace(
+          match.matchedText,
+          '[REDACTED]'
+        );
+      }
+
+      this.addModification(
+        context,
+        phase,
+        fieldName,
+        `Redacted ${matches.length} blocked patterns`,
+        textToCheck,
+        redactedText
+      );
+
+      // Update context
+      if (phase === 'pre_request') {
+        context.prompt = redactedText;
+        // Also update last message if present (create new object to avoid mutating original)
+        if (context.messages.length > 0) {
+          const lastIndex = context.messages.length - 1;
+          context.messages[lastIndex] = {
+            ...context.messages[lastIndex],
+            content: redactedText,
+          };
+        }
+      } else if (phase === 'pre_tool_input') {
+        try {
+          context.toolArgs = JSON.parse(redactedText) as Record<string, unknown>;
+        } catch {
+          // If parse fails, leave as is
+        }
+      }
+
+      return Promise.resolve(this.modify(context));
+    }
+
+    return Promise.resolve(this.allow(context));
+  }
+
+  /**
+   * Find all pattern matches in text
+   */
+  private findMatches(text: string): PatternMatch[] {
+    const matches: PatternMatch[] = [];
+    const searchText = this.caseSensitive ? text : text.toLowerCase();
+
+    // Check simple string patterns
+    for (const pattern of this.blockedPatterns) {
+      const searchPattern = this.caseSensitive ? pattern : pattern.toLowerCase();
+      let position = searchText.indexOf(searchPattern);
+      while (position !== -1) {
+        matches.push({
+          pattern,
+          isRegex: false,
+          matchedText: text.substring(position, position + pattern.length),
+          position,
+        });
+        position = searchText.indexOf(searchPattern, position + 1);
+      }
+    }
+
+    // Check regex patterns
+    for (const regex of this.blockedPatternsRegex) {
+      regex.lastIndex = 0; // Reset regex state
+      let match;
+      while ((match = regex.exec(text)) !== null) {
+        matches.push({
+          pattern: regex.source,
+          isRegex: true,
+          matchedText: match[0],
+          position: match.index,
+        });
+      }
+    }
+
+    return matches;
+  }
+
+  /**
+   * Get configured patterns (for testing)
+   */
+  getPatterns(): { simple: string[]; regex: string[] } {
+    return {
+      simple: [...this.blockedPatterns],
+      regex: this.blockedPatternsRegex.map((r) => r.source),
+    };
+  }
+}

package/src/guardrails/plugins/pii-redactor/detectors.ts

@@ -0,0 +1,200 @@
+export type PIIType =
+  | 'email'
+  | 'phone'
+  | 'ssn'
+  | 'api_key'
+  | 'credit_card'
+  | 'ip_address'
+  | 'custom';
+
+export interface PIIDetection {
+  type: PIIType;
+  value: string;
+  startIndex: number;
+  endIndex: number;
+  confidence: number;
+}
+
+export interface PIIDetectorConfig {
+  detectEmails: boolean;
+  detectPhones: boolean;
+  detectSSN: boolean;
+  detectAPIKeys: boolean;
+  detectCreditCards: boolean;
+  detectIPAddresses: boolean;
+  customPatterns: Array<{ name: string; pattern: string; placeholder: string }>;
+  allowlist: string[];
+  allowlistDomains: string[];
+}
+
+/**
+ * PII detector using regex patterns
+ */
+export class PIIDetector {
+  private patterns: Map<PIIType, RegExp> = new Map();
+  private allowlist: Set<string>;
+  private allowlistDomains: Set<string>;
+  private customPatterns: Array<{ name: string; regex: RegExp; placeholder: string }> = [];
+
+  constructor(config: PIIDetectorConfig) {
+    this.allowlist = new Set(config.allowlist.map((a) => a.toLowerCase()));
+    this.allowlistDomains = new Set(config.allowlistDomains.map((d) => d.toLowerCase()));
+
+    // Initialize built-in patterns
+    if (config.detectEmails) {
+      this.patterns.set(
+        'email',
+        /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g
+      );
+    }
+
+    if (config.detectPhones) {
+      // Handles multiple phone formats: US, international, with/without country code
+      this.patterns.set(
+        'phone',
+        /\b(?:\+?1[-.\s]?)?\(?[0-9]{3}\)?[-.\s]?[0-9]{3}[-.\s]?[0-9]{4}\b/g
+      );
+    }
+
+    if (config.detectSSN) {
+      // US SSN format: XXX-XX-XXXX or XXXXXXXXX
+      this.patterns.set(
+        'ssn',
+        /\b[0-9]{3}[-\s]?[0-9]{2}[-\s]?[0-9]{4}\b/g
+      );
+    }
+
+    if (config.detectAPIKeys) {
+      // Common API key patterns
+      this.patterns.set(
+        'api_key',
+        /\b(sk-[a-zA-Z0-9]{20,}|gsk_[a-zA-Z0-9]{20,}|api[_-]?key[_-]?[a-zA-Z0-9]{16,})\b/gi
+      );
+    }
+
+    if (config.detectCreditCards) {
+      // Credit card patterns (Visa, Mastercard, Amex, Discover)
+      // Simplified - doesn't validate Luhn, just matches format
+      this.patterns.set(
+        'credit_card',
+        /\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|3[47][0-9]{13}|6(?:011|5[0-9]{2})[0-9]{12})\b/g
+      );
+    }
+
+    if (config.detectIPAddresses) {
+      // IPv4 addresses
+      this.patterns.set(
+        'ip_address',
+        /\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b/g
+      );
+    }
+
+    // Custom patterns
+    for (const custom of config.customPatterns) {
+      try {
+        this.customPatterns.push({
+          name: custom.name,
+          regex: new RegExp(custom.pattern, 'g'),
+          placeholder: custom.placeholder,
+        });
+      } catch {
+        // Invalid regex, skip it
+      }
+    }
+  }
+
+  /**
+   * Detect PII in text
+   */
+  detect(text: string): PIIDetection[] {
+    const detections: PIIDetection[] = [];
+
+    // Check built-in patterns
+    for (const [type, pattern] of this.patterns) {
+      pattern.lastIndex = 0; // Reset regex state
+      let match;
+      while ((match = pattern.exec(text)) !== null) {
+        const value = match[0];
+
+        // Check allowlist
+        if (this.isAllowlisted(value, type)) {
+          continue;
+        }
+
+        detections.push({
+          type,
+          value,
+          startIndex: match.index,
+          endIndex: match.index + value.length,
+          confidence: this.calculateConfidence(type, value),
+        });
+      }
+    }
+
+    // Check custom patterns
+    for (const custom of this.customPatterns) {
+      custom.regex.lastIndex = 0;
+      let match;
+      while ((match = custom.regex.exec(text)) !== null) {
+        const value = match[0];
+
+        if (this.allowlist.has(value.toLowerCase())) {
+          continue;
+        }
+
+        detections.push({
+          type: 'custom',
+          value,
+          startIndex: match.index,
+          endIndex: match.index + value.length,
+          confidence: 0.9,
+        });
+      }
+    }
+
+    // Sort by position (for consistent pseudonymization)
+    return detections.sort((a, b) => a.startIndex - b.startIndex);
+  }
+
+  private isAllowlisted(value: string, type: PIIType): boolean {
+    const lowerValue = value.toLowerCase();
+
+    if (this.allowlist.has(lowerValue)) {
+      return true;
+    }
+
+    // For emails, check domain allowlist
+    if (type === 'email') {
+      const domain = lowerValue.split('@')[1];
+      if (domain && this.allowlistDomains.has(domain)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  private calculateConfidence(type: PIIType, value: string): number {
+    // Simple confidence scoring based on format strictness
+    switch (type) {
+      case 'ssn':
+        return 0.95; // High confidence for strict format
+      case 'credit_card':
+        return 0.95; // High confidence for strict format
+      case 'email':
+        return 0.9;
+      case 'phone':
+        return 0.85;
+      case 'api_key':
+        // Higher confidence for longer keys or known prefixes
+        if (value.startsWith('sk-') || value.startsWith('gsk_')) {
+          return 0.95;
+        }
+        return 0.7; // Lower confidence due to possible false positives
+      case 'ip_address':
+        return 0.8;
+      default:
+        return 0.8;
+    }
+  }
+}

package/src/guardrails/plugins/pii-redactor/index.ts

@@ -0,0 +1,203 @@
+import { BaseGuardrailPlugin } from '../base-plugin.js';
+import { GuardrailPhase, GuardrailContext, GuardrailResult } from '../../types.js';
+import { PIIRedactorConfig } from '../../../config/types.js';
+import { PIIDetector, PIIDetectorConfig } from './detectors.js';
+import { Pseudonymizer } from './pseudonymizer.js';
+import { logger } from '../../../utils/logger.js';
+
+/**
+ * PII Redactor plugin - detects and redacts sensitive data
+ */
+export class PIIRedactorPlugin extends BaseGuardrailPlugin {
+  name = 'pii_redactor';
+  phases: GuardrailPhase[] = ['pre_request', 'post_response', 'pre_tool_input', 'post_tool_output'];
+
+  private detector!: PIIDetector;
+  private pseudonymizer!: Pseudonymizer;
+  private restoreOnResponse: boolean = false;
+  private logDetections: boolean = true;
+
+  async initialize(config: Record<string, unknown>): Promise<void> {
+    await super.initialize(config);
+
+    const typedConfig = config as Partial<PIIRedactorConfig>;
+
+    const detectorConfig: PIIDetectorConfig = {
+      detectEmails: typedConfig.detect_emails ?? true,
+      detectPhones: typedConfig.detect_phones ?? true,
+      detectSSN: typedConfig.detect_ssn ?? true,
+      detectAPIKeys: typedConfig.detect_api_keys ?? true,
+      detectCreditCards: typedConfig.detect_credit_cards ?? true,
+      detectIPAddresses: typedConfig.detect_ip_addresses ?? false,
+      customPatterns: typedConfig.custom_patterns ?? [],
+      allowlist: typedConfig.allowlist ?? [],
+      allowlistDomains: typedConfig.allowlist_domains ?? [],
+    };
+
+    this.detector = new PIIDetector(detectorConfig);
+    this.pseudonymizer = new Pseudonymizer();
+    this.restoreOnResponse = typedConfig.restore_on_response ?? false;
+    this.logDetections = typedConfig.log_detections ?? true;
+    this.priority = typedConfig.priority ?? 25;
+  }
+
+  async execute(phase: GuardrailPhase, context: GuardrailContext): Promise<GuardrailResult> {
+    switch (phase) {
+      case 'pre_request':
+      case 'pre_tool_input':
+        return this.redactPII(context, phase);
+
+      case 'post_response':
+      case 'post_tool_output':
+        if (this.restoreOnResponse) {
+          return this.restorePII(context, phase);
+        }
+        return this.allow(context);
+
+      default:
+        return this.allow(context);
+    }
+  }
+
+  private redactPII(
+    context: GuardrailContext,
+    phase: GuardrailPhase
+  ): Promise<GuardrailResult> {
+    let textToScan: string;
+    let field: string;
+
+    if (phase === 'pre_request') {
+      textToScan = context.prompt || '';
+      field = 'prompt';
+    } else {
+      textToScan = JSON.stringify(context.toolArgs || {});
+      field = 'toolArgs';
+    }
+
+    if (!textToScan) {
+      return Promise.resolve(this.allow(context));
+    }
+
+    const detections = this.detector.detect(textToScan);
+
+    if (detections.length === 0) {
+      return Promise.resolve(this.allow(context));
+    }
+
+    // Log detections
+    if (this.logDetections) {
+      logger.info(`PII detected in ${field}:`, {
+        requestId: context.requestId,
+        types: [...new Set(detections.map((d) => d.type))],
+        count: detections.length,
+      });
+    }
+
+    // Pseudonymize
+    const { text: redactedText, mappings } = this.pseudonymizer.pseudonymize(
+      textToScan,
+      detections
+    );
+
+    // Store mappings for potential restoration
+    context.metadata.set('pii_mappings', mappings);
+
+    // Record modification
+    this.addModification(
+      context,
+      phase,
+      field,
+      `Redacted ${detections.length} PII items: ${[...new Set(detections.map((d) => d.type))].join(', ')}`,
+      undefined, // Don't store original (contains PII)
+      undefined  // Don't store new (would expose placeholder patterns)
+    );
+
+    // Apply modification
+    if (phase === 'pre_request') {
+      context.prompt = redactedText;
+      // Also update the last message if present
+      if (context.messages.length > 0) {
+        const lastIndex = context.messages.length - 1;
+        context.messages[lastIndex] = {
+          ...context.messages[lastIndex],
+          content: redactedText,
+        };
+      }
+    } else {
+      try {
+        context.toolArgs = JSON.parse(redactedText) as Record<string, unknown>;
+      } catch {
+        // If parse fails, store as string
+        context.toolArgs = { _redacted: redactedText };
+      }
+    }
+
+    return Promise.resolve(this.modify(context));
+  }
+
+  private restorePII(
+    context: GuardrailContext,
+    phase: GuardrailPhase
+  ): Promise<GuardrailResult> {
+    const mappings = context.metadata.get('pii_mappings') as Map<string, string> | undefined;
+
+    if (!mappings || mappings.size === 0) {
+      return Promise.resolve(this.allow(context));
+    }
+
+    let textToRestore: string;
+
+    if (phase === 'post_response') {
+      textToRestore = context.response || '';
+    } else {
+      textToRestore =
+        typeof context.toolResult === 'string'
+          ? context.toolResult
+          : JSON.stringify(context.toolResult);
+    }
+
+    if (!textToRestore) {
+      return Promise.resolve(this.allow(context));
+    }
+
+    const restoredText = this.pseudonymizer.restore(textToRestore, mappings);
+
+    // Only modify if something changed
+    if (restoredText === textToRestore) {
+      return Promise.resolve(this.allow(context));
+    }
+
+    this.addModification(
+      context,
+      phase,
+      phase === 'post_response' ? 'response' : 'toolResult',
+      `Restored ${mappings.size} PII placeholders`
+    );
+
+    if (phase === 'post_response') {
+      context.response = restoredText;
+    } else {
+      try {
+        context.toolResult = JSON.parse(restoredText) as unknown;
+      } catch {
+        context.toolResult = restoredText;
+      }
+    }
+
+    return Promise.resolve(this.modify(context));
+  }
+
+  /**
+   * Get detector for testing
+   */
+  getDetector(): PIIDetector {
+    return this.detector;
+  }
+
+  /**
+   * Get pseudonymizer for testing
+   */
+  getPseudonymizer(): Pseudonymizer {
+    return this.pseudonymizer;
+  }
+}

package/src/guardrails/plugins/pii-redactor/pseudonymizer.ts

@@ -0,0 +1,91 @@
+import { PIIDetection, PIIType } from './detectors.js';
+
+/**
+ * Pseudonymizer - replaces PII with numbered placeholders
+ * and supports optional restoration
+ */
+export class Pseudonymizer {
+  private counters: Map<PIIType, number> = new Map();
+
+  /**
+   * Pseudonymize text by replacing PII with placeholders
+   * Returns the modified text and a mapping for restoration
+   */
+  pseudonymize(
+    text: string,
+    detections: PIIDetection[]
+  ): { text: string; mappings: Map<string, string> } {
+    const mappings = new Map<string, string>();
+    let result = text;
+    let offset = 0;
+
+    // Reset counters for consistent numbering
+    this.counters.clear();
+
+    for (const detection of detections) {
+      const placeholder = this.generatePlaceholder(detection.type);
+      mappings.set(placeholder, detection.value);
+
+      // Replace in text (accounting for previous replacements)
+      const start = detection.startIndex + offset;
+      const end = detection.endIndex + offset;
+      result = result.substring(0, start) + placeholder + result.substring(end);
+
+      // Adjust offset for next replacement
+      offset += placeholder.length - detection.value.length;
+    }
+
+    return { text: result, mappings };
+  }
+
+  /**
+   * Restore placeholders in text with original values
+   */
+  restore(text: string, mappings: Map<string, string>): string {
+    let result = text;
+
+    for (const [placeholder, original] of mappings) {
+      // Use global replace to handle multiple occurrences
+      result = result.replace(
+        new RegExp(this.escapeRegex(placeholder), 'g'),
+        original
+      );
+    }
+
+    return result;
+  }
+
+  /**
+   * Generate a placeholder for a PII type
+   */
+  private generatePlaceholder(type: PIIType): string {
+    const count = (this.counters.get(type) || 0) + 1;
+    this.counters.set(type, count);
+
+    const typeLabels: Record<PIIType, string> = {
+      email: 'EMAIL',
+      phone: 'PHONE',
+      ssn: 'SSN',
+      api_key: 'API_KEY',
+      credit_card: 'CARD',
+      ip_address: 'IP',
+      custom: 'REDACTED',
+    };
+
+    return `[${typeLabels[type]}_${count}]`;
+  }
+
+  /**
+   * Escape special regex characters in a string
+   */
+  private escapeRegex(str: string): string {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+
+  /**
+   * Reset counters (for testing)
+   */
+  reset(): void {
+    this.counters.clear();
+  }
+}