@oculum/scanner 1.0.12 → 1.0.13

package/src/model/taint-tracker.ts

@@ -0,0 +1,333 @@
+/**
+ * Taint Propagation Tracker — Propagates taint through variable assignments.
+ *
+ * Walks lines forward from discovered sources, tracking how tainted data
+ * flows through assignments, destructuring, template literals, etc.
+ * Marks variables as sanitised when they pass through known sanitisers.
+ */
+
+import type { UserInputSource, TaintedVariable, TaintPropagationType } from './taint-types'
+import type { SanitiserInfo } from './taint-types'
+import { isSanitiserCall } from './sanitiser-detection'
+
+// ============================================================================
+// Scope Tracking
+// ============================================================================
+
+/**
+ * Track brace depth for approximate scope analysis.
+ * Counts { and } while ignoring those inside string literals and comments.
+ */
+function countBraceChanges(line: string, inMultiLineComment: boolean): { delta: number; inComment: boolean } {
+  let delta = 0
+  let inComment = inMultiLineComment
+  let inString: string | null = null
+  let escaped = false
+
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i]
+    const next = i < line.length - 1 ? line[i + 1] : ''
+
+    if (escaped) {
+      escaped = false
+      continue
+    }
+
+    if (ch === '\\') {
+      escaped = true
+      continue
+    }
+
+    // Handle multi-line comments
+    if (inComment) {
+      if (ch === '*' && next === '/') {
+        inComment = false
+        i++ // skip /
+      }
+      continue
+    }
+
+    // Handle single-line comments
+    if (!inString && ch === '/' && next === '/') {
+      break // rest of line is comment
+    }
+
+    // Handle multi-line comment start
+    if (!inString && ch === '/' && next === '*') {
+      inComment = true
+      i++ // skip *
+      continue
+    }
+
+    // Handle string literals
+    if (!inString && (ch === '"' || ch === "'" || ch === '`')) {
+      inString = ch
+      continue
+    }
+
+    if (inString && ch === inString) {
+      inString = null
+      continue
+    }
+
+    // Count braces outside strings and comments
+    if (!inString) {
+      if (ch === '{') delta++
+      if (ch === '}') delta--
+    }
+  }
+
+  return { delta, inComment }
+}
+
+// ============================================================================
+// Propagation Detection
+// ============================================================================
+
+/** Check if a tainted variable appears on the right side of an expression */
+function findTaintedVarInExpression(
+  line: string,
+  taintedVars: Map<string, TaintedVariable>
+): { varName: string; variable: TaintedVariable } | null {
+  for (const [name, tv] of taintedVars) {
+    // Use word boundary to avoid partial matches (e.g., "url" matching "urlParser")
+    const regex = new RegExp(`\\b${escapeRegex(name)}\\b`)
+    if (regex.test(line)) {
+      return { varName: name, variable: tv }
+    }
+  }
+  return null
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Detect what type of propagation is happening on a line.
+ */
+function detectPropagationType(line: string): TaintPropagationType | null {
+  const trimmed = line.trim()
+
+  // Destructuring: const { a, b } = taintedVar
+  if (/(?:const|let|var)\s+\{[^}]+\}\s*=/.test(trimmed)) {
+    return 'destructure'
+  }
+
+  // Spread: { ...taintedVar }
+  if (/\.\.\.\w+/.test(trimmed)) {
+    return 'spread'
+  }
+
+  // Template literal: `${taintedVar}`
+  if (/`[^`]*\$\{[^}]+\}[^`]*`/.test(trimmed)) {
+    return 'template_literal'
+  }
+
+  // String concatenation: "..." + taintedVar
+  if (/['"][^'"]*['"]\s*\+/.test(trimmed) || /\+\s*['"][^'"]*['"]/.test(trimmed)) {
+    return 'string_concat'
+  }
+
+  // Ternary/nullish: taintedVar ?? default, taintedVar || default
+  if (/\?\?|\|\|/.test(trimmed) && /(?:const|let|var)\s+\w+\s*=/.test(trimmed)) {
+    return 'ternary'
+  }
+
+  // Array push: arr.push(taintedVar)
+  if (/\.push\s*\(/.test(trimmed)) {
+    return 'array_push'
+  }
+
+  // Object spread: { ...taintedVar, key: value }
+  if (/\{[^}]*\.\.\.\w+/.test(trimmed)) {
+    return 'object_spread'
+  }
+
+  // Method chain: taintedVar.trim().toLowerCase() — result still tainted
+  if (/\.\w+\s*\(/.test(trimmed)) {
+    return 'method_chain'
+  }
+
+  // Direct assignment: const x = taintedVar
+  if (/(?:const|let|var)\s+\w+\s*=/.test(trimmed) || /\w+\s*=(?!=)/.test(trimmed)) {
+    return 'direct_assignment'
+  }
+
+  return null
+}
+
+/**
+ * Extract the newly assigned variable name from a line.
+ */
+function extractAssignedVariable(line: string): string[] {
+  const trimmed = line.trim()
+
+  // Destructuring: const { a, b } = ...
+  const destructMatch = trimmed.match(/(?:const|let|var)\s+\{\s*([^}]+)\}\s*=/)
+  if (destructMatch) {
+    return destructMatch[1].split(',').map(n => {
+      const parts = n.trim().split(':')
+      return (parts.length > 1 ? parts[1] : parts[0]).trim()
+    }).filter(n => n.length > 0 && n !== '...')
+  }
+
+  // Array destructuring: const [a, b] = ...
+  const arrayMatch = trimmed.match(/(?:const|let|var)\s+\[\s*([^\]]+)\]\s*=/)
+  if (arrayMatch) {
+    return arrayMatch[1].split(',').map(n => n.trim()).filter(n => n.length > 0 && n !== '...')
+  }
+
+  // Direct assignment: const x = ... or let x = ...
+  const directMatch = trimmed.match(/(?:const|let|var)\s+(\w+)\s*=/)
+  if (directMatch) {
+    return [directMatch[1]]
+  }
+
+  // Re-assignment: x = ... (no const/let/var)
+  const reassignMatch = trimmed.match(/^(\w+)\s*=(?!=)/)
+  if (reassignMatch) {
+    return [reassignMatch[1]]
+  }
+
+  return []
+}
+
+/**
+ * Determine variable scope type from declaration keyword.
+ */
+function getDeclarationType(line: string): 'block' | 'function' | 'reassign' {
+  const trimmed = line.trim()
+  if (/^(?:const|let)\b/.test(trimmed)) return 'block'
+  if (/^var\b/.test(trimmed)) return 'function'
+  return 'reassign'
+}
+
+// ============================================================================
+// Main Propagation Function
+// ============================================================================
+
+/**
+ * Propagate taint through variable assignments in a file.
+ *
+ * Algorithm:
+ * 1. Initialize tainted vars from sources
+ * 2. Walk lines forward, tracking brace depth for scope
+ * 3. For each line, check if any tainted var appears on the right side
+ * 4. If sanitiser wraps the expression, mark sanitised
+ * 5. When exiting a scope, remove block-scoped (const/let) vars at that depth
+ */
+export function propagateTaint(
+  content: string,
+  _filePath: string,
+  sources: UserInputSource[],
+  sanitisers: SanitiserInfo[]
+): TaintedVariable[] {
+  const lines = content.split('\n')
+  const taintedVars = new Map<string, TaintedVariable>()
+  const allTaintedVars: TaintedVariable[] = []
+
+  // Track scope for variable lifetime
+  let braceDepth = 0
+  let inMultiLineComment = false
+  const scopeVars = new Map<string, number>() // variable name -> declared scope depth
+
+  // Initialize tainted vars from sources
+  for (const source of sources) {
+    const tv: TaintedVariable = {
+      name: source.variable,
+      taintedAt: source.line,
+      source,
+      propagation: 'direct_assignment',
+      sanitised: false,
+      scopeDepth: 0,
+    }
+    taintedVars.set(source.variable, tv)
+    allTaintedVars.push(tv)
+  }
+
+  // Walk lines forward
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const lineNumber = i + 1
+    const trimmed = line.trim()
+
+    // Skip empty lines and comments
+    if (trimmed === '' || trimmed.startsWith('//')) {
+      continue
+    }
+
+    // Update brace depth
+    const braceResult = countBraceChanges(line, inMultiLineComment)
+    inMultiLineComment = braceResult.inComment
+
+    // Handle scope exit: remove block-scoped vars declared at the exiting depth
+    if (braceResult.delta < 0) {
+      const newDepth = braceDepth + braceResult.delta
+      for (const [varName, declDepth] of scopeVars) {
+        if (declDepth > newDepth) {
+          taintedVars.delete(varName)
+          scopeVars.delete(varName)
+        }
+      }
+    }
+
+    braceDepth = Math.max(0, braceDepth + braceResult.delta)
+
+    // Skip lines that are only closing braces
+    if (/^[}\])\s;]*$/.test(trimmed)) continue
+
+    // Check if any tainted variable appears in this line (on the right side of an assignment)
+    const found = findTaintedVarInExpression(line, taintedVars)
+    if (!found) continue
+
+    // Check if this line is an assignment that creates a new tainted variable
+    const assignedVars = extractAssignedVariable(line)
+    if (assignedVars.length === 0) continue
+
+    // Don't re-taint the same variable (e.g., `userInput = userInput.trim()`)
+    const newVars = assignedVars.filter(v => v !== found.varName)
+    if (newVars.length === 0) {
+      // Still might be a method chain on the same variable — update it
+      // Check if sanitiser is applied
+      const sanitResult = isSanitiserCall(line, sanitisers)
+      if (sanitResult.sanitised && taintedVars.has(found.varName)) {
+        const existing = taintedVars.get(found.varName)!
+        existing.sanitised = true
+        existing.sanitisedAt = lineNumber
+        existing.sanitisationMethod = sanitResult.method
+      }
+      continue
+    }
+
+    // Detect propagation type
+    const propagationType = detectPropagationType(line) ?? 'direct_assignment'
+    const declType = getDeclarationType(line)
+
+    // Check if sanitised at this assignment
+    const sanitResult = isSanitiserCall(line, sanitisers)
+
+    for (const varName of newVars) {
+      const tv: TaintedVariable = {
+        name: varName,
+        taintedAt: lineNumber,
+        source: found.variable.source,
+        propagation: propagationType,
+        sanitised: sanitResult.sanitised,
+        sanitisedAt: sanitResult.sanitised ? lineNumber : undefined,
+        sanitisationMethod: sanitResult.method,
+        scopeDepth: braceDepth,
+      }
+
+      taintedVars.set(varName, tv)
+      allTaintedVars.push(tv)
+
+      // Track scope for block-scoped vars
+      if (declType === 'block') {
+        scopeVars.set(varName, braceDepth)
+      }
+    }
+  }
+
+  return allTaintedVars
+}

package/src/model/taint-types.ts

@@ -0,0 +1,149 @@
+/**
+ * Taint Analysis Types
+ *
+ * All interfaces for intra-file taint tracking: source discovery,
+ * taint propagation, sanitiser detection, and sink matching.
+ */
+
+// ============================================================================
+// User Input Sources
+// ============================================================================
+
+export type UserInputSourceType =
+  | 'http_body'
+  | 'http_query'
+  | 'http_params'
+  | 'http_headers'
+  | 'url_search_params'
+  | 'form_data'
+  | 'file_upload'
+  | 'websocket_message'
+  | 'cli_args'
+  | 'env_var'
+  | 'database_result'
+  | 'external_api'
+
+export interface UserInputSource {
+  line: number
+  expression: string
+  variable: string
+  sourceType: UserInputSourceType
+  frameworkSource?: string
+  confidence: 'high' | 'medium' | 'low'
+}
+
+// ============================================================================
+// Taint Propagation
+// ============================================================================
+
+export type TaintPropagationType =
+  | 'direct_assignment'
+  | 'destructure'
+  | 'spread'
+  | 'function_arg'
+  | 'template_literal'
+  | 'string_concat'
+  | 'array_push'
+  | 'object_spread'
+  | 'method_chain'
+  | 'ternary'
+
+export interface TaintedVariable {
+  name: string
+  taintedAt: number
+  source: UserInputSource
+  propagation: TaintPropagationType
+  sanitised: boolean
+  sanitisedAt?: number
+  sanitisationMethod?: string
+  scopeDepth: number
+}
+
+// ============================================================================
+// Sinks
+// ============================================================================
+
+export type SinkType =
+  | 'sql_query'
+  | 'eval'
+  | 'exec'
+  | 'inner_html'
+  | 'http_request'
+  | 'redirect'
+  | 'file_write'
+  | 'path_access'
+  | 'template_render'
+  | 'command_exec'
+  | 'regex_constructor'
+  | 'dynamic_import'
+  | 'deserialization'
+
+export interface TaintSink {
+  line: number
+  expression: string
+  sinkType: SinkType
+}
+
+// ============================================================================
+// Taint Paths
+// ============================================================================
+
+export interface TaintPath {
+  source: UserInputSource
+  chain: TaintedVariable[]
+  sink: TaintSink
+  sanitised: boolean
+  confidence: 'high' | 'medium' | 'low'
+}
+
+// ============================================================================
+// Sanitisers
+// ============================================================================
+
+export type SanitiserTarget = 'html' | 'sql' | 'command' | 'url' | 'regex' | 'path' | 'all'
+
+export interface SanitiserInfo {
+  name: string
+  line: number
+  sanitises: SanitiserTarget
+  detection: 'known_library' | 'name_heuristic' | 'type_annotation'
+  library?: string
+}
+
+// ============================================================================
+// File-Level Taint Analysis Result
+// ============================================================================
+
+export interface FileTaintAnalysis {
+  filePath: string
+  sources: UserInputSource[]
+  taintedVariables: TaintedVariable[]
+  taintPaths: TaintPath[]
+  sanitisers: SanitiserInfo[]
+}
+
+// ============================================================================
+// Context Engine Result (Unified Container)
+// ============================================================================
+
+import type { ProjectContext } from './project-context'
+import type { RouteMap } from './route-discovery/types'
+import type { ModuleGraph, ModuleGraphStats } from './module-graph'
+import type { CrossFileTaintPath } from './cross-file-taint'
+import type { FunctionProfileMap } from './function-classifier'
+import type { FileFrameworkAnalysis } from './framework-models/types'
+
+/**
+ * Unified output from all Context Engine phases.
+ * Single container consumed by both scoring and AI validation.
+ */
+export interface ContextEngineResult {
+  projectContext: ProjectContext
+  fileTaintAnalyses: Map<string, FileTaintAnalysis>
+  routeMap?: RouteMap                           // CE Phase 2: Route & Handler Discovery
+  // CE Phase 4: Cross-File Analysis
+  moduleGraph?: ModuleGraph
+  crossFileTaintPaths?: CrossFileTaintPath[]
+  functionProfiles?: FunctionProfileMap
+  frameworkAnalyses?: Map<string, FileFrameworkAnalysis>  // CE Phase 5: Framework-Aware Analysis
+}

package/src/{utils → model}/trpc-analyzer.ts

@@ -7,7 +7,7 @@
  * procedures - the backend already handles authorization.
  */
 
-import type { ScanFile } from '../types'
+import type { ScanFile } from '../shared/types'
 
 export interface TRPCMiddleware {
   /** Name of the middleware/procedure base */

package/src/{utils/context-helpers.ts → parse/file-classifier.ts}

@@ -448,6 +448,60 @@ export function isFileLoaderContext(filePath: string): boolean {
   return loaderPatterns.some(p => p.test(filePath))
 }
 
+// ============================================================================
+// Agent Skill File Detection
+// ============================================================================
+
+/**
+ * Check if file is an AI agent skill/configuration file
+ * These files define agent behavior and are targets for prompt injection,
+ * data exfiltration, and hidden execution attacks.
+ *
+ * Note: Root CLAUDE.md is NOT matched. Only .claude/commands/, .claude/skills/,
+ * .claude/tools/ subdirectories are flagged.
+ */
+export function isAgentSkillFile(filePath: string): boolean {
+  const skillPatterns = [
+    // Skill definition files
+    /\/SKILL\.md$/i,
+    /\/AGENTS\.md$/i,
+    /\/skills\.json$/i,
+    /\/skills\.ya?ml$/i,
+    /\/agent\.ya?ml$/i,
+    /\/agent\.config\./i,
+    /\/agent-skills\//i,
+    /\/tools\.json$/i,
+
+    // Cursor
+    /\/\.cursor\/rules\//i,
+    /\/\.cursorrules$/i,
+
+    // Claude (skill-specific paths, NOT root CLAUDE.md)
+    /\/\.claude\/commands\//i,
+    /\/\.claude\/skills\//i,
+    /\/\.claude\/tools\//i,
+
+    // GitHub Copilot
+    /\/\.github\/copilot-instructions\.md$/i,
+    /\/\.github\/agents\//i,
+
+    // Moltbot/OpenClaw
+    /\/\.moltbot\//i,
+    /\/moltbot\.config\./i,
+    /\/\.openclaw\//i,
+
+    // Aider
+    /\/\.aider/i,
+
+    // MCP configs (complements existing config-mcp-audit.ts)
+    /\/mcp\.json$/i,
+    /\/mcp-config\.json$/i,
+    /\/\.mcp\//i,
+    /\/claude[-_]desktop[-_]config\.json$/i,
+  ]
+  return skillPatterns.some(p => p.test(filePath))
+}
+
 // ============================================================================
 // Code Line Context Detection
 // ============================================================================

package/src/{utils → parse}/path-exclusions.ts

@@ -4,7 +4,7 @@
  * to reduce false positives in security scans.
  */
 
-import type { Vulnerability, VulnerabilityCategory } from '../types'
+import type { Vulnerability, VulnerabilityCategory } from '../shared/types'
 
 export interface ExclusionConfig {
   testPatterns: string[]

package/src/pipeline/config.ts

@@ -0,0 +1,81 @@
+/**
+ * Pipeline Configuration — Scan options and mode resolution.
+ *
+ * Handles both scan mode (full/incremental) and depth (local/verified/deep).
+ */
+
+import type {
+  ScanMode,
+  ScanModeConfig,
+  ScanDepth,
+  CancellationToken,
+  ProgressCallback,
+} from '../shared/types'
+import { SCAN_MODE_DEFAULTS } from '../shared/types'
+
+export interface ScanOptions {
+  /** Enable AI-powered validation and analysis */
+  enableAI?: boolean
+  /** Maximum files to scan */
+  maxFiles?: number
+  /** Branch being scanned */
+  branch?: string
+  /** Scan mode configuration (full vs incremental) */
+  scanMode?: ScanMode | ScanModeConfig
+  /** Scan depth (cheap/validated/deep) - controls AI usage */
+  scanDepth?: ScanDepth
+  /** Suppress console.log output (for interactive CLI mode) */
+  quiet?: boolean
+  /** Cancellation token for aborting scans gracefully */
+  cancellationToken?: CancellationToken
+  /** Project path for loading suppression config (defaults to cwd) */
+  projectPath?: string
+  /** Include suppressed findings in output (for --show-suppressed) */
+  showSuppressed?: boolean
+  /** Include filter audit trail in output (for debugging/explaining dismissals) */
+  includeFilterAudit?: boolean
+}
+
+/**
+ * Resolve scan mode configuration from options
+ *
+ * Handles both scan mode (full/incremental) and depth (local/verified/deep).
+ * Depth controls AI usage:
+ * - local: skip AI validation + skip Layer 3
+ * - verified: run AI validation, skip Layer 3
+ * - deep: run AI validation + Layer 3
+ */
+export function resolveScanModeConfig(options: ScanOptions): ScanModeConfig {
+  const scanModeOption = options.scanMode
+
+  // Determine base mode
+  const mode: ScanMode = !scanModeOption ? 'full'
+    : typeof scanModeOption === 'string' ? scanModeOption
+    : scanModeOption.mode
+
+  const defaults = SCAN_MODE_DEFAULTS[mode]
+
+  // Build config from defaults + explicit overrides
+  let config: ScanModeConfig = {
+    ...defaults,
+    mode,
+    ...(typeof scanModeOption === 'object' ? scanModeOption : {}),
+  }
+
+  // Apply depth mode (default: 'local')
+  const depth = options.scanDepth ?? 'local'
+  config.scanDepth = depth
+
+  // Map depth to skipAIValidation/skipLayer3 unless explicitly overridden
+  const hasExplicitSkipAI = typeof scanModeOption === 'object' && scanModeOption.skipAIValidation !== undefined
+  const hasExplicitSkipL3 = typeof scanModeOption === 'object' && scanModeOption.skipLayer3 !== undefined
+
+  if (!hasExplicitSkipAI) {
+    config.skipAIValidation = depth === 'local'
+  }
+  if (!hasExplicitSkipL3) {
+    config.skipLayer3 = depth !== 'deep'
+  }
+
+  return config
+}