stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/features/checked/policy/declarative-multi-modal-policy-engine.md
master 9ca2de05df more features checks. setup improvements
2026-02-13 02:04:55 +02:00

4.9 KiB
Raw Permalink Blame History

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

  • 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)

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/