stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
359fafa9da86cf6722ed82bf90d67db9c8f81b17
git.stella-ops.org/docs/features/checked/api/policy-trace-panel.md
master 5bca406787 save checkpoint: save features
2026-02-12 10:27:23 +02:00

3.3 KiB
Raw Blame History

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

Module

Api

Status

VERIFIED

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

  • Query finding summaries (GET /api/v1/findings/summaries) with auth and verify structured summary payload is returned.
  • Query summary with invalid finding ID and verify 400 problem-details response.
  • Query unknown finding summary and verify 404.
  • Query unknown finding evidence graph and verify 404.
  • Query summaries without auth and verify 401.

Verification

  • Verified on 2026-02-11 via FLOW Tier 0/1/2 replay in run-001.
  • Tier 0: docs/qa/feature-checks/runs/api/policy-trace-panel/run-001/tier0-source-check.json
  • Tier 1: docs/qa/feature-checks/runs/api/policy-trace-panel/run-001/tier1-build-check.json
  • Tier 2: docs/qa/feature-checks/runs/api/policy-trace-panel/run-001/tier2-api-check.json