29 lines
3.4 KiB
Markdown
29 lines
3.4 KiB
Markdown
# 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
|