@oculum/scanner 1.0.11 → 1.0.13

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

@@ -0,0 +1,69 @@
+/**
+ * Next.js Framework Security Model
+ *
+ * App Router Server Components cannot access browser APIs (no DOM XSS).
+ * searchParams/params are user-controlled. Server Actions receive FormData.
+ */
+
+import type { FrameworkSecurityModel } from './types'
+
+const USE_CLIENT_RE = /['"]use client['"]/
+const SEARCH_PARAMS_RE = /searchParams/
+const PARAMS_RE = /\bparams\b/
+const FORM_DATA_RE = /FormData|formData/
+
+function isAppRouterServerComponent(filePath: string): boolean {
+  // Files in app/ directory without 'use client' at the top are Server Components
+  return /\/app\//.test(filePath) || /\\app\\/.test(filePath)
+}
+
+export const nextjsModel: FrameworkSecurityModel = {
+  framework: 'nextjs',
+
+  safePatterns: [
+    {
+      id: 'nextjs_server_component_no_dom',
+      suppressesCategory: ['xss', 'dangerous_function'],
+      detect: (_line: string, filePath: string, fileContent: string) => {
+        // Server Components can't access DOM — no client-side XSS
+        if (!isAppRouterServerComponent(filePath)) return false
+        // Check file extension is React
+        if (!/\.(tsx|jsx)$/.test(filePath)) return false
+        // Client Components have 'use client' — they ARE in the browser
+        if (USE_CLIENT_RE.test(fileContent)) return false
+        return true
+      },
+      reason: 'Next.js Server Component cannot access browser DOM — client-side XSS not applicable',
+    },
+  ],
+
+  unsafePatterns: [
+    {
+      id: 'nextjs_search_params_user_input',
+      boostsCategory: ['sql_injection', 'xss', 'command_injection', 'ssrf'],
+      detect: (line: string, _filePath: string, _fileContent: string) => SEARCH_PARAMS_RE.test(line),
+      reason: 'Next.js searchParams are user-controlled input — treat as untrusted',
+    },
+    {
+      id: 'nextjs_params_user_input',
+      boostsCategory: ['sql_injection', 'xss', 'command_injection', 'ssrf'],
+      detect: (line: string, _filePath: string, _fileContent: string) => {
+        // Only flag when it looks like destructuring or accessing params in a handler context
+        if (!PARAMS_RE.test(line)) return false
+        // Avoid false positives on generic variable names
+        return /\{\s*params\s*\}/.test(line) || /params\.\w+/.test(line)
+      },
+      reason: 'Next.js route params are user-controlled input',
+    },
+    {
+      id: 'nextjs_server_action_form_data',
+      boostsCategory: ['sql_injection', 'command_injection', 'xss'],
+      detect: (line: string, _filePath: string, fileContent: string) => {
+        // Only flag FormData usage in Server Action files
+        if (!/['"]use server['"]/.test(fileContent)) return false
+        return FORM_DATA_RE.test(line)
+      },
+      reason: 'Next.js Server Actions receive FormData — user-controlled input',
+    },
+  ],
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Prisma Framework Security Model
+ *
+ * Prisma Client methods (findMany, findFirst, create, etc.) are parameterised
+ * by default. $queryRaw with tagged templates is also safe.
+ * $queryRawUnsafe/$executeRawUnsafe and string concatenation bypass protections.
+ */
+
+import type { FrameworkSecurityModel } from './types'
+
+// Safe ORM patterns — Prisma methods are parameterised by default
+const PRISMA_METHOD_RE = /prisma\.\w+\.(findMany|findFirst|findUnique|findFirstOrThrow|findUniqueOrThrow|create|createMany|update|updateMany|upsert|delete|deleteMany|count|aggregate|groupBy)\s*\(/
+
+// $queryRaw with tagged template literal (Prisma.sql or template tag) is safe
+const PRISMA_TAGGED_RAW_RE = /\$queryRaw\s*`/
+
+// Unsafe patterns
+const PRISMA_UNSAFE_RAW_RE = /\$(queryRawUnsafe|executeRawUnsafe)\s*\(/
+const PRISMA_RAW_STRING_CONCAT_RE = /\$(queryRaw|executeRaw)\s*\([^`]*\+/
+
+export const prismaModel: FrameworkSecurityModel = {
+  framework: 'prisma',
+
+  safePatterns: [
+    {
+      id: 'orm_prisma_parameterised',
+      suppressesCategory: ['sql_injection', 'dangerous_function'],
+      detect: (line: string, _filePath: string, _fileContent: string) => PRISMA_METHOD_RE.test(line),
+      reason: 'Prisma Client methods use parameterised queries by default — SQL injection not applicable',
+    },
+    {
+      id: 'orm_prisma_tagged_raw',
+      suppressesCategory: ['sql_injection'],
+      detect: (line: string, _filePath: string, _fileContent: string) => PRISMA_TAGGED_RAW_RE.test(line),
+      reason: 'Prisma $queryRaw with tagged template literal is parameterised — SQL injection mitigated',
+    },
+  ],
+
+  unsafePatterns: [
+    {
+      id: 'prisma_unsafe_raw_concat',
+      boostsCategory: ['sql_injection'],
+      detect: (line: string, _filePath: string, _fileContent: string) => PRISMA_UNSAFE_RAW_RE.test(line),
+      reason: '$queryRawUnsafe/$executeRawUnsafe accepts raw SQL strings — SQL injection risk',
+    },
+    {
+      id: 'prisma_raw_string_concat',
+      boostsCategory: ['sql_injection'],
+      detect: (line: string, _filePath: string, _fileContent: string) => {
+        // Only flag when concatenation is used (not tagged templates)
+        if (PRISMA_TAGGED_RAW_RE.test(line)) return false
+        return PRISMA_RAW_STRING_CONCAT_RE.test(line)
+      },
+      reason: '$queryRaw/$executeRaw with string concatenation bypasses parameterisation — SQL injection risk',
+    },
+  ],
+}

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

@@ -0,0 +1,63 @@
+/**
+ * React/JSX Framework Security Model
+ *
+ * React auto-escapes JSX expressions by default, preventing XSS.
+ * dangerouslySetInnerHTML and ref.innerHTML bypass this protection.
+ */
+
+import type { FrameworkSecurityModel } from './types'
+
+const JSX_EXPRESSION_RE = /\{[^}]+\}/
+const DANGEROUS_INNER_HTML_RE = /dangerouslySetInnerHTML/
+const REF_INNER_HTML_RE = /\.current\.innerHTML\s*=/
+const CREATE_ELEMENT_RE = /React\.createElement\s*\(/
+
+export const reactModel: FrameworkSecurityModel = {
+  framework: 'react',
+
+  safePatterns: [
+    {
+      id: 'react_jsx_auto_escape',
+      suppressesCategory: ['xss', 'dangerous_function'],
+      detect: (line: string, filePath: string, _fileContent: string) => {
+        // Only applies to JSX files
+        if (!/\.(jsx|tsx)$/.test(filePath)) return false
+        // Require JSX context: a JSX tag or return with JSX on the line
+        const hasJSXContext = /<[A-Za-z][\w.]*/.test(line) || /return\s*\(?\s*</.test(line)
+        if (!hasJSXContext) return false
+        // JSX expression interpolation auto-escapes
+        if (!JSX_EXPRESSION_RE.test(line)) return false
+        // Unless it's dangerouslySetInnerHTML
+        if (DANGEROUS_INNER_HTML_RE.test(line)) return false
+        return true
+      },
+      reason: 'React JSX auto-escapes interpolated expressions — not an XSS vector',
+    },
+    {
+      id: 'react_create_element_safe',
+      suppressesCategory: ['xss'],
+      detect: (line: string, _filePath: string, _fileContent: string) => {
+        // React.createElement with string children is auto-escaped
+        if (!CREATE_ELEMENT_RE.test(line)) return false
+        if (DANGEROUS_INNER_HTML_RE.test(line)) return false
+        return true
+      },
+      reason: 'React.createElement auto-escapes string children',
+    },
+  ],
+
+  unsafePatterns: [
+    {
+      id: 'react_dangerous_inner_html',
+      boostsCategory: ['xss'],
+      detect: (line: string, _filePath: string, _fileContent: string) => DANGEROUS_INNER_HTML_RE.test(line),
+      reason: 'dangerouslySetInnerHTML bypasses React auto-escaping — XSS risk if input is unsanitised',
+    },
+    {
+      id: 'react_ref_inner_html',
+      boostsCategory: ['xss'],
+      detect: (line: string, _filePath: string, _fileContent: string) => REF_INNER_HTML_RE.test(line),
+      reason: 'Direct ref.innerHTML assignment bypasses React virtual DOM escaping',
+    },
+  ],
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Sequelize Framework Security Model
+ *
+ * Sequelize ORM methods (findAll, findOne, create, update, destroy) are
+ * parameterised by default. Raw queries with template literals are unsafe.
+ */
+
+import type { FrameworkSecurityModel } from './types'
+
+// Safe ORM patterns
+const SEQUELIZE_ORM_RE = /\.(findAll|findOne|findByPk|findOrCreate|create|update|destroy|bulkCreate|count|sum|max|min)\s*\(/
+const SEQUELIZE_REPLACEMENTS_RE = /sequelize\.query\s*\([^)]*replacements\s*:/
+
+// Unsafe raw query patterns
+const SEQUELIZE_RAW_TEMPLATE_RE = /sequelize\.query\s*\(\s*`/
+const SEQUELIZE_RAW_CONCAT_RE = /sequelize\.query\s*\([^)]*\+/
+const SEQUELIZE_LITERAL_RE = /Sequelize\.literal\s*\(/
+
+export const sequelizeModel: FrameworkSecurityModel = {
+  framework: 'sequelize',
+
+  safePatterns: [
+    {
+      id: 'orm_sequelize_parameterised',
+      suppressesCategory: ['sql_injection', 'dangerous_function'],
+      detect: (line: string, _filePath: string, _fileContent: string) => SEQUELIZE_ORM_RE.test(line),
+      reason: 'Sequelize ORM methods use parameterised queries — SQL injection not applicable',
+    },
+    {
+      id: 'orm_sequelize_replacements',
+      suppressesCategory: ['sql_injection'],
+      detect: (line: string, _filePath: string, _fileContent: string) => SEQUELIZE_REPLACEMENTS_RE.test(line),
+      reason: 'sequelize.query() with replacements is parameterised — SQL injection mitigated',
+    },
+  ],
+
+  unsafePatterns: [
+    {
+      id: 'sequelize_raw_template',
+      boostsCategory: ['sql_injection'],
+      detect: (line: string, _filePath: string, _fileContent: string) => {
+        if (SEQUELIZE_REPLACEMENTS_RE.test(line)) return false
+        return SEQUELIZE_RAW_TEMPLATE_RE.test(line)
+      },
+      reason: 'sequelize.query() with template literal is raw SQL — NOT parameterised',
+    },
+    {
+      id: 'sequelize_raw_concat',
+      boostsCategory: ['sql_injection'],
+      detect: (line: string, _filePath: string, _fileContent: string) => {
+        if (SEQUELIZE_REPLACEMENTS_RE.test(line)) return false
+        return SEQUELIZE_RAW_CONCAT_RE.test(line)
+      },
+      reason: 'sequelize.query() with string concatenation is raw SQL — NOT parameterised',
+    },
+    {
+      id: 'sequelize_literal_injection',
+      boostsCategory: ['sql_injection'],
+      detect: (line: string, _filePath: string, _fileContent: string) => SEQUELIZE_LITERAL_RE.test(line),
+      reason: 'Sequelize.literal() injects raw SQL expressions — injection risk with user input',
+    },
+  ],
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Framework Security Model Types
+ *
+ * Interfaces for encoding framework-specific security guarantees.
+ * Each framework model declares safe patterns (suppress findings)
+ * and unsafe patterns (boost findings).
+ */
+
+export interface FrameworkSecurityModel {
+  /** Which framework this model covers */
+  framework: string
+  /** Patterns that are safe by design — suppress findings */
+  safePatterns: FrameworkSafePattern[]
+  /** Patterns that are unsafe despite framework — boost findings */
+  unsafePatterns: FrameworkUnsafePattern[]
+}
+
+export interface FrameworkSafePattern {
+  /** Rule identifier */
+  id: string
+  /** What vulnerability categories this suppresses */
+  suppressesCategory: string[]
+  /** Detect the safe pattern on a line */
+  detect: (lineContent: string, filePath: string, fileContent: string) => boolean
+  /** Human-readable explanation for scoring/AI */
+  reason: string
+}
+
+export interface FrameworkUnsafePattern {
+  /** Rule identifier */
+  id: string
+  /** What vulnerability categories this boosts */
+  boostsCategory: string[]
+  /** Detect the unsafe pattern on a line */
+  detect: (lineContent: string, filePath: string, fileContent: string) => boolean
+  /** Human-readable explanation */
+  reason: string
+}
+
+/** Per-file framework analysis result */
+export interface FileFrameworkAnalysis {
+  /** Which safe patterns matched lines in this file */
+  safeLines: Map<number, FrameworkSafePattern[]>
+  /** Which unsafe patterns matched lines in this file */
+  unsafeLines: Map<number, FrameworkUnsafePattern[]>
+}

package/src/model/function-classifier.ts

@@ -0,0 +1,184 @@
+/**
+ * Function Classifier — Analyze exported functions to determine dangerous operations.
+ *
+ * For each exported function, extracts its body and scans for sink patterns
+ * and source patterns to build a security profile. Used by cross-file taint
+ * analysis to determine if calling an imported function can reach a sink.
+ */
+
+import type { ScanFile } from '../shared/types'
+import type { ParsedExport } from './import-resolver'
+import type { ModuleGraph } from './module-graph'
+import type { SinkType, UserInputSourceType } from './taint-types'
+import { extractBlock } from './route-discovery/utils'
+import { SINK_PATTERNS, escapeRegex } from './sink-patterns'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ExportedFunctionProfile {
+  name: string
+  filePath: string
+  reachesSinks: SinkType[]
+  returnsUserData: boolean
+  returnSourceType?: UserInputSourceType  // which user-input source the return expression matches
+  hasSanitisation: boolean
+  paramNames: string[]
+  dangerousParams: string[]      // params that appear on sink-pattern lines
+  line: number
+}
+
+export type FunctionProfileMap = Map<string, ExportedFunctionProfile[]>  // filePath → profiles
+
+// Source patterns indicating the function returns user data, with associated source types
+const RETURN_SOURCE_PATTERNS: Array<{ pattern: RegExp; sourceType: UserInputSourceType }> = [
+  { pattern: /return\s+.*\breq\.body\b/, sourceType: 'http_body' },
+  { pattern: /return\s+.*\breq\.query\b/, sourceType: 'http_query' },
+  { pattern: /return\s+.*\breq\.params\b/, sourceType: 'http_params' },
+  { pattern: /return\s+.*\brequest\.args\b/, sourceType: 'http_query' },
+  { pattern: /return\s+.*\brequest\.form\b/, sourceType: 'form_data' },
+  { pattern: /return\s+.*\brequest\.json\b/, sourceType: 'http_body' },
+  { pattern: /return\s+.*\brequest\.GET\b/, sourceType: 'http_query' },
+  { pattern: /return\s+.*\brequest\.POST\b/, sourceType: 'http_body' },
+  { pattern: /return\s+.*\bsearchParams\b/, sourceType: 'url_search_params' },
+  { pattern: /return\s+.*\bformData\b/, sourceType: 'form_data' },
+]
+
+// Sanitiser patterns
+const SANITISER_PATTERNS = [
+  /\bsanitize\w*\s*\(/i,
+  /\bescape\w*\s*\(/i,
+  /\bDOMPurify\.sanitize\s*\(/,
+  /\.parse\s*\(/,  // zod, joi
+  /\.validate\s*\(/,
+  /\bNumber\s*\(/,
+  /\bparseInt\s*\(/,
+  /\bparseFloat\s*\(/,
+  /\bpath\.normalize\s*\(/,
+]
+
+// ============================================================================
+// Function Classification
+// ============================================================================
+
+/**
+ * Classify exported functions in a file by their security profile.
+ */
+export function classifyExportedFunctions(
+  content: string,
+  filePath: string,
+  fileExports: ParsedExport[]
+): ExportedFunctionProfile[] {
+  const profiles: ExportedFunctionProfile[] = []
+  const lines = content.split('\n')
+
+  for (const exp of fileExports) {
+    if (exp.kind !== 'function' && exp.kind !== 'variable') continue
+
+    // Extract function body
+    const startLine = Math.max(0, exp.line - 1)
+    const body = extractBlock(lines, startLine)
+    if (!body || body.length < 5) continue
+
+    // Extract parameter names from the function signature
+    const paramNames = extractParamNames(lines[startLine] || '')
+
+    // Scan body for sinks
+    const bodyLines = body.split('\n')
+    const sinkTypes = new Set<SinkType>()
+    const dangerousParams = new Set<string>()
+
+    for (const bodyLine of bodyLines) {
+      const trimmed = bodyLine.trim()
+      if (trimmed.startsWith('//') || trimmed.startsWith('*')) continue
+
+      for (const sp of SINK_PATTERNS) {
+        if (sp.pattern.test(bodyLine)) {
+          sinkTypes.add(sp.sinkType)
+
+          // Check which params appear on this sink line
+          for (const param of paramNames) {
+            const paramRegex = new RegExp(`\\b${escapeRegex(param)}\\b`)
+            if (paramRegex.test(bodyLine)) {
+              dangerousParams.add(param)
+            }
+          }
+        }
+      }
+    }
+
+    // Check if function returns user data and extract source type
+    const matchedReturnSource = RETURN_SOURCE_PATTERNS.find(p => p.pattern.test(body))
+    const returnsUserData = !!matchedReturnSource
+    const returnSourceType = matchedReturnSource?.sourceType
+
+    // Check for sanitisation
+    const hasSanitisation = SANITISER_PATTERNS.some(p => p.test(body))
+
+    if (sinkTypes.size > 0 || returnsUserData) {
+      profiles.push({
+        name: exp.name,
+        filePath,
+        reachesSinks: [...sinkTypes],
+        returnsUserData,
+        returnSourceType,
+        hasSanitisation,
+        paramNames,
+        dangerousParams: [...dangerousParams],
+        line: exp.line,
+      })
+    }
+  }
+
+  return profiles
+}
+
+/**
+ * Build function profiles for all files that are imported by at least one other file.
+ */
+export function buildFunctionProfiles(
+  files: ScanFile[],
+  graph: ModuleGraph
+): FunctionProfileMap {
+  const profileMap: FunctionProfileMap = new Map()
+
+  for (const file of files) {
+    const node = graph.nodes.get(file.path)
+    if (!node) continue
+    // Only process files that are imported by at least one other file
+    if (node.importedBy.size === 0) continue
+    if (node.exports.length === 0) continue
+
+    const profiles = classifyExportedFunctions(file.content, file.path, node.exports)
+    if (profiles.length > 0) {
+      profileMap.set(file.path, profiles)
+    }
+  }
+
+  return profileMap
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function extractParamNames(signatureLine: string): string[] {
+  // Match function params: function foo(a, b, c) or (a, b) => or async (a: Type, b) =>
+  const paramMatch = signatureLine.match(/\(([^)]*)\)/)
+  if (!paramMatch) return []
+
+  return paramMatch[1]
+    .split(',')
+    .map(p => {
+      // Strip type annotations, defaults, destructuring braces
+      const cleaned = p.trim()
+        .replace(/\s*[:=].*/g, '')  // remove type annotations and defaults
+        .replace(/[{}[\]]/g, '')     // remove destructuring
+        .replace(/\.\.\./g, '')      // remove spread
+        .trim()
+      return cleaned
+    })
+    .filter(p => p.length > 0 && /^\w+$/.test(p))
+}
+