@oculum/scanner 1.0.11 → 1.0.13

package/src/model/sanitiser-detection.ts

@@ -0,0 +1,268 @@
+/**
+ * Sanitiser Detection — Identifies sanitisation functions in code.
+ *
+ * Two-pass approach:
+ * 1. Scan imports to know which sanitisation libraries are available
+ * 2. Scan for sanitiser calls (context-sensitive)
+ */
+
+import type { SanitiserInfo, SanitiserTarget } from './taint-types'
+
+// ============================================================================
+// Known Sanitiser Libraries
+// ============================================================================
+
+interface KnownSanitiser {
+  /** Import patterns that indicate the library is available */
+  importPatterns: RegExp[]
+  /** Function call patterns and what they sanitise */
+  callPatterns: { pattern: RegExp; sanitises: SanitiserTarget; name: string }[]
+  /** Library identifier */
+  library: string
+}
+
+const KNOWN_SANITISERS: KnownSanitiser[] = [
+  {
+    library: 'dompurify',
+    importPatterns: [/\bDOMPurify\b/, /\bdompurify\b/, /\bisomorphic-dompurify\b/],
+    callPatterns: [
+      { pattern: /DOMPurify\.sanitize\s*\(/, sanitises: 'html', name: 'DOMPurify.sanitize' },
+      { pattern: /\bsanitize\s*\(/, sanitises: 'html', name: 'sanitize' },
+    ],
+  },
+  {
+    library: 'validator',
+    importPatterns: [/\bvalidator\b/],
+    callPatterns: [
+      { pattern: /validator\.escape\s*\(/, sanitises: 'html', name: 'validator.escape' },
+    ],
+  },
+  {
+    library: 'escape-html',
+    importPatterns: [/\bescape-html\b/, /\bescapeHtml\b/],
+    callPatterns: [
+      { pattern: /\bescapeHtml\s*\(/, sanitises: 'html', name: 'escapeHtml' },
+      { pattern: /\bescapeHTML\s*\(/, sanitises: 'html', name: 'escapeHTML' },
+    ],
+  },
+  {
+    library: 'xss',
+    importPatterns: [/\bxss\b/],
+    callPatterns: [
+      { pattern: /\bxss\s*\(/, sanitises: 'html', name: 'xss' },
+      { pattern: /\bfilterXSS\s*\(/, sanitises: 'html', name: 'filterXSS' },
+    ],
+  },
+  {
+    library: 'zod',
+    importPatterns: [/\bzod\b/, /\bfrom\s+['"]zod['"]/],
+    callPatterns: [
+      { pattern: /\.parse\s*\(/, sanitises: 'all', name: 'zod.parse' },
+      { pattern: /\.safeParse\s*\(/, sanitises: 'all', name: 'zod.safeParse' },
+    ],
+  },
+  {
+    library: 'joi',
+    importPatterns: [/\bjoi\b/, /\bfrom\s+['"]joi['"]/],
+    callPatterns: [
+      { pattern: /\.validate\s*\(/, sanitises: 'all', name: 'joi.validate' },
+    ],
+  },
+  {
+    library: 'yup',
+    importPatterns: [/\byup\b/, /\bfrom\s+['"]yup['"]/],
+    callPatterns: [
+      { pattern: /\.validate\s*\(/, sanitises: 'all', name: 'yup.validate' },
+      { pattern: /\.validateSync\s*\(/, sanitises: 'all', name: 'yup.validateSync' },
+    ],
+  },
+  {
+    library: 'shell-escape',
+    importPatterns: [/\bshell-escape\b/, /\bshellescape\b/],
+    callPatterns: [
+      { pattern: /\bshellescape\s*\(/, sanitises: 'command', name: 'shellescape' },
+    ],
+  },
+]
+
+// ============================================================================
+// Import-Independent Sanitisers (always available)
+// ============================================================================
+
+interface UniversalSanitiser {
+  pattern: RegExp
+  sanitises: SanitiserTarget
+  name: string
+  detection: 'known_library' | 'name_heuristic'
+}
+
+const UNIVERSAL_SANITISERS: UniversalSanitiser[] = [
+  // Type coercion (always sanitises)
+  { pattern: /\bNumber\s*\(/, sanitises: 'all', name: 'Number', detection: 'known_library' },
+  { pattern: /\bparseInt\s*\(/, sanitises: 'all', name: 'parseInt', detection: 'known_library' },
+  { pattern: /\bparseFloat\s*\(/, sanitises: 'all', name: 'parseFloat', detection: 'known_library' },
+  { pattern: /\bBoolean\s*\(/, sanitises: 'all', name: 'Boolean', detection: 'known_library' },
+  { pattern: /\bString\s*\(/, sanitises: 'all', name: 'String', detection: 'known_library' },
+
+  // Path sanitisation
+  { pattern: /\bpath\.normalize\s*\(/, sanitises: 'path', name: 'path.normalize', detection: 'known_library' },
+  { pattern: /\bpath\.basename\s*\(/, sanitises: 'path', name: 'path.basename', detection: 'known_library' },
+
+  // Python
+  { pattern: /\bshlex\.quote\s*\(/, sanitises: 'command', name: 'shlex.quote', detection: 'known_library' },
+  { pattern: /\bhtml\.escape\s*\(/, sanitises: 'html', name: 'html.escape', detection: 'known_library' },
+  { pattern: /\bmarkup_safe\.escape\s*\(/, sanitises: 'html', name: 'markupsafe.escape', detection: 'known_library' },
+
+  // Name heuristic — functions with "sanitize", "escape", "encode" in name
+  { pattern: /\bsanitize\w*\s*\(/, sanitises: 'all', name: 'sanitize*', detection: 'name_heuristic' },
+  { pattern: /\bescape\w*\s*\(/, sanitises: 'html', name: 'escape*', detection: 'name_heuristic' },
+  { pattern: /\bencode(?:URI|URIComponent)\s*\(/, sanitises: 'url', name: 'encodeURI*', detection: 'known_library' },
+]
+
+// ============================================================================
+// Parameterised Query Detection
+// ============================================================================
+
+const PARAMETERISED_QUERY_PATTERNS: RegExp[] = [
+  // Placeholder-based: .query('SELECT ... WHERE id = ?', [value])
+  /\.query\s*\(\s*['"`][^'"`]*\?\s*[^'"`]*['"`]\s*,\s*\[/,
+  // $1-style: .query('SELECT ... WHERE id = $1', [value])
+  /\.query\s*\(\s*['"`][^'"`]*\$\d+\s*[^'"`]*['"`]\s*,\s*\[/,
+  // Sequelize replacements: .query('...', { replacements: ... })
+  /\.query\s*\([^)]*\breplacements\s*:/,
+  // Knex parameterised: .where('id', value) or .where({ id: value })
+  /\.where\s*\(\s*['"`]\w+['"`]\s*,/,
+  /\.where\s*\(\s*\{/,
+]
+
+// ============================================================================
+// Main Detection Functions
+// ============================================================================
+
+/**
+ * Detect sanitisation functions available in a file.
+ *
+ * Pass 1: Scan imports to determine which libraries are available.
+ * Pass 2: Find sanitiser call sites.
+ */
+export function detectSanitisers(content: string, _filePath: string): SanitiserInfo[] {
+  const lines = content.split('\n')
+  const sanitisers: SanitiserInfo[] = []
+  const seen = new Set<string>()
+
+  // Pass 1: Determine which libraries are imported (only check import/require lines)
+  const availableLibraries = new Set<string>()
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith('import') && !trimmed.includes('require(') && !trimmed.startsWith('from')) {
+      continue
+    }
+    for (const lib of KNOWN_SANITISERS) {
+      if (lib.importPatterns.some(p => p.test(line))) {
+        availableLibraries.add(lib.library)
+      }
+    }
+  }
+
+  // Pass 2: Find sanitiser calls
+  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 known library sanitisers (only if library is imported)
+    for (const lib of KNOWN_SANITISERS) {
+      if (!availableLibraries.has(lib.library)) continue
+
+      for (const cp of lib.callPatterns) {
+        if (cp.pattern.test(line)) {
+          const key = `${lineNumber}:${cp.name}`
+          if (seen.has(key)) continue
+          seen.add(key)
+
+          sanitisers.push({
+            name: cp.name,
+            line: lineNumber,
+            sanitises: cp.sanitises,
+            detection: 'known_library',
+            library: lib.library,
+          })
+        }
+      }
+    }
+
+    // Check universal sanitisers (always available)
+    for (const us of UNIVERSAL_SANITISERS) {
+      if (us.pattern.test(line)) {
+        const key = `${lineNumber}:${us.name}`
+        if (seen.has(key)) continue
+        seen.add(key)
+
+        sanitisers.push({
+          name: us.name,
+          line: lineNumber,
+          sanitises: us.sanitises,
+          detection: us.detection,
+        })
+      }
+    }
+
+    // Check parameterised queries
+    for (const pqp of PARAMETERISED_QUERY_PATTERNS) {
+      if (pqp.test(line)) {
+        const key = `${lineNumber}:parameterised_query`
+        if (seen.has(key)) continue
+        seen.add(key)
+
+        sanitisers.push({
+          name: 'parameterised_query',
+          line: lineNumber,
+          sanitises: 'sql',
+          detection: 'known_library',
+        })
+      }
+    }
+  }
+
+  return sanitisers
+}
+
+/**
+ * Check if a specific line contains a sanitiser call.
+ *
+ * Used during taint propagation to determine if a variable is sanitised
+ * at a particular assignment.
+ */
+export function isSanitiserCall(
+  line: string,
+  sanitisers: SanitiserInfo[]
+): { sanitised: boolean; method?: string; target?: SanitiserTarget } {
+  // Check against known sanitisers found in the file
+  for (const s of sanitisers) {
+    // Check both by exact name match and by pattern
+    if (line.includes(s.name.replace('*', ''))) {
+      return { sanitised: true, method: s.name, target: s.sanitises }
+    }
+  }
+
+  // Check universal sanitisers directly
+  for (const us of UNIVERSAL_SANITISERS) {
+    if (us.pattern.test(line)) {
+      return { sanitised: true, method: us.name, target: us.sanitises }
+    }
+  }
+
+  // Check parameterised queries
+  for (const pqp of PARAMETERISED_QUERY_PATTERNS) {
+    if (pqp.test(line)) {
+      return { sanitised: true, method: 'parameterised_query', target: 'sql' }
+    }
+  }
+
+  return { sanitised: false }
+}

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, '\\$&')
+}