# 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)
```json
{
  "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.