43 lines
2.9 KiB
Markdown
43 lines
2.9 KiB
Markdown
# 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}`
|