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.
86 lines
4.4 KiB
Markdown
86 lines
4.4 KiB
Markdown
# 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.
|