@oculum/scanner 1.0.0

package/src/__tests__/validation/triage-template.md

@@ -0,0 +1,132 @@
+# M7: Finding Triage Template
+
+Use this template to document triage decisions for each medium+ severity finding from real-repo validation.
+
+## Instructions
+
+1. For each medium+ finding from the validation scan:
+   - Copy the template below
+   - Fill in the finding details
+   - Classify as TP/FP/Borderline
+   - Document your reasoning
+   - Decide on action
+
+2. After triage, calculate FP rate:
+   - FP Rate = FP count / (TP count + FP count)
+   - Target: < 20%
+
+3. For each FP:
+   - Add a regression test to `known-false-positives.test.ts`
+   - Consider tuning the detector if pattern is common
+
+---
+
+## Triage Records
+
+### [Finding #1]
+
+**Category:** [e.g., ai_rag_exfiltration]
+**File:** [e.g., langchainjs/src/retrievers/base.ts]
+**Line:** [e.g., 142]
+**Severity:** [critical/high/medium]
+**Title:** [Finding title from scan]
+
+**Code Context:**
+```typescript
+// Paste relevant code snippet here
+```
+
+**Classification:** [ ] True Positive [ ] False Positive [ ] Borderline
+
+**Code Type:** [ ] Library internal [ ] Example code [ ] Test file [ ] Other
+
+**Reasoning:**
+> [Explain why this is/isn't a real security issue. Consider:
+> - Is this intentional design (library deferring to consumers)?
+> - Is this example/demo code?
+> - Is the finding contextually accurate?]
+
+**Action:**
+- [ ] Keep finding as-is
+- [ ] Tune detector (describe change needed)
+- [ ] Add to known-FP fixtures
+- [ ] Downgrade severity
+
+**Notes:**
+> [Any additional context or follow-up needed]
+
+---
+
+### [Finding #2]
+
+**Category:**
+**File:**
+**Line:**
+**Severity:**
+**Title:**
+
+**Code Context:**
+```typescript
+```
+
+**Classification:** [ ] True Positive [ ] False Positive [ ] Borderline
+
+**Code Type:** [ ] Library internal [ ] Example code [ ] Test file [ ] Other
+
+**Reasoning:**
+>
+
+**Action:**
+- [ ] Keep finding as-is
+- [ ] Tune detector
+- [ ] Add to known-FP fixtures
+- [ ] Downgrade severity
+
+**Notes:**
+>
+
+---
+
+## Summary Statistics
+
+After completing triage:
+
+| Metric | Count |
+|--------|-------|
+| Total medium+ findings | |
+| True Positives | |
+| False Positives | |
+| Borderline | |
+| **FP Rate** | % |
+
+### Notable True Positives
+
+List significant security issues found:
+
+1.
+2.
+3.
+
+### Common False Positive Patterns
+
+List patterns that frequently triggered FPs:
+
+1.
+2.
+3.
+
+### Recommended Detector Tuning
+
+Based on FP analysis:
+
+1. **[Detector name]**: [Suggested change]
+2. **[Detector name]**: [Suggested change]
+
+---
+
+## Action Items
+
+- [ ] Add FP regression tests
+- [ ] Update detectors based on findings
+- [ ] Re-run validation to verify improvements
+- [ ] Update docs/RESULTSCOMPARISON.md with final metrics

package/src/formatters/cli-terminal.ts

@@ -0,0 +1,446 @@
+/**
+ * CLI Terminal Formatter
+ * Formats scan results with ANSI colors for terminal output
+ */
+
+import type { ScanResult, Vulnerability, VulnerabilitySeverity } from '../types'
+import { groupByTheme, getBlockingIssues, GroupedFindings, THEME_CONFIG } from './grouping'
+
+/**
+ * ANSI color codes
+ */
+const colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  underline: '\x1b[4m',
+
+  // Foreground colors
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m',
+
+  // Background colors
+  bgRed: '\x1b[41m',
+  bgYellow: '\x1b[43m',
+  bgBlue: '\x1b[44m',
+}
+
+/**
+ * Severity colors and symbols
+ */
+const SEVERITY_STYLE: Record<VulnerabilitySeverity, { color: string; symbol: string; label: string }> = {
+  critical: { color: colors.bgRed + colors.white, symbol: '●', label: 'CRITICAL' },
+  high: { color: colors.red, symbol: '●', label: 'HIGH' },
+  medium: { color: colors.yellow, symbol: '●', label: 'MEDIUM' },
+  low: { color: colors.blue, symbol: '○', label: 'LOW' },
+  info: { color: colors.gray, symbol: '○', label: 'INFO' },
+}
+
+/**
+ * Format colored text
+ */
+function c(color: string, text: string): string {
+  return `${color}${text}${colors.reset}`
+}
+
+/**
+ * Format severity badge
+ */
+function severityBadge(severity: VulnerabilitySeverity): string {
+  const style = SEVERITY_STYLE[severity]
+  return c(style.color, `${style.symbol} ${style.label}`)
+}
+
+/**
+ * Format a single finding for terminal
+ */
+function formatFinding(finding: Vulnerability, indent: string = '  '): string {
+  const badge = severityBadge(finding.severity)
+  const location = c(colors.cyan, `${finding.filePath}:${finding.lineNumber}`)
+
+  let output = `${indent}${badge} ${c(colors.bold, finding.title)}\n`
+  output += `${indent}   ${location}\n`
+  output += `${indent}   ${c(colors.dim, finding.description)}\n`
+
+  if (finding.suggestedFix) {
+    output += `${indent}   ${c(colors.green, '💡 ' + finding.suggestedFix)}\n`
+  }
+
+  return output
+}
+
+/**
+ * Format a group of findings
+ */
+function formatGroup(group: GroupedFindings, maxFindings: number = 10): string {
+  const { theme, themeName, findings, severityCounts } = group
+  const config = THEME_CONFIG[theme]
+
+  // Count summary
+  const counts: string[] = []
+  if (severityCounts.critical > 0) counts.push(c(colors.red, `${severityCounts.critical} critical`))
+  if (severityCounts.high > 0) counts.push(c(colors.red, `${severityCounts.high} high`))
+  if (severityCounts.medium > 0) counts.push(c(colors.yellow, `${severityCounts.medium} medium`))
+  if (severityCounts.low > 0) counts.push(c(colors.blue, `${severityCounts.low} low`))
+  if (severityCounts.info > 0) counts.push(c(colors.gray, `${severityCounts.info} info`))
+
+  let output = `\n${c(colors.bold, `${config.icon} ${themeName}`)} (${counts.join(', ')})\n`
+  output += c(colors.dim, '─'.repeat(60)) + '\n'
+
+  // Show findings
+  const shown = findings.slice(0, maxFindings)
+  for (const finding of shown) {
+    output += formatFinding(finding) + '\n'
+  }
+
+  // Truncation notice
+  if (findings.length > maxFindings) {
+    output += c(colors.dim, `  ... and ${findings.length - maxFindings} more\n`)
+  }
+
+  return output
+}
+
+/**
+ * Format full scan result for terminal
+ */
+export function formatTerminalOutput(result: ScanResult, options: {
+  maxFindingsPerGroup?: number
+  showAllFindings?: boolean
+  noColor?: boolean
+} = {}): string {
+  const {
+    maxFindingsPerGroup = 10,
+    showAllFindings = false,
+  } = options
+
+  const { vulnerabilities, severityCounts, hasBlockingIssues, filesScanned, scanDuration } = result
+
+  let output = '\n'
+
+  // Header
+  output += c(colors.bold, '═'.repeat(60)) + '\n'
+  output += c(colors.bold, '  OCULUM SECURITY SCAN RESULTS') + '\n'
+  output += c(colors.bold, '═'.repeat(60)) + '\n\n'
+
+  // Status
+  if (hasBlockingIssues) {
+    const blocking = severityCounts.critical + severityCounts.high
+    output += c(colors.bgRed + colors.white + colors.bold, ` 🚨 ${blocking} BLOCKING ISSUES FOUND `) + '\n\n'
+  } else if (vulnerabilities.length > 0) {
+    output += c(colors.yellow, `⚠️  ${vulnerabilities.length} issues found (no blocking issues)`) + '\n\n'
+  } else {
+    output += c(colors.green, '✅ No security issues found!') + '\n\n'
+    output += c(colors.dim, `Scanned ${filesScanned} files in ${(scanDuration / 1000).toFixed(1)}s`) + '\n'
+    return output
+  }
+
+  // Summary counts
+  output += c(colors.bold, 'Summary:') + '\n'
+  if (severityCounts.critical > 0) output += `  ${severityBadge('critical')}  ${severityCounts.critical}\n`
+  if (severityCounts.high > 0) output += `  ${severityBadge('high')}      ${severityCounts.high}\n`
+  if (severityCounts.medium > 0) output += `  ${severityBadge('medium')}    ${severityCounts.medium}\n`
+  if (severityCounts.low > 0) output += `  ${severityBadge('low')}       ${severityCounts.low}\n`
+  if (severityCounts.info > 0) output += `  ${severityBadge('info')}      ${severityCounts.info}\n`
+  output += '\n'
+
+  // Blocking issues first
+  const blockingIssues = getBlockingIssues(vulnerabilities)
+  if (blockingIssues.length > 0) {
+    output += c(colors.bgRed + colors.white + colors.bold, ' BLOCKING ISSUES ') + '\n'
+    output += c(colors.red, 'These must be fixed before merging:') + '\n\n'
+
+    for (const finding of blockingIssues.slice(0, 10)) {
+      output += formatFinding(finding)
+      output += '\n'
+    }
+
+    if (blockingIssues.length > 10) {
+      output += c(colors.dim, `  ... and ${blockingIssues.length - 10} more blocking issues\n`)
+    }
+
+    output += '\n'
+  }
+
+  // Grouped findings
+  const grouped = groupByTheme(vulnerabilities)
+  output += c(colors.bold, '─'.repeat(60)) + '\n'
+  output += c(colors.bold, 'ALL FINDINGS BY CATEGORY') + '\n'
+
+  for (const group of grouped) {
+    // Skip if only showing non-blocking and all are blocking
+    if (!showAllFindings) {
+      const nonBlocking = group.findings.filter(
+        f => f.severity !== 'critical' && f.severity !== 'high'
+      )
+      if (nonBlocking.length === 0 && blockingIssues.length > 0) continue
+    }
+
+    output += formatGroup(group, maxFindingsPerGroup)
+  }
+
+  // Footer
+  output += '\n' + c(colors.dim, '─'.repeat(60)) + '\n'
+  output += c(colors.dim, `Scanned ${filesScanned} files in ${(scanDuration / 1000).toFixed(1)}s`) + '\n'
+
+  return output
+}
+
+/**
+ * Format as simple list (no grouping, no colors)
+ */
+export function formatSimpleList(vulnerabilities: Vulnerability[]): string {
+  let output = ''
+
+  for (const finding of vulnerabilities) {
+    const severity = finding.severity.toUpperCase().padEnd(8)
+    output += `[${severity}] ${finding.filePath}:${finding.lineNumber} - ${finding.title}\n`
+  }
+
+  return output
+}
+
+/**
+ * Format as JSON (for piping to other tools)
+ */
+export function formatJSON(result: ScanResult, pretty: boolean = false): string {
+  if (pretty) {
+    return JSON.stringify(result, null, 2)
+  }
+  return JSON.stringify(result)
+}
+
+/**
+ * Rule metadata for SARIF output
+ */
+const RULE_METADATA: Record<string, { name: string; description: string; helpUri: string; tags: string[] }> = {
+  hardcoded_secret: {
+    name: 'Hardcoded Secret',
+    description: 'Sensitive credentials or API keys hardcoded in source code. These can be extracted from version control history or compiled binaries.',
+    helpUri: 'https://oculum.dev/docs/rules/hardcoded-secrets',
+    tags: ['security', 'secrets', 'credentials'],
+  },
+  high_entropy_string: {
+    name: 'High Entropy String',
+    description: 'A high-entropy string that may be a secret or API key. Review to ensure it is not sensitive data.',
+    helpUri: 'https://oculum.dev/docs/rules/high-entropy',
+    tags: ['security', 'secrets'],
+  },
+  ai_prompt_injection: {
+    name: 'AI Prompt Injection',
+    description: 'User input is included in AI prompts without proper sanitization, potentially allowing prompt injection attacks.',
+    helpUri: 'https://oculum.dev/docs/rules/prompt-injection',
+    tags: ['security', 'ai', 'injection'],
+  },
+  ai_unsafe_execution: {
+    name: 'AI Unsafe Execution',
+    description: 'AI-generated content is used in code execution, SQL queries, or other dangerous sinks without validation.',
+    helpUri: 'https://oculum.dev/docs/rules/unsafe-execution',
+    tags: ['security', 'ai', 'injection'],
+  },
+  ai_overpermissive_tool: {
+    name: 'AI Overpermissive Tool',
+    description: 'AI agent tool has excessive permissions without proper restrictions or sandboxing.',
+    helpUri: 'https://oculum.dev/docs/rules/overpermissive-tools',
+    tags: ['security', 'ai', 'authorization'],
+  },
+  ai_rag_exfiltration: {
+    name: 'AI RAG Data Exfiltration',
+    description: 'RAG (Retrieval Augmented Generation) queries may expose data across tenant boundaries or leak sensitive context.',
+    helpUri: 'https://oculum.dev/docs/rules/rag-exfiltration',
+    tags: ['security', 'ai', 'data-exposure'],
+  },
+  ai_endpoint_unprotected: {
+    name: 'AI Endpoint Unprotected',
+    description: 'AI endpoint lacks authentication or rate limiting, potentially allowing abuse or cost attacks.',
+    helpUri: 'https://oculum.dev/docs/rules/unprotected-endpoints',
+    tags: ['security', 'ai', 'authentication'],
+  },
+  ai_schema_mismatch: {
+    name: 'AI Schema Validation Missing',
+    description: 'AI-generated output is used without schema validation, potentially allowing malformed or malicious data.',
+    helpUri: 'https://oculum.dev/docs/rules/schema-validation',
+    tags: ['security', 'ai', 'validation'],
+  },
+  sql_injection: {
+    name: 'SQL Injection',
+    description: 'User input is concatenated into SQL queries without parameterization, allowing SQL injection attacks.',
+    helpUri: 'https://oculum.dev/docs/rules/sql-injection',
+    tags: ['security', 'injection', 'database'],
+  },
+  xss: {
+    name: 'Cross-Site Scripting (XSS)',
+    description: 'User input is rendered in HTML without proper escaping, allowing script injection.',
+    helpUri: 'https://oculum.dev/docs/rules/xss',
+    tags: ['security', 'injection', 'web'],
+  },
+  command_injection: {
+    name: 'Command Injection',
+    description: 'User input is passed to shell commands without sanitization, allowing arbitrary command execution.',
+    helpUri: 'https://oculum.dev/docs/rules/command-injection',
+    tags: ['security', 'injection', 'shell'],
+  },
+  missing_auth: {
+    name: 'Missing Authentication',
+    description: 'Sensitive endpoint or route lacks authentication checks.',
+    helpUri: 'https://oculum.dev/docs/rules/missing-auth',
+    tags: ['security', 'authentication'],
+  },
+  data_exposure: {
+    name: 'Data Exposure',
+    description: 'Sensitive data may be exposed through logging, error messages, or API responses.',
+    helpUri: 'https://oculum.dev/docs/rules/data-exposure',
+    tags: ['security', 'data-exposure'],
+  },
+  insecure_config: {
+    name: 'Insecure Configuration',
+    description: 'Security-relevant configuration is set to an insecure value.',
+    helpUri: 'https://oculum.dev/docs/rules/insecure-config',
+    tags: ['security', 'configuration'],
+  },
+  dangerous_function: {
+    name: 'Dangerous Function',
+    description: 'Use of a function known to be dangerous or deprecated for security reasons.',
+    helpUri: 'https://oculum.dev/docs/rules/dangerous-functions',
+    tags: ['security', 'code-quality'],
+  },
+}
+
+/**
+ * Format as SARIF (Static Analysis Results Interchange Format)
+ * For integration with GitHub Code Scanning
+ */
+export function formatSARIF(result: ScanResult): object {
+  return {
+    $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
+    version: '2.1.0',
+    runs: [{
+      tool: {
+        driver: {
+          name: 'Oculum',
+          version: '1.0.0',
+          informationUri: 'https://oculum.dev',
+          organization: 'Oculum Security',
+          rules: getUniqueRules(result.vulnerabilities),
+        },
+      },
+      results: result.vulnerabilities.map((v, index) => ({
+        ruleId: v.category,
+        ruleIndex: getRuleIndex(result.vulnerabilities, v.category),
+        level: mapSeverityToSARIF(v.severity),
+        message: {
+          text: v.description,
+        },
+        locations: [{
+          physicalLocation: {
+            artifactLocation: {
+              uri: v.filePath,
+              uriBaseId: '%SRCROOT%',
+            },
+            region: {
+              startLine: v.lineNumber,
+              startColumn: 1,
+              snippet: v.lineContent ? { text: v.lineContent } : undefined,
+            },
+          },
+        }],
+        fingerprints: {
+          'oculum/v1': `${v.category}:${v.filePath}:${v.lineNumber}`,
+        },
+        fixes: v.suggestedFix ? [{
+          description: {
+            text: v.suggestedFix,
+          },
+        }] : undefined,
+        properties: {
+          confidence: v.confidence,
+          layer: v.layer,
+        },
+      })),
+      columnKind: 'utf16CodeUnits',
+    }],
+  }
+}
+
+function mapSeverityToSARIF(severity: VulnerabilitySeverity): 'error' | 'warning' | 'note' {
+  switch (severity) {
+    case 'critical':
+    case 'high':
+      return 'error'
+    case 'medium':
+      return 'warning'
+    default:
+      return 'note'
+  }
+}
+
+function getRuleIndex(vulnerabilities: Vulnerability[], category: string): number {
+  const seen = new Set<string>()
+  let index = 0
+  for (const v of vulnerabilities) {
+    if (!seen.has(v.category)) {
+      if (v.category === category) return index
+      seen.add(v.category)
+      index++
+    }
+  }
+  return 0
+}
+
+function getUniqueRules(vulnerabilities: Vulnerability[]): object[] {
+  const seen = new Set<string>()
+  const rules: object[] = []
+
+  for (const v of vulnerabilities) {
+    if (seen.has(v.category)) continue
+    seen.add(v.category)
+
+    const metadata = RULE_METADATA[v.category]
+    const ruleName = metadata?.name || v.category.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase())
+
+    rules.push({
+      id: v.category,
+      name: ruleName,
+      shortDescription: { text: ruleName },
+      fullDescription: {
+        text: metadata?.description || v.description,
+      },
+      helpUri: metadata?.helpUri || `https://oculum.dev/docs/rules/${v.category.replace(/_/g, '-')}`,
+      help: {
+        text: metadata?.description || v.description,
+        markdown: `# ${ruleName}\n\n${metadata?.description || v.description}\n\n[Learn more](${metadata?.helpUri || 'https://oculum.dev/docs'})`,
+      },
+      defaultConfiguration: {
+        level: mapSeverityToSARIF(v.severity),
+      },
+      properties: {
+        tags: metadata?.tags || ['security'],
+        precision: v.confidence === 'high' ? 'high' : v.confidence === 'medium' ? 'medium' : 'low',
+        'security-severity': mapSeverityToScore(v.severity),
+      },
+    })
+  }
+
+  return rules
+}
+
+function mapSeverityToScore(severity: VulnerabilitySeverity): string {
+  switch (severity) {
+    case 'critical':
+      return '9.0'
+    case 'high':
+      return '7.0'
+    case 'medium':
+      return '5.0'
+    case 'low':
+      return '3.0'
+    default:
+      return '1.0'
+  }
+}