@oculum/scanner 1.0.9 → 1.0.11

package/src/suppression/inline-parser.ts

@@ -0,0 +1,273 @@
+/**
+ * Inline Suppression Comment Parser
+ * Parses oculum-ignore comments from source code
+ */
+
+import type { InlineSuppression } from './types'
+import type { VulnerabilityCategory } from '../types'
+
+/**
+ * Valid suppression comment patterns:
+ *
+ * Single-line suppressions:
+ *   // oculum-ignore-next-line: reason here
+ *   // oculum-ignore-next-line [rule-id]: reason here
+ *   code // oculum-ignore: reason here
+ *   code // oculum-ignore [rule-id]: reason here
+ *
+ * Block suppressions:
+ *   /* oculum-ignore-block: reason here * /
+ *   ... code ...
+ *   /* oculum-ignore-block-end * /
+ *
+ * Also supports:
+ *   # oculum-ignore-next-line: reason (Python, Ruby, YAML, etc.)
+ *   -- oculum-ignore-next-line: reason (SQL)
+ */
+
+// Regex patterns for parsing comments
+const PATTERNS = {
+  // // oculum-ignore-next-line: reason
+  // // oculum-ignore-next-line [rule-id]: reason
+  nextLine: /(?:\/\/|#|--)\s*oculum-ignore-next-line(?:\s*\[([^\]]+)\])?\s*:\s*(.+)/i,
+
+  // code // oculum-ignore: reason
+  // code // oculum-ignore [rule-id]: reason
+  sameLine: /(?:\/\/|#|--)\s*oculum-ignore(?:\s*\[([^\]]+)\])?\s*:\s*(.+)/i,
+
+  // /* oculum-ignore-block: reason */
+  // /* oculum-ignore-block [rule-id]: reason */
+  blockStart: /\/\*\s*oculum-ignore-block(?:\s*\[([^\]]+)\])?\s*:\s*([^*]+)\*\//i,
+
+  // /* oculum-ignore-block-end */
+  blockEnd: /\/\*\s*oculum-ignore-block-end\s*\*\//i,
+}
+
+/**
+ * Parse a single line for suppression comments
+ */
+function parseLineForSuppression(
+  line: string,
+  lineNumber: number
+): InlineSuppression | null {
+  // Check for next-line suppression (must be the only thing on the line, aside from whitespace)
+  const trimmed = line.trim()
+
+  // Next-line pattern (comment at start of line)
+  if (
+    trimmed.startsWith('//') ||
+    trimmed.startsWith('#') ||
+    trimmed.startsWith('--')
+  ) {
+    const nextLineMatch = trimmed.match(PATTERNS.nextLine)
+    if (nextLineMatch) {
+      return {
+        lineNumber,
+        type: 'next-line',
+        ruleId: nextLineMatch[1] as VulnerabilityCategory | undefined,
+        reason: nextLineMatch[2].trim(),
+        commentText: trimmed,
+      }
+    }
+  }
+
+  // Same-line pattern (comment at end of line with code before)
+  // Only check if there's actual code before the comment
+  const sameLineMatch = line.match(PATTERNS.sameLine)
+  if (sameLineMatch) {
+    // Find where the comment starts
+    const commentIndex = line.search(/(?:\/\/|#|--)\s*oculum-ignore/i)
+    const beforeComment = line.substring(0, commentIndex).trim()
+
+    // Only treat as same-line if there's code before the comment
+    // (not just whitespace or if it's at the start)
+    if (beforeComment.length > 0) {
+      return {
+        lineNumber,
+        type: 'same-line',
+        ruleId: sameLineMatch[1] as VulnerabilityCategory | undefined,
+        reason: sameLineMatch[2].trim(),
+        commentText: line.substring(commentIndex).trim(),
+      }
+    }
+  }
+
+  // Block start pattern
+  const blockStartMatch = line.match(PATTERNS.blockStart)
+  if (blockStartMatch) {
+    return {
+      lineNumber,
+      type: 'block-start',
+      ruleId: blockStartMatch[1] as VulnerabilityCategory | undefined,
+      reason: blockStartMatch[2].trim(),
+      commentText: blockStartMatch[0],
+    }
+  }
+
+  // Block end pattern
+  const blockEndMatch = line.match(PATTERNS.blockEnd)
+  if (blockEndMatch) {
+    return {
+      lineNumber,
+      type: 'block-end',
+      reason: '', // Block end has no reason
+      commentText: blockEndMatch[0],
+    }
+  }
+
+  return null
+}
+
+/**
+ * Parse all inline suppressions from file content
+ *
+ * Returns a map of line numbers to their effective suppressions.
+ * A line can be suppressed by:
+ * 1. A same-line comment (oculum-ignore)
+ * 2. A next-line comment on the previous line (oculum-ignore-next-line)
+ * 3. Being within a block suppression (oculum-ignore-block ... oculum-ignore-block-end)
+ */
+export function parseInlineSuppressions(content: string): Map<number, InlineSuppression> {
+  const lines = content.split('\n')
+  const suppressions = new Map<number, InlineSuppression>()
+
+  // Track block suppression state
+  let currentBlock: { startLine: number; reason: string; ruleId?: VulnerabilityCategory } | null = null
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineNumber = i + 1 // 1-indexed
+    const line = lines[i]
+
+    const suppression = parseLineForSuppression(line, lineNumber)
+
+    if (suppression) {
+      switch (suppression.type) {
+        case 'next-line':
+          // Apply to the next line
+          if (i + 1 < lines.length) {
+            suppressions.set(lineNumber + 1, {
+              ...suppression,
+              lineNumber: lineNumber + 1,
+            })
+          }
+          break
+
+        case 'same-line':
+          // Apply to this line
+          suppressions.set(lineNumber, suppression)
+          break
+
+        case 'block-start':
+          // Start tracking block suppression
+          currentBlock = {
+            startLine: lineNumber,
+            reason: suppression.reason,
+            ruleId: suppression.ruleId,
+          }
+          break
+
+        case 'block-end':
+          // End block suppression
+          currentBlock = null
+          break
+      }
+    }
+
+    // If we're in a block suppression, add suppression for this line
+    // (unless it's the block start/end line itself)
+    if (currentBlock && suppression?.type !== 'block-start' && suppression?.type !== 'block-end') {
+      // Don't override explicit same-line suppressions
+      if (!suppressions.has(lineNumber)) {
+        suppressions.set(lineNumber, {
+          lineNumber,
+          type: 'block-start', // Mark as from block
+          reason: currentBlock.reason,
+          ruleId: currentBlock.ruleId,
+          commentText: `Block suppression from line ${currentBlock.startLine}`,
+        })
+      }
+    }
+  }
+
+  return suppressions
+}
+
+/**
+ * Check if a specific line is suppressed
+ */
+export function isLineSuppressed(
+  suppressions: Map<number, InlineSuppression>,
+  lineNumber: number,
+  category?: VulnerabilityCategory
+): InlineSuppression | null {
+  const suppression = suppressions.get(lineNumber)
+
+  if (!suppression) {
+    return null
+  }
+
+  // If suppression specifies a rule and category doesn't match, not suppressed
+  if (suppression.ruleId && category && suppression.ruleId !== category) {
+    return null
+  }
+
+  return suppression
+}
+
+/**
+ * Extract all unique suppression reasons from a file
+ * Useful for auditing suppressed findings
+ */
+export function extractSuppressionReasons(content: string): Array<{
+  reason: string
+  ruleId?: VulnerabilityCategory
+  lineNumber: number
+  type: InlineSuppression['type']
+}> {
+  const suppressions = parseInlineSuppressions(content)
+  const seen = new Set<string>()
+  const results: Array<{
+    reason: string
+    ruleId?: VulnerabilityCategory
+    lineNumber: number
+    type: InlineSuppression['type']
+  }> = []
+
+  for (const [lineNumber, suppression] of suppressions) {
+    // Only include unique comment sources (not duplicates from block propagation)
+    const key = `${suppression.commentText}`
+    if (!seen.has(key) && suppression.type !== 'block-end') {
+      seen.add(key)
+      results.push({
+        reason: suppression.reason,
+        ruleId: suppression.ruleId,
+        lineNumber,
+        type: suppression.type,
+      })
+    }
+  }
+
+  return results
+}
+
+/**
+ * Generate a suppression comment for a given line
+ */
+export function generateSuppressionComment(
+  reason: string,
+  options: {
+    type?: 'next-line' | 'same-line'
+    ruleId?: VulnerabilityCategory
+    commentStyle?: '//' | '#' | '--'
+  } = {}
+): string {
+  const { type = 'next-line', ruleId, commentStyle = '//' } = options
+
+  const ruleSpec = ruleId ? ` [${ruleId}]` : ''
+
+  if (type === 'next-line') {
+    return `${commentStyle} oculum-ignore-next-line${ruleSpec}: ${reason}`
+  }
+
+  return `${commentStyle} oculum-ignore${ruleSpec}: ${reason}`
+}

package/src/suppression/manager.ts

@@ -0,0 +1,379 @@
+/**
+ * Suppression Manager
+ * Central class for managing all suppression logic
+ */
+
+import { minimatch } from 'minimatch'
+import type { Vulnerability, ScanFile } from '../types'
+import type {
+  SuppressionConfig,
+  SuppressionMatch,
+  SuppressionResult,
+  SuppressedVulnerability,
+  InlineSuppression,
+  RuleSuppression,
+  FindingSuppression,
+} from './types'
+import { loadSuppressionConfig, isExpired } from './config-loader'
+import { parseInlineSuppressions, isLineSuppressed } from './inline-parser'
+import { computeFindingHash, normalizePathForHash } from './hash'
+
+/**
+ * Options for SuppressionManager
+ */
+export interface SuppressionManagerOptions {
+  /** Path to the project root (for finding config files) */
+  projectPath: string
+  /** Optional pre-loaded config (skips file loading) */
+  config?: SuppressionConfig
+  /** Whether to include expired suppressions (for auditing) */
+  includeExpired?: boolean
+}
+
+/**
+ * SuppressionManager handles all suppression logic
+ *
+ * Priority order for suppressions:
+ * 1. Inline comment suppressions (highest priority)
+ * 2. Config file finding suppressions (by hash)
+ * 3. Config file rule suppressions (by category)
+ */
+export class SuppressionManager {
+  private config: SuppressionConfig
+  private configPath: string | undefined
+  private configErrors: string[]
+  private includeExpired: boolean
+  private projectPath: string
+
+  // Cache for inline suppressions by file path
+  private inlineSuppressionCache: Map<string, Map<number, InlineSuppression>> = new Map()
+
+  constructor(options: SuppressionManagerOptions) {
+    this.projectPath = options.projectPath
+    this.includeExpired = options.includeExpired ?? false
+
+    if (options.config) {
+      this.config = options.config
+      this.configPath = undefined
+      this.configErrors = []
+    } else {
+      const result = loadSuppressionConfig(options.projectPath)
+      this.config = result.config
+      this.configPath = result.configPath
+      this.configErrors = result.errors
+    }
+  }
+
+  /**
+   * Get configuration errors (if any)
+   */
+  getConfigErrors(): string[] {
+    return this.configErrors
+  }
+
+  /**
+   * Get the path to the config file (if found)
+   */
+  getConfigPath(): string | undefined {
+    return this.configPath
+  }
+
+  /**
+   * Check if a file path should be ignored entirely
+   */
+  isPathIgnored(filePath: string): boolean {
+    if (!this.config.ignore || this.config.ignore.length === 0) {
+      return false
+    }
+
+    const normalizedPath = normalizePathForHash(filePath)
+
+    return this.config.ignore.some(pattern =>
+      minimatch(normalizedPath, pattern, { dot: true })
+    )
+  }
+
+  /**
+   * Parse inline suppressions for a file
+   */
+  private getInlineSuppressions(
+    filePath: string,
+    content: string
+  ): Map<number, InlineSuppression> {
+    // Check cache first
+    const cached = this.inlineSuppressionCache.get(filePath)
+    if (cached) {
+      return cached
+    }
+
+    // Parse and cache
+    const suppressions = parseInlineSuppressions(content)
+    this.inlineSuppressionCache.set(filePath, suppressions)
+    return suppressions
+  }
+
+  /**
+   * Check if a finding is suppressed
+   *
+   * Priority:
+   * 1. Inline comment (highest)
+   * 2. Config finding suppression (by hash)
+   * 3. Config rule suppression (by category)
+   */
+  isFindingSuppressed(
+    finding: Vulnerability,
+    fileContent?: string
+  ): SuppressionMatch {
+    const hash = computeFindingHash(finding)
+    const normalizedPath = normalizePathForHash(finding.filePath)
+
+    // 1. Check inline suppressions (if file content provided)
+    if (fileContent) {
+      const inlineSuppressions = this.getInlineSuppressions(finding.filePath, fileContent)
+      const inlineSuppression = isLineSuppressed(
+        inlineSuppressions,
+        finding.lineNumber,
+        finding.category
+      )
+
+      if (inlineSuppression) {
+        return {
+          suppressed: true,
+          match: {
+            type: 'inline',
+            reason: inlineSuppression.reason,
+          },
+          hash,
+        }
+      }
+    }
+
+    // 2. Check config finding suppressions (by hash)
+    const findingSuppressions = this.config.suppressions?.findings || []
+    const findingSuppression = findingSuppressions.find(s => s.hash === hash)
+
+    if (findingSuppression) {
+      const expired = isExpired(findingSuppression.expires)
+
+      if (expired && !this.includeExpired) {
+        // Expired - not suppressed
+        return {
+          suppressed: false,
+          match: {
+            type: 'config-finding',
+            reason: findingSuppression.reason,
+            expires: findingSuppression.expires,
+            expired: true,
+          },
+          hash,
+        }
+      }
+
+      return {
+        suppressed: true,
+        match: {
+          type: 'config-finding',
+          reason: findingSuppression.reason,
+          expires: findingSuppression.expires,
+          expired,
+        },
+        hash,
+      }
+    }
+
+    // 3. Check config rule suppressions (by category)
+    const ruleSuppressions = this.config.suppressions?.rules || []
+    const ruleSuppression = ruleSuppressions.find(s => {
+      // Must match category
+      if (s.category !== finding.category) {
+        return false
+      }
+
+      // If paths specified, must match one of them
+      if (s.paths && s.paths.length > 0) {
+        const matchesPath = s.paths.some(pattern =>
+          minimatch(normalizedPath, pattern, { dot: true })
+        )
+        if (!matchesPath) {
+          return false
+        }
+      }
+
+      return true
+    })
+
+    if (ruleSuppression) {
+      const expired = isExpired(ruleSuppression.expires)
+
+      if (expired && !this.includeExpired) {
+        // Expired - not suppressed
+        return {
+          suppressed: false,
+          match: {
+            type: 'config-rule',
+            reason: ruleSuppression.reason,
+            expires: ruleSuppression.expires,
+            expired: true,
+          },
+          hash,
+        }
+      }
+
+      return {
+        suppressed: true,
+        match: {
+          type: 'config-rule',
+          reason: ruleSuppression.reason,
+          expires: ruleSuppression.expires,
+          expired,
+        },
+        hash,
+      }
+    }
+
+    // Not suppressed
+    return {
+      suppressed: false,
+      hash,
+    }
+  }
+
+  /**
+   * Apply suppressions to a list of findings
+   */
+  applySuppressions(
+    findings: Vulnerability[],
+    files: ScanFile[]
+  ): SuppressionResult {
+    // Build file content lookup
+    const fileContentMap = new Map<string, string>()
+    for (const file of files) {
+      fileContentMap.set(normalizePathForHash(file.path), file.content)
+    }
+
+    const passed: Vulnerability[] = []
+    const suppressed: SuppressedVulnerability[] = []
+    let expiredCount = 0
+
+    const stats = {
+      total: findings.length,
+      inlineSuppressed: 0,
+      configFindingSuppressed: 0,
+      configRuleSuppressed: 0,
+      expired: 0,
+    }
+
+    for (const finding of findings) {
+      // Get file content for inline suppression checking
+      const normalizedPath = normalizePathForHash(finding.filePath)
+      const fileContent = fileContentMap.get(normalizedPath)
+
+      const result = this.isFindingSuppressed(finding, fileContent)
+
+      if (result.suppressed) {
+        suppressed.push({
+          vulnerability: {
+            id: finding.id,
+            filePath: finding.filePath,
+            lineNumber: finding.lineNumber,
+            category: finding.category,
+            severity: finding.severity,
+            title: finding.title,
+          },
+          suppression: {
+            type: result.match!.type,
+            reason: result.match!.reason,
+            expires: result.match!.expires,
+            hash: result.hash,
+          },
+        })
+
+        // Update stats
+        switch (result.match!.type) {
+          case 'inline':
+            stats.inlineSuppressed++
+            break
+          case 'config-finding':
+            stats.configFindingSuppressed++
+            break
+          case 'config-rule':
+            stats.configRuleSuppressed++
+            break
+        }
+      } else {
+        passed.push(finding)
+
+        // Track expired suppressions
+        if (result.match?.expired) {
+          expiredCount++
+          stats.expired++
+        }
+      }
+    }
+
+    return {
+      findings: passed,
+      suppressed,
+      expiredSuppressions: expiredCount,
+      stats,
+    }
+  }
+
+  /**
+   * Get all suppressions from config
+   */
+  getAllSuppressions(): {
+    rules: RuleSuppression[]
+    findings: FindingSuppression[]
+  } {
+    return {
+      rules: this.config.suppressions?.rules || [],
+      findings: this.config.suppressions?.findings || [],
+    }
+  }
+
+  /**
+   * Get ignore patterns from config
+   */
+  getIgnorePatterns(): string[] {
+    return this.config.ignore || []
+  }
+
+  /**
+   * Check if suppression system is active (has any suppressions)
+   */
+  hasSuppressions(): boolean {
+    const rules = this.config.suppressions?.rules || []
+    const findings = this.config.suppressions?.findings || []
+    const ignore = this.config.ignore || []
+
+    return rules.length > 0 || findings.length > 0 || ignore.length > 0
+  }
+
+  /**
+   * Get summary of suppression configuration
+   */
+  getSummary(): {
+    configPath: string | undefined
+    ruleCount: number
+    findingCount: number
+    ignorePatternCount: number
+    hasErrors: boolean
+  } {
+    return {
+      configPath: this.configPath,
+      ruleCount: this.config.suppressions?.rules?.length || 0,
+      findingCount: this.config.suppressions?.findings?.length || 0,
+      ignorePatternCount: this.config.ignore?.length || 0,
+      hasErrors: this.configErrors.length > 0,
+    }
+  }
+
+  /**
+   * Clear the inline suppression cache
+   * (useful if files have been modified)
+   */
+  clearCache(): void {
+    this.inlineSuppressionCache.clear()
+  }
+}