@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/src/rules/code-injection.ts

@@ -0,0 +1,346 @@
+/**
+ * CODE INJECTION  (CWE-94 / CWE-95, OWASP A05:2025 - Injection)
+ *
+ * WHAT THE BUG IS, in plain language:
+ * The other injection rules are about a string being read as instructions by
+ * something ELSE - a database, a shell, a browser. This one is about a string
+ * being read as instructions by YOUR OWN PROGRAM, in your own language, with
+ * every privilege your process has.
+ *
+ *     const total = eval(req.body.preTax);
+ *
+ * The author wanted arithmetic. What they built is a remote code execution
+ * endpoint: whatever the request body says, the server runs. No escaping helps,
+ * because there is nothing to escape - the whole string IS the program.
+ *
+ * It is the shortest path from "user input" to "attacker owns the machine" in
+ * any language that has it, and it is startlingly common in code that meant to
+ * be clever about configuration, formulas, filters or plugins.
+ *
+ * THE FIX is always the same shape: stop evaluating, start parsing. A maths
+ * expression wants an expression parser. A filter wants a fixed vocabulary of
+ * allowed operations. A plugin wants a registry of known functions looked up by
+ * name. All three are more code than `eval` and none of them can be talked into
+ * running `rm -rf`.
+ *
+ * WHY IT NEEDED A NEW SINK KIND:
+ * `command` is a shell; `code` is the interpreter you are already inside. A
+ * shell-quoting sanitiser (`escapeshellarg`, `shlex.quote`) does nothing here,
+ * and the engine has to know that, which is exactly what kind-scoping is for.
+ *
+ * WHY IT EXISTS AT ALL:
+ * Three independent test files pointed at the same hole on the same day -
+ * OWASP NodeGoat's `eval(req.body.preTax)`, a Python file's
+ * `eval(expression, safe_globals)`, and a TypeScript app's
+ * `new RegExp(req.query.filter)`. In every one the tracer had already found the
+ * source and followed it; there was simply nothing at the far end to hand it
+ * to. The engine could see these all along.
+ *
+ * WHAT THIS RULE DELIBERATELY DOES NOT COVER:
+ * ReDoS - `new RegExp(userInput)` - is a real bug and was one of the three that
+ * prompted this rule, but it is CWE-1333 and an AVAILABILITY problem: a
+ * catastrophically backtracking pattern hangs the process, it does not run the
+ * attacker's code. Filing it under CWE-94 would put the wrong number on a real
+ * finding, so it is left out and named here rather than quietly folded in.
+ */
+
+import type { LanguageId } from '../parse/languages.js';
+import { asCall, type Rule, type RuleHit } from './contract.js';
+import { analyzeStringExpression, constantProof } from './lib/strings.js';
+
+/**
+ * Calls that hand a string to the language's own interpreter.
+ *
+ * `setTimeout` and `setInterval` are NOT here, and the omission is deliberate.
+ * They only execute a string argument - `setTimeout("alert(1)", 100)` - and the
+ * overwhelmingly common form passes a FUNCTION. Reporting them on shape would
+ * light up every debounce and every retry in every codebase. They are listed as
+ * taint sinks instead, where the engine knows the value came from a request and
+ * a request cannot deliver a function.
+ */
+const EVALUATORS: Record<LanguageId, readonly string[]> = {
+  javascript: ['eval', 'Function', 'execScript', 'runInNewContext', 'runInThisContext'],
+  typescript: ['eval', 'Function', 'execScript', 'runInNewContext', 'runInThisContext'],
+  // `compile` produces a code object that only `exec` can run, but it is the
+  // same decision one step earlier, and reporting it points at the real line.
+  python: ['eval', 'exec', 'compile'],
+  // `assert($x)` evaluates its argument as PHP when handed a string. It is a
+  // debugging aid that became an RCE primitive, removed in PHP 8 - which means
+  // the codebases that still use it are the old ones nobody is watching.
+  php: ['eval', 'assert', 'create_function'],
+  // ScriptEngine.eval("...") runs JavaScript inside the JVM.
+  java: ['eval'],
+  // Go has no eval. There is no interpreter at runtime to hand a string to, so
+  // the shape this rule detects cannot occur, and an empty list is the honest
+  // answer rather than a rule that never fires but implies coverage.
+  go: [],
+  // C has no interpreter to hand a string to. `dlopen`/`dlsym` load code, but
+  // from a PATH rather than from a string, which is a different bug (untrusted
+  // search path) and not one this rule models. Empty on purpose, and the
+  // coverage matrix says so rather than leaving a blank.
+  c: [],
+  cpp: [],
+};
+
+/**
+ * Evaluators that are BUILT-IN FUNCTIONS, and are therefore only themselves
+ * when called with nothing in front of them.
+ *
+ * Scanning Django found 163 code-injection findings and 153 were this mistake:
+ *
+ *     compiler.compile(value)     Django's own SQL compiler        x82
+ *     re.compile(pattern)         a regular expression             x21
+ *     self.compile(node)          somebody's method                x20
+ *     x.eval(...)                 somebody else's method           x25
+ *
+ * `compile`, `eval` and `exec` are builtins. `re.compile` shares three letters
+ * with the dangerous one and nothing else. Matching the bare method name meant
+ * every object in Python with a `.compile()` or `.eval()` method - and there are
+ * a lot of them, because those are natural names for "turn this into a runnable
+ * thing" in any DSL, ORM or template engine.
+ *
+ * Not on this list: vm.runInNewContext, which is a method and is supposed to
+ * have `vm` in front of it, and Java's ScriptEngine.eval, which is handled by
+ * JAVA_ENGINE below.
+ */
+const BARE_BUILTINS: ReadonlySet<string> = new Set([
+  'eval',
+  'exec',
+  'compile',
+  'execScript',
+  'assert',
+  'create_function',
+  'Function',
+]);
+
+/**
+ * Receivers that ARE evaluators, and so keep the finding despite BARE_BUILTINS.
+ *
+ * The bare-only rule was too blunt on its own: OWASP's dvna has
+ *
+ *     mathjs.eval(req.body.eqn)
+ *
+ * which is a genuine remote-code-execution sink - mathjs's `eval` has its own
+ * CVEs - and it has a receiver, so the first version of this guard silently
+ * dropped it. That is the exact trade this rule has to get right: `re.compile`
+ * and `compiler.compile` are somebody's method, `mathjs.eval` and `window.eval`
+ * are the interpreter. The difference is WHICH object, not whether there is one.
+ */
+const EVALUATOR_RECEIVERS: ReadonlySet<string> = new Set([
+  'mathjs',
+  'math',
+  'vm',
+  'safeEval',
+  'eval5',
+  'builtins',
+  '__builtins__',
+]);
+
+/**
+ * Receivers that are the GLOBAL OBJECT, and therefore only in JavaScript.
+ *
+ * `self` was the expensive one. In a browser - and especially in a web worker,
+ * where it is the only name for the global scope - `self.eval(src)` IS the
+ * interpreter, so it belonged on the allowlist. In Python `self` is the
+ * instance, and `self.eval(expr)` is a method somebody wrote.
+ *
+ * Scanning pandas reported 42 code injections and seventeen were `self.eval` -
+ * pandas' own `DataFrame.eval`, a public API that parses a restricted
+ * expression grammar and cannot reach the interpreter. The allowlist was
+ * correct; applying a JavaScript fact to Python was not. `window`, `global`
+ * and `globalThis` move here for the same reason, even though no other language
+ * happened to collide with them yet.
+ */
+const JS_GLOBAL_RECEIVERS: ReadonlySet<string> = new Set([
+  'window',
+  'global',
+  'globalThis',
+  'self',
+]);
+
+/**
+ * Is this dangerous-looking name actually bound to something else in this file?
+ *
+ * pandas/core/computation/ops.py, with the import one line above the call:
+ *
+ *     from pandas.core.computation.eval import eval
+ *     res = eval(self, local_dict=env, engine=engine, parser=parser)
+ *
+ * `eval`, `exec` and `compile` are only dangerous because of what the
+ * interpreter binds those names to. An explicit import rebinds them, and this
+ * scanner is holding the very file that says so. Reporting it anyway was
+ * matching a name rather than a function.
+ *
+ * Deliberately narrow: only an explicit import of the same name counts. A
+ * reassignment (`eval = my_evaluator`) or a `import *` that happens to shadow
+ * it is NOT detected, and is a documented gap rather than a guess.
+ */
+function isImportedName(source: string, name: string): boolean {
+  const n = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // from x.y import (a, eval, b)  /  from x import eval as e  /  import eval
+  return (
+    new RegExp(`^[ \\t]*from[ \\t]+[\\w.]+[ \\t]+import[ \\t]*\\(?[^\\n]*\\b${n}\\b`, 'm').test(
+      source,
+    ) || new RegExp(`^[ \\t]*import[ \\t]+${n}\\b`, 'm').test(source)
+  );
+}
+
+/**
+ * Receivers that make `eval` unambiguous in Java, where the bare name is far
+ * too common. `engine.eval(script)` is the JSR-223 scripting API.
+ */
+const JAVA_ENGINE = /engine|script|nashorn|graal|interpreter/i;
+
+export const codeInjectionRule: Rule = {
+  id: 'code-injection',
+  name: 'User input evaluated as program code',
+  cwe: 'CWE-94',
+  owasp: 'A05:2025 Injection',
+  severity: 'critical',
+  summary: 'A string is run as program code; if any of it comes from outside, the sender decides what your server does.',
+  fix:
+    'Never eval input: parse it instead (a maths parser, a fixed list of allowed commands, or a lookup table).',
+  explanation:
+    'Passing a string to eval (or exec, Function, assert) tells your own language ' +
+    'to run it as a program, with every privilege the process has. If any part of ' +
+    'that string came from a request, the request decides what your server does. ' +
+    'There is nothing to escape here - the string IS the program - so the fix is ' +
+    'always to stop evaluating and start parsing: an expression parser for maths, ' +
+    'a fixed vocabulary for filters, a lookup table for plugins.',
+  limitations:
+    'UNVERIFIED (signature-based): we confirmed a value reaches an evaluator and ' +
+    'that it is not a fixed literal. We did NOT confirm it is attacker-controlled - ' +
+    'the data-flow pass is what upgrades this to flow-verified, and evaluating your ' +
+    'own constant is harmless. DELIBERATE GAP: setTimeout and setInterval accept a ' +
+    'string and run it, but almost always receive a function, so they are taint ' +
+    'sinks only and are never reported on shape alone. ALSO NOT COVERED: ReDoS - ' +
+    'new RegExp(userInput) - is a real bug but it is CWE-1333 and an availability ' +
+    'problem rather than code execution, so filing it here would put the wrong ' +
+    'identifier on a real finding. Go is not covered because it has no runtime ' +
+    'evaluator for the shape to occur in.',
+  shapes: ['call'],
+  support: {
+    javascript: {
+      status: 'implemented',
+      note: 'Covers eval, new Function, and the vm module\'s runInNewContext/runInThisContext. setTimeout/setInterval with a string are taint sinks only, because the common form passes a function and reporting on shape would flag every debounce in the codebase.',
+    },
+    typescript: {
+      status: 'implemented',
+      note: 'Identical to JavaScript.',
+    },
+    python: {
+      status: 'implemented',
+      note: 'Covers eval, exec and compile. NOT covered: __import__ with a built name, and the ast.literal_eval / eval confusion - literal_eval is safe and is deliberately absent.',
+    },
+    java: {
+      status: 'partial',
+      note: 'PARTIAL: ScriptEngine.eval only, and only on a receiver whose name looks like a script engine (engine, script, nashorn, graal). `eval` is a common method name in Java, so an engine stored under an unrelated name is missed rather than guessed at.',
+    },
+    php: {
+      status: 'implemented',
+      note: 'Covers eval, assert with a string argument, and create_function. assert() evaluating strings was removed in PHP 8, so a hit here also tells you the file predates that.',
+    },
+    go: {
+      status: 'not-implemented',
+      note: 'NOT IMPLEMENTED: Go has no runtime evaluator - no eval, no exec of source, no scripting engine in the standard library. The shape this rule detects cannot occur, so a Go entry would imply coverage of a risk that does not exist.',
+    },
+    c: {
+      status: 'not-implemented',
+      note:
+        'C has no interpreter to hand a string to. dlopen/dlsym load code, but from a PATH rather than from a string - that is an untrusted-search-path weakness, which this rule does not model. Empty on purpose rather than half-filled.',
+    },
+    cpp: {
+      status: 'not-implemented',
+      note:
+        'C++ has no interpreter to hand a string to either. Embedded scripting engines (Lua, V8, Python-C-API) genuinely do evaluate strings and are NOT modelled - a tainted string reaching luaL_dostring or v8::Script::Compile is missed entirely.',
+    },
+  },
+  check(shape, ctx): RuleHit | null {
+    const language = ctx.language;
+    const call = asCall(shape);
+    if (!call) return null;
+
+    if (!EVALUATORS[language].includes(call.calleeName)) return null;
+
+    // Java's `eval` needs a receiver that looks like a scripting engine.
+    if (language === 'java' && !JAVA_ENGINE.test(call.receiverText)) return null;
+
+    // Everywhere else, a builtin with something in front of it is somebody
+    // else's method that happens to share the name.
+    const isJs = language === 'javascript' || language === 'typescript';
+    if (language !== 'java' && BARE_BUILTINS.has(call.calleeName) && call.receiverText !== '') {
+      const owner = call.receiverText.split(/[.\s([]/).filter(Boolean).pop() ?? call.receiverText;
+      const known = EVALUATOR_RECEIVERS.has(owner) || (isJs && JS_GLOBAL_RECEIVERS.has(owner));
+      if (!known) return null;
+    }
+
+    // A builtin the file has explicitly imported over is not the builtin.
+    if (BARE_BUILTINS.has(call.calleeName) && isImportedName(ctx.file.source, call.calleeName)) {
+      return null;
+    }
+
+    // PHP's assert() is only dangerous with a STRING argument; assert($a > $b)
+    // is an ordinary boolean check and is not evaluated as source.
+    const argument = call.args[0];
+    if (!argument) return null;
+    if (language === 'php' && call.calleeName === 'assert') {
+      if (argument.type !== 'string' && argument.type !== 'encapsed_string') {
+        // A variable could still hold a string, so we do not drop it outright -
+        // but a visible comparison is provably not source text.
+        if (argument.type === 'binary_expression') return null;
+      }
+    }
+
+    /*
+     * `exec(compile(source, name, "exec"))` is ONE decision, and this rule saw
+     * two: once for the `exec` and once for the `compile` inside it. Flask's
+     * own config loader produced a duplicate pair on the same line.
+     *
+     * `compile` earns its place in the list because it is sometimes reached
+     * alone, but when its result is being handed straight to an evaluator the
+     * outer call is the honest place to report - it is where the code actually
+     * runs, and one line of source should not become two findings.
+     */
+    if (call.calleeName === 'compile') {
+      let ancestor = call.node.parent;
+      for (let depth = 0; ancestor && depth < 4; depth++) {
+        const text = ancestor.text ?? '';
+        if (/\b(eval|exec)\s*\(/.test(text) && ancestor.type !== 'call' && ancestor.type !== 'call_expression') {
+          ancestor = ancestor.parent;
+          continue;
+        }
+        if (
+          (ancestor.type === 'call' || ancestor.type === 'call_expression') &&
+          /^\s*(eval|exec)\s*\(/.test(text)
+        ) {
+          return null;
+        }
+        ancestor = ancestor.parent;
+      }
+    }
+
+    const built = analyzeStringExpression(argument, language);
+    // `eval("1 + 1")` is a constant. Nobody can put anything inside it.
+    if (!built.isDynamic) return null;
+    // `bar` written in a branch that cannot run, every live write a literal:
+    // the same proof the SQL rule withdraws on, with the same receipt.
+    const proof = constantProof(argument, built.dynamicParts, language, { staticMethod: ctx.staticMethod, javaTypeInScan: ctx.javaTypeInScan });
+    if (proof) {
+      if (proof.reasoned) ctx.noteClean?.('code-injection', argument, proof.reason);
+      return null;
+    }
+
+    return {
+      node: call.node,
+      message: `Value passed to ${call.calleeName}() is executed as ${language === 'php' ? 'PHP' : language} code`,
+      reasoning:
+        `\`${call.calleeName}()\` hands its argument to the interpreter this program is ` +
+        `already running inside, so whatever the string says, the process does - with ` +
+        `every permission it has. The value here is ${built.mechanism === 'opaque' ? 'a runtime value' : `built at runtime via ${built.mechanism}`}, ` +
+        `so its text is not fixed at the time you are reading this line. Escaping cannot ` +
+        `help, because the whole string is the program. Replace the evaluation with a ` +
+        `parser for the thing you actually wanted: an expression evaluator for arithmetic, ` +
+        `a fixed set of allowed operations for filters, a lookup table for plugin names.`,
+    };
+  },
+};

package/src/rules/command-injection.ts

@@ -0,0 +1,296 @@
+/**
+ * OS COMMAND INJECTION  (CWE-78, OWASP A05:2025 - Injection)
+ *
+ * WHAT THE BUG IS, in plain language:
+ * Some functions hand a string to the operating system's SHELL - the same
+ * program that runs your terminal. The shell has its own punctuation with
+ * special meaning: `;` ends a command and starts another, `|` pipes output,
+ * `&&` chains, and backticks or `$( )` run a command and paste its output.
+ *
+ *     exec("ping -c 1 " + host)
+ *
+ * If `host` is `example.com; rm -rf /`, the shell sees TWO commands and runs
+ * both. Same disease as SQL injection: data got mixed into instructions.
+ *
+ * THE FIX:
+ * Don't use a shell. Every language has a way to launch a program with its
+ * arguments as a LIST rather than a sentence - `execFile`/`spawn` without
+ * `shell: true` in Node, `subprocess.run([...])` without `shell=True` in
+ * Python, `exec.Command("ping", "-c", "1", host)` in Go. When arguments are a
+ * list, `;` is just a character in a string. Nothing parses it.
+ *
+ * WHY THIS RULE IS FUSSIER THAN THE SQL ONE:
+ * `spawn("ls", [dir])` is safe, `spawn("ls " + dir, {shell:true})` is not, and
+ * they are the same function. Where the safety depends on an options object we
+ * check for it textually and say so; where we cannot tell, we stay quiet rather
+ * than guess. A scanner that cries wolf on every subprocess call gets muted,
+ * and a muted scanner finds nothing.
+ */
+
+import type { Node } from 'web-tree-sitter';
+import type { LanguageId } from '../parse/languages.js';
+import { asCall, type Rule, type RuleHit } from './contract.js';
+import { analyzeStringExpression, constantProof } from './lib/strings.js';
+import { followLocalBuild } from './lib/local-build.js';
+import { partsAreGuarded } from './lib/guards.js';
+
+/** Calls that ALWAYS go through a shell. Dynamic argument = report it. */
+const SHELL_SINKS: Record<LanguageId, readonly string[]> = {
+  javascript: ['exec', 'execSync'],
+  typescript: ['exec', 'execSync'],
+  python: ['system', 'popen', 'getoutput', 'getstatusoutput'],
+  java: ['exec'], // Runtime.getRuntime().exec(String) splits naively - still injectable
+  go: [],
+  // Every one of these hands the string to /bin/sh. `exec` is PHP's own
+  // function, unrelated to the JS/Java `exec` above - it shares the name only.
+  php: ['system', 'exec', 'shell_exec', 'passthru', 'popen', 'proc_open', 'pcntl_exec'],
+  /*
+   * C's shell calls, and the cleanest sink list in this table.
+   *
+   * There is no ambiguity to scope away here. `system()` runs /bin/sh, always,
+   * and has done since the 1970s; it has no safe overload, no options object,
+   * and no parameterised form to be confused with - which is exactly the thing
+   * that makes the SQL and deserialisation lists so fiddly elsewhere.
+   *
+   * The `execlp`/`execvp` variants search PATH, and `execl`/`execv` do not,
+   * but neither family uses a shell: they take an argument VECTOR, so a
+   * semicolon in an argument is a semicolon, not a command separator. They are
+   * the CORRECT fix for a system() call and are deliberately absent from this
+   * list - see safe/c-format-constant.c, which asserts execv stays quiet.
+   *
+   * The one exception is execl with an explicit shell: `execlp("sh", "sh",
+   * "-c", tainted, ...)`. That IS a shell, so `execlp` and `execvp` appear in
+   * CONDITIONAL_SINKS below, gated on a shell program being visible.
+   */
+  c: ['system', 'popen'],
+  cpp: ['system', 'popen'],
+};
+
+/**
+ * Calls that MAY go through a shell depending on an option.
+ * We only report these when the shell-enabling option is visible in the call.
+ */
+const CONDITIONAL_SINKS: Record<LanguageId, readonly string[]> = {
+  javascript: ['spawn', 'spawnSync', 'execFile', 'execFileSync'],
+  typescript: ['spawn', 'spawnSync', 'execFile', 'execFileSync'],
+  python: ['run', 'call', 'check_call', 'check_output', 'Popen'],
+  java: ['ProcessBuilder', 'start'],
+  go: ['Command', 'CommandContext'],
+  // PHP has no safe-by-default process API to make conditional, so this list is
+  // empty and every shell call above is reported unconditionally.
+  php: [],
+  // exec* takes an argument vector and is SAFE - unless the program it runs is
+  // itself a shell, which turns the next argument back into a command.
+  c: ['execl', 'execlp', 'execv', 'execvp', 'execle', 'execve'],
+  cpp: ['execl', 'execlp', 'execv', 'execvp', 'execle', 'execve'],
+};
+
+const SHELL_OPTION: Record<LanguageId, RegExp> = {
+  javascript: /shell\s*:\s*true/,
+  typescript: /shell\s*:\s*true/,
+  python: /shell\s*=\s*True/,
+  java: /\b(sh|bash|cmd\.exe|powershell)\b/,
+  // Unused: PHP's CONDITIONAL_SINKS list is empty, so nothing consults this.
+  // It exists because the type demands an entry for every language, and an
+  // entry that never matches is more honest than one that pretends to.
+  php: /(?!)/,
+  // Only a shell PROGRAM makes exec.Command dangerous. `exec.Command("ping",
+  // "-c", "1", host)` is genuinely safe, so matching on "-c" alone would be a
+  // false positive on correct code.
+  go: /["'`](sh|bash|zsh|cmd\.exe|powershell)["'`]/,
+  // Same reasoning as Go: only a shell PROGRAM makes an exec* call injectable.
+  // `execv("/bin/ping", args)` with a tainted arg is genuinely safe and must
+  // stay quiet, so the program name is what this matches - not the "-c".
+  c: /["'](\/bin\/)?(sh|bash|zsh|ksh|dash)["']/,
+  cpp: /["'](\/bin\/)?(sh|bash|zsh|ksh|dash)["']/,
+};
+
+function nodeText(node: Node): string {
+  return (node.text ?? '').replace(/\s+/g, ' ').trim();
+}
+
+export const commandInjectionRule: Rule = {
+  id: 'command-injection',
+  name: 'Shell command built from a dynamic string',
+  cwe: 'CWE-78',
+  owasp: 'A05:2025 Injection',
+  severity: 'critical',
+  summary: 'A shell command is built from pieces; if any piece comes from outside, it can add a command of its own.',
+  fix:
+    'Run the program with an argument list and no shell, e.g. subprocess.run(["ls", path]) or execFile("ls", [path]).',
+  explanation:
+    'A shell reads punctuation like ; | && ` and $() as instructions. If a command ' +
+    'string is glued together from pieces, anything spliced in can end your command ' +
+    'and start a new one of the attacker\'s choosing, running as your process. ' +
+    'The fix is to launch the program with its arguments as a list instead of a ' +
+    'sentence, so no shell ever parses the input.',
+  limitations:
+    'UNVERIFIED (signature-based): we confirmed a shell-executing call receives a ' +
+    'dynamically built string - either built inside the call, or built in a local ' +
+    'variable earlier in the same function and followed back to it. We did NOT confirm ' +
+    'the spliced value is attacker-controlled. A command variable written inside an if, ' +
+    'a loop or a switch is not followed, and for list-style APIs we judged shell usage ' +
+    'from the visible text of the call only - an options object built elsewhere is ' +
+    'invisible to us. A command built right inside the call from values that are ' +
+    'PROVABLY fixed - by the same constant proof, and with the same limits, as the SQL ' +
+    'rule\'s, including a static Java helper in another file - is withdrawn and listed ' +
+    'as proved clean with the reason. Java only: in every other language this rule ' +
+    'does not use the proof and reports as before. A command assembled on an earlier ' +
+    'line does not get that proof either.',
+  shapes: ['call'],
+  support: {
+    javascript: {
+      status: 'implemented',
+      note: 'child_process exec/execSync always reported; spawn/execFile reported only when `shell: true` appears in the call text. A command built in a local variable before the call (`const cmd = "ls " + x; exec(cmd)`) is followed back to its build; one written inside a branch or loop, or passed in as a parameter, is not. An options object assembled in another variable is missed, because we read the shell option from the visible text of the call.',
+    },
+    typescript: {
+      status: 'implemented',
+      note: 'Identical to JavaScript.',
+    },
+    python: {
+      status: 'implemented',
+      note: 'os.system/os.popen always reported; subprocess.* reported only when `shell=True` is visible in the call. A command built in a local variable before the call is followed back to its build, including `+=` extensions after it; one written inside a branch or loop, or passed in as a parameter, is not.',
+    },
+    java: {
+      status: 'partial',
+      note: 'PARTIAL: Runtime.exec(String) and ProcessBuilder are detected when the command string is built at the call site, or in a straight-line assignment earlier in the same method. Java code commonly builds commands with StringBuilder across several statements, or picks the shell per operating system inside an if/else; the signature pass follows neither, and the taint engine tracks variables rather than the interior of objects, so a StringBuilder is not followed there either.',
+    },
+    go: {
+      status: 'partial',
+      note: 'PARTIAL: exec.Command is only reported when the call itself mentions a shell ("sh", "-c"). exec.Command("ping", host) is genuinely safe, so reporting every exec.Command would be noise - but that also means a shell wrapper built elsewhere is missed. The command string handed to `sh -c` is followed back to a local build (`c := "ls " + x`, fmt.Sprintf) when it was written in straight-line code.',
+    },
+    php: {
+      status: 'implemented',
+      note: 'Covers system, exec, shell_exec, passthru, popen, proc_open and pcntl_exec. Unlike Go and Java there is no conditional case to weigh: every one of these hands the string to a shell, so a dynamic argument is always reported.',
+    },
+    c: {
+      status: 'implemented',
+      note:
+        'system() and popen() hand the string to /bin/sh with no safe overload to be confused with, which makes this the least ambiguous sink list in the tool. exec* takes an argument VECTOR and is reported ONLY when the program being run is itself a shell - execv("/bin/ping", args) with a tainted argument is genuinely safe and stays quiet. The build-then-run idiom is followed through the buffer at both levels. The tracer follows a recognised source into sprintf/strcat and out through system(). The signature pass - which until build-then-run.c saw only `system(buf)`, a bare name, and so reported NOTHING for any C command injection whose source it did not recognise - now reads how the buffer was filled: sprintf/snprintf (reading the format string, so %d is not a splice and %s is), strcpy then strcat, an initialised array then strcat. A buffer written inside an if, a loop or a switch is not followed, and says nothing.',
+    },
+    cpp: {
+      status: 'implemented',
+      note:
+        'Every C entry applies unchanged, since C++ inherits the whole libc surface and real code still uses it. Namespace-qualified calls (std::system) and method calls on objects are recognised in addition. std::system() takes a const char*, so every C++ shell call ends in .c_str() or .data(); those are looked through, and a std::string built with +, += or append() before the call is followed back to its build - under the same straight-line-only condition as C.',
+    },
+  },
+  check(shape, ctx): RuleHit | null {
+    const call = asCall(shape);
+    if (!call) return null;
+    const language = ctx.language;
+
+    /*
+     * A SHELL FUNCTION THAT WAS RENAMED IS STILL A SHELL FUNCTION.
+     *
+     *     import { exec } from "child_process";
+     *     const execAsync = promisify(exec);
+     *     await execAsync(command);
+     *
+     * That is CVE-2025-53107 - twenty-three vulnerable files - and this rule
+     * found none of them, because the list holds `exec` and the call says
+     * `execAsync`. The near-identical CVE-2025-59046 WAS caught, purely because
+     * that author wrote `const exec = promisify(execCb)` and aliased back to a
+     * name we already knew. Two CVEs, and the only difference was luck.
+     *
+     * `promisify` is the standard Node idiom for exactly these APIs, so the
+     * aliased form is the normal one, not an exotic one. File-local only: an
+     * alias exported from another module is still missed.
+     */
+    const aliasOf = (called: string): string | null => {
+      const declaration = new RegExp(
+        `\\b${called.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*=\\s*([^;\\n]+)`,
+      ).exec(ctx.file.source);
+      if (!declaration?.[1]) return null;
+      const initialiser = declaration[1];
+      if (!/\bpromisify\s*\(|require\s*\(|child_process/.test(initialiser)) return null;
+      for (const known of [...SHELL_SINKS[language], ...CONDITIONAL_SINKS[language]]) {
+        if (known !== called && new RegExp(`\\b${known}\\b`).test(initialiser)) return known;
+      }
+      return null;
+    };
+    const resolved =
+      SHELL_SINKS[language].includes(call.calleeName) ||
+      CONDITIONAL_SINKS[language].includes(call.calleeName)
+        ? call.calleeName
+        : (aliasOf(call.calleeName) ?? call.calleeName);
+
+    const always = SHELL_SINKS[language].includes(resolved);
+    const conditional = CONDITIONAL_SINKS[language].includes(resolved);
+    if (!always && !conditional) return null;
+
+    // For the conditional family, require visible evidence that a shell is used.
+    const wholeCall = nodeText(call.node);
+    if (conditional && !always && !SHELL_OPTION[language].test(wholeCall)) return null;
+
+    for (const arg of call.args) {
+      let built = analyzeStringExpression(arg, language);
+      let builtOnLine: number | null = null;
+      /*
+       * A bare variable tells us nothing about a command ON ITS OWN - "you
+       * passed a variable to exec" is not actionable, and the rule has always
+       * skipped it. What it never did was ask the next question: where was that
+       * variable built? `cmd = "ls " + name` one line earlier is the same
+       * finding as `exec("ls " + name)`, and in C - which cannot build a string
+       * inside a call's brackets at all - it is the ONLY form a command
+       * injection ever takes. lib/local-build.ts says what it follows and,
+       * more importantly, where it gives up.
+       */
+      if (built.mechanism === 'opaque' && built.literalText.length === 0) {
+        const followed = followLocalBuild(arg, language);
+        if (!followed) continue;
+        built = followed.expression;
+        builtOnLine = followed.line;
+      }
+      if (!built.isDynamic) continue;
+      if (built.mechanism === 'opaque' && built.literalText.length === 0) continue;
+      /*
+       * ASSEMBLED FROM FIXED PIECES IS NOT ASSEMBLED FROM INPUT. The SQL rule
+       * has asked this since the constant proof existed; this rule never did,
+       * so `exec(cmd + bar)` with both halves provably fixed was reported -
+       * 31 of BenchmarkJava's command-injection false positives, where `cmd`
+       * comes from a helper in another file (StaticHelperCommand.java). When
+       * the proof needed reasoning it leaves a receipt, as the SQL rule's does.
+       *
+       * Only for a command written right here in the call. One assembled on an
+       * earlier line (builtOnLine) is read at the call, and a name's value at
+       * the call can differ from its value where the command was built - so
+       * that case keeps the guess.
+       *
+       * And only in Java for now. The first two rounds of an agent trying to
+       * break the proof (tests/probes/) found most of its holes outside Java, and the
+       * command rule had never leaned on it in any language; it starts where
+       * it has been tested hardest. Elsewhere this rule reports as before.
+       */
+      if (builtOnLine === null && language === 'java') {
+        const proof = constantProof(arg, built.dynamicParts, language, { staticMethod: ctx.staticMethod, javaTypeInScan: ctx.javaTypeInScan });
+        if (proof) {
+          if (proof.reasoned) ctx.noteClean?.('command-injection', arg, proof.reason);
+          continue;
+        }
+      }
+      /*
+       * A VALIDATION GUARD. Inside `if (is_numeric($octet[0]) && ...)` the value
+       * provably holds no shell metacharacter - it is digits. This is DVWA's own
+       * fix in exec/impossible.php, and reporting it was the seventh time this
+       * project punished a corrected file, and the last one still showing in the
+       * instrument panel. lib/guards.ts documents why the predicate list is tiny.
+       */
+      if (partsAreGuarded(arg, built.dynamicParts, language, 'command')) continue;
+
+      const callLine = arg.startPosition.row + 1;
+      const where = builtOnLine === null || builtOnLine === callLine ? '' : ` on line ${builtOnLine}`;
+      return {
+        node: arg,
+        message: `Command passed to ${call.calleeText}() is built with ${built.mechanism}${where}`,
+        reasoning:
+          `\`${call.calleeText}()\` executes its argument through a shell` +
+          `${conditional && !always ? ' (a shell option is set in this call)' : ''}. ` +
+          `The command string is not fixed - it was assembled via ${built.mechanism}${where}, ` +
+          `splicing in ${built.dynamicParts.slice(0, 3).map((p) => `\`${p}\``).join(', ') || 'a runtime value'}. ` +
+          `Shell metacharacters (; | && \` $()) inside that value would be executed as ` +
+          `separate commands.`,
+      };
+    }
+    return null;
+  },
+};