gitnexus 1.6.8-rc.9 → 1.6.8

package/dist/core/ingestion/taint/interproc-solver.js

@@ -0,0 +1,312 @@
+/**
+ * Interprocedural taint fixpoint (#2084 M4 U3).
+ *
+ * Composes per-function {@link FunctionSummary} objects over the resolved
+ * `CALLS` graph to find source→sink flows that cross function and file
+ * boundaries. PURE AND DETERMINISTIC (no graph, no I/O, no logger) — the phase
+ * builds the inputs from `ctx.graph` and persists the outputs.
+ *
+ * ## The model — whole-parameter taint reachability
+ *
+ * The unit of taint is `(function, parameter)`. The fixpoint computes the set
+ * of parameters that can hold source-derived data, then fires a finding
+ * whenever a tainted parameter feeds a modelled sink (`paramToSink`).
+ *
+ * - **Seeds** — every `sourceToCallArg` edge: a function generates a source and
+ *   passes it into argument `argIndex` of a call at `callLine`. Resolving that
+ *   call site against the caller's outgoing `CALLS` edges yields the callee;
+ *   the callee's parameter `argIndex` becomes tainted, with the generating
+ *   function recorded as the flow's source.
+ * - **Propagation** — every `paramToCallArg` edge of a function whose parameter
+ *   is ALREADY tainted: `param i → arg j of callee` taints the callee's
+ *   parameter `j` (TITO composition). Iterated to a fixpoint.
+ * - **Findings** — whenever a parameter becomes tainted and the owning
+ *   function's `paramToSink` contains that parameter, a cross-function finding
+ *   is emitted (source function → sink function, with the kind).
+ *
+ * ## Cycle safety (recursion)
+ *
+ * The tainted-parameter set is monotone over a FINITE lattice (`Σ functions ×
+ * params`), so the worklist fixpoint converges: a recursive or mutually
+ * recursive call merely re-proposes an already-tainted parameter, which the
+ * visited-set absorbs — no infinite descent. This is the functional/summary
+ * method's standard termination argument (Sharir-Pnueli; Pysa, Mariana Trench,
+ * and Infer all rely on it). SCC condensation would only refine the PROCESSING
+ * ORDER; correctness and termination do not require it.
+ *
+ * ## Context-insensitivity & the name-join over-approximation
+ *
+ * One summary per function, applied at every call site — return/param merging
+ * is accepted (the security-conservative direction). The call-arg→callee join
+ * is by callee NAME (not line), so when one caller invokes two DISTINCT
+ * same-named callees (`x.handler(src)` and `y.handler(clean)`), a source that
+ * flowed into ONE of them taints BOTH callees' parameter — an extra finding on
+ * the callee the source did not reach. This is sound (over-attribution, never a
+ * missed flow — the conservative direction for a security tool) and is the
+ * documented price of dropping the fragile line-based join; the `explain` tool
+ * surfaces it ("may over-attribute among same-named callees"). Other known
+ * precision losses (call-site conflation, shared dispatch, callbacks) are the
+ * documented M4 trade-offs; refinements are deferred (plan KTD).
+ */
+export const DEFAULT_MAX_INTERPROC_HOPS = 32;
+/**
+ * Default per-run cap on cross-function findings (#2084 review P1-3). Like the
+ * other pdg caps it is resolved into `RepoMeta.pdg` so `pdgModeMismatch`
+ * stamps it; `0` ⇒ unlimited. 2000 is generous for a real repo — more deduped
+ * `(source, sink, kind)` findings than that is a fixture or a runaway fan-in,
+ * and the overflow is deterministic + counted (`droppedFindings`).
+ */
+export const DEFAULT_PDG_MAX_INTERPROC_FINDINGS = 2000;
+/**
+ * Taint-state key — `(function, parameter, SOURCE)`. The source discriminator
+ * is load-bearing: without it, a parameter tainted by source A is marked
+ * visited and a later flow from source B to the SAME parameter is dropped
+ * before it can fire that function's sink, silently losing B→sink (the
+ * multi-source collapse — the recurring M3 bug class). Including the source
+ * keeps each origin's flow independent; the lattice stays finite (`fn × param ×
+ * source`), so the monotone worklist still terminates and is cycle-safe.
+ */
+const pkey = (fnId, param, sourceFnId) => `${fnId}#${param}#${sourceFnId}`;
+/**
+ * Run the interprocedural taint fixpoint. `summaries` is keyed by function node
+ * id; `callEdges` is the resolved `CALLS` graph (caller→callee with call-site
+ * lines). Deterministic: inputs in, sorted findings out.
+ */
+export function solveInterprocTaint(summaries, callEdges, limits) {
+    const maxHops = limits?.maxHops && limits.maxHops > 0 ? limits.maxHops : DEFAULT_MAX_INTERPROC_HOPS;
+    // Adjacency built ONCE (#2084 review P3-8): callerId → outgoing edges, AND
+    // callerId → calleeName → edges. The summary's call-arg edges resolve by
+    // callee NAME, so the per-name index turns each resolution into an O(1)
+    // lookup instead of a per-worklist-step `.filter` allocation (the
+    // build-index-once pattern).
+    const callsByCaller = new Map();
+    const callsByCallerName = new Map();
+    for (const e of callEdges) {
+        const list = callsByCaller.get(e.callerId);
+        if (list)
+            list.push(e);
+        else
+            callsByCaller.set(e.callerId, [e]);
+        let byName = callsByCallerName.get(e.callerId);
+        if (!byName) {
+            byName = new Map();
+            callsByCallerName.set(e.callerId, byName);
+        }
+        const named = byName.get(e.calleeName);
+        if (named)
+            named.push(e);
+        else
+            byName.set(e.calleeName, [e]);
+    }
+    let unmatchedCallSites = 0;
+    /** Edges to `name` from `callerId` (O(1)); empty if none — non-counting. */
+    const calleesByName = (callerId, name) => callsByCallerName.get(callerId)?.get(name) ?? [];
+    // Resolve a caller's call-arg edge (by callee name) to concrete callee edges.
+    // An unknown callee name (chain not statically resolvable) conservatively
+    // matches EVERY outgoing call — sound over-approximation (may over-taint).
+    const resolveCallees = (callerId, calleeName) => {
+        const candidates = callsByCaller.get(callerId);
+        if (!candidates || candidates.length === 0) {
+            unmatchedCallSites++;
+            return [];
+        }
+        if (calleeName === undefined)
+            return candidates;
+        const named = calleesByName(callerId, calleeName);
+        if (named.length === 0) {
+            unmatchedCallSites++;
+            return [];
+        }
+        return named;
+    };
+    // ── findings + worklist ───────────────────────────────────────────────────
+    const findingsByKey = new Map();
+    const tainted = new Map();
+    const queue = [];
+    const recordFinding = (sourceFnId, sinkFnId, sinkKind, hops, truncated) => {
+        const key = `${sourceFnId}|${sinkFnId}|${sinkKind}`;
+        if (findingsByKey.has(key))
+            return;
+        findingsByKey.set(key, { sourceFnId, sinkFnId, sinkKind, hops, hopsTruncated: truncated });
+    };
+    /** Fire every `paramToSink` of `tp`'s param, except kinds it neutralised. */
+    const fireSinks = (tp) => {
+        const summary = summaries.get(tp.fnId);
+        if (!summary)
+            return;
+        for (const ps of summary.paramToSink) {
+            if (ps.param !== tp.paramIndex)
+                continue;
+            if (tp.neutralized.has(ps.sinkKind))
+                continue; // sanitised across the boundary (P1-2)
+            // `tp.hops` already terminates at this (tainted) function — it IS the
+            // source→sink chain, no extra hop to append.
+            recordFinding(tp.sourceFnId, tp.fnId, ps.sinkKind, tp.hops, tp.truncated);
+        }
+    };
+    /**
+     * Mark (fnId, paramIndex, source) tainted; enqueue. On a fresh key, taint +
+     * fire sinks. On revisit, INTERSECT the neutralised set (a kind stays
+     * neutralised only if EVERY path neutralises it — the sound direction); if it
+     * shrank, re-enqueue + re-fire so a less-neutralised path's sinks surface
+     * (the shrink-reprocess guard, mirroring `propagate.ts:deriveTaint`). Without
+     * it, a first more-neutralised path would freeze out a real finding (FN).
+     */
+    const taint = (tp) => {
+        const key = pkey(tp.fnId, tp.paramIndex, tp.sourceFnId);
+        const existing = tainted.get(key);
+        if (existing) {
+            const inter = new Set();
+            for (const k of existing.neutralized)
+                if (tp.neutralized.has(k))
+                    inter.add(k);
+            if (inter.size >= existing.neutralized.size)
+                return; // no shrink — cycle-safe
+            const merged = { ...existing, neutralized: inter };
+            tainted.set(key, merged);
+            queue.push(merged);
+            fireSinks(merged);
+            return;
+        }
+        tainted.set(key, tp);
+        queue.push(tp);
+        fireSinks(tp);
+    };
+    // ── seeds: every source→callee-arg, resolved against CALLS ────────────────
+    for (const [callerId, summary] of summaries) {
+        for (const sc of summary.sourceToCallArg) {
+            for (const edge of resolveCallees(callerId, sc.calleeName)) {
+                const callee = summaries.get(edge.calleeId);
+                if (!callee)
+                    continue;
+                if (sc.argIndex >= callee.paramCount)
+                    continue; // arity guard
+                // Build the seed path through the capped append so `maxHops` truncates
+                // the prefix (#2084 review P2-7), not a 2-entry path flagged truncated.
+                const seed = appendHop([{ fnId: callerId }], { fnId: edge.calleeId, callLine: sc.callLine, argIndex: sc.argIndex }, maxHops);
+                taint({
+                    fnId: edge.calleeId,
+                    paramIndex: sc.argIndex,
+                    sourceFnId: callerId,
+                    hops: seed.hops,
+                    truncated: seed.truncated,
+                    neutralized: new Set(sc.neutralized ?? []),
+                });
+            }
+        }
+    }
+    // ── generative return composition (#2084 review P1-1) ─────────────────────
+    // `genReturns` = functions whose RETURN carries a generated source. Seed with
+    // `sourceToReturn`; a caller that returns the result of a generative call is
+    // itself generative (transitive — `wrap(){ return getInput() }`). Small
+    // monotone fixpoint over the name-resolved call graph (`calleesByName`).
+    const genReturns = new Set();
+    for (const [id, s] of summaries)
+        if (s.sourceToReturn.length > 0)
+            genReturns.add(id);
+    let grChanged = true;
+    while (grChanged) {
+        grChanged = false;
+        for (const [callerId, s] of summaries) {
+            if (genReturns.has(callerId))
+                continue;
+            for (const cr of s.callResults) {
+                if (cr.dest.to !== 'return')
+                    continue;
+                if (calleesByName(callerId, cr.calleeName).some((e) => genReturns.has(e.calleeId))) {
+                    genReturns.add(callerId);
+                    grChanged = true;
+                    break;
+                }
+            }
+        }
+    }
+    // Compose: a caller using a generative call's result either FIRES (the result
+    // hits a sink) or SEEDS (the result flows into another call's arg). The
+    // generated source's origin is the generative callee.
+    for (const [callerId, s] of summaries) {
+        for (const cr of s.callResults) {
+            const generative = calleesByName(callerId, cr.calleeName).filter((e) => genReturns.has(e.calleeId));
+            if (generative.length === 0)
+                continue;
+            for (const g of generative) {
+                const d = cr.dest;
+                if (d.to === 'sink') {
+                    recordFinding(g.calleeId, callerId, d.sinkKind, [{ fnId: g.calleeId }, { fnId: callerId }], 2 > maxHops);
+                }
+                else if (d.to === 'callArg') {
+                    for (const tc of d.toCallee === undefined
+                        ? (callsByCaller.get(callerId) ?? [])
+                        : calleesByName(callerId, d.toCallee)) {
+                        const callee = summaries.get(tc.calleeId);
+                        if (!callee || d.argIndex >= callee.paramCount)
+                            continue;
+                        // Capped successive append so `maxHops` truncates the prefix (P2-7).
+                        const h1 = appendHop([{ fnId: g.calleeId }], { fnId: callerId }, maxHops);
+                        const h2 = appendHop(h1.hops, { fnId: tc.calleeId, argIndex: d.argIndex }, maxHops);
+                        taint({
+                            fnId: tc.calleeId,
+                            paramIndex: d.argIndex,
+                            sourceFnId: g.calleeId,
+                            hops: h2.hops,
+                            truncated: h1.truncated || h2.truncated,
+                            neutralized: new Set(),
+                        });
+                    }
+                }
+                // dest:'return' is already folded into `genReturns` above.
+            }
+        }
+    }
+    // ── propagation worklist ──────────────────────────────────────────────────
+    let head = 0;
+    while (head < queue.length) {
+        const tp = queue[head++];
+        const summary = summaries.get(tp.fnId);
+        if (!summary)
+            continue;
+        // This function's tainted param flows into callee args via paramToCallArg.
+        for (const pc of summary.paramToCallArg) {
+            if (pc.param !== tp.paramIndex)
+                continue;
+            for (const edge of resolveCallees(tp.fnId, pc.calleeName)) {
+                const callee = summaries.get(edge.calleeId);
+                if (!callee)
+                    continue;
+                if (pc.argIndex >= callee.paramCount)
+                    continue;
+                const next = appendHop(tp.hops, { fnId: edge.calleeId, callLine: pc.callLine, argIndex: pc.argIndex }, maxHops);
+                // Union the edge's neutralised kinds onto the composed path (a
+                // sanitizer between this param and the callee arg stays neutralised).
+                const neutralized = pc.neutralized && pc.neutralized.length > 0
+                    ? new Set([...tp.neutralized, ...pc.neutralized])
+                    : tp.neutralized;
+                taint({
+                    fnId: edge.calleeId,
+                    paramIndex: pc.argIndex,
+                    sourceFnId: tp.sourceFnId,
+                    hops: next.hops,
+                    truncated: tp.truncated || next.truncated,
+                    neutralized,
+                });
+            }
+        }
+    }
+    // ── deterministic assembly ────────────────────────────────────────────────
+    const all = [...findingsByKey.values()].sort((a, b) => a.sourceFnId.localeCompare(b.sourceFnId) ||
+        a.sinkFnId.localeCompare(b.sinkFnId) ||
+        a.sinkKind.localeCompare(b.sinkKind));
+    const maxFindings = limits?.maxFindings && limits.maxFindings > 0 ? limits.maxFindings : Infinity;
+    const findings = all.length > maxFindings ? all.slice(0, maxFindings) : all;
+    return {
+        findings,
+        droppedFindings: all.length - findings.length,
+        unmatchedCallSites,
+    };
+}
+/** Append a hop, respecting the hop cap (keeps the source-side prefix). */
+function appendHop(hops, hop, maxHops) {
+    if (hops.length >= maxHops)
+        return { hops, truncated: true };
+    return { hops: [...hops, hop], truncated: hops.length + 1 > maxHops };
+}

package/dist/core/ingestion/taint/match.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Import-aware taint-site matcher (#2083 M3 U2, plan KTD7).
+ *
+ * Classifies a function's harvested {@link SiteRecord}s against a registered
+ * {@link SourceSinkSanitizerSpec}: which member reads are SOURCES, which
+ * call/new sites are SINKS (and at which argument positions), and which are
+ * SANITIZERS. Pure main-thread data work — sites + bindings come from the U1
+ * worker harvest, imports from `ParsedFile.parsedImports`; no AST, no I/O.
+ *
+ * PRECONDITION: the caller must gate the CFG through `hasTaintSafeSites`
+ * (taint/site-safety.ts) first — this module dereferences binding/site
+ * indices without re-validating them.
+ *
+ * ## Callee resolution precedence (bare and member-rooted calls)
+ *
+ * 1. ESM import join — the callee root's local name is resolved through the
+ *    {@link TaintImportIndex} built from `parsedImports` (`named`/`alias`
+ *    members, `namespace`/default-import module handles); `import { exec as
+ *    run } from 'child_process'` makes `run(c)` resolve to
+ *    `child_process.exec`, and `import * as cp …` makes `cp.exec(c)` resolve
+ *    the same way.
+ * 2. require-literal join — a binding whose in-function defining site carries
+ *    `requireArg` resolves like a namespace handle (`const cp =
+ *    require('child_process'); cp.exec(c)`). A BARE call of a require-joined
+ *    binding is matched under BOTH interpretations, `<module>.default` (the
+ *    module/default export invoked directly) and `<module>.<localName>`
+ *    (non-renamed destructured require — the harvest attaches `resultDefs`
+ *    to destructured bindings without recording the property path, and the
+ *    binding name IS the member name in the non-renamed case).
+ * 3. Bare-name fallback — TRUE GLOBALS only (`global: true` entries: `eval`,
+ *    `new Function`, `encodeURIComponent`), and only when the name is neither
+ *    import-bound nor shadowed. Conventional receiver names (`req`/`request`
+ *    member-read sources, `res.send`, `.query`/`.execute`) are matched
+ *    name-based by their own mechanisms, never via the global fallback.
+ *
+ * ## Shadowing rule (exact)
+ *
+ * A name is treated as function-local — blocking import/global resolution —
+ * iff the function's binding table contains a NON-`synthetic` entry with that
+ * name (an in-function `function exec(){}` / `const exec = …`). Synthetic
+ * bindings (kind `module`, `synthetic: true`) are imports, true globals, or
+ * enclosing-scope captures and do not shadow. Member-call roots use the
+ * harvested `receiver` binding index directly (no name scan).
+ *
+ * ## Documented resolution gaps (direction stated, per plan KTD10)
+ *
+ * - MODULE-LEVEL `const cp = require('child_process')`: the binding is
+ *   synthetic inside the function, produces no `ParsedImport`, and its
+ *   defining site lives outside the function's harvested sites — the
+ *   require join cannot see it. Module-mechanism sinks miss (FN) and
+ *   sanitizers don't kill (FP noise — never a false kill, the safe
+ *   direction). Only in-function requires resolve.
+ * - RENAMED destructured require (`const { exec: run } = require(…)`):
+ *   the dual interpretation resolves `run` to `child_process.run` — no
+ *   match (FN). Non-renamed destructures resolve exactly.
+ * - CONSERVATIVE shadow scan for bare calls: ANY non-synthetic binding of
+ *   the callee name anywhere in the function blocks import/global
+ *   resolution, even when the shadow is block-scoped elsewhere and the call
+ *   site actually sees the import (FN; rare; safe for sanitizers).
+ * - MODULE-LEVEL user declarations are indistinguishable from imports in
+ *   the binding table (both synthetic). ESM forbids a module-level
+ *   declaration colliding with an import name, so the import join is
+ *   authoritative when an import exists; a module-level user function
+ *   shadowing a TRUE GLOBAL (e.g. a local `encodeURIComponent`) is not
+ *   detectable and would still match (pathological; accepted).
+ * - Handle COPIES (`const c2 = cp; c2.exec(…)`) are not followed — joins
+ *   are one level deep (binding → import/require), never through
+ *   assignments (FN).
+ * - `this.`/`super.`-rooted and call-rooted callee chains have no
+ *   resolvable root: only the syntactic `anyReceiver`/`receivers`
+ *   mechanisms can match them.
+ * - `reexport`/`wildcard`/`dynamic-*`/`side-effect` imports introduce no
+ *   matcher-visible local binding and are skipped by the index.
+ */
+import type { ParsedImport } from '../../../_shared/index.js';
+import type { FunctionCfg } from '../cfg/types.js';
+import type { SourceSinkSanitizerSpec, TaintMemberSourceEntry, TaintSanitizerEntry, TaintSinkEntry } from './source-sink-config.js';
+/** What a local name imported into the file denotes. */
+export interface TaintImportBinding {
+    /** Normalized module specifier (`node:` scheme stripped). */
+    readonly module: string;
+    /**
+     * Exported member bound by a named/aliased import; `undefined` when the
+     * local name is a MODULE HANDLE (namespace import, or a default import —
+     * CJS interop makes the default export ≈ the module object).
+     */
+    readonly member?: string;
+}
+/** Local name → import provenance for one file. Build once per file (U4). */
+export type TaintImportIndex = ReadonlyMap<string, TaintImportBinding>;
+/** A member-read site matched as a taint source. */
+export interface MatchedSourceRead {
+    /** Index into the owning statement's `sites` array. */
+    readonly siteIndex: number;
+    readonly entry: TaintMemberSourceEntry;
+}
+/** A call/new site matched as a sink. */
+export interface MatchedSinkCall {
+    /** Index into the owning statement's `sites` array. */
+    readonly siteIndex: number;
+    readonly entry: TaintSinkEntry;
+    /**
+     * Positions (indices into `site.args`) that are registered sink positions
+     * AND carry at least one recorded binding occurrence, after the spread
+     * rule (a recorded position ≥ `site.spread` matches when any registered
+     * position ≥ the spread index exists — runtime positions after a spread
+     * are unknowable) and the template rule (`template: true` aggregates all
+     * substitutions at position 0 and matches any-position). Never empty — a
+     * sink whose dangerous positions carry no occurrences cannot produce a
+     * finding and is not reported.
+     */
+    readonly argPositions: readonly number[];
+}
+/** A call site matched as a sanitizer (import-aware/global only — see module doc). */
+export interface MatchedSanitizerCall {
+    /** Index into the owning statement's `sites` array. */
+    readonly siteIndex: number;
+    readonly entry: TaintSanitizerEntry;
+    /**
+     * Bindings the sanitizer's result defines directly (`const b = escape(t)`
+     * ⇒ `b`) — U3's kill targets (KTD4b). Empty for value-position sanitizer
+     * calls (`exec(escape(x))`), whose effect is occurrence INTERPOSITION via
+     * the site's `parent`/via-tag chain, not a def kill.
+     */
+    readonly resultDefs: readonly number[];
+}
+/** All matches within one statement. Emitted only when at least one list is non-empty. */
+export interface StatementMatches {
+    readonly blockIndex: number;
+    readonly statementIndex: number;
+    readonly line: number;
+    readonly sources: readonly MatchedSourceRead[];
+    readonly sinks: readonly MatchedSinkCall[];
+    readonly sanitizers: readonly MatchedSanitizerCall[];
+}
+/** Classified sites for one function, in (block, statement, site, entry) order. */
+export interface FunctionSiteMatches {
+    readonly statements: readonly StatementMatches[];
+    /** Fast-path gates for U4: the solver runs only when both are true. */
+    readonly hasSource: boolean;
+    readonly hasSink: boolean;
+}
+/**
+ * Build the local-name → module/member index from a file's `parsedImports`.
+ * Only `named`/`alias`/`namespace` kinds bind matcher-visible local names;
+ * `importedName === 'default'` collapses to a module handle.
+ */
+export declare function buildTaintImportIndex(imports: readonly ParsedImport[]): TaintImportIndex;
+/**
+ * Classify a function's harvested sites against a language spec. See the
+ * module doc for resolution precedence, the shadowing rule, and gaps.
+ */
+export declare function matchFunctionSites(cfg: FunctionCfg, spec: SourceSinkSanitizerSpec, imports: TaintImportIndex): FunctionSiteMatches;