@oculum/scanner 1.0.0

package/src/types.ts

@@ -0,0 +1,284 @@
+/**
+ * Scanner Types and Interfaces
+ * Defines the core data structures for the security scanning engine
+ */
+
+export type VulnerabilitySeverity = 'critical' | 'high' | 'medium' | 'low' | 'info'
+
+export type VulnerabilityCategory =
+  | 'hardcoded_secret'
+  | 'high_entropy_string'
+  | 'sensitive_variable'
+  | 'security_bypass'
+  | 'dangerous_function'
+  | 'sql_injection'
+  | 'xss'
+  | 'command_injection'
+  | 'insecure_config'
+  | 'missing_auth'
+  | 'suspicious_package'
+  | 'cors_misconfiguration'
+  | 'root_container'
+  | 'dangerous_file'
+  | 'ai_pattern'
+  | 'sensitive_url'
+  | 'weak_crypto'
+  | 'data_exposure'  // Logging/exposing sensitive data
+  // AI-specific categories (Story B)
+  | 'ai_prompt_injection'     // B1: Prompt hygiene issues - user input in system prompts
+  | 'ai_unsafe_execution'     // B2: LLM output fed to dangerous sinks (eval, exec, SQL)
+  | 'ai_overpermissive_tool'  // B4: Agent tools with excessive permissions
+  // AI-era vulnerability categories (M5)
+  | 'ai_rag_exfiltration'     // M5: RAG data leakage - cross-tenant retrieval, raw context exposure
+  | 'ai_endpoint_unprotected' // M5: AI endpoints without auth/rate limiting
+  | 'ai_schema_mismatch'      // M5: Missing schema validation on AI-generated outputs
+
+export type ValidationStatus = 'confirmed' | 'downgraded' | 'dismissed' | 'not_validated'
+
+export interface Vulnerability {
+  id: string
+  filePath: string
+  lineNumber: number
+  lineContent: string
+  severity: VulnerabilitySeverity
+  category: VulnerabilityCategory
+  title: string
+  description: string
+  suggestedFix?: string
+  confidence: 'high' | 'medium' | 'low'
+  layer: 1 | 2 | 3 // Which scan layer detected this
+  requiresAIValidation?: boolean // If true, must pass through AI validation before surfacing
+
+  // AI validation metadata
+  validatedByAI?: boolean // true if this finding was processed by AI validation
+  validationStatus?: ValidationStatus // outcome of AI validation
+  validationNotes?: string // e.g., "Route protected by Clerk middleware"
+  originalSeverity?: VulnerabilitySeverity // For downgraded findings, the original severity
+}
+
+export interface ScanFile {
+  path: string
+  content: string
+  language: string
+  size: number
+}
+
+// Severity counts for issue-mix display
+export interface SeverityCounts {
+  critical: number
+  high: number
+  medium: number
+  low: number
+  info: number
+}
+
+// Category counts keyed by VulnerabilityCategory
+export type CategoryCounts = Partial<Record<VulnerabilityCategory, number>>
+
+export interface ScanResult {
+  repoName: string
+  repoUrl: string
+  branch: string
+  filesScanned: number
+  filesSkipped: number
+  vulnerabilities: Vulnerability[]
+
+  // Issue-mix fields - use these for displaying security posture
+  severityCounts: SeverityCounts
+  categoryCounts: CategoryCounts
+  hasBlockingIssues: boolean // true if any critical or high severity issues
+
+  scanDuration: number // milliseconds
+  timestamp: string
+
+  // AI Validation stats (Phase 1 optimization metrics)
+  validationStats?: {
+    totalFindings: number
+    validatedFindings: number
+    confirmedFindings: number
+    dismissedFindings: number
+    downgradedFindings: number
+    autoDismissedFindings: number
+    estimatedInputTokens: number
+    estimatedOutputTokens: number
+    estimatedCost: number
+    apiCalls: number
+    cacheCreationTokens: number
+    cacheReadTokens: number
+    cacheHitRate: number
+  }
+}
+
+export interface ScanProgress {
+  status: 'fetching' | 'scanning_layer1' | 'scanning_layer2' | 'scanning_layer3' | 'complete' | 'failed'
+  currentFile?: string
+  filesProcessed: number
+  totalFiles: number
+  vulnerabilitiesFound: number
+}
+
+// Pattern definitions for Layer 1
+export interface SecretPattern {
+  name: string
+  pattern: RegExp
+  severity: VulnerabilitySeverity
+  description: string
+}
+
+// Config audit rules for Layer 1
+export interface ConfigRule {
+  name: string
+  filePatterns: string[]
+  check: (content: string, filePath: string) => ConfigViolation[]
+}
+
+export interface ConfigViolation {
+  line: number
+  lineContent: string
+  message: string
+  severity: VulnerabilitySeverity
+}
+
+// Layer 2 heuristics
+export interface SensitiveVariablePattern {
+  pattern: RegExp
+  severity: VulnerabilitySeverity
+  description: string
+}
+
+// Layer 3 AI analysis
+export interface AIAnalysisRequest {
+  filePath: string
+  content: string
+  context: string
+}
+
+export interface AIFinding {
+  lineNumber: number
+  lineContent: string
+  severity: VulnerabilitySeverity
+  category: VulnerabilityCategory
+  title: string
+  description: string
+  suggestedFix: string
+}
+
+// Supported file extensions for scanning
+export const SCANNABLE_EXTENSIONS = [
+  '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
+  '.py', '.rb', '.php', '.go', '.java', '.cs',
+  '.env', '.yaml', '.yml', '.json', '.toml',
+  '.dockerfile', '.sh', '.bash',
+]
+
+// Files to always scan regardless of extension
+export const SPECIAL_FILES = [
+  'Dockerfile',
+  'docker-compose.yml',
+  'docker-compose.yaml',
+  '.env',
+  '.env.local',
+  '.env.production',
+  '.env.development',
+  'package.json',
+  'requirements.txt',
+  'Gemfile',
+  'go.mod',
+]
+
+// Max file size to scan (50KB as per PRD)
+export const MAX_FILE_SIZE = 50 * 1024
+
+// ============================================================================
+// Scan Mode Configuration
+// ============================================================================
+
+/**
+ * Scan mode determines the depth and cost of the scan
+ * 
+ * - full: Complete scan with AI validation on all files (initial onboarding, deep audits)
+ * - incremental: Focused scan on changed files only (CI/CD, fast feedback)
+ */
+export type ScanMode = 'full' | 'incremental'
+
+/**
+ * Scan depth controls AI usage independent of full vs incremental mode
+ *
+ * - cheap: Layer 1 + Layer 2 only. No AI validation, no Layer 3.
+ *          Only Tier A (core) findings are surfaced.
+ *          Target: <5s for typical PR scans.
+ *
+ * - validated: Layer 1 + Layer 2 + AI validation on selected findings. No Layer 3.
+ *              Tier A is surfaced directly, Tier B goes through AI validation.
+ *              Target: <15s with <10 AI calls.
+ *
+ * - deep: Layer 1 + Layer 2 + AI validation + Layer 3 semantic analysis.
+ *         Full analysis for initial onboarding or deep security audits.
+ *         Target: Complete thoroughness, cost secondary.
+ *
+ * ## Workflow Profile Recommendations:
+ *
+ * | Workflow       | Default Depth | Rationale                            |
+ * |----------------|---------------|--------------------------------------|
+ * | GitHub PR      | cheap         | Fast feedback, high-signal findings  |
+ * | VS Code        | validated     | Interactive, balance depth + speed   |
+ * | CLI (default)  | cheap         | Fast local scans                     |
+ * | CLI --deep     | deep          | Thorough analysis when requested     |
+ * | Onboarding     | deep          | Full picture on first scan           |
+ */
+export type ScanDepth = 'cheap' | 'validated' | 'deep'
+
+export interface ScanModeConfig {
+  /** The scan mode */
+  mode: ScanMode
+  
+  /** For incremental scans: paths of changed files */
+  changedFiles?: string[]
+  
+  /** For incremental scans: base commit/branch to diff against */
+  baseBranch?: string
+  
+  /** Whether to skip AI validation entirely (for very fast scans) */
+  skipAIValidation?: boolean
+  
+  /** Whether to skip Layer 3 deep analysis (reduces cost) */
+  skipLayer3?: boolean
+  
+  /** Maximum files to send to AI validation (cost control) */
+  maxAIValidationFiles?: number
+  
+  /** Maximum files for Layer 3 analysis (cost control) */
+  maxLayer3Files?: number
+
+  /** Scan depth mode (cheap/validated/deep) - controls AI usage */
+  scanDepth?: ScanDepth
+
+  /** Whether to exclude test files from scanning (default: true) */
+  excludeTestFiles?: boolean
+
+  /** Whether to exclude seed files from scanning (default: true) */
+  excludeSeedFiles?: boolean
+
+  /** Custom file path patterns to exclude (glob format) */
+  customExclusions?: string[]
+}
+
+/**
+ * Default configurations for each scan mode
+ */
+export const SCAN_MODE_DEFAULTS: Record<ScanMode, Partial<ScanModeConfig>> = {
+  full: {
+    mode: 'full',
+    skipAIValidation: false,
+    skipLayer3: false,
+    maxAIValidationFiles: 50,
+    maxLayer3Files: 15,
+  },
+  incremental: {
+    mode: 'incremental',
+    skipAIValidation: false,
+    skipLayer3: true, // Skip expensive Layer 3 for incremental
+    maxAIValidationFiles: 20,
+    maxLayer3Files: 5,
+  },
+}