stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
cf5b72974f923126944f4dcd47e85864ebb31a3b
git.stella-ops.org/docs/features/unchecked/policy/delta-verdict-engine.md

3.7 KiB
Raw Blame History

Delta Verdict Engine

Module

Policy

Status

IMPLEMENTED

Description

Full delta verdict computation comparing two evaluation states, with signed delta JSON, API endpoints for delta generation, and verdict ID generation.

Implementation Details

  • WhatIfSimulationService: src/Policy/StellaOps.Policy.Engine/WhatIfSimulation/WhatIfSimulationService.cs -- WhatIfSimulationService (internal sealed class)
    • SimulateAsync(WhatIfSimulationRequest) computes delta between baseline and simulated evaluation states
    • Supports SBOM diffs: add, remove, upgrade, downgrade operations
    • Computes WhatIfDecisionChange: status_changed, severity_changed, new, removed
    • Decision simulation: new components checked against advisory count, VEX override, reachability downgrade
    • Upgrade simulation: fixed-all -> allow, remaining advisories -> warn
    • Downgrade simulation: with advisories -> deny (higher priority 150)
    • WhatIfSummary: TotalEvaluated, TotalChanged, NewlyAffected, NoLongerAffected, StatusChanges, SeverityChanges, Impact
    • WhatIfImpact: risk delta (increased/decreased/unchanged), blocked/warning deltas, recommendation text
    • Simulation ID generation: whatif-{SHA256(seed)[..16]}
  • WhatIfSimulationModels: src/Policy/StellaOps.Policy.Engine/WhatIfSimulation/WhatIfSimulationModels.cs -- request/response DTOs
    • WhatIfSimulationRequest: TenantId, BaseSnapshotId, SbomDiffs, DraftPolicy, TargetPurls, IncludeExplanations, Limit, CorrelationId
    • WhatIfSbomDiff: Purl, Operation, OriginalVersion, NewVersion, AdvisoryIds, VexStatus, Reachability
    • WhatIfDecision: Status, Severity, RuleName, Priority, HasException
    • WhatIfExplanation: MatchedRules, Factors, VexEvidence, Reachability
  • ConsoleSimulationDiffService: src/Policy/StellaOps.Policy.Engine/Console/ConsoleSimulationDiffService.cs -- deterministic delta diff for console surface
    • Before/After severity breakdowns, delta (added/removed/regressed), rule impact, explain samples
  • SimulationAnalyticsService: src/Policy/StellaOps.Policy.Engine/Simulation/SimulationAnalyticsService.cs -- delta summary computation with severity change tracking
  • Effective Decision Map: src/Policy/StellaOps.Policy.Engine/EffectiveDecisionMap/ -- materialized baseline decisions for delta comparison
  • Simulation Endpoints: src/Policy/StellaOps.Policy.Engine/Endpoints/
    • ConsoleSimulationEndpoint.cs -- console surface simulation diff
    • OverlaySimulationEndpoint.cs -- overlay-based simulation
    • RiskSimulationEndpoints.cs -- risk simulation with breakdowns
  • Attestation: src/Policy/StellaOps.Policy.Engine/Attestation/ -- verdict attestation for signed delta output

E2E Test Plan

  • POST what-if simulation with add component (3 advisories); verify deny decision with severity=high
  • POST what-if simulation with remove component; verify decision=allow and change_type=removed
  • POST what-if simulation with upgrade component fixing all CVEs; verify decision=allow
  • POST what-if simulation with downgrade component with advisories; verify decision=deny with priority 150
  • POST what-if simulation with VEX not_affected override; verify deny overridden to allow
  • POST what-if simulation with unreachable finding; verify deny downgraded to warn
  • Verify delta summary: TotalChanged matches actual number of decision changes
  • Verify impact: risk delta is "increased" when blocked count goes up, "decreased" when it goes down
  • POST with IncludeExplanations=true; verify explanations contain matched rules, SBOM factors, VEX evidence, and reachability
  • POST console simulation diff with two policy versions; verify deterministic before/after severity breakdowns and delta counts