ea970ead2a
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
sdk-generator-smoke / sdk-smoke (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
api-governance / spectral-lint (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
Mirror Thin Bundle Sign & Verify / mirror-sign (push) Has been cancelled
41 lines
2.1 KiB
Markdown
41 lines
2.1 KiB
Markdown
# Policy Explainers (UI)
|
|
|
|
> **Imposed rule:** Explain views must show evidence hashes, signals, and rule rationale; omit or obfuscate none. AOC tenants must see AOC badge and tenant-only data.
|
|
|
|
This guide describes how the Console renders explainability for policy decisions.
|
|
|
|
## 1. Surfaces
|
|
- **Findings table**: each row links to an explainer drawer.
|
|
- **Explainer drawer**: rule stack, inputs, signals, evidence hashes, reachability path, VEX statements, attestation refs.
|
|
- **Timeline tab**: events for submit/approve/publish/activate and recent runs.
|
|
- **Runs tab**: runId, input cursors, IR hash, shadow flag, coverage evidence.
|
|
|
|
## 2. Drawer layout
|
|
- Header: status, severity, policy version, shadow flag, AOC badge.
|
|
- Evidence panel: SBOM digest, advisory snapshot, VEX IDs, reachability graph hash, runtime hit flag, attestation refs.
|
|
- Rule hits: ordered list with `because`, signals snapshot, actions taken.
|
|
- Reachability path: signed call path when available; shows graph hash + edge bundle hash; link to Verify.
|
|
- Signals: `trust_score`, `reachability.state/score`, `entropy_penalty`, `uncertainty.level`, `runtime_hits`.
|
|
|
|
## 3. Interactions
|
|
- **Verify evidence**: button triggers `stella policy explain --verify` equivalent; shows DSSE/Rekor status.
|
|
- **Toggle baseline**: compare against previous policy version; highlights changed rules/outcomes.
|
|
- **Download**: export explain as JSON with evidence hashes; offline-friendly.
|
|
|
|
## 4. Accessibility
|
|
- Keyboard navigation: Tab order header → evidence → rules → actions; Enter activates verify/download.
|
|
- Screen reader labels include status, severity, reachability state, trust score.
|
|
|
|
## 5. Offline
|
|
- Drawer works on offline bundles; verify uses embedded DSSE/attestations; if Rekor unavailable, show “offline verify” with bundle digest.
|
|
|
|
## 6. Error states
|
|
- Missing evidence: display `unknown` chips; prompt to rerun when inputs unfrozen.
|
|
- Attestation mismatch: show warning badge and link to governance doc.
|
|
|
|
## References
|
|
- `docs/policy/overview.md`
|
|
- `docs/policy/runtime.md`
|
|
- `docs/policy/governance.md`
|
|
- `docs/policy/api.md`
|