stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

save checkpoint: save features

Browse Source
This commit is contained in:
master
2026-02-12 10:27:23 +02:00
parent dca86e1248
commit 5bca406787
8837 changed files with 1796879 additions and 5294 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
docs/features/checked/api/policy-trace-panel.md Normal file
View File

@@ -0,0 +1,34 @@
# 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`