@oculum/scanner 1.0.9 → 1.0.11

package/src/suppression/config-loader.ts

@@ -0,0 +1,462 @@
+/**
+ * Suppression Config Loader
+ * Loads and validates suppression configuration from various file formats
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs'
+import { join, dirname } from 'path'
+import * as yaml from 'js-yaml'
+import type {
+  SuppressionConfig,
+  RuleSuppression,
+  FindingSuppression,
+} from './types'
+import {
+  SUPPRESSION_CONFIG_FILES,
+  DEFAULT_SUPPRESSION_CONFIG,
+} from './types'
+import type { VulnerabilityCategory } from '../types'
+
+/**
+ * Result of loading suppression config
+ */
+export interface ConfigLoadResult {
+  /** The loaded config (or default if none found) */
+  config: SuppressionConfig
+  /** Path to the config file (if found) */
+  configPath?: string
+  /** Whether a config file was found */
+  found: boolean
+  /** Any errors encountered during loading */
+  errors: string[]
+}
+
+/**
+ * Find the config file by walking up the directory tree
+ */
+export function findConfigFile(startPath: string): string | null {
+  let currentDir = startPath
+
+  // Walk up directory tree looking for config file
+  while (currentDir !== dirname(currentDir)) {
+    for (const filename of SUPPRESSION_CONFIG_FILES) {
+      const configPath = join(currentDir, filename)
+      if (existsSync(configPath)) {
+        return configPath
+      }
+    }
+    currentDir = dirname(currentDir)
+  }
+
+  // Check root directory one more time
+  for (const filename of SUPPRESSION_CONFIG_FILES) {
+    const configPath = join(currentDir, filename)
+    if (existsSync(configPath)) {
+      return configPath
+    }
+  }
+
+  return null
+}
+
+/**
+ * Parse config file content based on extension
+ */
+function parseConfigContent(content: string, filePath: string): unknown {
+  const isYaml = filePath.endsWith('.yaml') || filePath.endsWith('.yml')
+
+  if (isYaml) {
+    return yaml.load(content)
+  }
+
+  // JSON or .oculumrc (treat as JSON)
+  return JSON.parse(content)
+}
+
+/**
+ * Validate suppression config structure
+ */
+function validateConfig(data: unknown): { valid: boolean; errors: string[] } {
+  const errors: string[] = []
+
+  if (!data || typeof data !== 'object') {
+    return { valid: false, errors: ['Config must be an object'] }
+  }
+
+  const config = data as Record<string, unknown>
+
+  // Validate version
+  if (config.version !== undefined && config.version !== 1) {
+    errors.push(`Unsupported config version: ${config.version}. Only version 1 is supported.`)
+  }
+
+  // Validate suppressions
+  if (config.suppressions !== undefined) {
+    if (typeof config.suppressions !== 'object' || config.suppressions === null) {
+      errors.push('suppressions must be an object')
+    } else {
+      const suppressions = config.suppressions as Record<string, unknown>
+
+      // Validate rules
+      if (suppressions.rules !== undefined) {
+        if (!Array.isArray(suppressions.rules)) {
+          errors.push('suppressions.rules must be an array')
+        } else {
+          suppressions.rules.forEach((rule, i) => {
+            if (!rule || typeof rule !== 'object') {
+              errors.push(`suppressions.rules[${i}] must be an object`)
+            } else {
+              const r = rule as Record<string, unknown>
+              if (!r.category || typeof r.category !== 'string') {
+                errors.push(`suppressions.rules[${i}].category is required`)
+              }
+              if (!r.reason || typeof r.reason !== 'string') {
+                errors.push(`suppressions.rules[${i}].reason is required`)
+              }
+              if (r.expires && typeof r.expires !== 'string') {
+                errors.push(`suppressions.rules[${i}].expires must be a string (ISO date)`)
+              }
+              if (r.paths && !Array.isArray(r.paths)) {
+                errors.push(`suppressions.rules[${i}].paths must be an array`)
+              }
+            }
+          })
+        }
+      }
+
+      // Validate findings
+      if (suppressions.findings !== undefined) {
+        if (!Array.isArray(suppressions.findings)) {
+          errors.push('suppressions.findings must be an array')
+        } else {
+          suppressions.findings.forEach((finding, i) => {
+            if (!finding || typeof finding !== 'object') {
+              errors.push(`suppressions.findings[${i}] must be an object`)
+            } else {
+              const f = finding as Record<string, unknown>
+              if (!f.hash || typeof f.hash !== 'string') {
+                errors.push(`suppressions.findings[${i}].hash is required`)
+              }
+              if (!f.file || typeof f.file !== 'string') {
+                errors.push(`suppressions.findings[${i}].file is required`)
+              }
+              if (!f.reason || typeof f.reason !== 'string') {
+                errors.push(`suppressions.findings[${i}].reason is required`)
+              }
+              if (f.expires && typeof f.expires !== 'string') {
+                errors.push(`suppressions.findings[${i}].expires must be a string (ISO date)`)
+              }
+            }
+          })
+        }
+      }
+    }
+  }
+
+  // Validate ignore patterns
+  if (config.ignore !== undefined) {
+    if (!Array.isArray(config.ignore)) {
+      errors.push('ignore must be an array of strings')
+    } else {
+      config.ignore.forEach((pattern, i) => {
+        if (typeof pattern !== 'string') {
+          errors.push(`ignore[${i}] must be a string`)
+        }
+      })
+    }
+  }
+
+  return { valid: errors.length === 0, errors }
+}
+
+/**
+ * Load suppression config from a specific path
+ */
+export function loadConfigFromPath(configPath: string): ConfigLoadResult {
+  const errors: string[] = []
+
+  try {
+    const content = readFileSync(configPath, 'utf-8')
+    const data = parseConfigContent(content, configPath)
+
+    const validation = validateConfig(data)
+    if (!validation.valid) {
+      return {
+        config: DEFAULT_SUPPRESSION_CONFIG,
+        configPath,
+        found: true,
+        errors: validation.errors,
+      }
+    }
+
+    // Cast to config type (after validation)
+    const config = data as SuppressionConfig
+
+    // Ensure defaults
+    return {
+      config: {
+        version: config.version || 1,
+        suppressions: {
+          rules: config.suppressions?.rules || [],
+          findings: config.suppressions?.findings || [],
+        },
+        ignore: config.ignore || [],
+      },
+      configPath,
+      found: true,
+      errors,
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return {
+      config: DEFAULT_SUPPRESSION_CONFIG,
+      configPath,
+      found: true,
+      errors: [`Failed to parse config: ${message}`],
+    }
+  }
+}
+
+/**
+ * Load suppression config from a project directory
+ * Searches up the directory tree for a config file
+ */
+export function loadSuppressionConfig(projectPath: string): ConfigLoadResult {
+  const configPath = findConfigFile(projectPath)
+
+  if (!configPath) {
+    return {
+      config: DEFAULT_SUPPRESSION_CONFIG,
+      found: false,
+      errors: [],
+    }
+  }
+
+  return loadConfigFromPath(configPath)
+}
+
+/**
+ * Write suppression config to a file
+ */
+export function writeSuppressionConfig(
+  configPath: string,
+  config: SuppressionConfig
+): void {
+  const isYaml = configPath.endsWith('.yaml') || configPath.endsWith('.yml')
+
+  let content: string
+  if (isYaml) {
+    content = yaml.dump(config, {
+      indent: 2,
+      lineWidth: 100,
+      noRefs: true,
+      sortKeys: false,
+    })
+  } else {
+    content = JSON.stringify(config, null, 2) + '\n'
+  }
+
+  writeFileSync(configPath, content, 'utf-8')
+}
+
+/**
+ * Add a finding suppression to the config file
+ */
+export function addFindingSuppression(
+  projectPath: string,
+  suppression: FindingSuppression
+): { success: boolean; configPath: string; error?: string } {
+  // Find or create config file
+  let configPath = findConfigFile(projectPath)
+  let config: SuppressionConfig
+
+  if (configPath) {
+    const result = loadConfigFromPath(configPath)
+    if (result.errors.length > 0) {
+      return {
+        success: false,
+        configPath: configPath,
+        error: result.errors.join(', '),
+      }
+    }
+    config = result.config
+  } else {
+    // Create new config file in project root
+    configPath = join(projectPath, '.oculum.yaml')
+    config = { ...DEFAULT_SUPPRESSION_CONFIG }
+  }
+
+  // Initialize suppressions if needed
+  if (!config.suppressions) {
+    config.suppressions = {}
+  }
+  if (!config.suppressions.findings) {
+    config.suppressions.findings = []
+  }
+
+  // Check for duplicate
+  const existingIndex = config.suppressions.findings.findIndex(
+    f => f.hash === suppression.hash
+  )
+
+  if (existingIndex >= 0) {
+    // Update existing suppression
+    config.suppressions.findings[existingIndex] = suppression
+  } else {
+    // Add new suppression
+    config.suppressions.findings.push(suppression)
+  }
+
+  // Write config
+  try {
+    writeSuppressionConfig(configPath, config)
+    return { success: true, configPath }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return { success: false, configPath, error: message }
+  }
+}
+
+/**
+ * Remove a finding suppression from the config file
+ */
+export function removeFindingSuppression(
+  projectPath: string,
+  hash: string
+): { success: boolean; configPath?: string; error?: string; removed: boolean } {
+  const configPath = findConfigFile(projectPath)
+
+  if (!configPath) {
+    return { success: true, removed: false }
+  }
+
+  const result = loadConfigFromPath(configPath)
+  if (result.errors.length > 0) {
+    return {
+      success: false,
+      configPath,
+      error: result.errors.join(', '),
+      removed: false,
+    }
+  }
+
+  const config = result.config
+
+  if (!config.suppressions?.findings) {
+    return { success: true, configPath, removed: false }
+  }
+
+  const initialLength = config.suppressions.findings.length
+  config.suppressions.findings = config.suppressions.findings.filter(
+    f => f.hash !== hash
+  )
+
+  const removed = config.suppressions.findings.length < initialLength
+
+  if (removed) {
+    try {
+      writeSuppressionConfig(configPath, config)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      return { success: false, configPath, error: message, removed: false }
+    }
+  }
+
+  return { success: true, configPath, removed }
+}
+
+/**
+ * Add a rule suppression to the config file
+ */
+export function addRuleSuppression(
+  projectPath: string,
+  suppression: RuleSuppression
+): { success: boolean; configPath: string; error?: string } {
+  // Find or create config file
+  let configPath = findConfigFile(projectPath)
+  let config: SuppressionConfig
+
+  if (configPath) {
+    const result = loadConfigFromPath(configPath)
+    if (result.errors.length > 0) {
+      return {
+        success: false,
+        configPath: configPath,
+        error: result.errors.join(', '),
+      }
+    }
+    config = result.config
+  } else {
+    // Create new config file in project root
+    configPath = join(projectPath, '.oculum.yaml')
+    config = { ...DEFAULT_SUPPRESSION_CONFIG }
+  }
+
+  // Initialize suppressions if needed
+  if (!config.suppressions) {
+    config.suppressions = {}
+  }
+  if (!config.suppressions.rules) {
+    config.suppressions.rules = []
+  }
+
+  // Check for duplicate (same category and paths)
+  const existingIndex = config.suppressions.rules.findIndex(
+    r => r.category === suppression.category &&
+      JSON.stringify(r.paths || []) === JSON.stringify(suppression.paths || [])
+  )
+
+  if (existingIndex >= 0) {
+    // Update existing suppression
+    config.suppressions.rules[existingIndex] = suppression
+  } else {
+    // Add new suppression
+    config.suppressions.rules.push(suppression)
+  }
+
+  // Write config
+  try {
+    writeSuppressionConfig(configPath, config)
+    return { success: true, configPath }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return { success: false, configPath, error: message }
+  }
+}
+
+/**
+ * List all suppressions in the config
+ */
+export function listSuppressions(projectPath: string): {
+  rules: RuleSuppression[]
+  findings: FindingSuppression[]
+  configPath?: string
+  errors: string[]
+} {
+  const result = loadSuppressionConfig(projectPath)
+
+  return {
+    rules: result.config.suppressions?.rules || [],
+    findings: result.config.suppressions?.findings || [],
+    configPath: result.configPath,
+    errors: result.errors,
+  }
+}
+
+/**
+ * Check if a date string is expired
+ */
+export function isExpired(dateString: string | undefined): boolean {
+  if (!dateString) {
+    return false
+  }
+
+  try {
+    const expirationDate = new Date(dateString)
+    const now = new Date()
+    return expirationDate < now
+  } catch {
+    // Invalid date format - treat as not expired
+    return false
+  }
+}

package/src/suppression/hash.ts

@@ -0,0 +1,95 @@
+/**
+ * Finding Hash Computation
+ * Creates stable, reproducible hashes for identifying specific findings
+ */
+
+import { createHash } from 'crypto'
+import type { Vulnerability } from '../types'
+
+/**
+ * Normalize a file path for hashing
+ * - Removes leading ./ or /
+ * - Converts backslashes to forward slashes
+ * - Lowercases (for case-insensitive matching)
+ */
+export function normalizePathForHash(filePath: string): string {
+  return filePath
+    .replace(/^\.\//, '') // Remove leading ./
+    .replace(/^\//, '') // Remove leading /
+    .replace(/\\/g, '/') // Normalize backslashes
+    .toLowerCase()
+}
+
+/**
+ * Normalize line content for hashing
+ * - Trims whitespace
+ * - Collapses multiple whitespace to single space
+ * - Removes common noise (line numbers, etc.)
+ */
+export function normalizeContentForHash(content: string): string {
+  return content
+    .trim()
+    .replace(/\s+/g, ' ') // Collapse whitespace
+    .replace(/^\d+:\s*/, '') // Remove line number prefix if present
+}
+
+/**
+ * Compute a stable hash for a vulnerability finding
+ *
+ * Hash = SHA256(normalizedPath:normalizedContent:category).slice(0,16)
+ *
+ * This creates a 16-character hex hash that:
+ * - Stays stable across whitespace changes
+ * - Changes when the actual code changes
+ * - Changes when the finding category changes
+ * - Is unique enough for practical use
+ *
+ * @param finding - The vulnerability to hash
+ * @returns A 16-character hex hash string
+ */
+export function computeFindingHash(finding: Vulnerability): string {
+  const normalizedPath = normalizePathForHash(finding.filePath)
+  const normalizedContent = normalizeContentForHash(finding.lineContent)
+  const category = finding.category
+
+  const input = `${normalizedPath}:${normalizedContent}:${category}`
+  const hash = createHash('sha256').update(input).digest('hex')
+
+  // Return first 16 characters (64 bits of entropy - sufficient for uniqueness)
+  return hash.slice(0, 16)
+}
+
+/**
+ * Compute hash from raw components (for testing or manual construction)
+ */
+export function computeHashFromComponents(
+  filePath: string,
+  lineContent: string,
+  category: string
+): string {
+  const normalizedPath = normalizePathForHash(filePath)
+  const normalizedContent = normalizeContentForHash(lineContent)
+
+  const input = `${normalizedPath}:${normalizedContent}:${category}`
+  const hash = createHash('sha256').update(input).digest('hex')
+
+  return hash.slice(0, 16)
+}
+
+/**
+ * Validate a hash format
+ * Must be 16 hexadecimal characters
+ */
+export function isValidHash(hash: string): boolean {
+  return /^[0-9a-f]{16}$/i.test(hash)
+}
+
+/**
+ * Format a hash for display (with truncation indicator)
+ */
+export function formatHashForDisplay(hash: string): string {
+  if (hash.length <= 16) {
+    return hash
+  }
+  return `${hash.slice(0, 12)}...`
+}

package/src/suppression/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Suppression System
+ * Allows users to suppress findings via config files and inline comments
+ */
+
+// Main exports
+export { SuppressionManager, type SuppressionManagerOptions } from './manager'
+
+// Types
+export type {
+  SuppressionConfig,
+  RuleSuppression,
+  FindingSuppression,
+  InlineSuppression,
+  SuppressionMatch,
+  SuppressedVulnerability,
+  SuppressionResult,
+} from './types'
+export { SUPPRESSION_CONFIG_FILES, DEFAULT_SUPPRESSION_CONFIG } from './types'
+
+// Hash utilities
+export {
+  computeFindingHash,
+  computeHashFromComponents,
+  normalizePathForHash,
+  normalizeContentForHash,
+  isValidHash,
+  formatHashForDisplay,
+} from './hash'
+
+// Config utilities
+export {
+  loadSuppressionConfig,
+  loadConfigFromPath,
+  findConfigFile,
+  writeSuppressionConfig,
+  addFindingSuppression,
+  removeFindingSuppression,
+  addRuleSuppression,
+  listSuppressions,
+  isExpired,
+  type ConfigLoadResult,
+} from './config-loader'
+
+// Inline comment utilities
+export {
+  parseInlineSuppressions,
+  isLineSuppressed,
+  extractSuppressionReasons,
+  generateSuppressionComment,
+} from './inline-parser'