39 lines
2.9 KiB
Markdown
39 lines
2.9 KiB
Markdown
# 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
|