stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
6c1177a6ceab81b77b16ec01a6c859b9e3c12f6a
git.stella-ops.org/docs/risk/explainability.md
StellaOps Bot 6c1177a6ce
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Enhance risk API documentation and error handling 
- 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.
2025-12-06 00:47:29 +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: 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