@oculum/scanner 1.0.11 → 1.0.13

package/src/{utils/context-helpers.ts → parse/file-classifier.ts}

@@ -8,6 +8,15 @@
 // File Path Context Detection
 // ============================================================================
 
+/**
+ * Check if file is in a tooling/scripts directory
+ * Files in these directories are typically build tools, CLI utilities, or dev scripts
+ * and should have reduced severity for findings like file path patterns
+ */
+export function isToolingDirectory(filePath: string): boolean {
+  return /\/(scripts?|cli|tools?|bin|devtools|build|tasks)\//i.test(filePath)
+}
+
 /**
  * Check if file is server-only (not bundled to client)
  * Server-only files can safely use service role keys and other admin secrets
@@ -44,6 +53,7 @@ export function isTestOrMockFile(filePath: string): boolean {
     /\/__tests__\//i,
     /\/test\//i,
     /\/tests\//i,
+    /\/testing\//i,                           // testing directories (e.g., docker/testing/)
     /\/mock/i,
     /\/mocks\//i,
     /\/fixtures?\//i,
@@ -158,6 +168,46 @@ export function isDocumentationFile(filePath: string): boolean {
   return docPatterns.some(pattern => pattern.test(filePath))
 }
 
+/**
+ * Check if file is a locale/i18n/translation file
+ * These files contain natural language translations, not code, and should be skipped entirely
+ * They often contain placeholder URLs (http://localhost) and other patterns that trigger false positives
+ */
+export function isLocaleFile(filePath: string): boolean {
+  const lowerPath = filePath.toLowerCase()
+
+  // Directory-based detection
+  if (
+    lowerPath.includes('/locales/') ||
+    lowerPath.includes('/locale/') ||
+    lowerPath.includes('/i18n/') ||
+    lowerPath.includes('/translations/') ||
+    lowerPath.includes('/translation/') ||
+    lowerPath.includes('/lang/') ||
+    lowerPath.includes('/languages/') ||
+    lowerPath.includes('/messages/') ||
+    lowerPath.includes('/intl/')
+  ) {
+    return true
+  }
+
+  // File naming patterns (language codes)
+  // e.g., en.json, zh-CN.json, pt-BR.json, messages.en.json
+  const localeFilePatterns = [
+    // Direct language code files: en.json, zh-CN.json, pt-BR.json
+    /\/(en|fr|de|es|it|pt|ja|ko|zh|ru|ar|nl|pl|tr|vi|th|id|ms|hi|bn|uk|el|he|fa|sv|no|da|fi|cs|sk|hu|ro|bg|sr|hr|sl|ca|eu|gl|et|lv|lt|mk|sq|is|mt|ga|cy|af|sw|zu|xh|am|ne|si|km|lo|my|ka|hy|az|uz|kk|ky|tg|tk|mn|bo|dz)(-[a-z]{2,4})?\.json$/i,
+    // Prefixed language files: messages.en.json, strings.zh-CN.json
+    /\/(messages|strings|labels|text|content|copy)\.[a-z]{2}(-[a-z]{2,4})?\.json$/i,
+    // Common locale file names
+    /\/translation\.json$/i,
+    /\/translations\.json$/i,
+    /\/messages\.json$/i,
+    /\/strings\.json$/i,
+  ]
+
+  return localeFilePatterns.some(pattern => pattern.test(lowerPath))
+}
+
 /**
  * Check if file is scanner code, fixture, or rule definition
  * Avoid flagging the scanner's own code/test cases
@@ -245,6 +295,213 @@ export function isEducationalVulnerabilityFile(filePath: string): boolean {
   return patterns.some(p => p.test(filePath))
 }
 
+/**
+ * Check if file is a test configuration file
+ * These files (jest.config, vitest.config, etc.) are always dev/test contexts
+ * Localhost URLs and similar patterns should not be flagged in these files
+ */
+export function isTestConfigFile(filePath: string): boolean {
+  const testConfigPatterns = [
+    /jest\.config\.[jt]s$/i,
+    /jest\.config\.mjs$/i,
+    /vitest\.config\.[jt]s$/i,
+    /vitest\.config\.mts$/i,
+    /cypress\.config\.[jt]s$/i,
+    /cypress\.config\.mjs$/i,
+    /playwright\.config\.[jt]s$/i,
+    /playwright\.config\.mts$/i,
+    /karma\.conf\.[jt]s$/i,
+    /\.mocharc\.[jt]s$/i,
+    /\.mocharc\.json$/i,
+    /setupTests\.[jt]s$/i,
+    /setupTests\.tsx?$/i,
+    /test\.setup\.[jt]s$/i,
+    /jest\.setup\.[jt]s$/i,
+    /vitest\.setup\.[jt]s$/i,
+    /testEnvironment\.[jt]s$/i,
+    /globalSetup\.[jt]s$/i,
+    /globalTeardown\.[jt]s$/i,
+    /ava\.config\.[jt]s$/i,
+    /nyc\.config\.js$/i,  // Code coverage config
+  ]
+  return testConfigPatterns.some(pattern => pattern.test(filePath))
+}
+
+/**
+ * Check if file is a Python file
+ */
+export function isPythonFile(filePath: string): boolean {
+  return /\.py$/i.test(filePath)
+}
+
+/**
+ * Check if a line is inside a Python docstring
+ * Python docstrings are delimited by triple quotes (''' or """)
+ * Content inside docstrings (like example URLs, connection strings) should be ignored
+ *
+ * @param lines - Array of all lines in the file
+ * @param lineIndex - The 0-indexed line number to check
+ * @returns true if the line is inside a docstring
+ */
+export function isInsidePythonDocstring(
+  lines: string[],
+  lineIndex: number
+): boolean {
+  let inDocstring = false
+  let docstringChar: '"""' | "'''" | null = null
+
+  for (let i = 0; i <= lineIndex; i++) {
+    const line = lines[i]
+
+    // Count triple quote occurrences in this line
+    // We need to track both """ and '''
+    const tripleDoubleCount = (line.match(/"""/g) || []).length
+    const tripleSingleCount = (line.match(/'''/g) || []).length
+
+    // Process triple double quotes
+    for (let j = 0; j < tripleDoubleCount; j++) {
+      if (!inDocstring) {
+        inDocstring = true
+        docstringChar = '"""'
+      } else if (docstringChar === '"""') {
+        inDocstring = false
+        docstringChar = null
+      }
+    }
+
+    // Process triple single quotes
+    for (let j = 0; j < tripleSingleCount; j++) {
+      if (!inDocstring) {
+        inDocstring = true
+        docstringChar = "'''"
+      } else if (docstringChar === "'''") {
+        inDocstring = false
+        docstringChar = null
+      }
+    }
+  }
+
+  return inDocstring
+}
+
+// ============================================================================
+// Desktop/Electron App Context Detection
+// ============================================================================
+
+/**
+ * Check if file is in a desktop app context (Electron, Tauri, etc.)
+ * Desktop apps legitimately access filesystem and spawn processes,
+ * so findings in these contexts should have reduced severity.
+ *
+ * Used by:
+ * - Dynamic file path detection (downgrade to INFO)
+ * - child_process detection (downgrade to MEDIUM)
+ */
+export function isDesktopAppContext(filePath: string): boolean {
+  const desktopPatterns = [
+    // Directory patterns
+    /\/apps\/desktop\//i,
+    /\/electron\//i,
+    /\/tauri\//i,
+    /\/src-electron\//i,
+    /\/src-tauri\//i,
+    /\/desktop-app\//i,
+    /\/desktop\//i,
+
+    // File patterns (Electron conventions)
+    /\/main\.(ts|js)$/i, // Main process
+    /\/preload\.(ts|js)$/i, // Preload scripts
+    /\/ipc[A-Z]\w*\.(ts|js)$/i, // IPC handlers
+    /Ctr\.(ts|js)$/i, // Controller pattern
+
+    // Package patterns
+    /packages\/.*electron/i,
+    /packages\/.*desktop/i,
+  ]
+  return desktopPatterns.some(p => p.test(filePath))
+}
+
+/**
+ * Check if file is an MCP (Model Context Protocol) server
+ * MCP servers legitimately spawn processes to provide tool capabilities
+ */
+export function isMcpServerContext(filePath: string): boolean {
+  const mcpPatterns = [
+    /mcp/i,
+    /model-context-protocol/i,
+    /\/servers?\//i, // Common MCP server directory structure
+  ]
+  return mcpPatterns.some(p => p.test(filePath))
+}
+
+/**
+ * Check if file is a file loader/processor
+ * File loaders legitimately access filesystem to process files
+ */
+export function isFileLoaderContext(filePath: string): boolean {
+  const loaderPatterns = [
+    /file-loaders?\//i,
+    /loaders?\/(pdf|docx|excel|text|csv|xml|json)/i,
+    /document-loaders?\//i,
+    /parsers?\//i,
+  ]
+  return loaderPatterns.some(p => p.test(filePath))
+}
+
+// ============================================================================
+// Agent Skill File Detection
+// ============================================================================
+
+/**
+ * Check if file is an AI agent skill/configuration file
+ * These files define agent behavior and are targets for prompt injection,
+ * data exfiltration, and hidden execution attacks.
+ *
+ * Note: Root CLAUDE.md is NOT matched. Only .claude/commands/, .claude/skills/,
+ * .claude/tools/ subdirectories are flagged.
+ */
+export function isAgentSkillFile(filePath: string): boolean {
+  const skillPatterns = [
+    // Skill definition files
+    /\/SKILL\.md$/i,
+    /\/AGENTS\.md$/i,
+    /\/skills\.json$/i,
+    /\/skills\.ya?ml$/i,
+    /\/agent\.ya?ml$/i,
+    /\/agent\.config\./i,
+    /\/agent-skills\//i,
+    /\/tools\.json$/i,
+
+    // Cursor
+    /\/\.cursor\/rules\//i,
+    /\/\.cursorrules$/i,
+
+    // Claude (skill-specific paths, NOT root CLAUDE.md)
+    /\/\.claude\/commands\//i,
+    /\/\.claude\/skills\//i,
+    /\/\.claude\/tools\//i,
+
+    // GitHub Copilot
+    /\/\.github\/copilot-instructions\.md$/i,
+    /\/\.github\/agents\//i,
+
+    // Moltbot/OpenClaw
+    /\/\.moltbot\//i,
+    /\/moltbot\.config\./i,
+    /\/\.openclaw\//i,
+
+    // Aider
+    /\/\.aider/i,
+
+    // MCP configs (complements existing config-mcp-audit.ts)
+    /\/mcp\.json$/i,
+    /\/mcp-config\.json$/i,
+    /\/\.mcp\//i,
+    /\/claude[-_]desktop[-_]config\.json$/i,
+  ]
+  return skillPatterns.some(p => p.test(filePath))
+}
+
 // ============================================================================
 // Code Line Context Detection
 // ============================================================================
@@ -273,7 +530,7 @@ export function isNextPublicEnvVar(line: string): boolean {
 }
 
 /**
- * Check if line is a comment
+ * Check if line is a comment (single-line check)
  */
 export function isComment(lineContent: string): boolean {
   const trimmed = lineContent.trim()
@@ -288,6 +545,140 @@ export function isComment(lineContent: string): boolean {
   )
 }
 
+/**
+ * Check if a line is inside a multi-line comment block
+ * Used to properly skip code that's been commented out
+ *
+ * @param lines - Array of all lines in the file
+ * @param lineIndex - The 0-indexed line number to check
+ * @returns true if the line is inside a multi-line comment
+ */
+export function isInsideMultiLineComment(
+  lines: string[],
+  lineIndex: number
+): boolean {
+  let inComment = false
+
+  for (let i = 0; i <= lineIndex; i++) {
+    const line = lines[i]
+
+    // Check for comment start/end in this line
+    // Handle multiple occurrences in same line
+    let searchStart = 0
+    while (searchStart < line.length) {
+      const openIdx = line.indexOf('/*', searchStart)
+      const closeIdx = line.indexOf('*/', searchStart)
+
+      if (!inComment) {
+        // Not in comment - look for opening
+        if (openIdx !== -1 && (closeIdx === -1 || openIdx < closeIdx)) {
+          inComment = true
+          searchStart = openIdx + 2
+          continue
+        }
+      } else {
+        // In comment - look for closing
+        if (closeIdx !== -1 && (openIdx === -1 || closeIdx < openIdx)) {
+          inComment = false
+          searchStart = closeIdx + 2
+          continue
+        }
+      }
+      break
+    }
+  }
+
+  return inComment
+}
+
+/**
+ * Check if a line is commented out code (either single-line or multi-line comment)
+ * Combines single-line and multi-line comment detection
+ *
+ * @param lines - Array of all lines in the file
+ * @param lineIndex - The 0-indexed line number to check
+ * @returns true if the line is commented out
+ */
+export function isCommentedOutCode(
+  lines: string[],
+  lineIndex: number
+): boolean {
+  const line = lines[lineIndex]
+  if (!line) return false
+
+  // Check single-line comment
+  if (isComment(line)) {
+    return true
+  }
+
+  // Check if inside multi-line comment block
+  if (isInsideMultiLineComment(lines, lineIndex)) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Check if a line has a linter/security ignore comment
+ * These comments indicate the developer has acknowledged and accepted the risk
+ *
+ * @param lines - Array of all lines in the file
+ * @param lineIndex - The 0-indexed line number to check
+ * @returns object with hasIgnore flag and the ignore type if found
+ */
+export function hasLinterIgnoreComment(
+  lines: string[],
+  lineIndex: number
+): { hasIgnore: boolean; ignoreType?: string } {
+  // Check current line and previous line for ignore comments
+  const linesToCheck = [
+    lines[lineIndex],
+    lineIndex > 0 ? lines[lineIndex - 1] : '',
+  ]
+
+  const ignorePatterns = [
+    // ESLint
+    { pattern: /eslint-disable-next-line/i, type: 'eslint' },
+    { pattern: /eslint-disable-line/i, type: 'eslint' },
+    { pattern: /eslint-disable\s/i, type: 'eslint' },
+
+    // Biome
+    { pattern: /biome-ignore/i, type: 'biome' },
+
+    // TypeScript
+    { pattern: /@ts-ignore/i, type: 'typescript' },
+    { pattern: /@ts-expect-error/i, type: 'typescript' },
+    { pattern: /@ts-nocheck/i, type: 'typescript' },
+
+    // Security scanners
+    { pattern: /nosec/i, type: 'security' },
+    { pattern: /nolint/i, type: 'security' },
+    { pattern: /# noqa/i, type: 'security' },  // Python
+    { pattern: /# type:\s*ignore/i, type: 'mypy' },
+    { pattern: /NOSONAR/i, type: 'sonar' },
+    { pattern: /SuppressWarnings/i, type: 'java' },
+    { pattern: /pragma:\s*no cover/i, type: 'coverage' },
+
+    // Prettier
+    { pattern: /prettier-ignore/i, type: 'prettier' },
+
+    // Stylelint
+    { pattern: /stylelint-disable/i, type: 'stylelint' },
+  ]
+
+  for (const line of linesToCheck) {
+    if (!line) continue
+    for (const { pattern, type } of ignorePatterns) {
+      if (pattern.test(line)) {
+        return { hasIgnore: true, ignoreType: type }
+      }
+    }
+  }
+
+  return { hasIgnore: false }
+}
+
 /**
  * Check if value/line appears to be a placeholder
  */
@@ -306,9 +697,23 @@ export function isPlaceholderValue(value: string, line: string): boolean {
     /fixme/i,
   ]
 
+  // Common test passwords that appear in connection strings
+  // e.g., postgres://user:password@host:5432/db
+  const testPasswordPatterns = [
+    /:password@/i,           // user:password@ in connection strings
+    /:secret@/i,             // user:secret@
+    /:test@/i,               // user:test@
+    /:admin@/i,              // user:admin@
+    /:root@/i,               // user:root@
+    /:123456@/i,             // user:123456@
+    /:postgres@/i,           // postgres:postgres@
+    /:mysql@/i,              // mysql:mysql@
+    /:redis@/i,              // redis:redis@
+  ]
+
   return placeholderPatterns.some(pattern =>
     pattern.test(value) || pattern.test(line)
-  )
+  ) || testPasswordPatterns.some(pattern => pattern.test(value))
 }
 
 // ============================================================================
@@ -577,3 +982,58 @@ export function getServiceRoleKeyContext(
   // Hardcoded or ambiguous = needs review
   return 'needs_review'
 }
+
+// ============================================================================
+// File Context for Layer 2 Detectors (Phase 2b)
+// ============================================================================
+
+/**
+ * File-specific context for Layer 2 detectors
+ * Provides per-file classification for context-aware detection
+ */
+export interface FileContext {
+  /** Whether this file is server-only (not bundled to client) */
+  isServerOnly: boolean
+  /** Whether this file is client-bundled (exposed to browser) */
+  isClientBundled: boolean
+  /** Whether this file is a test/mock/fixture file */
+  isTestFile: boolean
+  /** Whether this file is a config file */
+  isConfigFile: boolean
+  /** Whether this file is in a tooling directory */
+  isToolingDir: boolean
+}
+
+/**
+ * Check if file is a configuration file
+ */
+export function isConfigFile(filePath: string): boolean {
+  const configPatterns = [
+    /config\.(ts|js|json|yaml|yml)$/i,
+    /settings\.(ts|js|json)$/i,
+    /constants\.(ts|js)$/i,
+    /\.config\.(ts|js|mjs|cjs)$/i,
+    /\.env/i,
+    /tsconfig\.json$/i,
+    /package\.json$/i,
+    /jest\.config/i,
+    /vitest\.config/i,
+    /eslint/i,
+    /prettier/i,
+  ]
+  return configPatterns.some(p => p.test(filePath))
+}
+
+/**
+ * Build file-specific context for a single file
+ * Used by Layer 2 detectors for context-aware detection
+ */
+export function buildFileContext(filePath: string): FileContext {
+  return {
+    isServerOnly: isServerOnlyFile(filePath),
+    isClientBundled: isClientBundledFile(filePath),
+    isTestFile: isTestOrMockFile(filePath),
+    isConfigFile: isConfigFile(filePath),
+    isToolingDir: isToolingDirectory(filePath),
+  }
+}

package/src/{utils → parse}/path-exclusions.ts

@@ -4,7 +4,7 @@
  * to reduce false positives in security scans.
  */
 
-import type { Vulnerability, VulnerabilityCategory } from '../types'
+import type { Vulnerability, VulnerabilityCategory } from '../shared/types'
 
 export interface ExclusionConfig {
   testPatterns: string[]

package/src/pipeline/config.ts

@@ -0,0 +1,81 @@
+/**
+ * Pipeline Configuration — Scan options and mode resolution.
+ *
+ * Handles both scan mode (full/incremental) and depth (local/verified/deep).
+ */
+
+import type {
+  ScanMode,
+  ScanModeConfig,
+  ScanDepth,
+  CancellationToken,
+  ProgressCallback,
+} from '../shared/types'
+import { SCAN_MODE_DEFAULTS } from '../shared/types'
+
+export interface ScanOptions {
+  /** Enable AI-powered validation and analysis */
+  enableAI?: boolean
+  /** Maximum files to scan */
+  maxFiles?: number
+  /** Branch being scanned */
+  branch?: string
+  /** Scan mode configuration (full vs incremental) */
+  scanMode?: ScanMode | ScanModeConfig
+  /** Scan depth (cheap/validated/deep) - controls AI usage */
+  scanDepth?: ScanDepth
+  /** Suppress console.log output (for interactive CLI mode) */
+  quiet?: boolean
+  /** Cancellation token for aborting scans gracefully */
+  cancellationToken?: CancellationToken
+  /** Project path for loading suppression config (defaults to cwd) */
+  projectPath?: string
+  /** Include suppressed findings in output (for --show-suppressed) */
+  showSuppressed?: boolean
+  /** Include filter audit trail in output (for debugging/explaining dismissals) */
+  includeFilterAudit?: boolean
+}
+
+/**
+ * Resolve scan mode configuration from options
+ *
+ * Handles both scan mode (full/incremental) and depth (local/verified/deep).
+ * Depth controls AI usage:
+ * - local: skip AI validation + skip Layer 3
+ * - verified: run AI validation, skip Layer 3
+ * - deep: run AI validation + Layer 3
+ */
+export function resolveScanModeConfig(options: ScanOptions): ScanModeConfig {
+  const scanModeOption = options.scanMode
+
+  // Determine base mode
+  const mode: ScanMode = !scanModeOption ? 'full'
+    : typeof scanModeOption === 'string' ? scanModeOption
+    : scanModeOption.mode
+
+  const defaults = SCAN_MODE_DEFAULTS[mode]
+
+  // Build config from defaults + explicit overrides
+  let config: ScanModeConfig = {
+    ...defaults,
+    mode,
+    ...(typeof scanModeOption === 'object' ? scanModeOption : {}),
+  }
+
+  // Apply depth mode (default: 'local')
+  const depth = options.scanDepth ?? 'local'
+  config.scanDepth = depth
+
+  // Map depth to skipAIValidation/skipLayer3 unless explicitly overridden
+  const hasExplicitSkipAI = typeof scanModeOption === 'object' && scanModeOption.skipAIValidation !== undefined
+  const hasExplicitSkipL3 = typeof scanModeOption === 'object' && scanModeOption.skipLayer3 !== undefined
+
+  if (!hasExplicitSkipAI) {
+    config.skipAIValidation = depth === 'local'
+  }
+  if (!hasExplicitSkipL3) {
+    config.skipLayer3 = depth !== 'deep'
+  }
+
+  return config
+}