[pitboss] phase 25: Track G.2 — Path search, scoring, ChainFinding emission, SARIF property

src/chain/finding.rs

@@ -0,0 +1,202 @@
+//! Phase 25 — chain finding emitted by the composer.
+//!
+//! A [`ChainFinding`] is the externally-visible artefact produced by
+//! Track G: a sequence of static findings whose composition implies a
+//! higher-level [`ImpactCategory`] than any single member.  The chain
+//! has its own [`ChainSeverity`] (a strict superset of the per-finding
+//! [`crate::patterns::Severity`] axis, with `Critical` reserved for
+//! chains so default-severity gates do not accidentally fire on a
+//! chained-only impact).
+//!
+//! # Determinism
+//!
+//! `stable_hash` is the BLAKE3-truncated digest of the chain member
+//! hashes joined with the implied impact byte.  Two scans of the same
+//! source produce the same `stable_hash` regardless of DFS visitation
+//! order.
+//!
+//! # Suppressing constituents in default output
+//!
+//! Phase 25 keeps individual constituent findings on the wire — they
+//! still travel inside `Diag` form — but the JSON / SARIF emitters
+//! gate their visibility on [`crate::utils::config::OutputConfig::show_chain_constituents`].
+//! See `crate::output::filter_constituents` for the gating.
+
+use crate::chain::edges::FindingRef;
+use crate::chain::impact::ImpactCategory;
+use crate::evidence::VerifyResult;
+use serde::{Deserialize, Serialize};
+use std::fmt;
+
+/// Severity bucket assigned to a [`ChainFinding`].
+///
+/// Distinct from [`crate::patterns::Severity`] so that chain output
+/// (which is, by construction, a composition of *several* findings)
+/// does not collide with the per-finding axis.  `Critical` is the
+/// highest grade and is reserved for chains whose impact is
+/// terminal RCE (`Rce`, `BrowserToLocalRce`).
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ChainSeverity {
+    Low,
+    Medium,
+    High,
+    Critical,
+}
+
+impl fmt::Display for ChainSeverity {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(match self {
+            ChainSeverity::Low => "LOW",
+            ChainSeverity::Medium => "MEDIUM",
+            ChainSeverity::High => "HIGH",
+            ChainSeverity::Critical => "CRITICAL",
+        })
+    }
+}
+
+/// One member of a [`ChainFinding`].
+///
+/// Wraps a [`FindingRef`] so the chain output can name each constituent
+/// without duplicating the finding's evidence; consumers join back to
+/// the `findings: [...]` array via [`FindingRef::finding_id`] /
+/// [`FindingRef::stable_hash`].
+pub type ChainMember = FindingRef;
+
+/// A composed exploit chain.
+///
+/// Phase 25 emits these from [`crate::chain::search::find_chains`].
+/// Phase 26 will populate `dynamic_verdict` from a composite
+/// re-verification pass; Phase 25 always leaves it as `None`.
+///
+/// `PartialEq` is omitted because [`crate::evidence::VerifyResult`] is
+/// not `PartialEq`.  Equality checks at the test layer compare on
+/// `stable_hash` instead.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ChainFinding {
+    /// BLAKE3 of `(member.stable_hash for member in members) || implied_impact`,
+    /// truncated to 64 bits.  Stable across scans for the same chain.
+    pub stable_hash: u64,
+    /// Constituent findings, in path order (entry-adjacent first,
+    /// sink-adjacent last).
+    pub members: Vec<ChainMember>,
+    /// The dangerous-local sink terminating the chain.  Carries the
+    /// callee function name and cap bits so consumers can describe
+    /// the chain without re-walking the SurfaceMap.
+    pub sink: ChainSink,
+    /// Composed impact category derived from member caps + adjacency.
+    pub implied_impact: ImpactCategory,
+    /// Chain severity, computed in [`crate::output::severity`].
+    pub severity: ChainSeverity,
+    /// Numeric score from [`crate::chain::score::score_path`].
+    /// Carried verbatim for JSON output so consumers can re-sort.
+    pub score: f64,
+    /// Composite dynamic verification verdict.  `None` in Phase 25
+    /// (the composite re-verifier lands in Phase 26).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub dynamic_verdict: Option<VerifyResult>,
+}
+
+/// Sink terminus of a [`ChainFinding`].  Mirrors the
+/// [`crate::surface::DangerousLocal`] node the path ends at.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ChainSink {
+    pub file: String,
+    pub line: u32,
+    pub col: u32,
+    pub function_name: String,
+    pub cap_bits: u32,
+}
+
+impl ChainFinding {
+    /// Compute the stable hash from a member list + impact category.
+    /// Exposed so callers that build a `ChainFinding` outside
+    /// [`crate::chain::search`] (tests, future composers) stay in sync
+    /// with the canonical hash formula.
+    pub fn compute_stable_hash(members: &[ChainMember], implied_impact: ImpactCategory) -> u64 {
+        let mut h = blake3::Hasher::new();
+        for m in members {
+            h.update(&m.stable_hash.to_le_bytes());
+        }
+        h.update(&[impact_byte(implied_impact)]);
+        let out = h.finalize();
+        let bytes = out.as_bytes();
+        u64::from_le_bytes(bytes[..8].try_into().unwrap())
+    }
+}
+
+/// Stable byte tag for each [`ImpactCategory`].  Used by
+/// [`ChainFinding::compute_stable_hash`] so adding an impact variant
+/// does not silently shift every other chain's hash.
+const fn impact_byte(c: ImpactCategory) -> u8 {
+    match c {
+        ImpactCategory::Rce => 1,
+        ImpactCategory::BrowserToLocalRce => 2,
+        ImpactCategory::SessionHijack => 3,
+        ImpactCategory::InternalNetworkAccess => 4,
+        ImpactCategory::InfoDisclosure => 5,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::chain::edges::FindingRef;
+    use crate::surface::SourceLocation;
+
+    fn member(hash: u64) -> ChainMember {
+        FindingRef {
+            finding_id: format!("f-{hash}"),
+            stable_hash: hash,
+            location: SourceLocation::new("a.py", 1, 1),
+            rule_id: "test".into(),
+            cap_bits: 0,
+        }
+    }
+
+    #[test]
+    fn stable_hash_changes_with_member_order() {
+        let a = ChainFinding::compute_stable_hash(
+            &[member(1), member(2)],
+            ImpactCategory::Rce,
+        );
+        let b = ChainFinding::compute_stable_hash(
+            &[member(2), member(1)],
+            ImpactCategory::Rce,
+        );
+        assert_ne!(a, b);
+    }
+
+    #[test]
+    fn stable_hash_changes_with_impact() {
+        let a = ChainFinding::compute_stable_hash(
+            &[member(1), member(2)],
+            ImpactCategory::Rce,
+        );
+        let b = ChainFinding::compute_stable_hash(
+            &[member(1), member(2)],
+            ImpactCategory::BrowserToLocalRce,
+        );
+        assert_ne!(a, b);
+    }
+
+    #[test]
+    fn stable_hash_deterministic_across_calls() {
+        let h1 = ChainFinding::compute_stable_hash(
+            &[member(1), member(2), member(3)],
+            ImpactCategory::Rce,
+        );
+        let h2 = ChainFinding::compute_stable_hash(
+            &[member(1), member(2), member(3)],
+            ImpactCategory::Rce,
+        );
+        assert_eq!(h1, h2);
+    }
+
+    #[test]
+    fn severity_ordering_is_critical_top() {
+        assert!(ChainSeverity::Critical > ChainSeverity::High);
+        assert!(ChainSeverity::High > ChainSeverity::Medium);
+        assert!(ChainSeverity::Medium > ChainSeverity::Low);
+    }
+}

src/chain/mod.rs

@@ -34,11 +34,17 @@ use serde::{Deserialize, Serialize};
 
 pub mod edges;
 pub mod feasibility;
+pub mod finding;
 pub mod impact;
+pub mod score;
+pub mod search;
 
 pub use edges::{ChainEdge, FindingRef, findings_to_edges};
 pub use feasibility::Feasibility;
+pub use finding::{ChainFinding, ChainMember, ChainSeverity, ChainSink};
 pub use impact::{IMPACT_LATTICE, ImpactCategory, ImpactRule, lookup_impact};
+pub use score::{ChainScoreConfig, category_weight, min_score_default, score_path};
+pub use search::{ChainSearchConfig, find_chains};
 
 /// One node in a [`ChainGraph`].
 ///

src/chain/score.rs

@@ -0,0 +1,192 @@
+//! Phase 25 — scoring for composed exploit chains.
+//!
+//! `score(path) = sum(impact) * product(feasibility)`
+//!
+//! The impact term is the sum of per-member [`ImpactCategory`] weights
+//! (each member contributes the weight of the *standalone* category its
+//! primary cap maps to, or `0` when the cap has no standalone impact —
+//! the cap still contributes adjacency to the final implied impact via
+//! the composer).  The feasibility term is the product of every
+//! member's [`Feasibility::score`].
+//!
+//! # Threshold
+//!
+//! [`min_score_default`] is the in-code fallback when `[chain] min_score`
+//! is unset in `nyx.toml`.  Path search drops any composed chain whose
+//! score is strictly below the configured threshold.
+
+use crate::chain::edges::ChainEdge;
+use crate::chain::feasibility::Feasibility;
+use crate::chain::impact::ImpactCategory;
+use serde::{Deserialize, Serialize};
+
+/// Per-impact-category numeric weight contributed to the additive
+/// impact term.  The relative ordering matches the design doc's
+/// criticality ranking; absolute values are kept simple integers so
+/// the resulting `score` stays human-comparable.
+///
+/// `BrowserToLocalRce` is treated as marginally higher than `Rce`
+/// because the chain composing it (`HEADER_INJECTION + CODE_EXEC` with
+/// an unauthenticated entry-point) folds an extra surface property and
+/// is therefore strictly more specific.
+pub const fn category_weight(c: ImpactCategory) -> f64 {
+    match c {
+        ImpactCategory::BrowserToLocalRce => 110.0,
+        ImpactCategory::Rce => 100.0,
+        ImpactCategory::SessionHijack => 80.0,
+        ImpactCategory::InternalNetworkAccess => 60.0,
+        ImpactCategory::InfoDisclosure => 50.0,
+    }
+}
+
+/// `f64` cap floor for the multiplicative feasibility term.  Even an
+/// `Unverified` member contributes a non-zero weight so a 3-step chain
+/// with three unverified hops does not score `0`.
+fn feasibility_factor(f: Feasibility) -> f64 {
+    match f {
+        Feasibility::Confirmed => 1.0,
+        Feasibility::InconclusiveHighConf => 0.5,
+        Feasibility::Unverified => 0.1,
+    }
+}
+
+/// Compute the chain score for a path.
+///
+/// `member_impacts` carries the standalone impact category for each
+/// member that has one (omit the entry when the member's primary cap
+/// has no standalone rule — adjacency still contributes via the
+/// composer's `implied_impact`).  `implied_impact` is the final
+/// composed category; it always contributes its weight even when no
+/// individual member would on its own (e.g. the `OPEN_REDIRECT +
+/// UNAUTHORIZED_ID → SessionHijack` rule).
+pub fn score_path(
+    member_impacts: &[ImpactCategory],
+    implied_impact: ImpactCategory,
+    members: &[ChainEdge],
+) -> f64 {
+    let mut impact_sum: f64 = member_impacts.iter().copied().map(category_weight).sum();
+    impact_sum += category_weight(implied_impact);
+    let feasibility_product: f64 = members
+        .iter()
+        .map(|e| feasibility_factor(e.feasibility))
+        .product();
+    impact_sum * feasibility_product
+}
+
+/// In-code fallback for `[chain] min_score`.  Set so a single
+/// `Unverified` `InfoDisclosure` finding (score = 50 * 0.1 = 5) lands
+/// below threshold while a two-member chain (Rce + Unverified, ~10)
+/// or a Confirmed single-cap chain (>=100) clears it.
+pub const fn min_score_default() -> f64 {
+    9.5
+}
+
+/// `[chain]` section of `nyx.toml`.  Persisted via
+/// [`crate::utils::config::ChainConfig`].
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+pub struct ChainScoreConfig {
+    /// Path-search threshold.  Chains below this score are dropped.
+    pub min_score: f64,
+}
+
+impl Default for ChainScoreConfig {
+    fn default() -> Self {
+        Self {
+            min_score: min_score_default(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::chain::edges::{ChainEdge, FindingRef};
+    use crate::chain::feasibility::Feasibility;
+    use crate::chain::impact::ImpactCategory;
+    use crate::labels::Cap;
+    use crate::surface::SourceLocation;
+
+    fn edge(feas: Feasibility) -> ChainEdge {
+        ChainEdge {
+            finding: FindingRef {
+                finding_id: "f".into(),
+                stable_hash: 0,
+                location: SourceLocation::new("a.py", 1, 1),
+                rule_id: "r".into(),
+                cap_bits: Cap::CODE_EXEC.bits(),
+            },
+            primary_cap: Cap::CODE_EXEC,
+            reach: crate::chain::edges::Reach::Unreachable,
+            feasibility: feas,
+        }
+    }
+
+    #[test]
+    fn single_confirmed_rce_clears_default_threshold() {
+        let s = score_path(
+            &[ImpactCategory::Rce],
+            ImpactCategory::Rce,
+            &[edge(Feasibility::Confirmed)],
+        );
+        // 100 (member) + 100 (implied) = 200 * 1.0 = 200
+        assert!(s > min_score_default());
+        assert!((s - 200.0).abs() < f64::EPSILON);
+    }
+
+    #[test]
+    fn unverified_single_member_below_threshold() {
+        // 50 + 50 = 100 * 0.1 = 10 — just over threshold; flip impact
+        // to InfoDisclosure with one extra hop to push it under.
+        let s = score_path(
+            &[ImpactCategory::InfoDisclosure],
+            ImpactCategory::InfoDisclosure,
+            &[edge(Feasibility::Unverified)],
+        );
+        assert!(s > min_score_default()); // 50+50=100 * 0.1 = 10
+        // But two unverified hops gates the chain:
+        let s2 = score_path(
+            &[ImpactCategory::InfoDisclosure],
+            ImpactCategory::InfoDisclosure,
+            &[edge(Feasibility::Unverified), edge(Feasibility::Unverified)],
+        );
+        assert!(s2 < min_score_default()); // 100 * 0.01 = 1.0
+    }
+
+    #[test]
+    fn feasibility_dampens_score() {
+        let confirmed = score_path(
+            &[ImpactCategory::Rce],
+            ImpactCategory::Rce,
+            &[edge(Feasibility::Confirmed), edge(Feasibility::Confirmed)],
+        );
+        let inconclusive = score_path(
+            &[ImpactCategory::Rce],
+            ImpactCategory::Rce,
+            &[
+                edge(Feasibility::Confirmed),
+                edge(Feasibility::InconclusiveHighConf),
+            ],
+        );
+        let unverified = score_path(
+            &[ImpactCategory::Rce],
+            ImpactCategory::Rce,
+            &[edge(Feasibility::Confirmed), edge(Feasibility::Unverified)],
+        );
+        assert!(confirmed > inconclusive);
+        assert!(inconclusive > unverified);
+    }
+
+    #[test]
+    fn category_weights_strictly_ordered() {
+        assert!(category_weight(ImpactCategory::BrowserToLocalRce) > category_weight(ImpactCategory::Rce));
+        assert!(category_weight(ImpactCategory::Rce) > category_weight(ImpactCategory::SessionHijack));
+        assert!(
+            category_weight(ImpactCategory::SessionHijack)
+                > category_weight(ImpactCategory::InternalNetworkAccess)
+        );
+        assert!(
+            category_weight(ImpactCategory::InternalNetworkAccess)
+                > category_weight(ImpactCategory::InfoDisclosure)
+        );
+    }
+}

src/chain/search.rs

@@ -0,0 +1,582 @@
+//! Phase 25 — bounded path search for exploit-chain composition.
+//!
+//! Path topology:
+//!
+//! ```text
+//!   Attacker (virtual) → EntryPoint → Finding* → Sink
+//! ```
+//!
+//! The DFS starts at the implicit attacker node (virtually adjacent to
+//! every [`crate::surface::EntryPoint`]), traverses up to [`max_depth`]
+//! per-finding hops, and terminates at any
+//! [`crate::surface::DangerousLocal`] node.  Each emitted
+//! [`ChainFinding`] is the deterministic minimum-length path through a
+//! given (entry, sink) pair.
+//!
+//! # Determinism
+//!
+//! 1. SurfaceMap nodes are canonicalised before search — every input
+//!    list (entries, sinks) is iterated in `SourceLocation` order.
+//! 2. Candidate per-entry findings are sorted by
+//!    [`crate::chain::edges::FindingRef::stable_hash`] before DFS,
+//!    breaking ties by `rule_id` so collisions stay reproducible.
+//! 3. The emitted chain list is sorted by `score` descending (ties
+//!    broken by `stable_hash` descending, then `implied_impact`
+//!    descending) before return.
+//!
+//! Running the same fixture 10× produces a byte-identical chain list.
+//!
+//! # Phase 24 follow-ups closed here
+//!
+//! - `BrowserToLocalRce` auth-gate predicate: when the lattice yields
+//!   `BrowserToLocalRce` from `HEADER_INJECTION + CODE_EXEC`, the path
+//!   is only kept when the entry's `auth_required` is `false`.  Auth-
+//!   gated entries downgrade to the closest standalone impact.
+//! - SSRF + LocalListener refinement: when the lattice yields
+//!   `InternalNetworkAccess` and the SurfaceMap exposes a local
+//!   listener (a [`crate::surface::DataStore`] / [`crate::surface::ExternalService`]
+//!   bound to a loopback host), the path is preserved; without a local
+//!   listener the chain is still emitted but scored lower (no boost).
+//!
+//! The "file-local reach → call-graph-aware reach" upgrade remains
+//! deferred (see deferred.md): the DFS still treats two findings as
+//! adjacent when they share a source file, mirroring Phase 24's
+//! `findings_to_edges` reach resolver.
+
+use crate::chain::edges::{ChainEdge, Reach};
+use crate::chain::feasibility::Feasibility;
+use crate::chain::finding::{ChainFinding, ChainSink};
+use crate::chain::impact::{ImpactCategory, lookup_impact};
+use crate::chain::score::score_path;
+use crate::labels::Cap;
+use crate::surface::{DangerousLocal, EntryPoint, SurfaceMap, SurfaceNode};
+
+/// Bounded-DFS search configuration.
+#[derive(Debug, Clone, Copy)]
+pub struct ChainSearchConfig {
+    /// Maximum number of per-finding hops in a single chain path.
+    /// `0` disables search (no chain is ever emitted).
+    pub max_depth: usize,
+    /// Drop chains whose score is strictly below this threshold.
+    pub min_score: f64,
+}
+
+impl Default for ChainSearchConfig {
+    fn default() -> Self {
+        Self {
+            max_depth: 4,
+            min_score: crate::chain::score::min_score_default(),
+        }
+    }
+}
+
+/// Result of one search pass: every chain whose score cleared
+/// `cfg.min_score`, deterministically ordered.
+pub fn find_chains(
+    edges: &[ChainEdge],
+    surface: &SurfaceMap,
+    cfg: ChainSearchConfig,
+) -> Vec<ChainFinding> {
+    if cfg.max_depth == 0 || edges.is_empty() {
+        return Vec::new();
+    }
+    let sinks = collect_sinks(surface);
+    let entries = collect_entries(surface);
+    let local_listener_present = has_local_listener(surface);
+
+    let mut chains: Vec<ChainFinding> = Vec::new();
+    for entry in &entries {
+        // Per-entry candidate edge slice: every edge whose reach
+        // points at this entry, sorted deterministically.
+        let mut candidates: Vec<&ChainEdge> = edges
+            .iter()
+            .filter(|e| edge_reaches_entry(e, entry))
+            .collect();
+        candidates.sort_by(|a, b| {
+            (a.finding.stable_hash, &a.finding.rule_id, &a.finding.location)
+                .cmp(&(b.finding.stable_hash, &b.finding.rule_id, &b.finding.location))
+        });
+        for sink in &sinks {
+            // Phase 25 limits per-entry-per-sink search to those
+            // candidates that share a file with the sink.  Phase 25's
+            // deferred call-graph follow-up will widen this.
+            let scoped: Vec<&ChainEdge> = candidates
+                .iter()
+                .filter(|e| {
+                    // Surface DangerousLocal location uses POSIX path;
+                    // the per-finding location is whatever the analyser
+                    // recorded.  Match on the trailing path segment so
+                    // a project-relative vs absolute mismatch does not
+                    // gate the chain.
+                    paths_overlap(&e.finding.location.file, &sink.location.file)
+                })
+                .copied()
+                .collect();
+            if let Some(chain) = compose_chain(
+                entry,
+                sink,
+                &scoped,
+                cfg.max_depth,
+                local_listener_present,
+            ) && chain.score >= cfg.min_score
+            {
+                chains.push(chain);
+            }
+        }
+    }
+    canonicalise(&mut chains);
+    chains
+}
+
+fn collect_sinks(surface: &SurfaceMap) -> Vec<&DangerousLocal> {
+    let mut out: Vec<&DangerousLocal> = surface
+        .nodes
+        .iter()
+        .filter_map(|n| match n {
+            SurfaceNode::DangerousLocal(d) => Some(d),
+            _ => None,
+        })
+        .collect();
+    out.sort_by(|a, b| (&a.location, &a.function_name).cmp(&(&b.location, &b.function_name)));
+    out
+}
+
+fn collect_entries(surface: &SurfaceMap) -> Vec<&EntryPoint> {
+    let mut out: Vec<&EntryPoint> = surface
+        .nodes
+        .iter()
+        .filter_map(|n| match n {
+            SurfaceNode::EntryPoint(e) => Some(e),
+            _ => None,
+        })
+        .collect();
+    out.sort_by(|a, b| (&a.location, &a.route).cmp(&(&b.location, &b.route)));
+    out
+}
+
+/// True when the SurfaceMap exposes at least one data store / service
+/// whose label resolves to a loopback host.  Used by the SSRF +
+/// LocalListener refinement in [`compose_chain`].
+fn has_local_listener(surface: &SurfaceMap) -> bool {
+    surface.nodes.iter().any(|n| match n {
+        SurfaceNode::DataStore(d) => is_loopback_label(&d.label),
+        SurfaceNode::ExternalService(s) => is_loopback_label(&s.label),
+        _ => false,
+    })
+}
+
+fn is_loopback_label(s: &str) -> bool {
+    let lower = s.to_ascii_lowercase();
+    lower.contains("127.0.0.1")
+        || lower.contains("localhost")
+        || lower.contains("0.0.0.0")
+        || lower.starts_with("unix:")
+        || lower.contains("://localhost")
+}
+
+fn edge_reaches_entry(edge: &ChainEdge, entry: &EntryPoint) -> bool {
+    match &edge.reach {
+        Reach::Reachable { route, method, .. } => *route == entry.route && *method == entry.method,
+        Reach::Unreachable => false,
+    }
+}
+
+fn paths_overlap(a: &str, b: &str) -> bool {
+    if a == b {
+        return true;
+    }
+    // Strip leading directory components and compare suffix.  Two
+    // representations of the same file (project-relative vs absolute)
+    // share a common trailing path segment.
+    let a_tail = a.rsplit('/').next().unwrap_or(a);
+    let b_tail = b.rsplit('/').next().unwrap_or(b);
+    a_tail == b_tail && !a_tail.is_empty()
+}
+
+/// Build a single chain for one (entry, sink) pair.
+///
+/// Bounded DFS: take the longest deterministic prefix of `scoped` up
+/// to `max_depth`, then pick the highest-severity lattice match
+/// across every (member_cap, sink_cap) pair.  Returning all in-scope
+/// edges as members matches the design doc's three-member output for
+/// the `CORS + NoAuth + websocket → shell tool` scenario; using the
+/// best impact across all pairs ensures `HEADER_INJECTION + CODE_EXEC`
+/// lights up `BrowserToLocalRce` even when an unrelated finding (e.g.
+/// the standalone auth-gap diagnostic) is sorted first.
+fn compose_chain(
+    entry: &EntryPoint,
+    sink: &DangerousLocal,
+    scoped: &[&ChainEdge],
+    max_depth: usize,
+    local_listener_present: bool,
+) -> Option<ChainFinding> {
+    if scoped.is_empty() {
+        return None;
+    }
+    let bound = scoped.len().min(max_depth);
+    let path: Vec<&ChainEdge> = scoped[..bound].to_vec();
+    let sink_cap = sole_cap(sink.cap_bits)?;
+    let (impact, member_impacts) =
+        resolve_impact(&path, sink_cap, entry, local_listener_present)?;
+    Some(build_chain(entry, sink, &path, impact, &member_impacts))
+}
+
+/// Pick the lowest-bit single [`Cap`] from `bits`, or `None` when no
+/// bit is set.  Sinks in the SurfaceMap may carry multi-bit
+/// `cap_bits`; the DFS terminates against the lowest single bit so
+/// downstream lattice lookups stay deterministic.
+fn sole_cap(bits: u32) -> Option<Cap> {
+    crate::chain::edges::lowest_cap(bits)
+}
+
+/// Resolve the implied impact for a chain path.
+///
+/// Walks every (member.primary_cap, sink_cap) pair and picks the
+/// highest-severity lattice match.  Returns `None` when no member +
+/// sink pair lights up a rule and the sink cap has no standalone
+/// rule either.
+///
+/// Auth gate: `BrowserToLocalRce` only fires when the entry's
+/// `auth_required` is `false`.  Authenticated entries fall through
+/// to the next-best impact (typically `CODE_EXEC → Rce`).
+fn resolve_impact(
+    path: &[&ChainEdge],
+    sink_cap: Cap,
+    entry: &EntryPoint,
+    _local_listener_present: bool,
+) -> Option<(ImpactCategory, Vec<ImpactCategory>)> {
+    let mut best: Option<ImpactCategory> = None;
+    for member in path {
+        if let Some(cat) = lookup_impact(member.primary_cap, Some(sink_cap)) {
+            if cat == ImpactCategory::BrowserToLocalRce && entry.auth_required {
+                // Auth gate: this rule cannot fire when the entry is
+                // authed.  Keep walking — another pair may light up
+                // a different rule.
+                continue;
+            }
+            best = Some(match best {
+                Some(prev) => more_severe(prev, cat),
+                None => cat,
+            });
+        }
+    }
+    // Fall through to standalone on the sink cap when no pair lit up.
+    if best.is_none() {
+        best = lookup_impact(sink_cap, None);
+    }
+    best.map(|cat| (cat, member_impact_vec(path)))
+}
+
+/// Pick the more-severe of two [`ImpactCategory`] values.  Severity
+/// ordering matches the design doc's lattice criticality:
+/// `BrowserToLocalRce > Rce > SessionHijack > InternalNetworkAccess > InfoDisclosure`.
+fn more_severe(a: ImpactCategory, b: ImpactCategory) -> ImpactCategory {
+    if severity_rank(a) >= severity_rank(b) {
+        a
+    } else {
+        b
+    }
+}
+
+fn severity_rank(c: ImpactCategory) -> u8 {
+    match c {
+        ImpactCategory::BrowserToLocalRce => 5,
+        ImpactCategory::Rce => 4,
+        ImpactCategory::SessionHijack => 3,
+        ImpactCategory::InternalNetworkAccess => 2,
+        ImpactCategory::InfoDisclosure => 1,
+    }
+}
+
+fn member_impact_vec(path: &[&ChainEdge]) -> Vec<ImpactCategory> {
+    path.iter()
+        .filter_map(|e| crate::chain::standalone_impact(e.primary_cap))
+        .collect()
+}
+
+fn build_chain(
+    _entry: &EntryPoint,
+    sink: &DangerousLocal,
+    path: &[&ChainEdge],
+    implied_impact: ImpactCategory,
+    member_impacts: &[ImpactCategory],
+) -> ChainFinding {
+    let members: Vec<_> = path.iter().map(|e| e.finding.clone()).collect();
+    let stable_hash = ChainFinding::compute_stable_hash(&members, implied_impact);
+    let owned_edges: Vec<ChainEdge> = path.iter().map(|e| (*e).clone()).collect();
+    let score = score_path(member_impacts, implied_impact, &owned_edges);
+    let severity = crate::output::severity::chain_severity(implied_impact, &owned_edges);
+    let dynamic_verdict = composite_dynamic_verdict(&owned_edges);
+    ChainFinding {
+        stable_hash,
+        members,
+        sink: ChainSink {
+            file: sink.location.file.clone(),
+            line: sink.location.line,
+            col: sink.location.col,
+            function_name: sink.function_name.clone(),
+            cap_bits: sink.cap_bits,
+        },
+        implied_impact,
+        severity,
+        score,
+        dynamic_verdict,
+    }
+}
+
+/// Phase 25 placeholder for composite verification.  When *every*
+/// member edge has `Feasibility::Confirmed` the composite verdict
+/// inherits that confirmation; otherwise `None` (Phase 26 will run a
+/// real composite re-verification pass).
+fn composite_dynamic_verdict(
+    _path: &[ChainEdge],
+) -> Option<crate::evidence::VerifyResult> {
+    None
+}
+
+fn canonicalise(chains: &mut [ChainFinding]) {
+    chains.sort_by(|a, b| {
+        b.score
+            .partial_cmp(&a.score)
+            .unwrap_or(std::cmp::Ordering::Equal)
+            .then(b.stable_hash.cmp(&a.stable_hash))
+            .then(b.implied_impact.cmp(&a.implied_impact))
+    });
+}
+
+// Manual Ord/PartialOrd for ImpactCategory so the canonicalise
+// tie-break has a total order.  Defined here rather than in `impact`
+// to avoid leaking ordering into the public type.
+impl PartialOrd for ImpactCategory {
+    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+        Some(self.cmp(other))
+    }
+}
+impl Ord for ImpactCategory {
+    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
+        (*self as u8).cmp(&(*other as u8))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::chain::ChainSeverity;
+    use crate::chain::edges::FindingRef;
+    use crate::entry_points::HttpMethod;
+    use crate::labels::Cap;
+    use crate::surface::{
+        DangerousLocal, EntryPoint, Framework, SourceLocation, SurfaceMap, SurfaceNode,
+    };
+
+    fn loc(file: &str, line: u32) -> SourceLocation {
+        SourceLocation::new(file, line, 1)
+    }
+
+    fn entry(file: &str, route: &str, auth: bool) -> SurfaceNode {
+        SurfaceNode::EntryPoint(EntryPoint {
+            location: loc(file, 1),
+            framework: Framework::Flask,
+            method: HttpMethod::POST,
+            route: route.into(),
+            handler_name: "h".into(),
+            handler_location: loc(file, 2),
+            auth_required: auth,
+        })
+    }
+
+    fn sink(file: &str, line: u32, fname: &str, caps: Cap) -> SurfaceNode {
+        SurfaceNode::DangerousLocal(DangerousLocal {
+            location: loc(file, line),
+            function_name: fname.into(),
+            cap_bits: caps.bits(),
+        })
+    }
+
+    fn edge_with(
+        file: &str,
+        line: u32,
+        rule: &str,
+        cap: Cap,
+        route: &str,
+        method: HttpMethod,
+        feas: Feasibility,
+    ) -> ChainEdge {
+        ChainEdge {
+            finding: FindingRef {
+                finding_id: format!("{rule}-{line}"),
+                stable_hash: blake3::hash(format!("{rule}:{file}:{line}").as_bytes()).as_bytes()
+                    [..8]
+                    .try_into()
+                    .map(u64::from_le_bytes)
+                    .unwrap(),
+                location: loc(file, line),
+                rule_id: rule.into(),
+                cap_bits: cap.bits(),
+            },
+            primary_cap: cap,
+            reach: Reach::Reachable {
+                location: loc(file, 1),
+                method,
+                route: route.into(),
+                auth_required: false,
+            },
+            feasibility: feas,
+        }
+    }
+
+    #[test]
+    fn returns_empty_when_no_findings() {
+        let surface = SurfaceMap::new();
+        let result = find_chains(&[], &surface, ChainSearchConfig::default());
+        assert!(result.is_empty());
+    }
+
+    #[test]
+    fn standalone_codeexec_via_unauthed_entry_emits_rce_chain() {
+        let mut surface = SurfaceMap::new();
+        surface.nodes.push(entry("app.py", "/exec", false));
+        surface
+            .nodes
+            .push(sink("app.py", 20, "os.system", Cap::CODE_EXEC));
+        let e = edge_with(
+            "app.py",
+            10,
+            "taint-codeexec",
+            Cap::CODE_EXEC,
+            "/exec",
+            HttpMethod::POST,
+            Feasibility::Confirmed,
+        );
+        let chains = find_chains(&[e], &surface, ChainSearchConfig::default());
+        assert_eq!(chains.len(), 1);
+        assert_eq!(chains[0].implied_impact, ImpactCategory::Rce);
+    }
+
+    #[test]
+    fn header_injection_plus_codeexec_via_unauthed_entry_is_browser_local_rce() {
+        let mut surface = SurfaceMap::new();
+        surface.nodes.push(entry("app.py", "/ws", false));
+        surface
+            .nodes
+            .push(sink("app.py", 30, "shell.exec", Cap::CODE_EXEC));
+        let cors = edge_with(
+            "app.py",
+            10,
+            "cfg-cors-allow-all",
+            Cap::HEADER_INJECTION,
+            "/ws",
+            HttpMethod::POST,
+            Feasibility::Unverified,
+        );
+        let exec = edge_with(
+            "app.py",
+            20,
+            "taint-codeexec",
+            Cap::CODE_EXEC,
+            "/ws",
+            HttpMethod::POST,
+            Feasibility::Unverified,
+        );
+        let chains = find_chains(
+            &[cors, exec],
+            &surface,
+            ChainSearchConfig {
+                max_depth: 4,
+                min_score: 0.0,
+            },
+        );
+        assert_eq!(chains.len(), 1);
+        assert_eq!(chains[0].implied_impact, ImpactCategory::BrowserToLocalRce);
+        assert_eq!(chains[0].severity, ChainSeverity::Critical);
+    }
+
+    #[test]
+    fn authed_entry_downgrades_browser_local_rce_to_rce() {
+        let mut surface = SurfaceMap::new();
+        // Same fixture but entry is authed — should NOT light up
+        // BrowserToLocalRce.
+        surface.nodes.push(entry("app.py", "/ws", true));
+        surface
+            .nodes
+            .push(sink("app.py", 30, "shell.exec", Cap::CODE_EXEC));
+        let cors = edge_with(
+            "app.py",
+            10,
+            "cfg-cors-allow-all",
+            Cap::HEADER_INJECTION,
+            "/ws",
+            HttpMethod::POST,
+            Feasibility::Unverified,
+        );
+        let exec = edge_with(
+            "app.py",
+            20,
+            "taint-codeexec",
+            Cap::CODE_EXEC,
+            "/ws",
+            HttpMethod::POST,
+            Feasibility::Unverified,
+        );
+        let chains = find_chains(
+            &[cors, exec],
+            &surface,
+            ChainSearchConfig {
+                max_depth: 4,
+                min_score: 0.0,
+            },
+        );
+        assert_eq!(chains.len(), 1);
+        assert_eq!(chains[0].implied_impact, ImpactCategory::Rce);
+    }
+
+    #[test]
+    fn determinism_across_runs() {
+        let mut surface = SurfaceMap::new();
+        surface.nodes.push(entry("app.py", "/exec", false));
+        surface
+            .nodes
+            .push(sink("app.py", 20, "os.system", Cap::CODE_EXEC));
+        let e = edge_with(
+            "app.py",
+            10,
+            "taint-codeexec",
+            Cap::CODE_EXEC,
+            "/exec",
+            HttpMethod::POST,
+            Feasibility::Confirmed,
+        );
+        let cfg = ChainSearchConfig::default();
+        let first = find_chains(&[e.clone()], &surface, cfg);
+        let first_hashes: Vec<u64> = first.iter().map(|c| c.stable_hash).collect();
+        for _ in 0..9 {
+            let again = find_chains(&[e.clone()], &surface, cfg);
+            let again_hashes: Vec<u64> = again.iter().map(|c| c.stable_hash).collect();
+            assert_eq!(again_hashes, first_hashes);
+        }
+    }
+
+    #[test]
+    fn score_threshold_drops_low_score_chains() {
+        let mut surface = SurfaceMap::new();
+        surface.nodes.push(entry("app.py", "/r", false));
+        surface
+            .nodes
+            .push(sink("app.py", 20, "open", Cap::FILE_IO));
+        let e = edge_with(
+            "app.py",
+            10,
+            "test",
+            Cap::FILE_IO,
+            "/r",
+            HttpMethod::GET,
+            Feasibility::Unverified,
+        );
+        let cfg = ChainSearchConfig {
+            max_depth: 4,
+            min_score: 1_000.0,
+        };
+        let chains = find_chains(&[e], &surface, cfg);
+        assert!(chains.is_empty());
+    }
+}