Documentation
¶
Overview ¶
Package runtimereach is the coordinator that turns an OBSERVED runtime library load on a monitored host (EPIC #1042 #1061) into a CONFIRMED, RAISE-ONLY reachability Judgment, reusing the existing audited propose→verify gate rather than any new confirmed-state path. It sits beside reachproof and mirrors its safety design, differing only in that runtime observation is raise-only:
- It mints ONLY reachable claims at TierRuntime, never a not_reachable one. The absence of a load is not evidence of unreachability, so no observation ever suppresses a finding.
- Its reserved identities (ProofActorRuntimeLibLoadedScan / Engine) are absent from IsDeterministicReachabilityProof, so a runtime verdict can never become a VEX not_affected even though it is confirmed. TierRuntime also falls through SuppressesFinding to false.
- The join that produces the per-finding hits is by PACKAGE OWNERSHIP (internal/domain/runtimereach), never a bare path, so a path collision never misattributes a load to the wrong finding.
SAFETY: proposer = the scan, verifier = the engine, two RESERVED, mutually-distinct, non-agent/non-human identities, so the domain self-confirm guard holds. Supersession is append-only: a new judgment row plus an audit entry naming both sides; the prior judgment is never mutated or deleted. It is not agent-reachable (composition-root-only), enforced by TestNotAgentReachable.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FindingPackages ¶
func FindingPackages(findings []finding.Finding) []runtimereach.FindingPackage
FindingPackages derives the finding-to-package bindings the domain join keys on, from each SCA finding's DedupKey (which parses to advisory+component+version). Only vuln-derived SCA findings carry that key; a license, SAST, or non-SCA finding has no owning OS package and is skipped, so a runtime load can only ever raise an actual OS-package vulnerability. The component name and version are exactly what the host's package database records, so the domain join matches them against a resolved package by identity.
Types ¶
type Coordinator ¶
type Coordinator struct {
// contains filtered or unexported fields
}
Coordinator records raise-only runtime-reachability judgments from observed host library loads.
func NewCoordinator ¶
func NewCoordinator(r recorder, audit ports.AuditLogger, clock ports.Clock) (*Coordinator, error)
NewCoordinator validates dependencies and returns a coordinator that mints TierRuntime library-load judgments under the reserved runtime-libloaded identities.
func (*Coordinator) Record ¶
func (c *Coordinator) Record(ctx context.Context, engagementID shared.ID, hits []runtimereach.Hit) (int, error)
Record mints a raise-only TierRuntime reachable judgment for each finding whose owning package was observed loaded (a domain runtimereach.Hit). It returns the number of judgments minted. A judgment is minted only when it SUPERSEDES the prior reachability judgment (or there is none), so a finding already proven reachable at TierRuntime does not churn, and a runtime observation legitimately supersedes a weaker static verdict (including a prior static not_reachable, which observed execution refutes). It never mints not_reachable, so it can never lower a finding's priority or drive a VEX not_affected.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service ties the package-ownership join to the raise-only coordinator: given a host's observed library loads and its package file-ownership database, it raises exactly the SCA findings whose vulnerable OS package was loaded. It is the entry point the fleet host-vulnerability path drives after a host reports runtime evidence.
func NewService ¶
func NewService(findings findingReader, coordinator *Coordinator) (*Service, error)
NewService validates dependencies and returns the join service.
func (*Service) Attribute ¶
func (s *Service) Attribute(ctx context.Context, engagementID shared.ID, ownership *runtimereach.Ownership, loads []runtimereach.LoadEvent) (int, error)
Attribute resolves each observed load to its owning package, joins the resolved packages to the engagement's SCA findings by package ownership, and mints a raise-only runtime-reachability judgment for every finding whose package was loaded. It returns the number of judgments minted. A load that resolves to no package, or a package no finding is about, mints nothing; nothing is ever de-escalated.
Source Files