f0662dd45f
- Added DefaultCryptoHmac class implementing ICryptoHmac interface. - Introduced purpose-based HMAC computation methods. - Implemented verification methods for HMACs with constant-time comparison. - Created HmacAlgorithms and HmacPurpose classes for well-known identifiers. - Added compliance profile support for HMAC algorithms. - Included asynchronous methods for HMAC computation from streams.
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: table of factors sorted by contribution, severity badge, gate badges (e.g., KEV+reachability), link to provenance hashes.
|
|
- CLI `stella risk explain job-001`: render table using fixture `explain-trace.json`; include `--json` option that emits the same payload.
|
|
- 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`
|