@oculum/scanner 1.0.12 → 1.0.13

package/src/model/sink-matcher.ts

@@ -0,0 +1,178 @@
+/**
+ * Sink Matcher — Matches tainted variables to dangerous sinks.
+ *
+ * Scans each line for known dangerous sink patterns, then checks if
+ * any tainted variable name appears on that line. Builds complete
+ * taint paths from source → propagation chain → sink.
+ */
+
+import type { TaintedVariable, TaintPath, TaintSink, SinkType } from './taint-types'
+import type { SanitiserInfo } from './taint-types'
+import { isSanitiserCall } from './sanitiser-detection'
+import { SINK_PATTERNS, escapeRegex } from './sink-patterns'
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Check if a tainted variable appears on a line (using word boundaries).
+ */
+function taintedVarAppearsOnLine(
+  line: string,
+  taintedVars: TaintedVariable[]
+): TaintedVariable | null {
+  for (const tv of taintedVars) {
+    const regex = new RegExp(`\\b${escapeRegex(tv.name)}\\b`)
+    if (regex.test(line)) {
+      return tv
+    }
+  }
+  return null
+}
+
+/**
+ * Build a taint chain from a tainted variable back to its source.
+ * Follows the propagation chain through assignments.
+ */
+function buildChain(
+  target: TaintedVariable,
+  allVars: TaintedVariable[]
+): TaintedVariable[] {
+  const chain: TaintedVariable[] = [target]
+  let current = target
+  const visited = new Set<string>()
+  visited.add(current.name)
+
+  // Walk back through the propagation chain
+  while (current.source) {
+    const sourceVar = allVars.find(v =>
+      v.name === current.source.variable &&
+      v.taintedAt < current.taintedAt &&
+      !visited.has(v.name)
+    )
+    if (!sourceVar) break
+    visited.add(sourceVar.name)
+    chain.unshift(sourceVar)
+    current = sourceVar
+  }
+
+  return chain
+}
+
+/**
+ * Compute confidence for a taint path based on source confidence and chain length.
+ */
+function computePathConfidence(
+  chain: TaintedVariable[],
+  sourceConfidence: 'high' | 'medium' | 'low'
+): 'high' | 'medium' | 'low' {
+  const chainLen = chain.length
+
+  if (sourceConfidence === 'high' && chainLen <= 3) return 'high'
+  if (sourceConfidence === 'low' || chainLen > 5) return 'low'
+  return 'medium'
+}
+
+/**
+ * Check if the line is a parameterised query (where the tainted var
+ * is in the parameter array, not interpolated into the query string).
+ */
+function isParameterisedQueryUsage(line: string, varName: string): boolean {
+  // Pattern: .query('...', [varName]) — var is in the parameter array
+  const paramArrayPattern = new RegExp(
+    `\\.query\\s*\\([^,]+,\\s*\\[[^\\]]*\\b${escapeRegex(varName)}\\b[^\\]]*\\]`
+  )
+  if (paramArrayPattern.test(line)) return true
+
+  // Pattern: .where('column', varName) — Knex parameterised
+  const knexWherePattern = new RegExp(
+    `\\.where\\s*\\(\\s*['"][^'"]+['"]\\s*,\\s*\\b${escapeRegex(varName)}\\b`
+  )
+  if (knexWherePattern.test(line)) return true
+
+  return false
+}
+
+// ============================================================================
+// Main Matching Function
+// ============================================================================
+
+/**
+ * Match tainted variables to dangerous sinks and build taint paths.
+ *
+ * For each line that matches a sink pattern, checks if any tainted variable
+ * appears on that line. Builds a complete TaintPath with source, chain, and sink.
+ */
+export function matchSinks(
+  content: string,
+  _filePath: string,
+  taintedVariables: TaintedVariable[],
+  sanitisers: SanitiserInfo[]
+): TaintPath[] {
+  if (taintedVariables.length === 0) return []
+
+  const lines = content.split('\n')
+  const taintPaths: TaintPath[] = []
+  const seen = new Set<string>()
+
+  // Get only unsanitised tainted variables (and all for chain building)
+  const activeTaintedVars = taintedVariables.filter(tv => !tv.sanitised)
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const lineNumber = i + 1
+    const trimmed = line.trim()
+
+    // Skip comments
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) {
+      continue
+    }
+
+    // Check each sink pattern
+    for (const sp of SINK_PATTERNS) {
+      if (!sp.pattern.test(line)) continue
+
+      // Check if any tainted variable appears on this line
+      const taintedVar = taintedVarAppearsOnLine(line, activeTaintedVars)
+      if (!taintedVar) continue
+
+      // Dedup: one taint path per source-sink-line combination
+      const key = `${taintedVar.source.variable}:${sp.sinkType}:${lineNumber}`
+      if (seen.has(key)) continue
+      seen.add(key)
+
+      // Build the sink
+      const sink: TaintSink = {
+        line: lineNumber,
+        expression: trimmed,
+        sinkType: sp.sinkType,
+      }
+
+      // Build the chain from source to this variable
+      const chain = buildChain(taintedVar, taintedVariables)
+
+      // Check if sanitised at the sink line itself
+      const sinkSanitResult = isSanitiserCall(line, sanitisers)
+      const isSanitised = sinkSanitResult.sanitised || taintedVar.sanitised
+
+      // Special case: parameterised SQL queries
+      const isParamQuery = sp.sinkType === 'sql_query' && isParameterisedQueryUsage(line, taintedVar.name)
+
+      const sanitised = isSanitised || isParamQuery
+
+      // Compute confidence
+      const confidence = computePathConfidence(chain, taintedVar.source.confidence)
+
+      taintPaths.push({
+        source: taintedVar.source,
+        chain,
+        sink,
+        sanitised,
+        confidence,
+      })
+    }
+  }
+
+  return taintPaths
+}

package/src/model/sink-patterns.ts

@@ -0,0 +1,109 @@
+/**
+ * Shared Sink Patterns — Canonical list of dangerous sink patterns.
+ *
+ * Single source of truth for sink detection patterns used by:
+ * - sink-matcher.ts (intra-file taint path matching)
+ * - function-classifier.ts (exported function profiling)
+ * - cross-file-taint.ts (cross-file taint analysis)
+ */
+
+import type { SinkType } from './taint-types'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface SinkPattern {
+  pattern: RegExp
+  sinkType: SinkType
+}
+
+// ============================================================================
+// Canonical Sink Patterns
+// ============================================================================
+
+export const SINK_PATTERNS: SinkPattern[] = [
+  // SQL injection
+  { pattern: /\.query\s*\(/, sinkType: 'sql_query' },
+  { pattern: /\.raw\s*\(/, sinkType: 'sql_query' },
+  { pattern: /\.execute\s*\(/, sinkType: 'sql_query' },
+  { pattern: /\bsequelize\.query\s*\(/, sinkType: 'sql_query' },
+  { pattern: /\bknex\.raw\s*\(/, sinkType: 'sql_query' },
+  { pattern: /\bcursor\.execute\s*\(/, sinkType: 'sql_query' },
+
+  // Code execution
+  { pattern: /\beval\s*\(/, sinkType: 'eval' },
+  { pattern: /new\s+Function\s*\(/, sinkType: 'eval' },
+
+  // Command execution (Node.js)
+  { pattern: /\bexec\s*\(/, sinkType: 'exec' },
+  { pattern: /\bexecSync\s*\(/, sinkType: 'exec' },
+  { pattern: /\bspawn\s*\(/, sinkType: 'exec' },
+  { pattern: /\bchild_process\./, sinkType: 'exec' },
+
+  // Command execution (Python)
+  { pattern: /\bsubprocess\.run\s*\(/, sinkType: 'command_exec' },
+  { pattern: /\bsubprocess\.call\s*\(/, sinkType: 'command_exec' },
+  { pattern: /\bsubprocess\.Popen\s*\(/, sinkType: 'command_exec' },
+  { pattern: /\bos\.system\s*\(/, sinkType: 'command_exec' },
+  { pattern: /\bos\.popen\s*\(/, sinkType: 'command_exec' },
+
+  // XSS / DOM injection
+  { pattern: /\.innerHTML\s*=/, sinkType: 'inner_html' },
+  { pattern: /\bdangerouslySetInnerHTML\b/, sinkType: 'inner_html' },
+  { pattern: /\bdocument\.write\s*\(/, sinkType: 'inner_html' },
+
+  // HTTP requests (SSRF)
+  { pattern: /\bfetch\s*\(/, sinkType: 'http_request' },
+  { pattern: /\baxios\.\w+\s*\(/, sinkType: 'http_request' },
+  { pattern: /\bgot\s*\(/, sinkType: 'http_request' },
+  { pattern: /\bhttp\.request\s*\(/, sinkType: 'http_request' },
+  { pattern: /\bhttps\.request\s*\(/, sinkType: 'http_request' },
+  { pattern: /\brequests\.\w+\s*\(/, sinkType: 'http_request' },
+
+  // Redirects
+  { pattern: /\bres\.redirect\s*\(/, sinkType: 'redirect' },
+  { pattern: /\bResponse\.redirect\s*\(/, sinkType: 'redirect' },
+  { pattern: /\blocation\.href\s*=/, sinkType: 'redirect' },
+  { pattern: /\bwindow\.location\s*=/, sinkType: 'redirect' },
+
+  // File system
+  { pattern: /\bfs\.writeFile\b/, sinkType: 'file_write' },
+  { pattern: /\bfs\.writeFileSync\b/, sinkType: 'file_write' },
+  { pattern: /\bcreateWriteStream\s*\(/, sinkType: 'file_write' },
+  { pattern: /\bfs\.readFile\b/, sinkType: 'path_access' },
+  { pattern: /\bfs\.readFileSync\b/, sinkType: 'path_access' },
+  { pattern: /\bpath\.join\s*\(/, sinkType: 'path_access' },
+  { pattern: /\bpath\.resolve\s*\(/, sinkType: 'path_access' },
+
+  // Template rendering
+  { pattern: /\bpug\.compile\s*\(/, sinkType: 'template_render' },
+  { pattern: /\bejs\.render\s*\(/, sinkType: 'template_render' },
+  { pattern: /\bhandlebars\.compile\s*\(/, sinkType: 'template_render' },
+
+  // Regex construction (ReDoS)
+  { pattern: /new\s+RegExp\s*\(/, sinkType: 'regex_constructor' },
+  { pattern: /\bre\.compile\s*\(/, sinkType: 'regex_constructor' },
+
+  // Dynamic imports
+  { pattern: /\bimport\s*\(/, sinkType: 'dynamic_import' },
+  { pattern: /\brequire\s*\(/, sinkType: 'dynamic_import' },
+
+  // Deserialization
+  { pattern: /\bJSON\.parse\s*\(/, sinkType: 'deserialization' },
+  { pattern: /\bpickle\.load\s*\(/, sinkType: 'deserialization' },
+  { pattern: /\bpickle\.loads\s*\(/, sinkType: 'deserialization' },
+  { pattern: /\byaml\.load\s*\(/, sinkType: 'deserialization' },
+  { pattern: /\byaml\.unsafe_load\s*\(/, sinkType: 'deserialization' },
+]
+
+// ============================================================================
+// Shared Utilities
+// ============================================================================
+
+/**
+ * Escape special regex characters in a string for use in RegExp constructors.
+ */
+export function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}

package/src/model/source-discovery.ts

@@ -0,0 +1,209 @@
+/**
+ * Source Discovery — Identifies user-input sources in code files.
+ *
+ * Scans for framework-specific patterns (Express, Next.js, Flask, Django, etc.)
+ * that represent user-controllable input entering the application.
+ */
+
+import type { UserInputSource, UserInputSourceType } from './taint-types'
+
+// ============================================================================
+// Framework Source Patterns
+// ============================================================================
+
+interface SourcePattern {
+  /** Regex to match the source expression in code */
+  pattern: RegExp
+  /** What type of user input this represents */
+  sourceType: UserInputSourceType
+  /** Which framework this pattern belongs to */
+  framework: string
+  /** Confidence in this being actual user input */
+  confidence: 'high' | 'medium' | 'low'
+}
+
+const SOURCE_PATTERNS: SourcePattern[] = [
+  // --- Express/Node.js ---
+  { pattern: /\breq\.body\b/, sourceType: 'http_body', framework: 'express', confidence: 'high' },
+  { pattern: /\breq\.query\b/, sourceType: 'http_query', framework: 'express', confidence: 'high' },
+  { pattern: /\breq\.params\b/, sourceType: 'http_params', framework: 'express', confidence: 'high' },
+  { pattern: /\breq\.headers\b/, sourceType: 'http_headers', framework: 'express', confidence: 'high' },
+  { pattern: /\breq\.cookies\b/, sourceType: 'http_headers', framework: 'express', confidence: 'high' },
+
+  // --- Koa ---
+  { pattern: /\bctx\.request\.body\b/, sourceType: 'http_body', framework: 'koa', confidence: 'high' },
+  { pattern: /\bctx\.query\b/, sourceType: 'http_query', framework: 'koa', confidence: 'high' },
+
+  // --- Next.js App Router ---
+  { pattern: /\bsearchParams\b/, sourceType: 'http_query', framework: 'nextjs', confidence: 'medium' },
+  { pattern: /\bformData\b/, sourceType: 'form_data', framework: 'nextjs', confidence: 'medium' },
+
+  // --- Browser APIs ---
+  { pattern: /\bdocument\.location\b/, sourceType: 'url_search_params', framework: 'browser', confidence: 'medium' },
+  { pattern: /\bwindow\.location\b/, sourceType: 'url_search_params', framework: 'browser', confidence: 'medium' },
+  { pattern: /\blocation\.search\b/, sourceType: 'url_search_params', framework: 'browser', confidence: 'medium' },
+  { pattern: /\blocation\.hash\b/, sourceType: 'url_search_params', framework: 'browser', confidence: 'medium' },
+  { pattern: /new\s+URLSearchParams\b/, sourceType: 'url_search_params', framework: 'browser', confidence: 'medium' },
+  { pattern: /\bdocument\.cookie\b/, sourceType: 'http_headers', framework: 'browser', confidence: 'medium' },
+  { pattern: /\bevent\.target\.value\b/, sourceType: 'form_data', framework: 'browser', confidence: 'medium' },
+
+  // --- WebSocket ---
+  { pattern: /\bws\.on\s*\(\s*['"]message['"]/, sourceType: 'websocket_message', framework: 'websocket', confidence: 'medium' },
+  { pattern: /\bsocket\.on\s*\(\s*['"]message['"]/, sourceType: 'websocket_message', framework: 'websocket', confidence: 'medium' },
+
+  // --- AWS Lambda ---
+  { pattern: /\bevent\.body\b/, sourceType: 'http_body', framework: 'aws-lambda', confidence: 'high' },
+  { pattern: /\bevent\.queryStringParameters\b/, sourceType: 'http_query', framework: 'aws-lambda', confidence: 'high' },
+
+  // --- Python Flask ---
+  { pattern: /\brequest\.args\b/, sourceType: 'http_query', framework: 'flask', confidence: 'high' },
+  { pattern: /\brequest\.form\b/, sourceType: 'form_data', framework: 'flask', confidence: 'high' },
+  { pattern: /\brequest\.json\b/, sourceType: 'http_body', framework: 'flask', confidence: 'high' },
+  { pattern: /\brequest\.data\b/, sourceType: 'http_body', framework: 'flask', confidence: 'high' },
+
+  // --- Python Django ---
+  { pattern: /\brequest\.GET\b/, sourceType: 'http_query', framework: 'django', confidence: 'high' },
+  { pattern: /\brequest\.POST\b/, sourceType: 'form_data', framework: 'django', confidence: 'high' },
+  { pattern: /\brequest\.body\b/, sourceType: 'http_body', framework: 'django', confidence: 'high' },
+
+  // --- CLI ---
+  { pattern: /\bprocess\.argv\b/, sourceType: 'cli_args', framework: 'node', confidence: 'low' },
+  { pattern: /\bsys\.argv\b/, sourceType: 'cli_args', framework: 'python', confidence: 'low' },
+  { pattern: /\binput\s*\(/, sourceType: 'cli_args', framework: 'python', confidence: 'low' },
+]
+
+// ============================================================================
+// Variable Extraction
+// ============================================================================
+
+/** Pattern for direct assignment: const/let/var NAME = ... */
+const DIRECT_ASSIGNMENT = /\b(?:const|let|var)\s+(\w+)\s*=\s*(.+)/
+
+/** Pattern for destructuring: const/let/var { A, B } = ... */
+const DESTRUCTURE_ASSIGNMENT = /\b(?:const|let|var)\s+\{\s*([^}]+)\}\s*=\s*(.+)/
+
+/** Pattern for array destructuring: const/let/var [ A, B ] = ... */
+const ARRAY_DESTRUCTURE = /\b(?:const|let|var)\s+\[\s*([^\]]+)\]\s*=\s*(.+)/
+
+/**
+ * Extract variable name(s) from an assignment line that contains a source expression.
+ */
+function extractVariables(line: string, sourceExpression: string): string[] {
+  const variables: string[] = []
+
+  // Try destructuring first: const { a, b } = req.body
+  const destructureMatch = line.match(DESTRUCTURE_ASSIGNMENT)
+  if (destructureMatch) {
+    const rhs = destructureMatch[2].trim()
+    if (rhs.includes(sourceExpression) || sourceMatchesRhs(rhs, sourceExpression)) {
+      const names = destructureMatch[1].split(',').map(n => {
+        // Handle renaming: `originalName: newName`
+        const parts = n.trim().split(':')
+        return (parts.length > 1 ? parts[1] : parts[0]).trim()
+      }).filter(n => n.length > 0 && n !== '...')
+      variables.push(...names)
+    }
+    return variables
+  }
+
+  // Try array destructuring: const [ a, b ] = ...
+  const arrayMatch = line.match(ARRAY_DESTRUCTURE)
+  if (arrayMatch) {
+    const rhs = arrayMatch[2].trim()
+    if (rhs.includes(sourceExpression) || sourceMatchesRhs(rhs, sourceExpression)) {
+      const names = arrayMatch[1].split(',').map(n => n.trim()).filter(n => n.length > 0 && n !== '...')
+      variables.push(...names)
+    }
+    return variables
+  }
+
+  // Try direct assignment: const name = req.body
+  const directMatch = line.match(DIRECT_ASSIGNMENT)
+  if (directMatch) {
+    const rhs = directMatch[2].trim()
+    if (rhs.includes(sourceExpression) || sourceMatchesRhs(rhs, sourceExpression)) {
+      variables.push(directMatch[1])
+    }
+  }
+
+  return variables
+}
+
+/**
+ * Check if a source pattern's expression is part of the RHS of an assignment.
+ */
+function sourceMatchesRhs(rhs: string, sourceExpression: string): boolean {
+  // Handle cases like `req.body.email` matching the `req.body` source
+  return rhs.includes(sourceExpression)
+}
+
+// ============================================================================
+// Main Discovery Function
+// ============================================================================
+
+/**
+ * Discover user-input sources in a file.
+ *
+ * Scans each line for framework-specific input patterns and extracts
+ * the variable names that receive user-controlled data.
+ */
+export function discoverSources(content: string, filePath: string): UserInputSource[] {
+  const lines = content.split('\n')
+  const sources: UserInputSource[] = []
+  const seen = new Set<string>()
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const lineNumber = i + 1
+
+    // Skip comments
+    const trimmed = line.trim()
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) {
+      continue
+    }
+
+    for (const sp of SOURCE_PATTERNS) {
+      const match = sp.pattern.exec(line)
+      if (!match) continue
+
+      const expression = match[0]
+
+      // Extract variables assigned from this source
+      const variables = extractVariables(line, expression)
+
+      if (variables.length > 0) {
+        for (const variable of variables) {
+          const key = `${lineNumber}:${variable}:${sp.sourceType}`
+          if (seen.has(key)) continue
+          seen.add(key)
+
+          sources.push({
+            line: lineNumber,
+            expression,
+            variable,
+            sourceType: sp.sourceType,
+            frameworkSource: sp.framework,
+            confidence: sp.confidence,
+          })
+        }
+      } else {
+        // Source found but no variable assignment (e.g., inline usage like `db.query(req.query.id)`)
+        // Still record it — the taint tracker and sink matcher can use the expression directly
+        const key = `${lineNumber}:${expression}:${sp.sourceType}`
+        if (seen.has(key)) continue
+        seen.add(key)
+
+        sources.push({
+          line: lineNumber,
+          expression,
+          variable: expression,
+          sourceType: sp.sourceType,
+          frameworkSource: sp.framework,
+          confidence: sp.confidence,
+        })
+      }
+    }
+  }
+
+  return sources
+}