@oculum/scanner 1.0.9 → 1.0.11

package/src/formatters/github-comment.ts

@@ -35,7 +35,29 @@ const CATEGORY_DOCS: Partial<Record<VulnerabilityCategory, string>> = {
 }
 
 /**
- * Format a single finding as a markdown list item
+ * Helper to determine language from file path
+ */
+function getLanguageFromPath(filePath: string): string {
+  const ext = filePath.split('.').pop()?.toLowerCase() || ''
+  const langMap: Record<string, string> = {
+    ts: 'typescript',
+    tsx: 'typescript',
+    js: 'javascript',
+    jsx: 'javascript',
+    py: 'python',
+    go: 'go',
+    java: 'java',
+    rb: 'ruby',
+    php: 'php',
+    yaml: 'yaml',
+    yml: 'yaml',
+    json: 'json',
+  }
+  return langMap[ext] || ''
+}
+
+/**
+ * Format a single finding as a markdown section with actionable info (PRO-82)
  */
 function formatFinding(finding: Vulnerability, options: { showFile?: boolean; showDocs?: boolean } = {}): string {
   const { showFile = true, showDocs = true } = options
@@ -44,18 +66,43 @@ function formatFinding(finding: Vulnerability, options: { showFile?: boolean; sh
     ? `\`${finding.filePath}:${finding.lineNumber}\``
     : `Line ${finding.lineNumber}`
 
-  let md = `- ${badge} **${finding.title}**\n`
-  md += `  - 📍 ${location}\n`
-  md += `  - ${finding.description}\n`
+  let md = `#### ${badge} ${finding.title}\n\n`
+  md += `📍 ${location}\n\n`
+
+  // Impact (why this matters) - shown if available
+  if (finding.impact) {
+    md += `**Impact:** ${finding.impact}\n\n`
+  }
+
+  // Code snippet in collapsible
+  if (finding.lineContent && finding.lineContent.trim()) {
+    const language = getLanguageFromPath(finding.filePath)
+    md += `<details>\n<summary>View code</summary>\n\n`
+    md += `\`\`\`${language}\n${finding.lineContent.trim()}\n\`\`\`\n\n`
+    md += `</details>\n\n`
+  }
 
-  if (finding.suggestedFix) {
-    md += `  - 💡 **Fix:** ${finding.suggestedFix}\n`
+  // Fix steps - shown as numbered list (PRO-82)
+  if (finding.fixSteps && finding.fixSteps.length > 0) {
+    md += `**Fix:**\n`
+    finding.fixSteps.forEach((step, i) => {
+      md += `${i + 1}. ${step}\n`
+    })
+    md += '\n'
+  } else if (finding.suggestedFix) {
+    // Fallback to legacy field
+    md += `💡 **Fix:** ${finding.suggestedFix}\n\n`
   }
 
-  // Add documentation link if available
+  // Documentation links
   const docsUrl = CATEGORY_DOCS[finding.category]
-  if (showDocs && docsUrl) {
-    md += `  - 📚 [Learn more](${docsUrl})\n`
+  const referenceUrl = finding.references && finding.references.length > 0 ? finding.references[0] : null
+
+  if (showDocs && (docsUrl || referenceUrl)) {
+    const links: string[] = []
+    if (docsUrl) links.push(`[Learn more](${docsUrl})`)
+    if (referenceUrl && referenceUrl !== docsUrl) links.push(`[OWASP/CWE](${referenceUrl})`)
+    md += links.join(' · ') + '\n\n'
   }
 
   return md
@@ -357,7 +404,7 @@ export function formatShortStatus(result: ScanResult): string {
 }
 
 /**
- * Format as inline annotation for GitHub check run
+ * Format as inline annotation for GitHub check run (PRO-82: actionable output)
  */
 export function formatAnnotation(finding: Vulnerability): {
   path: string
@@ -371,12 +418,33 @@ export function formatAnnotation(finding: Vulnerability): {
     finding.severity === 'critical' || finding.severity === 'high' ? 'failure' :
     finding.severity === 'medium' ? 'warning' : 'notice'
 
+  // Build actionable message
+  let message = ''
+
+  // Impact first (why this matters)
+  if (finding.impact) {
+    message += `Impact: ${finding.impact}\n\n`
+  }
+
+  // Description
+  message += finding.description
+
+  // Fix steps or legacy suggestedFix
+  if (finding.fixSteps && finding.fixSteps.length > 0) {
+    message += '\n\n💡 Fix:\n'
+    finding.fixSteps.forEach((step, i) => {
+      message += `${i + 1}. ${step}\n`
+    })
+  } else if (finding.suggestedFix) {
+    message += `\n\n💡 Fix: ${finding.suggestedFix}`
+  }
+
   return {
     path: finding.filePath,
     start_line: finding.lineNumber,
     end_line: finding.lineNumber,
     annotation_level: level,
     title: `${SEVERITY_BADGE[finding.severity]} ${finding.title}`,
-    message: finding.description + (finding.suggestedFix ? `\n\n💡 Fix: ${finding.suggestedFix}` : ''),
+    message,
   }
 }

package/src/formatters/index.ts

@@ -44,4 +44,8 @@ export {
   formatSimpleList,
   formatJSON,
   formatSARIF,
+  formatCompactSummary,
+  getNumberedFindings,
+  formatFindingDetail,
+  type CompactSummaryOptions,
 } from './cli-terminal'

package/src/index.ts

@@ -14,6 +14,7 @@ import type {
   ScanModeConfig,
   ScanDepth,
   CancellationToken,
+  SuppressedVulnerabilitySummary,
 } from './types'
 import { SCANNABLE_EXTENSIONS, SPECIAL_FILES, MAX_FILE_SIZE, SCAN_MODE_DEFAULTS } from './types'
 import { runLayer1Scan } from './layer1'
@@ -34,6 +35,14 @@ import {
   computeTierStats,
   formatTierStats,
 } from './tiers'
+// Suppression system
+import { SuppressionManager } from './suppression'
+// Rule metadata for actionable output (PRO-82)
+import { getRuleMetadata } from './rules'
+// Framework-aware fix suggestions (PRO-83)
+import { getFrameworkFix } from './rules/framework-fixes'
+// Project context for framework detection
+import { buildProjectContext, type ProjectContext } from './utils/project-context-builder'
 
 // Maximum candidates per file to send to AI validation (cost control)
 const MAX_VALIDATION_CANDIDATES_PER_FILE = 10
@@ -143,6 +152,10 @@ export interface ScanOptions {
   quiet?: boolean
   /** Cancellation token for aborting scans gracefully */
   cancellationToken?: CancellationToken
+  /** Project path for loading suppression config (defaults to cwd) */
+  projectPath?: string
+  /** Include suppressed findings in output (for --show-suppressed) */
+  showSuppressed?: boolean
 }
 
 export interface ScanProgress {
@@ -286,7 +299,11 @@ export async function runScan(
 
     checkCancelled()
 
+    // Phase timing tracking
+    const phaseTiming: { layer1?: number; layer2?: number; aiValidation?: number; layer3?: number } = {}
+
     // Layer 1: Surface Scan
+    const layer1Start = Date.now()
     reportProgress('layer1', 'Running surface scan (patterns, entropy, config)...')
     let layer1Result = await runLayer1Scan(files, onProgress, cancellationToken)
 
@@ -296,11 +313,13 @@ export async function runScan(
       ...layer1Result,
       vulnerabilities: aggregateLocalhostFindings(layer1Result.vulnerabilities)
     }
-    log(`[Layer1] repo=${repoInfo.name} findings_raw=${layer1RawCount} findings_deduped=${layer1Result.vulnerabilities.length}`)
+    phaseTiming.layer1 = Date.now() - layer1Start
+    log(`[Layer1] repo=${repoInfo.name} findings_raw=${layer1RawCount} findings_deduped=${layer1Result.vulnerabilities.length} duration=${phaseTiming.layer1}ms`)
 
     checkCancelled()
 
     // Layer 2: Structural Scan
+    const layer2Start = Date.now()
     reportProgress('layer2', 'Running structural scan (variables, logic gates)...', layer1Result.vulnerabilities.length)
     const layer2Result = await runLayer2Scan(files, { middlewareConfig, fileAuthImports }, onProgress, cancellationToken)
 
@@ -309,7 +328,8 @@ export async function runScan(
       .filter(([, count]) => count > 0)
       .map(([name, count]) => `${name}:${count}`)
       .join(',')
-    log(`[Layer2] repo=${repoInfo.name} findings_raw=${Object.values(layer2Result.stats.raw).reduce((a, b) => a + b, 0)} findings_deduped=${layer2Result.vulnerabilities.length} heuristic_breakdown={${heuristicBreakdown}}`)
+    phaseTiming.layer2 = Date.now() - layer2Start
+    log(`[Layer2] repo=${repoInfo.name} findings_raw=${Object.values(layer2Result.stats.raw).reduce((a, b) => a + b, 0)} findings_deduped=${layer2Result.vulnerabilities.length} duration=${phaseTiming.layer2}ms heuristic_breakdown={${heuristicBreakdown}}`)
 
     // Combine Layer 1 and Layer 2 findings
     const layer12Findings = [...layer1Result.vulnerabilities, ...layer2Result.vulnerabilities]
@@ -319,9 +339,19 @@ export async function runScan(
     const aggregatedFindings = aggregateNoisyFindings(layer12Findings)
     const aggregatedCount = beforeAggregationCount - aggregatedFindings.length
 
+    // Build project context for framework-aware fixes (PRO-83)
+    // This detects frameworks (Next.js, Express), ORMs (Prisma, Drizzle), and frontend libs (React, Vue)
+    const projectContext = buildProjectContext(files)
+
+    // Enrich findings with metadata from rule registry (PRO-82)
+    // PRO-83: Uses projectContext for framework-specific fix suggestions
+    // This provides default impact, evidence, fixSteps, references for all findings
+    // AI validation can override these later with context-aware content
+    const enrichedFindings = enrichWithMetadata(aggregatedFindings, projectContext)
+
     // Apply tier-based filtering based on scan depth
     // This is the key integration point for the detector tier system
-    const tierFiltered = filterByTierAndDepth(aggregatedFindings, depth)
+    const tierFiltered = filterByTierAndDepth(enrichedFindings, depth)
 
     // Log tier breakdown
     log(`[Scanner] repo=${repoInfo.name} tier_breakdown=${formatTierStats(tierFiltered.tierStats)}`)
@@ -339,7 +369,12 @@ export async function runScan(
     )
 
     // Surface findings that don't need validation (excluding those that do)
-    const noValidationNeeded = tierFiltered.toSurface.filter(v => !additionalValidation.includes(v))
+    const noValidationNeededRaw = tierFiltered.toSurface.filter(v => !additionalValidation.includes(v))
+
+    // Apply auto-dismiss rules to direct-surface findings (mode='surface')
+    // Uses 'surface' mode to exclude cost-saving rules like 'info_severity_core_only'
+    // This ensures test/scanner/example files are dismissed, but info-severity findings still surface
+    const { toValidate: noValidationNeeded, dismissed: surfaceDismissed } = applyAutoDismissRules(noValidationNeededRaw, 'surface')
 
     // Combine tier-filtered validation candidates with additional ones
     const requiresValidation = [...tierFiltered.toValidate, ...additionalValidation]
@@ -347,13 +382,22 @@ export async function runScan(
     // Apply smart auto-dismiss rules BEFORE AI validation (saves API costs)
     const { toValidate: afterAutoDismiss, dismissed: autoDismissed } = applyAutoDismissRules(requiresValidation)
 
-    // Track auto-dismiss by severity for logging
+    // Combine all dismissed findings for logging
+    const allDismissed = [...surfaceDismissed, ...autoDismissed]
+
+    // Track auto-dismiss by severity and category for logging
     const autoDismissBySeverity: Record<string, number> = { info: 0, low: 0, medium: 0, high: 0, critical: 0 }
-    for (const d of autoDismissed) {
+    const autoDismissByCategory: Record<string, number> = {}
+    for (const d of allDismissed) {
       autoDismissBySeverity[d.finding.severity] = (autoDismissBySeverity[d.finding.severity] || 0) + 1
+      autoDismissByCategory[d.finding.category] = (autoDismissByCategory[d.finding.category] || 0) + 1
     }
-    if (autoDismissed.length > 0) {
-      log(`[Layer2] repo=${repoInfo.name} auto_dismissed_total=${autoDismissed.length} by_severity={info:${autoDismissBySeverity.info},low:${autoDismissBySeverity.low},medium:${autoDismissBySeverity.medium},high:${autoDismissBySeverity.high}}`)
+    if (allDismissed.length > 0) {
+      const categoryBreakdown = Object.entries(autoDismissByCategory)
+        .sort(([, a], [, b]) => b - a)
+        .map(([cat, count]) => `${cat}:${count}`)
+        .join(',')
+      log(`[AutoDismiss] repo=${repoInfo.name} total=${allDismissed.length} (surface=${surfaceDismissed.length} validation=${autoDismissed.length}) by_severity={info:${autoDismissBySeverity.info},low:${autoDismissBySeverity.low},medium:${autoDismissBySeverity.medium},high:${autoDismissBySeverity.high}} by_category={${categoryBreakdown}}`)
     }
 
     // Apply per-file cap to validation candidates (cost control)
@@ -370,6 +414,7 @@ export async function runScan(
 
     if (shouldValidate) {
       checkCancelled()
+      const aiValidationStart = Date.now()
       reportProgress('validating', 'AI validating findings (entropy, secrets, AI patterns)...', cappedValidation.length)
 
       // For incremental scans, only validate findings in changed files
@@ -396,8 +441,9 @@ export async function runScan(
         validatedFindings = validationResult.vulnerabilities
         const { stats: validationStats } = validationResult
         capturedValidationStats = validationStats // Capture for return
+        phaseTiming.aiValidation = Date.now() - aiValidationStart
 
-        log(`[AI Validation] repo=${repoInfo.name} depth=${depth} candidates=${findingsToValidate.length} capped_from=${requiresValidation.length} auto_dismissed=${autoDismissed.length} kept=${validationStats.confirmedFindings} rejected=${validationStats.dismissedFindings} downgraded=${validationStats.downgradedFindings}`)
+        log(`[AI Validation] repo=${repoInfo.name} depth=${depth} duration=${phaseTiming.aiValidation}ms candidates=${findingsToValidate.length} capped_from=${requiresValidation.length} auto_dismissed=${autoDismissed.length} kept=${validationStats.confirmedFindings} rejected=${validationStats.dismissedFindings} downgraded=${validationStats.downgradedFindings}`)
         log(`[AI Validation] cost_estimate: input_tokens=${validationStats.estimatedInputTokens} output_tokens=${validationStats.estimatedOutputTokens} cost=$${validationStats.estimatedCost.toFixed(4)} api_calls=${validationStats.apiCalls}`)
 
         // Add back findings that weren't validated (not in changed files)
@@ -411,7 +457,11 @@ export async function runScan(
         validatedFindings.push(...notValidated)
       }
     } else if (scanModeConfig.skipAIValidation) {
-      log(`[AI Validation] repo=${repoInfo.name} depth=${depth} skipped=true reason=scan_mode_config`)
+      log(`[AI Validation] repo=${repoInfo.name} depth=${depth} skipped=true reason=scan_mode_config findings_requiring_validation=${cappedValidation.length}`)
+      // In cheap mode, don't surface findings that require AI validation
+      // These are low-confidence without validation and would be noise
+      // Only surface high-confidence findings that don't need validation
+      validatedFindings = []
     }
 
     // Combine validated and non-validated findings
@@ -423,6 +473,7 @@ export async function runScan(
 
     if (shouldRunLayer3) {
       checkCancelled()
+      const layer3Start = Date.now()
       reportProgress('layer3', 'Running AI semantic analysis...', allVulnerabilities.length)
 
       // For incremental scans, only analyze changed files
@@ -448,26 +499,64 @@ export async function runScan(
         },
         cancellationToken,
       })
+      phaseTiming.layer3 = Date.now() - layer3Start
       allVulnerabilities.push(...layer3Result.vulnerabilities)
-      log(`[Layer3] repo=${repoInfo.name} depth=${depth} files_analyzed=${layer3Result.aiAnalyzed} findings=${layer3Result.vulnerabilities.length}`)
+      log(`[Layer3] repo=${repoInfo.name} depth=${depth} duration=${phaseTiming.layer3}ms files_analyzed=${layer3Result.aiAnalyzed} findings=${layer3Result.vulnerabilities.length}`)
     } else if (scanModeConfig.skipLayer3) {
       log(`[Layer3] repo=${repoInfo.name} depth=${depth} skipped=true reason=scan_mode_config`)
     }
 
+    // Log phase timing summary
+    const phaseTimingStr = Object.entries(phaseTiming)
+      .filter(([, ms]) => ms !== undefined)
+      .map(([phase, ms]) => `${phase}=${ms}ms`)
+      .join(' ')
+    if (phaseTimingStr) {
+      log(`[Scanner] repo=${repoInfo.name} phase_timing: ${phaseTimingStr}`)
+    }
+
     // Deduplicate vulnerabilities
     const uniqueVulnerabilities = deduplicateVulnerabilities(allVulnerabilities)
 
     // Resolve contradictions (e.g., middleware-protected INFO vs missing-auth CRITICAL on same route)
     const resolvedVulnerabilities = resolveContradictions(uniqueVulnerabilities, middlewareConfig)
-    
+
+    // Apply suppressions (inline comments + config file)
+    const projectPath = options.projectPath || process.cwd()
+    const suppressionManager = new SuppressionManager({ projectPath })
+    const suppressionResult = suppressionManager.applySuppressions(resolvedVulnerabilities, files)
+
+    // Log suppression stats if any were suppressed
+    if (suppressionResult.suppressed.length > 0 || suppressionResult.expiredSuppressions > 0) {
+      log(`[Suppression] repo=${repoInfo.name} suppressed=${suppressionResult.suppressed.length} (inline=${suppressionResult.stats.inlineSuppressed} config_finding=${suppressionResult.stats.configFindingSuppressed} config_rule=${suppressionResult.stats.configRuleSuppressed}) expired=${suppressionResult.expiredSuppressions}`)
+    }
+
+    // Use the filtered findings (after suppression)
+    const afterSuppression = suppressionResult.findings
+
     // Sort by severity
-    const sortedVulnerabilities = sortBySeverity(resolvedVulnerabilities)
+    const sortedVulnerabilities = sortBySeverity(afterSuppression)
 
-    // Compute issue-mix counts
+    // 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 = options.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
+
     reportProgress('complete', 'Scan complete!', sortedVulnerabilities.length)
 
     return {
@@ -483,6 +572,10 @@ export async function runScan(
       scanDuration: Date.now() - startTime,
       timestamp: new Date().toISOString(),
       validationStats: capturedValidationStats,
+      suppressionStats: suppressionResult.suppressed.length > 0 || suppressionResult.expiredSuppressions > 0
+        ? suppressionResult.stats
+        : undefined,
+      suppressedVulnerabilities,
     }
   } catch (error) {
     if (cancellationToken?.cancelled) {
@@ -519,6 +612,50 @@ export async function runScan(
   }
 }
 
+/**
+ * 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
+ */
+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
+        // Optionally append code example to description if available
+        // This makes the fix more actionable
+      }
+    }
+
+    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,
+    }
+  })
+}
+
 /**
  * Aggregate noisy findings in the same file to reduce clutter
  * Groups repeated findings with same filePath + category + title
@@ -905,3 +1042,49 @@ export { runLayer3Scan } from './layer3'
 export { buildProjectContext, type ProjectContext } from './utils/project-context-builder'
 export { validateFindingsWithAI, type ValidationStats, type AIValidationResult } from './layer3/anthropic'
 export { createCancellationToken } from './types'
+
+// Suppression system exports
+export {
+  SuppressionManager,
+  computeFindingHash,
+  loadSuppressionConfig,
+  addFindingSuppression,
+  removeFindingSuppression,
+  addRuleSuppression,
+  listSuppressions,
+  parseInlineSuppressions,
+  generateSuppressionComment,
+  isValidHash,
+  type SuppressionConfig,
+  type FindingSuppression,
+  type RuleSuppression,
+  type SuppressionResult,
+  type SuppressedVulnerability,
+} from './suppression'
+
+// Baseline system exports
+export {
+  BaselineManager,
+  computeDiff,
+  hasNewBlockingIssues,
+  formatDiffSummary,
+  BASELINE_FILE_PATH,
+  OCULUM_DIR,
+  type BaselineData,
+  type BaselineFinding,
+  type DiffResult,
+  type BaselineDiff,
+  type BaselineManagerOptions,
+  type LoadBaselineResult,
+  type SaveBaselineResult,
+  type ClearBaselineResult,
+} from './baseline'
+
+// Rule metadata exports (PRO-82)
+export {
+  RULE_REGISTRY,
+  getRuleMetadata,
+  getAllCategories,
+  hasMetadata,
+  type RuleMetadata,
+} from './rules'

package/src/layer1/config-audit.ts

@@ -211,12 +211,33 @@ export const CONFIG_RULES: ConfigRule[] = [
         // Get the package's own npm scope to detect internal monorepo deps
         const ownScope = pkg.name?.startsWith('@') ? pkg.name.split('/')[0] : null
 
+        // Also detect common org scope from other dependencies (for packages without scoped names)
+        // If we see @org/foo and @org/bar in deps, @org is likely the monorepo's scope
+        const scopeCounts: Record<string, number> = {}
+        for (const depName of Object.keys(allDeps)) {
+          if (depName.startsWith('@')) {
+            const scope = depName.split('/')[0]
+            scopeCounts[scope] = (scopeCounts[scope] || 0) + 1
+          }
+        }
+        // Find the most common scope (likely the monorepo's org scope)
+        const inferredScope = Object.entries(scopeCounts)
+          .filter(([, count]) => count >= 2) // At least 2 deps from same scope
+          .sort((a, b) => b[1] - a[1])[0]?.[0] || null
+
         for (const [name, version] of Object.entries(allDeps)) {
           if (version === '*' || version === 'latest') {
-            // Skip internal monorepo packages (same npm scope with * version)
-            // In monorepos, * is used for workspace deps which are resolved locally
+            // Skip internal monorepo packages:
+            // 1. Same npm scope as the package itself
+            // 2. Or same scope as other workspace packages (inferred from multiple deps)
             const depScope = name.startsWith('@') ? name.split('/')[0] : null
-            if (ownScope && depScope === ownScope && version === '*') {
+
+            // Check if this is a workspace package
+            const isWorkspacePackage =
+              (ownScope && depScope === ownScope) ||
+              (inferredScope && depScope === inferredScope && version === '*')
+
+            if (isWorkspacePackage) {
               continue
             }