6c1177a6ce
- Updated API documentation for risk endpoints to include optional caching headers and error catalog references. - Added a new error catalog JSON file to standardize error responses. - Improved explainability documentation with sample outputs for console and CLI. - Added SHA256 checksums for new sample files related to explainability. - Refined AocGuard tests to utilize a helper method for generating test JSON, improving readability and maintainability. - Updated runbook references to ensure consistency in sprint documentation. - Introduced stub implementations for MongoDB storage interfaces and options, laying groundwork for future development. - Disabled analytics in Angular CLI configuration for privacy considerations.
37 lines
2.2 KiB
Markdown
37 lines
2.2 KiB
Markdown
# Risk Explainability
|
|
|
|
> Source: `CONTRACT-RISK-SCORING-002` (2025-12-05). Fixtures live under `docs/risk/samples/explain/`; all hashes in `SHA256SUMS`. Keep outputs deterministic (frozen payloads, stable ordering).
|
|
|
|
## Purpose
|
|
- Show how the scoring engine produces per-factor contributions and traces that UI/CLI/export surfaces render for auditors and operators.
|
|
|
|
## Scope & Audience
|
|
- Audience: Console/CLI users, auditors, SREs.
|
|
- In scope: explainability payload shape, field meanings, provenance, UI/CLI mapping, offline/export behavior.
|
|
- Out of scope: formula math (see `formulas.md`), API specifics (see `api.md`).
|
|
|
|
## Payload Shape
|
|
- Envelope: `job_id`, `tenant_id`, `context_id`, `profile_id`, `profile_version`, `profile_hash`, `finding_id`, `raw_score`, `normalized_score`, `severity`, `signal_values{}`, `signal_contributions{}`, optional `override_applied`, `override_reason`, `gates_triggered[]`, `scored_at`, `provenance` (job hash + fixture hashes).
|
|
- Factor entries (from `signal_values`/`signal_contributions`): `name`, `source`, `type`, `path`, `raw_value`, `normalized_value`, `weight`, `contribution`, `provenance`.
|
|
- UI/CLI expectations: deterministic ordering (factor type → source → timestamp), highlight top contributors, show attestation status for each factor.
|
|
|
|
## UI/CLI Views
|
|
- Console: frame sample in `docs/risk/samples/explain/console-frame.json` shows top contributors, gate badges, and provenance hashes.
|
|
- CLI `stella risk explain job-001`: deterministic text fixture in `docs/risk/samples/explain/cli-explain.txt`; `--json` mirrors `explain-trace.json`.
|
|
- Export Center: embed explain payload + SHA256 manifest; CSV export keeps deterministic ordering.
|
|
|
|
## Determinism & Offline Posture
|
|
- Example payload: `docs/risk/samples/explain/explain-trace.json` (hash in `SHA256SUMS`).
|
|
- No live calls; all captures from frozen fixtures. Use exact ordering and timestamps when regenerating.
|
|
|
|
## Open Items
|
|
- Capture UI telemetry screenshots/frames for console + CLI to replace textual description.
|
|
- Add schema file once JSON schema is frozen; update references accordingly.
|
|
|
|
## References
|
|
- `docs/risk/overview.md`
|
|
- `docs/risk/profiles.md`
|
|
- `docs/risk/factors.md`
|
|
- `docs/risk/formulas.md`
|
|
- `docs/risk/api.md`
|