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.
63 lines
2.9 KiB
Markdown
63 lines
2.9 KiB
Markdown
# 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`
|