@oculum/scanner 1.0.14 → 1.0.15

package/src/taint/def-use.ts

@@ -0,0 +1,556 @@
+/**
+ * Def-Use Extraction
+ *
+ * Given an AST statement node, extracts which variables are defined (written)
+ * and which are used (read). This feeds into CFGNode.defs and CFGNode.uses
+ * for taint propagation transfer functions.
+ *
+ * Conservative: if in doubt, a variable is "used". Over-approximation is safe
+ * for a security scanner (may produce more findings, never misses tainted flow).
+ */
+
+import type Parser from 'tree-sitter'
+import { walkAST } from '../parse/ast'
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export interface DefUseInfo {
+  defs: Set<string>
+  uses: Set<string>
+}
+
+/**
+ * Extract defs and uses from an AST statement node.
+ *
+ * A "def" is a variable that gets a new value written to it.
+ * A "use" is a variable whose current value is read.
+ *
+ * For `x = y + z`:  defs={x}, uses={y, z}
+ * For `const a = b`: defs={a}, uses={b}
+ * For `foo(x)`:      defs={}, uses={foo, x}
+ */
+export function computeDefUse(node: Parser.SyntaxNode): DefUseInfo {
+  const defs = new Set<string>()
+  const uses = new Set<string>()
+
+  extractFromNode(node, defs, uses, false)
+
+  // Remove defs from uses (if variable is both defined and used in same statement,
+  // the "use" of the old value matters for taint, so we keep both)
+  // Actually, for `x = x + 1`, x is both def AND use. Keep both sets as-is.
+
+  return { defs, uses }
+}
+
+// ============================================================================
+// Internal Extraction
+// ============================================================================
+
+/**
+ * Recursively extract defs and uses from a node.
+ * @param inLHS - true when we're inside the left-hand side of an assignment
+ */
+function extractFromNode(
+  node: Parser.SyntaxNode,
+  defs: Set<string>,
+  uses: Set<string>,
+  inLHS: boolean,
+): void {
+  switch (node.type) {
+    // ---- Variable declarations ----
+    case 'lexical_declaration':
+    case 'variable_declaration':
+      for (const child of node.namedChildren) {
+        extractFromNode(child, defs, uses, false)
+      }
+      return
+
+    case 'variable_declarator': {
+      const nameNode = node.childForFieldName('name')
+      const valueNode = node.childForFieldName('value')
+      if (nameNode) extractPattern(nameNode, defs)
+      if (valueNode) extractFromNode(valueNode, defs, uses, false)
+      return
+    }
+
+    // ---- Assignments ----
+    case 'assignment_expression':
+    case 'assignment': {
+      const left = node.childForFieldName('left')
+      const right = node.childForFieldName('right')
+      if (left) {
+        if (left.type === 'identifier') {
+          defs.add(left.text)
+        } else if (left.type === 'member_expression' || left.type === 'attribute') {
+          // obj.prop = val — the object is "used" and the property is a "def" of sorts
+          // For taint: we treat the whole member expression as a def of the root object
+          const obj = getMemberRoot(left)
+          if (obj) {
+            defs.add(obj)
+            uses.add(obj)
+          }
+        } else {
+          // Destructuring on LHS (JS) or tuple unpacking (Python)
+          extractPattern(left, defs)
+        }
+      }
+      if (right) extractFromNode(right, defs, uses, false)
+      return
+    }
+
+    // ---- Augmented assignment (+=, -=, etc.) ----
+    case 'augmented_assignment_expression':
+    case 'augmented_assignment': {
+      const left = node.childForFieldName('left')
+      const right = node.childForFieldName('right')
+      if (left?.type === 'identifier') {
+        defs.add(left.text)
+        uses.add(left.text) // reads old value
+      } else if (left?.type === 'member_expression' || left?.type === 'attribute') {
+        const obj = getMemberRoot(left)
+        if (obj) {
+          defs.add(obj)
+          uses.add(obj)
+        }
+      }
+      if (right) extractFromNode(right, defs, uses, false)
+      return
+    }
+
+    // ---- Update expression (++x, x--) ----
+    case 'update_expression': {
+      const arg = node.childForFieldName('argument') ?? node.namedChildren[0]
+      if (arg?.type === 'identifier') {
+        defs.add(arg.text)
+        uses.add(arg.text)
+      }
+      return
+    }
+
+    // ---- Function calls ----
+    case 'call_expression': {
+      const fn = node.childForFieldName('function')
+      const args = node.childForFieldName('arguments')
+      if (fn) extractFromNode(fn, defs, uses, false)
+      if (args) {
+        for (const arg of args.namedChildren) {
+          extractFromNode(arg, defs, uses, false)
+        }
+      }
+      return
+    }
+
+    // ---- Python function calls ----
+    case 'call': {
+      const fn = node.childForFieldName('function')
+      const args = node.childForFieldName('arguments') // argument_list
+      if (fn) extractFromNode(fn, defs, uses, false)
+      if (args) {
+        for (const arg of args.namedChildren) {
+          extractFromNode(arg, defs, uses, false)
+        }
+      }
+      return
+    }
+
+    case 'new_expression': {
+      const constructor = node.childForFieldName('constructor')
+      const args = node.childForFieldName('arguments')
+      if (constructor) extractFromNode(constructor, defs, uses, false)
+      if (args) {
+        for (const arg of args.namedChildren) {
+          extractFromNode(arg, defs, uses, false)
+        }
+      }
+      return
+    }
+
+    // ---- Identifiers ----
+    case 'identifier': {
+      if (inLHS) {
+        defs.add(node.text)
+      } else {
+        // Skip keywords that parse as identifiers
+        if (!KEYWORD_IDENTIFIERS.has(node.text)) {
+          uses.add(node.text)
+        }
+      }
+      return
+    }
+
+    // ---- Member expression (obj.prop, obj[expr]) ----
+    case 'member_expression': {
+      const obj = node.childForFieldName('object')
+      const prop = node.childForFieldName('property')
+      if (obj) extractFromNode(obj, defs, uses, false)
+      // Only extract computed property subscripts as uses
+      if (prop && node.children.some(c => c.type === '[')) {
+        extractFromNode(prop, defs, uses, false)
+      }
+      return
+    }
+
+    // ---- Python attribute access (obj.attr) ----
+    case 'attribute': {
+      const obj = node.childForFieldName('object')
+      if (obj) extractFromNode(obj, defs, uses, false)
+      // attribute field is just a name, not a use
+      return
+    }
+
+    // ---- Subscript expression ----
+    case 'subscript_expression': {
+      const obj = node.childForFieldName('object')
+      const index = node.childForFieldName('index')
+      if (obj) extractFromNode(obj, defs, uses, false)
+      if (index) extractFromNode(index, defs, uses, false)
+      return
+    }
+
+    // ---- Python subscript (obj[expr]) ----
+    case 'subscript': {
+      const obj = node.childForFieldName('value')
+      const subscripts = node.childForFieldName('subscript')
+      if (obj) extractFromNode(obj, defs, uses, false)
+      if (subscripts) extractFromNode(subscripts, defs, uses, false)
+      return
+    }
+
+    // ---- Return / throw / raise ----
+    case 'return_statement':
+    case 'throw_statement':
+    case 'raise_statement': {
+      for (const child of node.namedChildren) {
+        extractFromNode(child, defs, uses, false)
+      }
+      return
+    }
+
+    // ---- Expression statement (wraps an expression) ----
+    case 'expression_statement': {
+      for (const child of node.namedChildren) {
+        extractFromNode(child, defs, uses, false)
+      }
+      return
+    }
+
+    // ---- Await ----
+    case 'await_expression':
+    case 'await': {
+      for (const child of node.namedChildren) {
+        extractFromNode(child, defs, uses, false)
+      }
+      return
+    }
+
+    // ---- Yield ----
+    case 'yield_expression':
+    case 'yield': {
+      for (const child of node.namedChildren) {
+        extractFromNode(child, defs, uses, false)
+      }
+      return
+    }
+
+    // ---- Template string ----
+    case 'template_string': {
+      const subs = node.descendantsOfType('template_substitution')
+      for (const sub of subs) {
+        for (const child of sub.namedChildren) {
+          extractFromNode(child, defs, uses, false)
+        }
+      }
+      return
+    }
+
+    // ---- Binary / ternary / unary ----
+    case 'binary_expression':
+    case 'ternary_expression':
+    case 'unary_expression':
+    // Python operators
+    case 'binary_operator':
+    case 'boolean_operator':
+    case 'not_operator':
+    case 'unary_operator':
+    case 'comparison_operator':
+    case 'conditional_expression': {
+      for (const child of node.namedChildren) {
+        extractFromNode(child, defs, uses, false)
+      }
+      return
+    }
+
+    // ---- Array / object / Python collection literals ----
+    case 'array':
+    case 'object':
+    case 'tuple':
+    case 'list':
+    case 'dictionary':
+    case 'set': {
+      for (const child of node.namedChildren) {
+        extractFromNode(child, defs, uses, false)
+      }
+      return
+    }
+
+    case 'pair': {
+      const value = node.childForFieldName('value')
+      if (value) extractFromNode(value, defs, uses, false)
+      return
+    }
+
+    case 'spread_element': {
+      for (const child of node.namedChildren) {
+        extractFromNode(child, defs, uses, false)
+      }
+      return
+    }
+
+    // ---- Python keyword argument ----
+    case 'keyword_argument': {
+      const value = node.childForFieldName('value')
+      if (value) extractFromNode(value, defs, uses, false)
+      return
+    }
+
+    // ---- Python list comprehension / for_in_clause ----
+    case 'list_comprehension':
+    case 'set_comprehension':
+    case 'dictionary_comprehension':
+    case 'generator_expression':
+    case 'for_in_clause':
+    case 'if_clause': {
+      for (const child of node.namedChildren) {
+        extractFromNode(child, defs, uses, false)
+      }
+      return
+    }
+
+    // ---- Arrow / function expression (don't recurse into body — separate CFG) ----
+    case 'arrow_function':
+    case 'function_expression':
+    case 'function':
+    // Python function/class definitions — separate CFGs
+    case 'function_definition':
+    case 'class_definition':
+    case 'decorated_definition':
+      // Closures capture variables but we don't descend into their bodies
+      // The closure's own CFG handles its internal flow
+      return
+
+    // ---- Type annotations (skip) ----
+    case 'type_annotation':
+    case 'type_identifier':
+    case 'predefined_type':
+    case 'generic_type':
+      return
+
+    // ---- Literals (no defs or uses) ----
+    case 'string':
+      // Python f-strings have type 'string' but contain interpolation children with variables
+      if (node.descendantsOfType('interpolation').length > 0) {
+        for (const interp of node.descendantsOfType('interpolation')) {
+          for (const child of interp.namedChildren) {
+            extractFromNode(child, defs, uses, false)
+          }
+        }
+        return
+      }
+      return
+    case 'number':
+    case 'true':
+    case 'false':
+    case 'null':
+    case 'undefined':
+    case 'regex':
+    // Python literals
+    case 'integer':
+    case 'float':
+    case 'none':
+    case 'concatenated_string':
+      // May contain f-strings with interpolations
+      if (node.descendantsOfType('interpolation').length > 0) {
+        for (const interp of node.descendantsOfType('interpolation')) {
+          for (const child of interp.namedChildren) {
+            extractFromNode(child, defs, uses, false)
+          }
+        }
+        return
+      }
+      return
+
+    // ---- For-of/for-in header extracts ----
+    case 'for_in_statement': {
+      // handled by CFG builder, but if we see it extract the iterator var
+      const leftNode = node.childForFieldName('left')
+      const rightNode = node.childForFieldName('right')
+      if (leftNode) extractPattern(leftNode, defs)
+      if (rightNode) extractFromNode(rightNode, defs, uses, false)
+      return
+    }
+
+    // ---- Parenthesized ----
+    case 'parenthesized_expression': {
+      for (const child of node.namedChildren) {
+        extractFromNode(child, defs, uses, false)
+      }
+      return
+    }
+
+    // ---- Sequence expression (comma) ----
+    case 'sequence_expression': {
+      for (const child of node.namedChildren) {
+        extractFromNode(child, defs, uses, false)
+      }
+      return
+    }
+
+    // ---- Catch clause parameter ----
+    case 'catch_clause': {
+      const param = node.childForFieldName('parameter')
+      if (param) extractPattern(param, defs)
+      return
+    }
+
+    // ---- Python except clause ----
+    case 'except_clause':
+    case 'except_group_clause': {
+      for (const child of node.namedChildren) {
+        extractFromNode(child, defs, uses, false)
+      }
+      return
+    }
+
+    // ---- Python with statement ----
+    case 'with_statement': {
+      for (const child of node.namedChildren) {
+        extractFromNode(child, defs, uses, false)
+      }
+      return
+    }
+
+    // ---- Python as pattern (with X as y, except E as e) ----
+    case 'as_pattern': {
+      const target = node.namedChildren.find(c => c.type === 'as_pattern_target')
+      const ident = target?.namedChildren.find(c => c.type === 'identifier')
+      if (ident) defs.add(ident.text)
+      // Walk the expression side for uses
+      for (const child of node.namedChildren) {
+        if (child.type !== 'as_pattern_target') {
+          extractFromNode(child, defs, uses, false)
+        }
+      }
+      return
+    }
+
+    // ---- Default: walk named children for uses ----
+    default: {
+      for (const child of node.namedChildren) {
+        extractFromNode(child, defs, uses, false)
+      }
+      return
+    }
+  }
+}
+
+// ============================================================================
+// Pattern Extraction (destructuring)
+// ============================================================================
+
+/** Extract defined variable names from a pattern (identifier, array/object destructuring). */
+function extractPattern(node: Parser.SyntaxNode, defs: Set<string>): void {
+  switch (node.type) {
+    case 'identifier':
+      defs.add(node.text)
+      return
+
+    case 'array_pattern':
+      for (const element of node.namedChildren) {
+        extractPattern(element, defs)
+      }
+      return
+
+    case 'object_pattern':
+      for (const prop of node.namedChildren) {
+        if (prop.type === 'shorthand_property_identifier_pattern') {
+          defs.add(prop.text)
+        } else if (prop.type === 'pair_pattern') {
+          const value = prop.childForFieldName('value')
+          if (value) extractPattern(value, defs)
+        } else if (prop.type === 'rest_pattern') {
+          extractPattern(prop.namedChildren[0], defs)
+        }
+      }
+      return
+
+    case 'rest_pattern':
+      if (node.namedChildren[0]) {
+        extractPattern(node.namedChildren[0], defs)
+      }
+      return
+
+    case 'assignment_pattern': {
+      const left = node.childForFieldName('left')
+      if (left) extractPattern(left, defs)
+      return
+    }
+
+    // Variable declarations in for-of/for-in left side
+    case 'lexical_declaration':
+    case 'variable_declaration':
+      for (const child of node.namedChildren) {
+        if (child.type === 'variable_declarator') {
+          const nameNode = child.childForFieldName('name')
+          if (nameNode) extractPattern(nameNode, defs)
+        }
+      }
+      return
+
+    // Python tuple/list unpacking: a, b = ..., [a, b] = ...
+    case 'pattern_list':
+    case 'tuple_pattern':
+    case 'list_pattern':
+    case 'expression_list':
+    case 'tuple':
+    case 'list':
+      for (const child of node.namedChildren) {
+        extractPattern(child, defs)
+      }
+      return
+
+    // Python starred assignment: *rest = ...
+    case 'list_splat_pattern':
+      if (node.namedChildren[0]) {
+        extractPattern(node.namedChildren[0], defs)
+      }
+      return
+
+    default:
+      return
+  }
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/** Get the root identifier of a member expression chain: `a.b.c` → 'a'. */
+function getMemberRoot(node: Parser.SyntaxNode): string | null {
+  let current = node
+  while (current.type === 'member_expression' || current.type === 'attribute') {
+    const obj = current.childForFieldName('object')
+    if (!obj) return null
+    current = obj
+  }
+  return current.type === 'identifier' ? current.text : null
+}
+
+/** Keywords that tree-sitter may parse as identifiers in some contexts. */
+const KEYWORD_IDENTIFIERS = new Set([
+  'undefined', 'NaN', 'Infinity', 'arguments',
+  'this', 'super', 'globalThis',
+  // Python keywords
+  'None', 'True', 'False', 'self', 'cls',
+])

package/src/taint/file-analysis-cache.ts

@@ -0,0 +1,145 @@
+/**
+ * Per-File Analysis Cache
+ *
+ * Computes CFGs, sources, sinks, sanitizers, and import bindings exactly once
+ * per file. Eliminates redundant recomputation in cross-file resolution where
+ * a utility called from N files would get fully re-analyzed N times.
+ *
+ * Phase 8, Part 1.
+ */
+
+import type { ParsedAST } from '../parse/ast'
+import type { CFG, CFGNode } from './cfg-types'
+import { buildFileCFGs } from './cfg-builder'
+import { classifySources } from './source-classifier'
+import { classifySinks } from './sink-classifier'
+import { buildSanitizerRegistry } from './sanitizer-registry'
+import { collectImportBindings } from './helpers'
+import { collectVariableAliases } from '../detect/ast-rules/helpers/scope-analysis'
+import { collectPythonImportBindings } from '../detect/ast-rules/helpers/python-helpers'
+import type { TaintSource, TaintSink, TaintSanitizer } from './types'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface FileAnalysisCache {
+  cfgs: Map<string, CFG>
+  sources: TaintSource[]
+  sinks: TaintSink[]
+  sanitizers: TaintSanitizer[]
+  importBindings: Map<string, { module: string; originalName: string }>
+  aliases: Map<string, string>
+  /** Per-function CFG node maps: functionName → (astNodeId → CFGNode) */
+  cfgNodeMaps: Map<string, Map<number, CFGNode>>
+}
+
+/**
+ * ProjectAnalysisCache interface — consumers see a Map<string, FileAnalysisCache>.
+ * The actual implementation is lazy (see LazyProjectAnalysisCache).
+ */
+export type ProjectAnalysisCache = Map<string, FileAnalysisCache>
+
+// ============================================================================
+// CFG Node Map (for O(D) parent-chain lookup — Part 4)
+// ============================================================================
+
+/**
+ * Build a map from AST node ID → CFGNode for all nodes in a CFG.
+ * Used by findContainingCFGNodeFast() for O(D) parent-chain walk.
+ */
+export function buildCFGNodeMap(cfg: CFG): Map<number, CFGNode> {
+  const map = new Map<number, CFGNode>()
+  for (const [, cfgNode] of cfg.nodes) {
+    if (cfgNode.astNode) {
+      map.set(cfgNode.astNode.id, cfgNode)
+    }
+  }
+  return map
+}
+
+// ============================================================================
+// Per-File Cache Builder
+// ============================================================================
+
+/**
+ * Build analysis cache for a single file.
+ * Calls buildFileCFGs, classifySources, classifySinks, buildSanitizerRegistry,
+ * collectImportBindings exactly once.
+ */
+export function buildFileAnalysisCache(ast: ParsedAST): FileAnalysisCache {
+  const cfgs = buildFileCFGs(ast)
+
+  // Route imports based on language
+  const importBindings = ast.language === 'python'
+    ? collectPythonImportBindings(ast.tree.rootNode)
+    : collectImportBindings(ast.tree.rootNode)
+
+  const aliases = ast.language === 'python'
+    ? new Map<string, string>()  // Python aliases handled differently
+    : collectVariableAliases(ast.tree.rootNode)
+
+  const sources = classifySources(ast, importBindings)
+  const sinks = classifySinks(ast, importBindings, aliases)
+  const sanitizers = buildSanitizerRegistry(ast, importBindings, aliases)
+
+  // Build per-function CFG node maps
+  const cfgNodeMaps = new Map<string, Map<number, CFGNode>>()
+  for (const [name, cfg] of cfgs) {
+    cfgNodeMaps.set(name, buildCFGNodeMap(cfg))
+  }
+
+  return { cfgs, sources, sinks, sanitizers, importBindings, aliases, cfgNodeMaps }
+}
+
+// ============================================================================
+// Lazy Project-Level Cache
+// ============================================================================
+
+/**
+ * Lazy project analysis cache — computes per-file analysis on first access.
+ *
+ * Most files have zero taint sources and are never accessed during cross-file
+ * resolution. Eager computation wasted 3-15s on large repos (2800-5600 files).
+ * This lazy wrapper only builds CFGs/sources/sinks/sanitizers when `.get()` is
+ * called, reducing overhead to near-zero for untouched files.
+ */
+class LazyProjectAnalysisCache extends Map<string, FileAnalysisCache> {
+  private asts: Map<string, ParsedAST>
+  private computed = new Set<string>()
+
+  constructor(asts: Map<string, ParsedAST>) {
+    super()
+    this.asts = asts
+  }
+
+  override get(filePath: string): FileAnalysisCache | undefined {
+    // Return cached result if already computed
+    if (this.computed.has(filePath)) {
+      return super.get(filePath)
+    }
+
+    // Compute on first access
+    const ast = this.asts.get(filePath)
+    if (!ast) return undefined
+
+    const cache = buildFileAnalysisCache(ast)
+    super.set(filePath, cache)
+    this.computed.add(filePath)
+    return cache
+  }
+
+  override has(filePath: string): boolean {
+    return this.computed.has(filePath) || this.asts.has(filePath)
+  }
+}
+
+/**
+ * Build a lazy project analysis cache.
+ * Per-file caches are computed on first .get() access, not eagerly.
+ */
+export function buildProjectAnalysisCache(
+  asts: Map<string, ParsedAST>,
+): ProjectAnalysisCache {
+  return new LazyProjectAnalysisCache(asts)
+}