@oculum/scanner 1.0.11 → 1.0.13

package/src/{utils → model}/auth-helper-detector.ts

@@ -8,7 +8,7 @@
  * an authenticated user - no additional `if (!userId)` checks are needed.
  */
 
-import type { ScanFile } from '../types'
+import type { ScanFile } from '../shared/types'
 
 // ============================================================================
 // Types

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

@@ -0,0 +1,374 @@
+/**
+ * Cross-File Taint Analysis — Detects taint flows that cross file boundaries.
+ *
+ * Scenario 1: Source in file A, sink in imported function (file B).
+ *   File A has req.params.id (tainted), calls getUser(id) imported from B.
+ *   B's getUser has param 'id' reaching a sql_query sink.
+ *
+ * Scenario 2: Imported function returns user data.
+ *   File A calls getUserInput() from B which returns req.body.
+ *   File A then passes the return value to a local sink.
+ *
+ * Constraint: One level of imports only. No transitive chasing (A->B->C).
+ */
+
+import type { ScanFile } from '../shared/types'
+import type { ModuleGraph } from './module-graph'
+import type { FunctionProfileMap, ExportedFunctionProfile } from './function-classifier'
+import type {
+  FileTaintAnalysis,
+  UserInputSource,
+  TaintSink,
+  SinkType,
+} from './taint-types'
+import { SINK_PATTERNS, escapeRegex } from './sink-patterns'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CrossFileTaintPath {
+  sourceFile: string
+  source: UserInputSource
+  sinkFile: string
+  sink: TaintSink
+  importLink: {
+    fromFile: string
+    toFile: string
+    symbolName: string
+    paramName?: string
+    callLine: number
+  }
+  sanitised: boolean
+  confidence: 'high' | 'medium' | 'low'
+}
+
+// ============================================================================
+// Main Analysis
+// ============================================================================
+
+/**
+ * Analyze cross-file taint paths across the project.
+ *
+ * For each file with taint sources, check if tainted variables flow into
+ * calls to imported functions that reach dangerous sinks.
+ */
+export function analyzeCrossFileTaint(
+  files: ScanFile[],
+  graph: ModuleGraph,
+  functionProfiles: FunctionProfileMap,
+  fileTaintAnalyses: Map<string, FileTaintAnalysis>
+): CrossFileTaintPath[] {
+  const paths: CrossFileTaintPath[] = []
+  const fileContentMap = new Map(files.map(f => [f.path, f.content]))
+
+  for (const [filePath, analysis] of fileTaintAnalyses) {
+    if (analysis.sources.length === 0) continue
+
+    const node = graph.nodes.get(filePath)
+    if (!node) continue
+
+    // Skip files involved in circular imports (unsafe to analyze)
+    if (graph.circularImports.has(filePath)) continue
+
+    const content = fileContentMap.get(filePath)
+    if (!content) continue
+
+    // Scenario 1: Source in file A, sink in imported function (file B)
+    const scenario1Paths = analyzeScenario1(
+      filePath,
+      content,
+      analysis,
+      node,
+      graph,
+      functionProfiles
+    )
+    paths.push(...scenario1Paths)
+
+    // Scenario 2: Imported function returns user data, used in local sink
+    const scenario2Paths = analyzeScenario2(
+      filePath,
+      content,
+      analysis,
+      node,
+      graph,
+      functionProfiles
+    )
+    paths.push(...scenario2Paths)
+  }
+
+  return paths
+}
+
+// ============================================================================
+// Scenario 1: Source in A, sink in imported function B
+// ============================================================================
+
+function analyzeScenario1(
+  filePath: string,
+  content: string,
+  analysis: FileTaintAnalysis,
+  node: ReturnType<ModuleGraph['nodes']['get']> & {},
+  graph: ModuleGraph,
+  functionProfiles: FunctionProfileMap
+): CrossFileTaintPath[] {
+  const paths: CrossFileTaintPath[] = []
+  const lines = content.split('\n')
+
+  // Build a map of imported function names → their profiles
+  const importedFunctions = new Map<string, { profile: ExportedFunctionProfile; importPath: string }>()
+
+  for (const imp of node.imports) {
+    if (!imp.resolvedPath) continue
+    const profiles = functionProfiles.get(imp.resolvedPath)
+    if (!profiles) continue
+
+    for (const name of imp.importedNames) {
+      if (name === 'default') continue
+      const profile = profiles.find(p => p.name === name)
+      if (profile && profile.reachesSinks.length > 0) {
+        importedFunctions.set(name, { profile, importPath: imp.resolvedPath })
+      }
+    }
+  }
+
+  if (importedFunctions.size === 0) return paths
+
+  // Get tainted variable names and their sources
+  const taintedVarNames = new Map<string, UserInputSource>()
+  for (const src of analysis.sources) {
+    taintedVarNames.set(src.variable, src)
+  }
+  for (const tv of analysis.taintedVariables) {
+    if (!tv.sanitised) {
+      taintedVarNames.set(tv.name, tv.source)
+    }
+  }
+
+  // Pre-compile call patterns for imported functions (avoid per-line RegExp construction)
+  const compiledCallPatterns = new Map<string, RegExp>()
+  for (const funcName of importedFunctions.keys()) {
+    compiledCallPatterns.set(funcName, new RegExp(`\\b${escapeRegex(funcName)}\\s*\\(`))
+  }
+
+  // Pre-compile var patterns for tainted variables
+  const compiledVarPatterns = new Map<string, RegExp>()
+  for (const varName of taintedVarNames.keys()) {
+    compiledVarPatterns.set(varName, new RegExp(`\\b${escapeRegex(varName)}\\b`))
+  }
+
+  // Scan for calls to imported functions with tainted arguments
+  const seen = new Set<string>()
+
+  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
+
+    for (const [funcName, { profile, importPath }] of importedFunctions) {
+      // Check if this line calls the imported function
+      if (!compiledCallPatterns.get(funcName)!.test(line)) continue
+
+      // Extract call arguments
+      const args = extractCallArguments(line, funcName)
+
+      // Check if any tainted variable is passed as an argument
+      for (const arg of args) {
+        const argTrimmed = arg.trim()
+
+        // Check if this argument is a tainted variable
+        for (const [varName, source] of taintedVarNames) {
+          if (!compiledVarPatterns.get(varName)!.test(argTrimmed)) continue
+
+          // Check if the corresponding param is dangerous
+          const argIndex = args.indexOf(arg)
+          const paramName = profile.paramNames[argIndex]
+          const isDangerousParam = paramName
+            ? profile.dangerousParams.includes(paramName)
+            : profile.paramNames.length === 0 && profile.dangerousParams.length > 0
+
+          if (!isDangerousParam && profile.dangerousParams.length > 0) continue
+
+          // Build cross-file taint path
+          const key = `${filePath}:${source.variable}:${importPath}:${funcName}:${lineNumber}`
+          if (seen.has(key)) continue
+          seen.add(key)
+
+          const sinkType: SinkType = profile.reachesSinks[0]
+          paths.push({
+            sourceFile: filePath,
+            source,
+            sinkFile: profile.filePath,
+            sink: {
+              line: profile.line,
+              expression: `${funcName}(...)`,
+              sinkType,
+            },
+            importLink: {
+              fromFile: filePath,
+              toFile: importPath,
+              symbolName: funcName,
+              paramName,
+              callLine: lineNumber,
+            },
+            sanitised: profile.hasSanitisation,
+            confidence: 'medium',  // cross-file paths are medium confidence by default
+          })
+        }
+      }
+    }
+  }
+
+  return paths
+}
+
+// ============================================================================
+// Scenario 2: Imported function returns user data, used in local sink
+// ============================================================================
+
+function analyzeScenario2(
+  filePath: string,
+  content: string,
+  _analysis: FileTaintAnalysis,
+  node: ReturnType<ModuleGraph['nodes']['get']> & {},
+  _graph: ModuleGraph,
+  functionProfiles: FunctionProfileMap
+): CrossFileTaintPath[] {
+  const paths: CrossFileTaintPath[] = []
+  const lines = content.split('\n')
+
+  // Find imported functions that return user data
+  const userDataFunctions = new Map<string, { profile: ExportedFunctionProfile; importPath: string }>()
+
+  for (const imp of node.imports) {
+    if (!imp.resolvedPath) continue
+    const profiles = functionProfiles.get(imp.resolvedPath)
+    if (!profiles) continue
+
+    for (const name of imp.importedNames) {
+      if (name === 'default') continue
+      const profile = profiles.find(p => p.name === name)
+      if (profile && profile.returnsUserData) {
+        userDataFunctions.set(name, { profile, importPath: imp.resolvedPath })
+      }
+    }
+  }
+
+  if (userDataFunctions.size === 0) return paths
+
+  // Pre-compile assignment patterns for user-data functions
+  const compiledAssignPatterns = new Map<string, RegExp>()
+  for (const funcName of userDataFunctions.keys()) {
+    compiledAssignPatterns.set(funcName, new RegExp(`(?:const|let|var)\\s+(\\w+)\\s*=\\s*(?:await\\s+)?${escapeRegex(funcName)}\\s*\\(`))
+  }
+
+  // Track variables assigned from user-data-returning functions
+  const taintedByImport = new Map<string, { source: ExportedFunctionProfile; callLine: number; importPath: string; funcName: string }>()
+  // Cache compiled var patterns for tainted-by-import variables (grows as new vars are discovered)
+  const compiledImportVarPatterns = new Map<string, RegExp>()
+
+  const seen = new Set<string>()
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const lineNumber = i + 1
+    const trimmed = line.trim()
+
+    if (trimmed.startsWith('//') || trimmed.startsWith('*')) continue
+
+    // Check for assignments from user-data functions
+    for (const [funcName, { profile, importPath }] of userDataFunctions) {
+      const assignMatch = line.match(compiledAssignPatterns.get(funcName)!)
+      if (assignMatch) {
+        const varName = assignMatch[1]
+        taintedByImport.set(varName, { source: profile, callLine: lineNumber, importPath, funcName })
+        // Pre-compile pattern for newly discovered tainted variable
+        if (!compiledImportVarPatterns.has(varName)) {
+          compiledImportVarPatterns.set(varName, new RegExp(`\\b${escapeRegex(varName)}\\b`))
+        }
+      }
+    }
+
+    // Check if any tainted-by-import variable reaches a local sink
+    for (const sp of SINK_PATTERNS) {
+      if (!sp.pattern.test(line)) continue
+
+      for (const [varName, info] of taintedByImport) {
+        if (!compiledImportVarPatterns.get(varName)!.test(line)) continue
+
+        const key = `${filePath}:${varName}:${info.importPath}:${info.funcName}:${lineNumber}`
+        if (seen.has(key)) continue
+        seen.add(key)
+
+        paths.push({
+          sourceFile: info.importPath,
+          source: {
+            line: info.source.line,
+            expression: `${info.funcName}() return value`,
+            variable: varName,
+            sourceType: info.source.returnSourceType ?? 'http_body',
+            confidence: 'medium',
+          },
+          sinkFile: filePath,
+          sink: {
+            line: lineNumber,
+            expression: trimmed,
+            sinkType: sp.sinkType,
+          },
+          importLink: {
+            fromFile: filePath,
+            toFile: info.importPath,
+            symbolName: info.funcName,
+            callLine: info.callLine,
+          },
+          sanitised: false,
+          confidence: 'low',  // scenario 2 is lower confidence
+        })
+      }
+    }
+  }
+
+  return paths
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function extractCallArguments(line: string, funcName: string): string[] {
+  const startIdx = line.indexOf(funcName)
+  if (startIdx === -1) return []
+
+  const parenStart = line.indexOf('(', startIdx + funcName.length)
+  if (parenStart === -1) return []
+
+  let depth = 0
+  let current = ''
+  const args: string[] = []
+
+  for (let i = parenStart; i < line.length; i++) {
+    const ch = line[i]
+    if (ch === '(') {
+      if (depth > 0) current += ch
+      depth++
+    } else if (ch === ')') {
+      depth--
+      if (depth === 0) {
+        if (current.trim()) args.push(current.trim())
+        break
+      }
+      current += ch
+    } else if (ch === ',' && depth === 1) {
+      if (current.trim()) args.push(current.trim())
+      current = ''
+    } else if (depth > 0) {
+      current += ch
+    }
+  }
+
+  return args
+}
+

package/src/model/framework-models/django.ts

@@ -0,0 +1,82 @@
+/**
+ * Django Framework Security Model
+ *
+ * Django ORM queries are parameterised by default. Templates auto-escape.
+ * |safe filter, .extra(), .raw(), mark_safe() bypass protections.
+ */
+
+import type { FrameworkSecurityModel } from './types'
+
+// Safe ORM patterns
+const ORM_FILTER_RE = /\.objects\.(filter|get|exclude|create|update|values|annotate|aggregate|count|exists)\s*\(/
+const ORM_QUERYSET_RE = /\.(select_related|prefetch_related|order_by|distinct|first|last|earliest|latest)\s*\(/
+
+// Unsafe patterns
+const SAFE_FILTER_RE = /\|\s*safe\b/
+const EXTRA_RE = /\.extra\s*\(/
+const RAW_RE = /\.raw\s*\(/
+const CURSOR_EXECUTE_RE = /cursor\s*\(\s*\)\s*\.execute\s*\(/
+const MARK_SAFE_RE = /mark_safe\s*\(/
+
+export const djangoModel: FrameworkSecurityModel = {
+  framework: 'django',
+
+  safePatterns: [
+    {
+      id: 'orm_django_parameterised',
+      suppressesCategory: ['sql_injection', 'dangerous_function'],
+      detect: (line: string, filePath: string, _fileContent: string) => {
+        if (!/\.py$/.test(filePath)) return false
+        return ORM_FILTER_RE.test(line) || ORM_QUERYSET_RE.test(line)
+      },
+      reason: 'Django ORM parameterises queries by default — SQL injection not applicable',
+    },
+    {
+      id: 'django_template_auto_escape',
+      suppressesCategory: ['xss'],
+      detect: (line: string, filePath: string, _fileContent: string) => {
+        // Django templates auto-escape by default
+        if (!/\.html$/.test(filePath)) return false
+        // Template variable interpolation
+        return /\{\{.*\}\}/.test(line) && !SAFE_FILTER_RE.test(line)
+      },
+      reason: 'Django templates auto-escape variables by default — XSS not applicable',
+    },
+  ],
+
+  unsafePatterns: [
+    {
+      id: 'django_safe_filter',
+      boostsCategory: ['xss'],
+      detect: (line: string, filePath: string, _fileContent: string) => {
+        if (!/\.html$/.test(filePath)) return false
+        return SAFE_FILTER_RE.test(line)
+      },
+      reason: 'Django |safe filter bypasses template auto-escaping — XSS risk',
+    },
+    {
+      id: 'django_extra_raw_sql',
+      boostsCategory: ['sql_injection'],
+      detect: (line: string, _filePath: string, _fileContent: string) => EXTRA_RE.test(line),
+      reason: 'Django .extra() accepts raw SQL — SQL injection risk',
+    },
+    {
+      id: 'django_raw_query',
+      boostsCategory: ['sql_injection'],
+      detect: (line: string, _filePath: string, _fileContent: string) => RAW_RE.test(line),
+      reason: 'Django .raw() executes raw SQL — SQL injection risk',
+    },
+    {
+      id: 'django_cursor_execute',
+      boostsCategory: ['sql_injection'],
+      detect: (line: string, _filePath: string, _fileContent: string) => CURSOR_EXECUTE_RE.test(line),
+      reason: 'Django connection.cursor().execute() is raw SQL — SQL injection risk',
+    },
+    {
+      id: 'django_mark_safe',
+      boostsCategory: ['xss'],
+      detect: (line: string, _filePath: string, _fileContent: string) => MARK_SAFE_RE.test(line),
+      reason: 'mark_safe() bypasses Django template auto-escaping — XSS risk',
+    },
+  ],
+}

package/src/model/framework-models/express.ts

@@ -0,0 +1,54 @@
+/**
+ * Express Framework Security Model
+ *
+ * res.json() auto-serialises (no XSS in JSON). Helmet adds security headers.
+ * Template literals in res.send() with user data are XSS risks.
+ */
+
+import type { FrameworkSecurityModel } from './types'
+
+const RES_JSON_RE = /res\.json\s*\(/
+const RES_SEND_TEMPLATE_RE = /res\.send\s*\(\s*`/
+const RES_SEND_CONCAT_RE = /res\.send\s*\([^)]*\+/
+const RES_END_TEMPLATE_RE = /res\.end\s*\(\s*`/
+const HELMET_RE = /helmet\s*\(/
+
+export const expressModel: FrameworkSecurityModel = {
+  framework: 'express',
+
+  safePatterns: [
+    {
+      id: 'express_res_json_safe',
+      suppressesCategory: ['xss'],
+      detect: (line: string, _filePath: string, _fileContent: string) => RES_JSON_RE.test(line),
+      reason: 'Express res.json() auto-serialises to JSON — no XSS risk in JSON responses',
+    },
+    {
+      id: 'express_helmet_headers',
+      suppressesCategory: ['insecure_config', 'cors_misconfiguration'],
+      detect: (line: string, _filePath: string, _fileContent: string) => HELMET_RE.test(line),
+      reason: 'Helmet middleware sets security headers by default',
+    },
+  ],
+
+  unsafePatterns: [
+    {
+      id: 'express_res_send_template',
+      boostsCategory: ['xss'],
+      detect: (line: string, _filePath: string, _fileContent: string) => RES_SEND_TEMPLATE_RE.test(line),
+      reason: 'Template literal in res.send() may include user data — XSS risk',
+    },
+    {
+      id: 'express_res_send_concat',
+      boostsCategory: ['xss'],
+      detect: (line: string, _filePath: string, _fileContent: string) => RES_SEND_CONCAT_RE.test(line),
+      reason: 'String concatenation in res.send() may include user data — XSS risk',
+    },
+    {
+      id: 'express_res_end_template',
+      boostsCategory: ['xss'],
+      detect: (line: string, _filePath: string, _fileContent: string) => RES_END_TEMPLATE_RE.test(line),
+      reason: 'Template literal in res.end() may include user data — XSS risk',
+    },
+  ],
+}

package/src/model/framework-models/index.ts

@@ -0,0 +1,116 @@
+/**
+ * Framework Analysis Orchestrator
+ *
+ * Runs applicable framework security models against each file,
+ * returning per-file framework analysis results (safe/unsafe line annotations).
+ */
+
+import type { ScanFile } from '../../shared/types'
+import type { ProjectContext } from '../project-context'
+import type { FrameworkSecurityModel, FileFrameworkAnalysis, FrameworkSafePattern, FrameworkUnsafePattern } from './types'
+import { reactModel } from './react'
+import { nextjsModel } from './nextjs'
+import { expressModel } from './express'
+import { djangoModel } from './django'
+import { sequelizeModel } from './sequelize'
+import { prismaModel } from './prisma'
+
+/**
+ * Select applicable framework models based on project context.
+ */
+function selectModels(projectContext: ProjectContext): FrameworkSecurityModel[] {
+  const models: FrameworkSecurityModel[] = []
+
+  if (projectContext.frameworks.frontend === 'react') {
+    models.push(reactModel)
+  }
+  if (projectContext.frameworks.primary === 'nextjs') {
+    models.push(nextjsModel)
+    // Next.js uses React — ensure React model is included
+    if (!models.some(m => m.framework === 'react')) {
+      models.push(reactModel)
+    }
+  }
+  if (projectContext.frameworks.primary === 'express') {
+    models.push(expressModel)
+  }
+  if (projectContext.frameworks.primary === 'django') {
+    models.push(djangoModel)
+  }
+
+  // ORM-specific models
+  if (projectContext.dataAccess.orm === 'sequelize') {
+    models.push(sequelizeModel)
+  }
+  if (projectContext.dataAccess.orm === 'prisma') {
+    models.push(prismaModel)
+  }
+
+  return models
+}
+
+/**
+ * Analyze framework patterns across all files.
+ *
+ * For each file, runs all applicable framework models against each line.
+ * Returns a Map of file path → FileFrameworkAnalysis.
+ *
+ * Only files with at least one match are included in the result.
+ */
+export function analyzeFrameworkPatterns(
+  files: ScanFile[],
+  projectContext: ProjectContext
+): Map<string, FileFrameworkAnalysis> {
+  const models = selectModels(projectContext)
+  if (models.length === 0) return new Map()
+
+  const results = new Map<string, FileFrameworkAnalysis>()
+
+  for (const file of files) {
+    const safeLines = new Map<number, FrameworkSafePattern[]>()
+    const unsafeLines = new Map<number, FrameworkUnsafePattern[]>()
+    const lines = file.content.split('\n')
+
+    for (let i = 0; i < lines.length; i++) {
+      const lineContent = lines[i]
+      const lineNumber = i + 1
+
+      for (const model of models) {
+        for (const safe of model.safePatterns) {
+          if (safe.detect(lineContent, file.path, file.content)) {
+            const existing = safeLines.get(lineNumber)
+            if (existing) {
+              // Avoid duplicate IDs on the same line
+              if (!existing.some(p => p.id === safe.id)) {
+                existing.push(safe)
+              }
+            } else {
+              safeLines.set(lineNumber, [safe])
+            }
+          }
+        }
+        for (const unsafe of model.unsafePatterns) {
+          if (unsafe.detect(lineContent, file.path, file.content)) {
+            const existing = unsafeLines.get(lineNumber)
+            if (existing) {
+              if (!existing.some(p => p.id === unsafe.id)) {
+                existing.push(unsafe)
+              }
+            } else {
+              unsafeLines.set(lineNumber, [unsafe])
+            }
+          }
+        }
+      }
+    }
+
+    if (safeLines.size > 0 || unsafeLines.size > 0) {
+      results.set(file.path, { safeLines, unsafeLines })
+    }
+  }
+
+  return results
+}
+
+// Re-export types
+export type { FrameworkSecurityModel, FrameworkSafePattern, FrameworkUnsafePattern, FileFrameworkAnalysis } from './types'