@oculum/scanner 1.0.11 → 1.0.13

package/src/postprocess/validation-cap.ts

@@ -0,0 +1,66 @@
+/**
+ * Validation Cap — Per-file cap on AI validation candidates for cost control.
+ *
+ * Prioritizes findings by confidence score, severity, and category importance.
+ */
+
+import type { Vulnerability } from '../shared/types'
+import type { ScoredFinding } from '../score'
+import { severityRank } from '../shared/parsed-file'
+
+/** Maximum candidates per file to send to AI validation (cost control) */
+export const MAX_VALIDATION_CANDIDATES_PER_FILE = 10
+
+/**
+ * Cap validation candidates per file to control AI costs
+ * Prioritizes by:
+ * 1. Confidence score (higher score = more likely a real finding)
+ * 2. Severity (critical > high > medium > low > info)
+ * 3. Category importance (secrets/URLs/auth before cosmetic patterns)
+ */
+export function capValidationCandidatesPerFile(
+  vulnerabilities: Vulnerability[],
+  maxPerFile: number = MAX_VALIDATION_CANDIDATES_PER_FILE
+): Vulnerability[] {
+  // Group by file
+  const byFile = new Map<string, Vulnerability[]>()
+  for (const vuln of vulnerabilities) {
+    const existing = byFile.get(vuln.filePath) || []
+    existing.push(vuln)
+    byFile.set(vuln.filePath, existing)
+  }
+
+  const result: Vulnerability[] = []
+
+  for (const [, fileVulns] of byFile) {
+    // Sort by priority: confidence score descending, then severity, then category
+    const sorted = [...fileVulns].sort((a, b) => {
+      // Confidence score comparison (higher = higher priority for validation)
+      const aScore = (a as ScoredFinding).confidence_score?.score ?? (a.baseConfidence ?? 0.35)
+      const bScore = (b as ScoredFinding).confidence_score?.score ?? (b.baseConfidence ?? 0.35)
+      const scoreDiff = bScore - aScore
+      if (Math.abs(scoreDiff) > 0.01) return scoreDiff
+
+      // Severity comparison (higher severity = higher priority)
+      const severityDiff = severityRank(b.severity) - severityRank(a.severity)
+      if (severityDiff !== 0) return severityDiff
+
+      // Category importance (secrets/URLs/auth before AI patterns)
+      const categoryPriority = (v: Vulnerability): number => {
+        if (v.category === 'hardcoded_secret') return 10
+        if (v.category === 'high_entropy_string') return 9
+        if (v.category === 'sensitive_url') return 8
+        if (v.category === 'missing_auth') return 7
+        if (v.category === 'ai_pattern') return 3
+        return 5
+      }
+      return categoryPriority(b) - categoryPriority(a)
+    })
+
+    // Take top N per file
+    const capped = sorted.slice(0, maxPerFile)
+    result.push(...capped)
+  }
+
+  return result
+}

package/src/report/build-result.ts

@@ -0,0 +1,94 @@
+/**
+ * Report Builder — Composes the final ScanResult from processed findings.
+ *
+ * Encapsulates sorting, counting, suppressed-summary building, and result
+ * object construction.
+ */
+
+import type {
+  ScanResult,
+  Vulnerability,
+  SuppressedVulnerabilitySummary,
+} from '../shared/types'
+import type { ValidationStats } from '../validate'
+import type { SuppressionResult } from '../postprocess/suppression/types'
+import type { FilterPipeline } from '../postprocess/filtering/pipeline'
+import { sortBySeverity, computeSeverityCounts, computeCategoryCounts } from './summary'
+
+export interface BuildScanResultInput {
+  repoInfo: { name: string; url: string; branch: string }
+  files: { length: number }
+  findings: Vulnerability[]
+  suppressionResult: SuppressionResult
+  startTime: number
+  validationStats?: ValidationStats
+  showSuppressed?: boolean
+  filterPipeline?: FilterPipeline
+  cancelled?: boolean
+  cancelReason?: string
+}
+
+/**
+ * Build the final ScanResult from postprocessed findings.
+ */
+export function buildScanResult(input: BuildScanResultInput): ScanResult {
+  const {
+    repoInfo,
+    files,
+    findings,
+    suppressionResult,
+    startTime,
+    validationStats,
+    showSuppressed,
+    filterPipeline,
+    cancelled,
+    cancelReason,
+  } = input
+
+  // Use the filtered findings (after suppression)
+  const afterSuppression = suppressionResult.findings
+
+  // Sort by severity
+  const sortedVulnerabilities = sortBySeverity(afterSuppression)
+
+  // Compute issue-mix counts (based on unsuppressed findings)
+  const severityCounts = computeSeverityCounts(sortedVulnerabilities)
+  const categoryCounts = computeCategoryCounts(sortedVulnerabilities)
+  const hasBlockingIssues = severityCounts.critical > 0 || severityCounts.high > 0
+
+  // Build suppressed vulnerabilities summary (for --show-suppressed)
+  const suppressedVulnerabilities: SuppressedVulnerabilitySummary[] | undefined = showSuppressed
+    ? suppressionResult.suppressed.map(s => ({
+        hash: s.suppression.hash,
+        filePath: s.vulnerability.filePath,
+        lineNumber: s.vulnerability.lineNumber,
+        category: s.vulnerability.category,
+        severity: s.vulnerability.severity,
+        title: s.vulnerability.title,
+        suppressionType: s.suppression.type,
+        suppressionReason: s.suppression.reason,
+        expires: s.suppression.expires,
+      }))
+    : undefined
+
+  return {
+    repoName: repoInfo.name,
+    repoUrl: repoInfo.url,
+    branch: repoInfo.branch,
+    filesScanned: files.length,
+    filesSkipped: 0, // TODO: track skipped files
+    vulnerabilities: sortedVulnerabilities,
+    severityCounts,
+    categoryCounts,
+    hasBlockingIssues: cancelled ? false : hasBlockingIssues,
+    scanDuration: Date.now() - startTime,
+    timestamp: new Date().toISOString(),
+    validationStats,
+    suppressionStats: suppressionResult.suppressed.length > 0 || suppressionResult.expiredSuppressions > 0
+      ? suppressionResult.stats
+      : undefined,
+    suppressedVulnerabilities,
+    filterAuditTrail: filterPipeline?.isEnabled ? filterPipeline.getAuditTrail() : undefined,
+    ...(cancelled ? { cancelled: true, cancelReason } : {}),
+  }
+}

package/src/report/enrichment.ts

@@ -0,0 +1,52 @@
+/**
+ * Report Enrichment — Adds rule registry metadata and framework-specific fixes to findings.
+ *
+ * Extracted from the orchestrator. Runs after detection + aggregation, before scoring.
+ */
+
+import type { Vulnerability } from '../shared/types'
+import type { ProjectContext } from '../model/project-context'
+import { getRuleMetadata } from '../shared/rules'
+import { getFrameworkFix } from '../shared/rules/framework-fixes'
+
+/**
+ * Enrich findings with metadata from the rule registry (PRO-82)
+ * Sets default impact, evidence, fixSteps, and references from registry
+ *
+ * PRO-83: When projectContext is provided, uses framework-aware fix suggestions
+ * that are tailored to the user's detected tech stack (e.g., Prisma-specific
+ * SQL injection fixes instead of generic advice).
+ *
+ * These can be overridden later by AI-generated content
+ */
+export function enrichWithMetadata(
+  findings: Vulnerability[],
+  projectContext?: ProjectContext
+): Vulnerability[] {
+  return findings.map(f => {
+    const metadata = getRuleMetadata(f.category)
+    if (!metadata) return f
+
+    // PRO-83: Check for framework-specific fix suggestions
+    let fixSteps = metadata.fixSteps
+    if (projectContext) {
+      const frameworkFix = getFrameworkFix(
+        f.category,
+        projectContext.frameworks,
+        projectContext.dataAccess
+      )
+      if (frameworkFix) {
+        fixSteps = frameworkFix.fixSteps
+      }
+    }
+
+    return {
+      ...f,
+      // Set defaults from registry (AI can override later)
+      impact: f.impact || metadata.whyItMatters,
+      evidence: f.evidence || metadata.evidence,
+      fixSteps: f.fixSteps || fixSteps,
+      references: f.references || metadata.references,
+    }
+  })
+}

package/src/report/formatters/__tests__/ai-context.test.ts

@@ -0,0 +1,254 @@
+/**
+ * AI Context Formatter Tests
+ */
+
+import { formatAIContext } from '../ai-context'
+import type { ScanResult, Vulnerability } from '../../types'
+
+const createMockVulnerability = (overrides: Partial<Vulnerability> = {}): Vulnerability => ({
+  id: 'test-vuln-1',
+  filePath: 'src/api/users.ts',
+  lineNumber: 42,
+  lineContent: 'const query = `SELECT * FROM users WHERE id = ${userId}`',
+  severity: 'high',
+  category: 'sql_injection',
+  title: 'SQL Injection Vulnerability',
+  description: 'User input is directly concatenated into SQL query without parameterization.',
+  suggestedFix: 'Use parameterized queries instead of string concatenation.',
+  confidence: 'high',
+  layer: 2,
+  impact: 'Attackers can execute arbitrary SQL commands, potentially accessing or modifying all database records.',
+  fixSteps: [
+    'Replace string concatenation with parameterized query',
+    'Use prepared statements or an ORM',
+    'Validate and sanitize input data'
+  ],
+  references: ['https://owasp.org/www-community/attacks/SQL_Injection'],
+  ...overrides,
+})
+
+const createMockScanResult = (vulnerabilities: Vulnerability[] = []): ScanResult => ({
+  repoName: 'test-repo',
+  repoUrl: 'https://github.com/test/test-repo',
+  branch: 'main',
+  filesScanned: 50,
+  filesSkipped: 5,
+  vulnerabilities,
+  severityCounts: {
+    critical: vulnerabilities.filter(v => v.severity === 'critical').length,
+    high: vulnerabilities.filter(v => v.severity === 'high').length,
+    medium: vulnerabilities.filter(v => v.severity === 'medium').length,
+    low: vulnerabilities.filter(v => v.severity === 'low').length,
+    info: vulnerabilities.filter(v => v.severity === 'info').length,
+  },
+  categoryCounts: {},
+  hasBlockingIssues: vulnerabilities.some(v => v.severity === 'critical' || v.severity === 'high'),
+  scanDuration: 1500,
+  timestamp: '2024-01-15T10:30:00.000Z',
+})
+
+describe('formatAIContext', () => {
+  it('should generate markdown with all sections', () => {
+    const vuln = createMockVulnerability()
+    const result = createMockScanResult([vuln])
+
+    const output = formatAIContext(result)
+
+    // Check header
+    expect(output).toContain('<!-- OCULUM AI CONTEXT - AUTO-GENERATED -->')
+    expect(output).toContain('# Security Issues Requiring Fixes')
+    expect(output).toContain('**Repository:** test-repo')
+    expect(output).toContain('**Findings:** 1')
+
+    // Check instructions section
+    expect(output).toContain('## Instructions for AI Assistants')
+    expect(output).toContain('Address CRITICAL issues first, then HIGH')
+
+    // Check finding details
+    expect(output).toContain('## HIGH Issues')
+    expect(output).toContain('SQL Injection Vulnerability')
+    expect(output).toContain('`src/api/users.ts:42`')
+    expect(output).toContain('sql_injection')
+
+    // Check fix instructions
+    expect(output).toContain('**Fix Instructions:**')
+    expect(output).toContain('Replace string concatenation with parameterized query')
+
+    // Check summary table
+    expect(output).toContain('## Summary')
+    expect(output).toContain('| Severity | Count | Files |')
+
+    // Check footer
+    expect(output).toContain('*Generated by Oculum Security Scanner*')
+  })
+
+  it('should order findings by severity (critical first)', () => {
+    const critical = createMockVulnerability({
+      id: 'critical-1',
+      severity: 'critical',
+      title: 'Critical Issue',
+    })
+    const high = createMockVulnerability({
+      id: 'high-1',
+      severity: 'high',
+      title: 'High Issue',
+    })
+    const medium = createMockVulnerability({
+      id: 'medium-1',
+      severity: 'medium',
+      title: 'Medium Issue',
+    })
+    const result = createMockScanResult([medium, critical, high])
+
+    const output = formatAIContext(result)
+
+    // Critical section should appear before High section
+    const criticalIndex = output.indexOf('## CRITICAL Issues')
+    const highIndex = output.indexOf('## HIGH Issues')
+    const mediumIndex = output.indexOf('## MEDIUM Issues')
+
+    expect(criticalIndex).toBeLessThan(highIndex)
+    expect(highIndex).toBeLessThan(mediumIndex)
+  })
+
+  it('should include file:line locations', () => {
+    const vuln = createMockVulnerability({
+      filePath: 'src/controllers/auth.ts',
+      lineNumber: 156,
+    })
+    const result = createMockScanResult([vuln])
+
+    const output = formatAIContext(result)
+
+    expect(output).toContain('`src/controllers/auth.ts:156`')
+  })
+
+  it('should include current code and fix instructions', () => {
+    const vuln = createMockVulnerability({
+      lineContent: 'eval(userInput)',
+      fixSteps: [
+        'Remove eval() usage',
+        'Use a safe alternative like JSON.parse()',
+        'Validate all user input'
+      ],
+    })
+    const result = createMockScanResult([vuln])
+
+    const output = formatAIContext(result)
+
+    // Check code block
+    expect(output).toContain('**Current Code:**')
+    expect(output).toContain('eval(userInput)')
+
+    // Check fix steps
+    expect(output).toContain('**Fix Instructions:**')
+    expect(output).toContain('1. Remove eval() usage')
+    expect(output).toContain('2. Use a safe alternative like JSON.parse()')
+    expect(output).toContain('3. Validate all user input')
+  })
+
+  it('should return minimal output for zero findings', () => {
+    const result = createMockScanResult([])
+
+    const output = formatAIContext(result)
+
+    expect(output).toContain('<!-- OCULUM AI CONTEXT - AUTO-GENERATED -->')
+    expect(output).toContain('# Security Issues Requiring Fixes')
+    expect(output).toContain('**Findings:** 0')
+    expect(output).toContain('No security issues found')
+    // Should not have severity sections
+    expect(output).not.toContain('## CRITICAL Issues')
+    expect(output).not.toContain('## HIGH Issues')
+  })
+
+  it('should respect maxFindings option', () => {
+    const vulnerabilities = Array.from({ length: 10 }, (_, i) =>
+      createMockVulnerability({
+        id: `vuln-${i}`,
+        title: `Issue ${i + 1}`,
+        severity: 'high',
+      })
+    )
+    const result = createMockScanResult(vulnerabilities)
+
+    const output = formatAIContext(result, { maxFindings: 3 })
+
+    // Should only show 3 findings details
+    expect(output).toContain('### 1. Issue')
+    expect(output).toContain('### 2. Issue')
+    expect(output).toContain('### 3. Issue')
+    expect(output).not.toContain('### 4. Issue')
+
+    // Should indicate more issues exist
+    expect(output).toContain('7 more HIGH issues')
+  })
+
+  it('should include references when option is enabled', () => {
+    const vuln = createMockVulnerability({
+      references: [
+        'https://owasp.org/www-community/attacks/SQL_Injection',
+        'https://cwe.mitre.org/data/definitions/89.html',
+      ],
+    })
+    const result = createMockScanResult([vuln])
+
+    const output = formatAIContext(result, { includeReferences: true })
+
+    expect(output).toContain('**References:**')
+    expect(output).toContain('https://owasp.org/www-community/attacks/SQL_Injection')
+    expect(output).toContain('https://cwe.mitre.org/data/definitions/89.html')
+  })
+
+  it('should include impact when available', () => {
+    const vuln = createMockVulnerability({
+      impact: 'Attackers can execute arbitrary SQL commands and access sensitive data.',
+    })
+    const result = createMockScanResult([vuln])
+
+    const output = formatAIContext(result)
+
+    expect(output).toContain('**Impact:**')
+    expect(output).toContain('Attackers can execute arbitrary SQL commands')
+  })
+
+  it('should handle multiple files in summary', () => {
+    const vulns = [
+      createMockVulnerability({
+        id: 'v1',
+        filePath: 'src/api/users.ts',
+        severity: 'critical',
+      }),
+      createMockVulnerability({
+        id: 'v2',
+        filePath: 'src/api/orders.ts',
+        severity: 'critical',
+      }),
+      createMockVulnerability({
+        id: 'v3',
+        filePath: 'src/api/users.ts',
+        severity: 'high',
+      }),
+    ]
+    const result = createMockScanResult(vulns)
+
+    const output = formatAIContext(result)
+
+    // Summary table should list files
+    expect(output).toContain('| Critical | 2 |')
+    expect(output).toContain('src/api/users.ts')
+    expect(output).toContain('src/api/orders.ts')
+  })
+
+  it('should use suggestedFix as fallback when fixSteps not available', () => {
+    const vuln = createMockVulnerability({
+      fixSteps: undefined,
+      suggestedFix: 'Use parameterized queries instead of string concatenation.',
+    })
+    const result = createMockScanResult([vuln])
+
+    const output = formatAIContext(result)
+
+    expect(output).toContain('**Fix Instructions:**')
+    expect(output).toContain('Use parameterized queries instead of string concatenation.')
+  })
+})