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

more features checks. setup improvements

Browse Source
This commit is contained in:
master
2026-02-13 02:04:55 +02:00
parent 9911b7d73c
commit 9ca2de05df
675 changed files with 37550 additions and 1826 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/features/checked/policy/explainability-with-proof-extracts.md Normal file
View File

@@ -0,0 +1,38 @@
# Explainability with Proof Extracts
## Module
Policy
## Status
IMPLEMENTED
## Description
Verdict rationale rendering with full explainability system, reachability explanation UI with "why" drawer for interactive proof browsing.
## Implementation Details
- **VerdictRationaleRenderer**: `src/Policy/__Libraries/StellaOps.Policy.Explainability/VerdictRationaleRenderer.cs` (sealed class implements `IVerdictRationaleRenderer`)
- 4-line template rendering with structured evidence, policy clause, attestations, and decision sections
- Evidence section includes reachability details: vulnerable function symbol, entry point, path summary
- Attestation section references: path witnesses (reachability proofs), VEX statements, provenance attestations
- Each attestation includes Id, Type, Digest, and Summary for browsing
- Content-addressed RationaleId (`rat:sha256:{hash}`) enables proof linking
- Multi-format output: PlainText, Markdown, canonical JSON (RFC 8785)
- **VerdictRationale model**: `src/Policy/__Libraries/StellaOps.Policy.Explainability/VerdictRationale.cs`
- `RationaleEvidence` with ComponentIdentity (PURL, name, version, ecosystem) and ReachabilityDetail (VulnerableFunction, EntryPoint, PathSummary)
- `RationaleAttestations` with PathWitness (reachability proof reference), VexStatements (list of VEX attestation references), Provenance
- `RationaleInputDigests` with VerdictDigest, PolicyDigest, EvidenceDigest for full proof chain
- **PolicyExplainTrace**: `src/Policy/StellaOps.Policy.Engine/Materialization/PolicyExplainTrace.cs` -- trace objects for materialized explanations
- **Counterfactual paths**: `src/Policy/__Libraries/StellaOps.Policy/Counterfactuals/CounterfactualEngine.cs` -- "what would fix this" paths linked to rationale
- **Verdict attestation**: `src/Policy/StellaOps.Policy.Engine/Attestation/VerdictAttestationService.cs` -- DSSE-signed verdicts that rationale references
## E2E Test Plan
- [ ] Render verdict rationale for finding with reachability proof; verify Evidence section includes vulnerable function symbol and entry point
- [ ] Render rationale with path witness attestation; verify Attestations.PathWitness.Id and Digest are populated
- [ ] Render rationale with 3 VEX statements; verify all 3 appear in Attestations.VexStatements
- [ ] Render rationale with provenance attestation; verify Provenance.Type and Summary are set
- [ ] Verify RenderMarkdown output includes clickable attestation IDs in Attestations section
- [ ] Verify InputDigests.VerdictDigest matches the actual verdict's content digest
- [ ] Verify InputDigests.EvidenceDigest matches the evidence bundle digest
- [ ] Render rationale for finding without reachability; verify Evidence.Reachability is null and FormattedText omits reachability details
- [ ] Verify RenderJson output can be re-parsed and matches original rationale structure
- [ ] Verify content-addressed RationaleId is stable across serialization roundtrips