@oculum/scanner 1.0.14 → 1.0.15

package/src/detect/ast-rules/variables-ast.ts

@@ -0,0 +1,446 @@
+/**
+ * AST-Based Sensitive Variable Detection
+ *
+ * Migrates structural/variables.ts from regex to AST.
+ * Detects variable declarations/assignments with sensitive names
+ * that have hardcoded string values.
+ *
+ * AST advantages over regex:
+ * - Understands declaration structure (skips type annotations, interfaces)
+ * - Resolves destructured assignments
+ * - Skips comments at the AST level (no regex heuristic)
+ * - Handles multi-line declarations
+ */
+
+import type { ParsedAST } from "../../parse/ast";
+import {
+  registerASTRule,
+  type ASTRuleMatch,
+  type NodeIndex,
+  getNodes,
+} from "./index";
+import type Parser from "tree-sitter";
+import { extractStringValue } from "./helpers/string-analysis";
+import { extractPythonStringValue } from "./helpers/python-helpers";
+import { isScannerOrFixtureFile } from "../../parse/file-classifier";
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function isInsideTypeDeclaration(node: Parser.SyntaxNode): boolean {
+  let current = node.parent;
+  while (current) {
+    if (
+      current.type === "type_alias_declaration" ||
+      current.type === "interface_declaration" ||
+      current.type === "type_annotation"
+    )
+      return true;
+    current = current.parent;
+  }
+  return false;
+}
+
+// ============================================================================
+// Sensitive Variable Patterns
+// ============================================================================
+
+interface SensitivePattern {
+  pattern: RegExp;
+  severity: "critical" | "high" | "medium" | "low" | "info";
+  description: string;
+}
+
+const SENSITIVE_PATTERNS: SensitivePattern[] = [
+  // Critical: admin/db/app secrets
+  {
+    pattern:
+      /^(user_?password|admin_?password|db_?password|database_?password)$/i,
+    severity: "critical",
+    description: "Variable name suggests database/admin password",
+  },
+  {
+    pattern: /^(client_?secret|app_?secret|jwt_?secret)$/i,
+    severity: "critical",
+    description: "Variable name suggests application secret",
+  },
+  {
+    pattern: /^(encryption_?key|decrypt_?key|cipher_?key|aes_?key)$/i,
+    severity: "critical",
+    description: "Variable name suggests encryption key",
+  },
+  {
+    pattern: /^(ssh_?key|private_?key|cert_?key|ssl_?key)$/i,
+    severity: "critical",
+    description: "Variable name suggests SSH/SSL key",
+  },
+  // High: passwords, tokens, secrets
+  {
+    pattern: /^(password|passwd|pwd|pass)$/i,
+    severity: "high",
+    description: "Variable name suggests password storage",
+  },
+  {
+    pattern: /^(auth_?token|access_?token|refresh_?token|bearer_?token)$/i,
+    severity: "high",
+    description: "Variable name suggests authentication token",
+  },
+  {
+    pattern: /^(api_?token|api_?key|apikey)$/i,
+    severity: "high",
+    description: "Variable name suggests API key/token",
+  },
+  {
+    pattern: /^(secret|secret_?key|private_?key|signing_?key)$/i,
+    severity: "high",
+    description: "Variable name suggests secret/private key",
+  },
+  {
+    pattern: /^(credential|credentials|creds)$/i,
+    severity: "high",
+    description: "Variable name suggests credentials",
+  },
+  {
+    pattern: /^(connection_?string|conn_?string|database_?url|db_?url)$/i,
+    severity: "high",
+    description: "Variable name suggests database connection string",
+  },
+];
+
+// ============================================================================
+// Value Safety Checks
+// ============================================================================
+
+function isPlaceholderOrEnvRef(valueNode: Parser.SyntaxNode): boolean {
+  const text = valueNode.text;
+
+  // process.env.X or env('X') (JS/TS)
+  if (text.includes("process.env") || /^env\(/.test(text)) return true;
+
+  // Python env references: os.environ, os.getenv(), config()
+  if (/os\.environ|os\.getenv\(|environ\.get\(|config\(/.test(text))
+    return true;
+
+  // Null/undefined/None
+  if (["null", "undefined", "None"].includes(text)) return true;
+
+  // String values that are placeholders
+  const strVal =
+    extractStringValue(valueNode) ?? extractPythonStringValue(valueNode);
+  if (!strVal) return false;
+  if (strVal.length <= 3) return true; // too short to be a real secret
+
+  const placeholders = [
+    /^xxx+$/i,
+    /^yyy+$/i,
+    /^your[-_]/i,
+    /^my[-_]/i,
+    /^test[-_]/i,
+    /^sample[-_]/i,
+    /^example[-_]/i,
+    /^demo[-_]/i,
+    /^placeholder/i,
+    /^<.*>$/,
+    /^\[.*\]$/,
+    /^\{.*\}$/,
+    /^TODO/i,
+    /^CHANGEME/i,
+    /^REPLACE/i,
+    /^\*+$/,
+  ];
+
+  return placeholders.some((p) => p.test(strVal));
+}
+
+function isTestVariableName(name: string): boolean {
+  const testKeywords =
+    /^(TEST|MOCK|EXAMPLE|DUMMY|FAKE|SAMPLE|PLACEHOLDER|DEMO)[_A-Z0-9]*$/i;
+  const testSuffixes = /_?(TEST|MOCK|EXAMPLE|DUMMY|FAKE|SAMPLE)$/i;
+  return testKeywords.test(name) || testSuffixes.test(name);
+}
+
+/**
+ * Known safe values for sensitive-named keys that are NOT actual secrets.
+ * e.g. fetch API `credentials: 'include'`, express session `secret: 'keyboard cat'`
+ */
+const KNOWN_SAFE_VALUES: Record<string, Set<string>> = {
+  credentials: new Set(["include", "same-origin", "omit"]),
+  creds: new Set(["include", "same-origin", "omit"]),
+};
+
+function isKnownSafeValue(
+  keyName: string,
+  valueNode: Parser.SyntaxNode,
+): boolean {
+  const safeValues = KNOWN_SAFE_VALUES[keyName.toLowerCase()];
+  if (!safeValues) return false;
+  const val = extractStringValue(valueNode);
+  return val !== null && safeValues.has(val);
+}
+
+function hasHardcodedStringValue(valueNode: Parser.SyntaxNode): boolean {
+  // Direct string literal with non-trivial content
+  if (valueNode.type === "string" || valueNode.type === "template_string") {
+    const val =
+      extractStringValue(valueNode) ?? extractPythonStringValue(valueNode);
+    return val !== null && val.length > 3;
+  }
+  return false;
+}
+
+/**
+ * Unified value classifier: returns true if the value is NOT an actual secret.
+ * Covers: empty strings, template expressions, env var refs, UPPER_SNAKE_CASE names,
+ * known placeholders, permission scope identifiers, and template literals with
+ * runtime interpolations.
+ */
+export function isNotActualSecretValue(
+  value: string,
+  valueNode: Parser.SyntaxNode,
+  options?: { highSensitivity?: boolean },
+): boolean {
+  // 1. Empty string
+  if (value === "") return true;
+
+  // 2. Template expression (n8n ={{...}} or Jinja/Handlebars/Mustache {{...}})
+  if (/^={{.*}}$/.test(value) || /^\{\{.*\}\}$/.test(value)) return true;
+
+  // 3. Template literal with runtime interpolations (non-literal expressions)
+  if (valueNode.type === "template_string") {
+    const subs = valueNode.descendantsOfType("template_substitution");
+    if (subs.length > 0) {
+      const hasRuntimeExpr = subs.some((sub) => {
+        const expr = sub.namedChildren[0];
+        if (!expr) return false;
+        // If the interpolated expression is just a string literal, it's still static
+        return expr.type !== "string" && expr.type !== "number";
+      });
+      if (hasRuntimeExpr) return true;
+    }
+  }
+
+  // 4. Environment variable reference in the value text
+  if (
+    /process\.env|os\.environ|env\(['"]|getEnvironmentVariable|Deno\.env|import\.meta\.env/i.test(
+      value,
+    )
+  )
+    return true;
+
+  // 5. UPPER_SNAKE_CASE identifier (env var NAME being mapped, not the value)
+  if (/^[A-Z][A-Z0-9_]{3,}$/.test(value)) return true;
+
+  // 6. Known placeholder values (extended)
+  if (
+    /^(test|fake|dummy|placeholder|example|sample|demo|todo|changeme|replace|xxx+|yyy+|not-needed|avoid-error|none|N\/A)$/i.test(
+      value,
+    )
+  )
+    return true;
+
+  // 7. Permission scope format (resource:action like "apikeys:import")
+  if (/^[a-z][a-z0-9_-]*:[a-z][a-z0-9_:-]*$/i.test(value) && value.length < 50)
+    return true;
+
+  // 8. Simple lowercase identifier (common word, not high entropy)
+  // Single word that looks like a field name or store name
+  // Skip this filter for high-sensitivity patterns (secret_key, password, api_key, auth_token)
+  // because values like 'random' or 'super_secret' ARE real secrets for those patterns
+  if (!options?.highSensitivity) {
+    if (/^[a-z][a-z0-9_]{0,15}$/.test(value) && !/[0-9]{3,}/.test(value))
+      return true;
+  }
+
+  return false;
+}
+
+// ============================================================================
+// High-sensitivity patterns (skip lenient value filters for these)
+// ============================================================================
+
+const HIGH_SENSITIVITY_NAMES =
+  /^(secret_?key|password|passwd|api_?key|auth_?token|private_?key)$/i;
+
+function isHighSensitivityPattern(varName: string): boolean {
+  return HIGH_SENSITIVITY_NAMES.test(varName);
+}
+
+/**
+ * Shared matching logic for a variable name + value pair.
+ * Returns an ASTRuleMatch or null.
+ */
+function matchSensitiveVariable(
+  varName: string,
+  valueNode: Parser.SyntaxNode,
+  reportNode: Parser.SyntaxNode,
+  isPython: boolean,
+): ASTRuleMatch | null {
+  if (isTestVariableName(varName)) return null;
+  if (isKnownSafeValue(varName, valueNode)) return null;
+
+  for (const pattern of SENSITIVE_PATTERNS) {
+    if (!pattern.pattern.test(varName)) continue;
+
+    if (!hasHardcodedStringValue(valueNode)) return null;
+    if (isPlaceholderOrEnvRef(valueNode)) return null;
+
+    const strVal = isPython
+      ? (extractPythonStringValue(valueNode) ?? extractStringValue(valueNode))
+      : extractStringValue(valueNode);
+
+    const highSensitivity = isHighSensitivityPattern(varName);
+    if (
+      strVal !== null &&
+      isNotActualSecretValue(strVal, valueNode, { highSensitivity })
+    )
+      return null;
+
+    // Disambiguate 'pass': only flag when value looks like a credential
+    if (varName.toLowerCase() === "pass") {
+      if (strVal && /={{|true|false|startsWith|endsWith|filter/i.test(strVal))
+        return null;
+    }
+
+    return {
+      node: reportNode,
+      severity: pattern.severity,
+      note:
+        pattern.description +
+        ". The value appears to be hardcoded rather than loaded from environment.",
+    };
+  }
+  return null;
+}
+
+// ============================================================================
+// AST Rule: Sensitive Variables
+// ============================================================================
+
+registerASTRule({
+  id: "ast-sensitive-variable",
+  title: "Sensitive variable with hardcoded value",
+  description:
+    "Variable with a sensitive name has a hardcoded value instead of being loaded from environment",
+  severity: "high",
+  category: "sensitive_variable",
+  suggestedFix:
+    "Move this sensitive value to an environment variable or secure secrets manager.",
+  languages: ["javascript", "typescript", "tsx", "python"],
+  confidence: "medium",
+  baseConfidence: 0.2,
+  layer: 2,
+  source: "structural",
+  detect(
+    ast: ParsedAST,
+    content: string,
+    nodeIndex?: NodeIndex,
+  ): ASTRuleMatch[] {
+    if (isScannerOrFixtureFile(ast.filePath)) return [];
+
+    const matches: ASTRuleMatch[] = [];
+    const isPython = ast.language === "python";
+
+    // Python uses 'assignment' and 'pair' (in dicts); JS/TS uses 'variable_declarator', 'pair', 'assignment_expression'
+    const nodeTypes = isPython
+      ? ["assignment", "pair"]
+      : ["variable_declarator", "pair", "assignment_expression"];
+
+    for (const node of getNodes(nodeIndex!, ...nodeTypes)) {
+      if (!isPython && isInsideTypeDeclaration(node)) continue;
+
+      // JS/TS: Variable declarators: const password = "secret"
+      if (node.type === "variable_declarator") {
+        const nameNode = node.childForFieldName("name");
+        const valueNode = node.childForFieldName("value");
+        if (!nameNode || !valueNode) continue;
+        if (nameNode.type !== "identifier") continue;
+
+        const m = matchSensitiveVariable(
+          nameNode.text,
+          valueNode,
+          nameNode,
+          false,
+        );
+        if (m) matches.push(m);
+        continue;
+      }
+
+      // Object/dict property: { password: "secret" } or {"SECRET_KEY": "value"}
+      if (node.type === "pair") {
+        const keyNode = node.childForFieldName("key");
+        const valueNode = node.childForFieldName("value");
+        if (!keyNode || !valueNode) continue;
+
+        // Get key text (strip quotes for string keys)
+        let keyText = keyNode.text;
+        if (keyNode.type === "string") {
+          keyText =
+            (isPython
+              ? extractPythonStringValue(keyNode)
+              : extractStringValue(keyNode)) ?? keyText;
+        }
+
+        const m = matchSensitiveVariable(keyText, valueNode, keyNode, isPython);
+        if (m) matches.push(m);
+        continue;
+      }
+
+      // JS/TS: Assignment expression: password = "secret"
+      if (node.type === "assignment_expression") {
+        const left = node.childForFieldName("left");
+        const right = node.childForFieldName("right");
+        if (!left || !right) continue;
+
+        const varName =
+          left.type === "identifier"
+            ? left.text
+            : left.type === "member_expression"
+              ? (left.childForFieldName("property")?.text ?? "")
+              : "";
+
+        if (!varName) continue;
+
+        const m = matchSensitiveVariable(varName, right, left, false);
+        if (m) matches.push(m);
+        continue;
+      }
+
+      // Python: assignment — password = "secret", app.secret_key = "value", app.config['SECRET_KEY'] = "value"
+      if (node.type === "assignment") {
+        const left = node.childForFieldName("left");
+        const right = node.childForFieldName("right");
+        if (!left || !right) continue;
+
+        let varName = "";
+
+        // Simple identifier: SECRET_KEY = 'value'
+        if (left.type === "identifier") {
+          varName = left.text;
+        }
+        // Attribute: app.secret_key = 'value'
+        else if (left.type === "attribute") {
+          varName = left.childForFieldName("attribute")?.text ?? "";
+        }
+        // Subscript: app.config['SECRET_KEY'] = 'value'
+        else if (left.type === "subscript") {
+          const subscripts = left.namedChildren.filter(
+            (c) => c.type === "string",
+          );
+          if (subscripts.length > 0) {
+            varName =
+              extractPythonStringValue(subscripts[0]) ?? subscripts[0].text;
+          }
+        }
+
+        if (!varName) continue;
+
+        const m = matchSensitiveVariable(varName, right, left, true);
+        if (m) matches.push(m);
+        continue;
+      }
+    }
+
+    return matches;
+  },
+});