35 lines
3.3 KiB
Markdown
35 lines
3.3 KiB
Markdown
# 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
|
|
- [x] Query finding summaries (`GET /api/v1/findings/summaries`) with auth and verify structured summary payload is returned.
|
|
- [x] Query summary with invalid finding ID and verify `400` problem-details response.
|
|
- [x] Query unknown finding summary and verify `404`.
|
|
- [x] Query unknown finding evidence graph and verify `404`.
|
|
- [x] 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`
|