244 lines
8.7 KiB
Markdown
244 lines
8.7 KiB
Markdown
# SPRINT_4300 Summary - Explainable Triage Gaps
|
||
|
||
## Overview
|
||
|
||
This sprint series closes the remaining gaps between the "Designing Explainable Triage and Proof-Linked Evidence" advisory (18-Dec-2025) and the current implementation.
|
||
|
||
**Origin Advisory:** `docs/product-advisories/18-Dec-2025 - Designing Explainable Triage and Proof‑Linked Evidence.md`
|
||
|
||
**Gap Analysis:** `docs/implplan/analysis/4300_explainable_triage_gap_analysis.md`
|
||
|
||
## Executive Summary
|
||
|
||
The advisory defined a comprehensive vision for explainable, evidence-linked triage. **~85% was already implemented** through prior sprints (3800, 3801, 4100, 4200 series). This series addresses the remaining **6 gaps**:
|
||
|
||
| Gap | Description | Sprint | Priority | Effort |
|
||
|-----|-------------|--------|----------|--------|
|
||
| G1 | CLI attestation chain verify command | 4300.0001.0001 | HIGH | M |
|
||
| G6 | Findings evidence API endpoint | 4300.0001.0002 | MEDIUM | S |
|
||
| G2 | Evidence privacy controls | 4300.0002.0001 | MEDIUM | M |
|
||
| G3 | Evidence TTL enforcement | 4300.0002.0002 | MEDIUM | S |
|
||
| G4 | Predicate JSON schemas | 4300.0003.0001 | LOW | S |
|
||
| G5 | Attestation completeness metrics | 4300.0003.0002 | LOW | M |
|
||
|
||
**Total Effort:** ~10-14 days across teams
|
||
|
||
## Sprint Structure
|
||
|
||
```
|
||
SPRINT_4300 (Explainable Triage Gaps)
|
||
├── 0001 (CLI & API)
|
||
│ ├── 0001 CLI Attestation Verify Command [HIGH]
|
||
│ └── 0002 Findings Evidence API [MEDIUM]
|
||
├── 0002 (Evidence Management)
|
||
│ ├── 0001 Evidence Privacy Controls [MEDIUM]
|
||
│ └── 0002 Evidence TTL Enforcement [MEDIUM]
|
||
└── 0003 (Quality & Observability)
|
||
├── 0001 Predicate JSON Schemas [LOW]
|
||
└── 0002 Attestation Metrics [LOW]
|
||
```
|
||
|
||
## Dependencies
|
||
|
||
### External Dependencies (Already DONE)
|
||
|
||
| Dependency | Sprint | Status |
|
||
|------------|--------|--------|
|
||
| OCI Referrer Discovery | 4100.0003.0002 | DONE |
|
||
| Risk Verdict Attestation | 4100.0003.0001 | DONE |
|
||
| Human Approval Attestation | 3801.0001.0004 | DONE |
|
||
| Approve Button UI | 4100.0005.0001 | DONE |
|
||
| Evidence Composition Service | 3800.0003.0001 | DONE |
|
||
| Boundary Extractors | 3800.0002.* | DONE |
|
||
| Trust Lattice Engine | (core) | DONE |
|
||
|
||
### Internal Dependencies
|
||
|
||
```
|
||
4300.0001.0001 ─┬─> (none, can start immediately)
|
||
4300.0001.0002 ─┤
|
||
4300.0002.0001 ─┤
|
||
4300.0002.0002 ─┤
|
||
4300.0003.0001 ─┤
|
||
4300.0003.0002 ─┘
|
||
```
|
||
|
||
All sprints can run in parallel.
|
||
|
||
## Recommended Execution Order
|
||
|
||
**Wave 1 (Week 1):** HIGH priority + foundations
|
||
- 4300.0001.0001 - CLI Attestation Verify (CLI Team)
|
||
- 4300.0001.0002 - Findings Evidence API (Scanner Team)
|
||
- 4300.0002.0002 - Evidence TTL Enforcement (Policy Team)
|
||
|
||
**Wave 2 (Week 2):** MEDIUM + LOW priority
|
||
- 4300.0002.0001 - Evidence Privacy Controls (Scanner Team)
|
||
- 4300.0003.0001 - Predicate Schemas (Attestor Team)
|
||
- 4300.0003.0002 - Attestation Metrics (Telemetry Team)
|
||
|
||
## Success Criteria (from Advisory)
|
||
|
||
| # | Criterion | Coverage |
|
||
|---|-----------|----------|
|
||
| 1 | Every risk row expands to path, boundary, VEX, last-seen in <300ms | 4200.0001.0001 (planned) + 4300.0001.0002 |
|
||
| 2 | "Approve" button disabled until SBOM+VEX+Decision attestations validate | 4100.0005.0001 (DONE) |
|
||
| 3 | One-click "Show DSSE chain" renders envelopes with digests and signers | 4200.0001.0001 (planned) |
|
||
| 4 | Audit log captures who approved, which digests, evidence hashes | 3801.0001.0004 (DONE) |
|
||
| 5 | CLI can verify attestation chain before deploy | **4300.0001.0001** |
|
||
| 6 | % attestation completeness >= 95% | **4300.0003.0002** |
|
||
| 7 | TTFE (time-to-first-evidence) <= 30s | **4300.0003.0002** |
|
||
| 8 | Post-deploy reversions trend to zero | **4300.0003.0002** |
|
||
|
||
## Team Assignments
|
||
|
||
| Team | Sprints | Total Effort |
|
||
|------|---------|--------------|
|
||
| CLI Team | 4300.0001.0001 | M (2-3d) |
|
||
| Scanner Team | 4300.0001.0002, 4300.0002.0001 | S+M (3-5d) |
|
||
| Policy Team | 4300.0002.0002 | S (1-2d) |
|
||
| Attestor Team | 4300.0003.0001 | S (1-2d) |
|
||
| Telemetry Team | 4300.0003.0002 | M (2-3d) |
|
||
|
||
## Deliverables
|
||
|
||
### New CLI Commands
|
||
- `stella verify image <reference> --require sbom,vex,decision`
|
||
|
||
### New API Endpoints
|
||
- `GET /api/v1/findings/{findingId}/evidence`
|
||
- `POST /api/v1/findings/evidence/batch`
|
||
|
||
### New Services
|
||
- `ImageAttestationVerifier`
|
||
- `TrustPolicyLoader`
|
||
- `EvidenceRedactionService`
|
||
- `EvidenceTtlEnforcer`
|
||
- `AttestationCompletenessCalculator`
|
||
- `PredicateSchemaValidator`
|
||
|
||
### New Metrics
|
||
- `stella_attestations_created_total`
|
||
- `stella_attestations_verified_total`
|
||
- `stella_attestations_failed_total`
|
||
- `stella_ttfe_seconds`
|
||
- `stella_post_deploy_reversions_total`
|
||
|
||
### New Schemas
|
||
- `docs/schemas/predicates/sbom.v1.schema.json`
|
||
- `docs/schemas/predicates/vex.v1.schema.json`
|
||
- `docs/schemas/predicates/reachability.v1.schema.json`
|
||
- `docs/schemas/predicates/boundary.v1.schema.json`
|
||
- `docs/schemas/predicates/policy-decision.v1.schema.json`
|
||
- `docs/schemas/predicates/human-approval.v1.schema.json`
|
||
|
||
### New Dashboard
|
||
- `deploy/grafana/dashboards/attestation-metrics.json`
|
||
|
||
## Risk Register
|
||
|
||
| Risk | Impact | Mitigation |
|
||
|------|--------|------------|
|
||
| OCI referrers API not supported by all registries | Fallback tag discovery | Already implemented in 4100.0003.0002 |
|
||
| Schema validation performance | Latency on attestation creation | Cache compiled schemas |
|
||
| Metric cardinality explosion | Prometheus storage | Limit label values |
|
||
|
||
## Completion Checklist
|
||
|
||
- [ ] All 6 sprints marked DONE
|
||
- [ ] CLI verify command works end-to-end
|
||
- [ ] Evidence API returns advisory-compliant contract
|
||
- [ ] Privacy redaction enforced by default
|
||
- [ ] TTL staleness affects policy decisions
|
||
- [ ] All predicate schemas validate correctly
|
||
- [ ] Grafana dashboard shows all metrics
|
||
- [ ] Integration tests pass
|
||
- [ ] Documentation updated
|
||
|
||
## Post-Completion
|
||
|
||
After all sprints complete:
|
||
1. Update `docs/09_API_CLI_REFERENCE.md` with new CLI command
|
||
2. Update `docs/modules/scanner/architecture.md` with evidence API
|
||
3. Archive this summary to `docs/implplan/archived/`
|
||
4. Close advisory tracking issue
|
||
|
||
---
|
||
|
||
## Topic & Scope
|
||
- Track delivery of the Explainable Triage gaps identified in the 18-Dec-2025 advisory.
|
||
- Provide a single coordination view across the six gap-closing sprints.
|
||
- Capture decisions, risks, and cross-module interlocks.
|
||
- **Working directory:** `docs/implplan`.
|
||
|
||
## Dependencies & Concurrency
|
||
- Depends on prior SPRINT_3800/3801/4100/4200 series outlined above.
|
||
- All child sprints can run in parallel.
|
||
|
||
## Documentation Prerequisites
|
||
- `docs/README.md`
|
||
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
|
||
- `docs/modules/platform/architecture-overview.md`
|
||
- `docs/product-advisories/18-Dec-2025 - Designing Explainable Triage and Proof-Linked Evidence.md`
|
||
|
||
## Delivery Tracker
|
||
|
||
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| 1 | SUMMARY-G1 | TODO | SPRINT_4300_0001_0001 | Planning | Track CLI attestation verify sprint completion. |
|
||
| 2 | SUMMARY-G6 | TODO | SPRINT_4300_0001_0002 | Planning | Track findings evidence API sprint completion. |
|
||
| 3 | SUMMARY-G2 | TODO | SPRINT_4300_0002_0001 | Planning | Track evidence privacy controls sprint completion. |
|
||
| 4 | SUMMARY-G3 | TODO | SPRINT_4300_0002_0002 | Planning | Track evidence TTL enforcement sprint completion. |
|
||
| 5 | SUMMARY-G4 | TODO | SPRINT_4300_0003_0001 | Planning | Track predicate schema sprint completion. |
|
||
| 6 | SUMMARY-G5 | TODO | SPRINT_4300_0003_0002 | Planning | Track attestation metrics sprint completion. |
|
||
|
||
## Wave Coordination
|
||
|
||
- Wave 1: CLI + API + TTL foundations.
|
||
- Wave 2: Privacy controls + schemas + metrics.
|
||
|
||
## Wave Detail Snapshots
|
||
|
||
- See "Recommended Execution Order" for wave details.
|
||
|
||
## Interlocks
|
||
|
||
- UI evidence drawer depends on findings evidence API and privacy controls.
|
||
- CLI verification depends on attestation verification services and referrer discovery.
|
||
|
||
## Upcoming Checkpoints
|
||
|
||
| Date (UTC) | Checkpoint | Owner |
|
||
| --- | --- | --- |
|
||
| 2025-12-22 | Summary normalized to sprint template. | Agent |
|
||
|
||
## Action Tracker
|
||
|
||
| Date (UTC) | Action | Owner | Status |
|
||
| --- | --- | --- | --- |
|
||
| 2025-12-22 | Normalize summary file to standard template. | Agent | DONE |
|
||
|
||
## Execution Log
|
||
|
||
| Date (UTC) | Update | Owner |
|
||
| --- | --- | --- |
|
||
| 2025-12-22 | Summary created from Explainable Triage advisory gap analysis. | Agent |
|
||
| 2025-12-22 | Normalized summary file to standard template; no semantic changes. | Agent |
|
||
|
||
## Decisions & Risks
|
||
|
||
| Item | Type | Owner | Notes |
|
||
| --- | --- | --- | --- |
|
||
| Advisory gaps | Decision | Planning | Six gaps targeted for closure per analysis. |
|
||
|
||
| Risk | Impact | Mitigation |
|
||
| --- | --- | --- |
|
||
| Parallel execution drift | Coordination overhead | Weekly checkpoints with sprint owners. |
|
||
|
||
---
|
||
|
||
**Sprint Series Status:** TODO (0/6 sprints complete)
|
||
|
||
**Created:** 2025-12-22
|
||
**Origin:** Gap analysis of 18-Dec-2025 advisory
|