# Risk Formulas

> Based on `CONTRACT-RISK-SCORING-002` (2025-12-05). Keep math examples deterministic with fixed fixtures.

## Purpose
- Describe how normalized factors combine into a 0–100 risk score with severity bands.
- Capture gating, weighting, normalization, and override rules.

## Scope & Audience
- Audience: risk engineers, policy authors, auditors.
- In scope: weighting strategies, aggregation functions, severity thresholds, gating rules, tie-breakers.
- Out of scope: full API payloads (see `api.md`), factor definitions (see `factors.md`).

## Formula Building Blocks
- Weighted sum with per-factor caps; enforce max contribution per family (exploitability, reachability, runtime).
- Base rule (contract): `raw_score = Σ(signal_value × weight)`, `normalized_score = clamp(raw_score, 0.0, 1.0)`.
- VEX gate: if `signals.HasVexDenial`, return `0.0` immediately (mitigated finding).
- CVSS + KEV provider: `score = clamp01((cvss/10) + (kev ? 0.2 : 0))`.
- Guard rails: hard gates when `(exploit_likelihood >= T1) AND (reachability >= T2)` or when provenance trust below minimum.
- Decay/time weighting: exponential decay for stale runtime/KEV signals; fresh VEX `not_affected` may down-weight exploit scores.
- Tenant/asset overrides: additive/override blocks with expiry; always logged in explainability output.
- Safety: divide-by-zero and null handling must be deterministic and reflected in explain trace.

## Severity Mapping
- Contract levels: `critical`, `high`, `medium`, `low`, `informational` (priority 1–5).
- Map `normalized_score` to bands per profile policy; include band rationale in explainability payload.

## Determinism
- Stable ordering of factors before aggregation.
- Use fixed precision (e.g., 4 decimals) before severity mapping; round not truncate.
- Hash fixtures and record SHA256 for every example payload in `docs/risk/samples/formulas/SHA256SUMS`.

Interim notes: mirror legacy rule — simulation and production must share the exact evaluation codepath; no per-environment divergences. Severity buckets must be deterministic and governed by Authority scopes.

## Example (contract-aligned)
```json
{
  "finding_id": "f-123",
  "profile_id": "default-profile",
  "profile_version": "1.0.0",
  "raw_score": 0.75,
  "normalized_score": 0.85,
  "severity": "high",
  "signal_values": { "cvss": 7.5, "kev": true, "reachability": 0.9 },
  "signal_contributions": { "cvss": 0.4, "kev": 0.3, "reachability": 0.3 },
  "override_applied": "kev-boost",
  "override_reason": "Known Exploited Vulnerability",
  "scored_at": "2025-12-05T00:00:02Z"
}
```
- CLI/Console screenshots pending telemetry assets (keep deterministic fixture IDs).

## Open Items
- Fixtures for jobs/results and explainability traces.
- Final per-profile severity thresholds (document once agreed).
- UI traces for console/CLI explainability views.

## References
- `docs/risk/overview.md`
- `docs/risk/profiles.md`
- `docs/risk/factors.md`
- `docs/risk/api.md`