@oculum/scanner 1.0.13 → 1.0.15

package/src/taint/cfg-types.ts

@@ -0,0 +1,110 @@
+/**
+ * Control Flow Graph Types
+ *
+ * Data model for intra-procedural control flow graphs built from tree-sitter ASTs.
+ * Each function maps to one CFG. Used by the taint propagation engine (Part 3)
+ * to trace data flow through branches, loops, and error handling.
+ *
+ * Granularity: statement-level. Each CFGNode = one AST statement.
+ * Expression-level flow is handled by the taint propagator within each node.
+ */
+
+import type Parser from 'tree-sitter'
+
+// ============================================================================
+// Nodes
+// ============================================================================
+
+export type CFGNodeKind = 'entry' | 'exit' | 'statement' | 'condition'
+
+export interface CFGNode {
+  /** Unique node id. 0 = entry, 1 = exit, >= 2 for real nodes. */
+  id: number
+  kind: CFGNodeKind
+  /** The AST statement this node represents. Null for synthetic entry/exit. */
+  astNode: Parser.SyntaxNode | null
+  /** Variables written by this node. */
+  defs: Set<string>
+  /** Variables read by this node. */
+  uses: Set<string>
+  /** 1-based source line. -1 for synthetic entry/exit. */
+  line: number
+  /** Human-readable debug label. */
+  label: string
+}
+
+// ============================================================================
+// Edges
+// ============================================================================
+
+export type CFGEdgeKind =
+  | 'normal'
+  | 'true'
+  | 'false'
+  | 'exception'
+  | 'return'
+  | 'throw'
+  | 'break'
+  | 'continue'
+  | 'fallthrough'
+
+export interface CFGEdge {
+  from: number
+  to: number
+  kind: CFGEdgeKind
+}
+
+// ============================================================================
+// Graph
+// ============================================================================
+
+export interface CFG {
+  /** All nodes keyed by id. */
+  nodes: Map<number, CFGNode>
+  /** Forward adjacency: nodeId -> outgoing edges. */
+  edges: Map<number, CFGEdge[]>
+  /** Reverse adjacency: nodeId -> incoming edges. */
+  reverseEdges: Map<number, CFGEdge[]>
+  /** Always 0. */
+  entryId: number
+  /** Always 1. */
+  exitId: number
+  /** The AST node of the function this CFG represents. */
+  functionNode: Parser.SyntaxNode
+  /** Function name matching call-graph naming conventions. */
+  functionName: string
+}
+
+// ============================================================================
+// Builder internals (exported for testing)
+// ============================================================================
+
+/** A pending exit: a node id + the edge kind to connect with. */
+export interface PendingExit {
+  nodeId: number
+  edgeKind: CFGEdgeKind
+}
+
+/** Tracks an active loop for break/continue resolution. */
+export interface LoopFrame {
+  /** Node id that `continue` should jump to. */
+  continueTarget: number
+  /** Label if this loop is labeled. */
+  label?: string
+  /** Collected break exits. */
+  breakExits: PendingExit[]
+}
+
+/** Tracks an active switch for break resolution. */
+export interface SwitchFrame {
+  /** Label if this switch is labeled. */
+  label?: string
+  /** Collected break exits. */
+  breakExits: PendingExit[]
+}
+
+/** Tracks try/catch for throw resolution. */
+export interface TryFrame {
+  /** Node id of the catch entry (throw jumps here). */
+  catchEntry: number
+}

package/src/taint/constant-propagation.ts

@@ -0,0 +1,170 @@
+/**
+ * Constant Propagation for Taint Analysis
+ *
+ * Tracks constant values through the propagation engine so that variables
+ * assigned from literals, string concatenation of constants, or template
+ * literals with only constant substitutions are marked as NOT tainted.
+ *
+ * Scope: `const` declarations with primitive literal initializers only.
+ * Does NOT track `let`/`var` (can be reassigned), arrays, or objects.
+ */
+
+import type Parser from 'tree-sitter'
+import { walkAST } from '../parse/ast'
+
+export type ConstantMap = Map<string, string | number | boolean | null>
+
+const LITERAL_TYPES = new Set(['string', 'number', 'true', 'false', 'null', 'undefined'])
+
+/**
+ * Collect all `const` declarations with literal initializers in a function scope.
+ * Only collects primitive literals (string, number, boolean, null).
+ */
+export function collectConstants(root: Parser.SyntaxNode): ConstantMap {
+  const constants: ConstantMap = new Map()
+
+  walkAST(root, (node) => {
+    // Only collect from lexical_declaration with 'const'
+    if (node.type === 'lexical_declaration') {
+      const text = node.text
+      if (!text.startsWith('const ')) return false
+
+      for (const child of node.namedChildren) {
+        if (child.type !== 'variable_declarator') continue
+        const nameNode = child.childForFieldName('name')
+        const valueNode = child.childForFieldName('value')
+        if (!nameNode || !valueNode || nameNode.type !== 'identifier') continue
+
+        const value = extractLiteralValue(valueNode)
+        if (value !== undefined) {
+          constants.set(nameNode.text, value)
+        }
+      }
+      return false
+    }
+
+    // Don't descend into nested function scopes
+    if (node.type === 'arrow_function' || node.type === 'function_expression' ||
+        node.type === 'function_declaration' || node.type === 'method_definition') {
+      return true
+    }
+
+    return false
+  })
+
+  return constants
+}
+
+/**
+ * Extract a literal value from a node. Returns undefined if not a literal.
+ */
+function extractLiteralValue(node: Parser.SyntaxNode): string | number | boolean | null | undefined {
+  switch (node.type) {
+    case 'string': {
+      // Remove quotes
+      const text = node.text
+      return text.slice(1, -1)
+    }
+    case 'number':
+      return Number(node.text)
+    case 'true':
+      return true
+    case 'false':
+      return false
+    case 'null':
+      return null
+    case 'undefined':
+      return null
+    case 'template_string': {
+      // Only if no substitutions
+      if (node.descendantsOfType('template_substitution').length === 0) {
+        // Remove backticks
+        return node.text.slice(1, -1)
+      }
+      return undefined
+    }
+    default:
+      return undefined
+  }
+}
+
+/**
+ * Try to fold an expression to a constant string value.
+ * Returns null if any part is non-constant.
+ *
+ * Handles:
+ * - Literal strings/numbers
+ * - `const` identifiers from ConstantMap
+ * - Binary `+` of two constants
+ * - Template literals with only constant substitutions
+ */
+export function foldExpression(node: Parser.SyntaxNode, constants: ConstantMap): string | null {
+  // Literal values
+  // Python f-strings have type 'string' but contain dynamic interpolations — NOT constant
+  if (LITERAL_TYPES.has(node.type)) {
+    if (node.type === 'string' && node.descendantsOfType('interpolation').length > 0) {
+      return null  // f-string with interpolations is not constant
+    }
+    const v = extractLiteralValue(node)
+    return v !== undefined ? String(v) : null
+  }
+
+  // Identifier: look up in constants
+  if (node.type === 'identifier') {
+    const v = constants.get(node.text)
+    return v !== undefined ? String(v) : null
+  }
+
+  // Binary +: fold both sides
+  if (node.type === 'binary_expression') {
+    const op = node.childForFieldName('operator')
+    if (!op || op.text !== '+') return null
+
+    const left = node.childForFieldName('left')
+    const right = node.childForFieldName('right')
+    if (!left || !right) return null
+
+    const lv = foldExpression(left, constants)
+    if (lv === null) return null
+    const rv = foldExpression(right, constants)
+    if (rv === null) return null
+
+    return lv + rv
+  }
+
+  // Template literal: fold all substitutions
+  if (node.type === 'template_string') {
+    const parts: string[] = []
+    for (const child of node.children) {
+      if (child.type === 'string_fragment' || child.type === 'escape_sequence') {
+        parts.push(child.text)
+      } else if (child.type === 'template_substitution') {
+        const inner = child.namedChildren[0]
+        if (!inner) return null
+        const folded = foldExpression(inner, constants)
+        if (folded === null) return null
+        parts.push(folded)
+      } else if (child.type === '`') {
+        // Skip template literal delimiters
+      }
+    }
+    return parts.join('')
+  }
+
+  // Parenthesized expression
+  if (node.type === 'parenthesized_expression') {
+    const inner = node.namedChildren[0]
+    return inner ? foldExpression(inner, constants) : null
+  }
+
+  // Not foldable
+  return null
+}
+
+/**
+ * Check if an expression is entirely constant-derived.
+ * Returns true if all leaf values are literals or resolve to constants.
+ */
+export function isConstantExpression(node: Parser.SyntaxNode, constants: ConstantMap): boolean {
+  return foldExpression(node, constants) !== null
+}

package/src/taint/cross-file-analyzer.ts

@@ -0,0 +1,118 @@
+/**
+ * Cross-File Taint Analyzer — Project-wide orchestrator
+ *
+ * Combines the CrossFileIndex with per-file taint analysis, providing
+ * CallResolutionContext to enable inter-procedural taint tracking.
+ *
+ * Phase 8: Uses ProjectAnalysisCache to avoid redundant recomputation
+ * and SummaryCache for function-level taint summarization.
+ *
+ * Public API:
+ *   analyzeTaintsForProject(files, asts, moduleGraph): TaintFinding[]
+ */
+
+import type { ScanFile } from '../shared/types'
+import type { ParsedAST } from '../parse/ast'
+import type { ModuleGraph } from '../model/module-graph'
+import { buildCrossFileIndex } from './cross-file-index'
+import { analyzeTaintsForFile } from './taint-analyzer'
+import type { TaintFinding, CallResolutionContext, SummaryCache } from './propagation-types'
+import { isTestOrMockFile } from '../parse/file-classifier'
+import { buildProjectAnalysisCache } from './file-analysis-cache'
+import { hasLikelySources } from './source-classifier'
+
+// ============================================================================
+// Project-Level Analysis
+// ============================================================================
+
+/**
+ * Run taint analysis across all files in a project with cross-file resolution.
+ *
+ * 1. Build CrossFileIndex from ASTs and module graph
+ * 2. Build ProjectAnalysisCache (CFGs, sources, sinks, sanitizers per file)
+ * 3. Create CallResolutionContext with index + caches
+ * 4. For each file, run analyzeTaintsForFile with the context
+ * 5. Collect and deduplicate findings across files
+ */
+export function analyzeTaintsForProject(
+  files: ScanFile[],
+  asts: Map<string, ParsedAST>,
+  moduleGraph: ModuleGraph,
+): TaintFinding[] {
+  // Build cross-file function resolution index
+  const crossFileIndex = buildCrossFileIndex(files, asts, moduleGraph)
+
+  // Build lazy per-file analysis cache (Phase 8) — computes on first .get()
+  const analysisCache = buildProjectAnalysisCache(asts)
+
+  // Initialize summary cache for function-level taint summaries (Phase 8)
+  const summaryCache: SummaryCache = new Map()
+
+  // Create call resolution context
+  const callContext: CallResolutionContext = {
+    crossFileIndex,
+    allASTs: asts,
+    callStack: new Set(),
+    maxDepth: 5,
+    resultCache: new Map(),
+    analysisCache,
+    summaryCache,
+  }
+
+  const allFindings: TaintFinding[] = []
+
+  // Build content map for quick source pre-filtering
+  const contentMap = new Map<string, string>()
+  for (const file of files) {
+    contentMap.set(file.path, file.content)
+  }
+
+  // Analyze each file with cross-file context
+  for (const [filePath, ast] of asts) {
+    // Skip test files
+    if (isTestOrMockFile(filePath)) continue
+
+    // Quick regex pre-filter: skip files that can't possibly have taint sources.
+    // Conservative over-approximation — files passing this check may still have
+    // zero real sources (handled by the normal early exit in analyzeTaintsForFile).
+    const content = contentMap.get(filePath)
+    if (content && !hasLikelySources(content)) continue
+
+    // Reset call stack for each file (but keep the result cache + analysis cache)
+    callContext.callStack.clear()
+
+    const findings = analyzeTaintsForFile(ast, filePath, callContext)
+    allFindings.push(...findings)
+  }
+
+  // Also collect callee findings from the result cache
+  for (const result of callContext.resultCache.values()) {
+    if (result && result.calleeFindings.length > 0) {
+      allFindings.push(...result.calleeFindings)
+    }
+  }
+
+  return deduplicateProjectFindings(allFindings)
+}
+
+// ============================================================================
+// Deduplication
+// ============================================================================
+
+/**
+ * Deduplicate findings across files.
+ * Same source line + same sink line + same file + same kinds = one finding.
+ */
+function deduplicateProjectFindings(findings: TaintFinding[]): TaintFinding[] {
+  const seen = new Set<string>()
+  const result: TaintFinding[] = []
+
+  for (const f of findings) {
+    const key = `${f.filePath}:${f.source.line}:${f.sink.line}:${[...f.matchingKinds].sort().join(',')}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    result.push(f)
+  }
+
+  return result
+}

package/src/taint/cross-file-index.ts

@@ -0,0 +1,275 @@
+/**
+ * Cross-File Function Index
+ *
+ * Builds a project-wide function index that maps imported names to their
+ * actual function definitions across files. Foundation for all cross-file
+ * taint analysis (Phase 3, Part 1).
+ *
+ * Combines:
+ * - Module graph (import/export edges, path resolution)
+ * - Per-file call graphs (FunctionNode with params, isExported, astNode)
+ * - AST-based import binding collection
+ *
+ * Public API:
+ *   buildCrossFileIndex(files, asts, moduleGraph): CrossFileIndex
+ */
+
+import type Parser from 'tree-sitter'
+import type { ScanFile } from '../shared/types'
+import type { ParsedAST } from '../parse/ast'
+import { collectFunctions, type FunctionNode } from '../parse/call-graph'
+import type { ModuleGraph, ModuleNode } from '../model/module-graph'
+import { collectImportBindings } from './helpers'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface FunctionDefinition {
+  filePath: string
+  functionName: string
+  astNode: Parser.SyntaxNode
+  params: string[]
+  isAsync: boolean
+  isExported: boolean
+}
+
+export interface CallSiteInfo {
+  callerFile: string
+  callerFunction: string
+  line: number
+  argumentExpressions: string[]
+}
+
+export interface CrossFileIndex {
+  /**
+   * Resolve an imported name to the actual function definition.
+   * Key: "${filePath}:${localName}" → FunctionDefinition in the target file.
+   */
+  resolveImport: Map<string, FunctionDefinition>
+
+  /**
+   * All function definitions across the project.
+   * Key: "${filePath}:${functionName}" → FunctionDefinition.
+   */
+  functionDefs: Map<string, FunctionDefinition>
+
+  /**
+   * Reverse index: which call sites invoke a given function.
+   * Key: "${filePath}:${functionName}" → call sites from other files/functions.
+   */
+  calledFrom: Map<string, CallSiteInfo[]>
+}
+
+// ============================================================================
+// Index Builder
+// ============================================================================
+
+/**
+ * Build a cross-file function index from parsed ASTs and the module graph.
+ *
+ * Steps:
+ * 1. For each file with AST, extract function definitions (collectFunctions only)
+ * 2. Build resolveImport map using module graph edges + export resolution
+ */
+export function buildCrossFileIndex(
+  files: ScanFile[],
+  asts: Map<string, ParsedAST>,
+  moduleGraph: ModuleGraph,
+): CrossFileIndex {
+  const functionDefs = new Map<string, FunctionDefinition>()
+  const resolveImport = new Map<string, FunctionDefinition>()
+  const calledFrom = new Map<string, CallSiteInfo[]>()
+
+  // Step 1: Extract function definitions from all files (collectFunctions only, no call edges)
+  for (const [filePath, ast] of asts) {
+    const fileFunctions = new Map<string, FunctionNode>()
+    collectFunctions(ast.tree.rootNode, fileFunctions)
+
+    for (const [fnName, fnNode] of fileFunctions) {
+      const def: FunctionDefinition = {
+        filePath,
+        functionName: fnName,
+        astNode: fnNode.node,
+        params: fnNode.params,
+        isAsync: fnNode.isAsync,
+        isExported: fnNode.isExported,
+      }
+      functionDefs.set(`${filePath}:${fnName}`, def)
+    }
+  }
+
+  // Per-file bindings cache (avoids redundant collectImportBindings calls)
+  const bindingsCache = new Map<string, Map<string, { module: string; originalName: string }>>()
+
+  // Step 2: Build resolveImport map
+  for (const [filePath, moduleNode] of moduleGraph.nodes) {
+    if (!asts.has(filePath)) continue
+
+    for (const imp of moduleNode.imports) {
+      if (!imp.resolvedPath) continue
+
+      const targetNode = moduleGraph.nodes.get(imp.resolvedPath)
+      if (!targetNode) continue
+
+      if (imp.isNamespace) {
+        // import * as ns from './mod' — resolve ns.x at call site
+        const nsName = imp.importedNames[0]
+        if (!nsName) continue
+
+        // Register all exported functions from target under this namespace
+        for (const exp of targetNode.exports) {
+          const resolvedDef = resolveExportToDefinition(
+            exp.name, exp.isDefault, imp.resolvedPath, targetNode,
+            moduleGraph, functionDefs, 0,
+          )
+          if (resolvedDef) {
+            resolveImport.set(`${filePath}:${nsName}.${exp.name}`, resolvedDef)
+          }
+        }
+        continue
+      }
+
+      for (const importedName of imp.importedNames) {
+        const isDefault = importedName === 'default'
+
+        // Find the matching export in the target file
+        const resolvedDef = resolveExportToDefinition(
+          importedName, isDefault, imp.resolvedPath, targetNode,
+          moduleGraph, functionDefs, 0,
+        )
+
+        if (resolvedDef) {
+          // Also check aliased import: import { query as q } -> key is the local name
+          // importedNames stores the original name; we need to map local binding
+          const localName = getLocalBindingName(filePath, importedName, asts, bindingsCache)
+          resolveImport.set(`${filePath}:${localName}`, resolvedDef)
+
+          // Also register under the original name (if different)
+          if (localName !== importedName) {
+            resolveImport.set(`${filePath}:${importedName}`, resolvedDef)
+          }
+        }
+      }
+    }
+  }
+
+  return { resolveImport, functionDefs, calledFrom }
+}
+
+// ============================================================================
+// Export Resolution (follows re-export chains)
+// ============================================================================
+
+const MAX_REEXPORT_DEPTH = 5
+
+/**
+ * Resolve an exported name to its actual FunctionDefinition.
+ * Follows re-export chains (up to MAX_REEXPORT_DEPTH hops).
+ */
+function resolveExportToDefinition(
+  exportName: string,
+  isDefault: boolean,
+  filePath: string,
+  moduleNode: ModuleNode,
+  moduleGraph: ModuleGraph,
+  functionDefs: Map<string, FunctionDefinition>,
+  depth: number,
+): FunctionDefinition | null {
+  if (depth > MAX_REEXPORT_DEPTH) return null
+
+  // First, check if this file has a direct function definition matching the export
+  const directKey = `${filePath}:${exportName}`
+  const directDef = functionDefs.get(directKey)
+  if (directDef) return directDef
+
+  // For default exports, also check 'default' key
+  if (isDefault) {
+    const defaultKey = `${filePath}:default`
+    const defaultDef = functionDefs.get(defaultKey)
+    if (defaultDef) return defaultDef
+  }
+
+  // Check exports to find the actual name or follow re-export chains
+  for (const exp of moduleNode.exports) {
+    const nameMatch = isDefault
+      ? exp.isDefault
+      : exp.name === exportName
+
+    if (!nameMatch) continue
+
+    if (exp.kind === 'reexport' && exp.sourceModule) {
+      // Follow re-export chain
+      const reExportTarget = findResolvedImportPath(moduleNode, exp.sourceModule)
+      if (!reExportTarget) continue
+
+      const targetModuleNode = moduleGraph.nodes.get(reExportTarget)
+      if (!targetModuleNode) continue
+
+      return resolveExportToDefinition(
+        exportName, isDefault, reExportTarget, targetModuleNode,
+        moduleGraph, functionDefs, depth + 1,
+      )
+    }
+
+    // Non-re-export: the export's `name` is the actual function name.
+    // For `export default function createApp()`, exp.name='createApp' but
+    // the caller asked for 'default'. Check functionDefs with the actual name.
+    if (exp.name !== exportName) {
+      const actualKey = `${filePath}:${exp.name}`
+      const actualDef = functionDefs.get(actualKey)
+      if (actualDef) return actualDef
+    }
+  }
+
+  return null
+}
+
+/**
+ * Find the resolved file path for a given import path within a module's imports.
+ */
+function findResolvedImportPath(
+  moduleNode: ModuleNode,
+  importPath: string,
+): string | null {
+  for (const imp of moduleNode.imports) {
+    if (imp.importPath === importPath && imp.resolvedPath) {
+      return imp.resolvedPath
+    }
+  }
+  return null
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Get the local binding name for an imported symbol.
+ * Handles aliased imports: `import { query as q }` -> returns 'q'.
+ */
+function getLocalBindingName(
+  filePath: string,
+  originalName: string,
+  asts: Map<string, ParsedAST>,
+  bindingsCache: Map<string, Map<string, { module: string; originalName: string }>>,
+): string {
+  const ast = asts.get(filePath)
+  if (!ast) return originalName
+
+  let bindings = bindingsCache.get(filePath)
+  if (!bindings) {
+    bindings = collectImportBindings(ast.tree.rootNode)
+    bindingsCache.set(filePath, bindings)
+  }
+
+  // Look for a binding whose originalName matches
+  for (const [localName, info] of bindings) {
+    if (info.originalName === originalName) {
+      return localName
+    }
+  }
+
+  return originalName
+}
+