stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
44cd1827c23f37e4fc31f6cd89a57efcb3dd1fb8
git.stella-ops.org/docs/features/checked/policy/explainability-with-proof-extracts.md
master 9ca2de05df more features checks. setup improvements
2026-02-13 02:04:55 +02:00

2.9 KiB
Raw Blame History

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