f0662dd45f
- Added DefaultCryptoHmac class implementing ICryptoHmac interface. - Introduced purpose-based HMAC computation methods. - Implemented verification methods for HMACs with constant-time comparison. - Created HmacAlgorithms and HmacPurpose classes for well-known identifiers. - Added compliance profile support for HMAC algorithms. - Included asynchronous methods for HMAC computation from streams.
47 lines
3.1 KiB
Markdown
47 lines
3.1 KiB
Markdown
# 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`
|