stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
1bf6bbf3955ecbd8d20f5eeb767da5c7f8324b57
git.stella-ops.org/docs/features/unchecked/api/policy-trace-panel.md

3.4 KiB
Raw Blame History

Policy trace panel ("why blocked" / "what would make it pass")

Module

Api

Status

IMPLEMENTED

Description

Block explanation API controller, CLI explain commands, and verdict rationale renderer provide policy trace functionality explaining why artifacts are blocked and what would unblock them.

Implementation Details

  • Scoring Endpoints: src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/ScoringEndpoints.cs -- exposes REST endpoints for querying scored findings with policy trace context, including why a finding is blocked and which evidence would change the outcome.
  • Evidence Graph Endpoints: src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/EvidenceGraphEndpoints.cs -- serves evidence graph subgraphs connecting findings to attestations, VEX statements, and policy decisions, showing the trace of what inputs led to the verdict.
  • Finding Summary Endpoints: src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/FindingSummaryEndpoints.cs -- returns finding summaries with policy evaluation trace context including rule names, evaluation outcomes, and evidence references.
  • Finding Scoring Service: src/Findings/StellaOps.Findings.Ledger.WebService/Services/FindingScoringService.cs -- computes and caches finding scores combining CVSS, EPSS, VEX, and reachability signals; explains score composition.
  • Evidence Graph Builder: src/Findings/StellaOps.Findings.Ledger.WebService/Services/EvidenceGraphBuilder.cs -- constructs evidence subgraphs from ledger events and attestation pointers for trace visualization.
  • VEX Consensus Service: src/Findings/StellaOps.Findings.Ledger.WebService/Services/VexConsensusService.cs -- aggregates VEX decisions across sources to explain the consensus status.
  • Policy Evaluation Service: src/Findings/StellaOps.Findings.Ledger/Infrastructure/Policy/PolicyEngineEvaluationService.cs -- evaluates policy rules against findings and returns detailed trace output explaining each rule's contribution.
  • Inline Policy Evaluation Service: src/Findings/StellaOps.Findings.Ledger/Infrastructure/Policy/InlinePolicyEvaluationService.cs -- lightweight inline evaluation for single-finding traces without external policy engine calls.
  • Tests: src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Integration/ScoringEndpointsIntegrationTests.cs, ScoringAuthorizationTests.cs, PolicyEngineEvaluationServiceTests.cs, InlinePolicyEvaluationServiceTests.cs, src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Services/EvidenceGraphBuilderTests.cs, FindingScoringServiceTests.cs

E2E Test Plan

  • Submit a finding that fails policy evaluation and query the trace endpoint to verify the response explains which rule blocked it and what evidence is required to pass
  • Query the evidence graph endpoint for a blocked finding and verify the returned subgraph contains nodes for the finding, its attestations, VEX statements, and policy rules with correct edge relationships
  • Modify a finding's VEX status to "not_affected" and re-query the trace to verify the explanation updates to reflect the new unblocked status
  • Verify authorization: attempt to query trace endpoints without the required scope and confirm a 403 response
  • Verify the inline policy evaluation service returns the same trace results as the full policy engine evaluation service for a simple single-rule scenario