@oculum/scanner 1.0.0

package/src/formatters/github-comment.ts

@@ -0,0 +1,382 @@
+/**
+ * GitHub Comment Formatter
+ * Formats scan results as markdown for GitHub PR comments
+ */
+
+import type { ScanResult, Vulnerability, VulnerabilitySeverity, VulnerabilityCategory } from '../types'
+import { groupByTheme, limitPerGroup, getBlockingIssues, GroupedFindings } from './grouping'
+
+/**
+ * Severity badges for GitHub markdown
+ */
+const SEVERITY_BADGE: Record<VulnerabilitySeverity, string> = {
+  critical: '🔴 Critical',
+  high: '🟠 High',
+  medium: '🟡 Medium',
+  low: '🔵 Low',
+  info: '⚪ Info',
+}
+
+/**
+ * Category documentation URLs
+ */
+const CATEGORY_DOCS: Partial<Record<VulnerabilityCategory, string>> = {
+  hardcoded_secret: 'https://oculum.dev/docs/rules/hardcoded-secrets',
+  ai_prompt_injection: 'https://oculum.dev/docs/rules/prompt-injection',
+  ai_unsafe_execution: 'https://oculum.dev/docs/rules/unsafe-execution',
+  ai_overpermissive_tool: 'https://oculum.dev/docs/rules/overpermissive-tools',
+  ai_rag_exfiltration: 'https://oculum.dev/docs/rules/rag-exfiltration',
+  ai_endpoint_unprotected: 'https://oculum.dev/docs/rules/unprotected-endpoints',
+  ai_schema_mismatch: 'https://oculum.dev/docs/rules/schema-validation',
+  sql_injection: 'https://oculum.dev/docs/rules/sql-injection',
+  xss: 'https://oculum.dev/docs/rules/xss',
+  missing_auth: 'https://oculum.dev/docs/rules/missing-auth',
+  data_exposure: 'https://oculum.dev/docs/rules/data-exposure',
+}
+
+/**
+ * Format a single finding as a markdown list item
+ */
+function formatFinding(finding: Vulnerability, options: { showFile?: boolean; showDocs?: boolean } = {}): string {
+  const { showFile = true, showDocs = true } = options
+  const badge = SEVERITY_BADGE[finding.severity]
+  const location = showFile
+    ? `\`${finding.filePath}:${finding.lineNumber}\``
+    : `Line ${finding.lineNumber}`
+
+  let md = `- ${badge} **${finding.title}**\n`
+  md += `  - 📍 ${location}\n`
+  md += `  - ${finding.description}\n`
+
+  if (finding.suggestedFix) {
+    md += `  - 💡 **Fix:** ${finding.suggestedFix}\n`
+  }
+
+  // Add documentation link if available
+  const docsUrl = CATEGORY_DOCS[finding.category]
+  if (showDocs && docsUrl) {
+    md += `  - 📚 [Learn more](${docsUrl})\n`
+  }
+
+  return md
+}
+
+/**
+ * Format a group of findings
+ */
+function formatGroup(group: GroupedFindings, maxFindings: number = 5): string {
+  const { themeIcon, themeName, findings, severityCounts } = group
+
+  // Count summary
+  const counts: string[] = []
+  if (severityCounts.critical > 0) counts.push(`${severityCounts.critical} critical`)
+  if (severityCounts.high > 0) counts.push(`${severityCounts.high} high`)
+  if (severityCounts.medium > 0) counts.push(`${severityCounts.medium} medium`)
+  if (severityCounts.low > 0) counts.push(`${severityCounts.low} low`)
+  if (severityCounts.info > 0) counts.push(`${severityCounts.info} info`)
+
+  let md = `### ${themeIcon} ${themeName}\n`
+  md += `> ${counts.join(', ')}\n\n`
+
+  // Show top findings
+  const shown = findings.slice(0, maxFindings)
+  for (const finding of shown) {
+    md += formatFinding(finding) + '\n'
+  }
+
+  // Show truncation notice if needed
+  if (findings.length > maxFindings) {
+    md += `<details>\n<summary>+ ${findings.length - maxFindings} more ${themeName.toLowerCase()} issues</summary>\n\n`
+    for (const finding of findings.slice(maxFindings)) {
+      md += formatFinding(finding) + '\n'
+    }
+    md += `</details>\n`
+  }
+
+  return md
+}
+
+/**
+ * Options for GitHub comment formatting
+ */
+export interface GitHubCommentOptions {
+  maxFindingsPerGroup?: number
+  showAllFindings?: boolean
+  includeFooter?: boolean
+  scanDepth?: 'cheap' | 'validated' | 'deep'
+  previousScanCounts?: {
+    critical: number
+    high: number
+    medium: number
+    low: number
+    info: number
+  }
+}
+
+/**
+ * Format scan result as GitHub PR comment
+ */
+export function formatGitHubComment(result: ScanResult, options: GitHubCommentOptions = {}): string {
+  const {
+    maxFindingsPerGroup = 5,
+    showAllFindings = false,
+    includeFooter = true,
+    scanDepth,
+    previousScanCounts,
+  } = options
+
+  const { vulnerabilities, severityCounts, hasBlockingIssues } = result
+
+  // Professional header with Oculum branding
+  let md = `<!-- oculum-security-scan -->\n`
+  md += `<div align="center">\n\n`
+  md += `# 🛡️ Oculum Security Scan\n\n`
+  md += `</div>\n\n`
+
+  // Status banner
+  if (hasBlockingIssues) {
+    const blocking = severityCounts.critical + severityCounts.high
+    md += `> 🚨 **${blocking} blocking issue${blocking === 1 ? '' : 's'} found** — These must be addressed before merging.\n\n`
+  } else if (vulnerabilities.length > 0) {
+    md += `> ⚠️ **${vulnerabilities.length} issue${vulnerabilities.length === 1 ? '' : 's'} found** — Review recommended, but no blocking issues.\n\n`
+  } else {
+    md += `> ✅ **No security issues detected** — This PR looks good!\n\n`
+    md += formatScanMetadata(result, scanDepth)
+    if (includeFooter) {
+      md += formatFooter()
+    }
+    return md
+  }
+
+  // Comparison with previous scan if available
+  if (previousScanCounts) {
+    md += formatComparison(severityCounts, previousScanCounts)
+  }
+
+  // Summary section
+  md += `## 📊 Summary\n\n`
+  md += formatSummaryTable(severityCounts)
+  md += '\n'
+
+  // Scan metadata
+  md += formatScanMetadata(result, scanDepth)
+
+  // Blocking issues section (critical + high)
+  const blockingIssues = getBlockingIssues(vulnerabilities)
+  if (blockingIssues.length > 0) {
+    md += `## 🚨 Blocking Issues\n\n`
+    md += `> These issues must be fixed before merging.\n\n`
+
+    for (const finding of blockingIssues.slice(0, 10)) {
+      md += formatFinding(finding) + '\n'
+    }
+
+    if (blockingIssues.length > 10) {
+      md += `<details>\n<summary>+ ${blockingIssues.length - 10} more blocking issues</summary>\n\n`
+      for (const finding of blockingIssues.slice(10)) {
+        md += formatFinding(finding, { showDocs: false }) + '\n'
+      }
+      md += `</details>\n`
+    }
+    md += '\n'
+  }
+
+  // All findings grouped by theme
+  const grouped = groupByTheme(vulnerabilities)
+  const limited = showAllFindings ? grouped : limitPerGroup(grouped, 10)
+
+  // Only show non-blocking findings in "All Findings" section
+  const hasNonBlockingFindings = vulnerabilities.some(
+    v => v.severity !== 'critical' && v.severity !== 'high'
+  )
+
+  if (hasNonBlockingFindings) {
+    md += `## 📋 All Findings by Category\n\n`
+
+    for (const group of limited) {
+      // Skip groups with only blocking issues (already shown above)
+      const nonBlockingInGroup = group.findings.filter(
+        f => f.severity !== 'critical' && f.severity !== 'high'
+      )
+      if (nonBlockingInGroup.length === 0) continue
+
+      md += formatGroup(group, maxFindingsPerGroup) + '\n'
+    }
+  }
+
+  // Quick actions
+  md += formatQuickActions(hasBlockingIssues)
+
+  // Footer
+  if (includeFooter) {
+    md += formatFooter()
+  }
+
+  return md
+}
+
+/**
+ * Format summary table
+ */
+function formatSummaryTable(severityCounts: Record<VulnerabilitySeverity, number>): string {
+  let md = `| Severity | Count | Status |\n`
+  md += `|:---------|:-----:|:------:|\n`
+
+  if (severityCounts.critical > 0) {
+    md += `| 🔴 **Critical** | ${severityCounts.critical} | ❌ Blocking |\n`
+  }
+  if (severityCounts.high > 0) {
+    md += `| 🟠 **High** | ${severityCounts.high} | ❌ Blocking |\n`
+  }
+  if (severityCounts.medium > 0) {
+    md += `| 🟡 Medium | ${severityCounts.medium} | ⚠️ Review |\n`
+  }
+  if (severityCounts.low > 0) {
+    md += `| 🔵 Low | ${severityCounts.low} | ℹ️ Info |\n`
+  }
+  if (severityCounts.info > 0) {
+    md += `| ⚪ Info | ${severityCounts.info} | ℹ️ Info |\n`
+  }
+
+  return md
+}
+
+/**
+ * Format comparison with previous scan
+ */
+function formatComparison(
+  current: Record<VulnerabilitySeverity, number>,
+  previous: Record<VulnerabilitySeverity, number>
+): string {
+  const currentTotal = Object.values(current).reduce((a, b) => a + b, 0)
+  const previousTotal = Object.values(previous).reduce((a, b) => a + b, 0)
+  const diff = currentTotal - previousTotal
+
+  const currentBlocking = current.critical + current.high
+  const previousBlocking = previous.critical + previous.high
+  const blockingDiff = currentBlocking - previousBlocking
+
+  let md = `### 📈 Changes from Previous Scan\n\n`
+
+  if (diff === 0 && blockingDiff === 0) {
+    md += `No change in findings.\n\n`
+  } else {
+    const parts: string[] = []
+
+    if (blockingDiff > 0) {
+      parts.push(`🔺 **${blockingDiff} new blocking issue${blockingDiff === 1 ? '' : 's'}**`)
+    } else if (blockingDiff < 0) {
+      parts.push(`🔻 **${Math.abs(blockingDiff)} blocking issue${Math.abs(blockingDiff) === 1 ? '' : 's'} resolved**`)
+    }
+
+    if (diff > 0 && diff !== blockingDiff) {
+      parts.push(`${diff - blockingDiff} new non-blocking issue${diff - blockingDiff === 1 ? '' : 's'}`)
+    } else if (diff < 0 && diff !== blockingDiff) {
+      parts.push(`${Math.abs(diff - blockingDiff)} non-blocking issue${Math.abs(diff - blockingDiff) === 1 ? '' : 's'} resolved`)
+    }
+
+    md += parts.join(' • ') + '\n\n'
+  }
+
+  return md
+}
+
+/**
+ * Format scan metadata
+ */
+function formatScanMetadata(result: ScanResult, scanDepth?: string): string {
+  let md = `<details>\n<summary>📋 Scan Details</summary>\n\n`
+  md += `| Metric | Value |\n`
+  md += `|--------|-------|\n`
+  md += `| Files scanned | ${result.filesScanned} |\n`
+  md += `| Files skipped | ${result.filesSkipped} |\n`
+  md += `| Scan duration | ${(result.scanDuration / 1000).toFixed(1)}s |\n`
+  if (scanDepth) {
+    const depthLabels: Record<string, string> = {
+      cheap: 'Fast (pattern matching)',
+      validated: 'Validated (AI-assisted)',
+      deep: 'Deep (full semantic)',
+    }
+    md += `| Scan depth | ${depthLabels[scanDepth] || scanDepth} |\n`
+  }
+  md += `| Timestamp | ${result.timestamp} |\n`
+  md += `\n</details>\n\n`
+  return md
+}
+
+/**
+ * Format quick actions section
+ */
+function formatQuickActions(hasBlockingIssues: boolean): string {
+  let md = `## 🎯 Quick Actions\n\n`
+
+  if (hasBlockingIssues) {
+    md += `- [ ] Fix all blocking issues before merging\n`
+    md += `- [ ] Review medium/low severity findings\n`
+  } else {
+    md += `- [ ] Review findings and address as needed\n`
+  }
+
+  md += `- [ ] Mark false positives with \`// oculum-ignore\` comment\n`
+  md += `- 📖 [View documentation](https://oculum.dev/docs)\n`
+  md += `- 🐛 [Report false positive](https://github.com/oculum-security/oculum/issues/new?template=false-positive.md)\n\n`
+
+  return md
+}
+
+/**
+ * Format footer
+ */
+function formatFooter(): string {
+  let md = `---\n\n`
+  md += `<div align="center">\n\n`
+  md += `🛡️ Powered by [Oculum Security Scanner](https://oculum.dev) • `
+  md += `[Documentation](https://oculum.dev/docs) • `
+  md += `[Get Pro](https://oculum.dev/pricing)\n\n`
+  md += `</div>\n`
+  return md
+}
+
+/**
+ * Format scan result as a short status comment (for check run summary)
+ */
+export function formatShortStatus(result: ScanResult): string {
+  const { severityCounts, hasBlockingIssues, filesScanned, scanDuration } = result
+
+  if (hasBlockingIssues) {
+    const blocking = severityCounts.critical + severityCounts.high
+    return `🚨 Found ${blocking} blocking security issue${blocking === 1 ? '' : 's'} (${severityCounts.critical} critical, ${severityCounts.high} high)`
+  }
+
+  const total = Object.values(severityCounts).reduce((a, b) => a + b, 0)
+  if (total > 0) {
+    return `⚠️ Found ${total} issue${total === 1 ? '' : 's'} (${severityCounts.medium} medium, ${severityCounts.low} low, ${severityCounts.info} info)`
+  }
+
+  return `✅ No security issues found (scanned ${filesScanned} files in ${(scanDuration / 1000).toFixed(1)}s)`
+}
+
+/**
+ * Format as inline annotation for GitHub check run
+ */
+export function formatAnnotation(finding: Vulnerability): {
+  path: string
+  start_line: number
+  end_line: number
+  annotation_level: 'failure' | 'warning' | 'notice'
+  message: string
+  title: string
+} {
+  const level: 'failure' | 'warning' | 'notice' =
+    finding.severity === 'critical' || finding.severity === 'high' ? 'failure' :
+    finding.severity === 'medium' ? 'warning' : 'notice'
+
+  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}` : ''),
+  }
+}

package/src/formatters/grouping.ts

@@ -0,0 +1,190 @@
+/**
+ * Finding Grouping Logic
+ * Groups and sorts vulnerabilities for workflow-friendly output
+ */
+
+import type { Vulnerability, VulnerabilitySeverity, VulnerabilityCategory } from '../types'
+
+/**
+ * Risk themes for grouping findings
+ */
+export type RiskTheme =
+  | 'secrets'      // Hardcoded secrets, high entropy strings
+  | 'injection'    // SQL, XSS, command injection
+  | 'auth'         // Missing auth, weak auth patterns
+  | 'ai'           // AI-specific vulnerabilities
+  | 'config'       // Insecure configuration
+  | 'data'         // Data exposure, sensitive variables
+  | 'other'        // Uncategorized
+
+/**
+ * Map categories to risk themes
+ */
+export function getRiskTheme(category: VulnerabilityCategory): RiskTheme {
+  switch (category) {
+    case 'hardcoded_secret':
+    case 'high_entropy_string':
+    case 'sensitive_url':
+      return 'secrets'
+
+    case 'sql_injection':
+    case 'xss':
+    case 'command_injection':
+    case 'dangerous_function':
+      return 'injection'
+
+    case 'missing_auth':
+    case 'security_bypass':
+      return 'auth'
+
+    case 'ai_pattern':
+    case 'ai_prompt_injection':
+    case 'ai_unsafe_execution':
+    case 'ai_overpermissive_tool':
+      return 'ai'
+
+    case 'insecure_config':
+    case 'cors_misconfiguration':
+    case 'root_container':
+    case 'dangerous_file':
+    case 'weak_crypto':
+      return 'config'
+
+    case 'data_exposure':
+    case 'sensitive_variable':
+      return 'data'
+
+    default:
+      return 'other'
+  }
+}
+
+/**
+ * Theme display names and icons
+ */
+export const THEME_CONFIG: Record<RiskTheme, { name: string; icon: string; priority: number }> = {
+  secrets: { name: 'Secrets & Credentials', icon: '🔑', priority: 1 },
+  injection: { name: 'Injection Vulnerabilities', icon: '💉', priority: 2 },
+  auth: { name: 'Authentication Issues', icon: '🔒', priority: 3 },
+  ai: { name: 'AI Security', icon: '🤖', priority: 4 },
+  config: { name: 'Configuration Issues', icon: '⚙️', priority: 5 },
+  data: { name: 'Data Exposure', icon: '📊', priority: 6 },
+  other: { name: 'Other Issues', icon: '⚠️', priority: 7 },
+}
+
+/**
+ * Severity sort order (higher = more severe)
+ */
+const SEVERITY_ORDER: Record<VulnerabilitySeverity, number> = {
+  critical: 5,
+  high: 4,
+  medium: 3,
+  low: 2,
+  info: 1,
+}
+
+/**
+ * Grouped findings by risk theme
+ */
+export interface GroupedFindings {
+  theme: RiskTheme
+  themeName: string
+  themeIcon: string
+  findings: Vulnerability[]
+  severityCounts: Record<VulnerabilitySeverity, number>
+}
+
+/**
+ * Group vulnerabilities by risk theme
+ */
+export function groupByTheme(vulnerabilities: Vulnerability[]): GroupedFindings[] {
+  // Group by theme
+  const groups = new Map<RiskTheme, Vulnerability[]>()
+
+  for (const vuln of vulnerabilities) {
+    const theme = getRiskTheme(vuln.category)
+    if (!groups.has(theme)) {
+      groups.set(theme, [])
+    }
+    groups.get(theme)!.push(vuln)
+  }
+
+  // Convert to array and sort
+  const result: GroupedFindings[] = []
+
+  for (const [theme, findings] of groups) {
+    // Sort findings within group: severity desc, then confidence desc
+    findings.sort((a, b) => {
+      const severityDiff = SEVERITY_ORDER[b.severity] - SEVERITY_ORDER[a.severity]
+      if (severityDiff !== 0) return severityDiff
+
+      const confidenceOrder = { high: 3, medium: 2, low: 1 }
+      return confidenceOrder[b.confidence] - confidenceOrder[a.confidence]
+    })
+
+    // Count severities
+    const severityCounts: Record<VulnerabilitySeverity, number> = {
+      critical: 0,
+      high: 0,
+      medium: 0,
+      low: 0,
+      info: 0,
+    }
+    for (const f of findings) {
+      severityCounts[f.severity]++
+    }
+
+    const config = THEME_CONFIG[theme]
+    result.push({
+      theme,
+      themeName: config.name,
+      themeIcon: config.icon,
+      findings,
+      severityCounts,
+    })
+  }
+
+  // Sort groups by theme priority
+  result.sort((a, b) => THEME_CONFIG[a.theme].priority - THEME_CONFIG[b.theme].priority)
+
+  return result
+}
+
+/**
+ * Limit findings per group to avoid overwhelming output
+ */
+export function limitPerGroup(groups: GroupedFindings[], maxPerGroup: number = 10): GroupedFindings[] {
+  return groups.map(group => ({
+    ...group,
+    findings: group.findings.slice(0, maxPerGroup),
+  }))
+}
+
+/**
+ * Get findings sorted by severity across all groups
+ */
+export function sortBySeverity(vulnerabilities: Vulnerability[]): Vulnerability[] {
+  return [...vulnerabilities].sort((a, b) => {
+    const severityDiff = SEVERITY_ORDER[b.severity] - SEVERITY_ORDER[a.severity]
+    if (severityDiff !== 0) return severityDiff
+
+    const confidenceOrder = { high: 3, medium: 2, low: 1 }
+    return confidenceOrder[b.confidence] - confidenceOrder[a.confidence]
+  })
+}
+
+/**
+ * Filter to only blocking issues (critical/high)
+ */
+export function getBlockingIssues(vulnerabilities: Vulnerability[]): Vulnerability[] {
+  return vulnerabilities.filter(v => v.severity === 'critical' || v.severity === 'high')
+}
+
+/**
+ * Filter to actionable issues (medium and above)
+ */
+export function getActionableIssues(vulnerabilities: Vulnerability[]): Vulnerability[] {
+  return vulnerabilities.filter(v =>
+    v.severity === 'critical' || v.severity === 'high' || v.severity === 'medium'
+  )
+}

package/src/formatters/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Output Formatters
+ * Export all formatting utilities for different workflows
+ */
+
+// Grouping utilities
+export {
+  groupByTheme,
+  limitPerGroup,
+  sortBySeverity,
+  getBlockingIssues,
+  getActionableIssues,
+  getRiskTheme,
+  THEME_CONFIG,
+  type RiskTheme,
+  type GroupedFindings,
+} from './grouping'
+
+// GitHub comment formatter
+export {
+  formatGitHubComment,
+  formatShortStatus,
+  formatAnnotation,
+  type GitHubCommentOptions,
+} from './github-comment'
+
+// VS Code diagnostic formatter
+export {
+  formatDiagnostic,
+  formatDiagnosticsByFile,
+  generateCodeAction,
+  formatForProblemsPanel,
+  DiagnosticSeverity,
+  type Diagnostic,
+  type DiagnosticsByFile,
+  type CodeAction,
+  type Position,
+  type Range,
+} from './vscode-diagnostic'
+
+// CLI terminal formatter
+export {
+  formatTerminalOutput,
+  formatSimpleList,
+  formatJSON,
+  formatSARIF,
+} from './cli-terminal'