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

## Module
Attestor

## Status
VERIFIED

## 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

## Verification

| Check | Result |
|-------|--------|
| Tier 0 - Source Verification | PASS |
| Tier 1 - Build + Code Review | PASS |
| Tier 2 - Behavioral Verification | PASS |
| Verified Date | 2026-02-13 |
| Run ID | run-001 |