stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
f0662dd45f2f05ab6fd0e67489da5f2008e9c0f9
git.stella-ops.org/docs/risk/explainability.md
StellaOps Bot f0662dd45f feat: Implement DefaultCryptoHmac for compliance-aware HMAC operations 
- 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.
2025-12-06 00:41:04 +02:00

2.2 KiB
Raw Blame History

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