59 lines
4.3 KiB
Markdown
59 lines
4.3 KiB
Markdown
# Declarative Multi-Modal Policy Engine
|
|
|
|
## Module
|
|
Policy
|
|
|
|
## Status
|
|
IMPLEMENTED
|
|
|
|
## 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
|
|
- [ ] Compile a YAML policy with CVSS threshold, EPSS threshold, and VEX trust gates; verify compiled bundle is valid
|
|
- [ ] Evaluate a finding against compiled policy; verify verdict includes gate decisions from all applicable gates
|
|
- [ ] Evaluate with VEX trust gate; verify per-environment threshold enforcement (production stricter than development)
|
|
- [ ] Evaluate with determinism guard enabled; verify GuardedPolicyEvaluator wraps evaluation and reports no violations
|
|
- [ ] Submit policy YAML with wall-clock usage; verify ProhibitedPatternAnalyzer detects violation
|
|
- [ ] Evaluate finding with evidence-weighted scoring; verify proof-aware score includes evidence references
|
|
- [ ] Evaluate finding with ClaimScoreMerger; verify conflicting claims are penalized and winning claim selected
|
|
- [ ] Use counterfactual engine on blocked finding; verify paths to pass are returned
|
|
- [ ] POST policy lint endpoint with invalid YAML; verify lint errors returned
|
|
- [ ] Compile and evaluate same policy+finding twice; verify deterministic verdict (identical results)
|