# Risk Factors

> Aligned to `CONTRACT-RISK-SCORING-002` (published 2025-12-05). Keep fixtures deterministic and offline-friendly.

## Purpose
- Catalog supported factors (exploit likelihood, VEX state, reachability, runtime facts, fix availability, asset criticality, provenance trust, tenant overrides) and how they normalize into risk math.

## Scope & Audience
- Audience: risk engineers, policy authors, platform SREs.
- In scope: factor definitions, required/optional fields, normalization rules, TTLs, provenance expectations.
- Out of scope: full formula math (see `formulas.md`), API wiring (see `api.md`).

## Factor Catalog (mirrors profile `signals[]`)
| Factor | Required fields | Optional fields | Notes |
| --- | --- | --- | --- |
| CVSS / exploit likelihood | `name`, `source`, `type:"numeric"`, `path`, `transform:"normalize_10"` | `unit:"score"`, `last_seen`, `confidence` | Normalize 0–10 to 0–1; clamp and keep original in provenance. |
| KEV flag | `name`, `source`, `type:"boolean"`, `path` | `last_seen` | Boolean boost; drives severity overrides/decisions. |
| Reachability | `name`, `source`, `type:"numeric"`, `path` | `unit:"score"`, `guards` | May fuse static reachability + runtime observation; ordered by entrypoint/path hash. |
| Runtime facts | `name`, `source`, `type:"categorical" or "numeric"`, `path` | `trace_id`, `span_id` | Includes host/container identity and provenance for runtime traces. |
| Fix availability | `name`, `source`, `type`, `path` | `mitigation`, `vendor_status` | Decay older advisories; keep mitigation text intact. |
| Asset criticality | `name`, `source`, `type`, `path` | `tenant_scope`, `owner` | Used as multiplier/guard in formulas. |
| Provenance trust | `name`, `source`, `type:"categorical"`, `path` | `key_id`, `chain_of_custody` | Gate low-trust inputs; must carry attestation hash. |
| Custom overrides | `name`, `source`, `type`, `path` | `override_reason`, `reviewer`, `expires_at` | Logged and expiring; surfaced in `signal_contributions`. |

## Normalization Rules
- Validate against profile `signals.type` and known transforms; reject unknown fields.
- Clamp numeric inputs to 0–1; record original value in provenance for audit.
- TTL/decay: apply per-factor defaults (pending payload fixtures); drop expired signals deterministically.
- Precedence: signed → unsigned; runtime → static; newer → older; when tied, lowest hash order.

Interim notes: follow legacy profile guidance — preserve provenance, never mutate source evidence, and keep ordering stable so explainability hashes are repeatable across UI/CLI/exports.

## Determinism & Ordering
- Sort factors by `factor_type` then `source` then `timestamp_utc`; deterministic hashing for fixtures.
- Record SHA256 for sample payloads in `docs/risk/samples/factors/SHA256SUMS` once provided.

## Open Items
- Sample payloads per factor for fixtures + hashes.
- TTL/decay parameters from Risk Engine Guild.
- Provenance attestation examples (signed runtime traces, KEV ingestion evidence).

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