stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity

save checkpoint

Browse Source
This commit is contained in:
master
2026-02-14 09:11:48 +02:00
parent 9ca2de05df
commit e9aeadc040
1512 changed files with 30863 additions and 4728 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/features/checked/attestor/per-finding-explainability.md Normal file
View File

@@ -0,0 +1,43 @@
# 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 |