@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/dist/src/rules/lib/guards.d.ts

@@ -0,0 +1,168 @@
+/**
+ * VALIDATION GUARDS - cleanliness that lives in the control flow.
+ * ==============================================================
+ *
+ * Every sanitiser this engine knew about until now was value-in / value-out:
+ *
+ *     $safe = esc_html($dirty);        // takes a dirty value, returns a clean one
+ *
+ * A GUARD is a different shape. It transforms nothing and returns a boolean,
+ * and the fact it establishes is true only where the program can stand after
+ * that boolean came out a particular way:
+ *
+ *     if (is_numeric($octet[0]) && is_numeric($octet[1])) {
+ *         $target = $octet[0] . '.' . $octet[1];
+ *         shell_exec('ping ' . $target);        // <- cannot hold a metacharacter
+ *     }
+ *
+ * That is DVWA's `exec/impossible.php`, the author's deliberate FIX, and this
+ * scanner reported it for weeks. It is the seventh time this project has
+ * punished a fix.
+ *
+ * WHY THE BAR FOR A GUARD IS SO HIGH.
+ *
+ * A sanitiser rule that fires too often costs precision. A GUARD rule that
+ * fires too often costs SILENCE, and silence is the failure this scanner
+ * cannot detect in itself - a tool that has gone quiet looks exactly like a
+ * tool that has been fixed. This project has over-corrected before: the
+ * lowercase-word rejection that dropped the corpus from 48 findings to 32, and
+ * the mathjs.eval regression that was caught only because dvna's flow count
+ * fell from 3 to 2.
+ *
+ * So a check earns a place here on exactly one condition: being on the
+ * passing side of it must prove what the value can contain. Three strengths:
+ *
+ *     digits  only digits (is_numeric, ctype_digit, preg_match('/^\d+$/'))
+ *     word    only letters, digits and underscore (ctype_alnum, /^\w+$/)
+ *     fixed   only values the programmer wrote down ($x === 'png',
+ *             in_array($x, ['jpg', 'png'], true))
+ *
+ * and each one clears a different set of sinks - see guardClears(). A word is
+ * not enough for a SQL query unless it sits inside quotes (`WHERE id = id` is
+ * true for every row), so `word` hands SQL to the same quote check that
+ * escaping uses.
+ *
+ * These do NOT count, and they are the ones that look reassuring:
+ *
+ *     strlen($x) < 100        a hundred characters of `; rm -rf /` fits fine
+ *     $x !== ''               proves only that something is there
+ *     isset($x)               proves only that it exists
+ *     preg_match('/\d+/', $x) not anchored: "1; rm -rf /" contains a digit
+ *     preg_match('/^\d+$/m')  multi-line: "1\n; rm -rf /" has a line of digits
+ *     preg_match(...) !== 0   preg_match returns FALSE on an error, and
+ *                             false !== 0 - the error would pass as a match
+ *
+ * WHERE A FACT HOLDS (guardFactsAt):
+ *
+ *     if (CHECK) { here }                     the true branch
+ *     if (!CHECK) { ... } else { here }       the else of a negated check
+ *     if (!CHECK) { exit; }  here             after a branch that always leaves
+ *     CHECK ? here : not-here                 the matching arm of a ternary
+ *
+ * and only while the checked value is not written again: a write to it
+ * anywhere in that region - including the condition - drops the fact, because
+ * `if (is_numeric($x)) { $x = $_GET['y']; run($x); }` is a real injection. The
+ * walk also stops at a function boundary: a closure defined inside the branch
+ * may run long after the value changed.
+ *
+ * NOT covered, on purpose or not yet - each one only means a finding stays:
+ *   Java (no checks recognised at all yet); Python's `abort()` and other calls
+ *   that never return; compiled regex objects (`re.compile(...).fullmatch`,
+ *   `const re = /.../; re.test(x)`); `switch` on the value; a check whose
+ *   result was stored in a variable first; a closure or by-reference
+ *   parameter that rewrites the value from inside a called function.
+ *
+ * See safe/validated-guard.php and safe/allow-list-guards.* for the shapes this
+ * recognises, and vulnerable/weak-guard.php and vulnerable/allow-list-fence.*
+ * for the fence around them.
+ */
+import type { Node } from 'web-tree-sitter';
+import type { LanguageId } from '../../parse/languages.js';
+import type { SinkKind } from '../../taint/types.js';
+export type GuardStrength = 'digits' | 'word' | 'fixed' | 'quoted-literal';
+export interface GuardFact {
+    readonly strength: GuardStrength;
+    /** For `fixed`: the values the check lets through. */
+    readonly values?: readonly string[];
+    /** For `fixed`: the check compared a lower- or upper-cased copy. */
+    readonly caseFolded?: boolean;
+    /** A regex `$` in PHP or Python also lets one line break through after the value. */
+    readonly newlineTail?: boolean;
+    /** The check itself, for the path a reader sees. */
+    readonly check: Node;
+}
+/** Does this language have any checks this module recognises? */
+export declare const guardsApply: (language: LanguageId) => boolean;
+/** Which sinks a fact makes safe, and which of those only when the value lands inside quotes. */
+export declare const guardClears: (fact: GuardFact) => {
+    readonly kinds: readonly SinkKind[];
+    readonly insideQuotesOnly: readonly SinkKind[];
+};
+/** One sentence for the path: what the check proved. */
+export declare function describeFact(fact: GuardFact): string;
+/**
+ * The same expression written two ways must compare equal. DVWA writes
+ * `$_REQUEST[ 'ip' ]` with spaces and reads it back the same way, but a check
+ * written `$_GET["id"]` and a read written `$_GET['id']` are one value too.
+ */
+export declare function normalizeExpression(raw: string): string;
+/**
+ * What a whole-value regular expression lets through: 'digits', 'word',
+ * 'fixed' (a list of literal words, `/^(asc|desc)$/`), or null when anything
+ * else could pass - and null is the answer for everything this does not
+ * understand.
+ *
+ * The body may only be digits, letters, underscores, `\d`, `\w`, classes of
+ * those, groups, alternation INSIDE a group, and quantifiers. Top-level `|`
+ * is refused because it splits the anchors: `/^1|2$/` is "starts with 1" OR
+ * "ends with 2", and "1; rm -rf /" starts with 1.
+ *
+ * `$` lets one trailing newline through in PHP and Python (not in
+ * JavaScript, and not with PHP's D flag). A lone newline at the very end
+ * cannot open a quote or a tag, and is accepted - but it is recorded, so a
+ * fixed list is not vouched for inside a URL (see guardClears).
+ */
+export declare function regexAllowList(source: string, options: {
+    readonly flags?: string;
+    readonly implicitStart?: boolean;
+    readonly implicitEnd?: boolean;
+    readonly language: LanguageId;
+}): {
+    readonly strength: GuardStrength;
+    readonly values?: readonly string[];
+    readonly caseFolded?: boolean;
+    readonly newlineTail?: boolean;
+} | null;
+/**
+ * Every value a check proves something about, at this node. Keys are
+ * normalised expression texts (see normalizeExpression).
+ */
+export declare function guardFactsAt(node: Node, language: LanguageId): ReadonlyMap<string, GuardFact>;
+/**
+ * Are ALL the spliced parts of this expression proven safe by a check?
+ *
+ * Every part must be covered. That is deliberate and it is the lesson from the
+ * Jenkins escaper bug, where a sanitiser covering ONE value in an expression
+ * was allowed to vouch for a DIFFERENT value beside it. Here, one unchecked
+ * part means the whole expression still reports:
+ *
+ *     if (is_numeric($port)) { shell_exec('nc ' . $host . ' ' . $port); }
+ *                                                    ^^^^^ never checked
+ *
+ * One level of local indirection is followed, because the shape that matters
+ * rebuilds the value inside the branch:
+ *
+ *     $target = $octet[0] . '.' . $octet[1];    <- every piece checked here
+ *     shell_exec('ping ' . $target);            <- and used here
+ *
+ * A name counts when its value here certainly comes from one assignment: the
+ * last plain `name = ...` before this point, sitting directly in a block that
+ * also holds this point, with no other write to the name from that assignment
+ * to the end of the statement this point is in (so a loop cannot bring a
+ * different value round). And every piece of that one value was checked where
+ * it was assigned. DVWA writes `$target` twice - once from the request, once
+ * rebuilt from checked octets - so "assigned once in the function" was too
+ * strict, and "assigned somewhere in the branch" (the first version) never
+ * asked whether a later write replaced it.
+ */
+export declare function partsAreGuarded(node: Node, dynamicParts: readonly string[], language: LanguageId, kind: SinkKind): boolean;