@oculum/scanner 1.0.1 → 1.0.3

package/src/layer2/dangerous-functions.ts

@@ -8,6 +8,8 @@ import {
   isComment,
   isTestOrMockFile,
   isScannerOrFixtureFile,
+  isSeedOrDataGenFile,
+  isEducationalVulnerabilityFile,
 } from '../utils/context-helpers'
 
 /**
@@ -807,12 +809,9 @@ function isCosmeticMathRandom(lineContent: string, content: string, lineNumber:
     /Math\.random.*\*\s*\d+\s*\+\s*\d+.*\bpx\b/i,        // Math.random() * 100 + 50 + 'px'
     /Math\.random.*\*\s*\d+\s*\+\s*\d+.*\bms\b/i,        // Math.random() * 1000 + 500 + 'ms'
     /Math\.random.*\*\s*\d+\s*\+\s*\d+.*\bs\b/i,         // Math.random() * 5 + 2 + 's'
-    // UI identifier generation (short strings for element IDs, keys, etc.)
-    /Math\.random\(\)\.toString\(36\)\.substring\(/,     // .toString(36).substring(2, 9) - short UI IDs
-    /Math\.random\(\)\.toString\(36\)\.substr\(/,        // .substr() variant
-    /Math\.random\(\)\.toString\(36\)\.slice\(/,         // .slice() variant
-    /Math\.random\(\)\.toString\(16\)\.substring\(/,     // .toString(16).substring() - hex UI IDs
-    /Math\.random\(\)\.toString\(16\)\.slice\(/,         // hex slice variant
+    // NOTE: toString patterns removed - now handled by analyzeToStringPattern()
+    // which provides more granular severity classification (info/low/medium/high)
+    // based on truncation length and context
   ]
   
   if (cosmeticLinePatterns.some(p => p.test(lineContent))) {
@@ -879,6 +878,269 @@ function isCosmeticMathRandom(lineContent: string, content: string, lineNumber:
   return false  // Default to flagging if unclear
 }
 
+/**
+ * Extract function context where Math.random() is being called
+ * Looks backwards from the current line to find enclosing function name
+ * Returns lowercase function name or null if not found
+ */
+function extractFunctionContext(content: string, lineNumber: number): string | null {
+  const lines = content.split('\n')
+  const start = Math.max(0, lineNumber - 10)
+
+  // Look backwards for function declaration
+  for (let i = lineNumber; i >= start; i--) {
+    const line = lines[i]
+
+    // Match various function declaration patterns
+    // 1. function functionName
+    // 2. export function functionName
+    // 3. const/let functionName = function
+    // 4. const/let functionName = (arrow function)
+    // 5. export const functionName =
+
+    // Traditional function declaration
+    const funcDeclMatch = line.match(/(?:export\s+)?function\s+(\w+)/i)
+    if (funcDeclMatch) {
+      return funcDeclMatch[1].toLowerCase()
+    }
+
+    // Arrow function or function expression assignment
+    // Only match if there's an equals sign and function-like syntax
+    const arrowFuncMatch = line.match(/(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:function|\(|async)/i)
+    if (arrowFuncMatch) {
+      return arrowFuncMatch[1].toLowerCase()
+    }
+  }
+  return null
+}
+
+/**
+ * Classify function intent based on function name
+ * Used to determine if Math.random() usage is legitimate
+ */
+function classifyFunctionIntent(functionName: string | null): 'uuid' | 'captcha' | 'demo' | 'security' | 'unknown' {
+  if (!functionName) return 'unknown'
+
+  const lower = functionName.toLowerCase()
+
+  // UUID/ID generation (UI correlation, not security)
+  // Check for specific UUID patterns and generic ID generation functions
+  const uuidPatterns = ['uuid', 'guid', 'uniqueid', 'correlationid']
+  const idGenerationPatterns = /^(generate|create|make|build)(id|identifier)$/i
+  if (uuidPatterns.some(p => lower.includes(p)) || idGenerationPatterns.test(lower)) {
+    return 'uuid'
+  }
+
+  // CAPTCHA/puzzle generation (legitimate non-security)
+  const captchaPatterns = ['captcha', 'puzzle', 'mathproblem']
+  // Also check for 'challenge' but only if not in security context
+  if (captchaPatterns.some(p => lower.includes(p))) return 'captcha'
+  if (lower.includes('challenge') && !lower.includes('auth')) return 'captcha'
+
+  // Demo/seed/fixture data
+  const demoPatterns = ['seed', 'fixture', 'demo', 'mock', 'fake']
+  if (demoPatterns.some(p => lower.includes(p))) return 'demo'
+
+  // Security-sensitive (check this after id generation to avoid false positives)
+  const securityPatterns = ['token', 'secret', 'key', 'password', 'credential', 'signature']
+  // Also match generate/create + security term combinations
+  const securityFunctionPattern = /^(generate|create|make)(token|secret|key|session|password|credential)/i
+  if (securityPatterns.some(p => lower.includes(p)) || securityFunctionPattern.test(lower)) {
+    return 'security'
+  }
+
+  return 'unknown'
+}
+
+/**
+ * Analyze toString() pattern in Math.random() usage
+ * Determines intent based on base and truncation length
+ */
+function analyzeToStringPattern(lineContent: string): {
+  hasToString: boolean
+  base: number | null
+  isTruncated: boolean
+  truncationLength: number | null
+  intent: 'short-ui-id' | 'business-id' | 'full-token' | 'unknown'
+} {
+  const toString36Match = lineContent.match(/Math\.random\(\)\.toString\(36\)/)
+  const toString16Match = lineContent.match(/Math\.random\(\)\.toString\(16\)/)
+
+  if (!toString36Match && !toString16Match) {
+    return { hasToString: false, base: null, isTruncated: false, truncationLength: null, intent: 'unknown' }
+  }
+
+  const base = toString36Match ? 36 : 16
+
+  // Check for truncation methods
+  const substringMatch = lineContent.match(/\.substring\((\d+)(?:,\s*(\d+))?\)/)
+  const sliceMatch = lineContent.match(/\.slice\((\d+)(?:,\s*(\d+))?\)/)
+  const substrMatch = lineContent.match(/\.substr\((\d+)(?:,\s*(\d+))?\)/)
+
+  const truncMatch = substringMatch || sliceMatch || substrMatch
+
+  if (!truncMatch) {
+    return { hasToString: true, base, isTruncated: false, truncationLength: null, intent: 'full-token' }
+  }
+
+  // Calculate truncation length
+  const start = parseInt(truncMatch[1])
+  const end = truncMatch[2] ? parseInt(truncMatch[2]) : null
+  const length = end ? (end - start) : null
+
+  // Classify intent by length
+  // Short (2-9 chars): UI correlation IDs, React keys
+  // Medium (10-15 chars): Business IDs, order numbers
+  if (length && length <= 9) {
+    return { hasToString: true, base, isTruncated: true, truncationLength: length, intent: 'short-ui-id' }
+  } else if (length && length <= 15) {
+    return { hasToString: true, base, isTruncated: true, truncationLength: length, intent: 'business-id' }
+  } else {
+    return { hasToString: true, base, isTruncated: true, truncationLength: length, intent: 'business-id' }
+  }
+}
+
+/**
+ * Extract variable name from Math.random() assignment
+ * Examples:
+ *   const token = Math.random() -> "token"
+ *   const businessId = Math.random().toString(36) -> "businessId"
+ *   return Math.random() -> null (no variable)
+ */
+function extractMathRandomVariableName(lineContent: string): string | null {
+  // const/let/var variableName = Math.random...
+  const assignmentMatch = lineContent.match(/(?:const|let|var)\s+(\w+)\s*=.*Math\.random/)
+  if (assignmentMatch) return assignmentMatch[1]
+
+  // object.property = Math.random...
+  const propertyMatch = lineContent.match(/(\w+)\s*[:=]\s*Math\.random/)
+  if (propertyMatch) return propertyMatch[1]
+
+  // function parameter default: functionName(param = Math.random())
+  const paramMatch = lineContent.match(/(\w+)\s*=\s*Math\.random/)
+  if (paramMatch) return paramMatch[1]
+
+  return null // No variable name found
+}
+
+/**
+ * Classify variable name security risk based on naming patterns
+ *
+ * High risk: Security-sensitive names (token, secret, key, etc.)
+ * Medium risk: Unclear context
+ * Low risk: Non-security names (id, businessId, orderId, etc.)
+ */
+function classifyVariableNameRisk(varName: string | null): 'high' | 'medium' | 'low' {
+  if (!varName) return 'medium' // Unknown usage, moderate risk
+
+  const lower = varName.toLowerCase()
+
+  // High risk: security-sensitive variable names
+  const highRiskPatterns = [
+    'token', 'secret', 'key', 'password', 'credential',
+    'signature', 'salt', 'nonce', 'session', 'csrf',
+    'auth', 'apikey', 'accesstoken', 'refreshtoken',
+    'jwt', 'bearer', 'oauth', 'sessionid'
+  ]
+  if (highRiskPatterns.some(p => lower.includes(p))) {
+    return 'high'
+  }
+
+  // Low risk: clearly non-security contexts
+  const lowRiskPatterns = [
+    // Business identifiers
+    'id', 'uid', 'guid', 'business', 'order', 'invoice',
+    'customer', 'user', 'product', 'item', 'transaction',
+    'request', 'reference', 'tracking', 'confirmation',
+    // Test/demo data
+    'test', 'mock', 'demo', 'sample', 'example', 'fixture',
+    'random', 'temp', 'temporary', 'generated', 'dummy',
+    // UI identifiers
+    'toast', 'notification', 'element', 'component', 'widget',
+    'modal', 'dialog', 'popup', 'unique', 'react'
+  ]
+  if (lowRiskPatterns.some(p => lower.includes(p))) {
+    return 'low'
+  }
+
+  return 'medium' // Unclear context, moderate risk
+}
+
+/**
+ * Analyze surrounding code context for security signals
+ * Returns context type and description for severity classification
+ */
+function analyzeMathRandomContext(
+  content: string,
+  filePath: string,
+  lineNumber: number
+): {
+  inSecurityContext: boolean
+  inTestContext: boolean
+  inUIContext: boolean
+  inBusinessLogicContext: boolean
+  contextDescription: string
+} {
+  const lines = content.split('\n')
+  const start = Math.max(0, lineNumber - 10)
+  const end = Math.min(lines.length, lineNumber + 5)
+  const context = lines.slice(start, end).join('\n')
+
+  // Security context indicators (functions, imports, comments)
+  const securityPatterns = [
+    /\b(generate|create)(Token|Secret|Key|Password|Nonce|Salt|Session|Signature)/i,
+    /\b(auth|crypto|encrypt|decrypt|hash|sign)\b/i,
+    /function\s+.*(?:token|secret|key|auth|crypto)/i,
+    /\bimport.*(?:crypto|jsonwebtoken|bcrypt|argon2|jose)/i,
+    /\/\*.*(?:security|authentication|cryptograph|authorization)/i,
+    /\/\/.*(?:security|auth|crypto|token|secret)/i,
+  ]
+  const inSecurityContext = securityPatterns.some(p => p.test(context))
+
+  // Test context
+  const testFilePatterns = /\.(test|spec)\.(ts|tsx|js|jsx)$/i
+  const testContextPatterns = [
+    /\b(describe|it|test|expect|mock|jest|vitest|mocha|chai)\b/i,
+    /\b(beforeEach|afterEach|beforeAll|afterAll)\b/i,
+    /\b(fixture|stub|spy)\b/i,
+  ]
+  const inTestContext = testFilePatterns.test(filePath) ||
+    testContextPatterns.some(p => p.test(context))
+
+  // UI/cosmetic context (reuse existing logic)
+  const lineContent = lines[lineNumber]
+  const inUIContext = isCosmeticMathRandom(lineContent, content, lineNumber)
+
+  // Business logic context (non-security ID generation)
+  // Note: UUID/CAPTCHA patterns excluded - handled by functionIntent classification
+  const businessLogicPatterns = [
+    /\b(business|order|invoice|customer|product|transaction)Id\b/i,
+    /\b(reference|tracking|confirmation)Number\b/i,
+  ]
+  const inBusinessLogicContext = businessLogicPatterns.some(p => p.test(context)) &&
+    !inSecurityContext
+
+  // Determine context description
+  let contextDescription = 'unknown context'
+  if (inSecurityContext) {
+    contextDescription = 'security-sensitive function'
+  } else if (inTestContext) {
+    contextDescription = 'test/mock data generation'
+  } else if (inUIContext) {
+    contextDescription = 'UI/cosmetic usage'
+  } else if (inBusinessLogicContext) {
+    contextDescription = 'business identifier generation'
+  }
+
+  return {
+    inSecurityContext,
+    inTestContext,
+    inUIContext,
+    inBusinessLogicContext,
+    contextDescription,
+  }
+}
+
 export function detectDangerousFunctions(
   content: string,
   filePath: string
@@ -1171,13 +1433,108 @@ export function detectDangerousFunctions(
           }
         }
 
-        // Special handling for Math.random() - skip cosmetic/UI uses
+        // Special handling for Math.random() - enhanced context-aware severity classification
         if (funcPattern.name === 'Math.random for security') {
-          // Check if this is cosmetic use (CSS, animations, UI variations)
-          if (isCosmeticMathRandom(line, content, index)) {
-            // Skip entirely - this is not a security concern
-            break
+          // Phase 1: File-level exclusions (skip entirely)
+          if (isSeedOrDataGenFile(filePath)) {
+            break  // Skip seed/data generation files entirely
+          }
+
+          if (isEducationalVulnerabilityFile(filePath)) {
+            break  // Skip intentional vulnerability examples
+          }
+
+          // Phase 2: Context analysis
+          const varName = extractMathRandomVariableName(line)
+          const nameRisk = classifyVariableNameRisk(varName)
+          const context = analyzeMathRandomContext(content, filePath, index)
+          const functionName = extractFunctionContext(content, index)
+          const functionIntent = classifyFunctionIntent(functionName)
+          const toStringPattern = analyzeToStringPattern(line)
+
+          // Phase 3: Skip cosmetic/UI uses
+          if (context.inUIContext) {
+            break  // Already working
+          }
+
+          // Phase 4: Skip UUID/CAPTCHA generation functions
+          if (functionIntent === 'uuid' || functionIntent === 'captcha') {
+            break  // Legitimate non-security uses
+          }
+
+          // Phase 5: Determine severity
+          let severity: VulnerabilitySeverity = 'medium'
+          let confidence: 'high' | 'medium' | 'low' = 'medium'
+          let explanation = ''
+          let description = funcPattern.description
+          let suggestedFix = funcPattern.suggestedFix
+
+          // Test context - INFO
+          if (context.inTestContext) {
+            severity = 'info'
+            confidence = 'low'
+            explanation = ' (test data generation)'
+            description = 'Math.random() used in test context for generating mock data. Not security-critical, but consider crypto.randomUUID() for better uniqueness in tests.'
+            suggestedFix = 'Consider crypto.randomUUID() for test data uniqueness, though Math.random() is acceptable in tests'
+          }
+          // Seed/demo function context - INFO
+          else if (functionIntent === 'demo') {
+            severity = 'info'
+            confidence = 'low'
+            explanation = ' (seed/demo data generation)'
+            description = 'Math.random() used for generating fixture/seed data. Not security-critical in development contexts.'
+            suggestedFix = 'Acceptable for seed data. Use crypto.randomUUID() if uniqueness guarantees needed.'
+          }
+          // Security context - HIGH
+          else if (nameRisk === 'high' || context.inSecurityContext || functionIntent === 'security') {
+            severity = 'high'
+            confidence = 'high'
+            explanation = ' (security-sensitive context)'
+            description = 'Math.random() is NOT cryptographically secure and MUST NOT be used for tokens, keys, passwords, or session IDs. This can lead to predictable values that attackers can exploit.'
+            suggestedFix = 'Replace with crypto.randomBytes() or crypto.randomUUID() for security-sensitive operations'
+          }
+          // Short UI ID pattern - INFO
+          else if (toStringPattern.intent === 'short-ui-id') {
+            severity = 'info'
+            confidence = 'low'
+            explanation = ' (UI correlation ID)'
+            description = 'Math.random() used for short UI correlation IDs. Not security-critical, but collisions possible in high-volume scenarios.'
+            suggestedFix = 'For UI correlation, crypto.randomUUID() provides better uniqueness guarantees'
+          }
+          // Business ID pattern - LOW
+          else if (nameRisk === 'low' || context.inBusinessLogicContext || toStringPattern.intent === 'business-id') {
+            severity = 'low'
+            confidence = 'low'
+            explanation = ' (business identifier)'
+            description = 'Math.random() is being used for non-security purposes (business IDs, tracking numbers). While not critical, Math.random() can produce collisions in high-volume scenarios.'
+            suggestedFix = 'Consider crypto.randomUUID() for better uniqueness guarantees and collision resistance'
+          }
+          // Unknown context - MEDIUM
+          else {
+            severity = 'medium'
+            confidence = 'medium'
+            explanation = ' (unclear context)'
+            description = 'Math.random() is being used. Verify this is not for security-critical purposes like tokens, session IDs, or cryptographic operations.'
+            suggestedFix = 'If used for security, replace with crypto.randomBytes(). For unique IDs, use crypto.randomUUID()'
           }
+
+          // Update title with context
+          const title = `Math.random() in ${context.contextDescription}${explanation}`
+
+          vulnerabilities.push({
+            id: `dangerous-func-${filePath}-${index + 1}-${funcPattern.name}`,
+            filePath,
+            lineNumber: index + 1,
+            lineContent: line.trim(),
+            severity,
+            category: 'dangerous_function',
+            title,
+            description,
+            suggestedFix,
+            confidence,
+            layer: 2,
+          })
+          break // Only report once per line
         }
 
         // Standard handling for all other patterns

package/src/layer2/index.ts

@@ -5,7 +5,8 @@
  * and AI code fingerprinting
  */
 
-import type { Vulnerability, ScanFile } from '../types'
+import type { Vulnerability, ScanFile, CancellationToken } from '../types'
+import type { ProgressCallback } from '../index'
 import type { MiddlewareAuthConfig } from '../utils/middleware-detector'
 import { detectAuthHelpers, type AuthHelperContext } from '../utils/auth-helper-detector'
 import type { FileAuthImports } from '../utils/imported-auth-detector'
@@ -182,12 +183,16 @@ function processFileLayer2(
   }
 }
 
-// Parallel batch size for Layer 2 processing
+// Parallel batch size for Layer 2 processing (larger batches for performance)
 const LAYER2_PARALLEL_BATCH_SIZE = 50
+// Progress update interval (report every N files for better UX)
+const PROGRESS_UPDATE_INTERVAL = 10
 
 export async function runLayer2Scan(
   files: ScanFile[],
-  options: Layer2Options = {}
+  options: Layer2Options = {},
+  onProgress?: ProgressCallback,
+  cancellationToken?: CancellationToken
 ): Promise<Layer2Result> {
   const startTime = Date.now()
   const vulnerabilities: Vulnerability[] = []
@@ -208,17 +213,24 @@ export async function runLayer2Scan(
     endpointProtection: 0,
     schemaValidation: 0,
   }
-  
+
   // Detect auth helpers once for all files (if not already provided)
   const authHelperContext = options.authHelperContext || detectAuthHelpers(files)
 
+  // Track progress for frequent updates
+  let filesProcessed = 0
+  let lastProgressUpdate = 0
+
   // Process files in parallel batches for better performance on large codebases
   for (let i = 0; i < files.length; i += LAYER2_PARALLEL_BATCH_SIZE) {
+    // Check for cancellation before processing batch
+    if (cancellationToken?.cancelled) break
+
     const batch = files.slice(i, i + LAYER2_PARALLEL_BATCH_SIZE)
     const results = await Promise.all(
       batch.map(file => Promise.resolve(processFileLayer2(file, options, authHelperContext)))
     )
-    
+
     for (const result of results) {
       vulnerabilities.push(...result.findings)
       // Accumulate stats
@@ -226,6 +238,20 @@ export async function runLayer2Scan(
         stats[key as keyof Layer2DetectorStats] += value
       }
     }
+
+    filesProcessed = Math.min(i + LAYER2_PARALLEL_BATCH_SIZE, files.length)
+
+    // Report progress every PROGRESS_UPDATE_INTERVAL files for better UX
+    if (onProgress && (filesProcessed - lastProgressUpdate >= PROGRESS_UPDATE_INTERVAL || filesProcessed === files.length)) {
+      onProgress({
+        status: 'layer2',
+        message: 'Running structural scan (variables, logic gates)...',
+        filesProcessed,
+        totalFiles: files.length,
+        vulnerabilitiesFound: vulnerabilities.length,
+      })
+      lastProgressUpdate = filesProcessed
+    }
   }
 
   // Deduplicate findings

package/src/layer3/anthropic.ts

@@ -733,6 +733,35 @@ Distinguish these patterns:
     - Cross-tenant storage: medium (data isolation risk)
   - Do NOT describe transient BYOK keys as "stored without encryption" - they are NOT stored
 
+**Math.random() for Security:**
+Distinguish legitimate uses from security-critical misuse:
+- **Seed/Data Generation Files**: Files in /seed/, /fixtures/, /factories/, datacreator.ts, *.fixture.* are for test data generation
+  - Math.random() in seed files is acceptable - these are never production security code
+  - REJECT findings from seed/data generation files entirely
+- **Educational Vulnerability Files**: Files named insecurity.ts, vulnerable.ts, or in /intentionally-vulnerable/ paths
+  - These are OWASP Juice Shop challenges or security training examples
+  - REJECT entirely - they're intentionally vulnerable for educational purposes
+- **UUID/Identifier Generation**: Functions named generateUUID(), createId(), correlationId(), etc.
+  - Use Math.random() for UI correlation, React keys, element IDs
+  - Short toString(36).substring(2, 9) patterns are for UI correlation, NOT security tokens
+  - REJECT unless function name explicitly indicates security (generateToken, createSessionId, generateSecret)
+- **CAPTCHA/Puzzle Generation**: Math.random() for CAPTCHA questions, puzzle difficulty, game mechanics
+  - These don't need cryptographic randomness - legitimate non-security use
+  - REJECT findings in CAPTCHA/puzzle generation functions
+- **Security-Sensitive Context**: Only keep as HIGH/CRITICAL when:
+  - Variable names indicate security: token, secret, key, auth, session, password
+  - Function names indicate security: generateToken, createSession, makeSecret
+  - Used in security-critical files: auth.ts, crypto.ts, session.ts
+  - Long toString() patterns without truncation (potential token generation)
+
+**Severity Ladder for Math.random():**
+- Seed/educational files: REJECT (not production code)
+- UUID/CAPTCHA functions: REJECT (legitimate use)
+- Short UI IDs (toString(36).substring(2, 9)): INFO (UI correlation, suggest crypto.randomUUID())
+- Business IDs: LOW (suggest crypto.randomUUID() for collision resistance)
+- Security contexts (tokens/secrets/keys): HIGH (cryptographic weakness)
+- Unknown context: MEDIUM (needs manual review)
+
 ### 3.6 DOM Sinks and Bootstrap Scripts
 Recognise LOW-RISK patterns:
 - Static scripts reading localStorage for theme/preferences
@@ -1320,7 +1349,8 @@ async function validateWithOpenAI(
 export async function validateFindingsWithAI(
   findings: Vulnerability[],
   files: ScanFile[],
-  projectContext?: ProjectContext
+  projectContext?: ProjectContext,
+  onProgress?: (progress: { filesProcessed: number; totalFiles: number; status: string }) => void
 ): Promise<AIValidationResult> {
   // Initialize stats tracking
   const stats: ValidationStats = {
@@ -1393,11 +1423,23 @@ export async function validateFindingsWithAI(
 
   console.log(`[AI Validation] Phase 2: Processing ${fileEntries.length} files in ${totalFileBatches} API batch(es) (${FILES_PER_API_BATCH} files/batch)`)
 
+  // Track files processed for progress reporting
+  let filesValidated = 0
+
   // Process files in batches - each batch is ONE API call with multiple files
   for (let batchStart = 0; batchStart < fileEntries.length; batchStart += FILES_PER_API_BATCH) {
     const fileBatch = fileEntries.slice(batchStart, batchStart + FILES_PER_API_BATCH)
     const batchNum = Math.floor(batchStart / FILES_PER_API_BATCH) + 1
 
+    // Report progress before processing batch
+    if (onProgress) {
+      onProgress({
+        filesProcessed: filesValidated,
+        totalFiles: fileEntries.length,
+        status: `AI validating batch ${batchNum}/${totalFileBatches}`,
+      })
+    }
+
     console.log(`[AI Validation] API Batch ${batchNum}/${totalFileBatches}: ${fileBatch.length} files`)
 
     // Prepare file data for batch request
@@ -1578,6 +1620,18 @@ export async function validateFindingsWithAI(
 
     const batchDuration = Date.now() - batchStartTime
     totalBatchWaitTime += batchDuration
+
+    // Update files validated counter
+    filesValidated += fileBatch.length
+
+    // Report progress after batch completion
+    if (onProgress) {
+      onProgress({
+        filesProcessed: filesValidated,
+        totalFiles: fileEntries.length,
+        status: `AI validation complete for batch ${batchNum}/${totalFileBatches}`,
+      })
+    }
   }
 
   // Calculate cache hit rate

package/src/layer3/index.ts

@@ -3,7 +3,7 @@
  * Deep security analysis using Claude AI and package verification
  */
 
-import type { Vulnerability, ScanFile } from '../types'
+import type { Vulnerability, ScanFile, CancellationToken } from '../types'
 import { batchAnalyzeWithAI, type Layer3Context } from './anthropic'
 import { checkPackages } from './package-check'
 
@@ -33,6 +33,8 @@ export interface Layer3Options {
   maxFiles?: number
   /** Project context for auth-aware analysis */
   projectContext?: Layer3Context
+  /** Cancellation token for aborting scans */
+  cancellationToken?: CancellationToken
 }
 
 export async function runLayer3Scan(
@@ -42,17 +44,40 @@ export async function runLayer3Scan(
   const startTime = Date.now()
   const vulnerabilities: Vulnerability[] = []
   let aiAnalyzedCount = 0
-  
+
   // Use provided maxFiles or default
   const maxAIFiles = options.maxFiles ?? MAX_AI_FILES
 
+  // Check for cancellation before package check
+  if (options.cancellationToken?.cancelled) {
+    return {
+      vulnerabilities: [],
+      filesScanned: files.length,
+      duration: Date.now() - startTime,
+      aiAnalyzed: 0,
+    }
+  }
+
   // 1. Check packages (always run, fast)
   const packageFiles = files.filter(f => f.path.endsWith('package.json'))
   for (const file of packageFiles) {
+    // Check for cancellation in package loop
+    if (options.cancellationToken?.cancelled) break
+
     const packageFindings = await checkPackages(file.content, file.path)
     vulnerabilities.push(...packageFindings)
   }
 
+  // Check for cancellation before AI analysis
+  if (options.cancellationToken?.cancelled) {
+    return {
+      vulnerabilities,
+      filesScanned: files.length,
+      duration: Date.now() - startTime,
+      aiAnalyzed: 0,
+    }
+  }
+
   // 2. AI Analysis (if enabled)
   if (options.enableAI !== false) {
     // Select files for AI analysis