@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/src/rules/contract.ts

@@ -0,0 +1,220 @@
+/**
+ * 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 function asCall(shape: Shape): CallSite | null {
+  return shape.kind === 'call' ? shape : null;
+}
+
+export function asAssignment(shape: Shape): Assignment | null {
+  return shape.kind === 'assignment' ? shape : null;
+}

package/src/rules/format-string.ts

@@ -0,0 +1,158 @@
+/**
+ * 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 { LanguageId } from '../parse/languages.js';
+import { asCall, type Rule, type RuleHit } from './contract.js';
+import { isStringLiteral } from './lib/strings.js';
+
+/**
+ * Function name -> which argument is the FORMAT.
+ *
+ * Getting an index wrong here does not just miss a bug, it reports correct
+ * code, so each one is written out rather than inferred from the name.
+ */
+const FORMAT_ARGUMENT: ReadonlyMap<string, number> = new Map([
+  ['printf', 0],
+  ['vprintf', 0],
+  ['fprintf', 1],
+  ['sprintf', 1],
+  ['vfprintf', 1],
+  ['vsprintf', 1],
+  ['dprintf', 1],
+  ['asprintf', 1],
+  ['syslog', 1],
+  ['snprintf', 2],
+  ['vsnprintf', 2],
+]);
+
+const C_FAMILY: ReadonlySet<LanguageId> = new Set<LanguageId>(['c', 'cpp']);
+
+const NOT_C = {
+  status: 'not-implemented' as const,
+  note:
+    'Format string injection is a C-family bug. Other languages either take the format ' +
+    'as a constant by construction or have no %n equivalent, so there is nothing here to ' +
+    'match and this rule never fires. Stated rather than left as a blank column.',
+};
+
+export const formatStringRule: Rule = {
+  id: 'format-string',
+  name: 'Attacker-controlled format string',
+  cwe: 'CWE-134',
+  owasp: 'A05:2025 Injection',
+  severity: 'high',
+  summary: 'The format string is not fixed; if it comes from outside, it can read or even write memory.',
+  fix:
+    'Make the format a fixed string and pass the value separately: printf("%s", name), not printf(name).',
+  explanation:
+    'A format string is a small program: %x reads, %s dereferences, and %n WRITES. When ' +
+    'the format itself comes from the user, they are writing that program. The fix is ' +
+    'always the same shape and always cheap - make the format a constant and pass the ' +
+    'value as data: printf("%s", name) instead of printf(name).',
+  limitations:
+    'A signature-based finding here means only that the format argument is not a literal ' +
+    'in this call - it may be a constant defined elsewhere, which we cannot see because ' +
+    'the preprocessor is not run and constants are not folded. A flow-verified finding ' +
+    'means the value was traced from an attacker-controlled source into the format ' +
+    'position, and that claim carries its path.',
+  shapes: ['call'],
+  support: {
+    c: {
+      status: 'implemented',
+      note:
+        'Covers the printf family (printf, fprintf, sprintf, snprintf, dprintf, asprintf, ' +
+        'syslog and their v- variants), with the format argument index recorded per ' +
+        'function so that the correct form - a constant format with the value passed as ' +
+        'data - is never reported. A format built by a macro is missed: the preprocessor ' +
+        'is not run.',
+    },
+    cpp: {
+      status: 'implemented',
+      note:
+        'Identical to C. std::format and iostreams are type-safe and cannot carry this ' +
+        'bug, so they are deliberately not matched; C++ code that calls printf still can, ' +
+        'and still does.',
+    },
+    javascript: NOT_C,
+    typescript: NOT_C,
+    python: NOT_C,
+    java: NOT_C,
+    go: NOT_C,
+    php: NOT_C,
+  },
+
+  check(shape, ctx): RuleHit | null {
+    if (!C_FAMILY.has(ctx.language)) return null;
+    const call = asCall(shape);
+    if (!call) return null;
+
+    const index = FORMAT_ARGUMENT.get(call.calleeName);
+    if (index === undefined) return null;
+
+    const formatArgument = call.args[index];
+    // No argument in the format position at all - nothing to say about it.
+    if (!formatArgument) return null;
+
+    /*
+     * A literal format is the SAFE form and the whole point of the fix. It is
+     * checked first and returns null, so `printf("%s", name)` can never be
+     * reported however dirty `name` is.
+     */
+    if (isStringLiteral(formatArgument, ctx.language)) return null;
+
+    const argumentText = ctx.text(formatArgument);
+    return {
+      node: call.node,
+      message: `${call.calleeName}() is called with a non-constant format string (\`${argumentText}\`)`,
+      reasoning:
+        `The format argument of \`${call.calleeName}()\` is \`${argumentText}\`, which is not a ` +
+        `string literal. A format string is executable: \`%x\` reads values off the stack, ` +
+        `\`%s\` dereferences one as a pointer, and \`%n\` writes to memory. If that value ` +
+        `can be influenced by a user, this is a memory-write primitive rather than a print ` +
+        `statement. The fix is to make the format constant and pass the value as data: ` +
+        `\`${call.calleeName}(${index === 0 ? '' : '..., '}"%s", ${argumentText})\`.`,
+    };
+  },
+};