@oculum/scanner 1.0.11 → 1.0.13

package/src/report/formatters/ide/index.ts

@@ -0,0 +1,216 @@
+/**
+ * IDE Integration Module
+ * Exports formatters and utilities for IDE-specific config files
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs'
+import { join, dirname } from 'path'
+
+// Export formatters
+export { formatCursorRules } from './cursor'
+export { formatWindsurfRules } from './windsurf'
+export { formatClaudeCodeSection, OCULUM_SECTION_START, OCULUM_SECTION_END } from './claude-code'
+
+/** Supported IDE types */
+export type IDEType = 'cursor' | 'windsurf' | 'claude-code'
+
+/** Default file paths for each IDE */
+export const IDE_FILE_PATHS: Record<IDEType, string> = {
+  cursor: '.cursor/rules/security.mdc',
+  windsurf: '.windsurfrules',
+  'claude-code': 'CLAUDE.md',
+}
+
+/** Result of a file write operation */
+export interface WriteIDEFileResult {
+  success: boolean
+  path: string
+  error?: string
+}
+
+/** Result of a file clear operation */
+export interface ClearIDEFilesResult {
+  success: boolean
+  clearedFiles: string[]
+  errors: string[]
+}
+
+/**
+ * Detect which IDE configurations exist in the project
+ *
+ * @param projectPath - Path to the project root
+ * @returns Array of detected IDE types
+ */
+export function detectIDEConfigs(projectPath: string): IDEType[] {
+  const detected: IDEType[] = []
+
+  // Check for Cursor
+  if (existsSync(join(projectPath, '.cursor'))) {
+    detected.push('cursor')
+  }
+
+  // Check for Windsurf rules
+  if (existsSync(join(projectPath, '.windsurfrules'))) {
+    detected.push('windsurf')
+  }
+
+  // Check for Claude Code
+  if (existsSync(join(projectPath, 'CLAUDE.md'))) {
+    detected.push('claude-code')
+  }
+
+  return detected
+}
+
+/**
+ * Write an IDE-specific file
+ *
+ * @param projectPath - Path to the project root
+ * @param relativePath - Relative path for the file
+ * @param content - Content to write
+ * @returns Result object
+ */
+export function writeIDEFile(
+  projectPath: string,
+  relativePath: string,
+  content: string
+): WriteIDEFileResult {
+  const fullPath = join(projectPath, relativePath)
+
+  try {
+    // Ensure directory exists
+    const dir = dirname(fullPath)
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true })
+    }
+
+    // Write file
+    writeFileSync(fullPath, content)
+
+    return { success: true, path: fullPath }
+  } catch (err) {
+    return {
+      success: false,
+      path: fullPath,
+      error: `Failed to write ${relativePath}: ${err instanceof Error ? err.message : 'Unknown error'}`,
+    }
+  }
+}
+
+/**
+ * Update the Oculum section in CLAUDE.md
+ * Replaces content between OCULUM_SECURITY_START and OCULUM_SECURITY_END markers
+ * If markers don't exist, appends the section at the end
+ *
+ * @param projectPath - Path to the project root
+ * @param section - The section content (including markers)
+ * @returns Result object
+ */
+export function updateClaudeMdSection(
+  projectPath: string,
+  section: string
+): WriteIDEFileResult {
+  const filePath = join(projectPath, 'CLAUDE.md')
+
+  try {
+    let content: string
+
+    if (existsSync(filePath)) {
+      content = readFileSync(filePath, 'utf-8')
+
+      // Check if markers exist
+      const startMarker = '<!-- OCULUM_SECURITY_START -->'
+      const endMarker = '<!-- OCULUM_SECURITY_END -->'
+      const startIndex = content.indexOf(startMarker)
+      const endIndex = content.indexOf(endMarker)
+
+      if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+        // Replace existing section
+        content =
+          content.substring(0, startIndex) +
+          section +
+          content.substring(endIndex + endMarker.length)
+      } else {
+        // Append section at end
+        content = content.trimEnd() + '\n\n' + section
+      }
+    } else {
+      // Create new file with section
+      content = `# CLAUDE.md\n\n${section}`
+    }
+
+    writeFileSync(filePath, content)
+
+    return { success: true, path: filePath }
+  } catch (err) {
+    return {
+      success: false,
+      path: filePath,
+      error: `Failed to update CLAUDE.md: ${err instanceof Error ? err.message : 'Unknown error'}`,
+    }
+  }
+}
+
+/**
+ * Clear IDE rule files
+ *
+ * @param projectPath - Path to the project root
+ * @param types - Optional array of IDE types to clear. If not provided, clears all.
+ * @returns Result object with list of cleared files
+ */
+export function clearIDEFiles(
+  projectPath: string,
+  types?: IDEType[]
+): ClearIDEFilesResult {
+  const toCheck = types || (['cursor', 'windsurf', 'claude-code'] as IDEType[])
+  const clearedFiles: string[] = []
+  const errors: string[] = []
+
+  for (const ide of toCheck) {
+    const relativePath = IDE_FILE_PATHS[ide]
+    const fullPath = join(projectPath, relativePath)
+
+    try {
+      if (ide === 'claude-code') {
+        // For CLAUDE.md, remove only the Oculum section, not the whole file
+        if (existsSync(fullPath)) {
+          const content = readFileSync(fullPath, 'utf-8')
+          const startMarker = '<!-- OCULUM_SECURITY_START -->'
+          const endMarker = '<!-- OCULUM_SECURITY_END -->'
+          const startIndex = content.indexOf(startMarker)
+          const endIndex = content.indexOf(endMarker)
+
+          if (startIndex !== -1 && endIndex !== -1) {
+            // Remove section (including potential surrounding newlines)
+            let newContent = content.substring(0, startIndex) + content.substring(endIndex + endMarker.length)
+            // Clean up extra newlines
+            newContent = newContent.replace(/\n{3,}/g, '\n\n').trimEnd() + '\n'
+            writeFileSync(fullPath, newContent)
+            clearedFiles.push(relativePath)
+          }
+        }
+      } else {
+        // For other IDEs, delete the file
+        if (existsSync(fullPath)) {
+          unlinkSync(fullPath)
+          clearedFiles.push(relativePath)
+        }
+      }
+    } catch (err) {
+      errors.push(`Failed to clear ${relativePath}: ${err instanceof Error ? err.message : 'Unknown error'}`)
+    }
+  }
+
+  return {
+    success: errors.length === 0,
+    clearedFiles,
+    errors,
+  }
+}
+
+/**
+ * Get the default file path for an IDE type
+ */
+export function getIDEFilePath(ide: IDEType): string {
+  return IDE_FILE_PATHS[ide]
+}

package/src/report/formatters/ide/windsurf.ts

@@ -0,0 +1,135 @@
+/**
+ * Windsurf IDE Integration
+ * Generates .windsurfrules format
+ */
+
+import type { ScanResult, Vulnerability, VulnerabilityCategory } from '../../../shared/types'
+import { sortBySeverity } from '../grouping'
+
+/**
+ * Get security pattern rule for a category
+ */
+function getPatternRule(category: VulnerabilityCategory): string | null {
+  const rules: Partial<Record<VulnerabilityCategory, string>> = {
+    sql_injection: 'ALWAYS use parameterized queries for database operations.',
+    xss: 'ALWAYS escape user input before inserting into HTML.',
+    hardcoded_secret: 'NEVER hardcode secrets, API keys, or credentials in source code.',
+    high_entropy_string: 'NEVER commit high-entropy strings that could be secrets.',
+    missing_auth: 'ALWAYS add authentication middleware to API endpoints.',
+    dangerous_function: 'NEVER use eval(), exec(), or similar functions with user input.',
+    command_injection: 'ALWAYS sanitize input before passing to shell commands.',
+    sensitive_url: 'NEVER hardcode localhost or internal URLs in production code.',
+    insecure_config: 'ALWAYS review configuration files for security issues.',
+    data_exposure: 'NEVER log or expose sensitive data in error messages.',
+    weak_crypto: 'ALWAYS use strong cryptographic algorithms (avoid MD5, SHA1).',
+    ai_prompt_injection: 'ALWAYS sanitize user input before including in AI prompts.',
+    ai_unsafe_execution: 'NEVER execute code generated by AI without validation.',
+  }
+
+  return rules[category] || null
+}
+
+/**
+ * Format scan result as Windsurf rules
+ *
+ * @param result - The scan result to format
+ * @returns Markdown string for .windsurfrules
+ */
+export function formatWindsurfRules(result: ScanResult): string {
+  const { vulnerabilities, timestamp } = result
+
+  // Sort by severity
+  const sorted = sortBySeverity(vulnerabilities)
+
+  let md = ''
+
+  // Header
+  md += `# Oculum Security Rules\n\n`
+  md += `> Generated: ${timestamp}\n\n`
+
+  // No findings case
+  if (vulnerabilities.length === 0) {
+    md += `## Status\n\n`
+    md += `No security issues found.\n\n`
+    md += `*Run \`oculum scan --windsurf --clear\` to remove this file.*\n`
+    return md
+  }
+
+  // Security Issues Section
+  md += `## Security Issues\n\n`
+  md += `The following security issues were detected and need attention:\n\n`
+
+  // Group by file
+  const byFile = new Map<string, Vulnerability[]>()
+  for (const vuln of sorted) {
+    const group = byFile.get(vuln.filePath) || []
+    group.push(vuln)
+    byFile.set(vuln.filePath, group)
+  }
+
+  // List by file
+  for (const [filePath, vulns] of byFile) {
+    md += `### ${filePath}\n\n`
+
+    for (const vuln of vulns) {
+      const severityEmoji =
+        vuln.severity === 'critical' ? '!!' :
+        vuln.severity === 'high' ? '!' :
+        vuln.severity === 'medium' ? '*' : '-'
+
+      md += `- ${severityEmoji} **Line ${vuln.lineNumber}:** ${vuln.title}`
+      if (vuln.suggestedFix) {
+        md += ` - ${vuln.suggestedFix}`
+      }
+      md += '\n'
+    }
+    md += '\n'
+  }
+
+  // Code Patterns Section
+  md += `## Code Patterns\n\n`
+  md += `Follow these security patterns when writing code:\n\n`
+
+  // Collect unique pattern rules
+  const patternRules = new Set<string>()
+  for (const vuln of vulnerabilities) {
+    const rule = getPatternRule(vuln.category)
+    if (rule) {
+      patternRules.add(rule)
+    }
+  }
+
+  for (const rule of patternRules) {
+    md += `- ${rule}\n`
+  }
+  md += '\n'
+
+  // Quick Reference
+  md += `## Quick Reference\n\n`
+  md += `| Severity | Count | Action |\n`
+  md += `|----------|-------|--------|\n`
+
+  const { severityCounts } = result
+  if (severityCounts.critical > 0) {
+    md += `| Critical | ${severityCounts.critical} | Fix immediately |\n`
+  }
+  if (severityCounts.high > 0) {
+    md += `| High | ${severityCounts.high} | Fix before commit |\n`
+  }
+  if (severityCounts.medium > 0) {
+    md += `| Medium | ${severityCounts.medium} | Review and fix |\n`
+  }
+  if (severityCounts.low > 0) {
+    md += `| Low | ${severityCounts.low} | Consider fixing |\n`
+  }
+  if (severityCounts.info > 0) {
+    md += `| Info | ${severityCounts.info} | For awareness |\n`
+  }
+  md += '\n'
+
+  // Footer
+  md += `---\n\n`
+  md += `*Run \`oculum scan\` to verify fixes. Run \`oculum scan --windsurf --clear\` to remove this file.*\n`
+
+  return md
+}

package/src/{formatters → report/formatters}/index.ts

@@ -16,6 +16,30 @@ export {
   type GroupedFindings,
 } from './grouping'
 
+// AI Context formatter
+export {
+  formatAIContext,
+  type AIContextOptions,
+} from './ai-context'
+
+// IDE integrations
+export {
+  formatCursorRules,
+  formatWindsurfRules,
+  formatClaudeCodeSection,
+  detectIDEConfigs,
+  writeIDEFile,
+  updateClaudeMdSection,
+  clearIDEFiles,
+  getIDEFilePath,
+  OCULUM_SECTION_START,
+  OCULUM_SECTION_END,
+  IDE_FILE_PATHS,
+  type IDEType,
+  type WriteIDEFileResult,
+  type ClearIDEFilesResult,
+} from './ide'
+
 // GitHub comment formatter
 export {
   formatGitHubComment,

package/src/{formatters → report/formatters}/vscode-diagnostic.ts

@@ -3,7 +3,7 @@
  * Formats scan results as LSP diagnostic format for VS Code integration
  */
 
-import type { Vulnerability, VulnerabilitySeverity } from '../types'
+import type { Vulnerability, VulnerabilitySeverity } from '../../shared/types'
 
 /**
  * LSP Diagnostic Severity

package/src/report/summary.ts

@@ -0,0 +1,70 @@
+/**
+ * Report Summary — Sorting and counting utilities for scan results.
+ *
+ * Pure functions extracted from the orchestrator. No cross-stage dependencies.
+ */
+
+import type {
+  Vulnerability,
+  SeverityCounts,
+  CategoryCounts,
+  VulnerabilityCategory,
+} from '../shared/types'
+import { severityRank, confidenceRank } from '../shared/parsed-file'
+
+/**
+ * Sort vulnerabilities by severity (critical first)
+ */
+export function sortBySeverity(vulnerabilities: Vulnerability[]): Vulnerability[] {
+  return [...vulnerabilities].sort((a, b) => {
+    const severityDiff = severityRank(b.severity) - severityRank(a.severity)
+    if (severityDiff !== 0) return severityDiff
+
+    // Secondary sort by confidence
+    return confidenceRank(b.confidence) - confidenceRank(a.confidence)
+  })
+}
+
+/**
+ * Compute severity counts from vulnerabilities
+ */
+export function computeSeverityCounts(vulnerabilities: Vulnerability[]): SeverityCounts {
+  const counts: SeverityCounts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 }
+
+  for (const vuln of vulnerabilities) {
+    if (vuln.severity in counts) {
+      counts[vuln.severity]++
+    }
+  }
+
+  return counts
+}
+
+/**
+ * Compute category counts from vulnerabilities
+ */
+export function computeCategoryCounts(vulnerabilities: Vulnerability[]): CategoryCounts {
+  const counts: CategoryCounts = {}
+
+  for (const vuln of vulnerabilities) {
+    const category = vuln.category as VulnerabilityCategory
+    counts[category] = (counts[category] || 0) + 1
+  }
+
+  return counts
+}
+
+/**
+ * Helper to compute counts from vulnerabilities (for backfilling legacy scans)
+ */
+export function computeIssueMixFromVulnerabilities(vulnerabilities: Vulnerability[]): {
+  severityCounts: SeverityCounts
+  categoryCounts: CategoryCounts
+  hasBlockingIssues: boolean
+} {
+  const severityCounts = computeSeverityCounts(vulnerabilities)
+  const categoryCounts = computeCategoryCounts(vulnerabilities)
+  const hasBlockingIssues = severityCounts.critical > 0 || severityCounts.high > 0
+
+  return { severityCounts, categoryCounts, hasBlockingIssues }
+}