Files

StellaOps Bot f0662dd45f feat: Implement DefaultCryptoHmac for compliance-aware HMAC operations

- 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.

2025-12-06 00:41:04 +02:00

2.9 KiB

Raw Permalink Blame History

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)

{
  "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

2.9 KiB Raw Permalink Blame History Unescape Escape