@oculum/scanner 1.0.9 → 1.0.11

package/src/layer3/anthropic/index.ts

@@ -0,0 +1,170 @@
+/**
+ * Layer 3: AI Semantic Analysis
+ *
+ * Uses Claude to perform deep security analysis including:
+ * - Taint analysis (data flow from sources to sinks)
+ * - Business logic flaw detection
+ * - Missing authorization checks
+ * - Cryptography validation
+ * - Data exposure detection
+ * - Framework-specific deep analysis
+ *
+ * Also provides high-context validation for Layer 1/2 findings.
+ */
+
+import type { Vulnerability, ScanFile } from '../../types'
+import type { ProjectContext } from '../../utils/project-context-builder'
+import { buildProjectContext } from '../../utils/project-context-builder'
+import type { ValidationStats, AIValidationResult, Layer3Context, AIFinding } from './types'
+import { createInitialStats } from './types'
+import { getAnthropicClient } from './clients'
+import { parseAIResponse, getLineContent, validateSeverity, validateCategory } from './utils/response-parser'
+import { buildAuthContextForPrompt, SECURITY_ANALYSIS_PROMPT } from './prompts/semantic-analysis'
+import { validateWithOpenAI } from './providers/openai'
+import { validateWithAnthropic } from './providers/anthropic'
+
+// Re-export types and functions for backward compatibility
+export type { ValidationStats, AIValidationResult, Layer3Context } from './types'
+export { applyAutoDismissRules } from './auto-dismiss'
+
+// ============================================================================
+// Layer 3: Deep AI Analysis
+// ============================================================================
+
+/**
+ * Analyze a single file using AI for deep security analysis (Layer 3)
+ */
+export async function analyzeWithAI(
+  file: ScanFile,
+  context?: Layer3Context
+): Promise<Vulnerability[]> {
+  const client = getAnthropicClient()
+
+  // Prepare the code with line numbers for reference
+  const numberedCode = file.content
+    .split('\n')
+    .map((line, i) => `${i + 1}: ${line}`)
+    .join('\n')
+
+  // Build auth context for the prompt
+  const authContext = buildAuthContextForPrompt(context)
+
+  const userMessage = `Analyze this ${file.language} file for security vulnerabilities:
+
+File: ${file.path}${authContext}
+
+\`\`\`${file.language}
+${numberedCode}
+\`\`\`
+
+Return ONLY a JSON array of findings.`
+
+  try {
+    const response = await client.messages.create({
+      model: 'claude-3-5-haiku-20241022',
+      max_tokens: 4096,
+      system: SECURITY_ANALYSIS_PROMPT,
+      messages: [
+        {
+          role: 'user',
+          content: userMessage,
+        },
+      ],
+    })
+
+    // Extract text content from response
+    const textContent = response.content.find((block: { type: string }) => block.type === 'text')
+    if (!textContent || textContent.type !== 'text') {
+      console.error('No text content in AI response')
+      return []
+    }
+
+    // Parse the JSON response
+    const findings = parseAIResponse(textContent.text)
+
+    // Convert to Vulnerability format
+    return findings.map((finding, index) => ({
+      id: `ai-${file.path}-${finding.lineNumber}-${index}`,
+      filePath: file.path,
+      lineNumber: finding.lineNumber,
+      lineContent: getLineContent(file.content, finding.lineNumber),
+      severity: finding.severity,
+      category: finding.category,
+      title: finding.title,
+      description: finding.description,
+      suggestedFix: finding.suggestedFix,
+      confidence: 'high' as const,
+      layer: 3 as const,
+    }))
+  } catch (error) {
+    console.error('AI analysis error:', error)
+    return []
+  }
+}
+
+/**
+ * Batch analyze multiple files using AI (Layer 3)
+ * Processes files in batches to avoid rate limits
+ */
+export async function batchAnalyzeWithAI(
+  files: ScanFile[],
+  context?: Layer3Context,
+  maxConcurrent: number = 3
+): Promise<Vulnerability[]> {
+  const vulnerabilities: Vulnerability[] = []
+
+  // Process files in batches to avoid rate limits
+  for (let i = 0; i < files.length; i += maxConcurrent) {
+    const batch = files.slice(i, i + maxConcurrent)
+    const results = await Promise.all(
+      batch.map(file => analyzeWithAI(file, context).catch(err => {
+        console.error(`AI analysis failed for ${file.path}:`, err)
+        return []
+      }))
+    )
+    vulnerabilities.push(...results.flat())
+
+    // Small delay between batches to avoid rate limits
+    if (i + maxConcurrent < files.length) {
+      await new Promise(resolve => setTimeout(resolve, 500))
+    }
+  }
+
+  return vulnerabilities
+}
+
+// ============================================================================
+// Layer 2.5: High-Context Validation
+// ============================================================================
+
+/**
+ * Validate Layer 1/2 findings using AI with HIGH-CONTEXT validation
+ *
+ * Key improvements over previous version:
+ * 1. Sends FULL FILE CONTENT (not just snippets) for better context
+ * 2. Includes PROJECT CONTEXT (auth patterns, data access, etc.)
+ * 3. Uses generalised rules from Section 3 of the security model
+ */
+export async function validateFindingsWithAI(
+  findings: Vulnerability[],
+  files: ScanFile[],
+  projectContext?: ProjectContext,
+  onProgress?: (progress: { filesProcessed: number; totalFiles: number; status: string }) => void
+): Promise<AIValidationResult> {
+  // Initialize stats tracking
+  const stats: ValidationStats = createInitialStats(findings.length)
+
+  if (findings.length === 0) {
+    return { vulnerabilities: [], stats }
+  }
+
+  // Check for provider override (GPT-5-mini is default for 47% cost savings)
+  const aiProvider = process.env.AI_PROVIDER || 'openai'
+  if (aiProvider === 'anthropic') {
+    console.log('[AI Validation] Using Anthropic provider (Claude 3.5 Haiku)')
+    return validateWithAnthropic(findings, files, projectContext, stats, onProgress)
+  } else {
+    console.log('[AI Validation] Using OpenAI provider (GPT-5-mini)')
+    return validateWithOpenAI(findings, files, projectContext, stats)
+  }
+}

package/src/layer3/anthropic/prompts/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Prompts Index
+ *
+ * Re-exports all prompt templates and helpers.
+ */
+
+export {
+  SECURITY_ANALYSIS_PROMPT,
+  buildAuthContextForPrompt,
+} from './semantic-analysis'
+
+export {
+  HIGH_CONTEXT_VALIDATION_PROMPT,
+} from './validation'

package/src/layer3/anthropic/prompts/semantic-analysis.ts

@@ -0,0 +1,173 @@
+/**
+ * Security Analysis Prompt (Layer 3)
+ *
+ * System prompt for deep semantic security analysis using AI.
+ */
+
+import type { Layer3Context } from '../types'
+
+// ============================================================================
+// Security Analysis Prompt
+// ============================================================================
+
+/**
+ * System prompt for security analysis
+ */
+export const SECURITY_ANALYSIS_PROMPT = `You are an expert security code reviewer. Analyze the provided code for security vulnerabilities.
+
+Focus on these specific vulnerability types:
+
+1. **Taint Analysis (Data Flow)**
+   - Track user input from sources (req.query, req.params, req.body, searchParams, URL parameters)
+   - To dangerous sinks (eval, dangerouslySetInnerHTML, exec, SQL queries, file operations)
+   - Flag any path where untrusted data reaches a dangerous function without sanitization
+
+2. **SQL Injection**
+   - String concatenation in SQL queries
+   - Template literals with user input in queries
+   - Missing parameterized queries
+
+3. **XSS (Cross-Site Scripting)**
+   - User input rendered without escaping
+   - dangerouslySetInnerHTML with user data
+   - innerHTML assignments
+   - NOTE: React/Next.js JSX automatically escapes content, so {variable} in JSX is NOT XSS
+
+4. **Command Injection**
+   - exec, spawn, execSync with user input
+   - Shell command construction with variables
+
+5. **Missing Authorization**
+   - API routes that modify data without auth checks
+   - Database writes in GET handlers
+   - Missing permission checks before sensitive operations
+
+6. **Insecure Deserialization**
+   - JSON.parse on untrusted data without validation
+   - eval of serialized data
+
+7. **Cryptography Validation**
+   - Weak algorithms: MD5 (for security), SHA1 (for security), DES, RC4
+   - Insecure random: Math.random() for tokens/keys/secrets
+   - Hardcoded encryption keys or IVs (not from env vars)
+   - ECB mode usage (patterns indicate cipher mode)
+   - Low iteration counts for PBKDF2 (< 10000)
+   - Short key lengths (< 256 bits for symmetric)
+   - Missing salt for password hashing
+   - createCipher() instead of createCipheriv()
+
+8. **Data Exposure Detection**
+   - Logging sensitive data: console.log with passwords, tokens, secrets, API keys
+   - Stack traces exposed to clients: err.stack in response
+   - Returning entire user objects (may include password hash)
+   - Debug endpoints left in code: /debug, /test, /_internal routes
+   - Verbose error messages exposing internal details
+   - Sensitive data in error responses
+
+9. **Framework-Specific Security**
+
+   **Next.js:**
+   - Server actions ('use server') without authentication
+   - Client components ('use client') accessing non-NEXT_PUBLIC_ env vars
+   - Middleware that returns NextResponse.next() without auth checks
+   - getServerSideProps without session validation
+   - Exposed API routes without rate limiting
+
+   **React:**
+   - Sensitive data stored in useState (visible in devtools)
+   - dangerouslySetInnerHTML with props/state
+   - useEffect making authenticated API calls without token validation
+
+   **Express:**
+   - Missing helmet() middleware for security headers
+   - CORS with origin: "*" in production
+   - Missing body-parser limits (DoS risk)
+   - Trust proxy without verification
+   - Error handlers exposing stack traces
+
+IMPORTANT - DO NOT FLAG THESE AS VULNERABILITIES (common false positives):
+
+**Framework Patterns (Safe by Design):**
+- Next.js middleware using request.url for redirects (standard pattern)
+- React/Next.js JSX rendering variables like {user.name} (auto-escaped by React)
+- Supabase/Firebase client creation with NEXT_PUBLIC_ environment variables
+- Using headers().get('host') in Next.js server actions
+
+**Data Handling (Low Risk):**
+- JSON.parse on data from YOUR OWN database (the app wrote it, it's trusted). Do NOT report this as a vulnerability. At most, you may mention an info-level robustness note if there is no error handling, but generally you should omit it.
+- JSON.parse on localStorage data (same-origin, XSS is a separate issue). This is also not a security vulnerability. At most, you may suggest an info-level robustness improvement, and usually it is not worth mentioning.
+- Passing user's own data to external APIs (user embedding their own content).
+- Error messages that use error.message in catch blocks or are returned to the client as a generic error string are standard error handling. Treat them as LOW/INFO hardening at most, and DO NOT mark them as medium/high unless the message clearly includes credentials, secrets, or full stack traces.
+- Generic configuration or feature messages like "OpenAI API key not configured" or "service disabled" are operational information, not security vulnerabilities. Treat them as info at most, or ignore them.
+
+**Authentication Patterns (Context Matters):**
+- Internal server-side functions only called from trusted code paths (OAuth callbacks, etc.)
+- Functions with userId parameters called with session.user.id from authenticated contexts
+- Service role keys used in server-side code with proper auth checks elsewhere
+- API routes that call getCurrentUserId() and use the result (the auth check IS the userId call)
+
+**BYOK (Bring Your Own Key) Patterns:**
+- User-provided API keys in BYOK mode are INTENTIONAL - the user wants to use their own key
+- This is a feature, not a vulnerability - don't flag it unless there's actual abuse potential
+- When a BYOK key is only used TRANSIENTLY in memory for a single provider call (and is never logged or stored), and the route is authenticated, do NOT report this as a medium/high vulnerability. At most, you may surface a low/info note reminding the developer not to log or persist keys.
+- Frontend components sending a BYOK key to an authenticated backend endpoint for one-shot use are expected behavior, not a vulnerability. Do NOT flag these as data_exposure or dangerous_function unless the key is logged, stored, or echoed back to the client.
+- Only raise medium/high BYOK findings when keys are clearly stored (e.g., written to a database or long-term logs), logged in plaintext, or accepted by unauthenticated endpoints that attackers could abuse at scale.
+
+**What TO Flag (Real Vulnerabilities):**
+- SQL string concatenation with user input
+- eval() or Function() with user-controlled strings
+- Missing auth checks where sensitive data could be accessed by wrong user
+- Actual hardcoded secrets (real API keys, not env var references)
+- Command injection (exec/spawn with user input)
+
+Respond ONLY with a JSON array of findings. Each finding must have:
+{
+  "lineNumber": <number>,
+  "severity": "critical" | "high" | "medium" | "low",
+  "category": "sql_injection" | "xss" | "command_injection" | "missing_auth" | "dangerous_function",
+  "title": "<short title>",
+  "description": "<detailed explanation of the vulnerability>",
+  "suggestedFix": "<how to fix it>"
+}
+
+If no vulnerabilities are found, return an empty array: []
+
+CRITICAL: Only report REAL vulnerabilities with HIGH confidence. Be conservative - it's better to miss a low-confidence issue than to report false positives. The code is likely using modern frameworks with built-in protections.`
+
+// ============================================================================
+// Auth Context Builder
+// ============================================================================
+
+/**
+ * Build auth context string for AI prompt
+ */
+export function buildAuthContextForPrompt(ctx?: Layer3Context): string {
+  if (!ctx) return ''
+
+  const parts: string[] = []
+
+  if (ctx.middlewareConfig?.hasAuthMiddleware) {
+    parts.push(`**IMPORTANT AUTH CONTEXT**: This project uses ${ctx.middlewareConfig.authType || 'auth'} middleware.`)
+    if (ctx.middlewareConfig.protectedPaths.length > 0) {
+      parts.push(`Protected paths: ${ctx.middlewareConfig.protectedPaths.join(', ')}`)
+    } else {
+      parts.push('All /api/** routes are protected by default.')
+    }
+    parts.push('Routes under these paths are ALREADY AUTHENTICATED - do NOT flag them as "missing auth".')
+    parts.push('Client components calling these protected API routes are also safe - the backend handles auth.')
+  }
+
+  if (ctx.authHelpers?.hasThrowingHelpers) {
+    parts.push('')
+    parts.push('**AUTH HELPER FUNCTIONS**: This project uses throwing auth helpers that guarantee authenticated context:')
+    parts.push(ctx.authHelpers.summary)
+    parts.push('Code after these helper calls is GUARANTEED to be authenticated. Do NOT flag "missing auth" after these calls.')
+  }
+
+  if (ctx.additionalContext) {
+    parts.push('')
+    parts.push(ctx.additionalContext)
+  }
+
+  return parts.length > 0 ? '\n\n' + parts.join('\n') : ''
+}