52 lines
4.3 KiB
Markdown
52 lines
4.3 KiB
Markdown
# CVE-Aware Release Policy Gates (EPSS/KEV/Reachable/Delta/Aggregate)
|
|
|
|
## Module
|
|
Policy
|
|
|
|
## Status
|
|
VERIFIED
|
|
|
|
## Description
|
|
Five specialized CVE-aware policy gates (EpssThresholdGate, KevBlockerGate, ReachableCveGate, CveDeltaGate, ReleaseAggregateCveGate) that use real-time EPSS scores, KEV catalog membership, reachability status, and cross-release delta to make gate decisions. Distinct from existing generic "CVSS Threshold Gate" or "EPSS Threshold Policy Gate" because these are an integrated multi-gate system with OPA/Rego support.
|
|
|
|
## Implementation Details
|
|
- **PolicyGateEvaluator**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateEvaluator.cs` -- orchestrates multi-gate evaluation
|
|
- Evaluates gates in sequence: Evidence -> Lattice State -> VEX Trust -> Uncertainty Tier -> Confidence
|
|
- Short-circuits on first Block; accumulates warnings from non-blocking gates
|
|
- Override support with justification requirement
|
|
- **VexTrustGate**: `src/Policy/StellaOps.Policy.Engine/Gates/VexTrustGate.cs` -- VEX trust-based gate with per-environment thresholds
|
|
- `VexTrustGateOptions`: per-environment `VexTrustThresholds` with MinCompositeScore and RequireIssuerVerified
|
|
- `MissingTrustBehavior`: Block, Warn, or Allow when trust data absent
|
|
- Trust tiers: VeryHigh >= 0.9, High >= 0.7, Medium >= 0.5, Low >= 0.3, VeryLow < 0.3
|
|
- **DriftGateEvaluator**: `src/Policy/StellaOps.Policy.Engine/Gates/DriftGateEvaluator.cs` -- drift-based gate for cross-release delta
|
|
- `DriftGateOptions`: configurable via `DriftGateContext`
|
|
- **StabilityDampingGate**: `src/Policy/StellaOps.Policy.Engine/Gates/StabilityDampingGate.cs` -- stability damping for flapping prevention
|
|
- `StabilityDampingOptions`: configurable damping parameters
|
|
- **PolicyGateDecision Model**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateDecision.cs`
|
|
- Decision types: Allow, Warn, Block
|
|
- Contains: GateId, Subject (VulnId/Purl/SymbolId/ScanId), Evidence (LatticeState/UncertaintyTier/GraphHash/RiskScore/Confidence), Gates array, Advisory, BlockedBy, BlockReason, Suggestion
|
|
- **Reachability Lattice States**: U (Unknown), SR (StaticallyReachable), SU (StaticallyUnreachable), RO (RuntimeObserved), RU (RuntimeUnobserved), CR (ConfirmedReachable), CU (ConfirmedUnreachable), X (Contested)
|
|
- **Uncertainty Tiers**: T1 (High), T2 (Medium), T3 (Low), T4 (Negligible)
|
|
- **UnknownRanker Integration**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Services/UnknownRanker.cs` -- exploit pressure factors (KEV +0.50, EPSS >= 0.90 +0.30, EPSS >= 0.50 +0.15, CVSS >= 9.0 +0.05)
|
|
- **Scoring Integration**: `src/Policy/StellaOps.Policy.Engine/Scoring/` -- profile-aware scoring with EPSS/CVSS/KEV inputs
|
|
- **Gate Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/PolicyDecisionEndpoint.cs` -- REST API for gate evaluation
|
|
|
|
## E2E Test Plan
|
|
- [x] Evaluate gate for not_affected with CU lattice state and T4 uncertainty; verify Allow decision
|
|
- [x] Evaluate gate for not_affected with CR lattice state; verify Block with suggestion to submit unreachability evidence
|
|
- [x] Evaluate gate for not_affected with missing graphHash; verify Block by EvidenceCompleteness gate
|
|
- [x] Evaluate gate with VEX trust score below production threshold; verify Block by VexTrust gate
|
|
- [x] Evaluate gate with VEX trust score above threshold but signature unverified; verify Block when RequireIssuerVerified=true
|
|
- [x] Evaluate gate with T1 uncertainty for not_affected and BlockT1ForNotAffected=true; verify Block by UncertaintyTier gate
|
|
- [x] Evaluate gate with KEV finding using UnknownRanker; verify exploit pressure includes +0.50 KEV factor
|
|
- [x] Evaluate gate with EPSS=0.95; verify exploit pressure includes +0.30 EPSS factor
|
|
- [x] Evaluate gate with override and valid justification; verify Block overridden to Warn with advisory
|
|
- [x] Evaluate gate with Contested (X) lattice state for not_affected; verify Block with suggestion to resolve through triage
|
|
|
|
## Verification
|
|
- **Run ID**: run-002
|
|
- **Date**: 2026-02-12
|
|
- **Tests**: 52 targeted gate tests passed (26 PolicyGateEvaluatorTests + 26 CveAwareReleasePolicyGatesDeepTests)
|
|
- **Bugs Fixed**: 2 test compilation errors in CveAwareReleasePolicyGatesDeepTests.cs (FluentAssertions .Or syntax, read-only property assignment)
|
|
- **Evidence**: `docs/qa/feature-checks/runs/policy/cve-aware-release-policy-gates/run-002/`
|