@oculum/scanner 1.0.14 → 1.0.15

package/src/detect/ast-rules/helpers/user-input.ts

@@ -0,0 +1,256 @@
+/**
+ * AST User Input & Dangerous Sink Detection Helpers
+ *
+ * Identifies user input sources (req.body, req.query, etc.),
+ * LLM output expressions, and dangerous code sinks.
+ */
+
+import type Parser from 'tree-sitter'
+import { walkAST, findEnclosingFunction } from '../../../parse/ast'
+
+// ============================================================================
+// User Input Detection
+// ============================================================================
+
+/** Known user input property paths */
+const USER_INPUT_PATTERNS: Array<{ object: RegExp; property: string | RegExp }> = [
+  // Express / generic
+  { object: /^req(uest)?$/, property: 'body' },
+  { object: /^req(uest)?$/, property: 'query' },
+  { object: /^req(uest)?$/, property: 'params' },
+  { object: /^req(uest)?$/, property: 'headers' },
+  { object: /^req(uest)?$/, property: 'cookies' },
+  { object: /^req(uest)?$/, property: /^(get|header)$/ },
+  // Koa
+  { object: /^ctx$/, property: /^request$/ },
+  { object: /^ctx\.request$/, property: 'body' },
+  { object: /^ctx\.request$/, property: 'query' },
+  // Next.js App Router
+  { object: /^(req|request)$/, property: 'json' },
+  { object: /^(req|request)$/, property: 'text' },
+  { object: /^(req|request)$/, property: 'formData' },
+  // Fastify
+  { object: /^(req|request)$/, property: 'body' },
+  { object: /^(req|request)$/, property: 'query' },
+  { object: /^(req|request)$/, property: 'params' },
+  // Hono
+  { object: /^c$/, property: /^req$/ },
+  // URL search params
+  { object: /searchParams/, property: /^(get|getAll)$/ },
+]
+
+/**
+ * Check if a node accesses user input (req.body, req.query, etc.).
+ */
+export function isUserInputExpression(node: Parser.SyntaxNode): boolean {
+  if (node.type === 'member_expression') {
+    const obj = node.childForFieldName('object')
+    const prop = node.childForFieldName('property')
+    if (!obj || !prop) return false
+
+    for (const pattern of USER_INPUT_PATTERNS) {
+      const objMatch = pattern.object.test(obj.text)
+      const propMatch = typeof pattern.property === 'string'
+        ? prop.text === pattern.property
+        : pattern.property.test(prop.text)
+      if (objMatch && propMatch) return true
+    }
+
+    // Recursive: req.body.username (user input with property access)
+    if (isUserInputExpression(obj)) return true
+  }
+
+  // Destructured from request: const { body } = req
+  if (node.type === 'identifier') {
+    const name = node.text
+    if (['body', 'query', 'params'].includes(name)) {
+      // Check if destructured from request-like object
+      const fn = findEnclosingFunction(node)
+      if (fn) {
+        const params = fn.childForFieldName('parameters')
+        if (params) {
+          const destructured = params.descendantsOfType('object_pattern')
+          for (const d of destructured) {
+            const props = d.descendantsOfType('shorthand_property_identifier_pattern')
+            if (props.some(p => p.text === name)) return true
+          }
+        }
+      }
+    }
+  }
+
+  return false
+}
+
+// ============================================================================
+// LLM Output Detection
+// ============================================================================
+
+/** Patterns that indicate LLM API response content */
+const LLM_OUTPUT_PATTERNS = [
+  /response\.choices\[?\d*\]?\.message\.content/,
+  /completion\.choices\[?\d*\]?\.message\.content/,
+  /result\.choices\[?\d*\]?\.message\.content/,
+  /response\.data\.choices/,
+  /response\.content\[?\d*\]?\.text/,  // Anthropic SDK
+  /message\.content/,
+  /output\.text/,
+  /response\.text/,
+  /result\.text/,
+  /generation\.text/,
+  /\.generated_text/,
+  /\.output_text/,
+]
+
+/**
+ * Check if a node accesses LLM output content.
+ */
+export function isLLMOutputExpression(node: Parser.SyntaxNode): boolean {
+  if (node.type !== 'member_expression' && node.type !== 'subscript_expression') {
+    return false
+  }
+
+  const fullText = node.text
+  return LLM_OUTPUT_PATTERNS.some(p => p.test(fullText))
+}
+
+// ============================================================================
+// Dangerous Sinks
+// ============================================================================
+
+/** Known dangerous function sinks */
+const DANGEROUS_SINKS = new Set([
+  'eval',
+  'Function',
+  'setTimeout',  // when called with string arg
+  'setInterval', // when called with string arg
+  'execSync',
+  'exec',
+  'execFile',
+  'spawn',
+  'spawnSync',
+  'fork',
+])
+
+const DANGEROUS_MEMBER_SINKS: Array<{ object: RegExp; method: string }> = [
+  { object: /^(document|window)$/, method: 'write' },
+  { object: /^document$/, method: 'writeln' },
+  { object: /^(child_process|cp)$/, method: 'exec' },
+  { object: /^(child_process|cp)$/, method: 'execSync' },
+  { object: /^(child_process|cp)$/, method: 'spawn' },
+]
+
+const DANGEROUS_PROPERTY_SINKS = new Set([
+  'innerHTML',
+  'outerHTML',
+  'insertAdjacentHTML',
+])
+
+/**
+ * Check if a call_expression is a known dangerous sink.
+ */
+export function isDangerousSink(node: Parser.SyntaxNode): boolean {
+  if (node.type !== 'call_expression') return false
+
+  const fn = node.childForFieldName('function')
+  if (!fn) return false
+
+  // Direct call: eval(...)
+  if (fn.type === 'identifier' && DANGEROUS_SINKS.has(fn.text)) return true
+
+  // Member call: child_process.exec(...)
+  if (fn.type === 'member_expression') {
+    const obj = fn.childForFieldName('object')
+    const prop = fn.childForFieldName('property')
+    if (obj && prop) {
+      // Check member sinks
+      for (const sink of DANGEROUS_MEMBER_SINKS) {
+        if (sink.object.test(obj.text) && prop.text === sink.method) return true
+      }
+      // Check property sinks (used as function: el.insertAdjacentHTML())
+      if (DANGEROUS_PROPERTY_SINKS.has(prop.text)) return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Check if an assignment target is a dangerous DOM property.
+ * e.g., el.innerHTML = userInput
+ */
+export function isDangerousPropertyAssignment(node: Parser.SyntaxNode): boolean {
+  if (node.type !== 'assignment_expression') return false
+
+  const left = node.childForFieldName('left')
+  if (left?.type !== 'member_expression') return false
+
+  const prop = left.childForFieldName('property')
+  return prop ? DANGEROUS_PROPERTY_SINKS.has(prop.text) : false
+}
+
+// ============================================================================
+// Request Handler Detection
+// ============================================================================
+
+/**
+ * Check if a function is an Express/Next.js/Fastify route handler.
+ * Looks at parameter names/types for (req, res) or (request, response) patterns.
+ */
+export function isRequestHandler(fnNode: Parser.SyntaxNode): boolean {
+  const params = fnNode.childForFieldName('parameters')
+  if (!params) return false
+
+  const paramNames = params.namedChildren
+    .map(p => {
+      if (p.type === 'identifier') return p.text
+      const pattern = p.childForFieldName('pattern')
+      return pattern?.text ?? p.text
+    })
+    .filter(Boolean)
+
+  // (req, res) or (request, response) or (ctx) or (c) patterns
+  if (paramNames.length >= 2) {
+    const [first, second] = paramNames
+    if (
+      (/^req(uest)?$/i.test(first) && /^res(ponse)?$/i.test(second)) ||
+      (/^ctx$/i.test(first)) ||
+      (/^c$/i.test(first) && paramNames.length <= 2)
+    ) {
+      return true
+    }
+  }
+
+  // Next.js App Router: single Request param or NextRequest
+  if (paramNames.length >= 1) {
+    // Check type annotations
+    const firstParam = params.namedChildren[0]
+    if (firstParam) {
+      const typeAnnotation = firstParam.childForFieldName('type')
+      if (typeAnnotation) {
+        const typeText = typeAnnotation.text
+        if (/Request|NextRequest|NextApiRequest/.test(typeText)) return true
+      }
+    }
+  }
+
+  return false
+}
+
+/**
+ * Collect all user input access points in a file.
+ * Returns nodes that access request data.
+ */
+export function getUserInputSources(root: Parser.SyntaxNode): Parser.SyntaxNode[] {
+  const sources: Parser.SyntaxNode[] = []
+
+  walkAST(root, (node) => {
+    if (isUserInputExpression(node)) {
+      sources.push(node)
+      return true // skip children (avoid double-counting nested access)
+    }
+    return false
+  })
+
+  return sources
+}

package/src/detect/ast-rules/index.ts

@@ -0,0 +1,311 @@
+/**
+ * AST Rule Engine
+ *
+ * Defines and runs AST-based detection rules against tree-sitter parse trees.
+ * Rules declare patterns (node types, matchers, context checks) and produce
+ * Vulnerability objects compatible with the existing pipeline.
+ *
+ * This is the v2 foundation — new detectors should be written as AST rules
+ * rather than regex patterns.
+ */
+
+import type Parser from 'tree-sitter'
+import type { Vulnerability, VulnerabilitySeverity, VulnerabilityCategory, TaintPathOutput, EvidenceLevel } from '../../shared/types'
+import type { ParsedAST } from '../../parse/ast'
+import { walkAST } from '../../parse/ast'
+import { type NodeIndex, buildNodeIndexCached, getNodes } from '../../parse/node-index'
+export { type NodeIndex, getNodes } from '../../parse/node-index'
+
+// ============================================================================
+// Rule Definition Types
+// ============================================================================
+
+export interface ASTRuleMatch {
+  node: Parser.SyntaxNode
+  /** Override severity for this specific match (optional) */
+  severity?: VulnerabilitySeverity
+  /** Override category for this specific match (optional, used by LLM taint routing) */
+  category?: VulnerabilityCategory
+  /** Extra context to append to the description */
+  note?: string
+  /** Serialized taint path (from taint-flow-ast.ts) */
+  taintPath?: TaintPathOutput
+  /** Evidence level classification */
+  evidenceLevel?: EvidenceLevel
+  /** Context-specific fix steps (from taint-fix-templates) */
+  fixSteps?: string[]
+}
+
+/**
+ * An AST detection rule.
+ *
+ * Rules are functions that receive the AST root + file metadata and return
+ * an array of matches. The engine converts matches into Vulnerability objects.
+ */
+export interface ASTRule {
+  /** Unique rule ID (e.g., 'ast-weak-crypto-math-random') */
+  id: string
+  /** Human-readable title shown in findings */
+  title: string
+  /** Default description for findings */
+  description: string
+  /** Default severity */
+  severity: VulnerabilitySeverity
+  /** Vulnerability category */
+  category: VulnerabilityCategory
+  /** Default suggested fix */
+  suggestedFix?: string
+  /** Which languages this rule applies to */
+  languages: Array<'javascript' | 'typescript' | 'tsx' | 'python'>
+  /** Confidence level */
+  confidence: 'high' | 'medium' | 'low'
+  /** Base confidence score for the scoring engine */
+  baseConfidence?: number
+  /** Whether this finding requires AI validation */
+  requiresAIValidation?: boolean
+  /** Detection layer (1 = pattern, 2 = structural). Defaults to 2 for AST rules. */
+  layer?: 1 | 2 | 3
+  /** Detector group source. Defaults to 'structural'. */
+  source?: 'secrets' | 'structural' | 'ai_code' | 'config'
+  /**
+   * The detection function. Receives the parsed AST and returns matched nodes.
+   * Should be fast — no I/O, no network calls.
+   */
+  detect(ast: ParsedAST, content: string, nodeIndex?: NodeIndex): ASTRuleMatch[]
+}
+
+// ============================================================================
+// Rule Registry
+// ============================================================================
+
+const rules: ASTRule[] = []
+
+/**
+ * Register an AST rule. Called by individual rule modules during import.
+ */
+export function registerASTRule(rule: ASTRule): void {
+  rules.push(rule)
+}
+
+/**
+ * Get all registered AST rules.
+ */
+export function getASTRules(): readonly ASTRule[] {
+  return rules
+}
+
+// ============================================================================
+// Rule Runner
+// ============================================================================
+
+/**
+ * Run all applicable AST rules against a single parsed file.
+ * Returns Vulnerability objects ready for the pipeline.
+ */
+export function runASTRules(
+  ast: ParsedAST,
+  content: string
+): Vulnerability[] {
+  const vulnerabilities: Vulnerability[] = []
+  const lines = content.split('\n')
+  const nodeIndex = buildNodeIndexCached(ast.tree.rootNode, ast.language, ast.hash)
+
+  for (const rule of rules) {
+    // Skip rules that don't apply to this language
+    if (!rule.languages.includes(ast.language)) continue
+
+    try {
+      const matches = rule.detect(ast, content, nodeIndex)
+
+      for (const match of matches) {
+        const lineNumber = match.node.startPosition.row + 1 // tree-sitter is 0-indexed
+        const lineContent = lines[match.node.startPosition.row]?.trim() || ''
+
+        vulnerabilities.push({
+          id: `${rule.id}-${ast.filePath}-${lineNumber}`,
+          filePath: ast.filePath,
+          lineNumber,
+          lineContent,
+          severity: match.severity ?? rule.severity,
+          category: match.category ?? rule.category,
+          title: rule.title,
+          description: match.note
+            ? `${rule.description}. ${match.note}`
+            : rule.description,
+          suggestedFix: rule.suggestedFix,
+          confidence: rule.confidence,
+          baseConfidence: rule.baseConfidence,
+          layer: rule.layer ?? 2,
+          source: rule.source ?? 'structural',
+          requiresAIValidation: rule.requiresAIValidation ?? false,
+          taintPath: match.taintPath,
+          evidenceLevel: match.evidenceLevel,
+          fixSteps: match.fixSteps,
+        })
+      }
+    } catch (err) {
+      // Individual rule failure should not break the scan
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn(`[AST] Rule ${rule.id} failed on ${ast.filePath}: ${err}`)
+      }
+    }
+  }
+
+  return vulnerabilities
+}
+
+/**
+ * Run all applicable AST rules across multiple parsed files.
+ */
+export function runASTRulesOnFiles(
+  asts: Map<string, ParsedAST>,
+  files: Array<{ path: string; content: string }>
+): Vulnerability[] {
+  const allVulnerabilities: Vulnerability[] = []
+  const contentMap = new Map(files.map(f => [f.path, f.content]))
+
+  for (const [filePath, ast] of asts) {
+    const content = contentMap.get(filePath)
+    if (!content) continue
+
+    const vulns = runASTRules(ast, content)
+    allVulnerabilities.push(...vulns)
+  }
+
+  return allVulnerabilities
+}
+
+// ============================================================================
+// AST Query Helpers (used by rule implementations)
+// ============================================================================
+
+/**
+ * Collect all import bindings from the top level of a file.
+ * Returns a map of local name → { source module, original name }.
+ *
+ * Handles:
+ *  - import { foo } from 'mod'
+ *  - import { foo as bar } from 'mod'
+ *  - import foo from 'mod'
+ *  - const { foo } = require('mod')
+ */
+export function collectImportBindings(
+  root: Parser.SyntaxNode
+): Map<string, { module: string; originalName: string }> {
+  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
+}
+
+/**
+ * Check if a call_expression node calls a specific function name
+ * (handles both direct calls and member expressions like crypto.createHash).
+ */
+export function isCallTo(node: Parser.SyntaxNode, name: string): boolean {
+  if (node.type !== 'call_expression') return false
+  const fn = node.childForFieldName('function')
+  if (!fn) return false
+
+  // Direct: functionName(...)
+  if (fn.type === 'identifier' && fn.text === name) return true
+
+  // Member: obj.method(...)
+  if (fn.type === 'member_expression') {
+    const prop = fn.childForFieldName('property')
+    if (prop?.text === name) return true
+  }
+
+  return false
+}
+
+/**
+ * Get the string value of the first argument to a call expression.
+ * Returns null if the first arg isn't a string literal.
+ */
+export function getFirstStringArg(callNode: Parser.SyntaxNode): string | null {
+  const args = callNode.childForFieldName('arguments')
+  if (!args) return null
+  const firstArg = args.namedChildren[0]
+  if (!firstArg) return null
+
+  if (firstArg.type === 'string' || firstArg.type === 'template_string') {
+    // Strip quotes
+    const text = firstArg.text
+    if ((text.startsWith("'") && text.endsWith("'")) ||
+        (text.startsWith('"') && text.endsWith('"'))) {
+      return text.slice(1, -1)
+    }
+    if (text.startsWith('`') && text.endsWith('`')) {
+      return text.slice(1, -1)
+    }
+    // string node may contain a string_fragment child
+    const fragment = firstArg.descendantsOfType('string_fragment')
+    if (fragment.length > 0) return fragment[0].text
+  }
+
+  return null
+}