@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/dist/src/rules/command-injection.js

@@ -0,0 +1,286 @@
+/**
+ * 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 { asCall } 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 = {
+    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 = {
+    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 = {
+    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) {
+    return (node.text ?? '').replace(/\s+/g, ' ').trim();
+}
+export const commandInjectionRule = {
+    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) {
+        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) => {
+            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 = 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;
+    },
+};
+//# sourceMappingURL=command-injection.js.map

package/dist/src/rules/command-injection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-injection.js","sourceRoot":"","sources":["../../../src/rules/command-injection.ts"],"names":[],"mappings":"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"}

package/dist/src/rules/contract.d.ts

@@ -0,0 +1,198 @@
+/**
+ * THE RULE CONTRACT
+ * =================
+ *
+ * A "rule" is one thing Defuse knows how to look for. This file defines the shape
+ * every rule must have. Nothing else in the codebase knows what SQL injection
+ * is - the engine just runs whatever satisfies this interface.
+ *
+ * ARCHITECTURAL DECISION (this is the big one - it shapes Phases 3 and 5):
+ *
+ * Rules do NOT write tree-sitter queries and rules do NOT walk the AST.
+ * Instead, the engine lowers every language's syntax tree into a handful of
+ * language-neutral SHAPES - right now `CallSite` and `Assignment` - and a rule
+ * is a plain function that inspects a shape and says yes or no.
+ *
+ * Why:
+ *   - A rule written once works for all five languages. `db.query(...)` in JS,
+ *     `cursor.execute(...)` in Python and `stmt.executeQuery(...)` in Java all
+ *     arrive at the rule as the same CallSite object with a different
+ *     `calleeName`. The rule needs a name list per language, not a rewrite.
+ *   - Adding language number six means teaching the SHAPE LAYER one new query.
+ *     Every existing rule gains that language for free.
+ *   - Phase 3's taint engine needs exactly these shapes anyway (a "source" is a
+ *     CallSite, a "sink" is a CallSite, propagation happens through
+ *     Assignments). Building them now means Phase 3 is an addition, not a
+ *     rewrite.
+ *
+ * The escape hatch: a rule may declare `status: 'partial'` or
+ * `'not-implemented'` for a language the shape layer cannot express. That is a
+ * documented gap, printed in every report. It is never silence.
+ */
+import type { Node } from 'web-tree-sitter';
+import type { Severity } from '../core/finding.js';
+import type { LanguageId } from '../parse/languages.js';
+import type { ParsedFile } from '../parse/parser.js';
+/**
+ * A function/method call, normalised across languages.
+ *
+ *   JS      db.query(sql)           receiverText "db"      calleeName "query"
+ *   Python  cursor.execute(sql)     receiverText "cursor"  calleeName "execute"
+ *   Java    stmt.executeQuery(sql)  receiverText "stmt"    calleeName "executeQuery"
+ *   Go      db.Query(sql)           receiverText "db"      calleeName "Query"
+ */
+export interface CallSite {
+    readonly kind: 'call';
+    /** The whole call expression - what a finding points at. */
+    readonly node: Node;
+    /** The method or function name only, no dots. */
+    readonly calleeName: string;
+    /** Text before the dot, e.g. "db", "child_process", "Runtime.getRuntime()". */
+    readonly receiverText: string;
+    /** Full callee text, e.g. "crypto.createHash". */
+    readonly calleeText: string;
+    /** Argument expressions, already stripped of commas and parentheses. */
+    readonly args: readonly Node[];
+}
+/**
+ * A value being stored somewhere, normalised across languages. Covers
+ * variable declarations, plain assignments, object/dict literal entries and
+ * keyword arguments - anywhere a name gets bound to a value.
+ */
+export interface Assignment {
+    readonly kind: 'assignment';
+    readonly node: Node;
+    /** Full left-hand side text, e.g. "el.innerHTML", "config.apiKey". */
+    readonly targetText: string;
+    /** Last segment of the target, e.g. "innerHTML", "apiKey". */
+    readonly targetName: string;
+    /** The value expression. */
+    readonly value: Node;
+}
+export type Shape = CallSite | Assignment;
+/** Everything a rule is allowed to know while deciding. */
+export interface RuleContext {
+    readonly file: ParsedFile;
+    readonly language: LanguageId;
+    /** Convenience: source text of a node, whitespace-collapsed. */
+    readonly text: (node: Node) => string;
+    /**
+     * Record that this rule examined a line and can PROVE it is not the bug the
+     * shape suggests - so the guess it would have made is withdrawn, not dropped.
+     *
+     * A rule that declines to report leaves no trace, and that was fine while
+     * declining meant "these are plain literals". Once a rule can decline because
+     * of REASONING - a branch that cannot run, a condition fixed at compile time -
+     * the reasoning has to be visible, because reasoning can be wrong. Receipts
+     * appear in --json as verifiedClean entries with the reason attached, are
+     * counted in the terminal summary, and show as "proved clean" in the UI.
+     *
+     * Optional so a caller that builds its own context is not broken by it.
+     */
+    readonly noteClean?: (ruleId: string, node: Node, reason: string) => void;
+    /**
+     * Java only: the static method a call like `Utils.m(...)` or
+     * `a.b.Utils.m(...)` runs, when that is not in doubt - see
+     * taint/project.ts, staticMethod(). Absent when cross-file resolution is
+     * off, and then nothing is read through another file.
+     */
+    readonly staticMethod?: StaticMethodLookup | undefined;
+    /** Java only: is a type of this simple name - top-level or nested - declared anywhere in the scan? */
+    readonly javaTypeInScan?: ((simpleName: string) => boolean) | undefined;
+}
+/** A static method found in the scan: the file a reader should be shown, and its declaration. */
+export interface StaticMethodHit {
+    readonly path: string;
+    readonly method: Node;
+}
+/**
+ * `receiver` is the class as written at the call - `Utils` or `a.b.Utils`;
+ * `supertypes`, what the classes around the call inherit from.
+ */
+export type StaticMethodLookup = (receiver: string, method: string, supertypes?: readonly string[], allowInstance?: boolean) => StaticMethodHit | null;
+/**
+ * What a rule returns when it decides something is worth reporting.
+ * Note there is NO confidence field: a rule cannot set its own confidence.
+ * The engine stamps a rule's result as signature-based; only the taint engine,
+ * which can produce a source-to-sink path, may emit flow-verified. A rule that wanted
+ * to claim more would have to change the engine, in a commit, in review.
+ */
+export interface RuleHit {
+    /** Node to point the finding at. Usually the shape's node or a sub-node. */
+    readonly node: Node;
+    /** One line for the terminal. */
+    readonly message: string;
+    /** Why this matched, in plain language. Shown to the user. Required. */
+    readonly reasoning: string;
+    /** Optional per-hit override of the rule's general limitations text. */
+    readonly limitations?: string;
+    /** Optional severity override (e.g. a confirmed AWS key beats a generic one). */
+    readonly severity?: Severity;
+}
+export type SupportStatus = 'implemented' | 'partial' | 'not-implemented';
+export interface LanguageSupport {
+    readonly status: SupportStatus;
+    /**
+     * REQUIRED for every language, including implemented ones. For 'partial' and
+     * 'not-implemented' this must say exactly what is missing. This text is
+     * printed in the coverage section of every scan, so a gap can never be silent.
+     */
+    readonly note: string;
+}
+export interface Rule {
+    /** Stable machine id, kebab-case. Used in --json, tests and suppressions. */
+    readonly id: string;
+    readonly name: string;
+    /** CWE identifier - the industry's shared catalogue of weakness types. */
+    readonly cwe: string;
+    /** OWASP Top 10 (2025) category. */
+    readonly owasp: string;
+    readonly severity: Severity;
+    /**
+     * 2-4 sentences explaining the VULNERABILITY (not the detection code) to
+     * someone who has never heard of it. Printed by `defuse rules --explain`.
+     */
+    readonly explanation: string;
+    /**
+     * ONE plain sentence a beginner can read under a finding: what goes wrong,
+     * no jargon. The terminal prints it on every finding; `explanation` is the
+     * long version behind --full and `rules --explain`.
+     */
+    readonly summary: string;
+    /** ONE sentence: what to change in the code. Printed as `fix` on every finding. */
+    readonly fix: string;
+    /**
+     * What this rule structurally cannot determine. Copied onto every finding it
+     * produces unless the hit overrides it. Required - a rule with no stated
+     * limitations is a rule pretending to be certain.
+     */
+    readonly limitations: string;
+    /**
+     * Per-language honesty declaration. REQUIRED FOR EVERY LANGUAGE.
+     *
+     * This was `Partial<Record<...>>` with "missing language = not-implemented"
+     * as the default, and that default caused the worst kind of bug this project
+     * can have: the tool contradicting itself about its own coverage.
+     *
+     * Adding C and C++ silently marked all eight existing rules not-implemented
+     * for them. rulesForLanguage() then filtered those rules out, so their
+     * SIGNATURE matchers never ran on a C file at all - while the taint engine,
+     * which reaches rules by id and never consults this table, went on producing
+     * flow-verified `command-injection` findings in C. The report printed six of
+     * them directly underneath a line saying command-injection/c was NOT
+     * IMPLEMENTED.
+     *
+     * A silent default is what made that possible. Requiring every language
+     * turns the next language addition into a compile error per rule, which is
+     * exactly what the taint dictionaries already do - nineteen of them, each a
+     * real decision someone had to make on purpose.
+     */
+    readonly support: Record<LanguageId, LanguageSupport>;
+    /** Which shapes this rule wants to see. Engine only calls matching ones. */
+    readonly shapes: readonly Shape['kind'][];
+    /** The decision. Return null for "not interesting". */
+    readonly check: (shape: Shape, ctx: RuleContext) => RuleHit | null;
+}
+/** Helper so a rule can narrow a Shape without repeating the same three lines. */
+export declare function asCall(shape: Shape): CallSite | null;
+export declare function asAssignment(shape: Shape): Assignment | null;

package/dist/src/rules/contract.js

@@ -0,0 +1,39 @@
+/**
+ * THE RULE CONTRACT
+ * =================
+ *
+ * A "rule" is one thing Defuse knows how to look for. This file defines the shape
+ * every rule must have. Nothing else in the codebase knows what SQL injection
+ * is - the engine just runs whatever satisfies this interface.
+ *
+ * ARCHITECTURAL DECISION (this is the big one - it shapes Phases 3 and 5):
+ *
+ * Rules do NOT write tree-sitter queries and rules do NOT walk the AST.
+ * Instead, the engine lowers every language's syntax tree into a handful of
+ * language-neutral SHAPES - right now `CallSite` and `Assignment` - and a rule
+ * is a plain function that inspects a shape and says yes or no.
+ *
+ * Why:
+ *   - A rule written once works for all five languages. `db.query(...)` in JS,
+ *     `cursor.execute(...)` in Python and `stmt.executeQuery(...)` in Java all
+ *     arrive at the rule as the same CallSite object with a different
+ *     `calleeName`. The rule needs a name list per language, not a rewrite.
+ *   - Adding language number six means teaching the SHAPE LAYER one new query.
+ *     Every existing rule gains that language for free.
+ *   - Phase 3's taint engine needs exactly these shapes anyway (a "source" is a
+ *     CallSite, a "sink" is a CallSite, propagation happens through
+ *     Assignments). Building them now means Phase 3 is an addition, not a
+ *     rewrite.
+ *
+ * The escape hatch: a rule may declare `status: 'partial'` or
+ * `'not-implemented'` for a language the shape layer cannot express. That is a
+ * documented gap, printed in every report. It is never silence.
+ */
+/** Helper so a rule can narrow a Shape without repeating the same three lines. */
+export function asCall(shape) {
+    return shape.kind === 'call' ? shape : null;
+}
+export function asAssignment(shape) {
+    return shape.kind === 'assignment' ? shape : null;
+}
+//# sourceMappingURL=contract.js.map

package/dist/src/rules/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/rules/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAsLH,kFAAkF;AAClF,MAAM,UAAU,MAAM,CAAC,KAAY;IACjC,OAAO,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAY;IACvC,OAAO,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC"}

package/dist/src/rules/format-string.d.ts

@@ -0,0 +1,46 @@
+/**
+ * FORMAT STRING INJECTION  (CWE-134)
+ *
+ * WHAT THE BUG IS.
+ *
+ *     printf(name);            // `name` came from the user
+ *
+ * looks like printing a string and is not. printf reads its first argument as a
+ * FORMAT, so whoever controls that string controls the conversions too:
+ *
+ *     %x %x %x %x     walks up the stack and prints whatever is sitting there
+ *     %s              treats a stack value as a pointer - crash, or a leak
+ *     %n              WRITES the number of bytes printed so far to a pointer
+ *                     argument, which turns a logging call into an arbitrary
+ *                     memory write
+ *
+ * That last conversion is why this is not a cosmetic bug. It is the standard
+ * route from "the program logs a username" to "the attacker runs code".
+ *
+ * WHY THIS RULE IS THE BEST ARGUMENT FOR POINTING A TAINT ENGINE AT C.
+ *
+ * Most famous C bugs are SIZE bugs - is this buffer big enough, is this integer
+ * about to wrap - and answering those needs an analysis of sizes, allocations
+ * and aliasing that this engine does not have. The unbounded-copy rule next
+ * door is careful to claim much less than its name suggests for exactly that
+ * reason.
+ *
+ * A format string bug needs none of it. The entire question is "is this ONE
+ * argument attacker-controlled?", which is the only question this engine
+ * answers, and it answers it with a printed path. So a flow-verified finding
+ * here means precisely what it says, with no hedge underneath it.
+ *
+ * THE TRAP THIS RULE MUST NOT FALL INTO.
+ *
+ *     printf(name)             dangerous
+ *     printf("%s", name)       correct
+ *
+ * Same function, one extra argument - the identical shape as a parameterised
+ * SQL query versus a concatenated one. A rule that fired on "printf with a
+ * tainted argument" would report the FIX as the bug, which this project treats
+ * as worse than a miss: it teaches people that hardening does not help. Only
+ * the format argument counts, and its index differs per function, so the table
+ * below is the whole rule.
+ */
+import { type Rule } from './contract.js';
+export declare const formatStringRule: Rule;