@oculum/scanner 1.0.14 → 1.0.15

package/src/detect/ast-rules/helpers/call-analysis.ts

@@ -0,0 +1,256 @@
+/**
+ * AST Call Expression Analysis Helpers
+ *
+ * Resolves call targets, extracts arguments, detects method calls,
+ * and analyzes object literals for security-relevant patterns.
+ */
+
+import type Parser from 'tree-sitter'
+import { walkAST } from '../../../parse/ast'
+import { collectVariableAliases } from './scope-analysis'
+
+// ============================================================================
+// Call Target Resolution
+// ============================================================================
+
+export interface ResolvedCallTarget {
+  /** 'direct' = fn(), 'member' = obj.fn(), 'computed' = obj[fn]() */
+  type: 'direct' | 'member' | 'computed' | 'new'
+  /** The function/method name being called */
+  name: string
+  /** For member calls, the object expression text */
+  object?: string
+  /** Full chain: 'a.b.c' */
+  fullChain: string
+  /** Whether this was resolved via an alias */
+  aliased: boolean
+}
+
+/**
+ * For a call_expression node, resolve what function is being called.
+ * Handles direct calls, member expressions, aliases, and imports.
+ */
+export function resolveCallTarget(
+  node: Parser.SyntaxNode,
+  aliases?: Map<string, string>
+): ResolvedCallTarget | null {
+  if (node.type !== 'call_expression' && node.type !== 'new_expression') return null
+
+  const fn = node.childForFieldName('function')
+    ?? node.childForFieldName('constructor')
+  if (!fn) return null
+
+  const isNew = node.type === 'new_expression'
+
+  // Direct call: functionName(...)
+  if (fn.type === 'identifier') {
+    const aliasTarget = aliases?.get(fn.text)
+    if (aliasTarget) {
+      // Aliased: const e = eval; e() -> resolves to eval
+      const parts = aliasTarget.split('.')
+      return {
+        type: isNew ? 'new' : (parts.length > 1 ? 'member' : 'direct'),
+        name: parts[parts.length - 1],
+        object: parts.length > 1 ? parts.slice(0, -1).join('.') : undefined,
+        fullChain: aliasTarget,
+        aliased: true,
+      }
+    }
+    return {
+      type: isNew ? 'new' : 'direct',
+      name: fn.text,
+      fullChain: fn.text,
+      aliased: false,
+    }
+  }
+
+  // Member call: obj.method(...)
+  if (fn.type === 'member_expression') {
+    const prop = fn.childForFieldName('property')
+    const obj = fn.childForFieldName('object')
+    if (!prop) return null
+
+    return {
+      type: isNew ? 'new' : 'member',
+      name: prop.text,
+      object: obj?.text,
+      fullChain: fn.text,
+      aliased: false,
+    }
+  }
+
+  return null
+}
+
+// ============================================================================
+// Argument Extraction
+// ============================================================================
+
+/**
+ * Get the argument list from a call expression.
+ * Returns array of argument nodes.
+ */
+export function getCallArguments(node: Parser.SyntaxNode): Parser.SyntaxNode[] {
+  if (node.type !== 'call_expression' && node.type !== 'new_expression') return []
+  const args = node.childForFieldName('arguments')
+  if (!args) return []
+  return args.namedChildren
+}
+
+/**
+ * Get the Nth argument from a call expression (0-indexed).
+ */
+export function getCallArgument(node: Parser.SyntaxNode, index: number): Parser.SyntaxNode | null {
+  const args = getCallArguments(node)
+  return args[index] ?? null
+}
+
+// ============================================================================
+// Method Call Matching
+// ============================================================================
+
+/**
+ * Check if a call_expression matches `obj.method(...)` pattern.
+ * objectPattern can be a string or regex to match the object.
+ */
+export function isMethodCallOn(
+  node: Parser.SyntaxNode,
+  objectPattern: string | RegExp,
+  methodName: string | string[]
+): boolean {
+  if (node.type !== 'call_expression') return false
+  const fn = node.childForFieldName('function')
+  if (!fn || fn.type !== 'member_expression') return false
+
+  const prop = fn.childForFieldName('property')
+  const obj = fn.childForFieldName('object')
+  if (!prop || !obj) return false
+
+  // Check method name
+  const methods = Array.isArray(methodName) ? methodName : [methodName]
+  if (!methods.includes(prop.text)) return false
+
+  // Check object
+  if (typeof objectPattern === 'string') {
+    return obj.text === objectPattern
+  }
+  return objectPattern.test(obj.text)
+}
+
+/**
+ * Extract the full receiver chain from nested member expressions.
+ * e.g., `a.b.c.d()` -> ['a', 'b', 'c', 'd']
+ */
+export function getReceiverChain(node: Parser.SyntaxNode): string[] {
+  const chain: string[] = []
+
+  function walk(n: Parser.SyntaxNode): void {
+    if (n.type === 'member_expression') {
+      const obj = n.childForFieldName('object')
+      const prop = n.childForFieldName('property')
+      if (obj) walk(obj)
+      if (prop) chain.push(prop.text)
+    } else if (n.type === 'identifier') {
+      chain.push(n.text)
+    } else if (n.type === 'this') {
+      chain.push('this')
+    }
+  }
+
+  walk(node)
+  return chain
+}
+
+/**
+ * Check if a node is a `new ClassName(...)` call.
+ */
+export function isConstructorCall(
+  node: Parser.SyntaxNode,
+  className: string | string[]
+): boolean {
+  if (node.type !== 'new_expression') return false
+  const ctor = node.childForFieldName('constructor')
+  if (!ctor) return false
+
+  const names = Array.isArray(className) ? className : [className]
+  return names.includes(ctor.text)
+}
+
+// ============================================================================
+// Object Literal Analysis
+// ============================================================================
+
+/**
+ * Extract a property value from an object literal node.
+ * Handles shorthand, regular, and computed properties.
+ */
+export function getObjectLiteralProperty(
+  node: Parser.SyntaxNode,
+  key: string
+): Parser.SyntaxNode | null {
+  if (node.type !== 'object') return null
+
+  for (const child of node.namedChildren) {
+    if (child.type === 'pair') {
+      const keyNode = child.childForFieldName('key')
+      if (keyNode?.text === key) {
+        return child.childForFieldName('value')
+      }
+    }
+    if (child.type === 'shorthand_property_identifier') {
+      if (child.text === key) return child
+    }
+  }
+
+  return null
+}
+
+/**
+ * Extract all key-value pairs from an object literal.
+ * Returns a map of key name -> value node.
+ */
+export function getObjectLiteralProperties(
+  node: Parser.SyntaxNode
+): Map<string, Parser.SyntaxNode> {
+  const props = new Map<string, Parser.SyntaxNode>()
+  if (node.type !== 'object') return props
+
+  for (const child of node.namedChildren) {
+    if (child.type === 'pair') {
+      const keyNode = child.childForFieldName('key')
+      const valNode = child.childForFieldName('value')
+      if (keyNode && valNode) {
+        props.set(keyNode.text, valNode)
+      }
+    }
+    if (child.type === 'shorthand_property_identifier') {
+      props.set(child.text, child)
+    }
+  }
+
+  return props
+}
+
+/**
+ * Find all call expressions in a subtree that match a given target.
+ */
+export function findCallsTo(
+  root: Parser.SyntaxNode,
+  targetName: string | string[],
+  aliases?: Map<string, string>
+): Parser.SyntaxNode[] {
+  const targets = Array.isArray(targetName) ? targetName : [targetName]
+  const results: Parser.SyntaxNode[] = []
+
+  walkAST(root, (node) => {
+    if (node.type === 'call_expression') {
+      const resolved = resolveCallTarget(node, aliases)
+      if (resolved && targets.includes(resolved.name)) {
+        results.push(node)
+      }
+    }
+    return false
+  })
+
+  return results
+}

package/src/detect/ast-rules/helpers/context-detection.ts

@@ -0,0 +1,277 @@
+/**
+ * AST Context Detection Helpers
+ *
+ * Detects file-level and function-level context: LLM code,
+ * route handlers, middleware, server/client directives, auth checks.
+ */
+
+import type Parser from 'tree-sitter'
+import { walkAST } from '../../../parse/ast'
+import { hasImport, getImportedModules } from './import-analysis'
+import { isMethodCallOn, getReceiverChain } from './call-analysis'
+
+// ============================================================================
+// LLM / AI Context
+// ============================================================================
+
+/** AI/LLM SDK module patterns */
+const AI_SDK_MODULES = [
+  /^openai$/i,
+  /^@anthropic-ai\//,
+  /^anthropic$/,
+  /^@langchain\//,
+  /^langchain/,
+  /^@google-ai\//,
+  /^@google\/generative-ai$/,
+  /^cohere-ai$/,
+  /^ai$/,  // Vercel AI SDK
+  /^@ai-sdk\//,
+  /^llamaindex/,
+  /^@huggingface\//,
+]
+
+/**
+ * Detect if a file contains AI/LLM code from AST analysis.
+ * Checks imports, API call patterns, and message array structures.
+ */
+const LLM_CONTENT_QUICK_CHECK = /openai|anthropic|langchain|@google.*generative|cohere|@ai-sdk|llamaindex|huggingface|completions?\.create|messages\.create|generateText|streamText|generateObject|role['"]?\s*:\s*['"](?:system|user|assistant)/i
+
+export function isLLMContextFile(root: Parser.SyntaxNode, content?: string): boolean {
+  // Quick content pre-check — skip files that can't have LLM patterns
+  if (content && !LLM_CONTENT_QUICK_CHECK.test(content)) return false
+
+  const modules = getImportedModules(root)
+
+  // Check for AI SDK imports
+  for (const mod of modules) {
+    if (AI_SDK_MODULES.some(p => p.test(mod))) return true
+  }
+
+  // Check for common AI API patterns in code
+  let hasAIPattern = false
+  walkAST(root, (node) => {
+    if (hasAIPattern) return true // short-circuit
+
+    // chat.completions.create(), openai.createChatCompletion(), etc.
+    if (node.type === 'call_expression') {
+      const chain = getReceiverChain(node.childForFieldName('function') ?? node)
+      const chainStr = chain.join('.')
+      if (
+        /completions?\.create/i.test(chainStr) ||
+        /chat\.completions/i.test(chainStr) ||
+        /messages\.create/i.test(chainStr) ||
+        /generateText|streamText|generateObject/i.test(chainStr)
+      ) {
+        hasAIPattern = true
+        return true
+      }
+    }
+
+    // Message array with role/content objects
+    if (node.type === 'object' && node.parent?.type === 'array') {
+      const hasRole = node.namedChildren.some(c =>
+        c.type === 'pair' && c.childForFieldName('key')?.text === 'role'
+      )
+      const hasContent = node.namedChildren.some(c =>
+        c.type === 'pair' && c.childForFieldName('key')?.text === 'content'
+      )
+      if (hasRole && hasContent) {
+        hasAIPattern = true
+        return true
+      }
+    }
+
+    return false
+  })
+
+  return hasAIPattern
+}
+
+// ============================================================================
+// Route Handler Detection
+// ============================================================================
+
+/**
+ * Detect if a function node is an Express/Next.js/Fastify route handler.
+ * Checks: parameter patterns, export names, decorator patterns.
+ */
+export function isRouteHandler(fnNode: Parser.SyntaxNode): boolean {
+  // Check parameter pattern (req, res)
+  const params = fnNode.childForFieldName('parameters')
+  if (params) {
+    const paramNames = params.namedChildren
+      .map(p => {
+        if (p.type === 'identifier') return p.text
+        const pattern = p.childForFieldName('pattern')
+        return pattern?.text ?? ''
+      })
+
+    if (paramNames.length >= 2) {
+      const [first, second] = paramNames
+      if (/^req(uest)?$/i.test(first) && /^res(ponse)?$/i.test(second)) return true
+    }
+
+    // Type annotation check
+    const firstParam = params.namedChildren[0]
+    if (firstParam) {
+      const typeNode = firstParam.childForFieldName('type')
+      if (typeNode && /Request|NextRequest|NextApiRequest|IncomingMessage/.test(typeNode.text)) {
+        return true
+      }
+    }
+  }
+
+  // Check if this is an exported HTTP method function (Next.js App Router)
+  const exportParent = fnNode.parent
+  if (exportParent?.type === 'export_statement') {
+    const fnName = fnNode.childForFieldName('name')?.text
+    if (fnName && /^(GET|POST|PUT|DELETE|PATCH|HEAD)$/.test(fnName)) return true
+  }
+
+  // Check if assigned to a variable with HTTP method name
+  if (fnNode.parent?.type === 'variable_declarator') {
+    const varName = fnNode.parent.childForFieldName('name')?.text
+    if (varName && /^(GET|POST|PUT|DELETE|PATCH|HEAD)$/.test(varName)) return true
+  }
+
+  return false
+}
+
+// ============================================================================
+// Middleware Detection
+// ============================================================================
+
+/**
+ * Detect app.use() middleware setup patterns in the root.
+ */
+export function hasMiddlewarePattern(root: Parser.SyntaxNode): boolean {
+  let found = false
+  walkAST(root, (node) => {
+    if (found) return true
+    if (node.type === 'call_expression') {
+      if (isMethodCallOn(node, /^(app|router|server)$/, ['use', 'middleware'])) {
+        found = true
+        return true
+      }
+    }
+    return false
+  })
+  return found
+}
+
+// ============================================================================
+// Server / Client Detection
+// ============================================================================
+
+/**
+ * Detect 'use client' or 'use server' directives at the top of the file.
+ */
+export function getFileDirective(root: Parser.SyntaxNode): 'use client' | 'use server' | null {
+  // Look at the first expression statement
+  for (const child of root.namedChildren) {
+    if (child.type === 'expression_statement') {
+      const expr = child.namedChildren[0]
+      if (expr?.type === 'string') {
+        const val = expr.text.replace(/^['"`]|['"`]$/g, '')
+        if (val === 'use client') return 'use client'
+        if (val === 'use server') return 'use server'
+      }
+    }
+    // Only check the first few statements
+    if (child.startPosition.row > 5) break
+  }
+  return null
+}
+
+/**
+ * Detect if a file is server-side from AST.
+ * Checks: 'use server' directive, server-only imports, Node.js APIs.
+ */
+export function isServerFile(root: Parser.SyntaxNode): boolean {
+  // 'use server' directive
+  if (getFileDirective(root) === 'use server') return true
+
+  // Server-only module imports
+  const modules = getImportedModules(root)
+  const serverModules = ['fs', 'path', 'crypto', 'http', 'https', 'net', 'child_process',
+    'server-only', 'next/server', '@supabase/supabase-js', 'pg', 'mysql2', 'mongodb']
+  for (const mod of modules) {
+    if (serverModules.includes(mod)) return true
+    if (mod.startsWith('node:')) return true
+  }
+
+  return false
+}
+
+// ============================================================================
+// Auth Check Detection
+// ============================================================================
+
+/** Known auth helper function names / patterns */
+const AUTH_CHECK_PATTERNS = [
+  /^(require|check|verify|validate|ensure|assert)(Auth|Authentication|Session|Token|User|Login|Permission|Access)/i,
+  /^(getCurrentUser|getSession|getServerSession|auth|getAuth|useAuth|useSession)/i,
+  /^(isAuthenticated|isAuthorized|isLoggedIn|hasPermission|hasRole)/i,
+  /^(protect|guard|authenticate|authorize)/i,
+  /^(clerkMiddleware|withAuth|requireAuth)/i,
+]
+
+/**
+ * Find auth check calls within a function body.
+ * Returns the call nodes that appear to be auth checks.
+ */
+export function findAuthChecks(fnBody: Parser.SyntaxNode): Parser.SyntaxNode[] {
+  const authCalls: Parser.SyntaxNode[] = []
+
+  walkAST(fnBody, (node) => {
+    if (node.type === 'call_expression') {
+      const fn = node.childForFieldName('function')
+      if (!fn) return false
+
+      const fnName = fn.type === 'identifier'
+        ? fn.text
+        : fn.type === 'member_expression'
+          ? fn.childForFieldName('property')?.text ?? ''
+          : ''
+
+      if (AUTH_CHECK_PATTERNS.some(p => p.test(fnName))) {
+        authCalls.push(node)
+      }
+    }
+
+    // await auth() pattern (Clerk, etc.)
+    if (node.type === 'await_expression') {
+      const child = node.namedChildren[0]
+      if (child?.type === 'call_expression') {
+        const fn = child.childForFieldName('function')
+        if (fn?.type === 'identifier' && AUTH_CHECK_PATTERNS.some(p => p.test(fn.text))) {
+          authCalls.push(child)
+        }
+      }
+    }
+
+    return false
+  })
+
+  return authCalls
+}
+
+/**
+ * Check if a file has any auth-related imports.
+ */
+const AUTH_IMPORT_QUICK_CHECK = /clerk|next-auth|auth0|supabase|passport|jsonwebtoken|jose/i
+
+export function hasAuthImports(root: Parser.SyntaxNode, content?: string): boolean {
+  // Quick content pre-check — skip files without auth library mentions
+  if (content && !AUTH_IMPORT_QUICK_CHECK.test(content)) return false
+
+  return (
+    hasImport(root, /clerk/) ||
+    hasImport(root, /next-auth/) ||
+    hasImport(root, /auth0/) ||
+    hasImport(root, /supabase/, 'auth') ||
+    hasImport(root, /passport/) ||
+    hasImport(root, /jsonwebtoken/) ||
+    hasImport(root, /jose/)
+  )
+}

package/src/detect/ast-rules/helpers/control-flow.ts

@@ -0,0 +1,179 @@
+/**
+ * AST Control Flow Analysis Helpers
+ *
+ * Determines try-catch wrapping, conditional guards, dead code,
+ * and block-level containment for findings.
+ */
+
+import type Parser from 'tree-sitter'
+import { findEnclosingFunction } from '../../../parse/ast'
+
+// ============================================================================
+// Try-Catch Detection
+// ============================================================================
+
+/**
+ * Check if a node is inside a try block (not the catch/finally).
+ */
+export function isInsideTryCatch(node: Parser.SyntaxNode): boolean {
+  let current: Parser.SyntaxNode | null = node.parent
+  while (current) {
+    if (current.type === 'try_statement') {
+      // Verify the node is in the try body, not catch/finally
+      const tryBody = current.childForFieldName('body')
+      if (tryBody && isDescendantOf(node, tryBody)) return true
+    }
+    current = current.parent
+  }
+  return false
+}
+
+/**
+ * Check if a node is inside a catch clause.
+ */
+export function isInsideCatchClause(node: Parser.SyntaxNode): boolean {
+  let current: Parser.SyntaxNode | null = node.parent
+  while (current) {
+    if (current.type === 'catch_clause') return true
+    current = current.parent
+  }
+  return false
+}
+
+// ============================================================================
+// Conditional Guards
+// ============================================================================
+
+/**
+ * Check if a node is preceded by an if-return/throw guard in the same function.
+ * A guard is: if (condition) { return | throw }
+ * This means any code after the guard only runs when the condition is false.
+ */
+export function isInsideConditionalGuard(node: Parser.SyntaxNode): boolean {
+  const fn = findEnclosingFunction(node)
+  if (!fn) return false
+
+  const body = fn.childForFieldName('body')
+  if (!body) return false
+
+  // Look for if statements before this node's line
+  for (const child of body.namedChildren) {
+    if (child.startPosition.row >= node.startPosition.row) break
+    if (child.type === 'if_statement') {
+      const consequence = child.childForFieldName('consequence')
+      if (consequence && hasTerminator(consequence)) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+/**
+ * Check if a function has an early return/throw guard before a given point.
+ * The checkFn callback tests whether the guard condition is relevant.
+ */
+export function hasEarlyReturnGuard(
+  fnNode: Parser.SyntaxNode,
+  checkFn?: (guardNode: Parser.SyntaxNode) => boolean
+): boolean {
+  const body = fnNode.childForFieldName('body')
+  if (!body) return false
+
+  for (const child of body.namedChildren) {
+    if (child.type === 'if_statement') {
+      const consequence = child.childForFieldName('consequence')
+      if (consequence && hasTerminator(consequence)) {
+        if (!checkFn || checkFn(child)) return true
+      }
+    }
+  }
+
+  return false
+}
+
+/**
+ * Check which branch (consequent/alternate) of an if statement a node is in.
+ * Returns 'consequent', 'alternate', or null.
+ */
+export function isInsideIfBranch(
+  node: Parser.SyntaxNode
+): 'consequent' | 'alternate' | null {
+  let current: Parser.SyntaxNode | null = node.parent
+  while (current) {
+    if (current.parent?.type === 'if_statement') {
+      const ifStmt = current.parent
+      const consequence = ifStmt.childForFieldName('consequence')
+      const alternate = ifStmt.childForFieldName('alternative')
+
+      if (consequence && isDescendantOf(node, consequence)) return 'consequent'
+      if (alternate && isDescendantOf(node, alternate)) return 'alternate'
+    }
+    current = current.parent
+  }
+  return null
+}
+
+// ============================================================================
+// Dead Code Detection
+// ============================================================================
+
+/**
+ * Check if a node is after an unconditional return/throw in the same block.
+ */
+export function isDeadCode(node: Parser.SyntaxNode): boolean {
+  const block = getEnclosingBlock(node)
+  if (!block) return false
+
+  for (const child of block.namedChildren) {
+    if (child.startPosition.row >= node.startPosition.row) break
+    if (child.type === 'return_statement' || child.type === 'throw_statement') {
+      // Only unconditional: not inside an if
+      if (child.parent === block) return true
+    }
+  }
+
+  return false
+}
+
+// ============================================================================
+// Block Helpers
+// ============================================================================
+
+/**
+ * Get the nearest enclosing block statement (statement_block).
+ */
+export function getEnclosingBlock(node: Parser.SyntaxNode): Parser.SyntaxNode | null {
+  let current: Parser.SyntaxNode | null = node.parent
+  while (current) {
+    if (current.type === 'statement_block') return current
+    current = current.parent
+  }
+  return null
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+function isDescendantOf(node: Parser.SyntaxNode, ancestor: Parser.SyntaxNode): boolean {
+  let current: Parser.SyntaxNode | null = node
+  while (current) {
+    if (current.id === ancestor.id) return true
+    current = current.parent
+  }
+  return false
+}
+
+/**
+ * Check if a block has a terminating statement (return or throw).
+ */
+function hasTerminator(block: Parser.SyntaxNode): boolean {
+  for (const child of block.namedChildren) {
+    if (child.type === 'return_statement' || child.type === 'throw_statement') {
+      return true
+    }
+  }
+  return false
+}