visus-mcp 0.2.0 → 0.6.0

package/src/sanitizer/index.ts

@@ -10,12 +10,14 @@
 
 import { detectAndNeutralize, getSeverityScore, hasCriticalThreats } from './injection-detector.js';
 import { redactPII } from './pii-redactor.js';
+import { generateThreatReport, type ThreatReport } from './threat-reporter.js';
 
 export interface SanitizationResult {
   content: string;
   sanitization: {
     patterns_detected: string[];
     pii_types_redacted: string[];
+    pii_allowlisted: Array<{ type: string; value: string; reason: string }>;
     content_modified: boolean;
   };
   metadata: {
@@ -30,6 +32,7 @@ export interface SanitizationResult {
       low: number;
     };
   };
+  threat_report?: ThreatReport;
 }
 
 /**
@@ -37,20 +40,21 @@ export interface SanitizationResult {
  *
  * Pipeline:
  * 1. Injection detection and neutralization (43 patterns)
- * 2. PII redaction (email, phone, SSN, CC, IP)
+ * 2. PII redaction (email, phone, SSN, CC, IP) with allowlisting
  * 3. Metadata collection and logging
  *
  * @param content Raw content from web page
+ * @param sourceUrl Optional source URL for domain-scoped PII allowlisting
  * @returns Sanitized content with detection metadata
  */
-export function sanitize(content: string): SanitizationResult {
+export function sanitize(content: string, sourceUrl?: string): SanitizationResult {
   const originalLength = content.length;
 
   // Step 1: Detect and neutralize injection patterns
   const injectionResult = detectAndNeutralize(content);
 
-  // Step 2: Redact PII from the already-sanitized content
-  const piiResult = redactPII(injectionResult.content);
+  // Step 2: Redact PII from the already-sanitized content (with allowlisting)
+  const piiResult = redactPII(injectionResult.content, sourceUrl);
 
   // Step 3: Combine results
   const finalContent = piiResult.content;
@@ -63,16 +67,26 @@ export function sanitize(content: string): SanitizationResult {
   logSanitization({
     patterns_detected: injectionResult.patterns_detected,
     pii_types_redacted: piiResult.pii_types_redacted,
+    pii_allowlisted: piiResult.pii_allowlisted,
     severity_score: severityScore,
     has_critical_threats: criticalThreats,
     content_modified: contentModified
   });
 
-  return {
+  // Step 4: Generate threat report (only if findings exist)
+  const threatReport = generateThreatReport({
+    patterns_detected: injectionResult.patterns_detected,
+    pii_redacted: piiResult.pii_types_redacted.length,
+    source_url: sourceUrl || 'unknown',
+    detections_by_severity: injectionResult.metadata.detections_by_severity
+  });
+
+  const result: SanitizationResult = {
     content: finalContent,
     sanitization: {
       patterns_detected: injectionResult.patterns_detected,
       pii_types_redacted: piiResult.pii_types_redacted,
+      pii_allowlisted: piiResult.pii_allowlisted,
       content_modified: contentModified
     },
     metadata: {
@@ -83,6 +97,13 @@ export function sanitize(content: string): SanitizationResult {
       detections_by_severity: injectionResult.metadata.detections_by_severity
     }
   };
+
+  // Include threat_report only if findings exist
+  if (threatReport) {
+    result.threat_report = threatReport;
+  }
+
+  return result;
 }
 
 /**
@@ -92,6 +113,7 @@ export function sanitize(content: string): SanitizationResult {
 function logSanitization(event: {
   patterns_detected: string[];
   pii_types_redacted: string[];
+  pii_allowlisted: Array<{ type: string; value: string; reason: string }>;
   severity_score: number;
   has_critical_threats: boolean;
   content_modified: boolean;
@@ -103,7 +125,7 @@ function logSanitization(event: {
   };
 
   // Only log if there were detections (reduce noise)
-  if (event.content_modified) {
+  if (event.content_modified || event.pii_allowlisted.length > 0) {
     console.error(JSON.stringify(logEntry));
   }
 }

package/src/sanitizer/patterns.ts

@@ -313,7 +313,7 @@ export const INJECTION_PATTERNS: InjectionPattern[] = [
   {
     name: 'code_execution_requests',
     description: 'Requests code execution or contains dangerous code patterns',
-    regex: /\b(execute|run\s+the\s+following|eval\(|exec\(|os\.system|subprocess|__import__|shell\s+command|bash\s+-c)\b/gi,
+    regex: /\b(execute(?!-api\.)|run\s+the\s+following|eval\(|exec\(|os\.system|subprocess|__import__|shell\s+command|bash\s+-c)\b/gi,
     severity: 'high',
     action: 'redact'
   },

package/src/sanitizer/pii-allowlist.ts

@@ -0,0 +1,273 @@
+/**
+ * PII Allowlist Configuration
+ *
+ * Defines trusted phone numbers that should NOT be redacted from web content.
+ * Primarily for verified health authority and government emergency numbers.
+ *
+ * CRITICAL: Only add numbers that are:
+ * 1. Publicly published institutional/government numbers
+ * 2. Verified health/safety authorities
+ * 3. Not personal contact information
+ */
+
+export interface TrustedPhoneNumber {
+  /** Display name for logging */
+  name: string;
+  /** Normalized phone number variants (all formats this number might appear in) */
+  numbers: string[];
+  /** Optional: domains where this number is trusted (empty = trusted everywhere) */
+  trustedDomains?: string[];
+  /** Category for audit logging */
+  category: 'emergency' | 'health_authority' | 'government' | 'helpline';
+}
+
+export interface PIIAllowlistConfig {
+  /** When true, trusted numbers only preserved if source domain matches trustedDomains */
+  strictDomainMode: boolean;
+  /** List of verified trusted phone numbers */
+  trustedPhoneNumbers: TrustedPhoneNumber[];
+}
+
+/**
+ * Normalize a phone number to digits-only format for comparison
+ */
+export function normalizePhoneNumber(phone: string): string {
+  return phone.replace(/\D/g, '');
+}
+
+/**
+ * Extract domain from URL (returns hostname without www.)
+ */
+export function extractDomain(url: string): string {
+  try {
+    const parsedUrl = new URL(url);
+    return parsedUrl.hostname.replace(/^www\./, '').toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Built-in allowlist of verified health authority and emergency numbers
+ */
+export const DEFAULT_ALLOWLIST: PIIAllowlistConfig = {
+  strictDomainMode: false, // Default: trust globally, not domain-scoped
+
+  trustedPhoneNumbers: [
+    // Emergency Services
+    {
+      name: 'Emergency Services (911)',
+      numbers: ['911'],
+      category: 'emergency'
+    },
+
+    // Poison Control
+    {
+      name: 'Poison Control Center',
+      numbers: [
+        '18002221222',
+        '8002221222',
+        '1-800-222-1222',
+        '800-222-1222'
+      ],
+      trustedDomains: [
+        'medlineplus.gov',
+        'cdc.gov',
+        'fda.gov',
+        'aapcc.org',
+        'poison.org',
+        'nih.gov',
+        'nlm.nih.gov'
+      ],
+      category: 'health_authority'
+    },
+
+    // FDA MedWatch (adverse event reporting)
+    {
+      name: 'FDA MedWatch',
+      numbers: [
+        '18003321088',
+        '8003321088',
+        '1-800-332-1088',
+        '800-332-1088'
+      ],
+      trustedDomains: [
+        'fda.gov',
+        'medlineplus.gov',
+        'cdc.gov',
+        'nih.gov'
+      ],
+      category: 'health_authority'
+    },
+
+    // CDC INFO
+    {
+      name: 'CDC INFO',
+      numbers: [
+        '18002324636',
+        '8002324636',
+        '1-800-232-4636',
+        '800-232-4636'
+      ],
+      trustedDomains: [
+        'cdc.gov',
+        'medlineplus.gov',
+        'nih.gov'
+      ],
+      category: 'health_authority'
+    },
+
+    // SAMHSA National Helpline (substance abuse/mental health)
+    {
+      name: 'SAMHSA National Helpline',
+      numbers: [
+        '18006624357',
+        '8006624357',
+        '1-800-662-4357',
+        '800-662-4357'
+      ],
+      trustedDomains: [
+        'samhsa.gov',
+        'medlineplus.gov',
+        'cdc.gov',
+        'nih.gov'
+      ],
+      category: 'helpline'
+    },
+
+    // National Suicide Prevention Lifeline
+    {
+      name: 'National Suicide Prevention Lifeline',
+      numbers: [
+        '18002738255',
+        '8002738255',
+        '1-800-273-8255',
+        '800-273-8255',
+        '988' // New 3-digit code
+      ],
+      trustedDomains: [
+        'suicidepreventionlifeline.org',
+        'samhsa.gov',
+        'medlineplus.gov',
+        'cdc.gov',
+        'nih.gov'
+      ],
+      category: 'helpline'
+    },
+
+    // National Domestic Violence Hotline
+    {
+      name: 'National Domestic Violence Hotline',
+      numbers: [
+        '18007997233',
+        '8007997233',
+        '1-800-799-7233',
+        '800-799-7233'
+      ],
+      trustedDomains: [
+        'thehotline.org',
+        'cdc.gov',
+        'medlineplus.gov',
+        'nih.gov'
+      ],
+      category: 'helpline'
+    },
+
+    // Medicare
+    {
+      name: 'Medicare',
+      numbers: [
+        '18006331795',
+        '8006331795',
+        '1-800-633-1795',
+        '800-633-1795'
+      ],
+      trustedDomains: [
+        'medicare.gov',
+        'cms.gov',
+        'medlineplus.gov',
+        'nih.gov'
+      ],
+      category: 'government'
+    },
+
+    // Veterans Crisis Line
+    {
+      name: 'Veterans Crisis Line',
+      numbers: [
+        '18002738255',
+        '8002738255',
+        '1-800-273-8255',
+        '800-273-8255'
+      ],
+      trustedDomains: [
+        'va.gov',
+        'veteranscrisisline.net',
+        'medlineplus.gov',
+        'nih.gov'
+      ],
+      category: 'helpline'
+    }
+  ]
+};
+
+/**
+ * Check if a phone number should be allowlisted (not redacted)
+ *
+ * @param phoneNumber The phone number to check (in any format)
+ * @param sourceUrl Optional source URL for domain-scoped allowlisting
+ * @param config Optional custom config (defaults to DEFAULT_ALLOWLIST)
+ * @returns The trusted number entry if allowlisted, null otherwise
+ */
+export function isAllowlistedPhoneNumber(
+  phoneNumber: string,
+  sourceUrl?: string,
+  config: PIIAllowlistConfig = DEFAULT_ALLOWLIST
+): TrustedPhoneNumber | null {
+  const normalized = normalizePhoneNumber(phoneNumber);
+  const sourceDomain = sourceUrl ? extractDomain(sourceUrl) : '';
+
+  for (const trustedEntry of config.trustedPhoneNumbers) {
+    // Check if any variant of this trusted number matches
+    const matchesNumber = trustedEntry.numbers.some(variant => {
+      const normalizedVariant = normalizePhoneNumber(variant);
+      return normalized === normalizedVariant;
+    });
+
+    if (!matchesNumber) {
+      continue; // Number doesn't match, check next entry
+    }
+
+    // Number matches - now check domain restrictions
+    const hasDomainRestrictions = trustedEntry.trustedDomains && trustedEntry.trustedDomains.length > 0;
+
+    if (!hasDomainRestrictions) {
+      // No domain restrictions - trust globally
+      return trustedEntry;
+    }
+
+    // Has domain restrictions
+    if (config.strictDomainMode && !sourceUrl) {
+      // Strict mode requires domain match, but no URL provided
+      continue;
+    }
+
+    if (sourceUrl && trustedEntry.trustedDomains) {
+      // Check if source domain matches any trusted domain
+      const isDomainTrusted = trustedEntry.trustedDomains.some(trustedDomain => {
+        return sourceDomain.endsWith(trustedDomain);
+      });
+
+      if (isDomainTrusted) {
+        return trustedEntry;
+      }
+    }
+
+    // In non-strict mode, trust the number even if domain doesn't match
+    if (!config.strictDomainMode) {
+      return trustedEntry;
+    }
+  }
+
+  return null; // No match found
+}

package/src/sanitizer/pii-redactor.ts

@@ -5,14 +5,23 @@
  * to prevent leakage of sensitive data to the LLM.
  *
  * Redacts: emails, phone numbers, SSNs, credit cards, IP addresses
+ * Supports allowlisting of trusted institutional phone numbers (e.g., Poison Control)
  */
 
+import {
+  isAllowlistedPhoneNumber,
+  type PIIAllowlistConfig,
+  DEFAULT_ALLOWLIST
+} from './pii-allowlist.js';
+
 export interface PIIRedactionResult {
   content: string;
   pii_types_redacted: string[];
+  pii_allowlisted: Array<{ type: string; value: string; reason: string }>;
   content_modified: boolean;
   metadata: {
     redaction_counts: Record<string, number>;
+    allowlist_counts: Record<string, number>;
   };
 }
 
@@ -151,10 +160,20 @@ function luhnCheck(digits: string): boolean {
 
 /**
  * Redact PII from content
+ *
+ * @param content Content to redact PII from
+ * @param sourceUrl Optional source URL for domain-scoped allowlisting
+ * @param allowlistConfig Optional custom allowlist config
  */
-export function redactPII(content: string): PIIRedactionResult {
+export function redactPII(
+  content: string,
+  sourceUrl?: string,
+  allowlistConfig: PIIAllowlistConfig = DEFAULT_ALLOWLIST
+): PIIRedactionResult {
   const piiTypesRedacted = new Set<string>();
   const redactionCounts: Record<string, number> = {};
+  const allowlistCounts: Record<string, number> = {};
+  const piiAllowlisted: Array<{ type: string; value: string; reason: string }> = [];
   let sanitizedContent = content;
 
   for (const pattern of PII_PATTERNS) {
@@ -168,6 +187,26 @@ export function redactPII(content: string): PIIRedactionResult {
         continue;
       }
 
+      // Check allowlist for phone numbers
+      if (pattern.type === 'PHONE') {
+        const allowlistedEntry = isAllowlistedPhoneNumber(
+          matchedText,
+          sourceUrl,
+          allowlistConfig
+        );
+
+        if (allowlistedEntry) {
+          // This is a trusted number - DO NOT redact
+          piiAllowlisted.push({
+            type: pattern.type,
+            value: matchedText,
+            reason: `Trusted ${allowlistedEntry.category}: ${allowlistedEntry.name}`
+          });
+          allowlistCounts[pattern.name] = (allowlistCounts[pattern.name] || 0) + 1;
+          continue; // Skip redaction
+        }
+      }
+
       // Redact the PII
       sanitizedContent = sanitizedContent.replace(
         matchedText,
@@ -182,9 +221,11 @@ export function redactPII(content: string): PIIRedactionResult {
   return {
     content: sanitizedContent,
     pii_types_redacted: Array.from(piiTypesRedacted),
+    pii_allowlisted: piiAllowlisted,
     content_modified: sanitizedContent !== content,
     metadata: {
-      redaction_counts: redactionCounts
+      redaction_counts: redactionCounts,
+      allowlist_counts: allowlistCounts
     }
   };
 }

package/src/sanitizer/severity-classifier.ts

@@ -0,0 +1,132 @@
+/**
+ * Severity Classification Engine
+ *
+ * Maps injection pattern categories to standardized severity levels.
+ * Used for threat reporting and compliance documentation.
+ */
+
+export type Severity = 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
+export type OverallSeverity = Severity | 'CLEAN';
+
+/**
+ * Pattern category to severity mapping
+ * Aligned with NIST AI 600-1 and OWASP LLM Top 10 risk levels
+ */
+const SEVERITY_MAP: Record<string, Severity> = {
+  // CRITICAL - Immediate threat, block-level
+  direct_instruction_injection: 'CRITICAL',
+  role_hijacking: 'CRITICAL',
+  system_prompt_extraction: 'CRITICAL',
+  privilege_escalation: 'CRITICAL',
+  data_exfiltration: 'CRITICAL',
+  code_execution_requests: 'CRITICAL',
+  memory_manipulation: 'CRITICAL',
+  jailbreak_keywords: 'CRITICAL',
+  ethical_override: 'CRITICAL',
+  credential_harvesting: 'CRITICAL',
+  html_script_injection: 'CRITICAL',
+
+  // HIGH - Significant threat
+  context_poisoning: 'HIGH',
+  base64_obfuscation: 'HIGH',
+  zero_width_characters: 'HIGH',
+  data_uri_injection: 'HIGH',
+  markdown_link_injection: 'HIGH',
+  instruction_delimiter_injection: 'HIGH',
+  token_smuggling: 'HIGH',
+  system_message_injection: 'HIGH',
+  file_system_access: 'HIGH',
+  training_data_extraction: 'HIGH',
+  nested_encoding: 'HIGH',
+  authority_impersonation: 'HIGH',
+  callback_url_injection: 'HIGH',
+
+  // MEDIUM - Moderate threat
+  comment_injection: 'MEDIUM',
+  unicode_lookalikes: 'MEDIUM',
+  url_fragment_hashjack: 'MEDIUM',
+  social_engineering_urgency: 'MEDIUM',
+  multi_language_obfuscation: 'MEDIUM',
+  reverse_text_obfuscation: 'MEDIUM',
+  conversation_reset: 'MEDIUM',
+  chain_of_thought_manipulation: 'MEDIUM',
+  hypothetical_scenario_injection: 'MEDIUM',
+  output_format_manipulation: 'MEDIUM',
+  simulator_mode: 'MEDIUM',
+  payload_splitting: 'MEDIUM',
+  css_hiding: 'MEDIUM',
+  testing_debugging_claims: 'MEDIUM',
+
+  // LOW - Low threat, flagged for awareness
+  leetspeak_obfuscation: 'LOW',
+  capability_probing: 'LOW',
+  negative_instruction: 'LOW',
+  time_based_triggers: 'LOW',
+  whitespace_steganography: 'LOW'
+};
+
+/**
+ * Classify severity for a single pattern category
+ */
+export function classifySeverity(patternCategory: string): Severity {
+  return SEVERITY_MAP[patternCategory] || 'LOW';
+}
+
+/**
+ * Interface for a threat finding
+ */
+export interface Finding {
+  pattern_category: string;
+  severity: Severity;
+}
+
+/**
+ * Aggregate severity across multiple findings
+ * Returns the highest severity level found, or CLEAN if no findings
+ */
+export function aggregateSeverity(findings: Finding[]): OverallSeverity {
+  if (findings.length === 0) {
+    return 'CLEAN';
+  }
+
+  const severities = findings.map(f => f.severity);
+
+  if (severities.includes('CRITICAL')) return 'CRITICAL';
+  if (severities.includes('HIGH')) return 'HIGH';
+  if (severities.includes('MEDIUM')) return 'MEDIUM';
+  if (severities.includes('LOW')) return 'LOW';
+
+  return 'CLEAN';
+}
+
+/**
+ * Count findings by severity level
+ */
+export function countBySeverity(findings: Finding[]): Record<Severity, number> {
+  const counts: Record<Severity, number> = {
+    CRITICAL: 0,
+    HIGH: 0,
+    MEDIUM: 0,
+    LOW: 0
+  };
+
+  for (const finding of findings) {
+    counts[finding.severity]++;
+  }
+
+  return counts;
+}
+
+/**
+ * Get emoji for severity level (for Markdown reports)
+ */
+export function getSeverityEmoji(severity: Severity | OverallSeverity): string {
+  switch (severity) {
+    case 'CRITICAL': return '🔴';
+    case 'HIGH': return '🟠';
+    case 'MEDIUM': return '🟡';
+    case 'LOW': return '🟢';
+    case 'CLEAN': return '✅';
+    default: return '⚪';
+  }
+}