@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/src/rules/unbounded-copy.ts

@@ -0,0 +1,162 @@
+/**
+ * COPIES WITH NO LENGTH BOUND  (CWE-120)
+ *
+ * READ THE NAME OF THIS RULE CAREFULLY. It is not `buffer-overflow`, and the
+ * difference is the entire honesty argument for shipping it.
+ *
+ * A buffer overflow is a SIZE bug. Whether `strcpy(dst, src)` overflows depends
+ * on how big `dst` is, how long `src` turns out to be at runtime, and whether
+ * any pointer between them aliases something else. This engine models none of
+ * that - it tracks VALUES, not sizes, allocation lifetimes or aliasing. It
+ * cannot tell you whether a copy overflows and does not claim to.
+ *
+ * What it CAN prove from data flow alone is narrower and still worth saying:
+ *
+ *     attacker-controlled data reaches a function that writes until it
+ *     meets a NUL byte, and the attacker chooses where that byte is.
+ *
+ * That is what a finding here asserts, and the wording says so. A `strcpy` into
+ * a destination that genuinely is large enough is a FALSE POSITIVE of this
+ * rule. That is declared here, in the finding text and in the coverage report,
+ * rather than left for somebody to discover and lose trust over.
+ *
+ * It is still worth reporting, because the unbounded functions have no safe
+ * upper bound by construction. Every one of them has a bounded sibling that
+ * takes a length - strncpy, strncat, snprintf, strlcpy - and those are
+ * registered as sanitisers for this sink kind, so switching to them retracts
+ * the finding. A rule that cannot be satisfied by fixing the code is a rule
+ * nobody will act on.
+ *
+ * gets() IS THE EXCEPTION, and it needs no data flow at all. It has no length
+ * parameter and no way to acquire one, which is why C11 removed it from the
+ * standard library outright. There is nothing to trace, so it is reported on
+ * sight as a SIGNATURE finding - honestly labelled as unverified flow, because
+ * there is no flow to verify, not because we failed to find one.
+ */
+
+import type { LanguageId } from '../parse/languages.js';
+import { asCall, type Rule, type RuleHit } from './contract.js';
+import { isStringLiteral } from './lib/strings.js';
+
+/** Copies with no length parameter, and which argument carries the data. */
+const UNBOUNDED_COPIES: ReadonlyMap<string, number> = new Map([
+  ['strcpy', 1],
+  ['stpcpy', 1],
+  ['strcat', 1],
+]);
+
+/**
+ * Cannot be called safely under any circumstances, so no source is needed.
+ * C11 removed gets() from the standard library rather than try to document it.
+ */
+const UNCONDITIONALLY_UNSAFE: ReadonlySet<string> = new Set(['gets']);
+
+const C_FAMILY: ReadonlySet<LanguageId> = new Set<LanguageId>(['c', 'cpp']);
+
+const NOT_C = {
+  status: 'not-implemented' as const,
+  note:
+    'Manual memory copies are a C-family concern. Managed languages bound their own ' +
+    'string operations, so this rule has nothing to match and never fires. Stated rather ' +
+    'than left as a blank column.',
+};
+
+export const unboundedCopyRule: Rule = {
+  id: 'unbounded-copy',
+  name: 'Attacker data reaches a copy with no length bound',
+  cwe: 'CWE-120',
+  owasp: 'A05:2025 Injection',
+  severity: 'high',
+  summary: 'Data is copied into a buffer with no size limit; if the data comes from outside, long input can overwrite memory.',
+  fix:
+    'Use the bounded version that takes the buffer size: snprintf, strncpy/strlcpy, strncat; replace gets with fgets.',
+  explanation:
+    'strcpy, strcat and sprintf write until they meet a NUL byte, and when the source is ' +
+    'attacker-controlled the attacker decides where that byte is. Each has a bounded ' +
+    'sibling that takes a length - strncpy, strncat, snprintf, strlcpy - and switching to ' +
+    'one retracts this finding. gets() has no bounded form at all and was removed from ' +
+    'the C standard in C11.',
+  limitations:
+    'THIS IS NOT A CLAIM THAT THE BUFFER OVERFLOWS. Deciding that needs the size of the ' +
+    'destination, the length of the source and the aliasing between them; this engine ' +
+    'tracks values, not sizes, so it cannot and does not decide it. What a flow-verified ' +
+    'finding here asserts is only that attacker-controlled data reached a copy with no ' +
+    'length bound. A copy into a destination that is genuinely large enough is a false ' +
+    'positive of this rule, and a declared one.',
+  shapes: ['call'],
+  support: {
+    c: {
+      status: 'partial',
+      note:
+        'PARTIAL BY CONSTRUCTION, and the limit is the point. Covers strcpy, stpcpy, ' +
+        'strcat and the sprintf family reached by attacker data, plus gets() on sight. ' +
+        'It does NOT model buffer sizes, so it cannot say whether any given copy ' +
+        'overflows - only that the copy has no bound. memcpy and friends with an ' +
+        'attacker-controlled LENGTH are a different bug (the size is the taint, not the ' +
+        'data) and are not covered. Use-after-free, double-free and integer overflow are ' +
+        'entirely out of scope: none of them is a data-flow question.',
+    },
+    cpp: {
+      status: 'partial',
+      note:
+        'Identical to C. std::string and std::vector manage their own storage and are ' +
+        'not matched; C++ code that calls the C string functions still is, and a great ' +
+        'deal of it 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;
+
+    if (UNCONDITIONALLY_UNSAFE.has(call.calleeName)) {
+      return {
+        node: call.node,
+        severity: 'high',
+        message: 'gets() cannot be called safely and was removed from the C standard',
+        reasoning:
+          'gets() reads a line from standard input into a buffer and takes no length ' +
+          'parameter, so there is no way to tell it how much room it has. The caller ' +
+          'cannot bound it, the function cannot bound itself, and the input comes from ' +
+          'outside the program. C11 removed it from the standard library rather than ' +
+          'attempt to document safe use. Replace it with fgets(buf, sizeof buf, stdin). ' +
+          'No data flow is traced for this finding because none is needed - the call is ' +
+          'unsafe with any input at all.',
+      };
+    }
+
+    const dataArgument = UNBOUNDED_COPIES.get(call.calleeName);
+    if (dataArgument === undefined) return null;
+
+    const source = call.args[dataArgument];
+    if (!source) return null;
+
+    /*
+     * A literal source is bounded at compile time - the compiler knows exactly
+     * how long `strcpy(buf, "ok")` writes. Reporting it would be noise on code
+     * that cannot be attacked, so the literal case returns null and only an
+     * opaque value is worth a signature guess.
+     */
+    if (isStringLiteral(source, ctx.language)) return null;
+
+    const sourceText = ctx.text(source);
+    return {
+      node: call.node,
+      message: `${call.calleeName}() copies \`${sourceText}\` with no length bound`,
+      reasoning:
+        `\`${call.calleeName}()\` writes until it meets a NUL byte in \`${sourceText}\`, and ` +
+        `nothing in the call says how much room the destination has. Whether this ` +
+        `actually overflows depends on the size of the destination, which is NOT analysed ` +
+        `here - so this is a guess about a risky shape, not a proof of a bug. Use ` +
+        `${call.calleeName === 'strcat' ? 'strncat' : 'strncpy'}() or strlcpy() with an ` +
+        `explicit length, and this finding goes away.`,
+    };
+  },
+};

package/src/rules/unsafe-deserialization.ts

@@ -0,0 +1,291 @@
+/**
+ * UNSAFE DESERIALIZATION  (CWE-502, OWASP A08:2025 - Software or Data Integrity Failures)
+ *
+ * WHAT THE BUG IS, in plain language:
+ * Serialising turns an object in memory into bytes you can store or send.
+ * Deserialising turns those bytes back into an object. The danger is in the
+ * word OBJECT: the bytes do not just carry data, they carry the NAME OF THE
+ * CLASS to rebuild, and rebuilding a class runs that class's code.
+ *
+ *     $session = unserialize($_COOKIE['session']);
+ *
+ * The attacker controls the cookie, so the attacker chooses which classes get
+ * constructed and with which fields. They then look through your code (and
+ * your libraries) for a class with a `__destruct`, `__wakeup` or `readObject`
+ * method that does something useful - deletes a file, writes a file, runs a
+ * command - and hand you an object designed to trigger it. Chaining a few of
+ * these together is called a POP CHAIN or a gadget chain, and the usual end
+ * result is remote code execution. No memory corruption, no exploit skill: the
+ * language does exactly what it was told.
+ *
+ * WHY THIS RULE IS DIFFERENT FROM THE OTHER INJECTION RULES:
+ * There is no "escaping" fix. You cannot sanitise attacker bytes into safe
+ * bytes, because the danger is the structure, not the characters. The real
+ * fixes are:
+ *
+ *   - Use a DATA format instead of an OBJECT format. `json_decode`,
+ *     `JSON.parse` and `json.loads` produce plain values and cannot construct
+ *     your classes. This is the right answer almost every time.
+ *   - If you must deserialise objects, restrict which classes are allowed
+ *     (`unserialize($x, ['allowed_classes' => false])`, `yaml.safe_load`,
+ *     a `MessageFormat` allowlist) - and this rule recognises those and stays
+ *     quiet, because reporting the hardened form would punish the fix.
+ *   - Sign the payload so you can tell it is yours before you open it.
+ *
+ * WHY IT TOOK A NEW SINK KIND:
+ * The engine's three existing kinds - sql, command, xss - all describe a
+ * string being read as instructions. This one is bytes being read as an
+ * object graph, so a SQL escaper or an HTML escaper means nothing here. Sink
+ * kinds are scoped for exactly this reason: `htmlspecialchars` on the way to
+ * `unserialize` clears nothing, and the engine has to know that.
+ */
+
+import type { LanguageId } from '../parse/languages.js';
+import { asCall, type Rule, type RuleHit } from './contract.js';
+
+/**
+ * Functions that turn bytes into OBJECTS.
+ *
+ * Deliberately excludes every JSON parser. `json_decode`, `JSON.parse` and
+ * `json.loads` return plain arrays, strings and numbers - they cannot name a
+ * class, so they cannot start a gadget chain. Listing them would bury the real
+ * findings under the single most common safe call in every codebase.
+ */
+const DESERIALIZERS: Record<LanguageId, readonly string[]> = {
+  // node-serialize and funcster revive functions from their payloads. The
+  // built-in JSON parser does not and is deliberately absent.
+  javascript: ['unserialize', 'deserialize'],
+  typescript: ['unserialize', 'deserialize'],
+  // pickle and marshal execute constructor code by design; yaml.load does too
+  // unless a safe Loader is named, which `unlessOption` checks for.
+  python: ['loads', 'load', 'Unpickler'],
+  // readObject is the classic Java gadget-chain entry point.
+  java: ['readObject', 'readUnshared', 'readResolve'],
+  php: ['unserialize'],
+  // Go's encoding/gob decodes into a type YOU name, so an attacker cannot
+  // choose the class to construct. That removes the gadget-chain shape this
+  // rule is about, which is why the list is empty rather than guessed at.
+  go: [],
+  // C has no object graph to revive, so the gadget-chain bug this rule is
+  // about cannot exist at all. Parsing untrusted binary in C IS dangerous, but
+  // for a completely different reason - it is where the memory-safety bugs
+  // live - and that is declared out of scope rather than half-covered here.
+  c: [],
+  cpp: [],
+};
+
+/**
+ * Receivers that make an otherwise-ambiguous method name unambiguous.
+ *
+ * `load` and `loads` are far too common to report on the name alone - every
+ * config reader in Python has one. Requiring a known-dangerous module in front
+ * of them is what separates `pickle.loads(data)` from `settings.loads(data)`.
+ */
+const REQUIRED_RECEIVERS: Record<LanguageId, readonly string[]> = {
+  javascript: ['serialize', 'node-serialize', 'funcster'],
+  typescript: ['serialize', 'node-serialize', 'funcster'],
+  python: ['pickle', 'cPickle', 'dill', 'marshal', 'yaml', 'shelve', 'jsonpickle'],
+  java: ['ois', 'objectInputStream', 'in', 'input', 'stream', 'decoder'],
+  php: [],
+  go: [],
+  c: [],
+  cpp: [],
+};
+
+/**
+ * Deserialisers whose payload arrives through the RECEIVER, not an argument.
+ * `ois.readObject()` reads from a stream that was loaded a line earlier, so
+ * there is no argument to inspect and the receiver check is the whole test.
+ */
+const ZERO_ARGUMENT_READERS: ReadonlySet<string> = new Set([
+  'readObject',
+  'readUnshared',
+  'readResolve',
+]);
+
+/** Calls that are safe BECAUSE of an argument, and must not be reported. */
+const SAFE_FORMS: Record<LanguageId, RegExp | null> = {
+  javascript: null,
+  typescript: null,
+  // yaml.load(x, Loader=SafeLoader) and yaml.safe_load are the hardened forms.
+  python: /\b(SafeLoader|CSafeLoader|BaseLoader|safe_load)\b/,
+  java: null,
+  // unserialize($x, ['allowed_classes' => false]) cannot construct your classes.
+  php: /allowed_classes/,
+  // Nothing to make safe, because nothing above is listed as dangerous.
+  c: null,
+  cpp: null,
+  go: null,
+};
+
+/**
+ * Does the receiver in front of this call identify a dangerous deserialiser?
+ * A language with no required receivers answers yes for everything, because
+ * its function names (`unserialize`, `readObject`) are already unambiguous.
+ */
+function receiverQualifies(language: LanguageId, receiverText: string): boolean {
+  const required = REQUIRED_RECEIVERS[language];
+  if (required.length === 0) return true;
+  const last = receiverText.split(/[.\s(]/).filter(Boolean).pop() ?? receiverText;
+  return required.some((name) => last === name || receiverText.includes(name));
+}
+
+export const unsafeDeserializationRule: Rule = {
+  id: 'unsafe-deserialization',
+  name: 'Untrusted bytes rebuilt into an object',
+  cwe: 'CWE-502',
+  owasp: 'A08:2025 Software or Data Integrity Failures',
+  severity: 'critical',
+  summary: 'Bytes are turned back into objects; if they come from outside, they can make the program run code the attacker picks.',
+  fix:
+    'Use a plain data format such as JSON, or restrict which classes may be loaded, or sign the data.',
+  explanation:
+    'Deserialising does not just read data - it names a class and rebuilds it, ' +
+    'which runs that class\'s code. Whoever controls the bytes therefore chooses ' +
+    'which objects your program constructs, and can chain together classes whose ' +
+    'destructors or wake-up methods do something useful to them. The usual end of ' +
+    'that chain is remote code execution. There is no escaping fix, because the ' +
+    'danger is the structure rather than the characters: use a data format such as ' +
+    'JSON, restrict which classes may be constructed, or sign the payload.',
+  limitations:
+    'UNVERIFIED (signature-based): we identified a call that rebuilds objects from ' +
+    'bytes and confirmed its argument is not a fixed literal. We did NOT confirm the ' +
+    'bytes are attacker-controlled - the data-flow pass is what upgrades this to ' +
+    'flow-verified, and it is worth waiting for, because deserialising your own ' +
+    'trusted data is ordinary and safe. Hardened forms are recognised and NOT ' +
+    'reported: unserialize with allowed_classes, and yaml with a Safe/Base Loader. ' +
+    'DELIBERATE GAP: that check reads the visible text of the call, so a Loader or ' +
+    'an options array assembled in another variable is missed and the finding still ' +
+    'fires. JSON parsers are deliberately excluded entirely - json_decode, JSON.parse ' +
+    'and json.loads return plain values and cannot name a class to construct. ' +
+    'Go is NOT covered: encoding/gob decodes into a type the PROGRAM names, so an ' +
+    'attacker cannot choose the class, and the gadget-chain shape does not arise.',
+  shapes: ['call'],
+  support: {
+    javascript: {
+      status: 'partial',
+      note: 'PARTIAL: node-serialize and funcster only, and only when called on a recognisable receiver. JSON.parse is deliberately excluded - it cannot construct a class. Most JavaScript deserialization risk lives in libraries with their own APIs that this does not model.',
+    },
+    typescript: {
+      status: 'partial',
+      note: 'PARTIAL: identical to JavaScript.',
+    },
+    python: {
+      status: 'implemented',
+      note: 'Covers pickle/cPickle/dill/marshal loads and load, yaml.load, shelve and jsonpickle, matched by module receiver so an ordinary settings.load() is not reported. yaml.load with a Safe/Base Loader is recognised as the hardened form and stays quiet.',
+    },
+    java: {
+      status: 'partial',
+      note: 'PARTIAL: ObjectInputStream.readObject/readUnshared, matched on a stream-looking receiver name. A stream stored under an unusual variable name is missed. XMLDecoder and SnakeYAML are NOT covered.',
+    },
+    php: {
+      status: 'implemented',
+      note: 'Covers unserialize(), the language\'s classic POP-chain entry point. unserialize($x, [\'allowed_classes\' => false]) is recognised as the hardened form and is not reported. json_decode is deliberately excluded.',
+    },
+    go: {
+      status: 'not-implemented',
+      note: 'NOT IMPLEMENTED: encoding/gob and encoding/json both decode into a type the program names, so an attacker cannot choose which class gets constructed. The gadget-chain shape this rule detects does not exist in Go, and a rule that fired here would be noise rather than coverage.',
+    },
+    c: {
+      status: 'not-implemented',
+      note:
+        'C has no object graph to revive, so the gadget-chain weakness this rule detects cannot exist. Parsing untrusted binary in C IS dangerous, but for memory-safety reasons that are declared out of scope rather than half-covered here.',
+    },
+    cpp: {
+      status: 'not-implemented',
+      note:
+        'Not implemented. C++ serialisation libraries - Boost.Serialization, cereal, protobuf - do reconstruct typed object graphs, and none of them is modelled here, so a gadget chain through Boost.Serialization is missed.',
+    },
+  },
+  check(shape, ctx): RuleHit | null {
+    const language = ctx.language;
+    const call = asCall(shape);
+    if (!call) return null;
+
+    const names = DESERIALIZERS[language];
+    if (!names.includes(call.calleeName)) return null;
+    if (!receiverQualifies(language, call.receiverText)) return null;
+
+    // The hardened form is the same call plus a restriction. Seeing the
+    // restriction means this is the fix, and reporting a fix teaches people
+    // that fixing does not help.
+    const safeForm = SAFE_FORMS[language];
+    if (safeForm && safeForm.test(call.node.text ?? '')) return null;
+
+    /*
+     * SOME DESERIALISERS TAKE NO ARGUMENTS.
+     *
+     *     Map<String,String> grant = (Map<String,String>) ois.readObject();
+     *
+     * The bytes were handed to the STREAM, one line earlier; `readObject()`
+     * just pulls the next object out of it. This rule required `args[0]` and
+     * therefore stayed silent on the single most famous gadget-chain entry
+     * point in Java - the exact call every CVE writeup about deserialization
+     * is about.
+     *
+     * Found by a Gemini-written test file. The taint engine already had this
+     * idea (`pb.command(list); pb.start()` - a sink whose payload was loaded
+     * earlier); the signature rule did not.
+     */
+    const argument = call.args[0];
+    if (!argument) {
+      if (!ZERO_ARGUMENT_READERS.has(call.calleeName)) return null;
+      return {
+        node: call.node,
+        message: `Untrusted bytes deserialised by ${call.calleeName}()`,
+        reasoning:
+          `\`${call.calleeName}()\` takes no arguments because the bytes were handed to ` +
+          `\`${call.receiverText || 'the stream'}\` earlier - it pulls the next object out of ` +
+          `that stream, and the bytes get to name the class it constructs. If the stream was ` +
+          `built from anything a caller controls, this is the classic Java gadget-chain entry ` +
+          `point. Validate and sign the payload before it reaches a stream, or use a data ` +
+          `format that cannot name a class.`,
+      };
+    }
+
+    /*
+     * A ROUND TRIP IS NOT AN INPUT.
+     *
+     *     pickle.loads(pickle.dumps(base))
+     *     json.loads(json.dumps(obj))
+     *
+     * Six of the sixteen deserialisation findings on a pandas scan were this,
+     * all in tests. Deserialising is dangerous because the BYTES come from
+     * somewhere else - a file, a socket, a cookie. Here they are produced two
+     * characters to the right, by this process, from a value this process
+     * already holds. There is no attacker position anywhere in the expression,
+     * and no amount of tracing will find one.
+     *
+     * The serialiser has to be visible as the DIRECT argument. `data = dumps(x)`
+     * on an earlier line then `loads(data)` still reports, because proving that
+     * one is the same round trip is a data-flow question, and this rule is not
+     * allowed to guess at data flow - that is what flow-verified means.
+     */
+    const argumentText = argument.text ?? '';
+    if (/^\s*(?:[\w.]+\.)?(?:dumps?|serialize|pack|marshal|encode)\s*\(/.test(argumentText)) {
+      return null;
+    }
+
+    // A fixed literal is your own data, not an attacker's. `unserialize('a:0:{}')`
+    // is a constant and cannot be chosen by anyone.
+    if (argument.type === 'string' || argument.type === 'encapsed_string') {
+      const interpolates = argument.namedChildren.some(
+        (c) => c !== null && c.type !== 'string_content' && c.type !== 'escape_sequence',
+      );
+      if (!interpolates) return null;
+    }
+
+    return {
+      node: call.node,
+      message: `Untrusted bytes deserialised by ${call.calleeName}()`,
+      reasoning:
+        `\`${call.calleeName}()\` rebuilds an object graph from bytes, which means the ` +
+        `bytes get to name the classes your program constructs. If any class reachable ` +
+        `from here has a destructor or wake-up method that touches the filesystem or ` +
+        `runs a command, an attacker who controls this input can chain them into code ` +
+        `execution. Escaping does not help - the danger is the structure, not the ` +
+        `characters. Parse it as data (JSON) instead, or restrict which classes may be ` +
+        `constructed.`,
+    };
+  },
+};