git.stella-ops.org/docs/features/checked/policy/verdict-explainability-rationale-renderer.md

Verdict Explainability / Rationale Renderer

Module

Policy

Status

IMPLEMENTED

Description

Verdict rationale renderer and rationale model in Policy Explainability library. Testing infrastructure includes explainability assertions, IExplainableDecision interface, and explainability models.

Implementation Details

• VerdictRationaleRenderer: src/Policy/__Libraries/StellaOps.Policy.Explainability/VerdictRationaleRenderer.cs (sealed class implements IVerdictRationaleRenderer)
  • Render(VerdictRationaleInput) produces structured 4-line rationale
  • RenderPlainText(rationale) produces 4-line plain text output
  • RenderMarkdown(rationale) produces Markdown with ## headers (Evidence, Policy Clause, Attestations, Decision)
  • RenderJson(rationale) produces canonical JSON (RFC 8785) via CanonJson.Serialize
  • Content-addressed RationaleId: rat:sha256:{hash} computed from SHA256 of canonical JSON
  • Evidence rendering: CVE ID, component PURL/name/version, reachability (vulnerable function, entry point, path summary)
  • Policy clause rendering: ClauseId, RuleDescription, Conditions
  • Attestation rendering: path witness, VEX statements, provenance references
  • Decision rendering: verdict, score, recommendation, mitigation (action, details)
• VerdictRationale model: src/Policy/__Libraries/StellaOps.Policy.Explainability/VerdictRationale.cs
  • SchemaVersion: "1.0"
  • 4-line template: RationaleEvidence, RationalePolicyClause, RationaleAttestations, RationaleDecision
  • RationaleInputDigests: VerdictDigest, PolicyDigest, EvidenceDigest for reproducibility
  • Supporting records: ComponentIdentity, ReachabilityDetail, AttestationReference, MitigationGuidance
• IVerdictRationaleRenderer: src/Policy/__Libraries/StellaOps.Policy.Explainability/IVerdictRationaleRenderer.cs
  • Interface with Render, RenderPlainText, RenderMarkdown, RenderJson methods
  • VerdictRationaleInput record with full input specification

E2E Test Plan

• Render rationale for CVE-2024-1234 in lodash@4.17.21 with reachability; verify Evidence.FormattedText contains CVE, component, vulnerable function
• Render rationale with policy clause "require-vex-for-critical"; verify PolicyClause.FormattedText includes clause ID and conditions
• Render rationale with 2 VEX attestation references; verify Attestations.FormattedText includes both
• Render rationale without attestations; verify FormattedText says "No attestations available."
• Render same input twice; verify RationaleId is identical (content-addressed determinism)
• Render with score=0.85 and mitigation; verify Decision.FormattedText includes "score 0.85" and mitigation action
• RenderPlainText produces 4-line output (evidence, clause, attestations, decision)
• RenderMarkdown produces valid Markdown with ## headers
• RenderJson produces valid JSON parseable by standard parser
• Verify RationaleId matches format rat:sha256:{64 hex chars}