@oculum/scanner 1.0.10 → 1.0.12

package/src/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 './utils/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/filtering/__tests__/pipeline.test.ts

@@ -0,0 +1,134 @@
+import { FilterPipeline } from '../pipeline'
+import type { FilterDecision } from '../pipeline'
+
+describe('FilterPipeline', () => {
+  describe('when disabled', () => {
+    it('does not record decisions', () => {
+      const pipeline = new FilterPipeline(false)
+      pipeline.record('finding-1', {
+        stage: 'auto_dismiss',
+        action: 'dismissed',
+        reason: 'test file',
+      })
+      expect(pipeline.getAuditTrail()).toEqual([])
+    })
+
+    it('reports isEnabled as false', () => {
+      expect(new FilterPipeline(false).isEnabled).toBe(false)
+      expect(new FilterPipeline().isEnabled).toBe(false)
+    })
+  })
+
+  describe('when enabled', () => {
+    let pipeline: FilterPipeline
+
+    beforeEach(() => {
+      pipeline = new FilterPipeline(true)
+    })
+
+    it('reports isEnabled as true', () => {
+      expect(pipeline.isEnabled).toBe(true)
+    })
+
+    it('records and retrieves decisions', () => {
+      const decision: FilterDecision = {
+        stage: 'auto_dismiss',
+        action: 'dismissed',
+        reason: 'test file detected',
+        ruleName: 'test_file_dismiss',
+      }
+      pipeline.record('finding-1', decision)
+
+      const trail = pipeline.getAuditTrail()
+      expect(trail).toHaveLength(1)
+      expect(trail[0].findingId).toBe('finding-1')
+      expect(trail[0].decisions).toEqual([decision])
+      expect(trail[0].finalStatus).toBe('dismissed')
+    })
+
+    it('accumulates multiple decisions for the same finding', () => {
+      pipeline.record('finding-1', {
+        stage: 'file_context_adjustment',
+        action: 'downgraded',
+        reason: 'tooling directory',
+        originalSeverity: 'medium',
+        newSeverity: 'info',
+      })
+      pipeline.record('finding-1', {
+        stage: 'ai_validation',
+        action: 'kept',
+        reason: 'AI confirmed the finding',
+      })
+
+      const decisions = pipeline.explainDismissal('finding-1')
+      expect(decisions).toHaveLength(2)
+      expect(decisions[0].stage).toBe('file_context_adjustment')
+      expect(decisions[1].stage).toBe('ai_validation')
+    })
+
+    it('marks final status as surfaced when no dismissal', () => {
+      pipeline.record('finding-1', {
+        stage: 'ai_validation',
+        action: 'kept',
+        reason: 'confirmed',
+      })
+
+      const trail = pipeline.getAuditTrail()
+      expect(trail[0].finalStatus).toBe('surfaced')
+    })
+
+    it('marks final status as dismissed for deduplicated findings', () => {
+      pipeline.record('finding-1', {
+        stage: 'deduplication',
+        action: 'deduplicated',
+        reason: 'duplicate of finding-2',
+      })
+
+      const trail = pipeline.getAuditTrail()
+      expect(trail[0].finalStatus).toBe('dismissed')
+    })
+
+    it('marks final status as dismissed for suppressed findings', () => {
+      pipeline.record('finding-1', {
+        stage: 'user_suppression',
+        action: 'suppressed',
+        reason: 'inline oculum-ignore comment',
+      })
+
+      const trail = pipeline.getAuditTrail()
+      expect(trail[0].finalStatus).toBe('dismissed')
+    })
+
+    it('returns empty array for unknown finding in explainDismissal', () => {
+      expect(pipeline.explainDismissal('nonexistent')).toEqual([])
+    })
+  })
+
+  describe('getSummaryStats', () => {
+    it('aggregates counts per stage and action', () => {
+      const pipeline = new FilterPipeline(true)
+
+      pipeline.record('f1', { stage: 'auto_dismiss', action: 'dismissed', reason: 'test' })
+      pipeline.record('f2', { stage: 'auto_dismiss', action: 'dismissed', reason: 'css' })
+      pipeline.record('f3', { stage: 'auto_dismiss', action: 'kept', reason: 'real finding' })
+      pipeline.record('f4', { stage: 'ai_validation', action: 'downgraded', reason: 'lower severity' })
+      pipeline.record('f5', { stage: 'deduplication', action: 'deduplicated', reason: 'dup' })
+
+      const stats = pipeline.getSummaryStats()
+
+      expect(stats.auto_dismiss.dismissed).toBe(2)
+      expect(stats.auto_dismiss.kept).toBe(1)
+      expect(stats.ai_validation.downgraded).toBe(1)
+      expect(stats.deduplication.deduplicated).toBe(1)
+      expect(stats.localhost_aggregation.dismissed).toBe(0)
+    })
+
+    it('returns zero counts when no decisions recorded', () => {
+      const pipeline = new FilterPipeline(true)
+      const stats = pipeline.getSummaryStats()
+
+      expect(stats.auto_dismiss.dismissed).toBe(0)
+      expect(stats.tier_filter.kept).toBe(0)
+    })
+  })
+})

package/src/filtering/context-adjustments.ts

@@ -0,0 +1,111 @@
+/**
+ * Centralized Context-Based Severity Adjustments
+ *
+ * Consolidates the duplicate filter logic from:
+ * - layer2/index.ts applyFileContextAdjustments() — per-file with full FileContext
+ * - index.ts applyGlobalContextAdjustments() — post-layers with tooling-dir only
+ *
+ * Both functions are replaced by a single applyContextAdjustments() that handles
+ * all context-based severity downgrades in one place.
+ */
+
+import type { Vulnerability } from '../types'
+import type { FileContext } from '../utils/context-helpers'
+
+/** Categories that are expected and not risky in tooling directories */
+const TOOLING_DOWNGRADABLE_CATEGORIES = [
+  'dangerous_function',   // exec, spawn, etc. are expected in scripts
+  'command_injection',    // child_process usage is expected in build scripts
+  'weak_crypto',          // Math.random() for seeding is fine in scripts
+  'data_exposure',        // Logging is expected in tooling
+  'ai_pattern',           // AI patterns in scripts are typically fine
+]
+
+/** Categories that are expected and not risky in test files */
+const TEST_DOWNGRADABLE_CATEGORIES = [
+  'ai_pattern',
+  'dangerous_function',
+  'sensitive_variable',
+  'data_exposure',
+]
+
+/**
+ * Apply context-based severity adjustments to findings.
+ *
+ * When called with a FileContext (from Layer 2 per-file processing), applies
+ * full context-aware rules: test files, tooling dirs, server-only files.
+ *
+ * When called without a FileContext (from the orchestrator for Layer 1 findings),
+ * applies only tooling-directory downgrades based on file path.
+ */
+export function applyContextAdjustments(
+  findings: Vulnerability[],
+  fileContext?: FileContext
+): Vulnerability[] {
+  return findings.map(finding => {
+    // Never downgrade critical findings
+    if (finding.severity === 'critical') {
+      return finding
+    }
+
+    if (fileContext) {
+      // Full per-file context available (Layer 2 path)
+
+      // Test files: Downgrade specific categories
+      if (fileContext.isTestFile) {
+        if (TEST_DOWNGRADABLE_CATEGORIES.includes(finding.category)) {
+          return {
+            ...finding,
+            severity: 'info' as const,
+            validationNotes: 'Downgraded: test/fixture file',
+          }
+        }
+      }
+
+      // Tooling directories: Downgrade expected patterns
+      if (fileContext.isToolingDir) {
+        if (TOOLING_DOWNGRADABLE_CATEGORIES.includes(finding.category)) {
+          return {
+            ...finding,
+            severity: 'info' as const,
+            validationNotes: 'Downgraded: tooling/scripts directory',
+          }
+        }
+      }
+
+      // Server-only files: Client-exposure concerns don't apply
+      if (fileContext.isServerOnly) {
+        if (finding.category === 'hardcoded_secret' &&
+            finding.title.toLowerCase().includes('service role')) {
+          return {
+            ...finding,
+            severity: 'info' as const,
+            validationNotes: 'Downgraded: server-only file (service role key expected)',
+          }
+        }
+      }
+    } else {
+      // No file context — apply path-based adjustments only (orchestrator path)
+      // This catches Layer 1 findings that didn't go through Layer 2's per-file adjustments
+      const inToolingDir = isToolingPath(finding.filePath)
+
+      if (inToolingDir && TOOLING_DOWNGRADABLE_CATEGORIES.includes(finding.category)) {
+        return {
+          ...finding,
+          severity: 'info' as const,
+          validationNotes: `${finding.validationNotes || ''} Downgraded: tooling/scripts directory`.trim(),
+        }
+      }
+    }
+
+    return finding
+  })
+}
+
+/**
+ * Tooling-path check for findings without FileContext.
+ * Uses the same regex as utils/context-helpers.ts isToolingDirectory().
+ */
+function isToolingPath(filePath: string): boolean {
+  return /\/(scripts?|cli|tools?|bin|devtools|build|tasks)\//i.test(filePath)
+}

package/src/filtering/index.ts

@@ -0,0 +1,10 @@
+export {
+  FilterPipeline,
+  type FilterStage,
+  type FilterAction,
+  type FilterDecision,
+  type AnnotatedFinding,
+  type FilterStageSummary,
+} from './pipeline'
+
+export { applyContextAdjustments } from './context-adjustments'