@oculum/scanner 1.0.11 → 1.0.13

package/src/shared/schema-semantics.ts

@@ -0,0 +1,233 @@
+/**
+ * Schema Semantics Utility
+ * Understands validation schema logic, particularly Zod/Yup/Joi patterns
+ *
+ * This addresses false positives where OR validation (either A or B required)
+ * is flagged as "bypass" when individual fields are marked optional.
+ *
+ * Key insight: `.optional()` + `.refine()` = OR validation, not bypass
+ */
+
+export interface SchemaAnalysis {
+  /** Whether the schema has cross-field refinement/validation */
+  hasRefinement: boolean
+  /** Type of refinement detected */
+  refinementType?: 'or_logic' | 'super_refine' | 'custom_validation' | 'none'
+  /** Number of optional fields in the schema */
+  optionalFieldCount: number
+  /** Whether this looks like legitimate OR validation */
+  isOrValidation: boolean
+}
+
+/**
+ * Patterns that indicate cross-field validation refinements
+ */
+const REFINEMENT_PATTERNS = [
+  // Zod .refine() with OR logic
+  /\.refine\s*\(\s*\([^)]*\)\s*=>\s*[^,]*\|\|/,
+  /\.refine\s*\(\s*\(\s*\{\s*\w+\s*,/,  // Destructured refine
+  /\.refine\s*\(\s*\(?data\)?\s*=>/,    // data => refine
+
+  // Zod .superRefine()
+  /\.superRefine\s*\(/,
+
+  // Yup .test() with cross-field validation
+  /\.test\s*\(\s*['"][^'"]+['"]\s*,\s*['"][^'"]+['"]\s*,\s*function/,
+  /\.test\s*\(\s*['"][^'"]+['"]\s*,\s*['"][^'"]+['"]\s*,\s*\([^)]*\)\s*=>/,
+
+  // Joi custom validation
+  /\.custom\s*\(/,
+  /Joi\.alternatives\s*\(\)/,
+  /\.xor\s*\(/,
+  /\.or\s*\(/,
+]
+
+/**
+ * Patterns indicating OR logic in refinement callbacks
+ */
+const OR_LOGIC_PATTERNS = [
+  // Direct OR in refine: (data) => data.a || data.b
+  /=>\s*[^,;]*\|\|/,
+  // Negated AND: !(a && b)
+  /=>\s*!\s*\([^)]*&&/,
+  // Ternary with OR
+  /\?\s*[^:]*\|\|/,
+]
+
+/**
+ * Find the start of a schema definition containing a given line
+ */
+function findSchemaStart(lines: string[], lineNumber: number): number {
+  // Look backwards for schema definition patterns
+  const schemaStartPatterns = [
+    /(?:const|let|var)\s+\w+\s*=\s*z\.object\s*\(/,
+    /(?:const|let|var)\s+\w+\s*=\s*Yup\.object\s*\(/,
+    /(?:const|let|var)\s+\w+\s*=\s*Joi\.object\s*\(/,
+    /export\s+(?:const|let|var)\s+\w+\s*=\s*z\.object\s*\(/,
+    /z\.object\s*\(\s*\{/,
+    /Yup\.object\s*\(\s*\{/,
+    /Joi\.object\s*\(\s*\{/,
+  ]
+
+  for (let i = lineNumber; i >= 0; i--) {
+    if (schemaStartPatterns.some(pattern => pattern.test(lines[i]))) {
+      return i
+    }
+    // Don't look back more than 50 lines
+    if (lineNumber - i > 50) break
+  }
+
+  return Math.max(0, lineNumber - 10)
+}
+
+/**
+ * Find the end of a schema definition containing a given line
+ */
+function findSchemaEnd(lines: string[], schemaStart: number): number {
+  let braceCount = 0
+  let inSchema = false
+
+  for (let i = schemaStart; i < lines.length; i++) {
+    const line = lines[i]
+
+    // Count braces/parens
+    for (const char of line) {
+      if (char === '(' || char === '{') {
+        braceCount++
+        inSchema = true
+      } else if (char === ')' || char === '}') {
+        braceCount--
+      }
+    }
+
+    // Schema ends when we return to zero brace count after entering
+    if (inSchema && braceCount === 0) {
+      return i + 1
+    }
+
+    // Don't look forward more than 100 lines
+    if (i - schemaStart > 100) break
+  }
+
+  return Math.min(lines.length, schemaStart + 50)
+}
+
+/**
+ * Count .optional() calls in content
+ */
+function countOptionalFields(content: string): number {
+  const matches = content.match(/\.optional\s*\(\s*\)/g)
+  return matches ? matches.length : 0
+}
+
+/**
+ * Analyze a validation schema for OR-logic refinement patterns
+ *
+ * @param content - The full file content
+ * @param lineNumber - The 0-indexed line number where the pattern was found
+ * @returns SchemaAnalysis with refinement information
+ */
+export function analyzeSchemaSemantics(
+  content: string,
+  lineNumber: number
+): SchemaAnalysis {
+  const lines = content.split('\n')
+
+  // Find the schema boundaries
+  const schemaStart = findSchemaStart(lines, lineNumber)
+  const schemaEnd = findSchemaEnd(lines, schemaStart)
+
+  // Extract schema content
+  const schemaLines = lines.slice(schemaStart, schemaEnd)
+  const schemaContent = schemaLines.join('\n')
+
+  // Check for refinement patterns
+  const hasRefine = REFINEMENT_PATTERNS.some(pattern => pattern.test(schemaContent))
+  const hasSuperRefine = /\.superRefine\s*\(/.test(schemaContent)
+  const hasOrLogic = OR_LOGIC_PATTERNS.some(pattern => pattern.test(schemaContent))
+
+  // Count optional fields
+  const optionalCount = countOptionalFields(schemaContent)
+
+  // Determine if this is OR validation
+  // OR validation pattern: multiple optional fields + refine with || logic
+  const isOrValidation = optionalCount >= 2 && hasRefine && hasOrLogic
+
+  // Determine refinement type
+  let refinementType: SchemaAnalysis['refinementType'] = 'none'
+  if (hasSuperRefine) {
+    refinementType = 'super_refine'
+  } else if (hasOrLogic && hasRefine) {
+    refinementType = 'or_logic'
+  } else if (hasRefine) {
+    refinementType = 'custom_validation'
+  }
+
+  return {
+    hasRefinement: hasRefine || hasSuperRefine,
+    refinementType,
+    optionalFieldCount: optionalCount,
+    isOrValidation,
+  }
+}
+
+/**
+ * Check if a line with .optional() is part of legitimate OR validation
+ *
+ * @param content - The full file content
+ * @param lineNumber - The 0-indexed line number where .optional() was found
+ * @returns true if this is part of OR validation (not a bypass)
+ */
+export function isLegitimateOrValidation(
+  content: string,
+  lineNumber: number
+): boolean {
+  const analysis = analyzeSchemaSemantics(content, lineNumber)
+  return analysis.isOrValidation || analysis.refinementType === 'super_refine'
+}
+
+/**
+ * Check if a 2FA-related field with .optional() has proper OR validation
+ * Specifically for 2FA patterns where either totpCode OR backupCode is required
+ *
+ * @param content - The full file content
+ * @param lineNumber - The 0-indexed line number
+ * @returns true if this is legitimate 2FA OR validation
+ */
+export function is2FAOrValidation(
+  content: string,
+  lineNumber: number
+): boolean {
+  const lines = content.split('\n')
+  const line = lines[lineNumber] || ''
+
+  // Check if this line is about 2FA fields
+  const is2FAField = /\b(totp|otp|backupCode|recoveryCode|twoFactor|2fa|mfa)\b/i.test(line)
+  if (!is2FAField) {
+    return false
+  }
+
+  // Check for OR validation in the schema
+  const analysis = analyzeSchemaSemantics(content, lineNumber)
+
+  // If there's refinement with OR logic, this is legitimate
+  if (analysis.isOrValidation) {
+    return true
+  }
+
+  // Check for specific 2FA OR patterns in nearby content
+  const schemaStart = findSchemaStart(lines, lineNumber)
+  const schemaEnd = findSchemaEnd(lines, schemaStart)
+  const schemaContent = lines.slice(schemaStart, schemaEnd).join('\n')
+
+  // Patterns like: "Either TOTP or backup code required"
+  const twoFAOrPatterns = [
+    /either.*or.*required/i,
+    /totp.*\|\|.*backup/i,
+    /backup.*\|\|.*totp/i,
+    /code.*\|\|.*code/i,
+    /one\s+of.*required/i,
+  ]
+
+  return twoFAOrPatterns.some(pattern => pattern.test(schemaContent))
+}

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
 }
 
 /**
@@ -256,16 +269,21 @@ export interface ScanResult {
       title: string
     }>
   }
+
+  /** Filter audit trail (when includeFilterAudit option is enabled) */
+  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
@@ -312,12 +330,124 @@ export interface AIFinding {
   suggestedFix: string
 }
 
+// ============================================================================
+// Detector Context (for Layer 2 context-aware detection)
+// ============================================================================
+
+/**
+ * DetectorContext provides rich context information to Layer 2 detectors
+ * This allows detectors to make smarter decisions based on:
+ * - Project-level auth configuration
+ * - Framework detection
+ * - Per-file context (server vs client, test vs production)
+ */
+export interface DetectorContext {
+  // Auth context (project-wide)
+  auth: {
+    /** Middleware configuration (if detected) */
+    middleware: MiddlewareAuthContextSummary | null
+    /** Auth helpers detected in the project */
+    authHelpers: AuthHelperContextSummary
+    /** Public endpoint patterns (health, webhook, etc.) */
+    publicEndpoints: string[]
+  }
+
+  // Framework context (project-wide)
+  framework: {
+    /** Primary backend framework detected */
+    primary: 'nextjs' | 'express' | 'fastify' | 'koa' | 'hono' | 'nestjs' | 'django' | 'flask' | 'rails' | 'unknown' | null
+    /** Frontend framework detected */
+    frontend: 'react' | 'vue' | 'svelte' | 'angular' | 'unknown' | null
+    /** Whether the project uses TypeScript */
+    hasTypeScript: boolean
+  }
+
+  // Data access context (project-wide)
+  dataAccess: {
+    /** ORM/query builder detected */
+    orm: 'prisma' | 'drizzle' | 'typeorm' | 'sequelize' | 'knex' | null
+    /** Whether RLS (Row-Level Security) is detected */
+    hasRLS: boolean
+    /** Validation library detected */
+    validationLib: 'zod' | 'yup' | 'joi' | 'valibot' | null
+  }
+
+  // Per-file context (computed for each file)
+  file: {
+    /** Whether this file is server-only (not bundled to client) */
+    isServerOnly: boolean
+    /** Whether this file is client-bundled (exposed to browser) */
+    isClientBundled: boolean
+    /** Whether this file is a test/mock/fixture file */
+    isTestFile: boolean
+    /** Whether this file is a config file */
+    isConfigFile: boolean
+    /** Whether this file is in a tooling directory */
+    isToolingDir: boolean
+  }
+}
+
+/** Simplified middleware auth config for DetectorContext */
+export interface MiddlewareAuthContextSummary {
+  /** Whether auth middleware was detected */
+  hasAuthMiddleware: boolean
+  /** The type of auth detected */
+  authType: 'clerk' | 'nextauth' | 'auth0' | 'supabase' | 'custom' | 'unknown' | null
+  /** Protected path patterns */
+  protectedPaths: string[]
+  /** Public/excluded path patterns */
+  publicPaths: string[]
+}
+
+/** Simplified auth helper context for DetectorContext */
+export interface AuthHelperContextSummary {
+  /** Whether the project has throwing auth helpers */
+  hasThrowingHelpers: boolean
+  /** Names of throwing auth helpers */
+  throwingHelperNames: string[]
+}
+
+/**
+ * Create an empty/default DetectorContext
+ * Useful for tests or when context isn't available
+ */
+export function createEmptyDetectorContext(): DetectorContext {
+  return {
+    auth: {
+      middleware: null,
+      authHelpers: {
+        hasThrowingHelpers: false,
+        throwingHelperNames: [],
+      },
+      publicEndpoints: [],
+    },
+    framework: {
+      primary: null,
+      frontend: null,
+      hasTypeScript: false,
+    },
+    dataAccess: {
+      orm: null,
+      hasRLS: false,
+      validationLib: null,
+    },
+    file: {
+      isServerOnly: false,
+      isClientBundled: false,
+      isTestFile: false,
+      isConfigFile: false,
+      isToolingDir: false,
+    },
+  }
+}
+
 // 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',
+  '.md',  // Agent skill files (SKILL.md, copilot-instructions.md, etc.)
 ]
 
 // Files to always scan regardless of extension
@@ -333,6 +463,7 @@ export const SPECIAL_FILES = [
   'requirements.txt',
   'Gemfile',
   'go.mod',
+  '.cursorrules',
 ]
 
 // Max file size to scan (50KB as per PRD)
@@ -353,13 +484,13 @@ 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.
+ * - local: 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.
+ * - verified: 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.
@@ -369,13 +500,13 @@ export type ScanMode = 'full' | 'incremental'
  *
  * | 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                     |
+ * | GitHub PR      | local         | Fast feedback, high-signal findings  |
+ * | VS Code        | verified      | Interactive, balance depth + speed   |
+ * | CLI (default)  | local         | Fast local scans                     |
  * | CLI --deep     | deep          | Thorough analysis when requested     |
  * | Onboarding     | deep          | Full picture on first scan           |
  */
-export type ScanDepth = 'cheap' | 'validated' | 'deep'
+export type ScanDepth = 'local' | 'verified' | 'deep'
 
 export interface ScanModeConfig {
   /** The scan mode */

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',
 }
 
 // ============================================================================
@@ -293,17 +310,17 @@ export function getLayer2DetectorTier(detector: Layer2DetectorName): DetectorTie
  */
 export function isTierVisibleAtDepth(
   tier: DetectorTier,
-  depth: 'cheap' | 'validated' | 'deep'
+  depth: 'local' | 'verified' | 'deep'
 ): boolean {
   switch (depth) {
-    case 'cheap':
-      // Only Tier A (core) findings are visible in cheap scans
+    case 'local':
+      // Only Tier A (core) findings are visible in local scans
       return tier === 'core'
-    case 'validated':
+    case 'verified':
       // Tier A always visible, Tier B visible after AI validation
       return tier === 'core' || tier === 'ai_assisted'
     case 'deep':
-      // Same as validated for visibility (deep adds Layer 3, not more tiers)
+      // Same as verified for visibility (deep adds Layer 3, not more tiers)
       return tier === 'core' || tier === 'ai_assisted'
   }
 }
@@ -313,14 +330,14 @@ export function isTierVisibleAtDepth(
  */
 export function shouldValidateWithAI(
   tier: DetectorTier,
-  depth: 'cheap' | 'validated' | 'deep'
+  depth: 'local' | 'verified' | 'deep'
 ): boolean {
-  // Cheap scans skip AI validation entirely
-  if (depth === 'cheap') {
+  // Local scans skip AI validation entirely
+  if (depth === 'local') {
     return false
   }
 
-  // In validated/deep, Tier B findings should go through AI validation
+  // In verified/deep, Tier B findings should go through AI validation
   // Tier A is high-precision and doesn't need AI validation
   // Tier C is hidden anyway
   return tier === 'ai_assisted'