@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/dist/src/taint/tracer.d.ts

@@ -0,0 +1,265 @@
+/**
+ * THE TAINT TRACER
+ * ================
+ *
+ * This is the engine that turns "signature-based" into "flow-verified".
+ *
+ * HOW IT WORKS, in one paragraph:
+ * We read each function body top to bottom, keeping a notebook of which
+ * variables currently hold dirty data. When a line assigns something, we work
+ * out whether the right-hand side is dirty and write that in the notebook. When
+ * a line calls something dangerous, we look up its arguments in the notebook.
+ * If a dirty value reaches a sink and no sanitiser washed it on the way, we can
+ * finally say the thing a pattern match never could: *this specific value, from
+ * this specific source, reaches this specific sink.* And we can show every hop.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO - each of these is a documented gap, not an
+ * oversight, and each is printed in the scan report:
+ *
+ *   1. BOUNDED REACH. Functions defined in this file are followed, and so are
+ *      functions in another file when a relative import resolves to it. What
+ *      still ends a trace: a call into a third-party package, a dynamic or
+ *      aliased import, a name several modules define (we decline rather than
+ *      guess), and any chain deeper than four calls. A cut at that depth, or at
+ *      a call that looks recursive, does NOT end the value: it is carried past
+ *      the unread call exactly as in 3 below, with the reason for the stop
+ *      written into the path.
+ *
+ *   2. STATEMENT ORDER, NOT BRANCH LOGIC. We read lines in order and ignore
+ *      whether an `if` is true. So a value cleaned only inside `if (isAdmin)`
+ *      is treated as cleaned afterwards. That direction of error loses findings
+ *      rather than inventing them, which is the right way to be wrong.
+ *
+ *   3. UNKNOWN FUNCTIONS CARRY TAINT, AND SAY SO. `foo(dirty)` keeps the taint
+ *      and records the hop as UNMODELLED, naming `foo` on the finding. Treating
+ *      unknowns as clean was tried first and produced ZERO verified flows across
+ *      2,766 Java files, every one a known vulnerability - so the quiet option
+ *      was not the honest one. This is the weakest link in any path we print,
+ *      which is exactly why it is printed rather than smoothed over.
+ *
+ *   4. CONTAINERS ARE TAINTED WHOLE. `list.add(dirty)` dirties the list, not
+ *      the slot - so a clean element read back out of that list is treated as
+ *      dirty too. Following values into objects at all requires this trade; the
+ *      alternative was the previous behaviour, which was to lose the value
+ *      entirely the moment it entered a StringBuilder or a List.
+ *
+ *   5. NO LOOP FIXPOINT. A variable that becomes dirty at the bottom of a loop
+ *      and is used at the top is missed on the first pass. Real analysers
+ *      iterate to a fixpoint; we do not, yet.
+ *
+ * Every one of those makes the tool MISS things (false negatives). None of them
+ * makes it invent things. That asymmetry is deliberate: a flow-verified label is
+ * a promise, and a promise that is sometimes wrong is worth less than no promise
+ * at all.
+ */
+import type { Node } from 'web-tree-sitter';
+import type { FlowStep } from '../core/finding.js';
+import type { LanguageId } from '../parse/languages.js';
+import type { ParsedFile } from '../parse/parser.js';
+import { type SinkKind, type TaintDictionary } from './types.js';
+/**
+ * A flow that reached a sink but was correctly sanitised on the way.
+ * Not a vulnerability - evidence that this line is fine.
+ */
+export interface SanitizedFlow {
+    readonly ruleId: string;
+    readonly kind: SinkKind;
+    readonly sinkNode: Node;
+    /** The file the sink is in - may not be the file being scanned. */
+    readonly filePath: string;
+    /**
+     * What made it clean, in words, with the line it happened on - the receipt.
+     * See cleanReason: a line printed as "checked and cleared" has to say what
+     * checked it.
+     */
+    readonly reason: string;
+    /**
+     * Functions Defuse does not model that the cleaned value passed through
+     * AFTER it was cleaned. Each was assumed to hand back what it was given; if
+     * one undoes the cleaning, the receipt is wrong, and it says so up front.
+     */
+    readonly assumes?: readonly string[];
+}
+/** One confirmed source-to-sink flow, ready to become a finding. */
+export interface FlowResult {
+    readonly ruleId: string;
+    readonly kind: SinkKind;
+    /** The exact tainted expression - what the finding points at. */
+    readonly node: Node;
+    /** The whole sink call or assignment - used to match up with signature findings. */
+    readonly sinkNode: Node;
+    readonly path: readonly FlowStep[];
+    readonly origin: string;
+    readonly sinkDescription: string;
+    /** Functions on the path that we do not model. Named on the finding. */
+    readonly unknownHops: readonly string[];
+    /**
+     * The value reached this sink only because a clean write was skipped for
+     * being conditional. The finding is still REPORTED - a missed bug is the one
+     * failure this scanner cannot see in itself - but it is reported as a guess,
+     * because a branch was assumed rather than followed. See branchAssumed.
+     */
+    readonly branchAssumed?: boolean;
+    /**
+     * The value reached this sink out of a collection that took several elements,
+     * so which one came back is a guess. Reported, not certified. See
+     * containerGuess.
+     */
+    readonly containerGuess?: boolean;
+    /**
+     * The value went through escaping that only protects inside quotes, and was
+     * put into the query somewhere this engine cannot read, so whether it is
+     * quoted is unknown. Reported, not certified - and not cleared either.
+     */
+    readonly quoteUnknown?: boolean;
+    /**
+     * An SSRF flow whose request cannot go where the attacker chooses: the value
+     * sits after a fixed start of the address (`path`, with that start), or the
+     * code runs in a browser, so the request is the user's own (`browser`).
+     * Reported as a guess with the reason, never as proven SSRF and never cleared.
+     */
+    readonly fixedDestination?: {
+        readonly kind: 'path' | 'browser';
+        readonly before: string;
+    } | undefined;
+    /**
+     * A path-traversal flow whose value comes only from the program's own
+     * command line, environment or terminal. Reported as a guess with the
+     * reason, never as proven: the person who chose the path can read the file.
+     */
+    readonly localSource?: boolean | undefined;
+    /** The file the sink is in - may not be the file being scanned. */
+    readonly filePath: string;
+}
+/** How a clean part of a string is written in a urlPrefix. */
+export declare const CLEAN_PART = "\u0001";
+/**
+ * Does the text before a value pin the destination of the address it is part
+ * of? Only when a path, query or fragment has already begun - after a host
+ * (`https://api.example.com/`), after a clean base (`${base}/`), or in a
+ * relative path (`./`, `../`, `/api/`, `docs/`).
+ *
+ * NOT pinned, and each is a real SSRF shape: nothing before the value; a
+ * scheme with the host still open (`https://`); a host with no slash after it
+ * (`https://api.example.com` + `@evil.example`); a clean base with nothing
+ * after it, which may itself end without a slash; `https:///`, where URL
+ * parsers skip the extra slash and the value becomes the host.
+ *
+ * One shape it cannot see: a clean base holding only a scheme with no slashes
+ * (`https:`) followed by `/` and the value - parsers read `https:/evil` as
+ * host `evil`. A configuration value shaped like that is rare enough to
+ * accept, and it is written down here rather than discovered later.
+ */
+export declare function destinationPinned(before: string): boolean;
+/** A function we can follow a value into. */
+export interface LocalFunction {
+    readonly name: string;
+    readonly params: readonly string[];
+    readonly body: Node;
+    /**
+     * How many arguments a call to this function may pass: fewer than minArgs or
+     * more than maxArgs and it cannot be this function. Recorded at indexing
+     * time, while the tree is hot - a cross-file target's tree may be evicted by
+     * the time a call to it is resolved. See ARITY_ENFORCED.
+     */
+    readonly minArgs?: number | undefined;
+    readonly maxArgs?: number | undefined;
+}
+/**
+ * Index every function in a tree by name. Exported because the cross-file
+ * resolver needs exactly the same view of another file that the tracer has of
+ * this one - if the two disagreed about what counts as a function, a value
+ * could be followed into something that is not there.
+ */
+export declare function collectFunctions(root: Node, language: LanguageId): Map<string, LocalFunction>;
+/**
+ * How the tracer asks "is there a function called X in a file this one imports?"
+ * Implemented by src/taint/project.ts; absent when scanning a single file.
+ */
+export interface CrossFileResolver {
+    resolve(fromPath: string, name: string): {
+        readonly path: string;
+        readonly fn: LocalFunction;
+    } | null;
+    /** Called when several files export that name and we refuse to guess. */
+    noteAmbiguous(fromPath: string, name: string, candidates: number): void;
+}
+/**
+ * Where this trace RAN OUT, counted.
+ *
+ * The engine has always documented these limits in prose - "call chains deeper
+ * than four functions are not followed" sits in the capability block on every
+ * scan. But a general disclaimer and a measurement are different products. The
+ * disclaimer says the gap could exist; the count says it happened 38 times in
+ * YOUR code, which is the version a person can act on.
+ *
+ * A comment in this file used to claim these were "recorded as misses". They
+ * were not - they returned null and vanished. Now the claim is true.
+ */
+export interface TraceLimits {
+    /** Calls not followed because the chain already ran four deep. */
+    readonly depthTruncations: number;
+    /** Calls not re-entered because the function was already on the stack. */
+    readonly recursionStops: number;
+    /** Hops through a function we do not model, where taint was carried anyway. */
+    readonly unmodelledHops: number;
+    /**
+     * How many distinct places an attacker-controlled SOURCE was recognised.
+     *
+     * This exists because of a silence. Elasticsearch - 3,999 Java files, a REST
+     * API, a network service - produced zero flow-verified findings, and the
+     * report had no way to say why. It contains 0 `@RequestParam` and 0
+     * `getParameter()`: it uses its own REST layer, which the dictionaries do not
+     * model, so the tracer never found a single source to start from.
+     *
+     * Every number in a report is downstream of this one. Zero sources means
+     * zero flows can exist no matter how good the tracer is, and a reader
+     * deserves to be told that rather than reading "0 flow-verified" as good news.
+     */
+    readonly sourcesFound: number;
+    /**
+     * Statements not walked because the syntax tree was nested deeper than the
+     * walk will go.
+     *
+     * Distinct from depthTruncations, which counts CALL chains. This one counts
+     * places where a single EXPRESSION was too deep - and it exists because a
+     * 25,809-file scan of the TypeScript repository died with "Maximum call stack
+     * size exceeded" on a file containing one expression with 1,499 `+` operators.
+     * The walk recursed 1,499 frames and took the process with it.
+     *
+     * A crash is the worst possible answer: it produces no report at all, so a
+     * whole scan is lost to one pathological file. Stopping is better - but only
+     * if we SAY we stopped, which is what this counter is for.
+     */
+    readonly astTruncations: number;
+}
+/**
+ * Code the tracer did not walk because a condition fixed at compile time means
+ * it cannot run - the dead arm of an `if`, a case a decided switch cannot
+ * reach. Not a finding, and not a proof about any one line: a record of a
+ * decision, so that a flow which disappeared because of it did not disappear
+ * silently.
+ */
+export interface UnreachableRegion {
+    readonly node: Node;
+    readonly filePath: string;
+    readonly why: string;
+}
+export interface TraceOutcome {
+    readonly flows: readonly FlowResult[];
+    readonly sanitized: readonly SanitizedFlow[];
+    readonly unreachable: readonly UnreachableRegion[];
+    /** Reads from a local map resolved to the one put that supplies them - see local-map.ts. */
+    readonly resolvedReads: readonly UnreachableRegion[];
+    /** Traces ended at a read whose result is new data - see FreshResultSpec. */
+    readonly freshStops: readonly UnreachableRegion[];
+    readonly limits: TraceLimits;
+}
+export declare function traceFile(file: ParsedFile, language: LanguageId, resolver?: CrossFileResolver, 
+/**
+ * Absolute path -> the path a human should see. Resolution needs absolute
+ * paths; reports need short ones. Keeping both straight matters more once a
+ * single finding can name two different files.
+ */
+toDisplay?: (absolutePath: string) => string): TraceOutcome;
+export { type TaintDictionary };