@oculum/scanner 1.0.14 → 1.0.15

package/src/detect/ast-rules/helpers/python-helpers.ts

@@ -0,0 +1,1054 @@
+/**
+ * Python AST Analysis Helpers
+ *
+ * Python-specific equivalents of JS/TS helpers.
+ * Kept separate because Python AST nodes are structurally different
+ * (different node types, field names, scoping rules).
+ *
+ * Node type mapping (JS → Python):
+ *   call_expression → call
+ *   member_expression → attribute
+ *   import_statement → import_statement / import_from_statement
+ *   statement_block → block
+ *   catch_clause → except_clause
+ *   string (with backticks) → string (with f-prefix for f-strings)
+ *   template_substitution → interpolation
+ */
+
+import type Parser from "tree-sitter";
+import { walkAST } from "../../../parse/ast";
+
+// Cache import bindings per root node to avoid redundant AST traversals
+// when hasPythonImport / getPythonImportedModules / isPythonImportedFrom
+// are called in sequence by the same rule.
+const importBindingsCache = new WeakMap<
+  Parser.SyntaxNode,
+  Map<string, { module: string; originalName: string }>
+>();
+
+// Re-use the ResolvedCallTarget shape from call-analysis
+export interface PythonResolvedCallTarget {
+  /** 'direct' = fn(), 'member' = obj.fn() */
+  type: "direct" | "member";
+  /** The function/method name being called */
+  name: string;
+  /** For member calls, the object expression text */
+  object?: string;
+  /** Full chain: 'a.b.c' */
+  fullChain: string;
+  /** Whether resolved via alias */
+  aliased: boolean;
+}
+
+export interface PythonVariableBinding {
+  name: string;
+  node: Parser.SyntaxNode;
+  initValue: Parser.SyntaxNode | null;
+  kind: "assignment" | "annotated" | "parameter" | "for" | "with" | "except";
+}
+
+// ============================================================================
+// Import Analysis
+// ============================================================================
+
+/**
+ * Collect all import bindings from a Python file.
+ *
+ * Handles:
+ *   import os                     → { 'os': { module: 'os', originalName: 'default' } }
+ *   import os.path                → { 'os': { module: 'os.path', originalName: 'default' } }
+ *   from os import path           → { 'path': { module: 'os', originalName: 'path' } }
+ *   from os.path import join      → { 'join': { module: 'os.path', originalName: 'join' } }
+ *   from os import path as p     → { 'p': { module: 'os', originalName: 'path' } }
+ *   from . import utils           → { 'utils': { module: '.', originalName: 'utils' } }
+ */
+export function collectPythonImportBindings(
+  root: Parser.SyntaxNode,
+): Map<string, { module: string; originalName: string }> {
+  const cached = importBindingsCache.get(root);
+  if (cached) return cached;
+
+  const bindings = new Map<string, { module: string; originalName: string }>();
+
+  walkAST(root, (node) => {
+    // import os / import os.path
+    if (node.type === "import_statement") {
+      for (const child of node.namedChildren) {
+        if (child.type === "dotted_name") {
+          const fullModule = child.text;
+          // Local name is the first identifier (import os.path → local name 'os')
+          const firstIdent = child.namedChildren[0];
+          if (firstIdent) {
+            bindings.set(firstIdent.text, {
+              module: fullModule,
+              originalName: "default",
+            });
+          }
+        }
+        if (child.type === "aliased_import") {
+          const dottedName = child.namedChildren.find(
+            (c) => c.type === "dotted_name",
+          );
+          const alias = child.namedChildren.find(
+            (c) => c.type === "identifier",
+          );
+          if (dottedName && alias) {
+            bindings.set(alias.text, {
+              module: dottedName.text,
+              originalName: "default",
+            });
+          }
+        }
+      }
+      return true;
+    }
+
+    // from X import Y
+    if (node.type === "import_from_statement") {
+      // Resolve module name
+      let moduleName = "";
+      const relImport = node.namedChildren.find(
+        (c) => c.type === "relative_import",
+      );
+      if (relImport) {
+        // from .foo import bar / from ..package.sub import x
+        const prefix = relImport.descendantsOfType("import_prefix")[0];
+        const submodule = relImport.descendantsOfType("dotted_name")[0];
+        moduleName = (prefix?.text ?? ".") + (submodule ? submodule.text : "");
+      } else {
+        // from os.path import join
+        const modNode = node.namedChildren.find(
+          (c) => c.type === "dotted_name",
+        );
+        moduleName = modNode?.text ?? "";
+      }
+
+      // Collect imported names (skip the module dotted_name — it's the first one)
+      let skippedModule = false;
+      for (const child of node.namedChildren) {
+        // Skip the module name (first dotted_name or relative_import)
+        if (
+          !skippedModule &&
+          (child.type === "dotted_name" || child.type === "relative_import")
+        ) {
+          skippedModule = true;
+          continue;
+        }
+
+        if (child.type === "dotted_name") {
+          // from X import name
+          bindings.set(child.text, {
+            module: moduleName,
+            originalName: child.text,
+          });
+        }
+
+        if (child.type === "aliased_import") {
+          // from X import name as alias
+          const dottedName = child.namedChildren.find(
+            (c) => c.type === "dotted_name",
+          );
+          const alias = child.namedChildren.find(
+            (c) => c.type === "identifier",
+          );
+          if (dottedName && alias) {
+            bindings.set(alias.text, {
+              module: moduleName,
+              originalName: dottedName.text,
+            });
+          }
+        }
+      }
+      return true;
+    }
+
+    return false;
+  });
+
+  importBindingsCache.set(root, bindings);
+  return bindings;
+}
+
+/**
+ * Quick check: does the Python file import `name` from `module`?
+ */
+export function hasPythonImport(
+  root: Parser.SyntaxNode,
+  module: string | RegExp,
+  name?: string,
+): boolean {
+  const bindings = collectPythonImportBindings(root);
+
+  for (const [local, binding] of bindings) {
+    const moduleMatch =
+      typeof module === "string"
+        ? binding.module === module
+        : module.test(binding.module);
+    if (!moduleMatch) continue;
+    if (!name) return true;
+    if (binding.originalName === name || local === name) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Get all imported module names (unique set).
+ */
+export function getPythonImportedModules(root: Parser.SyntaxNode): Set<string> {
+  const modules = new Set<string>();
+  const bindings = collectPythonImportBindings(root);
+  for (const binding of bindings.values()) {
+    modules.add(binding.module);
+  }
+  return modules;
+}
+
+/**
+ * Check if a local name was imported from a module matching a pattern.
+ */
+export function isPythonImportedFrom(
+  root: Parser.SyntaxNode,
+  localName: string,
+  modulePattern: string | RegExp,
+): string | null {
+  const bindings = collectPythonImportBindings(root);
+  const binding = bindings.get(localName);
+  if (!binding) return null;
+
+  if (typeof modulePattern === "string") {
+    return binding.module === modulePattern ? binding.module : null;
+  }
+  return modulePattern.test(binding.module) ? binding.module : null;
+}
+
+// ============================================================================
+// Call Analysis
+// ============================================================================
+
+/**
+ * Resolve the target of a Python `call` node.
+ * Python uses 'call' (not 'call_expression') and 'attribute' (not 'member_expression').
+ */
+export function resolvePythonCallTarget(
+  node: Parser.SyntaxNode,
+  aliases?: Map<string, string>,
+): PythonResolvedCallTarget | null {
+  if (node.type !== "call") return null;
+
+  const fn = node.childForFieldName("function");
+  if (!fn) return null;
+
+  // Direct call: print(...)
+  if (fn.type === "identifier") {
+    const aliasTarget = aliases?.get(fn.text);
+    if (aliasTarget) {
+      const parts = aliasTarget.split(".");
+      return {
+        type: parts.length > 1 ? "member" : "direct",
+        name: parts[parts.length - 1],
+        object: parts.length > 1 ? parts.slice(0, -1).join(".") : undefined,
+        fullChain: aliasTarget,
+        aliased: true,
+      };
+    }
+    return {
+      type: "direct",
+      name: fn.text,
+      fullChain: fn.text,
+      aliased: false,
+    };
+  }
+
+  // Member call: obj.method(...) / obj.a.b.method(...)
+  if (fn.type === "attribute") {
+    const attr = fn.childForFieldName("attribute");
+    const obj = fn.childForFieldName("object");
+    if (!attr) return null;
+
+    return {
+      type: "member",
+      name: attr.text,
+      object: obj?.text,
+      fullChain: fn.text,
+      aliased: false,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Check if a `call` node calls a specific function name.
+ * Handles both direct calls and attribute (member) calls.
+ */
+export function isPythonCallTo(node: Parser.SyntaxNode, name: string): boolean {
+  if (node.type !== "call") return false;
+  const fn = node.childForFieldName("function");
+  if (!fn) return false;
+
+  // Direct: name(...)
+  if (fn.type === "identifier" && fn.text === name) return true;
+
+  // Member: obj.name(...)
+  if (fn.type === "attribute") {
+    const attr = fn.childForFieldName("attribute");
+    if (attr?.text === name) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Get positional arguments from a Python call node.
+ * Excludes keyword_argument, list_splat, and dictionary_splat.
+ */
+export function getPythonCallArguments(
+  node: Parser.SyntaxNode,
+): Parser.SyntaxNode[] {
+  if (node.type !== "call") return [];
+  const argList = node.childForFieldName("arguments");
+  if (!argList) return [];
+  return argList.namedChildren.filter(
+    (c) =>
+      c.type !== "keyword_argument" &&
+      c.type !== "list_splat" &&
+      c.type !== "dictionary_splat",
+  );
+}
+
+/**
+ * Get the Nth positional argument (0-indexed).
+ */
+export function getPythonCallArgument(
+  node: Parser.SyntaxNode,
+  index: number,
+): Parser.SyntaxNode | null {
+  const args = getPythonCallArguments(node);
+  return args[index] ?? null;
+}
+
+/**
+ * Extract a keyword argument value from a Python call.
+ * e.g., foo(model='gpt-4') → getPythonKeywordArgument(node, 'model') → string node
+ */
+export function getPythonKeywordArgument(
+  node: Parser.SyntaxNode,
+  keyword: string,
+): Parser.SyntaxNode | null {
+  if (node.type !== "call") return null;
+  const argList = node.childForFieldName("arguments");
+  if (!argList) return null;
+
+  for (const child of argList.namedChildren) {
+    if (child.type === "keyword_argument") {
+      const nameNode = child.childForFieldName("name");
+      if (nameNode?.text === keyword) {
+        return child.childForFieldName("value") ?? null;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Check if a call matches `obj.method(...)` pattern.
+ */
+export function isPythonMethodCallOn(
+  node: Parser.SyntaxNode,
+  objectPattern: string | RegExp,
+  methodName: string | string[],
+): boolean {
+  if (node.type !== "call") return false;
+  const fn = node.childForFieldName("function");
+  if (!fn || fn.type !== "attribute") return false;
+
+  const attr = fn.childForFieldName("attribute");
+  const obj = fn.childForFieldName("object");
+  if (!attr || !obj) return false;
+
+  const methods = Array.isArray(methodName) ? methodName : [methodName];
+  if (!methods.includes(attr.text)) return false;
+
+  if (typeof objectPattern === "string") {
+    return obj.text === objectPattern;
+  }
+  return objectPattern.test(obj.text);
+}
+
+/**
+ * Extract the full attribute chain from nested attribute nodes.
+ * e.g., `a.b.c.d` → ['a', 'b', 'c', 'd']
+ */
+export function getPythonAttributeChain(node: Parser.SyntaxNode): string[] {
+  const chain: string[] = [];
+
+  function walk(n: Parser.SyntaxNode): void {
+    if (n.type === "attribute") {
+      const obj = n.childForFieldName("object");
+      const attr = n.childForFieldName("attribute");
+      if (obj) walk(obj);
+      if (attr) chain.push(attr.text);
+    } else if (n.type === "identifier") {
+      chain.push(n.text);
+    }
+  }
+
+  walk(node);
+  return chain;
+}
+
+// ============================================================================
+// Scope & Variable Analysis
+// ============================================================================
+
+/**
+ * Collect variable declarations/assignments in a Python file.
+ *
+ * Handles:
+ *   x = 1                (assignment)
+ *   x: int = 2           (annotated assignment)
+ *   def foo(x, y=1)      (parameters)
+ *   for x in items       (for variable)
+ *   with open(f) as fh   (with variable)
+ *   except E as e        (except variable)
+ */
+export function collectPythonVariableDeclarations(
+  root: Parser.SyntaxNode,
+): Map<string, PythonVariableBinding> {
+  const bindings = new Map<string, PythonVariableBinding>();
+
+  walkAST(root, (node) => {
+    // x = 1 / x: int = 2
+    // TODO: Handle tuple unpacking (a, b = func()) — left side is pattern_list/expression_list
+    if (node.type === "assignment") {
+      const left = node.childForFieldName("left");
+      const right = node.childForFieldName("right");
+      const typeNode = node.childForFieldName("type");
+      if (left?.type === "identifier") {
+        bindings.set(left.text, {
+          name: left.text,
+          node,
+          initValue: right ?? null,
+          kind: typeNode ? "annotated" : "assignment",
+        });
+      }
+    }
+
+    // Function parameters
+    if (node.type === "parameters") {
+      const PARAM_TYPES_WITH_IDENT = [
+        "default_parameter",
+        "typed_parameter",
+        "list_splat_pattern",
+        "dictionary_splat_pattern",
+      ];
+      for (const child of node.namedChildren) {
+        if (child.type === "identifier") {
+          bindings.set(child.text, {
+            name: child.text,
+            node: child,
+            initValue: null,
+            kind: "parameter",
+          });
+        } else if (PARAM_TYPES_WITH_IDENT.includes(child.type)) {
+          const nameNode = child.namedChildren.find(
+            (c) => c.type === "identifier",
+          );
+          if (nameNode) {
+            bindings.set(nameNode.text, {
+              name: nameNode.text,
+              node: child,
+              initValue:
+                child.type === "default_parameter"
+                  ? (child.childForFieldName("value") ?? null)
+                  : null,
+              kind: "parameter",
+            });
+          }
+        }
+      }
+    }
+
+    // for x in items
+    if (node.type === "for_statement") {
+      const left = node.childForFieldName("left");
+      if (left?.type === "identifier") {
+        bindings.set(left.text, {
+          name: left.text,
+          node,
+          initValue: null,
+          kind: "for",
+        });
+      }
+    }
+
+    // with open(f) as fh / except Exception as e
+    if (node.type === "as_pattern") {
+      const kind: PythonVariableBinding["kind"] | null =
+        node.parent?.type === "with_item"
+          ? "with"
+          : node.parent?.type === "except_clause"
+            ? "except"
+            : null;
+      if (kind) {
+        const target = node.namedChildren.find(
+          (c) => c.type === "as_pattern_target",
+        );
+        const ident = target?.namedChildren.find(
+          (c) => c.type === "identifier",
+        );
+        if (ident) {
+          bindings.set(ident.text, {
+            name: ident.text,
+            node,
+            initValue: null,
+            kind,
+          });
+        }
+      }
+    }
+
+    return false;
+  });
+
+  return bindings;
+}
+
+/**
+ * Build alias map: tracks `e = eval` style variable aliases.
+ * Only tracks simple identifier-to-identifier or identifier-to-attribute assignments.
+ */
+export function collectPythonVariableAliases(
+  root: Parser.SyntaxNode,
+): Map<string, string> {
+  const aliases = new Map<string, string>();
+
+  walkAST(root, (node) => {
+    if (node.type === "assignment") {
+      const left = node.childForFieldName("left");
+      const right = node.childForFieldName("right");
+      if (left?.type === "identifier" && right) {
+        if (right.type === "identifier" || right.type === "attribute") {
+          aliases.set(left.text, right.text);
+        }
+      }
+    }
+    return false;
+  });
+
+  return aliases;
+}
+
+/**
+ * Resolve a Python variable identifier to its assigned value node.
+ * Walks backward from the reference to find the most recent assignment
+ * where the left side matches the identifier name.
+ *
+ * Example: resolves `user_query` in `execute(text(user_query))` to the
+ * value node of `user_query = f"SELECT * FROM users WHERE username = '{username}'"`
+ */
+export function resolvePythonVariableDefinition(
+  fromNode: Parser.SyntaxNode,
+  name: string,
+): Parser.SyntaxNode | null {
+  // Walk the enclosing function or module to find assignments
+  let searchRoot: Parser.SyntaxNode = fromNode.tree.rootNode;
+  let current: Parser.SyntaxNode | null = fromNode.parent;
+  while (current) {
+    if (current.type === "function_definition" || current.type === "module") {
+      searchRoot = current;
+      break;
+    }
+    current = current.parent;
+  }
+
+  let lastAssignment: Parser.SyntaxNode | null = null;
+  walkAST(searchRoot, (node) => {
+    if (
+      node.type === "assignment" &&
+      node.startPosition.row < fromNode.startPosition.row
+    ) {
+      const left = node.childForFieldName("left");
+      const right = node.childForFieldName("right");
+      if (left?.type === "identifier" && left.text === name && right) {
+        lastAssignment = right;
+      }
+    }
+    return false;
+  });
+
+  return lastAssignment;
+}
+
+// ============================================================================
+// String Analysis
+// ============================================================================
+
+/**
+ * Extract the string value from a Python string node.
+ * Handles single, double, triple-quoted strings.
+ * Returns the content text (without quotes/prefix).
+ */
+export function extractPythonStringValue(
+  node: Parser.SyntaxNode,
+): string | null {
+  if (node.type !== "string") return null;
+
+  // Collect string_content children and join them
+  const parts: string[] = [];
+  for (const child of node.namedChildren) {
+    if (child.type === "string_content") {
+      parts.push(child.text);
+    }
+  }
+
+  if (parts.length > 0) return parts.join("");
+
+  // Fallback: strip quotes manually
+  const text = node.text;
+  // Triple-quoted
+  for (const prefix of [
+    '"""',
+    "'''",
+    'f"""',
+    "f'''",
+    'b"""',
+    "b'''",
+    'r"""',
+    "r'''",
+  ]) {
+    if (text.startsWith(prefix)) {
+      const suffix = prefix.slice(-3);
+      if (text.endsWith(suffix)) {
+        return text.slice(prefix.length, -suffix.length);
+      }
+    }
+  }
+  // Single-quoted
+  for (const prefix of ['"', "'", 'f"', "f'", 'b"', "b'", 'r"', "r'"]) {
+    if (text.startsWith(prefix)) {
+      const quote = prefix.slice(-1);
+      if (text.endsWith(quote)) {
+        return text.slice(prefix.length, -1);
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get the first positional string argument from a Python call.
+ */
+export function getPythonFirstStringArg(
+  callNode: Parser.SyntaxNode,
+): string | null {
+  const firstArg = getPythonCallArgument(callNode, 0);
+  if (!firstArg) return null;
+  return extractPythonStringValue(firstArg);
+}
+
+/**
+ * Check if a Python string node is an f-string.
+ * In tree-sitter-python, f-strings are `string` nodes whose string_start begins with 'f' or 'F'.
+ */
+export function isPythonFString(node: Parser.SyntaxNode): boolean {
+  if (node.type !== "string") return false;
+  const start = node.children.find((c) => c.type === "string_start");
+  if (!start) return false;
+  return start.text.startsWith("f") || start.text.startsWith("F");
+}
+
+/**
+ * Get the static and dynamic parts of an f-string.
+ */
+export function getPythonFStringParts(node: Parser.SyntaxNode): {
+  staticParts: string[];
+  dynamicParts: Parser.SyntaxNode[];
+} {
+  const staticParts: string[] = [];
+  const dynamicParts: Parser.SyntaxNode[] = [];
+
+  if (node.type !== "string") return { staticParts, dynamicParts };
+
+  for (const child of node.namedChildren) {
+    if (child.type === "string_content") {
+      staticParts.push(child.text);
+    } else if (child.type === "interpolation") {
+      dynamicParts.push(child);
+    }
+  }
+
+  return { staticParts, dynamicParts };
+}
+
+// ============================================================================
+// Control Flow
+// ============================================================================
+
+/**
+ * Check if a node is inside a Python try block (not except/finally).
+ */
+export function isInsidePythonTryExcept(node: Parser.SyntaxNode): boolean {
+  let current: Parser.SyntaxNode | null = node.parent;
+  while (current) {
+    if (current.type === "try_statement") {
+      // Verify node is in the try body, not except/finally
+      const tryBody = current.childForFieldName("body");
+      if (tryBody && isDescendantOf(node, tryBody)) return true;
+    }
+    current = current.parent;
+  }
+  return false;
+}
+
+/**
+ * Check if a node is inside an except clause.
+ */
+export function isInsidePythonExceptClause(node: Parser.SyntaxNode): boolean {
+  let current: Parser.SyntaxNode | null = node.parent;
+  while (current) {
+    if (current.type === "except_clause") return true;
+    current = current.parent;
+  }
+  return false;
+}
+
+/**
+ * Get the nearest enclosing Python block node.
+ */
+export function getEnclosingPythonBlock(
+  node: Parser.SyntaxNode,
+): Parser.SyntaxNode | null {
+  let current: Parser.SyntaxNode | null = node.parent;
+  while (current) {
+    if (current.type === "block") return current;
+    current = current.parent;
+  }
+  return null;
+}
+
+// ============================================================================
+// Decorator Detection
+// ============================================================================
+
+/**
+ * Get decorator names for a function_definition or class_definition.
+ * Looks at the parent decorated_definition node for decorator children.
+ *
+ * @app.route('/api') → 'app.route'
+ * @login_required → 'login_required'
+ * @staticmethod → 'staticmethod'
+ */
+export function getPythonDecorators(node: Parser.SyntaxNode): string[] {
+  // The decorated_definition wraps decorators + the actual definition
+  const parent = node.parent;
+  if (parent?.type !== "decorated_definition") return [];
+
+  const decorators: string[] = [];
+  for (const child of parent.namedChildren) {
+    if (child.type !== "decorator") continue;
+
+    // Decorator can contain an identifier or a call
+    for (const dChild of child.namedChildren) {
+      if (dChild.type === "identifier") {
+        decorators.push(dChild.text);
+      } else if (dChild.type === "call") {
+        const fn = dChild.childForFieldName("function");
+        if (fn) decorators.push(fn.text);
+      } else if (dChild.type === "attribute") {
+        decorators.push(dChild.text);
+      }
+    }
+  }
+
+  return decorators;
+}
+
+/**
+ * Check if a function_definition has a specific decorator (exact or regex).
+ */
+export function hasPythonDecorator(
+  node: Parser.SyntaxNode,
+  pattern: string | RegExp,
+): boolean {
+  const decorators = getPythonDecorators(node);
+  for (const dec of decorators) {
+    if (typeof pattern === "string") {
+      if (dec === pattern) return true;
+    } else {
+      if (pattern.test(dec)) return true;
+    }
+  }
+  return false;
+}
+
+// ============================================================================
+// User Input Detection (Python)
+// ============================================================================
+
+/** Known Python user input attribute paths */
+const PYTHON_USER_INPUT_PATTERNS: Array<{
+  object: RegExp;
+  property: string | RegExp;
+}> = [
+  // Flask (including common aliases like flask_request, http_request)
+  { object: /^(?:flask_)?request$/, property: "form" },
+  { object: /^(?:flask_)?request$/, property: "args" },
+  { object: /^(?:flask_)?request$/, property: "json" },
+  { object: /^(?:flask_)?request$/, property: "data" },
+  { object: /^(?:flask_)?request$/, property: "files" },
+  { object: /^(?:flask_)?request$/, property: "values" },
+  { object: /^(?:flask_)?request$/, property: "cookies" },
+  { object: /^(?:flask_)?request$/, property: "headers" },
+  // Django (including common aliases like django_request, http_request)
+  { object: /^(?:django_|http_)?request$/, property: "GET" },
+  { object: /^(?:django_|http_)?request$/, property: "POST" },
+  { object: /^(?:django_|http_)?request$/, property: "body" },
+  { object: /^(?:django_|http_)?request$/, property: "FILES" },
+  { object: /^(?:django_|http_)?request$/, property: "data" },
+  // General
+  { object: /^sys$/, property: "argv" },
+  { object: /^os$/, property: "environ" },
+];
+
+/**
+ * Check if a Python node accesses user input.
+ *
+ * Handles:
+ *   request.form, request.args, request.json, request.data, request.GET, etc.
+ *   sys.argv, os.environ
+ *   request.form['key'], request.args.get('key')
+ *   input()
+ */
+export function isPythonUserInputExpression(node: Parser.SyntaxNode): boolean {
+  // input() builtin
+  if (node.type === "call") {
+    const fn = node.childForFieldName("function");
+    if (fn?.type === "identifier" && fn.text === "input") return true;
+    // request.get_json()
+    if (fn?.type === "attribute") {
+      const obj = fn.childForFieldName("object");
+      const attr = fn.childForFieldName("attribute");
+      if (
+        /^(?:flask_|http_)?request$/.test(obj?.text ?? "") &&
+        attr?.text === "get_json"
+      )
+        return true;
+      // Method call on user input source: request.form.get('key'), request.args.get('q')
+      if (obj && isPythonUserInputExpression(obj)) return true;
+    }
+  }
+
+  // attribute access: request.form, sys.argv, etc.
+  if (node.type === "attribute") {
+    const obj = node.childForFieldName("object");
+    const attr = node.childForFieldName("attribute");
+    if (obj && attr) {
+      for (const pattern of PYTHON_USER_INPUT_PATTERNS) {
+        const objMatch = pattern.object.test(obj.text);
+        const propMatch =
+          typeof pattern.property === "string"
+            ? attr.text === pattern.property
+            : pattern.property.test(attr.text);
+        if (objMatch && propMatch) return true;
+      }
+      // Recursive: request.form.get('key') → check object chain
+      if (isPythonUserInputExpression(obj)) return true;
+    }
+  }
+
+  // subscript: request.form['key'], request.args['q']
+  if (node.type === "subscript") {
+    const obj = node.childForFieldName("value");
+    if (obj && isPythonUserInputExpression(obj)) return true;
+  }
+
+  return false;
+}
+
+// ============================================================================
+// Dynamic String Detection (Python)
+// ============================================================================
+
+/**
+ * Check if a Python expression contains dynamic string content.
+ *
+ * Returns true for:
+ *   - f-strings with interpolation: f"Hello {name}"
+ *   - .format() calls: "Hello {}".format(name)
+ *   - % formatting: "Hello %s" % name
+ *   - String concatenation with non-literals: "Hello " + name
+ */
+export function isPythonDynamicString(node: Parser.SyntaxNode): boolean {
+  // f-string with interpolation
+  if (node.type === "string" && isPythonFString(node)) {
+    return node.namedChildren.some((c) => c.type === "interpolation");
+  }
+
+  // .format() call: "...".format(...)
+  if (node.type === "call") {
+    const fn = node.childForFieldName("function");
+    if (fn?.type === "attribute") {
+      const attr = fn.childForFieldName("attribute");
+      if (attr?.text === "format") {
+        const obj = fn.childForFieldName("object");
+        if (obj?.type === "string") return true;
+      }
+    }
+  }
+
+  // % formatting: "..." % (name,) or "..." % name
+  if (node.type === "binary_operator") {
+    const opNode = node.children.find((c) => c.type === "%");
+    if (opNode) {
+      const left = node.childForFieldName("left");
+      if (left?.type === "string") return true;
+    }
+  }
+
+  // String concatenation with non-literal
+  if (node.type === "binary_operator") {
+    const opNode = node.children.find((c) => c.type === "+");
+    if (opNode) {
+      const left = node.childForFieldName("left");
+      const right = node.childForFieldName("right");
+      if (left && right) {
+        const leftLiteral =
+          left.type === "string" ||
+          left.type === "integer" ||
+          left.type === "float";
+        const rightLiteral =
+          right.type === "string" ||
+          right.type === "integer" ||
+          right.type === "float";
+        if (!leftLiteral || !rightLiteral) return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+// ============================================================================
+// LLM Output Detection (Python)
+// ============================================================================
+
+/** Patterns that indicate LLM API response content in Python */
+const PYTHON_LLM_OUTPUT_PATTERNS = [
+  /response\.choices\[?\d*\]?\.message\.content/,
+  /completion\.choices\[?\d*\]?\.message\.content/,
+  /result\.choices\[?\d*\]?\.message\.content/,
+  /response\.content\[?\d*\]?\.text/, // Anthropic SDK
+  /message\.content/,
+  /response\.text/,
+  /result\.text/,
+  /result\.content/,
+  /response\.output_text/,
+  /result\[["']output["']\]/,
+  /response\[["']text["']\]/,
+  /response\.response/, // LlamaIndex
+  /response\.source_nodes/, // LlamaIndex
+  /completion\.text/, // litellm
+];
+
+/**
+ * Check if a Python node accesses LLM output content.
+ *
+ * Handles:
+ *   response.choices[0].message.content (OpenAI)
+ *   response.content[0].text (Anthropic)
+ *   result.content, response.text
+ *   result["output"], response["text"]
+ */
+export function isPythonLLMOutputExpression(node: Parser.SyntaxNode): boolean {
+  if (node.type !== "attribute" && node.type !== "subscript") {
+    return false;
+  }
+
+  const fullText = node.text;
+  return PYTHON_LLM_OUTPUT_PATTERNS.some((p) => p.test(fullText));
+}
+
+// ============================================================================
+// Dictionary Analysis (for LLM message dict classification)
+// ============================================================================
+
+/**
+ * Check if a Python AST node is a constant expression.
+ * Used to skip static/hardcoded values when classifying LLM sinks.
+ */
+export function isPyConstantExpression(node: Parser.SyntaxNode): boolean {
+  if (node.type === "string" && !isPythonFString(node)) return true;
+  if (node.type === "integer" || node.type === "float" || node.type === "none")
+    return true;
+  if (node.type === "true" || node.type === "false") return true;
+  if (node.type === "concatenated_string") {
+    return node.namedChildren.every(
+      (c) => c.type === "string" && !isPythonFString(c),
+    );
+  }
+  return false;
+}
+
+/**
+ * Extract a value from a Python dictionary literal by key.
+ * Handles both string keys {"role": "system"} and identifier keys {role: "system"}.
+ */
+export function getPythonDictProperty(
+  node: Parser.SyntaxNode,
+  key: string,
+): Parser.SyntaxNode | null {
+  if (node.type !== "dictionary") return null;
+  for (const child of node.namedChildren) {
+    if (child.type !== "pair") continue;
+    const keyNode = child.childForFieldName("key");
+    if (!keyNode) continue;
+    if (keyNode.type === "string") {
+      const keyText = extractPythonStringValue(keyNode);
+      if (keyText === key) return child.childForFieldName("value") ?? null;
+    }
+    if (keyNode.type === "identifier" && keyNode.text === key) {
+      return child.childForFieldName("value") ?? null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Classify a Python message dictionary as system_prompt or prompt_construction.
+ * Examines {"role": "system"|"user", "content": <dynamic>} patterns.
+ * Returns null if content is static or missing.
+ */
+export function classifyPythonMessageDict(
+  dictNode: Parser.SyntaxNode,
+): "system_prompt" | "prompt_construction" | null {
+  if (dictNode.type !== "dictionary") return null;
+  const contentValue = getPythonDictProperty(dictNode, "content");
+  if (!contentValue || isPyConstantExpression(contentValue)) return null;
+  const roleValue = getPythonDictProperty(dictNode, "role");
+  if (roleValue) {
+    const roleText = extractPythonStringValue(roleValue);
+    if (roleText === "system") return "system_prompt";
+    // User input in user/assistant role is expected — not a prompt injection vector
+    if (roleText === "user" || roleText === "assistant") return null;
+  }
+  return "prompt_construction";
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+function isDescendantOf(
+  node: Parser.SyntaxNode,
+  ancestor: Parser.SyntaxNode,
+): boolean {
+  let current: Parser.SyntaxNode | null = node;
+  while (current) {
+    if (current.id === ancestor.id) return true;
+    current = current.parent;
+  }
+  return false;
+}