@oculum/scanner 1.0.14 → 1.0.15

package/src/taint/framework-models.ts

@@ -0,0 +1,313 @@
+/**
+ * Framework Models — Middleware Chain & Route Handler Detection
+ *
+ * Models framework-specific request lifecycles as taint propagation context:
+ *
+ * 1. Express middleware chains: `app.use(middleware)` → `app.get('/path', handler)`
+ *    Detects middleware registration order and models that middleware-modified
+ *    `req` properties carry taint to downstream handlers.
+ *
+ * 2. Express route handler resolution: Identifies `app.get('/users', handler)`
+ *    where `handler` may be an imported function, enabling cross-file taint
+ *    tracking through the cross-file index.
+ *
+ * 3. Next.js Server Actions: Detects 'use server' functions that receive
+ *    form data as tainted input.
+ *
+ * Integration: Called from the project-level taint orchestrator to generate
+ * additional synthetic taint sources beyond what the source classifier finds.
+ */
+
+import type Parser from 'tree-sitter'
+import type { ParsedAST } from '../parse/ast'
+import { walkAST } from '../parse/ast'
+import type { TaintSource, TaintKind } from './types'
+import { ALL_TAINT_KINDS } from './types'
+import { collectImportBindings } from './helpers'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface MiddlewareRegistration {
+  filePath: string
+  /** The app/router object (e.g., 'app', 'router') */
+  appObject: string
+  /** The middleware function name or reference */
+  middlewareName: string
+  /** The mount path (e.g., '/api', '/') */
+  mountPath: string | null
+  /** AST node of the registration call */
+  node: Parser.SyntaxNode
+  /** Line number */
+  line: number
+}
+
+export interface RouteRegistration {
+  filePath: string
+  /** HTTP method (get, post, put, delete, all, use) */
+  method: string
+  /** Route path */
+  path: string | null
+  /** Handler function name(s) */
+  handlerNames: string[]
+  /** AST node */
+  node: Parser.SyntaxNode
+  line: number
+}
+
+// ============================================================================
+// Express Middleware & Route Detection
+// ============================================================================
+
+const EXPRESS_METHODS = /^(get|post|put|patch|delete|all|use|options|head)$/
+const ROUTER_OBJECTS = /^(app|router|server|api|route)$/i
+
+/**
+ * Detect Express-style middleware and route registrations in a file.
+ */
+export function detectExpressRoutes(
+  ast: ParsedAST,
+  filePath: string,
+): { middleware: MiddlewareRegistration[], routes: RouteRegistration[] } {
+  const middleware: MiddlewareRegistration[] = []
+  const routes: RouteRegistration[] = []
+  const root = ast.tree.rootNode
+
+  walkAST(root, (node) => {
+    if (node.type !== 'call_expression') return false
+
+    const fnNode = node.childForFieldName('function')
+    if (!fnNode || fnNode.type !== 'member_expression') return false
+
+    const obj = fnNode.childForFieldName('object')
+    const prop = fnNode.childForFieldName('property')
+    if (!obj || !prop) return false
+    if (!ROUTER_OBJECTS.test(obj.text) || !EXPRESS_METHODS.test(prop.text)) return false
+
+    const argsNode = node.childForFieldName('arguments')
+    if (!argsNode) return false
+    const args = argsNode.namedChildren
+
+    if (args.length === 0) return false
+
+    const method = prop.text
+
+    // Determine if first arg is a path string
+    let routePath: string | null = null
+    let handlerStartIdx = 0
+
+    if (args[0].type === 'string' || args[0].type === 'template_string') {
+      routePath = args[0].text.replace(/^['"`]|['"`]$/g, '')
+      handlerStartIdx = 1
+    }
+
+    // app.use() with only function args is middleware registration
+    if (method === 'use') {
+      for (let i = handlerStartIdx; i < args.length; i++) {
+        const handlerName = extractHandlerName(args[i])
+        if (handlerName) {
+          middleware.push({
+            filePath,
+            appObject: obj.text,
+            middlewareName: handlerName,
+            mountPath: routePath,
+            node,
+            line: node.startPosition.row + 1,
+          })
+        }
+      }
+      return false
+    }
+
+    // Route handler registration
+    const handlerNames: string[] = []
+    for (let i = handlerStartIdx; i < args.length; i++) {
+      const name = extractHandlerName(args[i])
+      if (name) handlerNames.push(name)
+    }
+
+    if (handlerNames.length > 0) {
+      routes.push({
+        filePath,
+        method,
+        path: routePath,
+        handlerNames,
+        node,
+        line: node.startPosition.row + 1,
+      })
+    }
+
+    return false
+  })
+
+  return { middleware, routes }
+}
+
+// ============================================================================
+// Next.js Server Actions
+// ============================================================================
+
+/**
+ * Detect Next.js Server Actions ('use server' directive) and generate
+ * synthetic taint sources for their form data parameters.
+ *
+ * Server Actions receive form data from the client as their first argument
+ * (when called from <form action={myAction}>). The FormData parameter is
+ * a taint source with all taint kinds.
+ */
+export function detectServerActions(
+  ast: ParsedAST,
+  filePath: string,
+): TaintSource[] {
+  const sources: TaintSource[] = []
+  const root = ast.tree.rootNode
+
+  // Check for file-level 'use server' directive
+  const hasFileDirective = hasDirective(root, 'use server')
+
+  walkAST(root, (node) => {
+    const fnTypes = new Set([
+      'function_declaration', 'arrow_function', 'function_expression',
+    ])
+    if (!fnTypes.has(node.type)) return false
+
+    // Check for function-level 'use server' directive
+    const isServerAction = hasFileDirective || hasFunctionDirective(node, 'use server')
+    if (!isServerAction) return false
+
+    // Get parameters — first param of server action is FormData
+    const params = node.childForFieldName('parameters')
+    if (!params) return false
+
+    for (const param of params.namedChildren) {
+      const paramName = extractActionParamName(param)
+      if (!paramName) continue
+
+      sources.push({
+        node: param,
+        line: param.startPosition.row + 1,
+        variable: paramName,
+        expression: `Server Action param: ${paramName}`,
+        sourceType: 'form_data',
+        taintKinds: new Set(ALL_TAINT_KINDS),
+        confidence: 'high',
+        framework: 'nextjs',
+      })
+    }
+
+    return true // don't descend into function body
+  })
+
+  return sources
+}
+
+// ============================================================================
+// Synthetic Source Generation for Route Handlers
+// ============================================================================
+
+/**
+ * Generate synthetic taint sources for route handler parameters.
+ *
+ * When a route handler is registered with `app.get('/users', handler)`,
+ * the `handler`'s `req` and `res` parameters are taint sources.
+ * The source classifier already handles this for inline handlers,
+ * but for imported handlers we need synthetic sources.
+ *
+ * This function generates sources for route handler parameters that
+ * are identifiers (imported or local function references), which the
+ * cross-file index can resolve.
+ */
+export function generateRouteHandlerSources(
+  routes: RouteRegistration[],
+  ast: ParsedAST,
+  filePath: string,
+): TaintSource[] {
+  const sources: TaintSource[] = []
+  const root = ast.tree.rootNode
+  const imports = collectImportBindings(root)
+
+  for (const route of routes) {
+    for (const handlerName of route.handlerNames) {
+      // Check if this is an imported handler
+      const binding = imports.get(handlerName)
+      if (!binding) continue
+
+      // The handler's first parameter (req) is a taint source
+      // We create a synthetic source that will be picked up by the
+      // cross-file analyzer when resolving the handler function
+      sources.push({
+        node: route.node,
+        line: route.line,
+        variable: `${handlerName}.req`,
+        expression: `${route.method.toUpperCase()} ${route.path ?? '/'} → ${handlerName}`,
+        sourceType: 'http_body',
+        taintKinds: new Set(ALL_TAINT_KINDS),
+        confidence: 'high',
+        framework: 'express',
+      })
+    }
+  }
+
+  return sources
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function extractHandlerName(node: Parser.SyntaxNode): string | null {
+  if (node.type === 'identifier') return node.text
+  if (node.type === 'member_expression') return node.text
+  // Inline arrow/function: can't name it, skip
+  return null
+}
+
+function extractActionParamName(param: Parser.SyntaxNode): string | null {
+  if (param.type === 'identifier') return param.text
+  if (param.type === 'required_parameter' || param.type === 'optional_parameter') {
+    const pattern = param.childForFieldName('pattern')
+    if (pattern?.type === 'identifier') return pattern.text
+  }
+  return null
+}
+
+/**
+ * Check if the file has a top-level 'use server' / 'use client' directive.
+ */
+function hasDirective(root: Parser.SyntaxNode, directive: string): boolean {
+  for (const child of root.children) {
+    if (child.type === 'expression_statement') {
+      const expr = child.namedChildren[0]
+      if (expr?.type === 'string') {
+        const text = expr.text.replace(/^['"`]|['"`]$/g, '')
+        if (text === directive) return true
+      }
+    }
+    // Directives must appear before any other statement
+    if (child.type !== 'expression_statement' && child.type !== 'comment') break
+  }
+  return false
+}
+
+/**
+ * Check if a function body starts with a 'use server' directive.
+ */
+function hasFunctionDirective(fnNode: Parser.SyntaxNode, directive: string): boolean {
+  const body = fnNode.childForFieldName('body')
+  if (!body || body.type !== 'statement_block') return false
+
+  // Use namedChildren to skip punctuation tokens ({ and })
+  for (const child of body.namedChildren) {
+    if (child.type === 'expression_statement') {
+      const expr = child.namedChildren[0]
+      if (expr?.type === 'string') {
+        const text = expr.text.replace(/^['"`]|['"`]$/g, '')
+        if (text === directive) return true
+      }
+    }
+    // Directives must appear before any other statement
+    if (child.type !== 'expression_statement' && child.type !== 'comment') break
+  }
+  return false
+}

package/src/taint/helpers.ts

@@ -0,0 +1,138 @@
+/**
+ * Taint Engine Helpers
+ *
+ * Standalone helpers for taint classifiers. These are intentionally duplicated
+ * from detect/ast-rules/index.ts to avoid importing the AST rule engine module,
+ * which causes tree-sitter native GC issues when running taint tests in Jest.
+ */
+
+import type Parser from 'tree-sitter'
+import { walkAST } from '../parse/ast'
+import { collectPythonImportBindings } from '../detect/ast-rules/helpers/python-helpers'
+
+/**
+ * Check if a set of call arguments represents a parameterized query (safe binding).
+ * Returns true if the first argument contains SQL placeholders ($1, $name, ?, :param, @param)
+ * and the second argument is an array or object with bind values.
+ *
+ * This is the single source of truth for parameterized query detection,
+ * used by both sink-classifier and sanitizer-registry.
+ */
+export function isParameterizedQueryArgs(args: Parser.SyntaxNode[]): boolean {
+  if (args.length < 2) return false
+
+  const firstArg = args[0]
+  if (firstArg.type !== 'string' && firstArg.type !== 'template_string') return false
+
+  const text = firstArg.text
+  // Check for placeholder patterns: $1, $name, ?, :paramName, @paramName
+  // Note: \? is safe here because we already verified the first arg is a
+  // string/template_string, and the second arg must be an array/object bind.
+  const hasPlaceholders = /\$\w+/.test(text) || /\?/.test(text) ||
+                          /:\w+/.test(text) || /@\w+/.test(text)
+  if (!hasPlaceholders) return false
+
+  const secondArg = args[1]
+  // Array of values: [val1, val2]
+  if (secondArg?.type === 'array') return true
+  // Object with bind/replacements: { bind: [...], replacements: {...} }
+  if (secondArg?.type === 'object') {
+    const props = secondArg.namedChildren
+    for (const prop of props) {
+      if (prop.type === 'pair') {
+        const key = prop.childForFieldName('key')
+        if (key && /^(bind|replacements|values|params)$/.test(key.text)) return true
+      }
+    }
+    // Even without explicit bind/replacements, object as 2nd arg with placeholders is usually safe
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Collect import bindings from a file's AST root.
+ *
+ * Returns a map: local binding name → { module, originalName }
+ * Handles both ES imports and CJS require().
+ *
+ * NOTE: This is a standalone copy of the function in detect/ast-rules/index.ts
+ * to keep the taint module tree independent of the detection module tree.
+ */
+export function collectImportBindings(
+  root: Parser.SyntaxNode
+): Map<string, { module: string; originalName: string }> {
+  // Python module root type is 'module', not 'program'
+  if (root.type === 'module') {
+    return collectPythonImportBindings(root)
+  }
+
+  const bindings = new Map<string, { module: string; originalName: string }>()
+
+  walkAST(root, (node) => {
+    // ES import
+    if (node.type === 'import_statement') {
+      const source = node.childForFieldName('source')
+      const moduleName = source?.text.replace(/^['"]|['"]$/g, '') ?? ''
+
+      // Find the import clause (might be a field or a direct child depending on grammar)
+      const clause = node.childForFieldName('import')
+        ?? node.children.find(c => c.type === 'import_clause')
+
+      if (clause) {
+        // import { a, b as c } from 'mod'
+        const namedImports = clause.descendantsOfType('import_specifier')
+        for (const spec of namedImports) {
+          const nameNode = spec.childForFieldName('name')
+          const aliasNode = spec.childForFieldName('alias')
+          const original = nameNode?.text ?? ''
+          const local = aliasNode?.text ?? original
+          bindings.set(local, { module: moduleName, originalName: original })
+        }
+        // import foo from 'mod' (default)
+        const defaultImport = clause.descendantsOfType('identifier')
+        if (defaultImport.length === 1 && namedImports.length === 0) {
+          bindings.set(defaultImport[0].text, { module: moduleName, originalName: 'default' })
+        }
+      }
+      return true // skip subtree
+    }
+
+    // CJS require: const { foo } = require('mod')
+    if (node.type === 'lexical_declaration' || node.type === 'variable_declaration') {
+      for (const declarator of node.descendantsOfType('variable_declarator')) {
+        const init = declarator.childForFieldName('value')
+        if (
+          init?.type === 'call_expression' &&
+          init.childForFieldName('function')?.text === 'require'
+        ) {
+          const args = init.childForFieldName('arguments')
+          const firstArg = args?.namedChildren[0]
+          const moduleName = firstArg?.text.replace(/^['"]|['"]$/g, '') ?? ''
+
+          const nameNode = declarator.childForFieldName('name')
+          if (nameNode?.type === 'object_pattern') {
+            // const { foo, bar: baz } = require('mod')
+            for (const prop of nameNode.namedChildren) {
+              if (prop.type === 'shorthand_property_identifier_pattern') {
+                bindings.set(prop.text, { module: moduleName, originalName: prop.text })
+              } else if (prop.type === 'pair_pattern') {
+                const key = prop.childForFieldName('key')?.text ?? ''
+                const value = prop.childForFieldName('value')?.text ?? ''
+                bindings.set(value, { module: moduleName, originalName: key })
+              }
+            }
+          } else if (nameNode?.type === 'identifier') {
+            // const foo = require('mod')
+            bindings.set(nameNode.text, { module: moduleName, originalName: 'default' })
+          }
+        }
+      }
+    }
+
+    return false
+  })
+
+  return bindings
+}

package/src/taint/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Taint Engine v2 — Barrel Exports
+ *
+ * Phase 2, Part 1: Foundation types + AST-based classifiers.
+ * Phase 2, Part 2: CFG construction + def-use analysis.
+ * Phase 2, Part 3: Taint propagation engine + analyzer.
+ * Phase 3, Part 1: Cross-file function resolution.
+ * Phase 3, Part 2: Inter-procedural taint propagation.
+ * Phase 3, Part 3: Framework routing + async patterns.
+ * Phase 4: LLM Flow Graph — LLM registry + risk scoring.
+ */
+
+export { classifySources } from './source-classifier'
+export { classifySinks } from './sink-classifier'
+export { buildSanitizerRegistry } from './sanitizer-registry'
+export * from './types'
+export * from './cfg-types'
+export {
+  type TaintState,
+  type TaintStep,
+  type TaintFinding,
+  type CallResolutionContext,
+  type CalleeResult,
+} from './propagation-types'
+export { computeDefUse, type DefUseInfo } from './def-use'
+export {
+  buildCFG,
+  buildFileCFGs,
+  getSuccessors,
+  getPredecessors,
+  isReachable,
+} from './cfg-builder'
+export {
+  propagateFunction,
+  mapSourcesToCFG,
+  mapSinksToCFG,
+  buildSanitizerMap,
+  isDescendantOf,
+  findContainingCFGNode,
+  applyTransfer,
+} from './propagation'
+export { analyzeTaintsForFile } from './taint-analyzer'
+export {
+  buildCrossFileIndex,
+  type CrossFileIndex,
+  type FunctionDefinition,
+  type CallSiteInfo,
+} from './cross-file-index'
+export { analyzeTaintsForProject } from './cross-file-analyzer'
+export { injectPromiseChainTaint, injectCallbackTaint } from './async-flow'
+export {
+  detectExpressRoutes,
+  detectServerActions,
+  generateRouteHandlerSources,
+  type MiddlewareRegistration,
+  type RouteRegistration,
+} from './framework-models'
+export {
+  isLLMClient,
+  isKnownLLMCall,
+  LLM_CLIENT_MODULES,
+  LLM_CLIENT_NAMES,
+  LLM_API_METHODS,
+  LLM_DIRECT_FUNCTIONS,
+  LANGCHAIN_MESSAGE_CLASSES,
+} from './llm-registry'
+export {
+  assessPromptInjectionRisk,
+  assessExecutionRisk,
+  type LLMRiskAssessment,
+} from './llm-risk-scoring'

package/src/taint/llm-registry.ts

@@ -0,0 +1,174 @@
+/**
+ * LLM Client Registry
+ *
+ * Shared constants and helpers for identifying LLM API clients and calls.
+ * Used by both sink-classifier (prompt sinks) and source-classifier (LLM output sources).
+ *
+ * Follows the same pattern as DB_CLIENT_MODULES/isDbClient() in sink-classifier.ts.
+ */
+
+// ============================================================================
+// LLM Client Module Patterns
+// ============================================================================
+
+/** Import module patterns that indicate an LLM client library */
+export const LLM_CLIENT_MODULES: RegExp[] = [
+  // OpenAI
+  /^openai$/,
+  // Anthropic
+  /^@anthropic-ai\/sdk$/, /^anthropic$/,
+  // Vercel AI SDK
+  /^ai$/, /^@ai-sdk\//,
+  // LangChain
+  /^@langchain\//, /^langchain/,
+  // Google AI
+  /^@google\/generative-ai$/, /^@google-ai\//,
+  // Cohere
+  /^cohere-ai$/, /^cohere$/,
+  // Ollama
+  /^ollama$/,
+  // LlamaIndex
+  /^llamaindex$/,
+  // HuggingFace
+  /^@huggingface\//,
+  // Mistral
+  /^@mistralai\//,
+  // Amazon Bedrock
+  /^@aws-sdk\/client-bedrock-runtime$/,
+  // Python-specific LLM SDKs (underscore packages, not npm @scope/)
+  /^langchain_openai$/,
+  /^langchain_anthropic$/,
+  /^langchain_core/,
+  /^langchain_community/,
+  /^google\.generativeai$/,
+  /^litellm$/,
+  /^llama_index/,
+  /^transformers$/,
+]
+
+/** Variable names commonly used for LLM clients */
+export const LLM_CLIENT_NAMES = /^(openai|anthropic|client|ai|model|llm|genAI|gemini|cohere|ollama|bedrock|mistral|chain|pipe|pipeline|query_engine|chat_model|llm_chain)$/i
+
+// ============================================================================
+// LLM API Methods
+// ============================================================================
+
+export interface LLMMethodInfo {
+  type: 'create' | 'invoke' | 'generate' | 'direct'
+}
+
+/**
+ * Known LLM API methods that accept messages/prompts as arguments.
+ * Key = method name, value = call type.
+ */
+export const LLM_API_METHODS: Record<string, LLMMethodInfo> = {
+  // OpenAI: openai.chat.completions.create(...)
+  create: { type: 'create' },
+  // LangChain: chain.invoke(...)
+  invoke: { type: 'invoke' },
+  // Google AI: model.generateContent(...)
+  generateContent: { type: 'generate' },
+  // Generic: model.chat(), model.generate()
+  chat: { type: 'invoke' },
+  generate: { type: 'generate' },
+  // Ollama
+  complete: { type: 'generate' },
+  // Python LangChain
+  predict: { type: 'invoke' },
+  run: { type: 'invoke' },
+  // Python LlamaIndex
+  query: { type: 'invoke' },
+  // Python litellm
+  completion: { type: 'generate' },
+  // Python Google AI
+  send_message: { type: 'invoke' },
+  generate_content: { type: 'generate' },
+}
+
+/**
+ * Direct function calls (not member methods) that are LLM API calls.
+ * These are imported directly: `import { generateText } from 'ai'`
+ */
+export const LLM_DIRECT_FUNCTIONS: Record<string, LLMMethodInfo> = {
+  // Vercel AI SDK
+  generateText: { type: 'direct' },
+  streamText: { type: 'direct' },
+  generateObject: { type: 'direct' },
+  streamObject: { type: 'direct' },
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Check if an object expression text refers to a known LLM client.
+ * Follows the same pattern as isDbClient() — checks imports first, falls back to name heuristic.
+ */
+export function isLLMClient(
+  objText: string,
+  imports: Map<string, { module: string; originalName: string }>
+): boolean {
+  // Check if the full object text is a known LLM client by name
+  if (LLM_CLIENT_NAMES.test(objText)) return true
+
+  // Check each part of a dotted chain (e.g., `openai.chat.completions` → check `openai`)
+  const parts = objText.split('.')
+  for (const part of parts) {
+    if (LLM_CLIENT_NAMES.test(part)) return true
+  }
+
+  // Check if imported from an LLM module
+  const rootObj = parts[0]
+  const binding = imports.get(rootObj)
+  if (binding) {
+    return LLM_CLIENT_MODULES.some(p => p.test(binding.module))
+  }
+
+  return false
+}
+
+/**
+ * Check if a call expression is a known LLM API call.
+ *
+ * Matches both:
+ * - Member calls: `openai.chat.completions.create(...)`, `model.generateContent(...)`
+ * - Direct calls: `generateText(...)`, `streamText(...)`
+ */
+export function isKnownLLMCall(
+  targetName: string,
+  targetObject: string | undefined,
+  imports: Map<string, { module: string; originalName: string }>
+): boolean {
+  // Direct function call (e.g., generateText from Vercel AI SDK)
+  if (!targetObject && targetName in LLM_DIRECT_FUNCTIONS) {
+    // Verify it's imported from an LLM module
+    const binding = imports.get(targetName)
+    if (binding && LLM_CLIENT_MODULES.some(p => p.test(binding.module))) {
+      return true
+    }
+    // No verified LLM import → not an LLM call
+    return false
+  }
+
+  // Member call (e.g., openai.chat.completions.create)
+  if (targetObject && targetName in LLM_API_METHODS) {
+    return isLLMClient(targetObject, imports)
+  }
+
+  return false
+}
+
+// ============================================================================
+// LangChain Message Class Names
+// ============================================================================
+
+/** LangChain message class names used in new_expression */
+export const LANGCHAIN_MESSAGE_CLASSES: Record<string, 'system_prompt' | 'prompt_construction'> = {
+  SystemMessage: 'system_prompt',
+  SystemMessagePromptTemplate: 'system_prompt',
+  HumanMessage: 'prompt_construction',
+  HumanMessagePromptTemplate: 'prompt_construction',
+  AIMessage: 'prompt_construction',
+  ChatMessage: 'prompt_construction',
+}