@oculum/scanner 1.0.0

package/src/layer2/ai-rag-safety.ts

@@ -0,0 +1,511 @@
+/**
+ * Layer 2: RAG Data Safety Detection
+ * Detects data exfiltration risks in Retrieval Augmented Generation systems
+ *
+ * Covers:
+ * - M5.1: RAG data exfiltration (cross-tenant retrieval, raw context exposure)
+ * - Unscoped vector store queries
+ * - Raw retrieved context in responses
+ * - Context logging risks
+ */
+
+import type { Vulnerability, VulnerabilitySeverity } from '../types'
+import {
+  isComment,
+  isTestOrMockFile,
+  isDocumentationFile,
+  isScannerOrFixtureFile,
+  isExampleDirectory,
+  isLibraryCode,
+} from '../utils/context-helpers'
+
+// ============================================================================
+// Context Detection
+// ============================================================================
+
+/**
+ * Check if file uses client-side fuzzy search libraries (not vector stores)
+ * These are safe local search implementations, not cross-tenant data access risks
+ */
+function isClientSideFuzzySearch(content: string): boolean {
+  const fuzzySearchPatterns = [
+    // Fuse.js - client-side fuzzy search
+    /import.*from\s+['"]fuse\.js['"]/i,
+    /require\s*\(\s*['"]fuse\.js['"]\s*\)/i,
+    /new\s+Fuse\s*\(/i,
+    // Other client-side search libraries
+    /import.*from\s+['"]flexsearch['"]/i,
+    /import.*from\s+['"]lunr['"]/i,
+    /import.*from\s+['"]minisearch['"]/i,
+    /import.*from\s+['"]fuzzysort['"]/i,
+    /import.*from\s+['"]match-sorter['"]/i,
+  ]
+  return fuzzySearchPatterns.some(p => p.test(content))
+}
+
+/**
+ * Check if a line contains a generic query pattern that is NOT a vector store query
+ * These are common web framework patterns that should not be flagged as RAG issues
+ */
+function isGenericQueryPattern(lineContent: string): boolean {
+  const genericQueryPatterns = [
+    // Express/Hono/Koa query params
+    /req\.query\s*\(/i,
+    /c\.req\.query\s*\(/i,
+    /ctx\.query\s*\(/i,
+    /request\.query\s*\(/i,
+    // URL search params
+    /searchParams\.get\s*\(/i,
+    /url\.searchParams/i,
+    /URLSearchParams/i,
+    // Query string parsing
+    /querystring\.parse/i,
+    /qs\.parse/i,
+    // Database query builders (not vector stores)
+    /\.query\s*\(\s*['"`]SELECT/i,
+    /\.query\s*\(\s*['"`]INSERT/i,
+    /\.query\s*\(\s*['"`]UPDATE/i,
+    /\.query\s*\(\s*['"`]DELETE/i,
+    // GraphQL queries
+    /graphql.*query/i,
+    /useQuery\s*\(/i,
+    /useLazyQuery\s*\(/i,
+    // tRPC/React Query
+    /trpc\.\w+\.\w+\.query/i,
+    /\.useQuery\s*\(/i,
+    // Prisma/Drizzle queries
+    /prisma\.\w+\.findMany/i,
+    /db\.query\./i,
+    // Generic method chaining that isn't vector search
+    /\.query\s*\(\s*\)/i,  // Empty query call
+  ]
+  return genericQueryPatterns.some(p => p.test(lineContent))
+}
+
+/**
+ * Check if file has vector store imports (required for RAG detection)
+ */
+function hasVectorStoreImport(content: string): boolean {
+  const vectorStoreImports = [
+    /from\s+['"]pinecone/i,
+    /from\s+['"]@pinecone-database/i,
+    /from\s+['"]weaviate/i,
+    /from\s+['"]chromadb/i,
+    /from\s+['"]@qdrant/i,
+    /from\s+['"]qdrant/i,
+    /from\s+['"]@langchain\/vectorstores/i,
+    /from\s+['"]langchain\/vectorstores/i,
+    /from\s+['"]faiss/i,
+    /from\s+['"]milvus/i,
+    /from\s+['"]@supabase.*vector/i,
+    /pgvector/i,
+    /VectorStore/i,
+    /Embeddings/i,
+  ]
+  return vectorStoreImports.some(p => p.test(content))
+}
+
+/**
+ * Check if a file is in a RAG/retrieval context based on path and content
+ */
+function isRAGContextFile(filePath: string, content: string): boolean {
+  // Skip client-side fuzzy search libraries - these are NOT vector stores
+  if (isClientSideFuzzySearch(content)) {
+    return false
+  }
+
+  // Must have vector store imports to be considered RAG context
+  if (!hasVectorStoreImport(content)) {
+    return false
+  }
+
+  // File path indicators of RAG code
+  const ragPathPatterns = [
+    /\/(rag|retrieval|retriever|embedding|vector|knowledge)\//i,
+    /\/(search|index|indexer|embeddings?)\//i,
+    /(rag|retriever|embedding|vector|knowledge).*\.(ts|js|tsx|jsx|py)$/i,
+    /(search|retrieval|indexer).*\.(ts|js|tsx|jsx|py)$/i,
+  ]
+
+  if (ragPathPatterns.some(p => p.test(filePath))) {
+    return true
+  }
+
+  // Content patterns suggesting RAG usage - must be actual vector store clients
+  const ragContentPatterns = [
+    // Vector store patterns - specific to actual vector DBs
+    /VectorStore|Embeddings?|Retriever/i,
+    /similaritySearch|query_engine|retriever/i,
+    /vectorStore|embeddingModel|documentLoader/i,
+    // Framework imports - actual vector store SDKs
+    /from\s+['"](?:langchain|llama[-_]?index|@pinecone|@qdrant|chromadb|weaviate)/i,
+    /import.*(?:Pinecone|Chroma|Weaviate|Qdrant|Milvus|PGVector)/i,
+    // Vercel AI SDK RAG
+    /VercelKVVectorStore|SupabaseVectorStore|createEmbedding/i,
+    // Query patterns - but NOT generic .search() which could be Fuse.js
+    /\.retrieve\(|\.query\(/i,
+    /sourceDocuments|retrievedDocs|retrievedChunks/i,
+    // Supabase vector search
+    /\.rpc\s*\(\s*['"`]match_documents/i,
+    /pgvector|embedding.*vector/i,
+  ]
+
+  return ragContentPatterns.some(p => p.test(content))
+}
+
+/**
+ * Check if line/context has access control scoping
+ */
+function hasAccessControlScoping(context: string): boolean {
+  const accessPatterns = [
+    // User/tenant scoping
+    /userId|user_id|user\.id|currentUser/i,
+    /tenantId|tenant_id|tenant\.id|orgId|org_id|workspaceId/i,
+    // Filter parameters
+    /filter\s*[:=]\s*\{[^}]*(?:user|tenant|org)/i,
+    /where\s*[:=].*(?:user|tenant|org)/i,
+    /metadata\s*[:=].*(?:user|tenant|org)/i,
+    /namespace\s*[:=]/i,
+    // Access check functions
+    /checkAccess|verifyPermission|canRead|canAccess|hasAccess/i,
+    /getAuthorized|filterByUser|filterByTenant/i,
+  ]
+  return accessPatterns.some(p => p.test(context))
+}
+
+/**
+ * Check if response is filtered/processed before return
+ */
+function hasResponseFiltering(context: string): boolean {
+  const filterPatterns = [
+    // Content filtering
+    /\.map\s*\([^)]*\.(title|name|id|metadata)\)/i,
+    /\.filter\s*\(/i,
+    /sanitize|redact|mask|strip/i,
+    // Only returning specific fields
+    /return\s*\{[^}]*(?:id|title|summary)[^}]*\}(?![^}]*content)/i,
+  ]
+  return filterPatterns.some(p => p.test(context))
+}
+
+/**
+ * Check if there's authentication in the route/function
+ */
+function hasAuthenticationInContext(content: string): boolean {
+  const authPatterns = [
+    /getSession|getCurrentUser|getServerSession/i,
+    /auth\(\)|requireAuth|verifyToken/i,
+    /req\.user|request\.user|context\.user/i,
+    /isAuthenticated|checkAuth|withAuth/i,
+    /Authorization.*Bearer/i,
+    /userId|user\.id|currentUserId/i,
+  ]
+  return authPatterns.some(p => p.test(content))
+}
+
+/**
+ * Get surrounding context lines
+ */
+function getSurroundingContext(content: string, lineIndex: number, windowSize: number = 25): string {
+  const lines = content.split('\n')
+  const start = Math.max(0, lineIndex - windowSize)
+  const end = Math.min(lines.length, lineIndex + windowSize)
+  return lines.slice(start, end).join('\n')
+}
+
+// ============================================================================
+// Pattern Definitions
+// ============================================================================
+
+interface RAGSafetyPattern {
+  name: string
+  pattern: RegExp
+  riskType: 'unscoped_retrieval' | 'context_exposure' | 'context_logging'
+  baseSeverity: VulnerabilitySeverity
+  description: string
+  suggestedFix: string
+}
+
+/**
+ * Unscoped retrieval query patterns
+ * Detects vector store queries without user/tenant filtering
+ */
+const UNSCOPED_RETRIEVAL_PATTERNS: RAGSafetyPattern[] = [
+  // Generic vector store queries
+  {
+    name: 'Unscoped vector store query',
+    pattern: /\.(?:query|search|similaritySearch|retrieve)\s*\(\s*(?:["'`][^"'`]+["'`]|[a-zA-Z_]\w*)\s*\)/gi,
+    riskType: 'unscoped_retrieval',
+    baseSeverity: 'high',
+    description: 'Vector store query without user/tenant scoping. Retrieved documents may belong to other users, enabling cross-tenant data access.',
+    suggestedFix: 'Add filter/metadata parameter to scope queries: .query(query, { filter: { userId: currentUser.id } })',
+  },
+  // LangChain retriever invoke
+  {
+    name: 'LangChain retriever without filter',
+    pattern: /retriever\.(?:invoke|getRelevantDocuments)\s*\(\s*(?:["'`][^"'`]+["'`]|[a-zA-Z_]\w*)\s*\)/gi,
+    riskType: 'unscoped_retrieval',
+    baseSeverity: 'high',
+    description: 'LangChain retriever invocation without metadata filter. Documents from all users may be retrieved.',
+    suggestedFix: 'Use a filtered retriever or add metadata filter: retriever.invoke(query, { filter: { userId } })',
+  },
+  // LlamaIndex query engine
+  {
+    name: 'LlamaIndex query engine without filter',
+    pattern: /query_engine\.query\s*\(\s*["'`][^"'`]+["'`]\s*\)/gi,
+    riskType: 'unscoped_retrieval',
+    baseSeverity: 'high',
+    description: 'LlamaIndex query without node postprocessors or filters. All indexed documents are searchable.',
+    suggestedFix: 'Add node_postprocessors to filter by user/tenant metadata before retrieval.',
+  },
+  // Pinecone query
+  {
+    name: 'Pinecone query without metadata filter',
+    pattern: /\.query\s*\(\s*\{[^}]*(?:vector|topK)[^}]*\}\s*\)/gi,
+    riskType: 'unscoped_retrieval',
+    baseSeverity: 'medium',
+    description: 'Pinecone query may lack metadata filtering. Verify namespace or filter is set.',
+    suggestedFix: 'Add filter parameter: .query({ vector, topK, filter: { userId: { $eq: currentUserId } } })',
+  },
+  // Chroma query
+  {
+    name: 'Chroma collection query',
+    pattern: /collection\.query\s*\(\s*\{[^}]*query_texts[^}]*\}\s*\)/gi,
+    riskType: 'unscoped_retrieval',
+    baseSeverity: 'medium',
+    description: 'ChromaDB query without where filter. All documents in collection are searchable.',
+    suggestedFix: 'Add where parameter: collection.query({ query_texts, where: { userId: currentUserId } })',
+  },
+  // Weaviate search
+  {
+    name: 'Weaviate search without filter',
+    pattern: /\.nearText\s*\([^)]+\)\.(?:do|withLimit)/gi,
+    riskType: 'unscoped_retrieval',
+    baseSeverity: 'medium',
+    description: 'Weaviate nearText search without where filter. Results may include other users\' data.',
+    suggestedFix: 'Add .withWhere() to filter by user: .nearText({...}).withWhere({ path: ["userId"], operator: "Equal", valueString: userId })',
+  },
+  // Supabase vector search
+  {
+    name: 'Supabase vector search without RLS',
+    pattern: /\.rpc\s*\(\s*['"`]match_documents['"`]/gi,
+    riskType: 'unscoped_retrieval',
+    baseSeverity: 'medium',
+    description: 'Supabase vector search function called. Ensure RLS policies filter by user.',
+    suggestedFix: 'Verify Row Level Security (RLS) is enabled and filters documents by authenticated user.',
+  },
+]
+
+/**
+ * Raw context exposure patterns
+ * Detects retrieved documents being returned directly to clients
+ */
+const CONTEXT_EXPOSURE_PATTERNS: RAGSafetyPattern[] = [
+  // Returning sourceDocuments in response
+  {
+    name: 'Source documents in API response',
+    pattern: /(?:res\.json|NextResponse\.json|return)\s*\([^)]*(?:sourceDocuments|retrievedDocs|documents|chunks)/gi,
+    riskType: 'context_exposure',
+    baseSeverity: 'medium',
+    description: 'Raw retrieved documents returned in API response. Source content may leak sensitive information from the knowledge base.',
+    suggestedFix: 'Return only synthesized response or document IDs/titles. If source attribution needed, filter to metadata only.',
+  },
+  // Spreading documents into response
+  {
+    name: 'Retrieved context spread in response',
+    pattern: /(?:res\.json|return)\s*\(\s*\{[^}]*\.\.\.(?:docs|documents|chunks|sourceDocuments|context)/gi,
+    riskType: 'context_exposure',
+    baseSeverity: 'medium',
+    description: 'Retrieved document objects spread into response. Full document content may be exposed.',
+    suggestedFix: 'Extract and return only safe fields: { sources: docs.map(d => ({ id: d.id, title: d.title })) }',
+  },
+  // Returning raw context in response object
+  {
+    name: 'Raw retrieval context in response',
+    pattern: /return\s*\{[^}]*(?:context|retrievedContext|ragContext)\s*:/gi,
+    riskType: 'context_exposure',
+    baseSeverity: 'low',
+    description: 'Retrieved context included in response object. Review what data is actually exposed.',
+    suggestedFix: 'Ensure context field contains only safe, summarized content - not raw document text.',
+  },
+  // WebSocket/stream context exposure
+  {
+    name: 'Context in streaming response',
+    pattern: /(?:socket|ws|stream)\.(?:send|emit|write)\s*\([^)]*(?:sourceDocuments|context|chunks)/gi,
+    riskType: 'context_exposure',
+    baseSeverity: 'medium',
+    description: 'Retrieved context sent via streaming/WebSocket. Clients receive raw source data.',
+    suggestedFix: 'Stream only AI-generated text. Send source attribution separately with filtered metadata.',
+  },
+]
+
+/**
+ * Context logging patterns
+ * Detects logging of retrieved documents or prompts with context
+ */
+const CONTEXT_LOGGING_PATTERNS: RAGSafetyPattern[] = [
+  // Logging retrieved documents
+  {
+    name: 'Retrieved documents logged',
+    pattern: /(?:console|logger)\.\w+\s*\([^)]*(?:retrievedDocs|sourceDocuments|documents|chunks)/gi,
+    riskType: 'context_logging',
+    baseSeverity: 'info',
+    description: 'Retrieved documents logged. If logs are accessible, sensitive document content may be exposed.',
+    suggestedFix: 'Log document IDs/titles only: console.log("Retrieved:", docs.map(d => d.id))',
+  },
+  // Logging full prompt with context
+  {
+    name: 'Full prompt with context logged',
+    pattern: /(?:console|logger)\.\w+\s*\([^)]*(?:fullPrompt|promptWithContext|augmentedPrompt)/gi,
+    riskType: 'context_logging',
+    baseSeverity: 'low',
+    description: 'Full prompt (including retrieved context) logged. May expose sensitive document content in logs.',
+    suggestedFix: 'Log prompt length/metadata only. Avoid logging full prompt content in production.',
+  },
+  // Debug logging of RAG context
+  {
+    name: 'RAG context debug logging',
+    pattern: /(?:console\.(?:debug|log)|logger\.debug)\s*\([^)]*(?:context|ragContext|retrievalContext)/gi,
+    riskType: 'context_logging',
+    baseSeverity: 'info',
+    description: 'RAG context logged for debugging. Ensure debug logging is disabled in production.',
+    suggestedFix: 'Use conditional logging: if (process.env.NODE_ENV !== "production") console.debug(...)',
+  },
+  // Storing prompts with context
+  {
+    name: 'Prompt with context persisted',
+    pattern: /(?:\.create|\.insert|\.save)\s*\([^)]*(?:fullPrompt|promptWithContext|augmentedPrompt)/gi,
+    riskType: 'context_logging',
+    baseSeverity: 'medium',
+    description: 'Full prompt with retrieved context being persisted. May store sensitive document content.',
+    suggestedFix: 'Store user query and response separately. Do not persist raw retrieved context.',
+  },
+]
+
+// ============================================================================
+// Main Detection Function
+// ============================================================================
+
+/**
+ * Main detection function for RAG data safety issues
+ */
+export function detectRAGSafetyIssues(
+  content: string,
+  filePath: string
+): Vulnerability[] {
+  const vulnerabilities: Vulnerability[] = []
+
+  // Skip non-applicable files
+  if (isScannerOrFixtureFile(filePath)) return vulnerabilities
+  if (isDocumentationFile(filePath)) return vulnerabilities
+
+  // Only scan files in RAG context
+  if (!isRAGContextFile(filePath, content)) {
+    return vulnerabilities
+  }
+
+  const lines = content.split('\n')
+  const isTestFile = isTestOrMockFile(filePath)
+  const isExample = isExampleDirectory(filePath)
+  const isLibrary = isLibraryCode(filePath)
+  const hasAuth = hasAuthenticationInContext(content)
+
+  // Process all pattern categories
+  const allPatterns: RAGSafetyPattern[] = [
+    ...UNSCOPED_RETRIEVAL_PATTERNS,
+    ...CONTEXT_EXPOSURE_PATTERNS,
+    ...CONTEXT_LOGGING_PATTERNS,
+  ]
+
+  for (const pattern of allPatterns) {
+    const regex = new RegExp(pattern.pattern.source, pattern.pattern.flags)
+    let match
+
+    while ((match = regex.exec(content)) !== null) {
+      const lineNumber = content.substring(0, match.index).split('\n').length
+      const lineContent = lines[lineNumber - 1]?.trim() || ''
+
+      // Skip comments
+      if (isComment(lineContent)) continue
+
+      // Skip generic query patterns (req.query, searchParams, etc.)
+      if (isGenericQueryPattern(lineContent)) continue
+
+      // Get surrounding context for analysis
+      const context = getSurroundingContext(content, lineNumber - 1, 25)
+
+      // Calculate severity based on context
+      let severity = pattern.baseSeverity
+      let description = pattern.description
+      const notes: string[] = []
+
+      // Apply context-aware severity adjustments
+      if (pattern.riskType === 'unscoped_retrieval') {
+        // Check for access control in surrounding context
+        if (hasAccessControlScoping(context)) {
+          severity = 'info'
+          notes.push('Access control scoping detected nearby')
+        } else if (!hasAuth) {
+          // No auth at all - higher risk
+          if (severity === 'medium') severity = 'high'
+          notes.push('No authentication detected in this file')
+        }
+      }
+
+      if (pattern.riskType === 'context_exposure') {
+        // Check if response is filtered
+        if (hasResponseFiltering(context)) {
+          severity = 'info'
+          notes.push('Response filtering detected')
+        } else if (!hasAuth) {
+          // Unauthenticated endpoint exposing context - higher risk
+          if (severity === 'medium') severity = 'high'
+          notes.push('Endpoint may be unauthenticated')
+        }
+      }
+
+      // Downgrade test files
+      if (isTestFile) {
+        severity = 'info'
+        notes.push('in test file')
+      }
+
+      // Downgrade example/demo directories
+      if (isExample && severity !== 'info') {
+        severity = 'info'
+        notes.push('in example/demo directory')
+      }
+
+      // Downgrade library code - base classes are intentionally generic
+      if (isLibrary && severity !== 'info') {
+        severity = 'info'
+        notes.push('library code - consumers add access controls')
+      }
+
+      // Build final description
+      if (notes.length > 0) {
+        description += ` (${notes.join('; ')})`
+      }
+
+      vulnerabilities.push({
+        id: `ai-rag-${filePath}-${lineNumber}-${pattern.name.replace(/\s+/g, '-')}`,
+        filePath,
+        lineNumber,
+        lineContent,
+        severity,
+        category: 'ai_rag_exfiltration',
+        title: pattern.name,
+        description,
+        suggestedFix: pattern.suggestedFix,
+        confidence: severity === 'info' ? 'low' : 'medium',
+        layer: 2,
+        requiresAIValidation: severity !== 'info' && pattern.riskType !== 'context_logging',
+      })
+    }
+  }
+
+  return vulnerabilities
+}
+
+// Export helper for use in other modules
+export { isRAGContextFile }