@oculum/scanner 1.0.10 → 1.0.12

package/src/baseline/diff.ts

@@ -0,0 +1,135 @@
+/**
+ * Baseline Diff Computation
+ * Computes the difference between current findings and a baseline
+ */
+
+import type { Vulnerability, SeverityCounts, VulnerabilitySeverity } from '../types'
+import type { BaselineData, BaselineFinding, DiffResult } from './types'
+import { computeFindingHash } from '../suppression/hash'
+
+/**
+ * Compute severity counts from baseline findings
+ */
+function computeBaselineSeverityCounts(findings: BaselineFinding[]): SeverityCounts {
+  const counts: SeverityCounts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 }
+
+  for (const finding of findings) {
+    const severity = finding.severity as VulnerabilitySeverity
+    if (severity in counts) {
+      counts[severity]++
+    }
+  }
+
+  return counts
+}
+
+/**
+ * Compute severity counts from vulnerabilities
+ */
+function computeVulnerabilitySeverityCounts(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 the diff between current scan findings and a baseline
+ *
+ * Uses finding hashes for comparison, which are computed from:
+ * - Normalized file path
+ * - Normalized line content
+ * - Category
+ *
+ * This means findings are considered the same even if:
+ * - Line numbers changed (code moved)
+ * - Minor whitespace changes occurred
+ *
+ * @param currentFindings - Vulnerabilities from the current scan
+ * @param baseline - The baseline to compare against
+ * @returns DiffResult with new, fixed, and existing findings
+ */
+export function computeDiff(
+  currentFindings: Vulnerability[],
+  baseline: BaselineData
+): DiffResult {
+  // Build hash set from baseline for O(1) lookup
+  const baselineHashes = new Set(baseline.findings.map(f => f.hash))
+
+  // Build hash map from current findings
+  const currentHashMap = new Map<string, Vulnerability>()
+  for (const finding of currentFindings) {
+    const hash = computeFindingHash(finding)
+    currentHashMap.set(hash, finding)
+  }
+
+  // Compute new findings (in current, not in baseline)
+  const newFindings: Vulnerability[] = []
+  for (const finding of currentFindings) {
+    const hash = computeFindingHash(finding)
+    if (!baselineHashes.has(hash)) {
+      newFindings.push(finding)
+    }
+  }
+
+  // Compute fixed findings (in baseline, not in current)
+  const fixedFindings: BaselineFinding[] = []
+  for (const baselineFinding of baseline.findings) {
+    if (!currentHashMap.has(baselineFinding.hash)) {
+      fixedFindings.push(baselineFinding)
+    }
+  }
+
+  // Compute existing findings (in both)
+  const existingFindings: Vulnerability[] = []
+  for (const finding of currentFindings) {
+    const hash = computeFindingHash(finding)
+    if (baselineHashes.has(hash)) {
+      existingFindings.push(finding)
+    }
+  }
+
+  return {
+    new: newFindings,
+    fixed: fixedFindings,
+    existing: existingFindings,
+    stats: {
+      newCount: newFindings.length,
+      fixedCount: fixedFindings.length,
+      existingCount: existingFindings.length,
+      newBySeverity: computeVulnerabilitySeverityCounts(newFindings),
+      fixedBySeverity: computeBaselineSeverityCounts(fixedFindings),
+    },
+  }
+}
+
+/**
+ * Check if a diff has any new blocking issues (critical or high severity)
+ */
+export function hasNewBlockingIssues(diff: DiffResult): boolean {
+  return diff.stats.newBySeverity.critical > 0 || diff.stats.newBySeverity.high > 0
+}
+
+/**
+ * Format a summary string for the diff
+ */
+export function formatDiffSummary(diff: DiffResult): string {
+  const parts: string[] = []
+
+  if (diff.stats.newCount > 0) {
+    parts.push(`${diff.stats.newCount} new`)
+  }
+  if (diff.stats.fixedCount > 0) {
+    parts.push(`${diff.stats.fixedCount} fixed`)
+  }
+  if (diff.stats.existingCount > 0) {
+    parts.push(`${diff.stats.existingCount} existing`)
+  }
+
+  return parts.join(', ')
+}

package/src/baseline/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Baseline Module
+ * Provides baseline/diff mode functionality for tracking security improvements
+ */
+
+// Types
+export type {
+  BaselineFinding,
+  BaselineData,
+  DiffResult,
+  BaselineDiff,
+} from './types'
+export { BASELINE_FILE_PATH, OCULUM_DIR } from './types'
+
+// Manager
+export {
+  BaselineManager,
+  type BaselineManagerOptions,
+  type LoadBaselineResult,
+  type SaveBaselineResult,
+  type ClearBaselineResult,
+} from './manager'
+
+// Diff computation
+export {
+  computeDiff,
+  hasNewBlockingIssues,
+  formatDiffSummary,
+} from './diff'

package/src/baseline/manager.ts

@@ -0,0 +1,230 @@
+/**
+ * Baseline Manager
+ * Handles loading, saving, and clearing baseline files
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs'
+import { join, dirname } from 'path'
+import { execFileSync } from 'child_process'
+import type { ScanResult, ScanDepth, Vulnerability } from '../types'
+import type { BaselineData, BaselineFinding } from './types'
+import { BASELINE_FILE_PATH, OCULUM_DIR } from './types'
+import { computeFindingHash } from '../suppression/hash'
+
+export interface BaselineManagerOptions {
+  /** Project root path */
+  projectPath: string
+}
+
+export interface LoadBaselineResult {
+  /** Whether a baseline was found */
+  found: boolean
+  /** The baseline data (if found) */
+  baseline?: BaselineData
+  /** Error message (if failed to load) */
+  error?: string
+}
+
+export interface SaveBaselineResult {
+  /** Whether the save was successful */
+  success: boolean
+  /** Path where baseline was saved */
+  path: string
+  /** Error message (if failed) */
+  error?: string
+}
+
+export interface ClearBaselineResult {
+  /** Whether the clear was successful */
+  success: boolean
+  /** Whether a baseline existed before clearing */
+  existed: boolean
+  /** Error message (if failed) */
+  error?: string
+}
+
+/**
+ * Get current git commit SHA (short form)
+ */
+function getGitCommit(projectPath: string): string | undefined {
+  try {
+    const result = execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+      cwd: projectPath,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return result.toString().trim()
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Get current git branch name
+ */
+function getGitBranch(projectPath: string): string | undefined {
+  try {
+    const result = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: projectPath,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return result.toString().trim()
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Convert a Vulnerability to a BaselineFinding
+ */
+function toBaselineFinding(vuln: Vulnerability): BaselineFinding {
+  return {
+    hash: computeFindingHash(vuln),
+    filePath: vuln.filePath,
+    lineNumber: vuln.lineNumber,
+    category: vuln.category,
+    severity: vuln.severity,
+    title: vuln.title,
+  }
+}
+
+/**
+ * Manages baseline files for diff mode
+ */
+export class BaselineManager {
+  private projectPath: string
+  private baselinePath: string
+
+  constructor(options: BaselineManagerOptions | string) {
+    // Support both old string arg and new options object
+    if (typeof options === 'string') {
+      this.projectPath = options
+    } else {
+      this.projectPath = options.projectPath
+    }
+    this.baselinePath = join(this.projectPath, BASELINE_FILE_PATH)
+  }
+
+  /**
+   * Get the full path to the baseline file
+   */
+  getBaselinePath(): string {
+    return this.baselinePath
+  }
+
+  /**
+   * Load baseline from .oculum/baseline.json
+   */
+  loadBaseline(): LoadBaselineResult {
+    if (!existsSync(this.baselinePath)) {
+      return { found: false }
+    }
+
+    try {
+      const content = readFileSync(this.baselinePath, 'utf-8')
+      const baseline = JSON.parse(content) as BaselineData
+
+      // Basic validation
+      if (baseline.version !== 1) {
+        return {
+          found: false,
+          error: `Unsupported baseline version: ${baseline.version}. Expected version 1.`,
+        }
+      }
+
+      if (!Array.isArray(baseline.findings)) {
+        return {
+          found: false,
+          error: 'Invalid baseline: missing findings array',
+        }
+      }
+
+      return { found: true, baseline }
+    } catch (err) {
+      return {
+        found: false,
+        error: `Failed to parse baseline: ${err instanceof Error ? err.message : 'Unknown error'}`,
+      }
+    }
+  }
+
+  /**
+   * Save current scan result as baseline
+   */
+  saveBaseline(
+    scanResult: ScanResult,
+    options?: { commit?: string; branch?: string; scanDepth?: ScanDepth }
+  ): SaveBaselineResult {
+    try {
+      // Ensure .oculum directory exists
+      const oculumDir = join(this.projectPath, OCULUM_DIR)
+      if (!existsSync(oculumDir)) {
+        mkdirSync(oculumDir, { recursive: true })
+      }
+
+      // Get git info if not provided
+      const commit = options?.commit ?? getGitCommit(this.projectPath)
+      const branch = options?.branch ?? getGitBranch(this.projectPath)
+
+      // Convert vulnerabilities to baseline findings
+      const findings = scanResult.vulnerabilities.map(toBaselineFinding)
+
+      // Build baseline data
+      const baseline: BaselineData = {
+        version: 1,
+        createdAt: new Date().toISOString(),
+        commit,
+        branch,
+        scanDepth: options?.scanDepth,
+        findings,
+        stats: {
+          total: findings.length,
+          critical: scanResult.severityCounts.critical,
+          high: scanResult.severityCounts.high,
+          medium: scanResult.severityCounts.medium,
+          low: scanResult.severityCounts.low,
+          info: scanResult.severityCounts.info,
+        },
+      }
+
+      // Write to file
+      writeFileSync(this.baselinePath, JSON.stringify(baseline, null, 2))
+
+      return { success: true, path: this.baselinePath }
+    } catch (err) {
+      return {
+        success: false,
+        path: this.baselinePath,
+        error: `Failed to save baseline: ${err instanceof Error ? err.message : 'Unknown error'}`,
+      }
+    }
+  }
+
+  /**
+   * Clear (delete) the baseline file
+   */
+  clearBaseline(): ClearBaselineResult {
+    const existed = existsSync(this.baselinePath)
+
+    if (!existed) {
+      return { success: true, existed: false }
+    }
+
+    try {
+      unlinkSync(this.baselinePath)
+      return { success: true, existed: true }
+    } catch (err) {
+      return {
+        success: false,
+        existed: true,
+        error: `Failed to clear baseline: ${err instanceof Error ? err.message : 'Unknown error'}`,
+      }
+    }
+  }
+
+  /**
+   * Check if a baseline exists
+   */
+  hasBaseline(): boolean {
+    return existsSync(this.baselinePath)
+  }
+}

package/src/baseline/types.ts

@@ -0,0 +1,97 @@
+/**
+ * Baseline Types
+ * Types for baseline/diff mode functionality
+ */
+
+import type { VulnerabilityCategory, VulnerabilitySeverity, SeverityCounts, ScanDepth } from '../types'
+
+/**
+ * A finding stored in the baseline
+ * Contains enough information to identify and display the finding
+ */
+export interface BaselineFinding {
+  /** Finding hash (from computeFindingHash) */
+  hash: string
+  /** File path relative to project root */
+  filePath: string
+  /** Line number in the file */
+  lineNumber: number
+  /** Vulnerability category */
+  category: VulnerabilityCategory
+  /** Severity level */
+  severity: VulnerabilitySeverity
+  /** Finding title */
+  title: string
+}
+
+/**
+ * Baseline data stored in .oculum/baseline.json
+ */
+export interface BaselineData {
+  /** Schema version for forward compatibility */
+  version: 1
+  /** ISO 8601 timestamp when baseline was created */
+  createdAt: string
+  /** Git commit SHA when baseline was created (optional) */
+  commit?: string
+  /** Git branch name when baseline was created (optional) */
+  branch?: string
+  /** Scan depth used when creating baseline */
+  scanDepth?: ScanDepth
+  /** List of findings in the baseline */
+  findings: BaselineFinding[]
+  /** Summary statistics */
+  stats: {
+    total: number
+    critical: number
+    high: number
+    medium: number
+    low: number
+    info: number
+  }
+}
+
+/**
+ * Result of comparing current findings against baseline
+ */
+export interface DiffResult {
+  /** Findings in current scan but NOT in baseline (new issues) */
+  new: import('../types').Vulnerability[]
+  /** Findings in baseline but NOT in current scan (fixed issues) */
+  fixed: BaselineFinding[]
+  /** Findings in both current scan AND baseline (existing issues) */
+  existing: import('../types').Vulnerability[]
+  /** Summary statistics */
+  stats: {
+    newCount: number
+    fixedCount: number
+    existingCount: number
+    newBySeverity: SeverityCounts
+    fixedBySeverity: SeverityCounts
+  }
+}
+
+/**
+ * Baseline diff metadata attached to ScanResult
+ * Only present when --new flag is used
+ */
+export interface BaselineDiff {
+  /** When the baseline was created */
+  baselineCreatedAt: string
+  /** Git commit of the baseline (if available) */
+  baselineCommit?: string
+  /** Number of new findings (not in baseline) */
+  newCount: number
+  /** Number of fixed findings (in baseline, not in current) */
+  fixedCount: number
+  /** Number of existing findings (in both) */
+  existingCount: number
+  /** Details of fixed findings for display */
+  fixedFindings: BaselineFinding[]
+}
+
+/** Default baseline file path relative to project root */
+export const BASELINE_FILE_PATH = '.oculum/baseline.json'
+
+/** Directory for oculum files */
+export const OCULUM_DIR = '.oculum'