@oculum/scanner 1.0.12 → 1.0.13

package/src/report/summary.ts

@@ -0,0 +1,70 @@
+/**
+ * Report Summary — Sorting and counting utilities for scan results.
+ *
+ * Pure functions extracted from the orchestrator. No cross-stage dependencies.
+ */
+
+import type {
+  Vulnerability,
+  SeverityCounts,
+  CategoryCounts,
+  VulnerabilityCategory,
+} from '../shared/types'
+import { severityRank, confidenceRank } from '../shared/parsed-file'
+
+/**
+ * Sort vulnerabilities by severity (critical first)
+ */
+export function sortBySeverity(vulnerabilities: Vulnerability[]): Vulnerability[] {
+  return [...vulnerabilities].sort((a, b) => {
+    const severityDiff = severityRank(b.severity) - severityRank(a.severity)
+    if (severityDiff !== 0) return severityDiff
+
+    // Secondary sort by confidence
+    return confidenceRank(b.confidence) - confidenceRank(a.confidence)
+  })
+}
+
+/**
+ * Compute severity counts from vulnerabilities
+ */
+export function computeSeverityCounts(vulnerabilities: Vulnerability[]): SeverityCounts {
+  const counts: SeverityCounts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 }
+
+  for (const vuln of vulnerabilities) {
+    if (vuln.severity in counts) {
+      counts[vuln.severity]++
+    }
+  }
+
+  return counts
+}
+
+/**
+ * Compute category counts from vulnerabilities
+ */
+export function computeCategoryCounts(vulnerabilities: Vulnerability[]): CategoryCounts {
+  const counts: CategoryCounts = {}
+
+  for (const vuln of vulnerabilities) {
+    const category = vuln.category as VulnerabilityCategory
+    counts[category] = (counts[category] || 0) + 1
+  }
+
+  return counts
+}
+
+/**
+ * Helper to compute counts from vulnerabilities (for backfilling legacy scans)
+ */
+export function computeIssueMixFromVulnerabilities(vulnerabilities: Vulnerability[]): {
+  severityCounts: SeverityCounts
+  categoryCounts: CategoryCounts
+  hasBlockingIssues: boolean
+} {
+  const severityCounts = computeSeverityCounts(vulnerabilities)
+  const categoryCounts = computeCategoryCounts(vulnerabilities)
+  const hasBlockingIssues = severityCounts.critical > 0 || severityCounts.high > 0
+
+  return { severityCounts, categoryCounts, hasBlockingIssues }
+}

package/src/score/adjustments.ts

@@ -0,0 +1,387 @@
+/**
+ * Confidence Adjustment Rules
+ *
+ * Data-driven list of all adjustment rules, organized by concern.
+ * Each rule has a name, source, applies() predicate, delta, and reason.
+ *
+ * Rules are evaluated against every finding; all matching rules
+ * contribute their delta to the final confidence score.
+ */
+
+import type { Vulnerability } from '../shared/types'
+import type { AdjustmentRule, AdjustmentContext } from './types'
+import {
+  isTestOrMockFile,
+  isExampleFile,
+  isScannerOrFixtureFile,
+  isToolingDirectory,
+  isServerOnlyFile,
+  isEnvVarReference,
+  isPublicEndpoint,
+  isComment,
+} from '../parse/file-classifier'
+
+// ============================================================================
+// File Context Rules (active now)
+// ============================================================================
+
+const FILE_CONTEXT_RULES: AdjustmentRule[] = [
+  {
+    name: 'test_file',
+    source: 'file_context',
+    applies: (finding: Vulnerability, ctx: AdjustmentContext) =>
+      isTestOrMockFile(finding.filePath),
+    delta: -0.35,
+    reason: 'Finding in test/mock file',
+  },
+  {
+    name: 'example_file',
+    source: 'file_context',
+    applies: (finding: Vulnerability, ctx: AdjustmentContext) =>
+      isExampleFile(finding.filePath),
+    delta: -0.30,
+    reason: 'Finding in example/demo file',
+  },
+  {
+    name: 'doc_file',
+    source: 'file_context',
+    applies: (finding: Vulnerability) =>
+      /\.(md|mdx|txt|rst)$/i.test(finding.filePath),
+    delta: -0.30,
+    reason: 'Finding in documentation file',
+  },
+  {
+    name: 'scanner_code',
+    source: 'file_context',
+    applies: (finding: Vulnerability) =>
+      isScannerOrFixtureFile(finding.filePath),
+    delta: -0.30,
+    reason: 'Finding in scanner/fixture code',
+  },
+  {
+    name: 'tooling_dir',
+    source: 'file_context',
+    applies: (finding: Vulnerability) =>
+      isToolingDirectory(finding.filePath),
+    delta: -0.25,
+    reason: 'Finding in tooling/scripts directory',
+  },
+  {
+    name: 'config_env_substitution',
+    source: 'file_context',
+    applies: (finding: Vulnerability) => {
+      if (finding.category !== 'hardcoded_secret' && finding.category !== 'high_entropy_string') {
+        return false
+      }
+      return isEnvVarReference(finding.lineContent)
+    },
+    delta: -0.15,
+    reason: 'Uses environment variable (not hardcoded)',
+  },
+  {
+    name: 'comment_context',
+    source: 'file_context',
+    applies: (finding: Vulnerability) => {
+      if (finding.category === 'ai_pattern') return false
+      return isComment(finding.lineContent)
+    },
+    delta: -0.20,
+    reason: 'Code comment (not executable)',
+  },
+  {
+    name: 'server_only_client_finding',
+    source: 'file_context',
+    applies: (finding: Vulnerability) => {
+      if (finding.category !== 'xss') return false
+      return isServerOnlyFile(finding.filePath)
+    },
+    delta: -0.10,
+    reason: 'XSS finding in server-only file',
+  },
+  {
+    name: 'client_bundled_server_finding',
+    source: 'file_context',
+    applies: (finding: Vulnerability, ctx: AdjustmentContext) => {
+      const serverOnlyCategories = [
+        'missing_auth', 'missing_authorization',
+        'data_exposure', 'sql_injection',
+        'command_injection', 'ssrf',
+      ]
+      if (!serverOnlyCategories.includes(finding.category)) return false
+      if (!ctx.file.isClientBundled) return false
+      // Exclude Next.js page files — App Router pages are server components
+      // by default and Pages Router pages can have getServerSideProps.
+      // Only penalise clearly client-only paths.
+      const ambiguousPageFile =
+        /\/pages\//i.test(finding.filePath) ||
+        /\/app\/.*page\.(ts|tsx|js|jsx)$/i.test(finding.filePath)
+      return !ambiguousPageFile
+    },
+    delta: -0.30,
+    reason: 'Server-side concern in client-bundled file (browser code)',
+  },
+]
+
+// ============================================================================
+// Auto-Dismiss Equivalent Rules (active now)
+// Mirrors current score/auto-dismiss.ts behavior using confidence deltas
+// ============================================================================
+
+const AUTO_DISMISS_RULES: AdjustmentRule[] = [
+  {
+    name: 'css_class_pattern',
+    source: 'auto_dismiss',
+    applies: (finding: Vulnerability) => {
+      if (finding.category !== 'high_entropy_string') return false
+      const cssIndicators = ['flex', 'grid', 'text-', 'bg-', 'px-', 'py-', 'rounded', 'shadow', 'hover:', 'dark:']
+      const lowerLine = finding.lineContent.toLowerCase()
+      const matchCount = cssIndicators.filter(ind => lowerLine.includes(ind)).length
+      return matchCount >= 2
+    },
+    delta: -0.40,
+    reason: 'CSS/Tailwind classes (not a secret)',
+  },
+  {
+    name: 'health_check_endpoint',
+    source: 'auto_dismiss',
+    applies: (finding: Vulnerability) => {
+      if (finding.category !== 'missing_auth') return false
+      return isPublicEndpoint(finding.lineContent, finding.filePath)
+    },
+    delta: -0.35,
+    reason: 'Public health check endpoint (auth not required)',
+  },
+  {
+    name: 'info_severity_low_priority',
+    source: 'auto_dismiss',
+    applies: (finding: Vulnerability) => {
+      if (finding.severity !== 'info') return false
+      // Use baseConfidence >= 0.35 instead of getTierForCategory
+      // This replaces the tier-based 'info_severity_core_only' rule
+      return (finding.baseConfidence ?? 0) >= 0.35
+    },
+    delta: -0.15,
+    reason: 'Already info severity for high-confidence detector (low priority)',
+  },
+  {
+    name: 'low_severity_ai_pattern',
+    source: 'auto_dismiss',
+    applies: (finding: Vulnerability) => {
+      if (finding.category !== 'ai_pattern') return false
+      return finding.severity === 'info' || finding.severity === 'low'
+    },
+    delta: -0.10,
+    reason: 'Low-severity AI pattern (code quality, not security)',
+  },
+  {
+    name: 'generic_message',
+    source: 'auto_dismiss',
+    applies: (finding: Vulnerability) => {
+      if (finding.category !== 'ai_pattern') return false
+      const genericPatterns = [
+        /['"`](success|done|ok|completed|finished|saved|updated|deleted|created)['"`]/i,
+        /['"`]something went wrong['"`]/i,
+        /['"`]an error occurred['"`]/i,
+        /console\.(log|info|debug)\s*\(\s*['"`][^'"]+['"`]\s*\)/i,
+      ]
+      return genericPatterns.some(p => p.test(finding.lineContent))
+    },
+    delta: -0.25,
+    reason: 'Generic UI message (not security-relevant)',
+  },
+  {
+    name: 'type_definition_any',
+    source: 'auto_dismiss',
+    applies: (finding: Vulnerability) => {
+      if (finding.category !== 'ai_pattern') return false
+      if (!finding.title.toLowerCase().includes('any')) return false
+      if (finding.filePath.includes('.d.ts')) return true
+      const typeDefPatterns = [/^type\s+\w+\s*=/, /^interface\s+\w+/, /declare\s+(const|let|var|function|class)/]
+      return typeDefPatterns.some(p => p.test(finding.lineContent.trim()))
+    },
+    delta: -0.25,
+    reason: 'Type definition (not runtime code)',
+  },
+  {
+    name: 'timeout_magic_number',
+    source: 'auto_dismiss',
+    applies: (finding: Vulnerability) => {
+      if (finding.category !== 'ai_pattern') return false
+      return /set(Timeout|Interval)\s*\([^,]+,\s*\d+\s*\)/.test(finding.lineContent)
+    },
+    delta: -0.20,
+    reason: 'Timeout value (code style, not security)',
+  },
+  {
+    name: 'data_config_file_secret',
+    source: 'auto_dismiss',
+    applies: (finding: Vulnerability) => {
+      if (finding.category !== 'high_entropy_string' && finding.category !== 'hardcoded_secret') {
+        return false
+      }
+      return /\.(yml|yaml|json|toml|ini|cfg)$/i.test(finding.filePath) &&
+             !/\.(env|secret|credential)/i.test(finding.filePath)
+    },
+    delta: -0.15,
+    reason: 'Secret finding in data/config file (often static content, not credentials)',
+  },
+]
+
+// ============================================================================
+// Future Context Engine Rules (empty arrays — structurally present)
+// ============================================================================
+
+/** Taint analysis rules — Context Engine Phase 1 */
+const TAINT_RULES: AdjustmentRule[] = [
+  {
+    name: 'confirmed_taint_unsanitised',
+    source: 'taint',
+    applies: (_finding: Vulnerability, ctx: AdjustmentContext) =>
+      ctx.taint?.confirmed === true && !ctx.taint.sanitised && ctx.taint.confidence !== 'low',
+    delta: +0.35,
+    reason: 'Confirmed taint path from user input (no sanitisation)',
+  },
+  {
+    name: 'confirmed_taint_sanitised',
+    source: 'taint',
+    applies: (_finding: Vulnerability, ctx: AdjustmentContext) =>
+      ctx.taint?.confirmed === true && ctx.taint.sanitised === true,
+    delta: +0.15,
+    reason: 'Confirmed taint path from user input (sanitised)',
+  },
+  {
+    name: 'no_taint_path',
+    source: 'taint',
+    applies: (finding: Vulnerability, ctx: AdjustmentContext) => {
+      const sinkCategories = ['dangerous_function', 'sql_injection', 'xss', 'command_injection', 'ssrf', 'data_exposure']
+      if (!sinkCategories.includes(finding.category)) return false
+      return ctx.taint !== undefined && ctx.taint.confirmed === false
+    },
+    delta: -0.10,
+    reason: 'No taint path found (static data reaches sink)',
+  },
+  {
+    name: 'low_confidence_taint',
+    source: 'taint',
+    applies: (_finding: Vulnerability, ctx: AdjustmentContext) =>
+      ctx.taint?.confirmed === true && !ctx.taint.sanitised && ctx.taint.confidence === 'low',
+    delta: +0.10,
+    reason: 'Low-confidence taint path (long chain or indirect)',
+  },
+]
+
+/** Auth-related categories where route auth context matters */
+const AUTH_RELATED_CATEGORIES = new Set([
+  'missing_auth', 'missing_authorization', 'data_exposure',
+  'sql_injection', 'command_injection', 'ssrf',
+  'xss', 'dangerous_function', 'xxe',
+  'ai_unsafe_execution', 'ai_endpoint_unprotected', 'ai_rag_exfiltration',
+])
+
+/** Route/auth context rules — Context Engine Phase 2 */
+const ROUTE_RULES: AdjustmentRule[] = [
+  {
+    name: 'no_auth_on_route',
+    source: 'route',
+    applies: (finding: Vulnerability, ctx: AdjustmentContext) => {
+      if (!ctx.route) return false
+      if (!AUTH_RELATED_CATEGORIES.has(finding.category)) return false
+      return !ctx.route.hasAuth && !ctx.route.isPublic
+    },
+    delta: +0.15,
+    reason: 'Route has no auth middleware and is not explicitly public',
+  },
+  {
+    name: 'has_auth_on_route',
+    source: 'route',
+    applies: (_finding: Vulnerability, ctx: AdjustmentContext) =>
+      ctx.route?.hasAuth === true,
+    delta: -0.15,
+    reason: 'Route is protected by auth middleware',
+  },
+  {
+    name: 'public_route',
+    source: 'route',
+    applies: (finding: Vulnerability, ctx: AdjustmentContext) => {
+      if (finding.category !== 'missing_auth') return false
+      return ctx.route?.isPublic === true
+    },
+    delta: -0.25,
+    reason: 'Route is an explicitly public endpoint (health, status, etc.)',
+  },
+  {
+    name: 'mutation_route',
+    source: 'route',
+    applies: (_finding: Vulnerability, ctx: AdjustmentContext) => {
+      if (!ctx.route) return false
+      const mutationMethods = ['POST', 'PUT', 'DELETE', 'PATCH']
+      return ctx.route.methods.some(m => mutationMethods.includes(m))
+    },
+    delta: +0.05,
+    reason: 'Route handles mutation methods (POST/PUT/DELETE/PATCH)',
+  },
+  {
+    name: 'rate_limited_route',
+    source: 'route',
+    applies: (_finding: Vulnerability, ctx: AdjustmentContext) =>
+      ctx.route?.hasRateLimiting === true,
+    delta: -0.05,
+    reason: 'Route has rate limiting applied',
+  },
+]
+
+/** Framework-specific rules — Context Engine Phase 5 */
+const FRAMEWORK_RULES: AdjustmentRule[] = [
+  {
+    name: 'framework_auto_protects',
+    source: 'framework',
+    applies: (_finding: Vulnerability, ctx: AdjustmentContext) => {
+      if (!ctx.framework?.safePatternMatch) return false
+      // ORM patterns are handled by orm_safe_query — avoid stacking
+      return !ctx.framework.safePatternMatch.id.startsWith('orm_')
+    },
+    delta: -0.30,
+    reason: 'Framework auto-protects against this vulnerability type',
+  },
+  {
+    name: 'framework_unsafe_pattern',
+    source: 'framework',
+    applies: (_finding: Vulnerability, ctx: AdjustmentContext) =>
+      ctx.framework?.unsafePatternMatch != null,
+    delta: +0.10,
+    reason: 'Finding uses a framework-unsafe pattern',
+  },
+  {
+    name: 'orm_safe_query',
+    source: 'framework',
+    applies: (finding: Vulnerability, ctx: AdjustmentContext) => {
+      if (finding.category !== 'sql_injection' && finding.category !== 'dangerous_function') return false
+      if (!ctx.framework?.orm) return false
+      return ctx.framework.safePatternMatch?.id.startsWith('orm_') ?? false
+    },
+    delta: -0.25,
+    reason: 'ORM parameterises this query pattern by default',
+  },
+]
+
+// ============================================================================
+// Combined Export
+// ============================================================================
+
+/** All active adjustment rules, evaluated in order */
+export const ALL_ADJUSTMENT_RULES: AdjustmentRule[] = [
+  ...FILE_CONTEXT_RULES,
+  ...AUTO_DISMISS_RULES,
+  ...TAINT_RULES,
+  ...ROUTE_RULES,
+  ...FRAMEWORK_RULES,
+]
+
+// Named exports for testing individual rule groups
+export {
+  FILE_CONTEXT_RULES,
+  AUTO_DISMISS_RULES,
+  TAINT_RULES,
+  ROUTE_RULES,
+  FRAMEWORK_RULES,
+}

package/src/{layer3/anthropic → score}/auto-dismiss.ts

@@ -5,8 +5,8 @@
  * These rules catch obvious false positives before sending to AI.
  */
 
-import type { Vulnerability } from '../../types'
-import type { AutoDismissRule } from './types'
+import type { Vulnerability } from '../shared/types'
+import type { AutoDismissRule } from '../validate/types'
 import {
   isTestOrMockFile,
   isExampleFile,
@@ -14,8 +14,8 @@ import {
   isEnvVarReference,
   isPublicEndpoint,
   isComment,
-} from '../../utils/context-helpers'
-import { getTierForCategory } from '../../tiers'
+} from '../parse/file-classifier'
+// getTierForCategory removed in Phase 2B — confidence scoring handles routing
 
 // ============================================================================
 // Auto-Dismiss Rules
@@ -97,19 +97,16 @@ const AUTO_DISMISS_RULES: AutoDismissRule[] = [
   },
 
   // Info severity already - no need to validate
-  // BUT: Only auto-dismiss info-severity for Tier A (core) findings
-  // Tier B (ai_assisted) findings MUST go through AI validation even at info severity
-  // because detectors may have pre-downgraded them based on partial context
+  // Only auto-dismiss info-severity for high-confidence detectors (baseConfidence >= 0.35)
+  // Low-confidence detectors should still go through AI validation
   {
     name: 'info_severity_core_only',
     check: (finding) => {
       if (finding.severity !== 'info') return false
-      // Only auto-dismiss info-severity for Tier A (core) findings
-      // Tier B should always go through AI for proper validation
-      const tier = getTierForCategory(finding.category, finding.layer)
-      return tier === 'core'
+      // Use baseConfidence instead of tier lookup (Phase 2B)
+      return (finding.baseConfidence ?? 0) >= 0.35
     },
-    reason: 'Already info severity for core detector (low priority)',
+    reason: 'Already info severity for high-confidence detector (low priority)',
   },
 
   // Generic success/error messages in ai_pattern
@@ -177,8 +174,12 @@ const VALIDATION_ONLY_RULES = new Set([
 ])
 
 /**
- * Apply smart auto-dismiss rules to filter obvious false positives
- * Returns findings that should be sent to AI validation
+ * Apply smart auto-dismiss rules to filter obvious false positives.
+ * Returns findings that should be sent to AI validation.
+ *
+ * @deprecated Phase 2B — Confidence scoring adjustments now handle auto-dismiss.
+ *   This function is kept for external consumers but is no longer called
+ *   from the orchestrator. Will be removed in a follow-up cleanup PR.
  *
  * @param findings - Array of vulnerabilities to filter
  * @param mode - 'validation' applies all rules (for AI validation candidates),

package/src/score/confidence.ts

@@ -0,0 +1,66 @@
+/**
+ * Confidence Score Computation
+ *
+ * Single function that computes a finding's confidence score from
+ * baseConfidence + sum(applicable adjustments), then routes by thresholds.
+ */
+
+import type { Vulnerability } from '../shared/types'
+import type {
+  ConfidenceComputation,
+  ConfidenceAdjustment,
+  AdjustmentRule,
+  AdjustmentContext,
+  DepthConfig,
+} from './types'
+
+/** Default base confidence when detector doesn't set baseConfidence */
+const DEFAULT_BASE_CONFIDENCE = 0.35
+
+/**
+ * Compute confidence score for a single finding.
+ *
+ * Logic: score = clamp(base + sum(applicable deltas), 0.0, 1.0)
+ * Then route by depth thresholds:
+ *   - score >= surfaceThreshold → 'surface'
+ *   - score >= validateThreshold && aiEnabled → 'validate'
+ *   - otherwise → 'suppress'
+ */
+export function computeConfidence(
+  finding: Vulnerability,
+  context: AdjustmentContext,
+  rules: AdjustmentRule[],
+  depthConfig: DepthConfig
+): ConfidenceComputation {
+  const base = finding.baseConfidence ?? DEFAULT_BASE_CONFIDENCE
+
+  // Evaluate all rules and collect applicable adjustments
+  const adjustments: ConfidenceAdjustment[] = []
+  for (const rule of rules) {
+    if (rule.applies(finding, context)) {
+      adjustments.push({
+        factor: rule.name,
+        delta: rule.delta,
+        reason: rule.reason,
+        source: rule.source,
+      })
+    }
+  }
+
+  // Compute final score: base + sum(deltas), clamped to [0.0, 1.0]
+  const totalDelta = adjustments.reduce((sum, adj) => sum + adj.delta, 0)
+  const rawScore = base + totalDelta
+  const score = Math.max(0.0, Math.min(1.0, rawScore))
+
+  // Route by thresholds
+  let routing: ConfidenceComputation['routing']
+  if (score >= depthConfig.surfaceThreshold) {
+    routing = 'surface'
+  } else if (score >= depthConfig.validateThreshold && depthConfig.aiEnabled) {
+    routing = 'validate'
+  } else {
+    routing = 'suppress'
+  }
+
+  return { score, base, adjustments, routing }
+}