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 634233dfed
112 changed files with 31925 additions and 1813 deletions
--- a/docs/modules/platform/explainable-triage-implementation-plan.md
+++ b/docs/modules/platform/explainable-triage-implementation-plan.md
@@ -0,0 +1,212 @@
+# Explainable Triage Workflows - Implementation Plan
+
+## Executive Summary
+
+This document outlines the implementation plan for delivering **Explainable Triage Workflows** as defined in the product advisory dated 21-Dec-2025. The capability set enables vulnerability-first, policy-backed, reachability-informed verdicts with full explainability and auditability.
+
+## Vision
+
+> Every vulnerability finding must resolve to a **policy-backed, reachability-informed, runtime-corroborated verdict** that is **exportable as one signed attestation attached to the built artifact**.
+
+## Current State Analysis
+
+### Already Implemented (75%)
+
+| Capability | Implementation | Completeness |
+|------------|----------------|--------------|
+| Reachability analysis | 10 language analyzers, binary, runtime | 95% |
+| VEX processing | OpenVEX, CSAF, CycloneDX with lattice | 90% |
+| Explainability | ExplainTrace with rule steps | 95% |
+| Evidence generation | Path witnesses, rich graphs | 90% |
+| Audit trails | Immutable ledger with chain integrity | 85% |
+| Policy gates | 4-stage gate system | 95% |
+| Attestations | 7 predicate types with DSSE | 90% |
+| Runtime capture | eBPF, dyld, ETW | 85% |
+
+### Already Planned (15%)
+
+| Capability | Sprint | Status |
+|------------|--------|--------|
+| Risk Verdict Attestation | SPRINT_4100_0003_0001 | TODO |
+| OCI Attachment | SPRINT_4100_0003_0002 | TODO |
+| Counterfactuals | SPRINT_4200_0002_0005 | TODO |
+| Replay Engine | SPRINT_4100_0002_0002 | TODO |
+| Knowledge Snapshot | SPRINT_4100_0002_0001 | TODO |
+| Audit Pack Export | SPRINT_5100_0006_0001 | TODO |
+| Unknown Budgets | SPRINT_4100_0001_0002 | TODO |
+
+### Net New Gaps (10%)
+
+| Gap | Sprint | Story Points |
+|-----|--------|--------------|
+| Unified Confidence Model | 7000.0002.0001 | 13 |
+| Vulnerability-First UX API | 7000.0002.0002 | 13 |
+| Evidence Graph API | 7000.0003.0001 | 8 |
+| Reachability Mini-Map | 7000.0003.0002 | 5 |
+| Runtime Timeline | 7000.0003.0003 | 5 |
+| Progressive Fidelity | 7000.0004.0001 | 13 |
+| Evidence Size Budgets | 7000.0004.0002 | 8 |
+| Quality KPIs | 7000.0005.0001 | 8 |
+
+## Implementation Roadmap
+
+### Phase 1: Foundation (Existing + New)
+
+**Objective**: Establish core verdict and confidence infrastructure.
+
+**Sprints**:
+- SPRINT_4100_0003_0001: Risk Verdict Attestation
+- SPRINT_4100_0002_0001: Knowledge Snapshot Manifest
+- SPRINT_7000_0002_0001: Unified Confidence Model
+- SPRINT_7000_0004_0001: Progressive Fidelity (parallel)
+- SPRINT_7000_0004_0002: Evidence Budgets (parallel)
+
+**Key Deliverables**:
+- `RiskVerdictAttestation` model with PASS/FAIL/PASS_WITH_EXCEPTIONS/INDETERMINATE
+- `ConfidenceScore` with 5-factor breakdown
+- `FidelityLevel` enum with Quick/Standard/Deep modes
+- `EvidenceBudget` with retention tiers
+
+### Phase 2: UX Layer
+
+**Objective**: Deliver vulnerability-first presentation layer.
+
+**Sprints**:
+- SPRINT_7000_0002_0002: Vulnerability-First UX API
+
+**Key Deliverables**:
+- `FindingSummaryResponse` with verdict chip, confidence, one-liner
+- `ProofBadges` (Reachability, Runtime, Policy, Provenance)
+- `GET /api/v1/findings` list endpoint
+- `GET /api/v1/findings/{id}/summary` detail endpoint
+
+### Phase 3: Visualization APIs
+
+**Objective**: Enable evidence exploration and click-through.
+
+**Sprints** (parallelizable):
+- SPRINT_7000_0003_0001: Evidence Graph API
+- SPRINT_7000_0003_0002: Reachability Mini-Map API
+- SPRINT_7000_0003_0003: Runtime Timeline API
+
+**Key Deliverables**:
+- `GET /api/v1/findings/{id}/evidence-graph`
+- `GET /api/v1/findings/{id}/reachability-map`
+- `GET /api/v1/findings/{id}/runtime-timeline`
+
+### Phase 4: Metrics & Observability
+
+**Objective**: Track quality KPIs for continuous improvement.
+
+**Sprints**:
+- SPRINT_7000_0005_0001: Quality KPIs Tracking
+
+**Key Deliverables**:
+- `TriageQualityKpis` model
+- `GET /api/v1/metrics/kpis` dashboard endpoint
+- Trend tracking over time
+
+## Architecture Changes
+
+### New Libraries
+
+```
+src/
+├── Policy/
+│   └── __Libraries/
+│       └── StellaOps.Policy.Confidence/     # NEW: Confidence model
+│           ├── Models/
+│           ├── Services/
+│           └── Configuration/
+├── Scanner/
+│   └── __Libraries/
+│       └── StellaOps.Scanner.Orchestration/ # NEW: Fidelity orchestration
+│           └── Fidelity/
+├── Findings/
+│   └── StellaOps.Findings.WebService/       # EXTEND: UX APIs
+│       ├── Contracts/
+│       ├── Services/
+│       └── Endpoints/
+├── Evidence/                                 # NEW: Evidence management
+│   └── StellaOps.Evidence/
+│       ├── Budgets/
+│       └── Retention/
+└── Metrics/                                  # NEW: KPI tracking
+    └── StellaOps.Metrics/
+        └── Kpi/
+```
+
+### Database Changes
+
+| Table | Purpose |
+|-------|---------|
+| `confidence_factors` | Store factor breakdown per verdict |
+| `evidence_items` | Track evidence with size and tier |
+| `kpi_counters` | Real-time KPI counters |
+| `kpi_snapshots` | Daily KPI snapshots |
+
+### API Surface
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/v1/findings` | GET | List findings with summaries |
+| `/api/v1/findings/{id}/summary` | GET | Detailed finding summary |
+| `/api/v1/findings/{id}/evidence-graph` | GET | Evidence graph |
+| `/api/v1/findings/{id}/reachability-map` | GET | Reachability mini-map |
+| `/api/v1/findings/{id}/runtime-timeline` | GET | Runtime timeline |
+| `/api/v1/scan/analyze` | POST | Analyze with fidelity level |
+| `/api/v1/scan/findings/{id}/upgrade` | POST | Upgrade fidelity |
+| `/api/v1/metrics/kpis` | GET | Quality KPIs |
+
+## Non-Negotiables
+
+From the advisory:
+
+1. **Vulnerability-first UX**: Users start from CVE/finding and immediately see applicability, reachability, runtime corroboration, and policy rationale.
+
+2. **Single canonical verdict artifact**: One built-in, signed verdict attestation per subject (OCI digest), replayable.
+
+3. **Deterministic evidence**: Evidence objects are content-hashed and versioned.
+
+4. **Unknowns are first-class**: "Unknown reachability/runtime/config" is not hidden; it is budgeted and policy-controlled.
+
+## Quality KPIs
+
+| KPI | Target | Measurement |
+|-----|--------|-------------|
+| % non-UNKNOWN reachability | >80% | Weekly |
+| % runtime corroboration | >50% (where sensor deployed) | Weekly |
+| Explainability completeness | >95% | Weekly |
+| Replay success rate | >99% | Weekly |
+| Median time to verdict | <5 min | Daily |
+
+## Risk Management
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Confidence model complexity | High | Start simple (3 factors), iterate |
+| Deep analysis performance | Medium | Progressive fidelity with timeouts |
+| Evidence storage growth | Medium | Budget enforcement + tier pruning |
+| API backward compatibility | Low | Versioned endpoints |
+
+## Definition of Done
+
+Per advisory, a release is "done" only if:
+
+- [ ] Build produces OCI artifact with attached **signed verdict attestation**
+- [ ] Each verdict is **explainable** (reason steps + proof pointers)
+- [ ] Reachability evidence stored as **reproducible subgraph** (or explicitly UNKNOWN with reason)
+- [ ] Replay verification reproduces same verdict with pinned inputs
+- [ ] UX starts from vulnerabilities and links directly to proofs and audit export
+
+## References
+
+- **Advisory**: `docs/product-advisories/archived/21-Dec-2025 - Designing Explainable Triage Workflows.md`
+- **Sprint Summary**: `docs/implplan/SPRINT_7000_SUMMARY.md`
+- **Individual Sprints**: `docs/implplan/SPRINT_7000_*.md`
+
+## Revision History
+
+| Date | Change | Author |
+|------|--------|--------|
+| 2025-12-22 | Initial implementation plan | Claude |
--- a/docs/modules/platform/moat-gap-analysis.md
+++ b/docs/modules/platform/moat-gap-analysis.md
@@ -0,0 +1,276 @@
+# Moat Gap Analysis: StellaOps Competitive Position
+
+> **Source Advisory**: 19-Dec-2025 - Stella Ops candidate features mapped to moat strength
+> **Analysis Date**: 2025-12-22
+> **Status**: Sprints created, implementation pending
+
+---
+
+## Executive Summary
+
+This document captures the gap analysis between the competitive moat advisory and StellaOps' current implementation, along with the sprint plan to address identified gaps.
+
+### Moat Scale Reference
+
+| Rating | Definition |
+|--------|------------|
+| **5** | Structural moat — new primitives, strong defensibility, durable switching cost |
+| **4** | Strong moat — difficult multi-domain engineering; incumbents have partial analogs |
+| **3** | Moderate moat — others can build; differentiation is execution + packaging |
+| **2** | Weak moat — table-stakes soon; limited defensibility |
+| **1** | Commodity — widely available in OSS / easy to replicate |
+
+---
+
+## Feature Implementation Matrix
+
+| Feature | Moat | Current % | Key Gaps | Sprint Coverage |
+|---------|------|-----------|----------|-----------------|
+| Signed, replayable risk verdicts | 5 | 70% | OCI push, one-command replay | 4300_0001_* |
+| VEX decisioning engine | 4 | 85% | Evidence hooks | Minimal |
+| Reachability with proof | 4 | 75% | Standalone artifact | 4400_0001_0002 |
+| Smart-Diff semantic delta | 4 | 80% | Signed delta verdict | 4400_0001_0001 |
+| Unknowns as first-class state | 4 | 75% | Policy budgets, attestations | 4300_0002_* |
+| Air-gapped epistemic mode | 4 | 70% | Sealed snapshot workflow | 4300_0003_0001 |
+| SBOM ledger + lineage | 3 | 60% | Historical tracking, BYOS | 4600_0001_* |
+| Policy engine with proofs | 3 | 85% | Compilation to artifact | Minimal |
+| VEX distribution network | 3-4 | 30% | Hub layer entirely | 4500_0001_* |
+
+---
+
+## Detailed Gap Analysis
+
+### 1. Signed, Replayable Risk Verdicts (Moat 5)
+
+**What exists:**
+- `VerdictReceiptStatement` with in-toto predicate
+- `ProofSpine` and `ProofChainBuilder` infrastructure
+- `TrustLatticeEngine.Evaluate()` producing `ProofBundle`
+- `ReplayManifest` and `ReplayVerifier`
+- Input hashing (sbomDigest, feedsDigest, policyDigest)
+
+**Gaps:**
+| Gap | Sprint |
+|-----|--------|
+| Verdict as OCI-attached attestation | 4300_0001_0001 |
+| One-command audit replay CLI | 4300_0001_0002 |
+| Formal replay determinism tests | 4300_0001_0002 |
+
+**Moat Thesis**: "We don't output findings; we output an attestable decision that can be replayed."
+
+---
+
+### 2. VEX Decisioning Engine (Moat 4)
+
+**What exists:**
+- `VexConsensusEngine` with 5 modes
+- `TrustLatticeEngine` with K4 lattice atoms
+- `TrustWeightEngine` for issuer weighting
+- VEX normalizers for CycloneDX, OpenVEX, CSAF
+- `VexLens` module with consensus rationale
+
+**Gaps:**
+| Gap | Sprint |
+|-----|--------|
+| Configurable evidence hooks | Minor enhancement |
+
+**Moat Thesis**: "We treat VEX as a logical claim system, not a suppression file."
+
+---
+
+### 3. Reachability with Proof (Moat 4)
+
+**What exists:**
+- `ReachabilityWitnessStatement` attestation type
+- `PathWitnessBuilder` for call-path proofs
+- `CallPath` models with entrypoint → symbol chain
+- `ReachabilityLattice` for state management
+- `CompositeGateDetector` for boundary extraction
+
+**Gaps:**
+| Gap | Sprint |
+|-----|--------|
+| Standalone reachability subgraph as OCI artifact | 4400_0001_0002 |
+| Binary-level reachability proof | 6000_* (existing) |
+
+**Moat Thesis**: "We provide proof of exploitability in *this* artifact, not just a badge."
+
+---
+
+### 4. Smart-Diff Semantic Risk Delta (Moat 4)
+
+**What exists:**
+- `MaterialRiskChangeDetector` with R1-R4 rules
+- `RiskStateSnapshot` capturing full finding state
+- Detection of all flip types
+- Priority scoring algorithm
+- SARIF output generation
+
+**Gaps:**
+| Gap | Sprint |
+|-----|--------|
+| Signed delta verdict attestation | 4400_0001_0001 |
+| Diff over reachability graphs | Future |
+
+**Moat Thesis**: "We explain what changed in exploitable surface area, not what changed in CVE count."
+
+---
+
+### 5. Unknowns as First-Class State (Moat 4)
+
+**What exists:**
+- `UncertaintyTier` (T1-T4) with entropy classification
+- `UnknownStateLedger` tracking marker kinds
+- Risk modifiers from uncertainty
+- `BlocksNotAffected()` gate on T1 tier
+
+**Gaps:**
+| Gap | Sprint |
+|-----|--------|
+| Policy rule: "fail if unknowns > N" | 4300_0002_0001 |
+| Unknown budgets with decay | 4100_0001_0002 (existing) |
+| Unknowns in attestations | 4300_0002_0002 |
+
+**Moat Thesis**: "We quantify uncertainty and gate on it."
+
+---
+
+### 6. Air-Gapped Epistemic Mode (Moat 4)
+
+**What exists:**
+- `AirGap.Controller` with state management
+- `ReplayVerifier` with depth levels
+- `TrustStore` and `TufMetadataValidator`
+- `EgressPolicy` enforcement
+- `TimeAnchor` for offline time validation
+
+**Gaps:**
+| Gap | Sprint |
+|-----|--------|
+| Sealed knowledge snapshot export CLI | 4300_0003_0001 |
+| One-command import + replay validation | 4300_0003_0001 |
+| Feed snapshot versioning with merkle roots | 4300_0003_0001 |
+
+**Moat Thesis**: Air-gapped "runtime" is common; air-gapped **reproducibility** is not.
+
+---
+
+### 7. SBOM Ledger + Lineage (Moat 3)
+
+**What exists:**
+- `SbomService` with versioning events
+- `CatalogRecord` for storage
+- `Graph` module for dependency indexing
+- `SbomVersionEvents`
+
+**Gaps:**
+| Gap | Sprint |
+|-----|--------|
+| Historical SBOM tracking with diff lineage | 4600_0001_0001 |
+| BYOS ingestion workflow with validation | 4600_0001_0002 |
+| SBOM grouping by artifact family | 4600_0001_0001 |
+
+**Moat Strategy**: Make the ledger valuable via **semantic diff, evidence joins, and provenance**.
+
+---
+
+### 8. Policy Engine with Proofs (Moat 3)
+
+**What exists:**
+- `PolicyEvaluation` with `PolicyExplanation`
+- OPA/Rego integration
+- `ProofBundle` generation from TrustLattice
+- Evidence pointers in verdict statements
+
+**Gaps:**
+| Gap | Sprint |
+|-----|--------|
+| Policy compilation to standalone decision artifact | Minor enhancement |
+
+**Moat Strategy**: Keep policy language small but rigorous; always emit evidence pointers.
+
+---
+
+### 9. VEX Distribution Network (Moat 3-4)
+
+**What exists:**
+- Excititor ingests from 7+ VEX sources
+- `VexConnectorMetadata` for source tracking
+
+**Gaps:**
+| Gap | Sprint |
+|-----|--------|
+| VEX Hub aggregation layer | 4500_0001_0001 |
+| Trust scoring of VEX sources | 4500_0001_0002 |
+| VEX verification + validation pipeline | 4500_0001_0001 |
+| API for VEX discovery/subscription | 4500_0001_0001 |
+
+**Moat Strategy**: Differentiate with **verification + trust scoring** of VEX sources.
+
+---
+
+## Sprint Roadmap
+
+### Phase 1: Moat 5 Anchor (P0)
+```
+4300_0001_0001 → 4300_0001_0002
+     │
+     └── Verdict becomes portable, replayable
+```
+
+### Phase 2: Moat 4 Hardening (P1)
+```
+4300_0002_0001 → 4300_0002_0002
+     │
+     └── Unknowns become actionable
+
+4300_0003_0001
+     │
+     └── Air-gap becomes reproducible
+
+4500_0001_0001 → 4500_0001_0002
+     │
+     └── VEX becomes distributable
+```
+
+### Phase 3: Moat 4 Extensions (P2)
+```
+4400_0001_0001 (Delta Verdict)
+4400_0001_0002 (Reachability Artifact)
+```
+
+### Phase 4: Moat 3 Foundation (P2)
+```
+4600_0001_0001 → 4600_0001_0002
+     │
+     └── SBOM becomes historical
+```
+
+---
+
+## Competitive Positioning Summary
+
+### Where StellaOps Is Strong
+1. **VEX decisioning** — Multi-mode consensus engine is ahead of competitors
+2. **Smart-Diff** — R1-R4 rules with priority scoring is unique
+3. **Policy engine** — OPA/Rego with proof output is mature
+4. **Attestor** — in-toto/DSSE infrastructure is complete
+
+### Where StellaOps Must Improve
+1. **Verdict portability** — OCI push makes verdicts first-class artifacts
+2. **Audit replay** — One-command replay is essential for compliance
+3. **VEX distribution** — Hub layer creates network effects
+4. **Unknown governance** — Policy budgets make uncertainty actionable
+
+### Avoid Head-On Fights
+- **Snyk**: Don't compete on developer UX; compete on proof-carrying reachability
+- **Prisma**: Don't compete on CNAPP breadth; compete on decision integrity
+- **Anchore**: Don't compete on SBOM storage; compete on semantic diff + VEX reasoning
+
+---
+
+## References
+
+- **Sprints**: `docs/implplan/SPRINT_4300_*.md`, `SPRINT_4400_*.md`, `SPRINT_4500_*.md`, `SPRINT_4600_*.md`
+- **Original Advisory**: `docs/product-advisories/archived/19-Dec-2025 - Stella Ops candidate features mapped to moat strength.md`
+- **Architecture**: `docs/07_HIGH_LEVEL_ARCHITECTURE.md`