66 lines
4.9 KiB
Markdown
66 lines
4.9 KiB
Markdown
# Declarative Multi-Modal Policy Engine
|
|
|
|
## Module
|
|
Policy
|
|
|
|
## Status
|
|
VERIFIED
|
|
|
|
## Description
|
|
Policy engine with 12+ gate types, trust lattice merge, OPA adapter integration, policy DSL, evidence-weighted scoring, and determinization gates covering CVSS, EPSS, VEX trust, reachability, unknowns, SBOM presence, and signature requirements.
|
|
|
|
## Implementation Details
|
|
- **Policy Evaluator**: `src/Policy/StellaOps.Policy.Engine/Evaluation/PolicyEvaluator.cs` -- core policy evaluation with expression evaluation
|
|
- `PolicyExpressionEvaluator.cs` -- evaluates policy expressions against findings
|
|
- `PolicyEvaluationContext.cs` -- evaluation context with tenant, snapshot, and environment info
|
|
- `VerdictSummary.cs` -- verdict summary generation
|
|
- **Policy Gates**: `src/Policy/StellaOps.Policy.Engine/Gates/`
|
|
- `PolicyGateEvaluator.cs` -- multi-gate orchestrator with 5 gate stages (Evidence, Lattice, VEX Trust, Uncertainty, Confidence)
|
|
- `VexTrustGate.cs` -- VEX trust score and signature verification per environment
|
|
- `DriftGateEvaluator.cs` -- drift-based gate for cross-release delta
|
|
- `StabilityDampingGate.cs` -- stability damping to prevent flapping
|
|
- `IDeterminizationGate.cs` -- interface for determinization gates
|
|
- `Gates/Determinization/` -- determinization gate implementations
|
|
- **Trust Lattice**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/`
|
|
- `TrustLatticeEngine.cs` -- K4 four-valued logic evaluation pipeline
|
|
- `ClaimScoreMerger.cs` -- lattice-based merge with conflict penalization
|
|
- VEX normalizers for CycloneDX, OpenVEX, CSAF formats
|
|
- **Policy DSL**: `src/Policy/StellaOps.PolicyDsl/` -- declarative policy language compiler
|
|
- Compiles YAML-based policy definitions into executable evaluation rules
|
|
- **Scoring Engines**: `src/Policy/StellaOps.Policy.Engine/Scoring/`
|
|
- `SimpleScoringEngine.cs`, `AdvancedScoringEngine.cs`, `ProofAwareScoringEngine.cs`
|
|
- `EvidenceWeightedScore/` -- evidence-weighted scoring with proof integration
|
|
- `ProfileAwareScoringService.cs` -- risk profile-driven scoring
|
|
- `ScoringEngineFactory.cs` -- engine selection based on configuration
|
|
- **CVSS Scoring**: `src/Policy/StellaOps.Policy.Scoring/` -- multi-version CVSS engine (v2, v3.x, v4.0)
|
|
- **Determinism Guards**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/`
|
|
- `DeterminismGuardService.cs` -- runtime determinism enforcement
|
|
- `ProhibitedPatternAnalyzer.cs` -- static analysis for non-deterministic patterns
|
|
- `GuardedPolicyEvaluator.cs` -- wraps evaluator with determinism checks
|
|
- **Policy Compilation**: `src/Policy/StellaOps.Policy.Engine/Compilation/` -- policy pack compilation
|
|
- `PolicyCompilationService` -- compiles policy YAML into evaluation bundles
|
|
- Endpoints: `PolicyCompilationEndpoints.cs`, `PolicyLintEndpoints.cs`
|
|
- **Effective Decision Map**: `src/Policy/StellaOps.Policy.Engine/EffectiveDecisionMap/` -- materialized decision lookup
|
|
- **Counterfactuals**: `src/Policy/__Libraries/StellaOps.Policy/Counterfactuals/` -- "what-if" analysis for blocked findings
|
|
- **Simulation**: `src/Policy/StellaOps.Policy.Engine/Simulation/` -- risk simulation with breakdowns
|
|
- **Unknowns Integration**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/` -- unknowns ranking and budget enforcement
|
|
|
|
## E2E Test Plan
|
|
- [x] Compile a YAML policy with CVSS threshold, EPSS threshold, and VEX trust gates; verify compiled bundle is valid
|
|
- [x] Evaluate a finding against compiled policy; verify verdict includes gate decisions from all applicable gates
|
|
- [x] Evaluate with VEX trust gate; verify per-environment threshold enforcement (production stricter than development)
|
|
- [x] Evaluate with determinism guard enabled; verify GuardedPolicyEvaluator wraps evaluation and reports no violations
|
|
- [x] Submit policy YAML with wall-clock usage; verify ProhibitedPatternAnalyzer detects violation
|
|
- [x] Evaluate finding with evidence-weighted scoring; verify proof-aware score includes evidence references
|
|
- [x] Evaluate finding with ClaimScoreMerger; verify conflicting claims are penalized and winning claim selected
|
|
- [x] Use counterfactual engine on blocked finding; verify paths to pass are returned
|
|
- [x] POST policy lint endpoint with invalid YAML; verify lint errors returned
|
|
- [x] Compile and evaluate same policy+finding twice; verify deterministic verdict (identical results)
|
|
|
|
## Verification
|
|
- **Run ID**: run-002
|
|
- **Date**: 2026-02-12
|
|
- **Tests**: 2621 tests passed across 4 projects (PolicyDsl: 140, Policy: 781, Determinization: 438, Engine: 1262); 1 pre-existing unrelated failure in Engine.Tests
|
|
- **Bugs Fixed**: 8 test/implementation bugs in Determinization.Tests (EWS risk tier assertion, kev_floor guardrail interaction, ArgumentException/ArgumentNullException type mismatch x2, score bounds min/max swap in DeltaIfPresentCalculator, triage priority threshold vs decay floor mismatch x2, speculative cap overriding kev_floor)
|
|
- **Evidence**: `docs/qa/feature-checks/runs/policy/declarative-multi-modal-policy-engine/run-002/`
|