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

Risk Profiles

Contract source: CONTRACT-RISK-SCORING-002 (published 2025-12-05). This file supersedes docs/risk/risk-profiles.md once fixtures are added.

Purpose

• Define how profiles group factors, weights, thresholds, and severity bands.
• Describe authoring, simulation, promotion, rollback, and provenance for profiles.

Scope & Audience

• Audience: policy authors, risk engineers, platform SREs.
• Coverage: profile schema, lifecycle, governance, promotion paths, rollback, and observability hooks.

Schema (from CONTRACT-RISK-SCORING-002)

• Required: id, version, description, signals[], weights, metadata.
• signals[] fields: name, source, type (numeric|boolean|categorical), path, optional transform, optional unit.
• Overrides: overrides.severity[] { when, set }, overrides.decisions[] { when, action, reason }.
• Optional: extends, rollout flags, tenant overrides, valid_from/valid_until.
• Storage rules: immutable once promoted; each change creates a new version with DSSE envelope and SHA256 manifest entry (docs/risk/samples/profiles/SHA256SUMS).

Example Profile (contract snippet)

{
  "id": "default-profile",
  "version": "1.0.0",
  "description": "Default risk profile for vulnerability prioritization",
  "extends": "base-profile",
  "signals": [
    { "name": "cvss", "source": "nvd", "type": "numeric", "path": "/cvss/base_score", "transform": "normalize_10", "unit": "score" },
    { "name": "kev", "source": "cisa", "type": "boolean", "path": "/kev/in_catalog" },
    { "name": "reachability", "source": "scanner", "type": "numeric", "path": "/reachability/score" }
  ],
  "weights": { "cvss": 0.4, "kev": 0.3, "reachability": 0.3 },
  "overrides": {
    "severity": [{ "when": { "kev": true }, "set": "critical" }],
    "decisions": [{ "when": { "kev": true, "reachability": { "$gt": 0.8 } }, "action": "deny", "reason": "KEV with high reachability" }]
  },
  "metadata": {}
}

Severity Levels

Level	Value	Priority
Critical	critical	1
High	high	2
Medium	medium	3
Low	low	4
Informational	informational	5

Lifecycle (outline)

1. Authoring in Policy Studio (draft state)
2. Simulation against fixtures (deterministic inputs)
3. Review/approval workflow
4. Promotion to environments (dev → staging → prod)
5. Rollback hooks and audit trail

Governance & Determinism

• Profiles stored with DSSE/signatures; fixtures recorded in docs/risk/samples/profiles/SHA256SUMS.
• Simulation and production share the same evaluation codepath; feature flags must be documented in metadata.flags.
• Offline posture: include profiles, fixtures, and explainability bundles inside mirror packages with manifest hashes.

Explainability & Observability

• Per-factor contribution outputs (JSON) with stable ordering (factor type → source).
• Metrics: evaluation latency (p50/p95), cache hit ratio, factor coverage %, profile hit rate, failed provenance validations.
• Dashboards/alerts: to be filled when telemetry payloads arrive; reserve panels for gating violations and override usage.

Open Items

• Add signed fixtures (profiles + hashes) under docs/risk/samples/profiles/ once payloads arrive.
• Capture feature-flag list for registry alignment.
• Telemetry field list for dashboards/alerts.
• Finalize migration note when legacy docs/risk/risk-profiles.md is archived.

References

• docs/risk/overview.md
• docs/risk/factors.md
• docs/risk/formulas.md
• docs/risk/explainability.md
• docs/risk/api.md
• Existing context: docs/risk/risk-profiles.md (to reconcile once schema lands)

Interim Notes (carried from legacy docs/risk/risk-profiles.md)

• Profiles define how evidence (CVSS/EPSS-like exploit likelihood, KEV flags, VEX status, reachability, runtime evidence, fix availability, asset criticality, provenance trust) normalizes into a 0–100 score with severity buckets.
• Workflow highlights: author in Policy Studio → simulate with fixtures → activate in Policy Engine → explain outputs in CLI/Console → export for auditors via Export Center.
• Governance: draft/review/approval with DSSE/signatures; rollback hooks and promotion gates enforced by Authority scopes; determinism required (same codepath for simulation and production).
• Observability: record scoring latency, factor distribution, and profile usage; offline posture via mirror bundles with fixtures and hash manifests.