git.stella-ops.org/docs/risk/overview.md

Risk Overview

Source of truth: CONTRACT-RISK-SCORING-002 (published 2025-12-05). Keep fixtures deterministic (UTC timestamps, stable ordering, sealed sample payloads) and avoid external assets.

Purpose

• Explain the risk model at a glance: factors, formulas, scoring semantics (0–100), and severity bands.
• Show how risk flows through StellaOps services (ingest → evaluate → explain → export) and how provenance is preserved.

Scope & Audience

• Audience: policy authors, risk engineers, auditors, and SREs consuming risk outputs.
• In scope: concepts, glossary, lifecycle, artifacts, cross-module data flow diagrams (add after schema approval).
• Out of scope: detailed factor math (goes to formulas.md), API specifics (goes to api.md).

Core Concepts

• Signal → evidence → factor: raw events (scanner, VEX, runtime) become evidence once validated; evidence is normalized into factors listed under profile signals[].
• Profile vs. formula: a profile bundles factor weights, thresholds, overrides, and severity mapping; formulas describe how weighted signals aggregate and when gates short-circuit.
• Provenance: every input keeps its attestation/signature and source hash; explainability echoes profile_hash, factor hashes, and job correlation IDs.
• Explainability payloads: UI/CLI show per-factor contributions (signal_contributions), source hashes, and rule gates; exports reuse the same envelope.
• Determinism: stable ordering (factor type → source → timestamp), UTC ISO-8601 timestamps, fixed precision math, sealed fixtures.

Profiles use normalized factors (exploit likelihood, KEV flag, reachability, runtime evidence, fix availability, asset criticality, provenance trust) to produce 0–1 scores mapped to severity buckets. Simulation and production share the exact code path.

Lifecycle

1. Job submit: POST /api/v1/risk/jobs with tenant_id, context_id, profile_id, finding list; request is signed and queued.
2. Evidence ingestion: scanner surface + reachability graphs, Zastava runtime signals, VEX/KEV feeds, mirror bundles (offline).
3. Normalization: clamp units to 0–1, apply TTL/decay, dedupe by provenance hash, map to canonical factor catalog.
4. Profile evaluation: apply weighted sum and overrides; respect gates (e.g., KEV + reachability) and Authority-imposed rules.
5. Severity assignment: map normalized_score to severity levels (critical/high/medium/low/informational) with rationale.
6. Explainability & observability: emit per-factor contribution table, provenance pointers, evaluation latency metrics; surface via /risk/jobs/{id} and export bundles.
7. Export/archival: package explainability + profile version/hash for Findings Ledger/Export Center; mirror-friendly.

Artifacts & Schemas

• Contract: CONTRACT-RISK-SCORING-002 (2025-12-05) — risk scoring jobs, results, and profile model.
• Profile schema fields: id, version, description, optional extends, signals[] {name, source, type, path, transform, unit}, weights{}, overrides{severity[], decisions[]}, metadata, provenance.
• Job/result fields: job_id, profile_hash, normalized_score, severity, signal_values, signal_contributions, optional overrides and timestamps.
• Explainability envelope: reuse signal_contributions + profile_hash; store fixtures under docs/risk/samples/explain/.

Determinism & Offline Posture

• Use frozen fixture sets with SHA256 tables; keep manifests in docs/risk/samples/*/SHA256SUMS.
• Regenerate examples via documented scripts only; no live network calls.
• Simulation, API, UI, and export consumers must share the same deterministic ordering and precision.

Open Items

• Need real payload fixtures (jobs + explainability traces) and UI telemetry captures; placeholders remain in samples folders.

References (to link once available)

• docs/risk/profiles.md
• docs/risk/factors.md
• docs/risk/formulas.md
• docs/risk/api.md