circle-ir 3.151.0 → 3.153.0

package/dist/analysis/passes/library-profile-sink-gate-pass.d.ts

@@ -0,0 +1,89 @@
+/**
+ * LibraryProfileSinkGatePass — cognium-dev #232
+ *
+ * Sink-side companion to `LibraryProfileSourceGatePass` (#236,
+ * shipped 3.151.0). Under the `library/*` project profile, drops
+ * sinks whose entire vulnerability class is off-topic for library
+ * code — currently just `log_injection` (CWE-117).
+ *
+ * Motivation:
+ *
+ *   `log_injection` requires a downstream log-viewer that interprets
+ *   attacker-controlled log content — the exploit ("log forging",
+ *   HTML/ANSI injection into a log renderer, log-based privilege
+ *   escalation) is exercised at the application-integration boundary,
+ *   not inside a library. A library that calls `Logger.info(x)` where
+ *   `x` originated from an HTTP parameter has not committed a defect:
+ *   the consuming application decides where those log records are
+ *   rendered and how their content is escaped.
+ *
+ *   Empirically, `log_injection` was ~10% of H+C findings on the
+ *   Tier 2 8-repo library cohort (402 findings in the audit
+ *   summarised in cognium-ai#189 §1). The signal is systemically
+ *   noisy for library code and provides no actionable
+ *   application-security value.
+ *
+ * Where #236 dropped speculative `interprocedural_param` sources
+ * (which removed the entire `external_taint_escape` Scenario-B
+ * synthesis path), this pass drops the sinks themselves. `log_injection`
+ * has real, non-speculative sources (`http_param`, `env_input`,
+ * `db_input`, …) that flow into concrete sink calls (`Logger.info`,
+ * `logging.info`, `console.log`, …); the source-side gate does not
+ * remove them. The *sink class* is what is off-topic here.
+ *
+ * Pipeline slot: runs after `CliMainReflectionSuppressPass` (so
+ * every sink-side categorisation / suppression pass fires first)
+ * and before `TaintPropagationPass` (so no dropped sink ever
+ * reaches the flow generators).
+ *
+ * Guardrails:
+ *   - Pass is a no-op when `graph.ir.meta.projectProfile` is absent,
+ *     `'unknown'`, or does not start with `library/`. Callers that do
+ *     not opt in to profile detection get the unmodified sink list.
+ *   - Only `log_injection` is eligible in 3.152.0. Every other
+ *     `SinkType` (`sql_injection`, `command_injection`, `xss`,
+ *     `path_traversal`, `deserialization`, …) is preserved
+ *     unconditionally. Extending the drop set is a deliberate
+ *     one-line change in `DROPPED_SINK_TYPES`.
+ *   - Guarded on `disabledPasses.has('library-profile-sink-gate')`
+ *     at the pipeline registration site.
+ *
+ * Scope note (Rust log macros): `LanguageSourcesPass` emits
+ * `rule_id: 'log_injection'` findings directly for Rust log macros
+ * (`info!`, `println!`, `eprintln!`, …). Those findings bypass the
+ * sink pipeline entirely and therefore bypass this pass. Deferred
+ * to a follow-up if the harness rerun shows material Rust
+ * residuals; the Tier 2 8-repo cohort is Java-heavy.
+ */
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+import type { ProjectProfile, SinkType } from '../../types/index.js';
+export interface LibraryProfileSinkGateResult {
+    /**
+     * Resolved `ProjectProfile` observed on `graph.ir.meta.projectProfile`
+     * at the time this pass ran. `undefined` when no profile was
+     * supplied by the caller.
+     */
+    profile: ProjectProfile | undefined;
+    /**
+     * Whether the profile matched the library-shape trigger and the
+     * gate was applied. `false` for every non-library shape and for
+     * `'unknown'` / absent profiles.
+     */
+    applied: boolean;
+    /**
+     * Number of sinks removed from the authoritative sink list. Zero
+     * when `applied === false`.
+     */
+    dropped: number;
+    /**
+     * Breakdown of drops by `SinkType`. Empty object when
+     * `applied === false`.
+     */
+    droppedByType: Partial<Record<SinkType, number>>;
+}
+export declare class LibraryProfileSinkGatePass implements AnalysisPass<LibraryProfileSinkGateResult> {
+    readonly name = "library-profile-sink-gate";
+    readonly category: "security";
+    run(ctx: PassContext): LibraryProfileSinkGateResult;
+}
+//# sourceMappingURL=library-profile-sink-gate-pass.d.ts.map

package/dist/analysis/passes/library-profile-sink-gate-pass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"library-profile-sink-gate-pass.d.ts","sourceRoot":"","sources":["../../../src/analysis/passes/library-profile-sink-gate-pass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAa,MAAM,sBAAsB,CAAC;AAYhF,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,SAAS,CAAC;IACpC;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAaD,qBAAa,0BACX,YAAW,YAAY,CAAC,4BAA4B,CAAC;IAErD,QAAQ,CAAC,IAAI,+BAA+B;IAC5C,QAAQ,CAAC,QAAQ,EAAG,UAAU,CAAU;IAExC,GAAG,CAAC,GAAG,EAAE,WAAW,GAAG,4BAA4B;CA0DpD"}

package/dist/analysis/passes/library-profile-sink-gate-pass.js

@@ -0,0 +1,132 @@
+/**
+ * LibraryProfileSinkGatePass — cognium-dev #232
+ *
+ * Sink-side companion to `LibraryProfileSourceGatePass` (#236,
+ * shipped 3.151.0). Under the `library/*` project profile, drops
+ * sinks whose entire vulnerability class is off-topic for library
+ * code — currently just `log_injection` (CWE-117).
+ *
+ * Motivation:
+ *
+ *   `log_injection` requires a downstream log-viewer that interprets
+ *   attacker-controlled log content — the exploit ("log forging",
+ *   HTML/ANSI injection into a log renderer, log-based privilege
+ *   escalation) is exercised at the application-integration boundary,
+ *   not inside a library. A library that calls `Logger.info(x)` where
+ *   `x` originated from an HTTP parameter has not committed a defect:
+ *   the consuming application decides where those log records are
+ *   rendered and how their content is escaped.
+ *
+ *   Empirically, `log_injection` was ~10% of H+C findings on the
+ *   Tier 2 8-repo library cohort (402 findings in the audit
+ *   summarised in cognium-ai#189 §1). The signal is systemically
+ *   noisy for library code and provides no actionable
+ *   application-security value.
+ *
+ * Where #236 dropped speculative `interprocedural_param` sources
+ * (which removed the entire `external_taint_escape` Scenario-B
+ * synthesis path), this pass drops the sinks themselves. `log_injection`
+ * has real, non-speculative sources (`http_param`, `env_input`,
+ * `db_input`, …) that flow into concrete sink calls (`Logger.info`,
+ * `logging.info`, `console.log`, …); the source-side gate does not
+ * remove them. The *sink class* is what is off-topic here.
+ *
+ * Pipeline slot: runs after `CliMainReflectionSuppressPass` (so
+ * every sink-side categorisation / suppression pass fires first)
+ * and before `TaintPropagationPass` (so no dropped sink ever
+ * reaches the flow generators).
+ *
+ * Guardrails:
+ *   - Pass is a no-op when `graph.ir.meta.projectProfile` is absent,
+ *     `'unknown'`, or does not start with `library/`. Callers that do
+ *     not opt in to profile detection get the unmodified sink list.
+ *   - Only `log_injection` is eligible in 3.152.0. Every other
+ *     `SinkType` (`sql_injection`, `command_injection`, `xss`,
+ *     `path_traversal`, `deserialization`, …) is preserved
+ *     unconditionally. Extending the drop set is a deliberate
+ *     one-line change in `DROPPED_SINK_TYPES`.
+ *   - Guarded on `disabledPasses.has('library-profile-sink-gate')`
+ *     at the pipeline registration site.
+ *
+ * Scope note (Rust log macros): `LanguageSourcesPass` emits
+ * `rule_id: 'log_injection'` findings directly for Rust log macros
+ * (`info!`, `println!`, `eprintln!`, …). Those findings bypass the
+ * sink pipeline entirely and therefore bypass this pass. Deferred
+ * to a follow-up if the harness rerun shows material Rust
+ * residuals; the Tier 2 8-repo cohort is Java-heavy.
+ */
+/**
+ * Sink types eligible for the library-profile drop. Seeded with
+ * `log_injection` (CWE-117) in 3.152.0. Extending this set is a
+ * deliberate, reviewable change.
+ */
+const DROPPED_SINK_TYPES = new Set([
+    'log_injection',
+]);
+/**
+ * Returns true when the resolved profile begins with `library/`
+ * (i.e. any `library/production`, `library/dev`, `library/sample`,
+ * `library/benchmark`, `library/test` environment binding).
+ * `'unknown'` and non-library shapes return false.
+ */
+function isLibraryShape(profile) {
+    if (!profile || profile === 'unknown')
+        return false;
+    return profile.startsWith('library/');
+}
+export class LibraryProfileSinkGatePass {
+    name = 'library-profile-sink-gate';
+    category = 'security';
+    run(ctx) {
+        const { graph } = ctx;
+        const profile = graph.ir.meta.projectProfile;
+        if (!isLibraryShape(profile)) {
+            return {
+                profile,
+                applied: false,
+                dropped: 0,
+                droppedByType: {},
+            };
+        }
+        // Authoritative sink list mirrors the fetch pattern in
+        // `SinkSemanticsPass`: prefer `SinkFilterResult.sinks` (what
+        // `analyzer.ts` assembles the final `taint.sinks` from), fall
+        // back to `graph.ir.taint.sinks` for stand-alone unit tests
+        // that don't run `SinkFilterPass`.
+        const sinks = ctx.hasResult('sink-filter')
+            ? ctx.getResult('sink-filter').sinks
+            : graph.ir.taint.sinks;
+        if (sinks.length === 0) {
+            return {
+                profile,
+                applied: true,
+                dropped: 0,
+                droppedByType: {},
+            };
+        }
+        const droppedByType = {};
+        const kept = [];
+        for (const sink of sinks) {
+            if (DROPPED_SINK_TYPES.has(sink.type)) {
+                droppedByType[sink.type] = (droppedByType[sink.type] ?? 0) + 1;
+                continue;
+            }
+            kept.push(sink);
+        }
+        const dropped = sinks.length - kept.length;
+        // Mutate the array in place so downstream passes see the
+        // filtered list. Preserves array identity for any consumer that
+        // captured a reference before this pass ran.
+        if (dropped > 0) {
+            sinks.length = 0;
+            sinks.push(...kept);
+        }
+        return {
+            profile,
+            applied: true,
+            dropped,
+            droppedByType,
+        };
+    }
+}
+//# sourceMappingURL=library-profile-sink-gate-pass.js.map

package/dist/analysis/passes/library-profile-sink-gate-pass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"library-profile-sink-gate-pass.js","sourceRoot":"","sources":["../../../src/analysis/passes/library-profile-sink-gate-pass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAMH;;;;GAIG;AACH,MAAM,kBAAkB,GAA0B,IAAI,GAAG,CAAW;IAClE,eAAe;CAChB,CAAC,CAAC;AA2BH;;;;;GAKG;AACH,SAAS,cAAc,CAAC,OAAmC;IACzD,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACpD,OAAO,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,OAAO,0BAA0B;IAG5B,IAAI,GAAG,2BAA2B,CAAC;IACnC,QAAQ,GAAG,UAAmB,CAAC;IAExC,GAAG,CAAC,GAAgB;QAClB,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC;QACtB,MAAM,OAAO,GAAG,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC;QAE7C,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7B,OAAO;gBACL,OAAO;gBACP,OAAO,EAAE,KAAK;gBACd,OAAO,EAAE,CAAC;gBACV,aAAa,EAAE,EAAE;aAClB,CAAC;QACJ,CAAC;QAED,uDAAuD;QACvD,6DAA6D;QAC7D,8DAA8D;QAC9D,4DAA4D;QAC5D,mCAAmC;QACnC,MAAM,KAAK,GAAgB,GAAG,CAAC,SAAS,CAAC,aAAa,CAAC;YACrD,CAAC,CAAC,GAAG,CAAC,SAAS,CAAmB,aAAa,CAAC,CAAC,KAAK;YACtD,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC;QAEzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO;gBACL,OAAO;gBACP,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,CAAC;gBACV,aAAa,EAAE,EAAE;aAClB,CAAC;QACJ,CAAC;QAED,MAAM,aAAa,GAAsC,EAAE,CAAC;QAC5D,MAAM,IAAI,GAAgB,EAAE,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;gBAC/D,SAAS;YACX,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAE3C,yDAAyD;QACzD,gEAAgE;QAChE,6CAA6C;QAC7C,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;YACjB,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACtB,CAAC;QAED,OAAO;YACL,OAAO;YACP,OAAO,EAAE,IAAI;YACb,OAAO;YACP,aAAa;SACd,CAAC;IACJ,CAAC;CACF"}

package/dist/analysis/require-entry-path.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Require-entry-path anchor (cognium-dev#234, ships 3.153.0).
+ *
+ * Post-pipeline, project-level helper that:
+ *   1. Annotates high+critical (H+C) taint findings with an
+ *      `entryPath[]` chain of methods traversed from a classified
+ *      Tier-1 entry point (Spring MVC handler, JAX-RS resource,
+ *      Servlet lifecycle method, Netty channel handler, `main(String[])`,
+ *      …) down to the finding's sink method.
+ *   2. Drops H+C findings under `application` / `server` / `cli` /
+ *      `plugin` / `unknown` project profiles when the reverse-BFS
+ *      conclusively returns no such chain — i.e. the finding lives on a
+ *      method that no HTTP / RPC / lifecycle entry point in the scan can
+ *      reach.
+ *
+ * # Why
+ *
+ * cognium-ai#189 §1 (2026-07 Tier-2 Java cohort — hutool, Sentinel,
+ * plantuml, mockserver) surfaced 1942 H+C findings on hutool with
+ * *zero* classified HTTP/RPC entry point and no reachable path from
+ * `main`. #236 (source-side profile gate, 3.151.0) and #232
+ * (sink-side profile gate, 3.152.0) each attacked the problem via
+ * profile-conditional per-file drops, but both leave the residual
+ * signal on files whose profile is `application/*` or `unknown` even
+ * though the enclosing method is manifestly unreachable from any
+ * classified boundary.
+ *
+ * This helper closes that hole: no entry point → no path from an
+ * entry point → no H+C finding. Every remaining H+C finding under
+ * `application/*` carries a demonstrable call chain from a real
+ * boundary as evidence, materialised on `entryPath[]` for consumers
+ * (CLI, SARIF, cognium-ai) to display.
+ *
+ * # Scope
+ *
+ * - Java only (relies on `classifyEntryPointTier`, which is Java-primary).
+ *   Non-Java files: pass-through, no annotation, no drop.
+ * - Project-level only. Per-file `analyze()` never runs this helper —
+ *   the reachability question is meaningful only across a full scan.
+ * - Only H+C findings from taint passes are candidates for drop. Metric
+ *   findings, `medium` / `low` taint findings, and findings without a
+ *   resolved containing method are always preserved.
+ *
+ * # Interaction with #236 / #232
+ *
+ * Both #236 and #232 fire when `projectProfile` starts with `library/`:
+ * the source / sink is dropped BEFORE the flow is materialised. This
+ * helper therefore no-ops under `library/*` (an already-dropped flow
+ * never reaches us) but still ANNOTATES findings with `entryPath[]`
+ * whenever a chain is available, so downstream consumers can see the
+ * anchor regardless of the drop decision.
+ *
+ * # Reference
+ *
+ * - cognium-dev#234 — this ticket.
+ * - cognium-dev#128 — entry-point tier classifier.
+ * - cognium-dev#236 (3.151.0) — source-side library-profile gate.
+ * - cognium-dev#232 (3.152.0) — sink-side library-profile gate.
+ * - cognium-ai#189  — Tier-2 Java cohort audit.
+ * - `docs/ARCHITECTURE.md` ADR-010.
+ */
+import type { CircleIR, ProjectProfile } from '../types/index.js';
+/** Rule identifier used for `disabledPasses` lookups. */
+export declare const RULE_ID_REQUIRE_ENTRY_PATH = "require-entry-path";
+export interface ApplyRequireEntryPathOptions {
+    /**
+     * Caller-resolved profile for each file. Same semantics as
+     * `AnalyzerOptions.projectProfile`. When absent, the helper treats
+     * every file as `'unknown'` — i.e. drops still apply.
+     */
+    projectProfile?: ProjectProfile | Map<string, ProjectProfile>;
+    /**
+     * Set of disabled pass ids (from `AnalyzerOptions.disabledPasses`).
+     * If it contains `'require-entry-path'`, the helper is a full no-op
+     * (no annotation, no drop).
+     */
+    disabledPasses?: ReadonlySet<string> | ReadonlyArray<string>;
+}
+/**
+ * Apply the entry-path gate + annotation to every file's findings in
+ * `fileAnalyses`, mutating each `analysis.findings` array in place.
+ *
+ * The mutation is idempotent — running twice produces the same result
+ * (BFS is deterministic; annotation always overwrites prior fields
+ * with the same values).
+ */
+export declare function applyRequireEntryPath(fileAnalyses: ReadonlyArray<{
+    file: string;
+    analysis: CircleIR;
+}>, options?: ApplyRequireEntryPathOptions): void;
+//# sourceMappingURL=require-entry-path.d.ts.map

package/dist/analysis/require-entry-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-entry-path.d.ts","sourceRoot":"","sources":["../../src/analysis/require-entry-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,KAAK,EACV,QAAQ,EAER,cAAc,EAIf,MAAM,mBAAmB,CAAC;AAO3B,yDAAyD;AACzD,eAAO,MAAM,0BAA0B,uBAAuB,CAAC;AAe/D,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,cAAc,CAAC,EAAE,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC9D;;;;OAIG;IACH,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;CAC9D;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC,EACjE,OAAO,GAAE,4BAAiC,GACzC,IAAI,CA6CN"}