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

semi implemented and features implemented save checkpoint

Browse Source
This commit is contained in:
master
2026-02-08 18:00:49 +02:00
parent 04360dff63
commit 1bf6bbf395
20895 changed files with 716795 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docs/features/unchecked/attestor/per-finding-explainability.md Normal file
View File

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