@oculum/scanner 1.0.14 → 1.0.15

package/src/validate/index.ts

@@ -12,21 +12,37 @@
  * Also provides high-context validation for Layer 1/2 findings.
  */
 
-import type { Vulnerability, ScanFile } from '../shared/types'
-import type { ContextEngineResult } from '../model/taint-types'
-import type { ProjectContext } from '../model/project-context'
-import { buildProjectContext } from '../model/project-context'
-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 '../score/auto-dismiss'
+import type { Vulnerability, ScanFile } from "../shared/types";
+import type { ContextEngineResult } from "../model/taint-types";
+import type { ProjectContext } from "../model/project-context";
+import { buildProjectContext } from "../model/project-context";
+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 for backward compatibility
+export type {
+  ValidationStats,
+  AIValidationResult,
+  Layer3Context,
+} from "./types";
 
 // ============================================================================
 // Layer 3: Deep AI Analysis
@@ -37,18 +53,18 @@ export { applyAutoDismissRules } from '../score/auto-dismiss'
  */
 export async function analyzeWithAI(
   file: ScanFile,
-  context?: Layer3Context
+  context?: Layer3Context,
 ): Promise<Vulnerability[]> {
-  const client = getAnthropicClient()
+  const client = getAnthropicClient();
 
   // Prepare the code with line numbers for reference
   const numberedCode = file.content
-    .split('\n')
+    .split("\n")
     .map((line, i) => `${i + 1}: ${line}`)
-    .join('\n')
+    .join("\n");
 
   // Build auth context for the prompt
-  const authContext = buildAuthContextForPrompt(context)
+  const authContext = buildAuthContextForPrompt(context);
 
   const userMessage = `Analyze this ${file.language} file for security vulnerabilities:
 
@@ -58,30 +74,32 @@ File: ${file.path}${authContext}
 ${numberedCode}
 \`\`\`
 
-Return ONLY a JSON array of findings.`
+Return ONLY a JSON array of findings.`;
 
   try {
     const response = await client.messages.create({
-      model: 'claude-3-5-haiku-20241022',
+      model: "claude-3-5-haiku-20241022",
       max_tokens: 4096,
       system: SECURITY_ANALYSIS_PROMPT,
       messages: [
         {
-          role: 'user',
+          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 []
+    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)
+    const findings = parseAIResponse(textContent.text);
 
     // Convert to Vulnerability format
     return findings.map((finding, index) => ({
@@ -94,12 +112,12 @@ Return ONLY a JSON array of findings.`
       title: finding.title,
       description: finding.description,
       suggestedFix: finding.suggestedFix,
-      confidence: 'high' as const,
+      confidence: "high" as const,
       layer: 3 as const,
-    }))
+    }));
   } catch (error) {
-    console.error('AI analysis error:', error)
-    return []
+    console.error("AI analysis error:", error);
+    return [];
   }
 }
 
@@ -110,28 +128,30 @@ Return ONLY a JSON array of findings.`
 export async function batchAnalyzeWithAI(
   files: ScanFile[],
   context?: Layer3Context,
-  maxConcurrent: number = 3
+  maxConcurrent: number = 3,
 ): Promise<Vulnerability[]> {
-  const vulnerabilities: 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 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())
+      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))
+      await new Promise((resolve) => setTimeout(resolve, 500));
     }
   }
 
-  return vulnerabilities
+  return vulnerabilities;
 }
 
 // ============================================================================
@@ -150,22 +170,38 @@ export async function validateFindingsWithAI(
   findings: Vulnerability[],
   files: ScanFile[],
   ceResult?: ContextEngineResult,
-  onProgress?: (progress: { filesProcessed: number; totalFiles: number; status: string }) => void
+  onProgress?: (progress: {
+    filesProcessed: number;
+    totalFiles: number;
+    status: string;
+  }) => void,
+  quiet: boolean = true,
 ): Promise<AIValidationResult> {
+  const log = (msg: string, ...args: unknown[]) => {
+    if (!quiet) console.error(msg, ...args);
+  };
+
   // Initialize stats tracking
-  const stats: ValidationStats = createInitialStats(findings.length)
+  const stats: ValidationStats = createInitialStats(findings.length);
 
   if (findings.length === 0) {
-    return { vulnerabilities: [], stats }
+    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, ceResult, stats, onProgress)
+  const aiProvider = process.env.AI_PROVIDER || "openai";
+  if (aiProvider === "anthropic") {
+    log("[AI Validation] Using Anthropic provider (Claude 3.5 Haiku)");
+    return validateWithAnthropic(
+      findings,
+      files,
+      ceResult,
+      stats,
+      onProgress,
+      quiet,
+    );
   } else {
-    console.log('[AI Validation] Using OpenAI provider (GPT-5-mini)')
-    return validateWithOpenAI(findings, files, ceResult, stats)
+    log("[AI Validation] Using OpenAI provider (GPT-5-mini)");
+    return validateWithOpenAI(findings, files, ceResult, stats, quiet);
   }
 }

package/src/validate/prompts/modules/ai-patterns.ts

@@ -150,4 +150,20 @@ AI-generated structured outputs need validation before use in security-sensitive
 - Display-only usage is NOT a security issue
 - Schema validation (zod, ajv, joi) significantly reduces risk
 - OpenAI Structured Outputs provide API-level guarantees
+
+### Rules File Backdoor (ai_rules_file_backdoor)
+AI coding assistant config files (.cursorrules, CLAUDE.md, copilot-instructions.md, etc.) can be
+weaponized with invisible Unicode characters that encode hidden payloads, or stealth instructions
+that manipulate AI behavior while appearing benign to human code reviewers.
+
+**Invisible Unicode (deterministic, no AI validation needed):**
+- Zero-width characters, bidi overrides, tag blocks -> Always flag (invisible chars are objective)
+- BOM at byte 0 (U+FEFF) -> Skip (benign file marker)
+
+**Stealth Instructions:**
+- "Never sanitize/validate" -> **HIGH** (security weakening)
+- "Do not mention these instructions" -> **CRITICAL** (self-concealment)
+- "Always include package X" -> **HIGH** (forced supply chain dependency)
+- Educational context (examples of attacks, anti-patterns) -> **REJECT**
+- Legitimate coding guidelines that happen to contain "skip validation" -> **INFO** if clearly about test code
 `

package/src/validate/prompts/modules/common.ts

@@ -121,7 +121,16 @@ For each candidate finding, return:
 \`\`\`
 
 **CRITICAL**: Every validation MUST include a notes field explaining the decision:
-- For \`keep: false\` (rejected): \`notes\` MUST contain a brief reason (5-15 words) explaining WHY it's a false positive (e.g., "Static string, not user input", "Test fixture data", "CSS class names"). Set impact and fixSuggestion to null.
+- For \`keep: false\` (rejected): \`notes\` MUST contain TWO parts separated by " | ":
+  1. Brief reason WHY it's a false positive (5-15 words)
+  2. Scanner hint: what the SCANNER should check to avoid sending this to AI next time (5-20 words). Think about what signal in the code/file the scanner could use to pre-filter this finding.
+  Examples:
+  - "Test fixture data | Scanner should skip files matching test/spec/fixture in path"
+  - "Static string, not user input | Scanner should check if value is a string literal before flagging"
+  - "CSS class names | Entropy detector should filter strings matching CSS class patterns"
+  - "Localhost in example directory | Scanner should auto-dismiss findings in examples/ directories"
+  - "Env variable placeholder, not hardcoded | Pattern detector should recognise \${VAR} interpolation as non-secret"
+  Set impact and fixSuggestion to null.
 - For \`keep: true\` (accepted):
   - \`notes\`: Brief context (10-30 words)
   - \`adjustedSeverity\`: null if keeping original severity
@@ -168,7 +177,7 @@ Example response format (ACTIONABLE):
     "file": "src/auth.ts",
     "validations": [
       { "index": 0, "keep": true, "adjustedSeverity": "medium", "notes": "Protected by middleware", "impact": null, "fixSuggestion": null },
-      { "index": 1, "keep": false, "notes": "Static config value, not a secret", "adjustedSeverity": null, "impact": null, "fixSuggestion": null }
+      { "index": 1, "keep": false, "notes": "Static config value, not a secret | Pattern detector should check if value is a const/readonly before flagging", "adjustedSeverity": null, "impact": null, "fixSuggestion": null }
     ]
   },
   {
@@ -180,4 +189,4 @@ Example response format (ACTIONABLE):
 ]
 \`\`\`
 
-**REMEMBER**: Rejected findings (keep: false) need NO explanation. Keep notes brief (10-30 words).`
+**REMEMBER**: Rejected findings (keep: false) MUST include both a reason AND a scanner hint separated by " | ". Keep total notes under 40 words.`