feat: Implement distro-native version comparison for RPM, Debian, and Alpine packages

- 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.
2025-12-22 09:49:38 +02:00
parent aff0ceb2fe
commit df94136727
111 changed files with 30413 additions and 1813 deletions
--- a/docs/implplan/analysis/4300_explainable_triage_gap_analysis.md
+++ b/docs/implplan/analysis/4300_explainable_triage_gap_analysis.md
@@ -0,0 +1,305 @@
+# Gap Analysis: Explainable Triage and Proof-Linked Evidence
+
+**Date:** 2025-12-22
+**Advisory:** 18-Dec-2025 - Designing Explainable Triage and Proof-Linked Evidence
+**Analyst:** Agent
+
+---
+
+## 1. Executive Summary
+
+The advisory "Designing Explainable Triage and Proof-Linked Evidence" defines a comprehensive vision for making security triage **explainable** and approvals **provably evidence-linked**. This gap analysis compares the advisory requirements against the current StellaOps implementation.
+
+**Key Finding:** ~85% of the advisory is already implemented through prior sprint work (3800, 3801, 4100, 4200 series). Six specific gaps remain, addressed by the SPRINT_4300 series.
+
+---
+
+## 2. Advisory Requirements Summary
+
+### 2.1 Explainable Triage UX
+- Every risk row shows: Score, CVE, service, package
+- Expand panel shows: Path, Boundary, VEX, Last-seen, Actions
+- Data contract for evidence retrieval
+
+### 2.2 Evidence-Linked Approvals
+- Chain: SBOM → VEX → Policy Decision
+- in-toto/DSSE attestations with signatures
+- Gate merges/deploys on chain validation
+
+### 2.3 Backend Requirements
+- `/findings/:id/evidence` endpoint
+- `/approvals/:artifact/attestations` endpoint
+- Proof bundles as content-addressed blobs
+- DSSE envelopes for signatures
+
+### 2.4 CLI/API
+- `stella verify image:<digest> --require sbom,vex,decision`
+- Signed summary return
+- Non-zero exit for CI/CD gates
+
+### 2.5 Invariants
+- Artifact anchoring (no "latest tag" approvals)
+- Evidence closure (decision refs exact evidence)
+- Signature chain (DSSE, signed, verifiable)
+- Staleness (last_seen, expires_at, TTL)
+
+### 2.6 Metrics
+- % attestation completeness (target ≥95%)
+- TTFE (time-to-first-evidence, target ≤30s)
+- Post-deploy reversions (target: zero)
+
+---
+
+## 3. Implementation Status
+
+### 3.1 Fully Implemented (No Action Needed)
+
+| Requirement | Implementation | Evidence |
+|-------------|----------------|----------|
+| **Triage DB Schema** | TriageDbContext with 8 entities | `src/Scanner/__Libraries/StellaOps.Scanner.Triage/` |
+| **Evidence Bundle** | EvidenceBundle with 6 evidence types | `src/__Libraries/StellaOps.Evidence.Bundle/` |
+| **VEX Decision Models** | OpenVEX output with x-stellaops-evidence | `src/Policy/StellaOps.Policy.Engine/Vex/` |
+| **Score Explanation** | ScoreExplanationService, additive model | `src/Signals/StellaOps.Signals/Services/` |
+| **Trust Lattice Engine** | K4 evaluation, claim aggregation | `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/` |
+| **Boundary Extractors** | K8s, Gateway, IaC extractors | SPRINT_3800_0002_* (archived, DONE) |
+| **Human Approval Attestation** | stella.ops/human-approval@v1 | SPRINT_3801_0001_0004 (DONE) |
+| **Risk Verdict Attestation** | RiskVerdictAttestation, RvaBuilder | SPRINT_4100_0003_0001 (DONE) |
+| **OCI Referrer Push** | OciPushClient, RvaOciPublisher | SPRINT_4100_0003_0002 (DONE) |
+| **Approve Button UI** | ApprovalButtonComponent (624 lines) | SPRINT_4100_0005_0001 (DONE) |
+| **Decision Recording** | DecisionService, replay tokens | `src/Findings/StellaOps.Findings.Ledger/` |
+| **Policy Gates** | PolicyGateEvaluator, Pass/Block/Warn | `src/Policy/StellaOps.Policy.Engine/Gates/` |
+| **Exception Evaluation** | ExceptionEvaluator, compensating controls | SPRINT_3900 series (DONE) |
+| **TTFS Telemetry** | TtfsIngestionService | `src/Telemetry/StellaOps.Telemetry.Core/Triage/` |
+
+### 3.2 Planned (In Progress)
+
+| Requirement | Sprint | Status |
+|-------------|--------|--------|
+| Proof Chain Verification UI | SPRINT_4200_0001_0001 | TODO |
+
+### 3.3 Gaps Identified
+
+| ID | Gap | Advisory Section | Priority |
+|----|-----|------------------|----------|
+| G1 | CLI Attestation Chain Verify | CLI/API, Pipeline gate | HIGH |
+| G2 | Evidence Privacy Controls | Evidence privacy | MEDIUM |
+| G3 | Evidence TTL Strategy API | Staleness invariant | MEDIUM |
+| G4 | Predicate Type JSON Schemas | Predicate types | LOW |
+| G5 | Metrics Dashboard | Metrics | LOW |
+| G6 | Findings Evidence API | Backend, Data contract | MEDIUM |
+
+---
+
+## 4. Gap Details
+
+### G1: CLI Attestation Chain Verify Command
+
+**Advisory Requirement:**
+```
+stella verify image:<digest> --require sbom,vex,decision
+```
+Returns signed summary; pipelines fail on non-zero.
+
+**Current State:**
+- `stella verify offline` exists for offline verification
+- No image-based attestation chain verification
+- No `--require` attestation type filtering
+
+**Gap:** Need online image verification with attestation requirements.
+
+**Resolution:** SPRINT_4300_0001_0001
+
+---
+
+### G2: Evidence Privacy Controls
+
+**Advisory Requirement:**
+> Store file hashes, symbol names, and line ranges (no raw source required). Gate raw source behind elevated permissions.
+
+**Current State:**
+- Evidence contains full details
+- No redaction service
+- No permission-based access control
+
+**Gap:** Need redaction levels and permission checks.
+
+**Resolution:** SPRINT_4300_0002_0001
+
+---
+
+### G3: Evidence TTL Strategy Enforcement
+
+**Advisory Requirement:**
+> SBOM: long TTL (weeks/months). Boundary: short TTL (hours/days). Reachability: medium TTL. Staleness behavior in policy.
+
+**Current State:**
+- TTL fields exist on evidence entities
+- No enforcement in policy gate
+- No staleness warnings
+
+**Gap:** Need TTL enforcer service integrated with policy.
+
+**Resolution:** SPRINT_4300_0002_0002
+
+---
+
+### G4: Predicate Type JSON Schemas
+
+**Advisory Requirement:**
+> Predicate types: stella/sbom@v1, stella/vex@v1, stella/reachability@v1, stella/boundary@v1, stella/policy-decision@v1, stella/human-approval@v1
+
+**Current State:**
+- C# models exist for all predicate types
+- No formal JSON Schema definitions
+- No schema validation on attestation creation
+
+**Gap:** Need JSON schemas and validation.
+
+**Resolution:** SPRINT_4300_0003_0001
+
+---
+
+### G5: Attestation Completeness Metrics
+
+**Advisory Requirement:**
+> Metrics: % changes with complete attestations (target ≥95%), TTFE (target ≤30s), Post-deploy reversions (trend to zero)
+
+**Current State:**
+- TTFS telemetry exists (time-to-first-skeleton)
+- No attestation completeness ratio
+- No reversion tracking
+- No Grafana dashboard
+
+**Gap:** Need full metrics suite and dashboard.
+
+**Resolution:** SPRINT_4300_0003_0002
+
+---
+
+### G6: Findings Evidence API Endpoint
+
+**Advisory Requirement:**
+> Backend: add `/findings/:id/evidence` (returns the contract).
+
+Contract:
+```json
+{
+  "finding_id": "f-7b3c",
+  "cve": "CVE-2024-12345",
+  "component": {...},
+  "reachable_path": [...],
+  "entrypoint": {...},
+  "vex": {...},
+  "last_seen": "...",
+  "attestation_refs": [...]
+}
+```
+
+**Current State:**
+- EvidenceCompositionService exists internally
+- No REST endpoint exposing advisory contract
+- Different internal response format
+
+**Gap:** Need REST endpoint with advisory-compliant contract.
+
+**Resolution:** SPRINT_4300_0001_0002
+
+---
+
+## 5. Coverage Matrix
+
+| Advisory Section | Subsection | Implemented | Gap Sprint |
+|------------------|------------|-------------|------------|
+| Explainable Triage UX | Row (collapsed) | ✅ | — |
+| | Expand panel | ✅ | — |
+| | Data contract | ⚠️ | 4300.0001.0002 |
+| Evidence-Linked Approvals | Chain exists | ✅ | — |
+| | in-toto/DSSE | ✅ | — |
+| | Gate merges | ✅ | — |
+| Backend | /findings/:id/evidence | ❌ | 4300.0001.0002 |
+| | /approvals/:artifact/attestations | ✅ | — |
+| | Proof bundles | ✅ | — |
+| CLI/API | stella verify image | ❌ | 4300.0001.0001 |
+| Invariants | Artifact anchoring | ✅ | — |
+| | Evidence closure | ✅ | — |
+| | Signature chain | ✅ | — |
+| | Staleness | ⚠️ | 4300.0002.0002 |
+| Data Model | artifacts table | ✅ | — |
+| | findings table | ✅ | — |
+| | evidence table | ✅ | — |
+| | attestations table | ✅ | — |
+| | approvals table | ✅ | — |
+| Evidence Types | Reachable path proof | ✅ | — |
+| | Boundary proof | ✅ | — |
+| | VEX status | ✅ | — |
+| | Score explanation | ✅ | — |
+| Predicate Types | stella/sbom@v1 | ⚠️ | 4300.0003.0001 |
+| | stella/vex@v1 | ⚠️ | 4300.0003.0001 |
+| | stella/reachability@v1 | ⚠️ | 4300.0003.0001 |
+| | stella/boundary@v1 | ⚠️ | 4300.0003.0001 |
+| | stella/policy-decision@v1 | ⚠️ | 4300.0003.0001 |
+| | stella/human-approval@v1 | ⚠️ | 4300.0003.0001 |
+| Policy Gate | OPA/Rego | ✅ | — |
+| | Signed decision | ✅ | — |
+| Approve Button | Disabled until valid | ✅ | — |
+| | Creates approval attestation | ✅ | — |
+| Verification | Shared verifier library | ✅ | — |
+| Privacy | Redacted proofs | ❌ | 4300.0002.0001 |
+| | Elevated permissions | ❌ | 4300.0002.0001 |
+| TTL Strategy | Per-type TTLs | ⚠️ | 4300.0002.0002 |
+| Metrics | % completeness | ❌ | 4300.0003.0002 |
+| | TTFE | ⚠️ | 4300.0003.0002 |
+| | Reversions | ❌ | 4300.0003.0002 |
+| UI Components | Findings list | ✅ | — |
+| | Evidence drawer | ⏳ | 4200.0001.0001 |
+| | Proof bundle viewer | ⏳ | 4200.0001.0001 |
+
+**Legend:** ✅ Implemented | ⚠️ Partial | ❌ Missing | ⏳ Planned
+
+---
+
+## 6. Effort Estimation
+
+| Sprint | Effort | Team | Parallelizable |
+|--------|--------|------|----------------|
+| 4300.0001.0001 | M (2-3d) | CLI | Yes |
+| 4300.0001.0002 | S (1-2d) | Scanner | Yes |
+| 4300.0002.0001 | M (2-3d) | Scanner | Yes |
+| 4300.0002.0002 | S (1-2d) | Policy | Yes |
+| 4300.0003.0001 | S (1-2d) | Attestor | Yes |
+| 4300.0003.0002 | M (2-3d) | Telemetry | Yes |
+
+**Total:** 10-14 days (can complete in 1-2 weeks with parallel execution)
+
+---
+
+## 7. Recommendations
+
+1. **Prioritize G1 (CLI Verify)** - This is the only HIGH priority gap and enables CI/CD integration.
+
+2. **Bundle G2+G3** - Evidence privacy and TTL can share context in Scanner/Policy teams.
+
+3. **Defer G4+G5** - Predicate schemas and metrics are LOW priority; can follow after core functionality.
+
+4. **Leverage 4200.0001.0001** - Proof Chain UI sprint is already planned; ensure it consumes new evidence API.
+
+---
+
+## 8. Appendix: Prior Sprint References
+
+| Sprint | Topic | Status |
+|--------|-------|--------|
+| 3800.0000.0000 | Explainable Triage Master | DONE |
+| 3800.0002.0001 | RichGraph Boundary Extractor | DONE |
+| 3800.0002.0002 | K8s Boundary Extractor | DONE |
+| 3800.0003.0001 | Evidence API Endpoint | DONE |
+| 3801.0001.0001 | Policy Decision Attestation | DONE |
+| 3801.0001.0004 | Human Approval Attestation | DONE |
+| 4100.0003.0001 | Risk Verdict Attestation | DONE |
+| 4100.0003.0002 | OCI Referrer Push | DONE |
+| 4100.0005.0001 | Approve Button UI | DONE |
+| 4200.0001.0001 | Proof Chain Verification UI | TODO |
+
+---
+
+**Analysis Complete:** 2025-12-22