@oculum/scanner 1.0.11 → 1.0.13

package/src/score/index.ts

@@ -0,0 +1,316 @@
+/**
+ * Confidence Scoring System
+ *
+ * Entry point for the confidence scoring system. Provides:
+ * - scoreFindings() — score a batch of findings
+ * - buildConfidenceLog() — structured logging for debugging/tuning
+ * - buildAdjustmentContext() — build context for adjustment rules
+ * - DEPTH_CONFIGS — threshold configs for each scan depth
+ */
+
+import type { Vulnerability, ScanDepth } from '../shared/types'
+import type {
+  ScoredFinding,
+  ConfidenceLog,
+  AdjustmentContext,
+  DepthConfig,
+} from './types'
+import type { ContextEngineResult } from '../model/taint-types'
+import type { CrossFileTaintPath } from '../model/cross-file-taint'
+import { findClosestRoute } from '../model/route-discovery/utils'
+import { computeConfidence } from './confidence'
+import { ALL_ADJUSTMENT_RULES } from './adjustments'
+import {
+  isTestOrMockFile,
+  isExampleFile,
+  isScannerOrFixtureFile,
+  isToolingDirectory,
+  isServerOnlyFile,
+  isClientBundledFile,
+} from '../parse/file-classifier'
+
+// ============================================================================
+// Depth Configurations
+// ============================================================================
+
+/**
+ * Score thresholds per scan depth.
+ *
+ * - local:    Only high-confidence findings surface. No AI.
+ * - verified: High-confidence surface directly; medium goes to AI.
+ * - deep:     High-confidence surface; nearly everything goes to AI.
+ */
+export const DEPTH_CONFIGS: Record<ScanDepth, DepthConfig> = {
+  local: {
+    surfaceThreshold: 0.70,
+    validateThreshold: 1.0,   // Effectively no validation (nothing reaches 1.0)
+    aiEnabled: false,
+  },
+  verified: {
+    surfaceThreshold: 0.70,
+    validateThreshold: 0.20,
+    aiEnabled: true,
+  },
+  deep: {
+    surfaceThreshold: 0.70,
+    validateThreshold: 0.10,
+    aiEnabled: true,
+  },
+}
+
+// ============================================================================
+// Context Builder
+// ============================================================================
+
+/**
+ * Build adjustment context for a finding from file + project info.
+ */
+export function buildAdjustmentContext(
+  finding: Vulnerability,
+  ceResult: ContextEngineResult
+): AdjustmentContext {
+  // Look up taint data for this finding's file
+  let taint: AdjustmentContext['taint'] = undefined
+  const fileAnalysis = ceResult.fileTaintAnalyses?.get(finding.filePath)
+  if (fileAnalysis) {
+    // Check if any taint path has a sink at the finding's line number
+    const matchingPaths = fileAnalysis.taintPaths.filter(
+      tp => tp.sink.line === finding.lineNumber
+    )
+    if (matchingPaths.length > 0) {
+      // Pick the highest-confidence unsanitised path, or any path
+      const bestPath = matchingPaths.find(p => !p.sanitised) ?? matchingPaths[0]
+      taint = {
+        confirmed: true,
+        sources: matchingPaths.map(p => p.source.sourceType),
+        sinkType: bestPath.sink.sinkType,
+        sanitised: bestPath.sanitised,
+        confidence: bestPath.confidence,
+      }
+    } else {
+      // Check cross-file taint paths (CE Phase 4) — sink-side match
+      const crossFilePaths = findCrossFileTaintMatch(ceResult, finding)
+
+      if (crossFilePaths.length > 0) {
+        const bestPath = crossFilePaths.find(p => !p.sanitised) ?? crossFilePaths[0]
+        taint = {
+          confirmed: true,
+          sources: crossFilePaths.map(p => p.source.sourceType),
+          sinkType: bestPath.sink.sinkType,
+          sanitised: bestPath.sanitised,
+          confidence: bestPath.confidence,
+        }
+      } else {
+        // File has taint analysis but no path to this finding's line
+        taint = {
+          confirmed: false,
+          sources: [],
+          sinkType: null,
+          sanitised: false,
+          confidence: null,
+        }
+      }
+    }
+  } else {
+    // No intra-file taint analysis — still check cross-file taint paths (call-site match)
+    const crossFilePaths = findCrossFileTaintMatch(ceResult, finding)
+    if (crossFilePaths.length > 0) {
+      const bestPath = crossFilePaths.find(p => !p.sanitised) ?? crossFilePaths[0]
+      taint = {
+        confirmed: true,
+        sources: crossFilePaths.map(p => p.source.sourceType),
+        sinkType: bestPath.sink.sinkType,
+        sanitised: bestPath.sanitised,
+        confidence: bestPath.confidence,
+      }
+    }
+  }
+
+  // Look up route data for this finding's file
+  let route: AdjustmentContext['route'] = undefined
+  const fileRoutes = ceResult.routeMap?.fileToRoutes.get(finding.filePath)
+  if (fileRoutes && fileRoutes.length > 0) {
+    // Find the closest route to the finding's line number
+    const closestRoute = findClosestRoute(fileRoutes, finding.lineNumber)
+    if (closestRoute) {
+      route = {
+        hasAuth: closestRoute.authMiddleware.length > 0,
+        isPublic: closestRoute.isPublic,
+        middleware: closestRoute.authMiddleware,
+        methods: closestRoute.methods,
+        hasRateLimiting: closestRoute.rateLimiting,
+      }
+    }
+  }
+
+  // Look up framework analysis for this finding's file
+  let framework: AdjustmentContext['framework'] = undefined
+  const fileFramework = ceResult.frameworkAnalyses?.get(finding.filePath)
+  if (fileFramework) {
+    const safeLinePatterns = fileFramework.safeLines.get(finding.lineNumber)
+    const unsafeLinePatterns = fileFramework.unsafeLines.get(finding.lineNumber)
+    const safeLine = safeLinePatterns?.[0]
+    const unsafeLine = unsafeLinePatterns?.[0]
+    if (safeLine || unsafeLine) {
+      const activeFrameworks: string[] = []
+      const pc2 = ceResult.projectContext
+      if (pc2.frameworks.primary) activeFrameworks.push(pc2.frameworks.primary)
+      if (pc2.frameworks.frontend && !activeFrameworks.includes(pc2.frameworks.frontend)) {
+        activeFrameworks.push(pc2.frameworks.frontend)
+      }
+      framework = {
+        safePatternMatch: safeLine ? { id: safeLine.id, reason: safeLine.reason } : null,
+        unsafePatternMatch: unsafeLine ? { id: unsafeLine.id, reason: unsafeLine.reason } : null,
+        activeFrameworks,
+        orm: ceResult.projectContext.dataAccess.orm ?? null,
+      }
+    }
+  }
+
+  const pc = ceResult.projectContext
+  return {
+    file: {
+      isTestFile: isTestOrMockFile(finding.filePath),
+      isExampleFile: isExampleFile(finding.filePath),
+      isDocFile: /\.(md|mdx|txt|rst)$/i.test(finding.filePath),
+      isScannerCode: isScannerOrFixtureFile(finding.filePath),
+      isToolingDir: isToolingDirectory(finding.filePath),
+      isServerOnly: isServerOnlyFile(finding.filePath),
+      isClientBundled: isClientBundledFile(finding.filePath),
+    },
+    project: {
+      hasAuthMiddleware: pc.auth.hasGlobalMiddleware,
+      hasTypeScript: pc.frameworks.usesTypeScript,
+      orm: pc.dataAccess.orm ?? null,
+      validationLib: pc.dataAccess.validationLibrary ?? null,
+    },
+    lineContent: finding.lineContent,
+    filePath: finding.filePath,
+    taint,
+    route,
+    framework,
+  }
+}
+
+/**
+ * Find cross-file taint paths matching a finding — both sink-side and call-site.
+ * Mirrors the matching logic in request-builder.ts for AI annotations.
+ */
+function findCrossFileTaintMatch(
+  ceResult: ContextEngineResult,
+  finding: Vulnerability
+): CrossFileTaintPath[] {
+  return ceResult.crossFileTaintPaths?.filter(
+    cfp => (cfp.sinkFile === finding.filePath && cfp.sink.line === finding.lineNumber) ||
+           (cfp.sourceFile === finding.filePath && cfp.importLink.callLine === finding.lineNumber)
+  ) ?? []
+}
+
+// ============================================================================
+// Score Findings
+// ============================================================================
+
+/**
+ * Score a batch of findings with confidence scoring.
+ *
+ * Each finding gets a ConfidenceComputation attached as `confidence_score`.
+ * The routing field indicates whether the finding should be surfaced,
+ * validated by AI, or suppressed.
+ */
+export interface ScoringDiagnostics {
+  /** How many times each adjustment rule fired */
+  ruleHitCounts: Record<string, number>
+  /** Score distribution buckets */
+  scoreDistribution: { '0.0-0.2': number; '0.2-0.4': number; '0.4-0.6': number; '0.6-0.8': number; '0.8-1.0': number }
+  /** Average score per category */
+  categoryAvgScores: Record<string, { avg: number; count: number }>
+  /** Taint rule hits specifically */
+  taintRuleHits: Record<string, number>
+}
+
+export function scoreFindings(
+  findings: Vulnerability[],
+  depth: ScanDepth,
+  ceResult: ContextEngineResult
+): { scored: ScoredFinding[]; diagnostics: ScoringDiagnostics } {
+  const depthConfig = DEPTH_CONFIGS[depth]
+  const ruleHitCounts: Record<string, number> = {}
+  const taintRuleHits: Record<string, number> = {}
+  const scoreDistribution = { '0.0-0.2': 0, '0.2-0.4': 0, '0.4-0.6': 0, '0.6-0.8': 0, '0.8-1.0': 0 }
+  const categoryScoreSums: Record<string, { sum: number; count: number }> = {}
+
+  const scored = findings.map(finding => {
+    const context = buildAdjustmentContext(finding, ceResult)
+    const computation = computeConfidence(finding, context, ALL_ADJUSTMENT_RULES, depthConfig)
+
+    // Collect diagnostics
+    for (const adj of computation.adjustments) {
+      ruleHitCounts[adj.factor] = (ruleHitCounts[adj.factor] || 0) + 1
+      if (adj.source === 'taint') {
+        taintRuleHits[adj.factor] = (taintRuleHits[adj.factor] || 0) + 1
+      }
+    }
+
+    // Score distribution
+    const s = computation.score
+    if (s < 0.2) scoreDistribution['0.0-0.2']++
+    else if (s < 0.4) scoreDistribution['0.2-0.4']++
+    else if (s < 0.6) scoreDistribution['0.4-0.6']++
+    else if (s < 0.8) scoreDistribution['0.6-0.8']++
+    else scoreDistribution['0.8-1.0']++
+
+    // Per-category avg
+    const cat = finding.category
+    if (!categoryScoreSums[cat]) categoryScoreSums[cat] = { sum: 0, count: 0 }
+    categoryScoreSums[cat].sum += computation.score
+    categoryScoreSums[cat].count++
+
+    return {
+      ...finding,
+      confidence_score: computation,
+    }
+  })
+
+  const categoryAvgScores: Record<string, { avg: number; count: number }> = {}
+  for (const [cat, data] of Object.entries(categoryScoreSums)) {
+    categoryAvgScores[cat] = { avg: data.sum / data.count, count: data.count }
+  }
+
+  return {
+    scored,
+    diagnostics: { ruleHitCounts, scoreDistribution, categoryAvgScores, taintRuleHits },
+  }
+}
+
+// ============================================================================
+// Confidence Log
+// ============================================================================
+
+/**
+ * Build structured confidence logs for a batch of scored findings.
+ * Used for debugging, tuning, and comparing with tier-based routing.
+ */
+export function buildConfidenceLog(scored: ScoredFinding[]): ConfidenceLog[] {
+  return scored.map(f => ({
+    findingId: `${f.filePath}:${f.lineNumber}:${f.category}`,
+    category: f.category,
+    detectorGroup: f.source ?? 'unknown',
+    base: f.confidence_score.base,
+    adjustments: f.confidence_score.adjustments,
+    final: f.confidence_score.score,
+    routing: f.confidence_score.routing,
+    filePath: f.filePath,
+    severity: f.severity,
+  }))
+}
+
+// Re-export types for consumer convenience
+export type {
+  ScoredFinding,
+  ConfidenceComputation,
+  ConfidenceAdjustment,
+  ConfidenceLog,
+  AdjustmentRule,
+  AdjustmentContext,
+  DepthConfig,
+} from './types'

package/src/score/types.ts

@@ -0,0 +1,187 @@
+/**
+ * Confidence Scoring Types
+ *
+ * Per-finding continuous confidence scoring (0.0–1.0) that replaces
+ * the tier-based routing system. Each finding gets a numeric score
+ * computed from baseConfidence + sum(adjustments), and routing
+ * decisions use score thresholds instead of tier membership.
+ *
+ * The adjustment system is extensible for the future Context Engine
+ * (taint, route, framework data).
+ */
+
+import type { Vulnerability, ScanDepth } from '../shared/types'
+
+// ============================================================================
+// Confidence Adjustment
+// ============================================================================
+
+/**
+ * A single adjustment applied to a finding's confidence score.
+ * Records what changed the score, by how much, and why.
+ */
+export interface ConfidenceAdjustment {
+  /** Which adjustment rule produced this */
+  factor: string
+  /** Numeric change to score (positive = more confident, negative = less) */
+  delta: number
+  /** Human-readable explanation */
+  reason: string
+  /** Origin of this adjustment */
+  source: 'file_context' | 'auto_dismiss' | 'taint' | 'route' | 'framework' | 'detector'
+}
+
+// ============================================================================
+// Confidence Computation Result
+// ============================================================================
+
+/**
+ * Full computation result for a single finding's confidence score.
+ */
+export interface ConfidenceComputation {
+  /** Final clamped score (0.0–1.0) */
+  score: number
+  /** Base confidence from the detector */
+  base: number
+  /** All adjustments applied */
+  adjustments: ConfidenceAdjustment[]
+  /** Routing decision based on score thresholds */
+  routing: 'surface' | 'validate' | 'suppress'
+}
+
+// ============================================================================
+// Scored Finding
+// ============================================================================
+
+/**
+ * A vulnerability enriched with confidence scoring data.
+ * Extends the base Vulnerability with computed confidence information.
+ */
+export interface ScoredFinding extends Vulnerability {
+  /** Confidence computation result */
+  confidence_score: ConfidenceComputation
+}
+
+// ============================================================================
+// Depth Configuration
+// ============================================================================
+
+/**
+ * Score thresholds for each scan depth level.
+ * Determines how findings are routed based on their confidence score.
+ */
+export interface DepthConfig {
+  /** Minimum score to surface directly without AI validation */
+  surfaceThreshold: number
+  /** Minimum score to send to AI validation (below this = suppress) */
+  validateThreshold: number
+  /** Whether AI validation is available at this depth */
+  aiEnabled: boolean
+}
+
+// ============================================================================
+// Confidence Log
+// ============================================================================
+
+/**
+ * Structured log entry for confidence scoring decisions.
+ * Used for debugging, tuning, and audit trails.
+ */
+export interface ConfidenceLog {
+  /** Finding identifier (filePath:lineNumber:category) */
+  findingId: string
+  /** Vulnerability category */
+  category: string
+  /** Detector group that produced the finding */
+  detectorGroup: string
+  /** Base confidence from detector */
+  base: number
+  /** All adjustments applied */
+  adjustments: ConfidenceAdjustment[]
+  /** Final computed score */
+  final: number
+  /** Routing decision */
+  routing: 'surface' | 'validate' | 'suppress'
+  /** File path */
+  filePath: string
+  /** Severity */
+  severity: string
+}
+
+// ============================================================================
+// Adjustment Rule System
+// ============================================================================
+
+/**
+ * Context available to adjustment rules for evaluating findings.
+ *
+ * Starts minimal (file classification + basic project info).
+ * When Context Engine lands, add optional taint?, route?, framework?
+ * fields — existing rules ignore them; new rules check for presence.
+ */
+export interface AdjustmentContext {
+  /** File-level classification */
+  file: {
+    isTestFile: boolean
+    isExampleFile: boolean
+    isDocFile: boolean
+    isScannerCode: boolean
+    isToolingDir: boolean
+    isServerOnly: boolean
+    isClientBundled: boolean
+  }
+  /** Project-level context */
+  project: {
+    hasAuthMiddleware: boolean
+    hasTypeScript: boolean
+    orm: string | null
+    validationLib: string | null
+  }
+  /** The raw line content of the finding */
+  lineContent: string
+  /** The file path of the finding */
+  filePath: string
+
+  // Context Engine fields (optional — existing rules ignore undefined)
+  taint?: {
+    confirmed: boolean
+    sources: string[]
+    sinkType: string | null
+    sanitised: boolean
+    confidence: 'high' | 'medium' | 'low' | null
+  }
+  route?: {
+    hasAuth: boolean
+    isPublic: boolean
+    middleware: string[]
+    methods: string[]
+    hasRateLimiting: boolean
+  }
+  framework?: {
+    /** A safe-by-design pattern matches this finding's line */
+    safePatternMatch: { id: string; reason: string } | null
+    /** An unsafe-despite-framework pattern matches this finding's line */
+    unsafePatternMatch: { id: string; reason: string } | null
+    /** Which frameworks are active in the project */
+    activeFrameworks: string[]
+    /** ORM in use */
+    orm: string | null
+  }
+}
+
+/**
+ * A single adjustment rule that can modify a finding's confidence score.
+ * Rules are evaluated in order; all matching rules contribute their delta.
+ */
+export interface AdjustmentRule {
+  /** Unique name for this rule */
+  name: string
+  /** Origin category */
+  source: ConfidenceAdjustment['source']
+  /** Whether this rule applies to the given finding + context */
+  applies: (finding: Vulnerability, context: AdjustmentContext) => boolean
+  /** Score delta when rule applies (negative = less confident) */
+  delta: number
+  /** Human-readable reason */
+  reason: string
+}

package/src/shared/__tests__/code-analysis.test.ts

@@ -0,0 +1,165 @@
+import { ParsedFile } from '../parsed-file'
+import {
+  isInsideTryCatch,
+  hasTryCatchNearby,
+  extractFunctionContext,
+  searchSurroundingLines,
+} from '../code-analysis'
+
+describe('isInsideTryCatch', () => {
+  it('returns true when line is inside try block', () => {
+    const code = `
+function foo() {
+  try {
+    doSomething()
+  } catch (e) {
+    handleError(e)
+  }
+}`
+    const file = new ParsedFile(code, 'test.ts')
+    // Line 3 is "    doSomething()" inside try
+    expect(isInsideTryCatch(file, 3)).toBe(true)
+  })
+
+  it('returns false when line is outside try block', () => {
+    const code = `
+function foo() {
+  const x = 1
+  try {
+    doSomething()
+  } catch (e) {
+    handleError(e)
+  }
+}`
+    const file = new ParsedFile(code, 'test.ts')
+    // Line 2 is "  const x = 1" before try
+    expect(isInsideTryCatch(file, 2)).toBe(false)
+  })
+
+  it('returns false when no try-catch exists', () => {
+    const code = `
+function foo() {
+  doSomething()
+}`
+    const file = new ParsedFile(code, 'test.ts')
+    expect(isInsideTryCatch(file, 2)).toBe(false)
+  })
+})
+
+describe('hasTryCatchNearby', () => {
+  it('returns true when try-catch wraps the target line', () => {
+    const code = `
+function foo() {
+  try {
+    JSON.parse(data)
+  } catch (e) {
+    console.error(e)
+  }
+}`
+    const file = new ParsedFile(code, 'test.ts')
+    expect(hasTryCatchNearby(file, 3)).toBe(true)
+  })
+
+  it('returns false when no try-catch nearby', () => {
+    const code = `
+function foo() {
+  JSON.parse(data)
+  return data
+}`
+    const file = new ParsedFile(code, 'test.ts')
+    expect(hasTryCatchNearby(file, 2)).toBe(false)
+  })
+
+  it('respects function boundaries', () => {
+    const code = `
+function bar() {
+  try {
+    something()
+  } catch (e) {}
+}
+function foo() {
+  JSON.parse(data)
+}`
+    const file = new ParsedFile(code, 'test.ts')
+    // Line 7 is inside foo(), try-catch is in bar()
+    expect(hasTryCatchNearby(file, 7)).toBe(false)
+  })
+})
+
+describe('extractFunctionContext', () => {
+  it('finds named function declaration', () => {
+    const code = `
+function processData() {
+  const result = JSON.parse(data)
+}`
+    const file = new ParsedFile(code, 'test.ts')
+    expect(extractFunctionContext(file, 2)).toBe('processdata')
+  })
+
+  it('finds arrow function', () => {
+    const code = `
+const handleRequest = (req) => {
+  const body = JSON.parse(req.body)
+}`
+    const file = new ParsedFile(code, 'test.ts')
+    expect(extractFunctionContext(file, 2)).toBe('handlerequest')
+  })
+
+  it('finds method declaration', () => {
+    const code = `
+class Foo {
+  processInput() {
+    return JSON.parse(this.data)
+  }
+}`
+    const file = new ParsedFile(code, 'test.ts')
+    expect(extractFunctionContext(file, 3)).toBe('processinput')
+  })
+
+  it('returns null when no function context found', () => {
+    const code = `
+const x = JSON.parse(data)
+`
+    const file = new ParsedFile(code, 'test.ts')
+    expect(extractFunctionContext(file, 1)).toBeNull()
+  })
+})
+
+describe('searchSurroundingLines', () => {
+  const code = `import express from 'express'
+const app = express()
+app.use(authMiddleware)
+app.get('/api/data', handler)
+app.listen(3000)`
+  const file = new ParsedFile(code, 'test.ts')
+
+  it('finds a matching pattern within window', () => {
+    const result = searchSurroundingLines(
+      file, 3, [/authMiddleware/], 2
+    )
+    expect(result.found).toBe(true)
+    expect(result.matchedLine).toBe(2)
+  })
+
+  it('returns not found when pattern is outside window', () => {
+    const result = searchSurroundingLines(
+      file, 4, [/authMiddleware/], 1
+    )
+    expect(result.found).toBe(false)
+  })
+
+  it('matches multiple patterns (returns first)', () => {
+    const result = searchSurroundingLines(
+      file, 2, [/express\(\)/, /authMiddleware/], 1
+    )
+    expect(result.found).toBe(true)
+    expect(result.matchedLine).toBe(1)
+  })
+
+  it('clamps to file boundaries', () => {
+    const result = searchSurroundingLines(
+      file, 0, [/express/], 100
+    )
+    expect(result.found).toBe(true)
+  })
+})