stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
49922dff5ad4435420dac177e832ba4290ceaea9
git.stella-ops.org/docs/risk/explainability.md
StellaOps Bot 2eaf0f699b
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
devportal-offline / build-offline (push) Has been cancelled
Details
Mirror Thin Bundle Sign & Verify / mirror-sign (push) Has been cancelled
Details
feat: Implement air-gap functionality with timeline impact and evidence snapshot services 
- Added AirgapTimelineImpact, AirgapTimelineImpactInput, and AirgapTimelineImpactResult records for managing air-gap bundle import impacts.
- Introduced EvidenceSnapshotRecord, EvidenceSnapshotLinkInput, and EvidenceSnapshotLinkResult records for linking findings to evidence snapshots.
- Created IEvidenceSnapshotRepository interface for managing evidence snapshot records.
- Developed StalenessValidationService to validate staleness and enforce freshness thresholds.
- Implemented AirgapTimelineService for emitting timeline events related to bundle imports.
- Added EvidenceSnapshotService for linking findings to evidence snapshots and verifying their validity.
- Introduced AirGapOptions for configuring air-gap staleness enforcement and thresholds.
- Added minimal jsPDF stub for offline/testing builds in the web application.
- Created TypeScript definitions for jsPDF to enhance type safety in the web application.
2025-12-06 01:30:08 +02:00

2.1 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

  • 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