@oculum/scanner 1.0.14 → 1.0.15

package/src/taint/llm-risk-scoring.ts

@@ -0,0 +1,412 @@
+/**
+ * LLM Risk Scoring
+ *
+ * Post-processing severity assessment for taint findings involving LLM calls.
+ * Absorbs mitigation logic from the old AST rules (prompt-hygiene-ast.ts,
+ * execution-sinks-ast.ts) into taint-engine-aware risk scoring.
+ *
+ * Called from taint-flow-ast.ts before emitting vulnerabilities.
+ */
+
+import type { TaintFinding } from './propagation-types'
+import type { VulnerabilitySeverity, VulnerabilityCategory } from '../shared/types'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface LLMRiskAssessment {
+  adjustedSeverity: VulnerabilitySeverity
+  adjustedCategory: VulnerabilityCategory
+  riskFactors: string[]
+  mitigations: string[]
+  contextRatio: number | null
+  note: string
+}
+
+// ============================================================================
+// Severity Adjustment Helpers
+// ============================================================================
+
+const SEVERITY_ORDER: VulnerabilitySeverity[] = ['info', 'low', 'medium', 'high', 'critical']
+
+function severityIndex(s: VulnerabilitySeverity): number {
+  return SEVERITY_ORDER.indexOf(s)
+}
+
+function reduceSeverity(s: VulnerabilitySeverity, steps: number): VulnerabilitySeverity {
+  const idx = severityIndex(s)
+  const newIdx = Math.max(0, idx - steps) // floor at 'info'
+  return SEVERITY_ORDER[newIdx]
+}
+
+// ============================================================================
+// Mitigation Heuristic Helpers
+// ============================================================================
+
+/** Get enclosing function body text from a taint finding's sink node */
+export function getEnclosingBodyText(finding: TaintFinding, content: string): string {
+  let current = finding.sink.node.parent
+  while (current) {
+    if (/function_declaration|arrow_function|function_expression|method_definition|function_definition/.test(current.type)) {
+      const bodyNode = current.childForFieldName('body') ?? current
+      return content.substring(bodyNode.startIndex, bodyNode.endIndex)
+    }
+    current = current.parent
+  }
+  // Fallback to full file content
+  return content
+}
+
+/** Check if node text contains prompt delimiters */
+export function hasDelimiters(text: string): boolean {
+  return /```|<user>|<\/user>|<human>|---+|\[USER\]|\{\{user\}\}|###\s*User|INPUT:|OUTPUT:/i.test(text)
+}
+
+/** Check if content filtering is present nearby */
+export function hasContentFiltering(bodyText: string): boolean {
+  return /filterContent|sanitizeContent|cleanContent|contentModeration|moderateContent|stripInstructions|escapePrompt|sanitizePrompt|validateInput/i.test(bodyText)
+}
+
+/** Check for jailbreak filtering */
+export function hasJailbreakFiltering(bodyText: string): boolean {
+  return /filterJailbreak|detectJailbreak|jailbreakFilter|sanitizePrompt|blockInjection|moderationApi|contentModeration|guardRails|guardrail|promptGuard|inputGuard/i.test(bodyText)
+}
+
+/** Check for sandbox environment */
+export function hasSandbox(bodyText: string): boolean {
+  return /vm2|isolated-vm|safeeval|safe-eval|sandbox|runInNewContext.*timeout|quickjs|webworker|iframe.*sandbox/i.test(bodyText)
+}
+
+/** Check for generic output validation */
+export function hasValidation(bodyText: string): boolean {
+  return /validate|sanitize|escape|\.filter\s*\([^)]*(?:allowed|safe|valid)|schema\.|\.parse\s*\(|allowlist|whitelist|blocklist|DOMPurify|xss|encodeURIComponent|textContent\s*=|ReactMarkdown|allowed(?:Columns|Tables|Hosts|Domains)/i.test(bodyText)
+}
+
+/** Check for URL validation */
+export function hasURLValidation(bodyText: string): boolean {
+  return /allowedHosts\.includes|safeDomains\.includes|allowedDomains\.includes|url\.origin\s*===|\.startsWith\s*\(\s*['"]\/|blockedHosts\.includes|privateIpPatterns|isValidUrl|validateUrl|isAllowedUrl/i.test(bodyText)
+}
+
+/** Check for DOM sanitization */
+export function hasDOMSanitization(bodyText: string): boolean {
+  return /DOMPurify\.sanitize|sanitizeHtml|escapeHtml|textContent\s*=|innerText\s*=|ReactMarkdown/i.test(bodyText)
+}
+
+/** Check for path validation */
+export function hasPathValidation(bodyText: string): boolean {
+  return /path\.resolve.*startsWith|resolved\.startsWith|allowedPaths|SAFE_BASE_DIR|baseDir|safeDir|path\.basename/i.test(bodyText)
+}
+
+/** Check for SQL parameterization */
+export function hasSQLParam(bodyText: string): boolean {
+  return /allowedColumns\.includes|schema\.parse|z\.enum|prisma\.\w+\.find|allowedColumns\.filter/i.test(bodyText)
+}
+
+/** Check for shell allowlist */
+export function hasShellAllowlist(bodyText: string): boolean {
+  return /allowedArgs\.includes|allowedCommands\.includes|execFile\s*\(\s*['"][^'"]+['"]|sanitized\s*=/i.test(bodyText)
+}
+
+/** Check for template safety */
+export function hasTemplateSafety(bodyText: string): boolean {
+  return /autoescape\s*[=:]\s*true|DOMPurify\.sanitize|escapeHtml|sanitizeHtml/i.test(bodyText) &&
+    !/autoescape\s*[=:]\s*false/i.test(bodyText)
+}
+
+/** Check for import allowlist */
+export function hasImportAllowlist(bodyText: string): boolean {
+  return /ALLOWED_PLUGINS|importMap|allowedModules/i.test(bodyText)
+}
+
+// ============================================================================
+// Context Window Ratio
+// ============================================================================
+
+/**
+ * Estimate the ratio of user-controlled content in a prompt value.
+ *
+ * - Single identifier → 1.0 (100% user-controlled)
+ * - Template literal → dynamicParts / totalLength
+ * - Static string → 0.0
+ */
+function estimateContextRatio(finding: TaintFinding, content: string): number | null {
+  // Walk from sink node to find the prompt value node
+  const sinkNode = finding.sink.node
+  // For system_prompt sinks, the dynamic content is typically the `content`/`system`/`prompt` property value
+  // We use the sink expression text as a proxy
+  const sinkText = content.substring(sinkNode.startIndex, sinkNode.endIndex)
+
+  // If the sink expression directly contains just an identifier that matches our tainted var
+  if (sinkText.includes('`')) {
+    // Template literal — estimate static vs dynamic ratio
+    const templateParts = sinkText.match(/\$\{[^}]+\}/g)
+    if (templateParts) {
+      // Subtract 3 per interpolation (${ and }) to count only inner expression length
+      const dynamicLen = templateParts.reduce((sum, p) => sum + Math.max(0, p.length - 3), 0)
+      const totalLen = sinkText.length
+      if (totalLen > 0) {
+        return Math.min(1.0, dynamicLen / totalLen)
+      }
+    }
+  }
+
+  // Simple identifier passed directly → 100% controlled
+  return 1.0
+}
+
+// ============================================================================
+// Prompt Injection Risk Assessment
+// ============================================================================
+
+/**
+ * Assess risk for taint findings where user input flows to a prompt sink.
+ */
+export function assessPromptInjectionRisk(finding: TaintFinding, content: string): LLMRiskAssessment {
+  const riskFactors: string[] = []
+  const mitigations: string[] = []
+
+  // 1. Base severity by sink position
+  const isSystemPrompt = finding.sink.sinkType === 'system_prompt'
+  let severity: VulnerabilitySeverity = isSystemPrompt ? 'critical' : 'high'
+
+  if (isSystemPrompt) {
+    riskFactors.push('User input flows to system prompt')
+  } else {
+    riskFactors.push('User input flows to prompt construction')
+  }
+
+  // 2. Source type context
+  const sourceType = finding.source.sourceType
+  let injectionType = 'direct prompt injection'
+  if (sourceType === 'rag_retrieval') {
+    injectionType = 'indirect injection via RAG retrieval'
+    riskFactors.push('External content from RAG pipeline')
+  } else if (sourceType === 'tool_output') {
+    injectionType = 'indirect injection via tool output'
+    riskFactors.push('Content from tool execution result')
+  } else if (sourceType === 'conversation_history') {
+    injectionType = 'injection via conversation history'
+    riskFactors.push('Content from conversation history')
+    // Chat history is typically previous messages being re-assembled — lower risk
+    severity = reduceSeverity(severity, 1)
+    mitigations.push('Conversation history source (serialization pattern)')
+  } else if (sourceType === 'database_result') {
+    injectionType = 'indirect injection via database content'
+    riskFactors.push('Content from database query result')
+    // Check if sink expression matches message deserialization patterns
+    const sinkExpr = finding.sink.expression
+    if (/AIMessage|HumanMessage|ChatMessage|messages\.append|messages\.push|ChatMessageHistory/.test(sinkExpr)) {
+      severity = reduceSeverity(severity, 1)
+      mitigations.push('Message deserialization pattern detected')
+    }
+  } else if (sourceType === 'external_api') {
+    injectionType = 'indirect injection via external API'
+    riskFactors.push('Content from external API response')
+  } else {
+    riskFactors.push(`Direct user input (${sourceType.replace(/_/g, ' ')})`)
+  }
+
+  // 3. Context window ratio
+  const contextRatio = estimateContextRatio(finding, content)
+  if (contextRatio !== null) {
+    if (contextRatio >= 0.9 && isSystemPrompt) {
+      riskFactors.push('System prompt almost entirely user-controlled')
+    } else if (contextRatio < 0.2) {
+      severity = reduceSeverity(severity, 1)
+      mitigations.push('Small interpolation in larger template')
+    }
+  }
+
+  // 4. Mitigation heuristics from enclosing function
+  const bodyText = getEnclosingBodyText(finding, content)
+
+  if (hasDelimiters(bodyText)) {
+    severity = reduceSeverity(severity, 1)
+    mitigations.push('Prompt delimiters detected')
+  }
+  if (hasContentFiltering(bodyText)) {
+    severity = reduceSeverity(severity, 1)
+    mitigations.push('Content filtering detected')
+  }
+  if (hasJailbreakFiltering(bodyText)) {
+    severity = reduceSeverity(severity, 1)
+    mitigations.push('Jailbreak filtering detected')
+  }
+
+  // Floor: prompt injection with partial mitigations should never drop below 'low'
+  if (severityIndex(severity) < severityIndex('low')) {
+    severity = 'low'
+  }
+
+  // Build note
+  const sourceDesc = finding.source.sourceType.replace(/_/g, ' ')
+  const sinkDesc = finding.sink.sinkType.replace(/_/g, ' ')
+  const pathLen = finding.path.length
+  let note = `${injectionType}: ${sourceDesc} at line ${finding.source.line} flows to ${sinkDesc} through ${pathLen} step${pathLen === 1 ? '' : 's'}`
+
+  if (mitigations.length > 0) {
+    note += ` (${mitigations.join('; ')})`
+  }
+
+  return {
+    adjustedSeverity: severity,
+    adjustedCategory: 'ai_prompt_injection',
+    riskFactors,
+    mitigations,
+    contextRatio,
+    note,
+  }
+}
+
+// ============================================================================
+// Execution Risk Assessment
+// ============================================================================
+
+/**
+ * Assess risk for taint findings where LLM output flows to execution sinks.
+ */
+export function assessExecutionRisk(finding: TaintFinding, content: string): LLMRiskAssessment {
+  const riskFactors: string[] = []
+  const mitigations: string[] = []
+
+  const sinkType = finding.sink.sinkType
+
+  // 1. Base severity by sink type
+  let severity: VulnerabilitySeverity
+  switch (sinkType) {
+    case 'eval':
+    case 'exec':
+    case 'command_exec':
+    case 'sql_query':
+    case 'nosql_query':
+    case 'http_request':
+    case 'file_write':
+    case 'path_access':
+    case 'dynamic_import':
+      severity = 'critical'
+      break
+    case 'inner_html':
+    case 'template_render':
+    case 'redirect':
+      severity = 'high'
+      break
+    case 'regex_constructor':
+      severity = 'medium'
+      break
+    case 'response_body':
+      severity = 'medium'
+      break
+    default:
+      severity = 'high'
+  }
+
+  riskFactors.push(`LLM output flows to ${sinkType.replace(/_/g, ' ')} sink`)
+
+  // 2. Source type context
+  const sourceType = finding.source.sourceType
+  if (sourceType === 'llm_output') {
+    riskFactors.push('Direct LLM API response output')
+  } else if (sourceType === 'tool_output') {
+    riskFactors.push('Tool execution result (may contain LLM-influenced data)')
+  } else if (sourceType === 'rag_retrieval') {
+    riskFactors.push('RAG retrieval result')
+  }
+
+  // 3. Mitigation heuristics from enclosing function
+  const bodyText = getEnclosingBodyText(finding, content)
+
+  // Sandbox — strong mitigation
+  if (hasSandbox(bodyText)) {
+    severity = reduceSeverity(severity, 2)
+    mitigations.push('Sandbox detected')
+  }
+
+  // Generic validation
+  if (hasValidation(bodyText)) {
+    severity = reduceSeverity(severity, 1)
+    mitigations.push('Validation detected')
+  }
+
+  // Sink-specific mitigations
+  switch (sinkType) {
+    case 'http_request':
+    case 'redirect':
+      if (hasURLValidation(bodyText)) {
+        severity = 'info'
+        mitigations.push('URL validation detected')
+      }
+      break
+    case 'inner_html':
+      if (hasDOMSanitization(bodyText)) {
+        severity = 'info'
+        mitigations.push('DOM sanitization detected')
+      }
+      break
+    case 'path_access':
+    case 'file_write':
+      if (hasPathValidation(bodyText)) {
+        severity = 'info'
+        mitigations.push('Path validation detected')
+      }
+      break
+    case 'sql_query':
+    case 'nosql_query':
+      if (hasSQLParam(bodyText)) {
+        severity = 'info'
+        mitigations.push('SQL parameterization detected')
+      }
+      break
+    case 'command_exec':
+      if (hasShellAllowlist(bodyText)) {
+        severity = reduceSeverity(severity, 1)
+        mitigations.push('Shell allowlist detected')
+      }
+      break
+    case 'template_render':
+      if (hasTemplateSafety(bodyText)) {
+        severity = 'info'
+        mitigations.push('Template safety detected')
+      }
+      break
+    case 'dynamic_import':
+      if (hasImportAllowlist(bodyText)) {
+        severity = reduceSeverity(severity, 1)
+        mitigations.push('Import allowlist detected')
+      }
+      break
+    case 'response_body': {
+      // AI SDK streaming responses are intentional LLM output delivery, not XSS vectors
+      const streamingPatterns = /toUIMessageStreamResponse|toDataStreamResponse|toTextStreamResponse|StreamingTextResponse|toAIStream|pipeDataStreamToResponse|streamText|streamObject/i
+      if (streamingPatterns.test(bodyText)) {
+        severity = 'info'
+        mitigations.push('AI SDK streaming response pattern')
+      }
+      // .json() response methods return structured JSON, not HTML
+      if (/\.json\s*\(/.test(bodyText)) {
+        severity = 'info'
+        mitigations.push('JSON response method')
+      }
+      break
+    }
+  }
+
+  // Build note
+  const sourceDesc = finding.source.sourceType.replace(/_/g, ' ')
+  const sinkDesc = finding.sink.sinkType.replace(/_/g, ' ')
+  const pathLen = finding.path.length
+  let note = `LLM output (${sourceDesc}) flows to ${sinkDesc} through ${pathLen} step${pathLen === 1 ? '' : 's'}`
+
+  if (mitigations.length > 0) {
+    note += ` (${mitigations.join('; ')})`
+  }
+
+  return {
+    adjustedSeverity: severity,
+    adjustedCategory: 'ai_unsafe_execution',
+    riskFactors,
+    mitigations,
+    contextRatio: null,
+    note,
+  }
+}

package/src/taint/propagation-types.ts

@@ -0,0 +1,188 @@
+/**
+ * Taint Propagation Types
+ *
+ * Data model for the taint propagation engine (Phase 2, Part 3).
+ * Extended in Phase 3 with cross-file call entry/return step types.
+ * Used by propagation.ts and taint-analyzer.ts.
+ */
+
+import type { TaintKind, TaintSource, TaintSink } from './types'
+import type { CrossFileIndex } from './cross-file-index'
+import type { ParsedAST } from '../parse/ast'
+import type { ProjectAnalysisCache } from './file-analysis-cache'
+
+// ============================================================================
+// Taint State
+// ============================================================================
+
+/** Field key: field name, or '*' for whole-object (unresolved field) taint. */
+export type FieldKey = string
+export const WHOLE_OBJECT: FieldKey = '*'
+
+/**
+ * Per-node taint state: variable name → field map → active taint kinds.
+ * The '*' key represents whole-object (unresolved field) taint.
+ */
+export type TaintState = Map<string, Map<FieldKey, Set<TaintKind>>>
+
+// ============================================================================
+// TaintState Accessors
+// ============================================================================
+
+/**
+ * Get effective taint for a variable (union of '*' and all fields).
+ *
+ * Phase 8 optimization: when only the WHOLE_OBJECT ('*') field exists (common case ~80%),
+ * returns the existing Set directly to avoid allocation. Callers that mutate the result
+ * MUST clone first (see augmented assignment and seed re-injection in propagation.ts).
+ */
+export function getTaint(state: TaintState, varName: string): Set<TaintKind> | undefined {
+  const fieldMap = state.get(varName)
+  if (!fieldMap) return undefined
+  // Fast path: single '*' field = return directly (no allocation)
+  if (fieldMap.size === 1) {
+    const onlyEntry = fieldMap.get(WHOLE_OBJECT)
+    if (onlyEntry && onlyEntry.size > 0) return onlyEntry
+  }
+  // Slow path: union of all field sets
+  const result = new Set<TaintKind>()
+  for (const kinds of fieldMap.values()) {
+    for (const k of kinds) result.add(k)
+  }
+  return result.size > 0 ? result : undefined
+}
+
+/** Get taint for a specific field (field-specific ∪ '*' fallback). */
+export function getFieldTaint(state: TaintState, varName: string, field: FieldKey): Set<TaintKind> | undefined {
+  const fieldMap = state.get(varName)
+  if (!fieldMap) return undefined
+  const result = new Set<TaintKind>()
+  // Field-specific taint
+  const fieldKinds = fieldMap.get(field)
+  if (fieldKinds) for (const k of fieldKinds) result.add(k)
+  // Whole-object fallback
+  if (field !== WHOLE_OBJECT) {
+    const wholeKinds = fieldMap.get(WHOLE_OBJECT)
+    if (wholeKinds) for (const k of wholeKinds) result.add(k)
+  }
+  return result.size > 0 ? result : undefined
+}
+
+/** Set whole-object taint (sets '*' key, clears field-specific entries). */
+export function setTaint(state: TaintState, varName: string, kinds: Set<TaintKind>): void {
+  const fieldMap = new Map<FieldKey, Set<TaintKind>>()
+  fieldMap.set(WHOLE_OBJECT, kinds)
+  state.set(varName, fieldMap)
+}
+
+/** Set taint for a specific field only. */
+export function setFieldTaint(state: TaintState, varName: string, field: FieldKey, kinds: Set<TaintKind>): void {
+  let fieldMap = state.get(varName)
+  if (!fieldMap) {
+    fieldMap = new Map<FieldKey, Set<TaintKind>>()
+    state.set(varName, fieldMap)
+  }
+  fieldMap.set(field, kinds)
+}
+
+/** Delete all taint for a variable. */
+export function deleteTaint(state: TaintState, varName: string): void {
+  state.delete(varName)
+}
+
+/** Check if a variable has any taint. */
+export function hasTaint(state: TaintState, varName: string): boolean {
+  const fieldMap = state.get(varName)
+  if (!fieldMap) return false
+  for (const kinds of fieldMap.values()) {
+    if (kinds.size > 0) return true
+  }
+  return false
+}
+
+// ============================================================================
+// Path Recording
+// ============================================================================
+
+/** One step in a taint propagation path. */
+export interface TaintStep {
+  nodeId: number
+  line: number
+  variable: string
+  taintKinds: ReadonlySet<TaintKind>
+  description: string
+  stepType: 'source' | 'propagation' | 'sanitizer' | 'sink'
+           | 'call_entry' | 'call_return'
+  /** When step is in a different file (cross-file analysis). */
+  filePath?: string
+  /** When entering/exiting a function (cross-file analysis). */
+  functionName?: string
+}
+
+// ============================================================================
+// Cross-File Call Resolution Context
+// ============================================================================
+
+/**
+ * Context for resolving function calls across file boundaries.
+ * Passed through the propagation engine to enable inter-procedural analysis.
+ */
+export interface CallResolutionContext {
+  crossFileIndex: CrossFileIndex
+  allASTs: Map<string, ParsedAST>
+  /** Prevent infinite recursion: set of "${filePath}:${functionName}" being analyzed. */
+  callStack: Set<string>
+  /** Max call depth to follow (default: 5). */
+  maxDepth: number
+  /** Cache: "${filePath}:${functionName}:${taintKindsSorted}" → return taint + steps. */
+  resultCache: Map<string, CalleeResult | null>
+  /** Pre-built per-file analysis cache (CFGs, sources, sinks, sanitizers). Phase 8. */
+  analysisCache?: ProjectAnalysisCache
+  /** Pre-built function taint summaries for summary-based composition. Phase 8. */
+  summaryCache?: SummaryCache
+}
+
+/** Sentinel value indicating a summary is currently being built (recursion guard). */
+export const BUILDING_SENTINEL = Symbol('building')
+
+export type SummaryCache = Map<string, FunctionTaintSummary | typeof BUILDING_SENTINEL | null>
+
+/** Summary of a function's taint behavior: which param taint kinds survive to return/sinks. */
+export interface FunctionTaintSummary {
+  functionName: string
+  filePath: string
+  params: string[]
+  /** Per param index: which taint kinds survive through sanitizers to return. */
+  paramReturnKinds: Map<number, Set<TaintKind>>
+  /** Per param index: which sinks are reachable with which taint kinds. */
+  paramSinkEntries: Map<number, ParamSinkEntry[]>
+}
+
+export interface ParamSinkEntry {
+  sinkLine: number
+  sinkExpression: string
+  sinkType: string
+  reachableKinds: Set<TaintKind>
+}
+
+export interface CalleeResult {
+  returnTaint: Set<TaintKind>
+  steps: TaintStep[]
+  /** Findings discovered inside the callee (sink reached within callee). */
+  calleeFindings: TaintFinding[]
+}
+
+// ============================================================================
+// Findings
+// ============================================================================
+
+/** A confirmed taint finding: source → sink with full path. */
+export interface TaintFinding {
+  source: TaintSource
+  sink: TaintSink
+  path: TaintStep[]
+  /** Intersection of source taint kinds and sink vulnerable-to kinds. */
+  matchingKinds: Set<TaintKind>
+  functionName: string
+  filePath: string
+}