df94136727
- Add RpmVersionComparer for RPM version comparison with epoch, version, and release handling. - Introduce DebianVersion for parsing Debian EVR (Epoch:Version-Release) strings. - Create ApkVersion for parsing Alpine APK version strings with suffix support. - Define IVersionComparator interface for version comparison with proof-line generation. - Implement VersionComparisonResult struct to encapsulate comparison results and proof lines. - Add tests for Debian and RPM version comparers to ensure correct functionality and edge case handling. - Create project files for the version comparison library and its tests.
172 lines
6.0 KiB
Markdown
172 lines
6.0 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
|
||
|
||
---
|
||
|
||
**Sprint Series Status:** TODO (0/6 sprints complete)
|
||
|
||
**Created:** 2025-12-22
|
||
**Origin:** Gap analysis of 18-Dec-2025 advisory
|