@oculum/scanner 1.0.12 → 1.0.13

package/src/{types.ts → shared/types.ts}

@@ -54,6 +54,13 @@ export type VulnerabilityCategory =
   | 'ai_unverified_model'           // Model loaded without integrity verification
   | 'ai_unsafe_finetuning'          // Training on unvalidated data
   | 'ai_excessive_agency'           // Unbounded agent autonomy risks
+  // Agent skill file security
+  | 'ai_skill_injection'            // Agent skill file with prompt injection, data exfil, or hidden execution
+  // OWASP Workstream 1: Classic vulnerability detectors
+  | 'missing_security_headers'      // Missing HTTP security headers (CSP, HSTS, etc.)
+  | 'ssrf'                          // Server-Side Request Forgery
+  | 'log_injection'                 // Log injection / log forging
+  | 'xxe'                           // XML External Entity injection
 
 export type ValidationStatus = 'confirmed' | 'downgraded' | 'dismissed' | 'not_validated'
 
@@ -68,7 +75,10 @@ export interface Vulnerability {
   description: string
   suggestedFix?: string
   confidence: 'high' | 'medium' | 'low'
-  layer: 1 | 2 | 3 // Which scan layer detected this
+  /** @deprecated Use `source` instead. Kept for backward compatibility. */
+  layer: 1 | 2 | 3
+  /** Which detector group produced this finding */
+  source?: 'secrets' | 'structural' | 'ai_code' | 'config' | 'validation'
   requiresAIValidation?: boolean // If true, must pass through AI validation before surfacing
 
   // AI validation metadata
@@ -83,6 +93,9 @@ export interface Vulnerability {
   fixSteps?: string[] // Step-by-step fix instructions
   references?: string[] // OWASP/CWE documentation links
   aiEnhanced?: boolean // True if AI provided custom impact/fix beyond registry defaults
+
+  /** Base confidence score (0.0-1.0) set by the detector. Used by scoring stage. */
+  baseConfidence?: number
 }
 
 /**
@@ -258,17 +271,19 @@ export interface ScanResult {
   }
 
   /** Filter audit trail (when includeFilterAudit option is enabled) */
-  filterAuditTrail?: import('./filtering/pipeline').AnnotatedFinding[]
+  filterAuditTrail?: import('../postprocess/filtering/pipeline').AnnotatedFinding[]
 }
 
 export interface ScanProgress {
-  status: 'fetching' | 'scanning_layer1' | 'scanning_layer2' | 'scanning_layer3' | 'complete' | 'failed'
-  currentFile?: string
+  status: 'fetching' | 'layer1' | 'layer2' | 'layer3' | 'validating' | 'complete' | 'failed'
+  message: string
   filesProcessed: number
   totalFiles: number
   vulnerabilitiesFound: number
 }
 
+export type ProgressCallback = (progress: ScanProgress) => void
+
 // Pattern definitions for Layer 1
 export interface SecretPattern {
   name: string
@@ -377,7 +392,7 @@ export interface MiddlewareAuthContextSummary {
   /** Whether auth middleware was detected */
   hasAuthMiddleware: boolean
   /** The type of auth detected */
-  authType: 'clerk' | 'nextauth' | 'auth0' | 'custom' | 'unknown' | null
+  authType: 'clerk' | 'nextauth' | 'auth0' | 'supabase' | 'custom' | 'unknown' | null
   /** Protected path patterns */
   protectedPaths: string[]
   /** Public/excluded path patterns */
@@ -432,6 +447,7 @@ export const SCANNABLE_EXTENSIONS = [
   '.py', '.rb', '.php', '.go', '.java', '.cs',
   '.env', '.yaml', '.yml', '.json', '.toml',
   '.dockerfile', '.sh', '.bash',
+  '.md',  // Agent skill files (SKILL.md, copilot-instructions.md, etc.)
 ]
 
 // Files to always scan regardless of extension
@@ -447,6 +463,7 @@ export const SPECIAL_FILES = [
   'requirements.txt',
   'Gemfile',
   'go.mod',
+  '.cursorrules',
 ]
 
 // Max file size to scan (50KB as per PRD)

package/src/tiers.ts

@@ -11,7 +11,7 @@
  * - Avoids "accidental promotion" of an experimental heuristic to production output
  */
 
-import type { VulnerabilityCategory } from './types'
+import type { VulnerabilityCategory } from './shared/types'
 
 /**
  * Detector tiers control visibility and trust level:
@@ -117,6 +117,11 @@ export type Layer2DetectorName =
   | 'ai_mcp_security'          // ai-mcp-security.ts - MCP tool security
   // AI Detection Roadmap Phase 2
   | 'model_supply_chain'       // model-supply-chain.ts - Model loading/finetuning risks
+  // OWASP Workstream 1
+  | 'security_headers'         // security-headers.ts - Missing HTTP security headers
+  | 'ssrf_detection'           // ssrf-detection.ts - Server-Side Request Forgery
+  | 'log_injection'            // log-injection.ts - Log injection / forging
+  | 'xxe_detection'            // xxe-detection.ts - XML External Entity injection
 
 /**
  * Layer 2 tier assignments
@@ -168,6 +173,12 @@ export const LAYER2_DETECTOR_TIERS: Record<Layer2DetectorName, DetectorTier> = {
   ai_mcp_security: 'core',           // Tier A - MCP tool security is critical for AI agents
   // AI Detection Roadmap Phase 2
   model_supply_chain: 'core',        // Tier A - Model supply chain risks are critical (RCE)
+
+  // OWASP Workstream 1
+  security_headers: 'ai_assisted',    // Tier B - Context-dependent (CDN/proxy may add headers)
+  ssrf_detection: 'core',             // Tier A - SSRF is high-impact with clear signals
+  log_injection: 'ai_assisted',       // Tier B - Context-dependent (structured logging may be fine)
+  xxe_detection: 'core',              // Tier A - XXE is high-impact with clear signals
 }
 
 /**
@@ -240,6 +251,12 @@ export const LAYER2_CATEGORY_TO_DETECTOR: Partial<Record<VulnerabilityCategory,
   ai_unverified_model: 'model_supply_chain',
   ai_unsafe_finetuning: 'model_supply_chain',
   ai_excessive_agency: 'ai_agent_tools',  // Extended in ai-agent-tools.ts
+
+  // OWASP Workstream 1 categories
+  missing_security_headers: 'security_headers',
+  ssrf: 'ssrf_detection',
+  log_injection: 'log_injection',
+  xxe: 'xxe_detection',
 }
 
 // ============================================================================

package/src/validate/__tests__/context-extractor.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Tests for the context extractor utility.
+ *
+ * Verifies:
+ * - Small files get full content
+ * - Large files get scoped content with omission markers
+ * - Adjacent findings merge ranges
+ * - High coverage falls back to full file
+ * - Edge cases (line 1, last line, empty)
+ * - mergeRanges helper
+ */
+
+import { extractRelevantContext, mergeRanges } from '../utils/context-extractor'
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function generateFile(lineCount: number): string {
+  return Array.from({ length: lineCount }, (_, i) => `line ${i + 1} content`).join('\n')
+}
+
+// ============================================================================
+// mergeRanges
+// ============================================================================
+
+describe('mergeRanges', () => {
+  test('empty input returns empty', () => {
+    expect(mergeRanges([])).toEqual([])
+  })
+
+  test('single range returns unchanged', () => {
+    expect(mergeRanges([{ start: 5, end: 10 }])).toEqual([{ start: 5, end: 10 }])
+  })
+
+  test('overlapping ranges merge', () => {
+    const result = mergeRanges([
+      { start: 1, end: 10 },
+      { start: 5, end: 15 },
+    ])
+    expect(result).toEqual([{ start: 1, end: 15 }])
+  })
+
+  test('adjacent ranges merge', () => {
+    const result = mergeRanges([
+      { start: 1, end: 10 },
+      { start: 11, end: 20 },
+    ])
+    expect(result).toEqual([{ start: 1, end: 20 }])
+  })
+
+  test('disjoint ranges remain separate', () => {
+    const result = mergeRanges([
+      { start: 1, end: 10 },
+      { start: 20, end: 30 },
+    ])
+    expect(result).toEqual([
+      { start: 1, end: 10 },
+      { start: 20, end: 30 },
+    ])
+  })
+
+  test('unsorted input gets sorted and merged', () => {
+    const result = mergeRanges([
+      { start: 20, end: 30 },
+      { start: 1, end: 10 },
+      { start: 5, end: 25 },
+    ])
+    expect(result).toEqual([{ start: 1, end: 30 }])
+  })
+
+  test('multiple separate ranges', () => {
+    const result = mergeRanges([
+      { start: 1, end: 5 },
+      { start: 10, end: 15 },
+      { start: 20, end: 25 },
+    ])
+    expect(result).toEqual([
+      { start: 1, end: 5 },
+      { start: 10, end: 15 },
+      { start: 20, end: 25 },
+    ])
+  })
+})
+
+// ============================================================================
+// extractRelevantContext
+// ============================================================================
+
+describe('extractRelevantContext', () => {
+  test('small file (50 lines) returns full content', () => {
+    const content = generateFile(50)
+    const result = extractRelevantContext(content, [25])
+    expect(result.isFullFile).toBe(true)
+    expect(result.linesSent).toBe(50)
+    expect(result.totalLines).toBe(50)
+    expect(result.content).toContain('line 1 content')
+    expect(result.content).toContain('line 50 content')
+    expect(result.content).not.toContain('lines omitted')
+  })
+
+  test('large file with single finding returns scoped content', () => {
+    const content = generateFile(300)
+    const result = extractRelevantContext(content, [150])
+    expect(result.isFullFile).toBe(false)
+    expect(result.totalLines).toBe(300)
+    expect(result.linesSent).toBeLessThan(300)
+    // Should contain the finding line
+    expect(result.content).toContain('line 150 content')
+    // Should contain imports (first 15 lines)
+    expect(result.content).toContain('line 1 content')
+    expect(result.content).toContain('line 15 content')
+    // Should have omission markers
+    expect(result.content).toContain('lines omitted')
+  })
+
+  test('adjacent findings merge ranges (no omission between them)', () => {
+    const content = generateFile(300)
+    const result = extractRelevantContext(content, [100, 110])
+    // Lines 100 and 110 are within padding distance, so should merge
+    expect(result.content).toContain('line 100 content')
+    expect(result.content).toContain('line 110 content')
+    // The region between 100 and 110 should NOT have omission
+    const lines = result.content.split('\n')
+    const between = lines.filter(l =>
+      l.includes('lines omitted') &&
+      l.includes('100') &&
+      l.includes('110')
+    )
+    expect(between).toHaveLength(0)
+  })
+
+  test('high coverage falls back to full file', () => {
+    const content = generateFile(200)
+    // 3 findings spread across the file covering >60%
+    const result = extractRelevantContext(content, [30, 100, 170])
+    expect(result.isFullFile).toBe(true)
+    expect(result.linesSent).toBe(200)
+  })
+
+  test('finding at line 1', () => {
+    const content = generateFile(300)
+    const result = extractRelevantContext(content, [1])
+    expect(result.content).toContain('line 1 content')
+    // Should not have negative line references
+    expect(result.content).not.toContain('line 0')
+    expect(result.content).not.toContain('line -')
+  })
+
+  test('finding at last line', () => {
+    const content = generateFile(300)
+    const result = extractRelevantContext(content, [300])
+    expect(result.content).toContain('line 300 content')
+  })
+
+  test('empty file returns full content', () => {
+    const result = extractRelevantContext('', [1])
+    expect(result.isFullFile).toBe(true)
+    expect(result.totalLines).toBe(1) // empty string splits to ['']
+  })
+
+  test('empty findings returns full content', () => {
+    const content = generateFile(300)
+    const result = extractRelevantContext(content, [])
+    expect(result.isFullFile).toBe(true)
+  })
+
+  test('custom config: smaller padding', () => {
+    const content = generateFile(300)
+    const result = extractRelevantContext(content, [150], { padding: 5 })
+    expect(result.isFullFile).toBe(false)
+    // Should have much fewer lines with small padding
+    expect(result.linesSent).toBeLessThan(50)
+    expect(result.content).toContain('line 150 content')
+  })
+
+  test('content includes line numbers in correct format', () => {
+    const content = generateFile(300)
+    const result = extractRelevantContext(content, [150])
+    // Should have "   1 | line 1 content" format
+    expect(result.content).toMatch(/^\s+1 \| line 1 content/m)
+    expect(result.content).toMatch(/\s+150 \| line 150 content/m)
+  })
+
+  test('omission markers show correct line ranges', () => {
+    const content = generateFile(300)
+    const result = extractRelevantContext(content, [150], { padding: 10, importLines: 5 })
+    // Should have omission markers with line ranges
+    expect(result.content).toMatch(/\[\.\.\..*lines omitted.*\]/)
+  })
+})

package/src/validate/__tests__/prompt-assembly.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Tests for the modular prompt assembly system.
+ *
+ * Verifies:
+ * - Category-to-module mapping correctness
+ * - Prompt assembly includes only relevant modules
+ * - Deterministic ordering for cache hits
+ * - Legacy compatibility
+ * - Category completeness (no unmapped categories slip through)
+ */
+
+import type { VulnerabilityCategory } from '../../shared/types'
+import {
+  assembleValidationPrompt,
+  getFullValidationPrompt,
+  CATEGORY_TO_MODULE,
+  INTENTIONALLY_UNMAPPED,
+  COMMON_PROMPT,
+  AUTH_ACCESS_MODULE,
+  XSS_PROMPT_MODULE,
+  SECRETS_CRYPTO_MODULE,
+  AI_PATTERNS_MODULE,
+  OWASP_CLASSIC_MODULE,
+} from '../prompts/modules'
+import { HIGH_CONTEXT_VALIDATION_PROMPT } from '../prompts/validation'
+
+// ============================================================================
+// Key phrases for each module (used to verify inclusion/exclusion)
+// ============================================================================
+
+const COMMON_KEY_PHRASE = 'Validate security findings'
+const COMMON_RESPONSE_FORMAT = 'Response Format'
+const AUTH_KEY_PHRASE = 'CRITICAL CONTRADICTION HANDLING'
+const XSS_KEY_PHRASE = 'XSS vs Prompt Injection'
+const SECRETS_KEY_PHRASE = 'Math.random() for Security'
+const AI_KEY_PHRASE = 'RAG Data Exfiltration'
+const OWASP_KEY_PHRASE = 'Server-Side Request Forgery'
+
+describe('assembleValidationPrompt', () => {
+  test('empty categories returns COMMON only', () => {
+    const result = assembleValidationPrompt([])
+    expect(result).toContain(COMMON_KEY_PHRASE)
+    expect(result).toContain(COMMON_RESPONSE_FORMAT)
+    // Should NOT contain module-specific content
+    expect(result).not.toContain(AUTH_KEY_PHRASE)
+    expect(result).not.toContain(XSS_KEY_PHRASE)
+    expect(result).not.toContain(SECRETS_KEY_PHRASE)
+    expect(result).not.toContain(AI_KEY_PHRASE)
+    expect(result).not.toContain(OWASP_KEY_PHRASE)
+  })
+
+  test('single module: missing_auth includes auth_access only', () => {
+    const result = assembleValidationPrompt(['missing_auth'])
+    expect(result).toContain(COMMON_KEY_PHRASE)
+    expect(result).toContain(AUTH_KEY_PHRASE)
+    // Should NOT contain other modules
+    expect(result).not.toContain(SECRETS_KEY_PHRASE)
+    expect(result).not.toContain(AI_KEY_PHRASE)
+    expect(result).not.toContain(OWASP_KEY_PHRASE)
+  })
+
+  test('multiple modules: auth + secrets + owasp', () => {
+    const result = assembleValidationPrompt([
+      'missing_auth',
+      'hardcoded_secret',
+      'ssrf',
+    ])
+    expect(result).toContain(COMMON_KEY_PHRASE)
+    expect(result).toContain(AUTH_KEY_PHRASE)
+    expect(result).toContain(SECRETS_KEY_PHRASE)
+    expect(result).toContain(OWASP_KEY_PHRASE)
+    // Should NOT contain unrelated modules
+    expect(result).not.toContain(AI_KEY_PHRASE)
+  })
+
+  test('unknown/unmapped categories get COMMON only, no crash', () => {
+    const result = assembleValidationPrompt(['dangerous_function'])
+    expect(result).toContain(COMMON_KEY_PHRASE)
+    expect(result).toContain(COMMON_RESPONSE_FORMAT)
+    // No module-specific content
+    expect(result).not.toContain(AUTH_KEY_PHRASE)
+    expect(result).not.toContain(XSS_KEY_PHRASE)
+    expect(result).not.toContain(SECRETS_KEY_PHRASE)
+    expect(result).not.toContain(AI_KEY_PHRASE)
+    expect(result).not.toContain(OWASP_KEY_PHRASE)
+  })
+
+  test('deterministic ordering: different input order produces same output', () => {
+    const result1 = assembleValidationPrompt(['ssrf', 'missing_auth', 'hardcoded_secret'])
+    const result2 = assembleValidationPrompt(['missing_auth', 'hardcoded_secret', 'ssrf'])
+    const result3 = assembleValidationPrompt(['hardcoded_secret', 'ssrf', 'missing_auth'])
+    expect(result1).toBe(result2)
+    expect(result2).toBe(result3)
+  })
+
+  test('ai_prompt_injection triggers both xss_prompt AND ai_patterns modules', () => {
+    const result = assembleValidationPrompt(['ai_prompt_injection'])
+    expect(result).toContain(XSS_KEY_PHRASE)
+    expect(result).toContain(AI_KEY_PHRASE)
+  })
+
+  test('duplicate categories do not cause duplicate modules', () => {
+    const result1 = assembleValidationPrompt(['missing_auth'])
+    const result2 = assembleValidationPrompt(['missing_auth', 'missing_auth', 'missing_auth'])
+    expect(result1).toBe(result2)
+  })
+})
+
+describe('getFullValidationPrompt', () => {
+  test('contains key phrases from EVERY module', () => {
+    const full = getFullValidationPrompt()
+    expect(full).toContain(COMMON_KEY_PHRASE)
+    expect(full).toContain(COMMON_RESPONSE_FORMAT)
+    expect(full).toContain(AUTH_KEY_PHRASE)
+    expect(full).toContain(XSS_KEY_PHRASE)
+    expect(full).toContain(SECRETS_KEY_PHRASE)
+    expect(full).toContain(AI_KEY_PHRASE)
+    expect(full).toContain(OWASP_KEY_PHRASE)
+  })
+})
+
+describe('legacy compatibility', () => {
+  test('HIGH_CONTEXT_VALIDATION_PROMPT equals getFullValidationPrompt()', () => {
+    expect(HIGH_CONTEXT_VALIDATION_PROMPT).toBe(getFullValidationPrompt())
+  })
+})
+
+describe('category completeness guard', () => {
+  /**
+   * Every VulnerabilityCategory must be either:
+   * 1. Mapped to a module in CATEGORY_TO_MODULE, or
+   * 2. Listed in INTENTIONALLY_UNMAPPED
+   *
+   * If a new category is added to types.ts without updating the mapping,
+   * this test will fail.
+   */
+  test('every VulnerabilityCategory is accounted for', () => {
+    // Get all categories from the type system at runtime
+    // We can't enumerate a TS union at runtime, so we maintain this list manually.
+    // This list MUST match the VulnerabilityCategory union in types.ts exactly.
+    const ALL_CATEGORIES: 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',
+      'ai_prompt_injection',
+      'ai_unsafe_execution',
+      'ai_overpermissive_tool',
+      'ai_rag_exfiltration',
+      'ai_endpoint_unprotected',
+      'ai_schema_mismatch',
+      'ai_package_hallucination',
+      'ai_rag_corpus_poisoning',
+      'ai_rag_pii_leakage',
+      'ai_mcp_tool_poisoning',
+      'ai_mcp_credential_issue',
+      'ai_mcp_confused_deputy',
+      'ai_mcp_description_injection',
+      'ai_mcp_server_shadowing',
+      'ai_mcp_config_secrets',
+      'ai_mcp_config_permissions',
+      'ai_rag_query_injection',
+      'ai_rag_embedding_poisoning',
+      'ai_rag_chunk_injection',
+      'ai_package_typosquat',
+      'ai_package_malicious',
+      'ai_unsafe_model_load',
+      'ai_unverified_model',
+      'ai_unsafe_finetuning',
+      'ai_excessive_agency',
+      'ai_skill_injection',
+      'missing_security_headers',
+      'ssrf',
+      'log_injection',
+      'xxe',
+    ]
+
+    for (const cat of ALL_CATEGORIES) {
+      const isMapped = CATEGORY_TO_MODULE.has(cat)
+      const isUnmapped = INTENTIONALLY_UNMAPPED.has(cat)
+      expect({
+        category: cat,
+        mapped: isMapped,
+        intentionallyUnmapped: isUnmapped,
+        accountedFor: isMapped || isUnmapped,
+      }).toEqual(expect.objectContaining({ accountedFor: true }))
+    }
+  })
+
+  test('no category is both mapped AND intentionally unmapped', () => {
+    for (const cat of INTENTIONALLY_UNMAPPED) {
+      expect(CATEGORY_TO_MODULE.has(cat)).toBe(false)
+    }
+  })
+})
+
+describe('module content integrity', () => {
+  test('COMMON_PROMPT contains taint analysis guidance', () => {
+    expect(COMMON_PROMPT).toContain('Taint Analysis Context')
+    expect(COMMON_PROMPT).toContain('User input reaches this sink')
+    expect(COMMON_PROMPT).toContain('No user-input data flow reaches this line')
+    expect(COMMON_PROMPT).toContain('Sanitised: Yes')
+    expect(COMMON_PROMPT).toContain('Confidence levels')
+  })
+
+  test('COMMON_PROMPT contains condensed heuristic reminders', () => {
+    expect(COMMON_PROMPT).toContain('JSON.parse')
+    expect(COMMON_PROMPT).toContain('error.message')
+    expect(COMMON_PROMPT).toContain('innerHTML')
+  })
+
+  test('each module is non-empty', () => {
+    expect(AUTH_ACCESS_MODULE.length).toBeGreaterThan(50)
+    expect(XSS_PROMPT_MODULE.length).toBeGreaterThan(50)
+    expect(SECRETS_CRYPTO_MODULE.length).toBeGreaterThan(50)
+    expect(AI_PATTERNS_MODULE.length).toBeGreaterThan(50)
+    expect(OWASP_CLASSIC_MODULE.length).toBeGreaterThan(50)
+  })
+})