stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
fa4823f46c4bc090294580a9136fb6b0e11e50f9
git.stella-ops.org/docs/features/unchecked/attestor/per-finding-explainability.md

2.9 KiB
Raw Blame History

Per-Finding Explainability (SBOM Node, Match Rule, VEX Gate, Reachability Trace)

Module

Attestor

Status

IMPLEMENTED

Description

Finding summaries, verdict decisions with inputs/outputs, and policy decisions are modeled for per-finding explainability.

Implementation Details

  • Finding Summary: src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/FindingSummary.cs -- summary of a single finding with CVE, component, severity, and explanation.
  • Verdict Decision: Statements/VerdictDecision.cs -- the security decision (Pass/Fail/Warn) for a finding.
  • Verdict Inputs: Statements/VerdictInputs.cs -- all inputs considered for the decision (scan results, SBOM data, reachability analysis, VEX statements).
  • Verdict Outputs: Statements/VerdictOutputs.cs -- outputs produced (policy violations, applied exceptions, risk justifications).
  • Policy Decision: Predicates/PolicyDecision.cs -- individual policy rule evaluation result for a finding. PolicyDecisionPredicate.cs -- full predicate model.
  • Reasoning Predicate: Predicates/ReasoningPredicate.cs -- reasoning chain explaining why a decision was made. Statements/ReasoningStatement.cs -- in-toto wrapper.
  • Evidence Predicate: Predicates/EvidencePredicate.cs -- evidence supporting the decision. Statements/EvidenceStatement.cs -- in-toto wrapper.
  • VEX Verdict Summary: Predicates/VexVerdictSummary.cs -- VEX verdict explaining exploitability status for the finding.
  • Reachability Witness: Statements/ReachabilityWitnessPayload.cs (with .Path) -- reachability trace from entrypoint to vulnerable function.
  • SBOM Reference: Predicates/SbomReference.cs -- link to the SBOM node (component) for the finding.
  • Explanation Graph: Graph/InMemoryProofGraphService.cs (with .Queries, .Subgraph) -- query explanation paths from verdict to evidence.
  • Tests: __Tests/StellaOps.Attestor.ProofChain.Tests/FindingSummaryTests.cs

E2E Test Plan

  • Create a FindingSummary with CVE, component, and severity; verify all fields are populated
  • Build a VerdictDecision with VerdictInputs (SBOM match, scan result, VEX statement) and VerdictOutputs (policy violation); verify the decision is explainable
  • Create a PolicyDecisionPredicate with a matching rule name and verify the rule is linked to the finding
  • Build a ReasoningPredicate explaining why a finding was marked "not_affected" and verify it references evidence IDs
  • Link a finding to its SBOM node via SbomReference and verify the component name, version, and bom-ref are correct
  • Create a reachability trace via ReachabilityWitnessPayload showing the call path to the vulnerable function and verify it is linked to the finding
  • Query the explanation graph via InMemoryProofGraphService.Queries from a verdict node to all evidence nodes and verify the complete explanation chain