@oculum/scanner 1.0.14 → 1.0.15

package/src/detect/ast-rules/taint-fix-templates.ts

@@ -0,0 +1,108 @@
+/**
+ * Taint-Specific Fix Templates
+ *
+ * Provides context-specific fix steps for taint flow findings based on
+ * source type, sink type, and taint kind. Returns 3-5 actionable steps
+ * instead of generic "Sanitize or validate user input" advice.
+ */
+
+import type { TaintSourceType, TaintSinkType, TaintKind } from '../../taint/types'
+
+// ============================================================================
+// Sink-Specific Fix Steps (primary axis)
+// ============================================================================
+
+const SINK_FIX_STEPS: Record<TaintKind, string[]> = {
+  sql: [
+    'Use parameterized queries or prepared statements (e.g., db.query("SELECT * FROM users WHERE id = $1", [id]))',
+    'Use ORM query builder methods (Prisma, Knex, Sequelize) instead of raw SQL',
+    'Never concatenate or interpolate user input into SQL strings',
+  ],
+  xss: [
+    'Escape output using your framework\'s built-in mechanism (React auto-escapes JSX, use textContent instead of innerHTML)',
+    'Sanitize HTML with DOMPurify.sanitize() before rendering dynamic content',
+    'Avoid dangerouslySetInnerHTML, innerHTML, and document.write with user data',
+  ],
+  command: [
+    'Use execFile() with an argument array instead of exec() with shell strings',
+    'Validate inputs against an allowlist of permitted values',
+    'Never pass user input directly to shell commands or eval()',
+  ],
+  ssrf: [
+    'Validate URLs against an allowlist of permitted domains',
+    'Reject requests to private/internal IP ranges (10.x, 172.16.x, 192.168.x, 169.254.x)',
+    'Parse the URL and verify the hostname before making the request',
+  ],
+  prompt: [
+    'Delimit user input with clear markers (e.g., <user_input>...</user_input>) in prompts',
+    'Use the structured messages API with separate system/user roles instead of string concatenation',
+    'Apply input length limits and content filtering before prompt construction',
+  ],
+  path: [
+    'Use path.resolve() and verify the result is within the allowed base directory',
+    'Reject inputs containing "../" or absolute paths',
+    'Use path.join() with a fixed base path and validate the resolved path stays within bounds',
+  ],
+}
+
+// ============================================================================
+// Source-Aware Prefix Steps (secondary axis)
+// ============================================================================
+
+const SOURCE_PREFIX: Partial<Record<TaintSourceType, string>> = {
+  http_body: 'Validate request body with a schema library (zod, joi, yup) before use',
+  http_query: 'Validate and sanitize URL query parameters before use',
+  http_params: 'Validate URL path parameters (check format, length, allowlist)',
+  http_headers: 'Validate and sanitize request headers before use',
+  llm_output: 'Treat LLM output as untrusted — validate and sanitize before passing to sinks',
+  rag_retrieval: 'Sanitize retrieved documents before including in prompts or rendering',
+  tool_output: 'Validate tool/function call output before further processing',
+  tool_input: 'Validate tool input parameters before execution',
+  conversation_history: 'Sanitize conversation history entries before reuse in prompts',
+  websocket_message: 'Validate and sanitize WebSocket message payloads',
+  file_upload: 'Validate file upload content and metadata before processing',
+  cli_args: 'Validate CLI arguments against expected patterns before use',
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Get context-specific fix steps for a taint finding.
+ *
+ * @param sourceType - The taint source type (e.g., 'http_body', 'llm_output')
+ * @param sinkType - The taint sink type (e.g., 'sql_query', 'eval')
+ * @param taintKind - The taint kind (e.g., 'sql', 'xss', 'command')
+ * @returns Array of 3-5 actionable fix steps
+ */
+export function getTaintFixSteps(
+  sourceType: TaintSourceType | string,
+  sinkType: TaintSinkType | string,
+  taintKind: TaintKind
+): string[] {
+  const steps: string[] = []
+
+  // Add source-aware prefix step if available
+  const prefix = SOURCE_PREFIX[sourceType as TaintSourceType]
+  if (prefix) {
+    steps.push(prefix)
+  }
+
+  // Add sink-specific fix steps (primary guidance)
+  const sinkSteps = SINK_FIX_STEPS[taintKind]
+  if (sinkSteps) {
+    steps.push(...sinkSteps)
+  }
+
+  // Fallback for unknown combinations
+  if (steps.length === 0) {
+    steps.push(
+      'Validate and sanitize user input before passing to security-sensitive functions',
+      'Use framework-provided safe APIs instead of raw string manipulation',
+      'Apply the principle of least privilege when handling untrusted data',
+    )
+  }
+
+  return steps
+}

package/src/detect/ast-rules/taint-flow-ast.ts

@@ -0,0 +1,416 @@
+/**
+ * AST-Based Taint Flow Detection
+ *
+ * Runs the v2 taint engine (CFG-based forward propagation) during AST detection
+ * and emits Vulnerability objects for confirmed taint flows from user input to
+ * dangerous sinks without sanitization.
+ *
+ * Registers one rule per TaintKind so each gets its own VulnerabilityCategory.
+ * Findings are cached per-file (by AST hash) so the taint engine only runs once
+ * even though 6 rules query results.
+ */
+
+import type { ParsedAST } from "../../parse/ast";
+import { registerASTRule, type ASTRuleMatch } from "./index";
+import { getTaintFixSteps } from "./taint-fix-templates";
+import { analyzeTaintsForFile } from "../../taint/taint-analyzer";
+import type { TaintFinding } from "../../taint/propagation-types";
+import type { TaintKind } from "../../taint/types";
+import type {
+  VulnerabilityCategory,
+  VulnerabilitySeverity,
+  TaintPathOutput,
+} from "../../shared/types";
+import {
+  isScannerOrFixtureFile,
+  isTestOrMockFile,
+} from "../../parse/file-classifier";
+import {
+  assessPromptInjectionRisk,
+  assessExecutionRisk,
+} from "../../taint/llm-risk-scoring";
+
+// ============================================================================
+// TaintKind → Vulnerability Mapping
+// ============================================================================
+
+const KIND_TO_CATEGORY: Record<TaintKind, VulnerabilityCategory> = {
+  sql: "sql_injection",
+  xss: "xss",
+  command: "command_injection",
+  ssrf: "ssrf",
+  prompt: "ai_prompt_injection",
+  path: "dangerous_function",
+};
+
+const KIND_TO_SEVERITY: Record<TaintKind, VulnerabilitySeverity> = {
+  sql: "high",
+  xss: "high",
+  command: "high",
+  ssrf: "high",
+  prompt: "medium",
+  path: "medium",
+};
+
+const KIND_TO_TITLE: Record<TaintKind, string> = {
+  sql: "SQL injection via unsanitized data flow",
+  xss: "Cross-site scripting via unsanitized data flow",
+  command: "Command injection via unsanitized data flow",
+  ssrf: "Server-side request forgery via unsanitized data flow",
+  prompt: "Prompt injection via unsanitized data flow",
+  path: "Path traversal via unsanitized data flow",
+};
+
+// ============================================================================
+// Taint Path Serialization
+// ============================================================================
+
+/** Convert internal TaintFinding to serializable TaintPathOutput. */
+export function serializeTaintPath(finding: TaintFinding): TaintPathOutput {
+  return {
+    sourceType: finding.source.sourceType,
+    sourceLine: finding.source.line,
+    sinkType: finding.sink.sinkType,
+    sinkLine: finding.sink.line,
+    taintKinds: [...finding.matchingKinds],
+    sanitized: false,
+    steps: finding.path.map((step) => ({
+      line: step.line,
+      variable: step.variable,
+      taintKinds: [...step.taintKinds],
+      description: step.description,
+      stepType: step.stepType,
+      ...(step.filePath ? { filePath: step.filePath } : {}),
+      ...(step.functionName ? { functionName: step.functionName } : {}),
+    })),
+  };
+}
+
+// ============================================================================
+// Per-file Findings Cache
+// ============================================================================
+
+/** IMPORTANT: Must call clearTaintFlowCache() between scans to prevent stale data. */
+const findingsCache = new Map<string, TaintFinding[]>();
+
+/** Project-level findings cache — keyed by filePath → findings in that file.
+ *  IMPORTANT: Must call clearTaintFlowCache() between scans to prevent stale data. */
+const projectFindingsCache = new Map<string, TaintFinding[]>();
+let hasProjectFindings = false;
+
+/**
+ * Pre-populate the cache with project-level cross-file taint findings.
+ * Called by detect/index.ts after running analyzeTaintsForProject().
+ * When set, the per-file fallback is skipped.
+ */
+export function setProjectFindings(findings: TaintFinding[]): void {
+  projectFindingsCache.clear();
+  for (const f of findings) {
+    const existing = projectFindingsCache.get(f.filePath) ?? [];
+    existing.push(f);
+    projectFindingsCache.set(f.filePath, existing);
+  }
+  hasProjectFindings = true;
+}
+
+function getFindings(ast: ParsedAST): TaintFinding[] {
+  // Prefer project-level cross-file findings when available
+  if (hasProjectFindings) {
+    return projectFindingsCache.get(ast.filePath) ?? [];
+  }
+
+  // Fallback: per-file analysis (no cross-file context)
+  const cached = findingsCache.get(ast.hash);
+  if (cached !== undefined) return cached;
+
+  const findings = analyzeTaintsForFile(ast, ast.filePath);
+  findingsCache.set(ast.hash, findings);
+  return findings;
+}
+
+/** Clear findings cache between scans. */
+export function clearTaintFlowCache(): void {
+  findingsCache.clear();
+  projectFindingsCache.clear();
+  hasProjectFindings = false;
+}
+
+// ============================================================================
+// LLM-Aware Category / Severity Routing
+// ============================================================================
+
+/** Source types that indicate LLM-related data flow */
+const LLM_SOURCE_TYPES = new Set([
+  "llm_output",
+  "tool_output",
+  "rag_retrieval",
+  "conversation_history",
+]);
+
+/** Sink types that are prompt-related */
+const PROMPT_SINK_TYPES = new Set(["prompt_construction", "system_prompt"]);
+
+/** LangChain message class names — LLM output wrapped in these is output packaging, not injection */
+const LANGCHAIN_MESSAGE_CLASS_RE =
+  /AIMessage|HumanMessage|SystemMessage|ChatMessage|AIMessageChunk|HumanMessageChunk|BaseMessage/;
+
+/** Check if a taint finding's sink involves LangChain message class wrapping (output packaging) */
+function isOutputPackaging(finding: TaintFinding): boolean {
+  const sinkExpr = finding.sink.expression;
+  return LANGCHAIN_MESSAGE_CLASS_RE.test(sinkExpr);
+}
+
+/** HTTP source types that represent direct user input */
+const HTTP_SOURCE_TYPES = new Set([
+  "http_body",
+  "http_query",
+  "http_params",
+  "http_header",
+  "form_input",
+  "url_param",
+]);
+
+function isHTTPSourceType(sourceType: string): boolean {
+  return HTTP_SOURCE_TYPES.has(sourceType);
+}
+
+/** Check if a file path matches context builder / prompt template patterns */
+function isContextBuilderFile(filePath: string): boolean {
+  return /context[-_]?builder|system[-_]?prompt|prompt[-_]?template|prompt[-_]?builder/i.test(
+    filePath,
+  );
+}
+
+/**
+ * Determine category and severity for a taint finding, with LLM-aware routing:
+ *
+ * - User input → prompt sink → ai_prompt_injection (with risk scoring)
+ * - LLM output → execution sink → ai_unsafe_execution (with risk scoring)
+ * - Standard taint flow → original kind-based mapping
+ */
+function getCategoryAndSeverity(
+  finding: TaintFinding,
+  kind: TaintKind,
+  content: string,
+): {
+  category: VulnerabilityCategory;
+  severity: VulnerabilitySeverity;
+  note: string;
+} {
+  const isLLMSource = LLM_SOURCE_TYPES.has(finding.source.sourceType);
+  const isPromptSink = PROMPT_SINK_TYPES.has(finding.sink.sinkType);
+
+  // LLM output → prompt sink with LangChain message class wrapping → output packaging (info)
+  if (isLLMSource && isPromptSink && isOutputPackaging(finding)) {
+    return {
+      category: "ai_prompt_injection",
+      severity: "info",
+      note: `LLM output wrapped in message class (output packaging) at line ${finding.sink.line} — standard multi-turn conversation pattern.`,
+    };
+  }
+
+  // User input → prompt sink → ai_prompt_injection (with risk scoring)
+  if (kind === "prompt" && isPromptSink) {
+    // FP-49: Internal context builder — non-HTTP sources in prompt builder files
+    if (
+      !isHTTPSourceType(finding.source.sourceType) &&
+      isContextBuilderFile(finding.filePath)
+    ) {
+      return {
+        category: "ai_prompt_injection",
+        severity: "info",
+        note: `Internal context builder: non-HTTP source flows to prompt construction in ${finding.filePath.split("/").pop()} — internal data assembly, not user-facing injection vector.`,
+      };
+    }
+
+    const risk = assessPromptInjectionRisk(finding, content);
+    return {
+      category: risk.adjustedCategory,
+      severity: risk.adjustedSeverity,
+      note: risk.note,
+    };
+  }
+
+  // LLM output → execution sink → ai_unsafe_execution (with risk scoring)
+  if (isLLMSource && !isPromptSink) {
+    const risk = assessExecutionRisk(finding, content);
+    return {
+      category: risk.adjustedCategory,
+      severity: risk.adjustedSeverity,
+      note: risk.note,
+    };
+  }
+
+  // LLM output → prompt sink → indirect prompt injection (multi-agent attack vector)
+  if (isLLMSource && isPromptSink) {
+    const sourceDesc = finding.source.sourceType.replace(/_/g, " ");
+    return {
+      category: "ai_prompt_injection",
+      severity: "medium",
+      note: `Indirect prompt injection: ${sourceDesc} at line ${finding.source.line} flows into another model's prompt at line ${finding.sink.line}. An attacker who controls the first model's output can manipulate the second model via injected instructions.`,
+    };
+  }
+
+  // Standard taint flow (unchanged)
+  const sourceDesc = finding.source.sourceType.replace(/_/g, " ");
+  const sinkDesc = finding.sink.sinkType.replace(/_/g, " ");
+  const pathLen = finding.path.length;
+  const note = `User input from ${sourceDesc} at line ${finding.source.line} flows to ${sinkDesc} (${kind}) through ${pathLen} step${pathLen === 1 ? "" : "s"} without sanitization`;
+
+  return {
+    category: KIND_TO_CATEGORY[kind],
+    severity: KIND_TO_SEVERITY[kind],
+    note,
+  };
+}
+
+// ============================================================================
+// Guard Clause / Early-Return Suppression
+// ============================================================================
+
+/**
+ * Validation keywords in if-conditions that indicate input validation or auth checks.
+ * Presence of these + early return/throw between source and sink suppresses the finding.
+ */
+const GUARD_VALIDATION_RE =
+  /\.startsWith\(|\.startswith\(|\.includes\(|\.endsWith\(|\.endswith\(|\.indexOf\(|\.some\(|\.every\(|\.has\(|\bnot\s+in\b|\bin\s+(?:allowed|whitelist|allowlist)\b|!==\s*(?:\w*(?:userId|ownerId|user_id|owner_id))|(?:userId|ownerId|user_id|owner_id)\w*\s*!==|!\s*(?:args\.)?(?:approved|confirmed)|\.(?:approved|confirmed)\b|(?:allowed|whitelist|allowlist)\b/i;
+
+/**
+ * Check if there's a guard clause (validation + early exit) between/around
+ * a taint source and sink that would make the finding a false positive.
+ *
+ * Looks for: if (validation_pattern) { return | throw | raise }
+ * within a window around the source-to-sink range.
+ */
+function hasGuardClause(content: string, finding: TaintFinding): boolean {
+  const lines = content.split("\n");
+  const startLine = Math.max(
+    0,
+    Math.min(finding.source.line, finding.sink.line) - 5,
+  );
+  const endLine = Math.min(
+    lines.length,
+    Math.max(finding.source.line, finding.sink.line) + 6,
+  );
+
+  for (let i = startLine; i < endLine; i++) {
+    const line = lines[i];
+    // Match if-statement line containing a validation keyword
+    if (/^\s*if\s*[\(\s]/.test(line) && GUARD_VALIDATION_RE.test(line)) {
+      // Check same line and next 3 lines for early exit
+      for (let j = i; j < Math.min(lines.length, i + 4); j++) {
+        if (/\b(?:return|throw)\b/.test(lines[j])) return true;
+      }
+    }
+    // Python: if ... : \n    return/raise
+    if (
+      /^\s*if\s+/.test(line) &&
+      GUARD_VALIDATION_RE.test(line) &&
+      line.trimEnd().endsWith(":")
+    ) {
+      for (let j = i + 1; j < Math.min(lines.length, i + 3); j++) {
+        if (/^\s+(?:return|raise)\b/.test(lines[j])) return true;
+      }
+    }
+  }
+  return false;
+}
+
+// ============================================================================
+// Register One Rule Per TaintKind
+// ============================================================================
+
+const ALL_KINDS: TaintKind[] = [
+  "sql",
+  "xss",
+  "command",
+  "ssrf",
+  "prompt",
+  "path",
+];
+
+for (const kind of ALL_KINDS) {
+  registerASTRule({
+    id: `ast-taint-flow-${kind}`,
+    title: KIND_TO_TITLE[kind],
+    description: `User input flows to a ${kind}-vulnerable sink without proper sanitization`,
+    severity: KIND_TO_SEVERITY[kind],
+    category: KIND_TO_CATEGORY[kind],
+    suggestedFix:
+      "Sanitize or validate user input before passing it to security-sensitive functions.",
+    languages: ["javascript", "typescript", "tsx", "python"],
+    confidence: "high",
+    baseConfidence: 0.7,
+    requiresAIValidation: false,
+    layer: 2,
+    source: "structural",
+    detect(ast: ParsedAST, content: string): ASTRuleMatch[] {
+      if (isScannerOrFixtureFile(ast.filePath)) return [];
+      if (isTestOrMockFile(ast.filePath)) return [];
+
+      const findings = getFindings(ast);
+      const matches: ASTRuleMatch[] = [];
+      // Dedup: one finding per sink line per taint kind.
+      // Multiple sources to the same sink are suppressed to reduce noise.
+      const emittedSinks = new Set<number>();
+
+      for (const finding of findings) {
+        if (finding.matchingKinds.has(kind)) {
+          if (emittedSinks.has(finding.sink.line)) continue;
+
+          // Suppress findings where source and sink originate from the same LLM call.
+          // This happens when a function's return value is an llm_output source and
+          // one of its input parameters hits a prompt sink — not a real data flow.
+          // A path with only source→sink (2 steps) is trivially short, indicating
+          // a same-expression or same-call scenario rather than a real data flow.
+          const MAX_STEPS_SAME_CALL = 2;
+          if (
+            finding.source.line === finding.sink.line &&
+            finding.path.length <= MAX_STEPS_SAME_CALL &&
+            LLM_SOURCE_TYPES.has(finding.source.sourceType) &&
+            PROMPT_SINK_TYPES.has(finding.sink.sinkType)
+          ) {
+            continue;
+          }
+
+          // Suppress findings where source and sink originate from the same LLM call.
+          // This happens when a function's return value is an llm_output source and
+          // one of its input parameters hits a prompt sink — not a real data flow.
+          if (finding.source.line === finding.sink.line
+              && finding.path.length <= 2
+              && LLM_SOURCE_TYPES.has(finding.source.sourceType)
+              && PROMPT_SINK_TYPES.has(finding.sink.sinkType)) {
+            continue
+          }
+
+          // Suppress findings where a guard clause (validation + early exit)
+          // protects the sink from reaching tainted data
+          if (hasGuardClause(content, finding)) continue;
+
+          emittedSinks.add(finding.sink.line);
+
+          const resolved = getCategoryAndSeverity(finding, kind, content);
+          const fixSteps = getTaintFixSteps(
+            finding.source.sourceType,
+            finding.sink.sinkType,
+            kind,
+          );
+          matches.push({
+            node: finding.sink.node,
+            severity: resolved.severity,
+            note: resolved.note,
+            taintPath: serializeTaintPath(finding),
+            evidenceLevel: "proven",
+            fixSteps,
+            // Override category when LLM routing changes it
+            ...(resolved.category !== KIND_TO_CATEGORY[kind]
+              ? { category: resolved.category }
+              : {}),
+          });
+        }
+      }
+
+      return matches;
+    },
+  });
+}