@oculum/scanner 1.0.11 → 1.0.13

package/src/shared/category-filter.ts

@@ -0,0 +1,400 @@
+/**
+ * Category-Based Filtering
+ *
+ * Enables CI to fail only on specific vulnerability categories,
+ * allowing gradual rollout (e.g., "only block prompt injection")
+ * and fine-grained control over which findings are blocking.
+ *
+ * @example
+ * // Fail only on AI-related and secret categories
+ * --fail-on-categories ai-*,secrets-*
+ *
+ * @example
+ * // Combined with severity
+ * --fail-on high --fail-on-categories ai-*
+ * // Only fail on high+ AI findings
+ */
+
+import type { VulnerabilityCategory, Vulnerability, VulnerabilitySeverity } from './types'
+import { severityRank } from './parsed-file'
+
+/**
+ * Category group definitions for wildcard expansion
+ *
+ * These groups allow users to specify broad categories like "ai-*"
+ * which expand to all AI-related vulnerability categories.
+ */
+export const CATEGORY_GROUPS: Record<string, VulnerabilityCategory[]> = {
+  'ai-*': [
+    'ai_pattern',
+    'ai_prompt_injection',
+    'ai_unsafe_execution',
+    'ai_overpermissive_tool',
+    'ai_rag_exfiltration',
+    'ai_endpoint_unprotected',
+    'ai_schema_mismatch',
+    'ai_package_hallucination',
+    'ai_rag_corpus_poisoning',
+    'ai_rag_pii_leakage',
+    'ai_mcp_tool_poisoning',
+    'ai_mcp_credential_issue',
+    'ai_mcp_confused_deputy',
+    'ai_mcp_description_injection',
+    'ai_mcp_server_shadowing',
+    'ai_mcp_config_secrets',
+    'ai_mcp_config_permissions',
+    'ai_rag_query_injection',
+    'ai_rag_embedding_poisoning',
+    'ai_rag_chunk_injection',
+    'ai_package_typosquat',
+    'ai_package_malicious',
+    'ai_unsafe_model_load',
+    'ai_unverified_model',
+    'ai_unsafe_finetuning',
+    'ai_excessive_agency',
+  ],
+  'secrets-*': [
+    'hardcoded_secret',
+    'high_entropy_string',
+    'sensitive_variable',
+  ],
+  'owasp-*': [
+    'sql_injection',
+    'xss',
+    'command_injection',
+    'missing_auth',
+    'security_bypass',
+    'insecure_config',
+    'cors_misconfiguration',
+    'data_exposure',
+    'weak_crypto',
+  ],
+}
+
+/**
+ * All known valid category names for validation
+ */
+export const ALL_CATEGORIES: VulnerabilityCategory[] = [
+  'hardcoded_secret',
+  'high_entropy_string',
+  'sensitive_variable',
+  'security_bypass',
+  'dangerous_function',
+  'sql_injection',
+  'xss',
+  'command_injection',
+  'insecure_config',
+  'missing_auth',
+  'suspicious_package',
+  'cors_misconfiguration',
+  'root_container',
+  'dangerous_file',
+  'ai_pattern',
+  'sensitive_url',
+  'weak_crypto',
+  'data_exposure',
+  'ai_prompt_injection',
+  'ai_unsafe_execution',
+  'ai_overpermissive_tool',
+  'ai_rag_exfiltration',
+  'ai_endpoint_unprotected',
+  'ai_schema_mismatch',
+  'ai_package_hallucination',
+  'ai_rag_corpus_poisoning',
+  'ai_rag_pii_leakage',
+  'ai_mcp_tool_poisoning',
+  'ai_mcp_credential_issue',
+  'ai_mcp_confused_deputy',
+  'ai_mcp_description_injection',
+  'ai_mcp_server_shadowing',
+  'ai_mcp_config_secrets',
+  'ai_mcp_config_permissions',
+  'ai_rag_query_injection',
+  'ai_rag_embedding_poisoning',
+  'ai_rag_chunk_injection',
+  'ai_package_typosquat',
+  'ai_package_malicious',
+  'ai_unsafe_model_load',
+  'ai_unverified_model',
+  'ai_unsafe_finetuning',
+  'ai_excessive_agency',
+]
+
+/**
+ * Normalize category name for comparison
+ * - Converts to lowercase
+ * - Converts hyphens to underscores
+ * - Trims whitespace
+ *
+ * @example
+ * normalizeCategory('SQL-Injection') // 'sql_injection'
+ * normalizeCategory('high_entropy_string') // 'high_entropy_string'
+ */
+export function normalizeCategory(category: string): string {
+  return category
+    .toLowerCase()
+    .trim()
+    .replace(/-/g, '_')
+}
+
+/**
+ * Check if a string is a valid wildcard pattern
+ * Valid wildcards end with '-*' or '_*'
+ */
+function isWildcardPattern(pattern: string): boolean {
+  return pattern.endsWith('-*') || pattern.endsWith('_*')
+}
+
+/**
+ * Expand a wildcard pattern or single category to a list of categories
+ *
+ * @param pattern - Category name or wildcard (e.g., 'sql_injection', 'ai-*')
+ * @returns Array of matching categories
+ *
+ * @example
+ * expandCategoryPattern('ai-*') // Returns all ai_* categories
+ * expandCategoryPattern('sql_injection') // Returns ['sql_injection']
+ * expandCategoryPattern('unknown-*') // Returns []
+ */
+export function expandCategoryPattern(pattern: string): VulnerabilityCategory[] {
+  const normalized = normalizeCategory(pattern)
+
+  // Check for wildcard patterns
+  if (isWildcardPattern(normalized)) {
+    // Normalize the wildcard pattern (both ai-* and ai_* should work)
+    const normalizedWildcard = normalized.replace('_*', '-*')
+
+    // Look up in category groups
+    const expanded = CATEGORY_GROUPS[normalizedWildcard]
+    if (expanded) {
+      return [...expanded]
+    }
+
+    // Unknown wildcard - return empty
+    return []
+  }
+
+  // Single category - validate and return
+  // Handle both hyphenated and underscored versions
+  const normalizedCategory = normalized as VulnerabilityCategory
+  if (ALL_CATEGORIES.includes(normalizedCategory)) {
+    return [normalizedCategory]
+  }
+
+  // Try hyphenated version converted to underscore
+  const underscored = normalized.replace(/-/g, '_') as VulnerabilityCategory
+  if (ALL_CATEGORIES.includes(underscored)) {
+    return [underscored]
+  }
+
+  return []
+}
+
+/**
+ * Check if a category matches any pattern in the filter list
+ *
+ * @param category - The vulnerability category to check
+ * @param patterns - Array of category patterns (names or wildcards)
+ * @returns true if the category matches any pattern
+ *
+ * @example
+ * matchesAnyCategory('ai_prompt_injection', ['ai-*']) // true
+ * matchesAnyCategory('sql_injection', ['ai-*']) // false
+ * matchesAnyCategory('sql_injection', ['sql_injection', 'xss']) // true
+ */
+export function matchesAnyCategory(
+  category: VulnerabilityCategory,
+  patterns: string[]
+): boolean {
+  if (!patterns || patterns.length === 0) {
+    return false
+  }
+
+  const normalizedCategory = normalizeCategory(category)
+
+  for (const pattern of patterns) {
+    const expanded = expandCategoryPattern(pattern)
+
+    // Check if category is in the expanded list
+    if (expanded.some(c => normalizeCategory(c) === normalizedCategory)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+// severityRank imported from utils/parsed-file
+
+/**
+ * Check if vulnerabilities should cause failure based on category filter
+ *
+ * When both category patterns and severity threshold are provided,
+ * BOTH conditions must match for a finding to cause failure.
+ *
+ * @param vulnerabilities - List of vulnerabilities to check
+ * @param categoryPatterns - Category patterns to filter on
+ * @param severityThreshold - Optional severity threshold (both must match)
+ * @returns true if any vulnerability matches and should cause failure
+ *
+ * @example
+ * // Only fail on AI findings
+ * shouldFailOnCategories(vulns, ['ai-*'])
+ *
+ * @example
+ * // Only fail on HIGH+ AI findings
+ * shouldFailOnCategories(vulns, ['ai-*'], 'high')
+ */
+export function shouldFailOnCategories(
+  vulnerabilities: Vulnerability[],
+  categoryPatterns: string[],
+  severityThreshold?: VulnerabilitySeverity
+): boolean {
+  if (!vulnerabilities || vulnerabilities.length === 0) {
+    return false
+  }
+
+  if (!categoryPatterns || categoryPatterns.length === 0) {
+    return false
+  }
+
+  const thresholdRank = severityThreshold ? severityRank(severityThreshold) : 0
+
+  for (const vuln of vulnerabilities) {
+    // Check if category matches any pattern
+    if (!matchesAnyCategory(vuln.category, categoryPatterns)) {
+      continue
+    }
+
+    // If no severity threshold specified, any matching category triggers failure
+    if (!severityThreshold) {
+      return true
+    }
+
+    // Check if severity meets threshold
+    if (severityRank(vuln.severity) >= thresholdRank) {
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Get the categories that matched the filter from vulnerabilities
+ * Useful for error messages showing which categories caused failure
+ */
+export function getMatchingCategories(
+  vulnerabilities: Vulnerability[],
+  categoryPatterns: string[],
+  severityThreshold?: VulnerabilitySeverity
+): VulnerabilityCategory[] {
+  if (!vulnerabilities || vulnerabilities.length === 0) {
+    return []
+  }
+
+  if (!categoryPatterns || categoryPatterns.length === 0) {
+    return []
+  }
+
+  const thresholdRank = severityThreshold ? severityRank(severityThreshold) : 0
+  const matched = new Set<VulnerabilityCategory>()
+
+  for (const vuln of vulnerabilities) {
+    // Check if category matches any pattern
+    if (!matchesAnyCategory(vuln.category, categoryPatterns)) {
+      continue
+    }
+
+    // If no severity threshold, or severity meets threshold
+    if (!severityThreshold || severityRank(vuln.severity) >= thresholdRank) {
+      matched.add(vuln.category)
+    }
+  }
+
+  return Array.from(matched)
+}
+
+/**
+ * Parse comma-separated category string into array
+ *
+ * @param input - Comma-separated category string
+ * @returns Array of trimmed category patterns
+ *
+ * @example
+ * parseCategoryList('ai-*, secrets-*') // ['ai-*', 'secrets-*']
+ * parseCategoryList('sql_injection, xss') // ['sql_injection', 'xss']
+ */
+export function parseCategoryList(input: string): string[] {
+  if (!input || typeof input !== 'string') {
+    return []
+  }
+
+  return input
+    .split(',')
+    .map(s => s.trim())
+    .filter(s => s.length > 0)
+}
+
+/**
+ * Validate category names, separating valid from invalid
+ *
+ * @param categories - Array of category patterns to validate
+ * @returns Object with valid and invalid category arrays
+ *
+ * @example
+ * validateCategories(['ai-*', 'sql_injection', 'fake_category'])
+ * // { valid: ['ai-*', 'sql_injection'], invalid: ['fake_category'] }
+ */
+export function validateCategories(categories: string[]): {
+  valid: string[]
+  invalid: string[]
+} {
+  const valid: string[] = []
+  const invalid: string[] = []
+
+  for (const category of categories) {
+    const normalized = normalizeCategory(category)
+
+    // Check if it's a valid wildcard
+    if (isWildcardPattern(normalized)) {
+      const normalizedWildcard = normalized.replace('_*', '-*')
+      if (CATEGORY_GROUPS[normalizedWildcard]) {
+        valid.push(category)
+      } else {
+        invalid.push(category)
+      }
+      continue
+    }
+
+    // Check if it's a valid category name
+    const expanded = expandCategoryPattern(category)
+    if (expanded.length > 0) {
+      valid.push(category)
+    } else {
+      invalid.push(category)
+    }
+  }
+
+  return { valid, invalid }
+}
+
+/**
+ * Get a human-readable list of available category groups
+ * Useful for help text and error messages
+ */
+export function getAvailableCategoryGroups(): string[] {
+  return Object.keys(CATEGORY_GROUPS)
+}
+
+/**
+ * Get the count of categories in each group
+ * Useful for documentation and help text
+ */
+export function getCategoryGroupCounts(): Record<string, number> {
+  const counts: Record<string, number> = {}
+  for (const [group, categories] of Object.entries(CATEGORY_GROUPS)) {
+    counts[group] = categories.length
+  }
+  return counts
+}

package/src/{layer2/dangerous-functions/utils/control-flow.ts → shared/code-analysis.ts}

@@ -1,33 +1,30 @@
 /**
- * Control Flow Analysis Utilities
+ * Shared Code Analysis Utilities
  *
- * Functions for analyzing code control flow, including try-catch detection
- * and function context extraction.
+ * ParsedFile-aware versions of control flow analysis and context extraction.
+ * Consolidates duplicated logic from control-flow.ts and various detectors.
  */
 
-import { isComment } from '../../../utils/context-helpers'
+import { ParsedFile } from './parsed-file'
+import { isComment } from '../parse/file-classifier'
 
 /**
- * Check if a line is inside a try-catch block
- * Looks for enclosing try { ... } catch pattern
+ * Check if a line is inside a try-catch block.
+ * Tracks brace depth from the start of the file to the target line.
  */
-export function isInsideTryCatch(content: string, lineNumber: number): boolean {
-  const lines = content.split('\n')
+export function isInsideTryCatch(file: ParsedFile, lineNumber: number): boolean {
+  const lines = file.lines
 
-  // Track brace depth and whether we're in a try block
   let tryDepth = 0
   let inTryBlock = false
   const braceStack: Array<'try' | 'other'> = []
 
-  // Scan from start to the target line
   for (let i = 0; i < lineNumber && i < lines.length; i++) {
     const line = lines[i]
 
-    // Check for try keyword (not in a comment)
     if (/\btry\s*\{/.test(line) && !isComment(line)) {
       inTryBlock = true
       tryDepth++
-      // Count opening braces on this line
       const openBraces = (line.match(/\{/g) || []).length
       const closeBraces = (line.match(/\}/g) || []).length
       for (let j = 0; j < openBraces - closeBraces; j++) {
@@ -35,11 +32,9 @@ export function isInsideTryCatch(content: string, lineNumber: number): boolean {
       }
     } else if (/\bcatch\s*\(/.test(line) && !isComment(line)) {
       // Entering catch block - still protected
-      // Don't decrement tryDepth yet
     } else if (/\bfinally\s*\{/.test(line) && !isComment(line)) {
       // Entering finally block - still protected
     } else {
-      // Track regular braces
       const openBraces = (line.match(/\{/g) || []).length
       const closeBraces = (line.match(/\}/g) || []).length
 
@@ -63,11 +58,11 @@ export function isInsideTryCatch(content: string, lineNumber: number): boolean {
 }
 
 /**
- * Simpler heuristic: check if there's a try-catch in the same function scope
- * Looks for try { before the line and } catch after, within reasonable bounds
+ * Simpler heuristic: check if there's a try-catch in the same function scope.
+ * Looks for try { before the line and } catch after, within reasonable bounds.
  */
-export function hasTryCatchNearby(content: string, lineNumber: number, windowSize: number = 20): boolean {
-  const lines = content.split('\n')
+export function hasTryCatchNearby(file: ParsedFile, lineNumber: number, windowSize: number = 20): boolean {
+  const lines = file.lines
   const startLine = Math.max(0, lineNumber - windowSize)
   const endLine = Math.min(lines.length, lineNumber + windowSize)
 
@@ -79,7 +74,6 @@ export function hasTryCatchNearby(content: string, lineNumber: number, windowSiz
       foundTry = true
       break
     }
-    // Stop if we hit a function boundary
     if (/\b(function|async function|=>|class)\b/.test(line) && /\{/.test(line)) {
       break
     }
@@ -93,7 +87,6 @@ export function hasTryCatchNearby(content: string, lineNumber: number, windowSiz
     if (/\}\s*catch\s*\(/.test(line) && !isComment(line)) {
       return true
     }
-    // Stop if we hit another function boundary
     if (i > lineNumber && /\b(function|async function|class)\b/.test(line) && /\{/.test(line)) {
       break
     }
@@ -103,55 +96,48 @@ export function hasTryCatchNearby(content: string, lineNumber: number, windowSiz
 }
 
 /**
- * Extract function context where a call is being made
- * Looks backwards from the current line to find enclosing function name
- * Returns lowercase function name or null if not found
+ * Extract function context where a call is being made.
+ * Looks backwards from the current line to find enclosing function name.
+ * Returns lowercase function name or null if not found.
  */
-export function extractFunctionContext(content: string, lineNumber: number): string | null {
-  const lines = content.split('\n')
-  const start = Math.max(0, lineNumber - 20) // Increased from 10 to 20 for nested callbacks
+export function extractFunctionContext(file: ParsedFile, lineNumber: number): string | null {
+  const lines = file.lines
+  const start = Math.max(0, lineNumber - 20)
 
-  // Look backwards for function declaration
   for (let i = lineNumber; i >= start; i--) {
     const line = lines[i]
 
-    // Skip anonymous arrow functions in callbacks (e.g., .map((x) => ...), .replace(/x/g, (c) => ...))
-    // These are not the function context we're looking for
-    // Look for pattern: .methodName(..., (param) => or .methodName(...(param) =>
+    // Skip anonymous arrow functions in callbacks
     const hasMethodCallWithArrowCallback = /\.\w+\(.*\([^)]*\)\s*=>/.test(line)
-
-    // Skip lines that only have arrow callbacks in method calls
     if (hasMethodCallWithArrowCallback && !/^(const|let|var|function|async|export)/.test(line.trim())) {
       continue
     }
 
-    // Named function declaration: function funcName(
+    // Named function declaration
     const funcMatch = line.match(/function\s+(\w+)\s*\(/)
     if (funcMatch) {
       return funcMatch[1].toLowerCase()
     }
 
-    // Arrow function with const/let/var: const funcName = () => | const funcName = async () =>
-    // Must have => after the parameters to distinguish from const x = (expression)
-    // Also handles TypeScript return type annotations: const funcName = (): string =>
+    // Arrow function with const/let/var
     const arrowMatch = line.match(/(const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\([^)]*\)(?:\s*:\s*\w+)?\s*=>/)
     if (arrowMatch) {
       return arrowMatch[2].toLowerCase()
     }
 
-    // Method declaration: methodName() { or async methodName() {
+    // Method declaration
     const methodMatch = line.match(/^\s*(?:async\s+)?(\w+)\s*\([^)]*\)\s*\{/)
     if (methodMatch) {
       return methodMatch[1].toLowerCase()
     }
 
-    // Export function: export function funcName( or export const funcName = () =>
+    // Export function
     const exportFuncMatch = line.match(/export\s+(?:async\s+)?function\s+(\w+)\s*\(/)
     if (exportFuncMatch) {
       return exportFuncMatch[1].toLowerCase()
     }
 
-    // Also handles TypeScript return type annotations: export const funcName = (): string =>
+    // Export const arrow
     const exportConstMatch = line.match(/export\s+const\s+(\w+)\s*=\s*(?:async\s*)?\([^)]*\)(?:\s*:\s*\w+)?\s*=>/)
     if (exportConstMatch) {
       return exportConstMatch[1].toLowerCase()
@@ -160,3 +146,34 @@ export function extractFunctionContext(content: string, lineNumber: number): str
 
   return null
 }
+
+/**
+ * Search surrounding lines for any of the given patterns.
+ * Consolidates the ±N line search pattern used across 55+ occurrences.
+ *
+ * @param file ParsedFile to search in
+ * @param lineIndex 0-based center line
+ * @param patterns RegExp patterns to search for
+ * @param windowSize number of lines before and after to search
+ * @returns found: true if any pattern matched, with matched line and pattern
+ */
+export function searchSurroundingLines(
+  file: ParsedFile,
+  lineIndex: number,
+  patterns: RegExp[],
+  windowSize: number
+): { found: boolean; matchedLine?: number; matchedPattern?: RegExp } {
+  const startIndex = Math.max(0, lineIndex - windowSize)
+  const endIndex = Math.min(file.lineCount - 1, lineIndex + windowSize)
+
+  for (let i = startIndex; i <= endIndex; i++) {
+    const line = file.lines[i]
+    for (const pattern of patterns) {
+      if (pattern.test(line)) {
+        return { found: true, matchedLine: i, matchedPattern: pattern }
+      }
+    }
+  }
+
+  return { found: false }
+}