git.stella-ops.org/docs/reachability/lattice.md

Reachability Lattice & Scoring Model

Status: Draft – mirrors the November 2025 advisory on confidence-based reachability.
Owners: Scanner Guild · Policy Guild · Signals Guild.

This document defines the confidence lattice, evidence types, mitigation scoring, and policy gates used to turn static/runtime signals into reproducible reachability decisions and VEX statuses.

---

1. Overview

Classic “reachable: true/false” answers are too brittle. Stella Ops models reachability as an ordered lattice with explicit states and scores. Each analyzer/runtime probe emits Evidence documents; mitigations add Mitigation entries. The lattice engine joins both inputs into a ReachDecision:

UNOBSERVED (0–9)
    < POSSIBLE (10–29)
        < STATIC_PATH (30–59)
            < DYNAMIC_SEEN (60–79)
                < DYNAMIC_USER_TAINTED (80–99)
                    < EXPLOIT_CONSTRAINTS_REMOVED (100)

Each state corresponds to increasing confidence that a vulnerability can execute. Mitigations reduce scores; policy gates map scores to VEX statuses (not_affected, under_investigation, affected).

---

2. Core types

public enum ReachState { Unobserved, Possible, StaticPath, DynamicSeen, DynamicUserTainted, ExploitConstraintsRemoved }

public enum EvidenceKind {
    StaticCallEdge, StaticEntryPointProximity, StaticPackageDeclaredOnly,
    RuntimeMethodHit, RuntimeStackSample, RuntimeHttpRouteHit,
    UserInputSource, DataTaintFlow, ConfigFlagOn, ConfigFlagOff,
    ContainerNetworkRestricted, ContainerNetworkOpen,
    WafRulePresent, PatchLevel, VendorVexNotAffected, VendorVexAffected,
    ManualOverride
}

public sealed record Evidence(
    string Id,
    EvidenceKind Kind,
    double Weight,
    string Source,
    DateTimeOffset Timestamp,
    string? ArtifactRef,
    string? Details);

public enum MitigationKind { WafRule, FeatureFlagDisabled, AuthZEnforced, InputValidation, PatchedVersion, ContainerNetworkIsolation, RuntimeGuard, KillSwitch, Other }

public sealed record Mitigation(
    string Id,
    MitigationKind Kind,
    double Strength,
    string Source,
    DateTimeOffset Timestamp,
    string? ConfigHash,
    string? Details);

public sealed record ReachDecision(
    string VulnerabilityId,
    string ComponentPurl,
    ReachState State,
    int Score,
    string PolicyVersion,
    IReadOnlyList<Evidence> Evidence,
    IReadOnlyList<Mitigation> Mitigations,
    IReadOnlyDictionary<string,string> Metadata);

---

3. Scoring policy (default)

Evidence class	Base score contribution
Static path (call graph)	≥ 30
Runtime hit	≥ 60
User-tainted flow	≥ 80
“Constraints removed”	= 100
Lockfile-only evidence	10 (if no other signals)

Mitigations subtract up to 40 points (configurable):

effectiveScore = baseScore - min(sum(m.Strength), 1.0) * MaxMitigationDelta

Clamp final scores to 0–100.

---

4. State & VEX gates

Default thresholds (edit in reachability.policy.yml):

State	Score range
UNOBSERVED	0–9
POSSIBLE	10–29
STATIC_PATH	30–59
DYNAMIC_SEEN	60–79
DYNAMIC_USER_TAINTED	80–99
EXPLOIT_CONSTRAINTS_REMOVED	100

VEX mapping:

• not_affected: score ≤ 25 or mitigations dominate (score reduced below threshold).
• affected: score ≥ 60 (dynamic evidence without sufficient mitigation).
• under_investigation: everything between.

Each decision records reachability.policy.version, analyzer versions, policy hash, and config snapshot so downstream verifiers can replay the exact logic.

---

5. Evidence sources

Signal group	Producers	EvidenceKind
Static call graph	Roslyn/IL walkers, ASP.NET routing models, JVM/JIT analyzers	StaticCallEdge, StaticEntryPointProximity, StaticFrameworkRouteEdge
Runtime sampling	.NET EventPipe, JFR, Node inspector, Go/Rust probes	RuntimeMethodHit, RuntimeStackSample, RuntimeHttpRouteHit
Data/taint	Taint analyzers, user-input detectors	UserInputSource, DataTaintFlow
Environment	Config snapshot, container args, network policy	ConfigFlagOn/Off, ContainerNetworkRestricted/Open
Mitigations	WAF connectors, patch diff, kill switches	MitigationKind.* via Mitigation records
Trust	Vendor VEX statements, manual overrides	VendorVexNotAffected/Affected, ManualOverride

Each evidence object must log Source, timestamps, and references (function IDs, config hashes) so auditors can trace it in the event graph.

---

6. Event graph schema

Persist function-level edges and evidence in Mongo (or your event store) under:

• reach_functions – documents keyed by FunctionId.
• reach_call_sites – CallSite edges (caller, callee, frameworkEdge).
• reach_evidence – array of Evidence per (scanId, vulnId, component).
• reach_mitigations – array of Mitigation entries with config hashes.
• reach_decisions – final ReachDecision document; references above IDs.

All collections are tenant-scoped and include analyzer/policy version metadata.

---

7. Policy gates → VEX decisions

VEXer consumes ReachDecision and reachability.policy.yml to emit:

{
  "vulnerability": "CVE-2025-1234",
  "products": ["pkg:nuget/Example@1.2.3"],
  "status": "not_affected|under_investigation|affected",
  "status_notes": "Reachability score 22 (Possible) with WAF rule mitigation.",
  "justification": "component_not_present|vulnerable_code_not_present|... or custom reason",
  "action_statement": "Monitor config ABC",
  "impact_statement": "Runtime probes observed 0 hits; static call graph absent.",
  "timestamp": "...",
  "custom": {
    "reachability": {
      "state": "POSSIBLE",
      "score": 22,
      "policyVersion": "reach-1",
      "evidenceRefs": ["evidence:123", "mitigation:456"]
    }
  }
}

Justifications cite specific evidence/mitigation IDs so replay bundles (docs/replay/DETERMINISTIC_REPLAY.md) can prove the decision.

---

8. Runtime probes (overview)

• .NET: EventPipe session watching Microsoft-Windows-DotNETRuntime/Loader,JIT → RuntimeMethodHit.
• JVM: JFR recording with MethodProfilingSample events.
• Node/TS: Inspector or --trace-event-categories node.async_hooks,node.perf sample.
• Go/Rust: pprof/probe instrumentation.

All runtime probes write evidence via IRuntimeEvidenceSink, which deduplicates hits, enriches them with FunctionId, and stores them in reach_evidence.

See src/Scanner/StellaOps.Scanner.WebService/Reachability/Runtime/DotNetRuntimeProbe.cs (once implemented) for reference.

---

9. Roadmap

Task	Description
REACH-LATTICE-401-023	Initial lattice types + scoring engine + event graph schema.
REACH-RUNTIME-402-024	Productionize runtime probes (EventPipe/JFR) with opt-in config and telemetry.
REACH-VEX-402-025	Wire ReachDecision into VEX generator; ensure OpenVEX/CSAF cite reachability evidence.
REACH-POLICY-402-026	Expose reachability gates in Policy DSL & CLI (edit/lint/test).

Keep this doc updated as the lattice evolves or new signals/mitigations are added. *** End Patch