Fix build and code structure improvements. New but essential UI functionality. CI improvements. Documentation improvements. AI module improvements.
This commit is contained in:
StellaOps Bot
@@ -0,0 +1,271 @@
|
||||
# Advisory Analysis: Evidence-First Container Security
|
||||
|
||||
**Date:** 2025-12-28
|
||||
**Status:** ANALYZED
|
||||
**Verdict:** HIGHLY ALIGNED - StellaOps is ~90% implemented
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This advisory proposes making container security "evidence-first and audit-ready" with deterministic, replayable verdicts and explainable evidence. After comprehensive analysis of the StellaOps codebase, **we find that ~90% of the recommendations are already implemented**.
|
||||
|
||||
The platform has mature infrastructure for:
|
||||
- Deterministic SBOM generation (RFC 8785 JCS canonicalization)
|
||||
- Verdict replay with drift detection
|
||||
- Delta verdicts with R1-R4 material change detection
|
||||
- Unknowns budgets with two-factor ranking
|
||||
- Air-gap operation with signed feed mirroring
|
||||
- VEX trust scoring with 5-component calculation
|
||||
- DSSE/in-toto attestation with Sigstore integration
|
||||
|
||||
**Remaining gaps (10%):**
|
||||
1. Formalize `replay.json` export format (infrastructure exists)
|
||||
2. OCI artifact attestation attachment workflow
|
||||
3. Frontend UI for evidence subgraph visualization
|
||||
4. eBPF runtime signal integration (optional)
|
||||
|
||||
---
|
||||
|
||||
## Gap Analysis Matrix
|
||||
|
||||
### Fully Implemented (No Gaps)
|
||||
|
||||
| Advisory Recommendation | StellaOps Implementation | Evidence |
|
||||
|------------------------|--------------------------|----------|
|
||||
| Deterministic SBOMs | RFC 8785 JCS via `CanonJson.cs` | `SbomDeterminismTests.cs` |
|
||||
| Reproducibility proofs | `DeterminismManifest`, feed snapshots | `FeedSnapshotCoordinatorService` |
|
||||
| Patch/backport awareness | 4-tier `BackportEvidenceResolver` | `ProvenanceScope.cs` |
|
||||
| Delta verdicts | `DeltaVerdict`, `SecurityStateDelta` | `MaterialRiskChangeDetector` (R1-R4) |
|
||||
| Unknowns budgets | `UnknownsBudgetGate`, two-factor ranking | `UnknownRanker.cs` |
|
||||
| Air-gap mode | `BundleExportService`, signed mirrors | `StellaOpsMirrorConnector` |
|
||||
| Self-hosted feeds | JWS signature verification | `MirrorSignatureVerifier` |
|
||||
| Postgres-only profile | All modules migrated | MongoDB removed |
|
||||
| VEX trust scoring | 5-component calculator | `SourceTrustScoreCalculator` |
|
||||
| DSSE/in-toto attestations | Full implementation | `DsseEnvelope`, `AttestorSigningService` |
|
||||
| Keyless signing | Fulcio integration | `KeylessDsseSigner` |
|
||||
| Offline verification | Bundled trust roots | `OfflineVerifier` |
|
||||
| 32 advisory connectors | National CERTs, distros, vendors | Concelier connectors |
|
||||
| 4 consensus algorithms | HighestWeight, WeightedVote, Lattice, AuthoritativeFirst | `VexConsensusEngine` |
|
||||
| Binary analysis (ELF/PE) | Feature extractors | `ElfFeatureExtractor`, `PeFeatureExtractor` |
|
||||
| Call graph extraction | Multi-language support | `BinaryCallGraphExtractor` |
|
||||
| Gate levels (G0-G4) | Risk-based release gates | `DeltaGateLevel` |
|
||||
| Merkle tree proofs | Evidence bundling | `MerkleTreeCalculator` |
|
||||
|
||||
### Partial Implementation (Low Gaps)
|
||||
|
||||
| Advisory Recommendation | Current State | Remaining Work |
|
||||
|------------------------|---------------|----------------|
|
||||
| `replay.json` export | `replay.schema.json` exists, infrastructure complete | Formalize export format, CI template |
|
||||
| OCI attestation attachment | Signing complete, attachment missing | Implement `OciAttestationAttacher` |
|
||||
| Trust lattice config UI | Backend complete | Admin UI needed |
|
||||
|
||||
### Not Implemented (Medium-High Gaps)
|
||||
|
||||
| Advisory Recommendation | Current State | Required Work |
|
||||
|------------------------|---------------|---------------|
|
||||
| Evidence subgraph UI | Backend exists | Frontend visualization |
|
||||
| Single-action triage cards | API exists | Angular components |
|
||||
| eBPF runtime signals | `RuntimeStaticMerger` exists | Probe implementation |
|
||||
|
||||
---
|
||||
|
||||
## Recommended Sprints
|
||||
|
||||
Based on the gap analysis, only **4 sprints** are needed (reduced from 8 originally estimated):
|
||||
|
||||
### Sprint 1: SPRINT_20251228_001_BE_replay_manifest_ci
|
||||
**Priority:** HIGH | **Effort:** Low
|
||||
- Formalize `replay.json` export schema
|
||||
- Create CI workflow template for SBOM drift detection
|
||||
- Add `--fail-on-drift` CLI flag
|
||||
|
||||
### Sprint 2: SPRINT_20251228_002_BE_oci_attestation_attach
|
||||
**Priority:** HIGH | **Effort:** Low
|
||||
- Implement `IOciAttestationAttacher` service
|
||||
- CLI commands `stella attest attach/verify/list`
|
||||
- Cosign compatibility documentation
|
||||
|
||||
### Sprint 3: SPRINT_20251228_003_FE_evidence_subgraph_ui
|
||||
**Priority:** MEDIUM | **Effort:** High
|
||||
- Evidence subgraph visualization component
|
||||
- Single-action triage cards
|
||||
- "Explain this verdict" summary
|
||||
- Quiet-by-design default filters
|
||||
|
||||
### Sprint 4: SPRINT_20251228_004_AG_ebpf_runtime_signals
|
||||
**Priority:** LOW (optional) | **Effort:** High
|
||||
- eBPF probe implementation
|
||||
- Runtime signal collection
|
||||
- Merge with static reachability
|
||||
|
||||
---
|
||||
|
||||
## Key Implementation Discoveries
|
||||
|
||||
### 1. Determinism Infrastructure
|
||||
|
||||
**Files examined:**
|
||||
- `src/__Libraries/StellaOps.Canonical.Json/CanonJson.cs` - RFC 8785 JCS implementation
|
||||
- `src/__Libraries/StellaOps.Replay.Core/Schemas/replay.schema.json` - Replay schema v1.0.0
|
||||
- `src/__Tests/Integration/StellaOps.Integration.Determinism/` - Comprehensive tests
|
||||
|
||||
**Findings:**
|
||||
- All 25 DET-GAP items documented as DONE
|
||||
- Cross-platform CI (Windows/Linux/macOS) implemented
|
||||
- Roslyn analyzers (STELLA0100/0101/0102) enforce boundaries
|
||||
- Property-based tests with FsCheck
|
||||
|
||||
### 2. Delta Verdict System
|
||||
|
||||
**Files examined:**
|
||||
- `src/Policy/__Libraries/StellaOps.Policy/Deltas/DeltaVerdict.cs`
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/MaterialRiskChangeDetector.cs`
|
||||
|
||||
**Findings:**
|
||||
- 5-dimension delta analysis (SBOM, Reachability, VEX, Policy, Unknowns)
|
||||
- R1-R4 material change detection rules
|
||||
- Priority scoring with contextual factors
|
||||
- Gate levels G0-G4 with escalation logic
|
||||
|
||||
### 3. Unknowns Management
|
||||
|
||||
**Files examined:**
|
||||
- `src/Policy/__Libraries/StellaOps.Policy/Gates/UnknownsBudgetGate.cs`
|
||||
- `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Services/UnknownRanker.cs`
|
||||
|
||||
**Findings:**
|
||||
- Two-factor ranking (uncertainty + exploit pressure)
|
||||
- Time decay with configurable buckets
|
||||
- Containment reduction from blast radius signals
|
||||
- Band assignment (Hot/Warm/Cold/Resolved)
|
||||
|
||||
### 4. VEX Trust Scoring
|
||||
|
||||
**Files examined:**
|
||||
- `src/VexLens/StellaOps.VexLens/Trust/SourceTrust/SourceTrustScoreCalculator.cs`
|
||||
- `src/VexLens/StellaOps.VexLens/Consensus/VexConsensusEngine.cs`
|
||||
|
||||
**Findings:**
|
||||
- 5-component scoring: Authority (0.20), Accuracy (0.25), Timeliness (0.20), Coverage (0.15), Verification (0.20)
|
||||
- Trust tiers: Critical (>0.75), High, Medium, Low
|
||||
- 4 consensus algorithms implemented
|
||||
- Conflict detection with severity levels
|
||||
|
||||
### 5. Air-Gap Capabilities
|
||||
|
||||
**Files examined:**
|
||||
- `src/AirGap/StellaOps.AirGap.Bundle/Services/BundleExportService.cs`
|
||||
- `src/Concelier/__Libraries/StellaOps.Concelier.Connector.StellaOpsMirror/Security/MirrorSignatureVerifier.cs`
|
||||
- `devops/compose/docker-compose.airgap.yaml`
|
||||
|
||||
**Findings:**
|
||||
- Production-grade offline kit with 300-500MB bundles
|
||||
- JWS signature verification for mirrors
|
||||
- Delta updates (<30MB daily)
|
||||
- Egress policy enforcement with sealed mode
|
||||
- Local observability stack (Prometheus/Grafana/Loki)
|
||||
|
||||
### 6. Attestation Infrastructure
|
||||
|
||||
**Files examined:**
|
||||
- `src/Attestor/StellaOps.Attestor.Envelope/DsseEnvelope.cs`
|
||||
- `src/__Libraries/StellaOps.AuditPack/Services/AuditPackBuilder.cs`
|
||||
- `src/ExportCenter/StellaOps.ExportCenter/StellaOps.ExportCenter.Core/AttestationBundle/AttestationBundleBuilder.cs`
|
||||
|
||||
**Findings:**
|
||||
- DSSE/in-toto v1 fully implemented
|
||||
- Multiple signing modes: keyless (Fulcio), KMS, HSM, FIDO2
|
||||
- Merkle tree integrity verification
|
||||
- Rekor transparency log integration
|
||||
- Multiple export formats: ZIP, JSON, DSSE envelope
|
||||
- Shell verification scripts for offline validation
|
||||
|
||||
---
|
||||
|
||||
## Validation Against StellaOps Vision
|
||||
|
||||
| Advisory Principle | CLAUDE.md Alignment |
|
||||
|-------------------|---------------------|
|
||||
| Determinism | "Outputs must be reproducible - stable ordering, UTC ISO-8601 timestamps" |
|
||||
| Offline-first | "Remote host allowlist, strict schema validation" |
|
||||
| VEX-first decisioning | "Exploitability modeled in OpenVEX with lattice logic for stable outcomes" |
|
||||
| Plugin architecture | "Concelier connectors, Authority plugins, Scanner analyzers are all plugin-based" |
|
||||
| Evidence as artifacts | EvidenceLocker, AuditPack, Attestor modules exist |
|
||||
|
||||
**Conclusion:** The advisory is a **natural evolution** of StellaOps' existing architecture, not a pivot.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Roadmap
|
||||
|
||||
### Q1 2026 (Immediate)
|
||||
- Sprint 1: replay.json formalization
|
||||
- Sprint 2: OCI attestation attachment
|
||||
|
||||
### Q2 2026
|
||||
- Sprint 3: Evidence subgraph UI
|
||||
|
||||
### Q3 2026 (Optional)
|
||||
- Sprint 4: eBPF runtime signals
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
### Sprint Files Created
|
||||
- `docs/implplan/SPRINT_20251228_001_BE_replay_manifest_ci.md`
|
||||
- `docs/implplan/SPRINT_20251228_002_BE_oci_attestation_attach.md`
|
||||
- `docs/implplan/SPRINT_20251228_003_FE_evidence_subgraph_ui.md`
|
||||
- `docs/implplan/SPRINT_20251228_004_AG_ebpf_runtime_signals.md`
|
||||
|
||||
### Key Source Files Analyzed
|
||||
- `src/Replay/` - Verdict replay infrastructure
|
||||
- `src/Policy/__Libraries/StellaOps.Policy/Deltas/` - Delta verdict system
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/` - Material change detection
|
||||
- `src/VexLens/` - VEX consensus and trust scoring
|
||||
- `src/AirGap/` - Offline bundle management
|
||||
- `src/Attestor/` - DSSE/in-toto attestations
|
||||
- `src/__Libraries/StellaOps.AuditPack/` - Audit pack export
|
||||
|
||||
### Documentation Referenced
|
||||
- `docs/contributing/canonicalization-determinism.md`
|
||||
- `docs/24_OFFLINE_KIT.md`
|
||||
- `docs/airgap/airgap-mode.md`
|
||||
- Module AGENTS.md files
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Original Advisory
|
||||
|
||||
<details>
|
||||
<summary>Click to expand original advisory text</summary>
|
||||
|
||||
### Why this matters (quick context)
|
||||
|
||||
Most scanners stop at "found X vulns." That creates noise, rework, and weak audit trails. The next leap is **deterministic, replayable verdicts** with **explainable evidence**—so engineers, auditors, and vendors see *why* something is (not) a risk and can reproduce the result exactly.
|
||||
|
||||
### Gaps to close (what typical tools miss)
|
||||
|
||||
* **Deterministic SBOMs + reproducibility proofs**
|
||||
* **Patch/backport awareness (distro-verified)**
|
||||
* **Delta verdicts as first-class artifacts**
|
||||
* **Offline/air-gap mode with self-hosted feeds**
|
||||
* **Explainable UI (evidence subgraphs, not lists)**
|
||||
|
||||
### Stella Ops "fill" (what to build in)
|
||||
|
||||
* **Binaries DB + call-stack capture**
|
||||
* **Policy-driven "unknowns budgets"**
|
||||
* **VEX authoring/ingestion with trust scoring**
|
||||
* **DSSE/in-toto attestations**
|
||||
* **Auditor-ready export packs**
|
||||
|
||||
### Minimal product slices (shippable now)
|
||||
|
||||
* **MVP-A: Deterministic SBOM kit**
|
||||
* **MVP-B: Backport-aware triage**
|
||||
* **MVP-C: Delta verdicts**
|
||||
|
||||
</details>
|
||||
|
||||
@@ -0,0 +1,524 @@
|
||||
# Advisory Lens - Gap Analysis and Implementation Plan
|
||||
|
||||
**Date:** 2025-12-27
|
||||
**Status:** Under Review
|
||||
**Related Advisory:** Advisory Lens Vision Document
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The "Advisory Lens" vision proposes a contextual copilot that learns from organizational data (SBOM changes, reachability graphs, triage outcomes, policy decisions) to surface explainable suggestions. After comprehensive analysis against the StellaOps codebase, this advisory represents a **high-value, strategically aligned enhancement** that leverages substantial existing infrastructure while filling critical gaps.
|
||||
|
||||
### Strategic Fit Score: 9/10
|
||||
|
||||
**Why this matters for StellaOps:**
|
||||
- Directly amplifies the platform's core differentiator: **explainable, evidence-backed decisioning**
|
||||
- Builds on existing investments in reachability, attestations, and policy infrastructure
|
||||
- Creates defensible moat through institutional memory and deterministic replay
|
||||
- Aligns with offline-first, determinism-first architectural principles
|
||||
|
||||
---
|
||||
|
||||
## Gap Analysis: What Exists vs. What's Needed
|
||||
|
||||
### 1. Signals & Learning Sources
|
||||
|
||||
| Advisory Requirement | Existing Capability | Gap Level |
|
||||
|---------------------|---------------------|-----------|
|
||||
| **Reachability graphs** | Scanner: SmartDiff, ReachabilityDrift, 3-bit ReachabilityGate, CallGraph extractors (5 languages) | **LOW** - Already rich |
|
||||
| **SBOM deltas** | Scanner: diff-aware rescans, SmartDiffPredicate; SbomService: lineage ledger, LNM schema | **LOW** - Needs delta extraction API |
|
||||
| **VEX & triage history** | Excititor: VexCandidateEmitter, emission triggers; Findings Ledger: immutable audit trail | **MEDIUM** - Need outcome correlation |
|
||||
| **Runtime hints** | Signals: 5-factor Unknowns scoring, HOT/WARM/COLD bands; Scanner: eBPF/ETW runtime traces (Sprint 3840) | **MEDIUM** - Feature flag detection missing |
|
||||
| **Policy outcomes** | Policy: K4 lattice logic, 7-status PolicyVerdict, PolicyExplanation, SuppressionRuleEvaluator | **LOW** - Outcomes tracked |
|
||||
|
||||
### 2. Core Loop Components
|
||||
|
||||
| Advisory Requirement | Existing Capability | Gap Level |
|
||||
|---------------------|---------------------|-----------|
|
||||
| **Ingest & normalize** | CycloneDX/SPDX fully supported; VEX ingestion; reachability edges via CallGraph | **LOW** |
|
||||
| **Match similar situations** | **BinaryIndex.Fingerprints** exists for binary matching; **NO semantic case matching** | **HIGH** - Core gap |
|
||||
| **Rank next actions** | Signals: Unknowns scoring with decay; Policy: risk scoring | **MEDIUM** - Need action ranking |
|
||||
| **Explain with evidence** | Attestor: ProofBundle, ReasoningPredicate, ProofSpine; StellaVerdict consolidation underway | **LOW** - Strong foundation |
|
||||
| **Capture feedback** | Findings Ledger: immutable audit; VEX approval workflow | **MEDIUM** - Need feedback loop |
|
||||
|
||||
### 3. Data Model & Storage
|
||||
|
||||
| Advisory Requirement | Existing Capability | Gap Level |
|
||||
|---------------------|---------------------|-----------|
|
||||
| **EvidenceCase** | Attestor: EvidencePredicate, content-addressed IDs (RFC 8785) | **MEDIUM** - Need advisory-specific schema |
|
||||
| **Outcome** | PolicyVerdict, VexCandidate with proof_refs | **MEDIUM** - Need outcome consolidation |
|
||||
| **Pattern** (graph-embedding + rules) | Graph module: in-memory, needs persistent backing; BinaryIndex: fingerprints | **HIGH** - Core gap |
|
||||
| **Signed & replayable** | Attestor: DSSE, Rekor, offline verification; Replay module exists | **LOW** |
|
||||
|
||||
### 4. Attestation Infrastructure
|
||||
|
||||
| Advisory Requirement | Existing Capability | Gap Level |
|
||||
|---------------------|---------------------|-----------|
|
||||
| **advisory.attestation type** | Attestor supports 6+ predicate types; adding new types is documented pattern | **LOW** - Add new predicate |
|
||||
| **OCI-attached attestation** | Scanner Sprint 3850: OCI artifact storage for slices | **LOW** - Reuse pattern |
|
||||
|
||||
### 5. UI Components
|
||||
|
||||
| Advisory Requirement | Existing Capability | Gap Level |
|
||||
|---------------------|---------------------|-----------|
|
||||
| **Lens panel** | Angular 17 frontend exists; no "Lens" component yet | **MEDIUM** - New component |
|
||||
| **Inline hints** | VEX emission surfaces candidates in triage UI | **MEDIUM** - Extend pattern |
|
||||
| **Playbooks drawer** | Policy templates exist; no dry-run UI | **HIGH** - New feature |
|
||||
| **Evidence chips** | Attestor proof chain visualization exists | **LOW** - Reuse |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Gap Assessment
|
||||
|
||||
### GAP-1: Semantic Case Matching (HIGH)
|
||||
|
||||
**What's missing:** The ability to fingerprint a situation (vuln + reachability path + context) and find similar historical cases.
|
||||
|
||||
**What exists:**
|
||||
- `BinaryIndex.Fingerprints` for binary identity extraction
|
||||
- `Scheduler.FailureSignatureIndexer` for failure pattern indexing
|
||||
- Graph module with diff/overlay capabilities
|
||||
|
||||
**Required:**
|
||||
- Graph embedding/fingerprint library for vulnerability situations
|
||||
- Similarity index (top-k nearest neighbor search)
|
||||
- Pattern storage with policy/outcome linkage
|
||||
|
||||
### GAP-2: Action Ranking Engine (MEDIUM)
|
||||
|
||||
**What's missing:** Greedy risk-per-change ranking algorithm.
|
||||
|
||||
**What exists:**
|
||||
- Signals: Unknowns 5-factor scoring with configurable weights
|
||||
- Policy: Risk scoring via `StellaOps.Policy.Scoring`
|
||||
- SmartDiff: reachability-weighted findings
|
||||
|
||||
**Required:**
|
||||
- Upgrade ranking algorithm (actions that remove most reachable CVEs per change)
|
||||
- Integration with SBOM delta to compute "change units"
|
||||
|
||||
### GAP-3: Feedback Loop Integration (MEDIUM)
|
||||
|
||||
**What's missing:** Capturing accept/modify/ignore actions to train suggestions.
|
||||
|
||||
**What exists:**
|
||||
- Findings Ledger: immutable audit trail
|
||||
- VEX approval workflow in Excititor
|
||||
|
||||
**Required:**
|
||||
- Feedback event schema
|
||||
- Outcome correlation service
|
||||
- Precision@k tracking
|
||||
|
||||
### GAP-4: Playbook/Dry-Run Infrastructure (HIGH)
|
||||
|
||||
**What's missing:** One-click policy application with preview.
|
||||
|
||||
**What exists:**
|
||||
- Policy simulation (Scheduler: `PolicyBatchSimulationWorker`)
|
||||
- Suppression rules with override providers
|
||||
|
||||
**Required:**
|
||||
- Dry-run API with diff preview
|
||||
- Rollback plan generation
|
||||
- Playbook templating system
|
||||
|
||||
### GAP-5: Advisory Service (NEW MODULE)
|
||||
|
||||
**What's missing:** Central service to compute and surface suggestions.
|
||||
|
||||
**What exists:**
|
||||
- AdvisoryAI module (AI-assisted analysis with LLM guardrails) - can be extended
|
||||
- Scanner.WebService adjacent pattern
|
||||
|
||||
**Required:**
|
||||
- Advisory suggestion computation service
|
||||
- REST API for suggestions
|
||||
- Background worker for proactive analysis
|
||||
|
||||
---
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|------|------------|--------|------------|
|
||||
| Similarity matching produces poor results | Medium | High | Start with simple heuristics; add ML gradually |
|
||||
| Performance overhead on suggestion computation | Medium | Medium | Background computation; aggressive caching |
|
||||
| User distrust of "AI suggestions" | Low | High | Always show evidence; never hide reasoning |
|
||||
| Scope creep into full ML platform | High | Medium | Phase boundaries; v1 heuristics-only |
|
||||
| Integration complexity across modules | Medium | Medium | Consolidate into single AdvisoryLens module |
|
||||
|
||||
---
|
||||
|
||||
## Recommendation: PROCEED with Phased Implementation
|
||||
|
||||
### Why Proceed:
|
||||
1. **Strategic Moat:** Institutional memory is defensible
|
||||
2. **Leverage Existing:** 70%+ infrastructure already built
|
||||
3. **User Delight:** Reduces triage time measurably
|
||||
4. **Determinism Aligned:** Replay-safe suggestions fit StellaOps philosophy
|
||||
|
||||
### Critical Success Factors:
|
||||
1. Every suggestion MUST cite prior evidence
|
||||
2. Deterministic replay of suggestion computation
|
||||
3. No opaque ML - start with interpretable heuristics
|
||||
4. Offline-first: works in air-gapped deployments
|
||||
|
||||
---
|
||||
|
||||
## Sprint/Task Breakdown
|
||||
|
||||
### Phase 1: Foundation (Sprints 4000-4020)
|
||||
|
||||
#### SPRINT_4000_0001_0001_LB_advisory_lens_core
|
||||
|
||||
**Objective:** Create core AdvisoryLens library with data models and interfaces.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 1.1 | TODO | Define `AdvisoryCase` model (sbom_hash_from/to, vuln_id, reachable_path_hash, context_keys) |
|
||||
| 1.2 | TODO | Define `AdvisoryOutcome` model (action, reason_code, proof_refs, feedback_status) |
|
||||
| 1.3 | TODO | Define `AdvisoryPattern` model (fingerprint, rules_digest, linked_outcomes) |
|
||||
| 1.4 | TODO | Define `AdvisorySuggestion` model (action, confidence, evidence_refs, explanation) |
|
||||
| 1.5 | TODO | Create `IAdvisoryLensService` interface |
|
||||
| 1.6 | TODO | Add canonical JSON serialization with RFC 8785 |
|
||||
| 1.7 | TODO | Add content-addressed ID generation |
|
||||
|
||||
**Files:**
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Models/AdvisoryCase.cs`
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Models/AdvisoryOutcome.cs`
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Models/AdvisoryPattern.cs`
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Models/AdvisorySuggestion.cs`
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Services/IAdvisoryLensService.cs`
|
||||
|
||||
#### SPRINT_4000_0001_0002_LB_graph_fingerprint
|
||||
|
||||
**Objective:** Deterministic graph fingerprinting for reachability subgraphs.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 2.1 | TODO | Design fingerprint schema (vuln + entrypoint + path + context) |
|
||||
| 2.2 | TODO | Implement `ReachabilityFingerprintBuilder` with deterministic hashing |
|
||||
| 2.3 | TODO | Add context extraction (feature flags, env vars, policy bindings) |
|
||||
| 2.4 | TODO | Create `IGraphFingerprintService` interface |
|
||||
| 2.5 | TODO | Add serialization to BLAKE3 content-addressed ID |
|
||||
| 2.6 | TODO | Write determinism tests (same inputs = same fingerprint) |
|
||||
|
||||
**Files:**
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Fingerprinting/ReachabilityFingerprintBuilder.cs`
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Fingerprinting/IGraphFingerprintService.cs`
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Fingerprinting/ContextExtractor.cs`
|
||||
|
||||
#### SPRINT_4000_0001_0003_BE_similarity_index
|
||||
|
||||
**Objective:** Pattern similarity index with top-k retrieval.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 3.1 | TODO | Design PostgreSQL schema for patterns with GIN indexes |
|
||||
| 3.2 | TODO | Implement `PatternRepository` with similarity search |
|
||||
| 3.3 | TODO | Add Valkey cache layer for hot patterns |
|
||||
| 3.4 | TODO | Create `ISimilarityIndexService` interface |
|
||||
| 3.5 | TODO | Implement simple Jaccard similarity for v1 |
|
||||
| 3.6 | TODO | Add threshold-based noise gating |
|
||||
| 3.7 | TODO | Write integration tests with Testcontainers |
|
||||
|
||||
**Files:**
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens.Persistence/Postgres/PatternRepository.cs`
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Services/SimilarityIndexService.cs`
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Services/ISimilarityIndexService.cs`
|
||||
|
||||
#### SPRINT_4000_0002_0001_BE_sbom_delta_service
|
||||
|
||||
**Objective:** Extract and expose SBOM deltas for suggestion computation.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 4.1 | TODO | Create `SbomDeltaExtractor` using existing SmartDiff infrastructure |
|
||||
| 4.2 | TODO | Define delta schema (added, removed, upgraded, downgraded packages) |
|
||||
| 4.3 | TODO | Add transitive dependency tracking |
|
||||
| 4.4 | TODO | Expose `GET /api/v1/sbom/{id}/delta?to={id}` endpoint |
|
||||
| 4.5 | TODO | Add deterministic ordering to delta output |
|
||||
|
||||
**Files:**
|
||||
- `src/SbomService/StellaOps.SbomService/Services/SbomDeltaExtractor.cs`
|
||||
- `src/SbomService/StellaOps.SbomService/Endpoints/SbomDeltaEndpoints.cs`
|
||||
|
||||
### Phase 1 Continued: Heuristics Engine (Sprints 4010-4020)
|
||||
|
||||
#### SPRINT_4010_0001_0001_BE_suggestion_engine
|
||||
|
||||
**Objective:** Core suggestion computation with initial heuristics.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 5.1 | TODO | Implement `GreedyRiskPerChangeRanker` |
|
||||
| 5.2 | TODO | Implement `SubgraphSimilarityMatcher` |
|
||||
| 5.3 | TODO | Implement `NoiseGateFilter` (weak evidence threshold) |
|
||||
| 5.4 | TODO | Create `SuggestionEngine` orchestrator |
|
||||
| 5.5 | TODO | Add explanation generator with evidence links |
|
||||
| 5.6 | TODO | Configure heuristic weights via IOptions |
|
||||
|
||||
**Files:**
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Heuristics/GreedyRiskPerChangeRanker.cs`
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Heuristics/SubgraphSimilarityMatcher.cs`
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Heuristics/NoiseGateFilter.cs`
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Services/SuggestionEngine.cs`
|
||||
|
||||
#### SPRINT_4010_0001_0002_BE_outcome_tracker
|
||||
|
||||
**Objective:** Capture and correlate outcomes from policy decisions.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 6.1 | TODO | Create `OutcomeCorrelationService` |
|
||||
| 6.2 | TODO | Integrate with Findings Ledger events |
|
||||
| 6.3 | TODO | Integrate with VEX approval workflow |
|
||||
| 6.4 | TODO | Add feedback event schema |
|
||||
| 6.5 | TODO | Store outcomes with pattern linkage |
|
||||
| 6.6 | TODO | Implement precision@k tracking |
|
||||
|
||||
**Files:**
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Services/OutcomeCorrelationService.cs`
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Events/FeedbackEvent.cs`
|
||||
|
||||
#### SPRINT_4010_0002_0001_BE_advisory_attestation
|
||||
|
||||
**Objective:** New attestation type for advisory suggestions.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 7.1 | TODO | Define `AdvisoryPredicate` following existing patterns |
|
||||
| 7.2 | TODO | Add predicate type: `application/vnd.stellaops.advisory+json` |
|
||||
| 7.3 | TODO | Implement `AdvisoryAttestationBuilder` |
|
||||
| 7.4 | TODO | Add DSSE signing integration |
|
||||
| 7.5 | TODO | Create schema: `docs/schemas/stellaops-advisory.v1.schema.json` |
|
||||
| 7.6 | TODO | Add to Attestor predicate registry |
|
||||
|
||||
**Files:**
|
||||
- `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/AdvisoryPredicate.cs`
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Attestation/AdvisoryAttestationBuilder.cs`
|
||||
- `docs/schemas/stellaops-advisory.v1.schema.json`
|
||||
|
||||
### Phase 1: API & Integration (Sprint 4020)
|
||||
|
||||
#### SPRINT_4020_0001_0001_BE_advisory_api
|
||||
|
||||
**Objective:** REST API for advisory suggestions.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 8.1 | TODO | Create `AdvisoryLensController` |
|
||||
| 8.2 | TODO | Implement `GET /api/v1/advisory/suggestions?artifact={id}` |
|
||||
| 8.3 | TODO | Implement `GET /api/v1/advisory/suggestions/{id}/evidence` |
|
||||
| 8.4 | TODO | Implement `POST /api/v1/advisory/feedback` |
|
||||
| 8.5 | TODO | Add tenant isolation via RLS |
|
||||
| 8.6 | TODO | Add rate limiting and caching |
|
||||
|
||||
**Files:**
|
||||
- `src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/Controllers/AdvisoryLensController.cs`
|
||||
|
||||
#### SPRINT_4020_0001_0002_BE_background_worker
|
||||
|
||||
**Objective:** Background suggestion computation on SBOM/VEX changes.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 9.1 | TODO | Create `AdvisorySuggestionWorker` |
|
||||
| 9.2 | TODO | Subscribe to SBOM ingestion events |
|
||||
| 9.3 | TODO | Subscribe to VEX change events |
|
||||
| 9.4 | TODO | Implement batch suggestion computation |
|
||||
| 9.5 | TODO | Add metrics: suggestion latency, cache hit ratio |
|
||||
|
||||
**Files:**
|
||||
- `src/AdvisoryAI/StellaOps.AdvisoryAI.Worker/Workers/AdvisorySuggestionWorker.cs`
|
||||
|
||||
### Phase 2: UI Integration (Sprints 4030-4040)
|
||||
|
||||
#### SPRINT_4030_0001_0001_FE_lens_panel
|
||||
|
||||
**Objective:** "Top 3 Suggestions Today" panel for Timeline/Projects.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 10.1 | TODO | Create `LensPanelComponent` |
|
||||
| 10.2 | TODO | Design suggestion card with evidence chips |
|
||||
| 10.3 | TODO | Add "Apply as dry-run" button |
|
||||
| 10.4 | TODO | Integrate with Timeline view |
|
||||
| 10.5 | TODO | Add loading/empty states |
|
||||
|
||||
**Files:**
|
||||
- `src/Web/StellaOps.Web/src/app/components/lens-panel/`
|
||||
|
||||
#### SPRINT_4030_0001_0002_FE_inline_hints
|
||||
|
||||
**Objective:** Inline hints on detail pages.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 11.1 | TODO | Create `InlineHintComponent` |
|
||||
| 11.2 | TODO | Add to vulnerability detail pages |
|
||||
| 11.3 | TODO | Add to SBOM component pages |
|
||||
| 11.4 | TODO | Style with non-obtrusive design |
|
||||
|
||||
**Files:**
|
||||
- `src/Web/StellaOps.Web/src/app/components/inline-hint/`
|
||||
|
||||
#### SPRINT_4040_0001_0001_FE_playbooks_drawer
|
||||
|
||||
**Objective:** Playbook application with dry-run preview.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 12.1 | TODO | Create `PlaybookDrawerComponent` |
|
||||
| 12.2 | TODO | Implement dry-run diff view |
|
||||
| 12.3 | TODO | Add rollback plan display |
|
||||
| 12.4 | TODO | Integrate with policy application |
|
||||
| 12.5 | TODO | Add confirmation flow |
|
||||
|
||||
**Files:**
|
||||
- `src/Web/StellaOps.Web/src/app/components/playbook-drawer/`
|
||||
|
||||
#### SPRINT_4040_0001_0002_BE_dry_run_api
|
||||
|
||||
**Objective:** Backend support for dry-run policy application.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 13.1 | TODO | Extend `PolicyBatchSimulationWorker` for dry-run |
|
||||
| 13.2 | TODO | Implement `POST /api/v1/advisory/apply?dryRun=true` |
|
||||
| 13.3 | TODO | Generate signed delta-verdict |
|
||||
| 13.4 | TODO | Generate rollback plan |
|
||||
| 13.5 | TODO | Add to attestation chain |
|
||||
|
||||
**Files:**
|
||||
- `src/Policy/StellaOps.Policy.Engine/Services/DryRunService.cs`
|
||||
|
||||
### Phase 2 Continued: Counterfactuals & Templates (Sprint 4050)
|
||||
|
||||
#### SPRINT_4050_0001_0001_BE_counterfactuals
|
||||
|
||||
**Objective:** "Had you done X, Y wouldn't have happened" analysis.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 14.1 | TODO | Design counterfactual computation model |
|
||||
| 14.2 | TODO | Implement `CounterfactualAnalyzer` |
|
||||
| 14.3 | TODO | Integrate with historical findings |
|
||||
| 14.4 | TODO | Add to suggestion explanations |
|
||||
|
||||
**Files:**
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Analysis/CounterfactualAnalyzer.cs`
|
||||
|
||||
#### SPRINT_4050_0001_0002_BE_playbook_templates
|
||||
|
||||
**Objective:** Turn accepted advisories into reusable playbooks.
|
||||
|
||||
| Task | Status | Description |
|
||||
|------|--------|-------------|
|
||||
| 15.1 | TODO | Design playbook template schema |
|
||||
| 15.2 | TODO | Implement `PlaybookTemplateService` |
|
||||
| 15.3 | TODO | Add parameterization support |
|
||||
| 15.4 | TODO | Create template storage |
|
||||
| 15.5 | TODO | Add sharing/team-scope controls |
|
||||
|
||||
**Files:**
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Playbooks/PlaybookTemplate.cs`
|
||||
- `src/__Libraries/StellaOps.AdvisoryLens/Playbooks/PlaybookTemplateService.cs`
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria for v1
|
||||
|
||||
| Metric | Target |
|
||||
|--------|--------|
|
||||
| Suggestions with prior case evidence | >= 70% |
|
||||
| Acceptance rate (accepted or edited) | >= 50% in pilot |
|
||||
| Mean triage time reduction | >= 30% on reachable CVE bursts |
|
||||
| Determinism | Same inputs = identical suggestions |
|
||||
| Offline support | Full functionality in air-gapped mode |
|
||||
|
||||
---
|
||||
|
||||
## Architecture Decision Records
|
||||
|
||||
### ADR-1: Module Placement
|
||||
|
||||
**Decision:** Create `StellaOps.AdvisoryLens` as new library under `src/__Libraries/`, extend `AdvisoryAI` module for hosting.
|
||||
|
||||
**Rationale:**
|
||||
- AdvisoryAI already exists with AI guardrails
|
||||
- Keep core logic in reusable library
|
||||
- WebService/Worker pattern matches existing modules
|
||||
|
||||
### ADR-2: Heuristics Before ML
|
||||
|
||||
**Decision:** Phase 1 uses deterministic heuristics only; ML deferred to Phase 3+.
|
||||
|
||||
**Rationale:**
|
||||
- Determinism is core StellaOps principle
|
||||
- Explainability requires interpretable rules
|
||||
- ML adds complexity without proven value
|
||||
- Easy to add ML later via strategy pattern
|
||||
|
||||
### ADR-3: Pattern Storage
|
||||
|
||||
**Decision:** PostgreSQL with GIN indexes + Valkey cache.
|
||||
|
||||
**Rationale:**
|
||||
- Consistent with platform data strategy
|
||||
- Supports offline operation
|
||||
- GIN indexes efficient for similarity search
|
||||
- Valkey provides hot pattern caching
|
||||
|
||||
### ADR-4: Attestation Type
|
||||
|
||||
**Decision:** New predicate `application/vnd.stellaops.advisory+json`.
|
||||
|
||||
**Rationale:**
|
||||
- Follows established Attestor predicate pattern
|
||||
- Enables signed, replayable suggestions
|
||||
- OCI attachment for portability
|
||||
|
||||
---
|
||||
|
||||
## Dependencies & Prerequisites
|
||||
|
||||
| Dependency | Status | Notes |
|
||||
|------------|--------|-------|
|
||||
| StellaVerdict consolidation | In Progress | Sprint 1227.0014.0001 |
|
||||
| Scanner SmartDiff | Complete | Provides reachability basis |
|
||||
| Findings Ledger | Complete | Outcome tracking |
|
||||
| Attestor ProofChain | Complete | Evidence linking |
|
||||
| Angular 17 frontend | Complete | UI foundation |
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- `docs/modules/advisory-ai/architecture.md` (to be created)
|
||||
- `docs/modules/scanner/reachability-drift.md`
|
||||
- `docs/modules/attestor/architecture.md`
|
||||
- `docs/modules/policy/architecture.md`
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Module Inventory Leveraged
|
||||
|
||||
| Module | Capabilities Used |
|
||||
|--------|------------------|
|
||||
| Scanner | SmartDiff, ReachabilityDrift, CallGraph, ReachabilityGate, VulnSurfaces |
|
||||
| Policy | K4 lattice, PolicyVerdict, SuppressionRules, RiskScoring |
|
||||
| Signals | Unknowns scoring, HOT/WARM/COLD bands, decay |
|
||||
| Attestor | DSSE, ProofChain, EvidencePredicate, ReasoningPredicate |
|
||||
| VexLens | VEX consensus |
|
||||
| Excititor | VexCandidateEmitter, emission triggers |
|
||||
| SbomService | Lineage ledger, LNM schema |
|
||||
| Graph | Query/diff/overlay APIs |
|
||||
| Findings Ledger | Immutable audit trail |
|
||||
| BinaryIndex | Fingerprinting patterns |
|
||||
|
||||
---
|
||||
|
||||
*This advisory was generated based on comprehensive codebase analysis. All sprint estimates are scope-based, not time-based.*
|
||||
636
docs/product-advisories/archived/ADVISORY_SBOM_LINEAGE_GRAPH.md
Normal file
636
docs/product-advisories/archived/ADVISORY_SBOM_LINEAGE_GRAPH.md
Normal file
@@ -0,0 +1,636 @@
|
||||
# Product Advisory Analysis: SBOM Lineage Graph
|
||||
|
||||
**Advisory Date:** 2025-12-28
|
||||
**Status:** Analysis Complete
|
||||
**Recommendation:** **APPROVED - High Strategic Value**
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The SBOM Lineage Graph advisory proposes a Git-like visualization of container image lineage with hover-to-proof micro-interactions, enabling auditors and developers to explore SBOM/VEX deltas across artifact versions. This feature aligns strongly with StellaOps' core mission of **reproducible vulnerability scanning with VEX-first decisioning** and leverages significant existing infrastructure.
|
||||
|
||||
### Strategic Alignment Score: **9/10**
|
||||
|
||||
| Criterion | Score | Rationale |
|
||||
|-----------|-------|-----------|
|
||||
| Vision Alignment | 10/10 | Core to "proof" differentiator - turns evidence into explorable UX |
|
||||
| Existing Infrastructure | 8/10 | 70%+ backend exists; frontend needs new components |
|
||||
| Customer Value | 9/10 | Direct auditor/compliance value; differentiator vs competitors |
|
||||
| Implementation Risk | Low | Builds on proven patterns (ledger, attestation, diff engine) |
|
||||
| Air-Gap Compatibility | 10/10 | Designed offline-first with replay hashes |
|
||||
|
||||
---
|
||||
|
||||
## Module-by-Module Gap Analysis
|
||||
|
||||
### 1. SbomService (`src/SbomService/`)
|
||||
|
||||
**Existing Capabilities:**
|
||||
- Immutable append-only versioning (`SbomLedgerVersion`)
|
||||
- Parent-child lineage via `ParentVersionId` and `ParentDigest` fields
|
||||
- Build relationship linking (same CI `BuildId`)
|
||||
- Component-level diff engine (`SbomLedgerService.DiffAsync`)
|
||||
- Lineage graph generation with nodes and edges (`GetLineageAsync`)
|
||||
- Content-addressed by SHA256 digest
|
||||
- Deterministic ordering (seq DESC, ordinal comparisons)
|
||||
- Version timeline queries with cursor pagination
|
||||
|
||||
**Gaps Identified:**
|
||||
|
||||
| Gap | Severity | Description |
|
||||
|-----|----------|-------------|
|
||||
| **OCI Ancestry Ingestion** | High | Scanner doesn't populate `ParentVersionId`/`ParentDigest` from OCI manifest |
|
||||
| **Lineage Edge Persistence** | Medium | Edges reconstructed on-read, not persisted for query efficiency |
|
||||
| **Replay Hash per Node** | Medium | No addressable replay token per lineage node for determinism verification |
|
||||
| **Upload API Extension** | Low | `SbomUploadRequestDto` missing `parentImageDigest` field |
|
||||
|
||||
**Recommended Changes:**
|
||||
```csharp
|
||||
// Extend SbomUploadRequestDto
|
||||
public sealed record SbomUploadRequestDto(
|
||||
string ArtifactRef,
|
||||
string Sbom,
|
||||
string? Format,
|
||||
string? Source,
|
||||
string? ParentArtifactDigest, // NEW: OCI parent image digest
|
||||
string? BaseImageRef // NEW: Base image reference
|
||||
);
|
||||
|
||||
// New table: sbom_lineage_edges (persistent)
|
||||
CREATE TABLE sbom_lineage_edges (
|
||||
parent_digest TEXT NOT NULL,
|
||||
child_digest TEXT NOT NULL,
|
||||
relationship TEXT NOT NULL, -- 'parent' | 'build' | 'base'
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
PRIMARY KEY (parent_digest, child_digest)
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. VEX Modules (`src/Excititor/`, `src/VexLens/`, `src/VexHub/`)
|
||||
|
||||
**Existing Capabilities:**
|
||||
- Merge trace recording with trust weights (`MergeTrace`)
|
||||
- Lattice-based conflict resolution (K4 logic in `OpenVexStatementMerger`)
|
||||
- VexLens consensus projections with `StatusChanged` flag
|
||||
- History tracking via `PreviousProjectionId`
|
||||
- Confidence scoring (0-1 scale)
|
||||
- Conflict detection with severity levels
|
||||
|
||||
**Gaps Identified:**
|
||||
|
||||
| Gap | Severity | Description |
|
||||
|-----|----------|-------------|
|
||||
| **VEX Delta Table** | High | No persistent `vex_delta` table for A→B status changes with rationale |
|
||||
| **Consensus Persistence** | High | VexLens uses in-memory store; no PostgreSQL backend |
|
||||
| **SBOM-Verdict Join** | High | No linking table for (sbom_version_id, cve, verdict) |
|
||||
| **Delta Verdict Attestation** | Medium | No signed delta predicate type for VEX changes |
|
||||
| **Merge Trace Persistence** | Medium | Traces captured but not persisted; lost on restart |
|
||||
|
||||
**Recommended Schema:**
|
||||
```sql
|
||||
-- VEX verdict deltas (A→B)
|
||||
CREATE TABLE vex_delta (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
from_artifact_digest TEXT NOT NULL,
|
||||
to_artifact_digest TEXT NOT NULL,
|
||||
cve TEXT NOT NULL,
|
||||
from_status TEXT NOT NULL,
|
||||
to_status TEXT NOT NULL,
|
||||
rationale JSONB,
|
||||
replay_hash TEXT NOT NULL,
|
||||
signature BYTEA,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
UNIQUE (from_artifact_digest, to_artifact_digest, cve)
|
||||
);
|
||||
|
||||
-- SBOM-Verdict linking
|
||||
CREATE TABLE sbom_verdict_link (
|
||||
sbom_version_id UUID NOT NULL REFERENCES sbom_snapshots(id),
|
||||
cve TEXT NOT NULL,
|
||||
consensus_projection_id UUID NOT NULL,
|
||||
linked_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
PRIMARY KEY (sbom_version_id, cve)
|
||||
);
|
||||
|
||||
-- Migrate VexLens consensus to Postgres
|
||||
CREATE TABLE vex_consensus_projections (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
vulnerability_id TEXT NOT NULL,
|
||||
product_key TEXT NOT NULL,
|
||||
tenant_id UUID NOT NULL,
|
||||
status TEXT NOT NULL,
|
||||
confidence_score DECIMAL(5,4) NOT NULL,
|
||||
outcome TEXT NOT NULL,
|
||||
statement_count INT NOT NULL,
|
||||
conflict_count INT NOT NULL,
|
||||
computed_at TIMESTAMPTZ NOT NULL,
|
||||
stored_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
previous_projection_id UUID REFERENCES vex_consensus_projections(id),
|
||||
status_changed BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
UNIQUE (tenant_id, vulnerability_id, product_key, computed_at)
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Reachability/Graph (`src/Graph/`, `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/`)
|
||||
|
||||
**Existing Capabilities:**
|
||||
- RichGraph-v1 with nodes, edges, roots
|
||||
- Surface-aware reachability analysis
|
||||
- PathWitness attestations (DSSE-signable)
|
||||
- Gate detection (auth, feature flags, admin-only)
|
||||
- PostgreSQL reachability cache
|
||||
- Deterministic ordering and BLAKE3/SHA256 digests
|
||||
- Confidence tiers (Confirmed, Likely, Present, Unreachable, Unknown)
|
||||
|
||||
**Gaps Identified:**
|
||||
|
||||
| Gap | Severity | Description |
|
||||
|-----|----------|-------------|
|
||||
| **Reachability Delta** | Medium | No diff between two reachability graphs for same CVE across versions |
|
||||
| **Node-level Replay Hash** | Low | Graph has digest but not per-CVE replay hash |
|
||||
|
||||
**Recommended Addition:**
|
||||
```csharp
|
||||
// New service: IReachabilityDeltaService
|
||||
public interface IReachabilityDeltaService
|
||||
{
|
||||
ValueTask<ReachabilityDelta> ComputeDeltaAsync(
|
||||
string fromArtifactDigest,
|
||||
string toArtifactDigest,
|
||||
string cve,
|
||||
CancellationToken cancellationToken);
|
||||
}
|
||||
|
||||
public sealed record ReachabilityDelta(
|
||||
string Cve,
|
||||
ReachabilityStatus FromStatus,
|
||||
ReachabilityStatus ToStatus,
|
||||
IReadOnlyList<PathDelta> AddedPaths,
|
||||
IReadOnlyList<PathDelta> RemovedPaths,
|
||||
IReadOnlyList<GateDelta> GateChanges,
|
||||
string ReplayHash);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Policy/Evidence (`src/Policy/`, `src/EvidenceLocker/`, `src/__Libraries/StellaOps.AuditPack/`)
|
||||
|
||||
**Existing Capabilities:**
|
||||
- Evidence-weighted scoring (6D formula with guardrails)
|
||||
- Audit Pack with Merkle root and optional DSSE signing
|
||||
- Replay mechanism with drift detection
|
||||
- Time anchors for deterministic replay
|
||||
- in-toto/DSSE attestations for replays
|
||||
- Export Center with delta computation (added/changed/removed)
|
||||
- Evidence bundle with RFC 3161 timestamps
|
||||
|
||||
**Gaps Identified:**
|
||||
|
||||
| Gap | Severity | Description |
|
||||
|-----|----------|-------------|
|
||||
| **Delta Verdict Export** | Medium | Export Center computes deltas but not as signed attestations |
|
||||
| **Node-Addressable Audit Pack** | Low | Audit packs are per-scan, not per-lineage-node |
|
||||
|
||||
**Recommended Addition:**
|
||||
```csharp
|
||||
// New predicate type for delta verdicts
|
||||
public static class DeltaPredicateTypes
|
||||
{
|
||||
public const string VexDelta = "stella.ops/vex-delta@v1";
|
||||
public const string SbomDelta = "stella.ops/sbom-delta@v1";
|
||||
public const string VerdictDelta = "stella.ops/verdict-delta@v1";
|
||||
}
|
||||
|
||||
// Lineage node evidence pack
|
||||
public sealed record LineageNodeEvidencePack(
|
||||
string ArtifactDigest,
|
||||
string SbomDigest,
|
||||
IReadOnlyList<string> VexVerdictDigests,
|
||||
string? PolicyVerdictDigest,
|
||||
string ReplayHash,
|
||||
DateTimeOffset GeneratedAt);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Attestor/Signer (`src/Attestor/`, `src/Signer/`)
|
||||
|
||||
**Existing Capabilities:**
|
||||
- DSSE signing (keyless/Fulcio, KMS, HSM)
|
||||
- Rekor transparency logging (primary + mirror)
|
||||
- 18+ predicate types (SBOM, VEX, verdict, reachability, PoE)
|
||||
- Proof chain predicates (ProofSpine, Evidence, VEX)
|
||||
- Offline bundle support with inclusion proofs
|
||||
- Trust verdict evaluation
|
||||
|
||||
**Gaps Identified:**
|
||||
|
||||
| Gap | Severity | Description |
|
||||
|-----|----------|-------------|
|
||||
| **Delta Predicate Types** | Medium | Missing `stella.ops/vex-delta@v1`, `stella.ops/sbom-delta@v1` |
|
||||
| **Lineage Attestation** | Low | No predicate for full lineage graph attestation |
|
||||
|
||||
**Recommended Additions to PredicateTypes.cs:**
|
||||
```csharp
|
||||
// Delta predicates
|
||||
public const string VexDelta = "stella.ops/vex-delta@v1";
|
||||
public const string SbomDelta = "stella.ops/sbom-delta@v1";
|
||||
public const string VerdictDelta = "stella.ops/verdict-delta@v1";
|
||||
public const string LineageGraph = "stella.ops/lineage-graph@v1";
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. Scanner (`src/Scanner/`)
|
||||
|
||||
**Existing Capabilities:**
|
||||
- SBOM generation (CycloneDX 1.4-1.7, SPDX 2.3-3.0.1)
|
||||
- OCI image digest handling via `OciImageReference`
|
||||
- Layer-based component tracking with `LayerDigest`
|
||||
- `SbomCompositionResult` with content hash and recipe
|
||||
|
||||
**Gaps Identified:**
|
||||
|
||||
| Gap | Severity | Description |
|
||||
|-----|----------|-------------|
|
||||
| **OCI Manifest Parsing** | High | No extraction of parent/base image from OCI manifest `config.history` |
|
||||
| **Parent Propagation** | High | `ParentVersionId` infrastructure exists but Scanner doesn't populate it |
|
||||
| **Multi-stage Build Tracking** | Medium | No linking of multi-stage build stages |
|
||||
|
||||
**Recommended Implementation:**
|
||||
```csharp
|
||||
// New service: IOciAncestryExtractor
|
||||
public interface IOciAncestryExtractor
|
||||
{
|
||||
ValueTask<OciAncestry> ExtractAncestryAsync(
|
||||
string imageReference,
|
||||
CancellationToken cancellationToken);
|
||||
}
|
||||
|
||||
public sealed record OciAncestry(
|
||||
string ImageDigest,
|
||||
string? BaseImageDigest, // FROM instruction base
|
||||
string? BaseImageRef, // e.g., "alpine:3.19"
|
||||
IReadOnlyList<string> LayerDigests,
|
||||
IReadOnlyList<OciHistoryEntry> History);
|
||||
|
||||
// Extend scan job to include ancestry
|
||||
public sealed record ScanJobResult(
|
||||
/* existing fields */,
|
||||
OciAncestry? Ancestry);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. Frontend (`src/Web/StellaOps.Web/`)
|
||||
|
||||
**Existing Capabilities:**
|
||||
- Graph-diff component with SVG/pan/zoom (0.1x-3x)
|
||||
- Evidence graph (D3 force-directed, lazy-loaded)
|
||||
- Proof tree/spine visualization
|
||||
- Lattice diagram for VEX merge outcomes
|
||||
- Function diff (side-by-side, unified, summary)
|
||||
- Accessibility (ARIA, keyboard, high-contrast, reduced motion)
|
||||
- Dark mode support
|
||||
|
||||
**Gaps Identified:**
|
||||
|
||||
| Gap | Severity | Description |
|
||||
|-----|----------|-------------|
|
||||
| **Lineage Lane View** | High | No Git-like horizontal graph with lanes/branches |
|
||||
| **Hover-to-Proof Card** | High | No micro-panel showing component diff + VEX delta on hover |
|
||||
| **Compare Mode** | High | No arbitrary A⇄B node selection for comparison |
|
||||
| **Timeline Slider** | Medium | No scrubbing through releases by time |
|
||||
| **Evidence Pack Export** | Medium | No one-click ZIP from lineage node |
|
||||
| **"Why Safe?" Button** | Medium | No human paragraph explanation from evidence |
|
||||
|
||||
**Recommended Components:**
|
||||
|
||||
```
|
||||
src/app/features/lineage/
|
||||
├── components/
|
||||
│ ├── lineage-graph/ # Git-like lane visualization
|
||||
│ │ ├── lineage-graph.component.ts
|
||||
│ │ ├── lineage-node.component.ts
|
||||
│ │ └── lineage-edge.component.ts
|
||||
│ ├── lineage-hover-card/ # Micro-panel on hover
|
||||
│ │ ├── component-diff-card.component.ts
|
||||
│ │ └── vex-delta-card.component.ts
|
||||
│ ├── lineage-compare/ # A⇄B comparison view
|
||||
│ │ ├── compare-selector.component.ts
|
||||
│ │ └── compare-panel.component.ts
|
||||
│ ├── lineage-timeline/ # Time slider
|
||||
│ └── why-safe-panel/ # Human explanation
|
||||
├── services/
|
||||
│ ├── lineage-graph.service.ts
|
||||
│ ├── lineage-diff.service.ts
|
||||
│ └── lineage-export.service.ts
|
||||
├── models/
|
||||
│ ├── lineage-node.model.ts
|
||||
│ └── lineage-diff.model.ts
|
||||
└── lineage.routes.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Consolidated Gap Summary
|
||||
|
||||
### Critical (Must Have for MVP)
|
||||
|
||||
| # | Gap | Module | Effort |
|
||||
|---|-----|--------|--------|
|
||||
| 1 | OCI ancestry extraction from manifest | Scanner | 3 days |
|
||||
| 2 | Persist lineage edges to Postgres | SbomService | 2 days |
|
||||
| 3 | VEX delta table with rationale | Excititor/VexLens | 3 days |
|
||||
| 4 | SBOM-verdict linking table | SbomService + VexLens | 2 days |
|
||||
| 5 | Lineage lane view (Git-like UI) | Web Frontend | 5 days |
|
||||
| 6 | Hover-to-proof card (component + VEX diff) | Web Frontend | 3 days |
|
||||
|
||||
### High (Sprint 2)
|
||||
|
||||
| # | Gap | Module | Effort |
|
||||
|---|-----|--------|--------|
|
||||
| 7 | Migrate VexLens consensus to Postgres | VexLens | 3 days |
|
||||
| 8 | A⇄B compare mode with reachability | Web Frontend | 4 days |
|
||||
| 9 | Delta verdict attestation (signed) | Attestor | 2 days |
|
||||
| 10 | Replay hash per lineage node | SbomService | 2 days |
|
||||
| 11 | Evidence pack export (ZIP) | ExportCenter | 2 days |
|
||||
|
||||
### Medium (Future)
|
||||
|
||||
| # | Gap | Module | Effort |
|
||||
|---|-----|--------|--------|
|
||||
| 12 | Timeline slider UI | Web Frontend | 2 days |
|
||||
| 13 | "Why Safe?" human explanation | AdvisoryAI + Web | 3 days |
|
||||
| 14 | Reachability delta service | Graph | 3 days |
|
||||
| 15 | Merge trace persistence | Excititor | 2 days |
|
||||
| 16 | Lineage graph attestation | Attestor | 1 day |
|
||||
|
||||
---
|
||||
|
||||
## Recommended Sprint Plan
|
||||
|
||||
### Sprint 1: Graph + Hover (2 weeks)
|
||||
|
||||
**Objective:** Render lineage graph with hover cards showing SBOM/VEX deltas
|
||||
|
||||
**Working Directories:**
|
||||
- `src/Scanner/` (OCI ancestry)
|
||||
- `src/SbomService/` (lineage edges, SBOM-verdict linking)
|
||||
- `src/Excititor/` (VEX delta table)
|
||||
- `src/Web/StellaOps.Web/` (lineage UI)
|
||||
|
||||
**Tasks:**
|
||||
|
||||
| # | Task | Module | Est. | Depends |
|
||||
|---|------|--------|------|---------|
|
||||
| 1.1 | Implement `IOciAncestryExtractor` to parse OCI manifest history | Scanner | 2d | - |
|
||||
| 1.2 | Add `parentImageDigest`, `baseImageRef` to `SbomUploadRequestDto` | Scanner | 0.5d | - |
|
||||
| 1.3 | Propagate ancestry to SbomService on upload | Scanner + SbomService | 1d | 1.1, 1.2 |
|
||||
| 1.4 | Create `sbom_lineage_edges` table and repository | SbomService | 1d | - |
|
||||
| 1.5 | Persist edges on version creation | SbomService | 0.5d | 1.4 |
|
||||
| 1.6 | Create `vex_delta` table and repository | Excititor | 1.5d | - |
|
||||
| 1.7 | Compute and store VEX deltas on consensus change | VexLens | 1.5d | 1.6 |
|
||||
| 1.8 | Create `sbom_verdict_link` table | SbomService | 1d | - |
|
||||
| 1.9 | Link verdicts to SBOM versions on evaluation | Policy | 1d | 1.8 |
|
||||
| 1.10 | Create `LineageGraphComponent` (lane view) | Web | 3d | - |
|
||||
| 1.11 | Create `LineageNodeComponent` with badges | Web | 1d | 1.10 |
|
||||
| 1.12 | Create `LineageHoverCardComponent` (diff + VEX) | Web | 2d | 1.10 |
|
||||
| 1.13 | Wire hover card to SBOM diff API | Web | 1d | 1.12 |
|
||||
| 1.14 | Wire hover card to VEX delta API | Web | 1d | 1.7, 1.12 |
|
||||
| 1.15 | Add lineage API endpoint `/api/v1/lineage/{artifact}` | SbomService | 1d | 1.5 |
|
||||
|
||||
**Sprint 1 Deliverables:**
|
||||
- Lineage lane view rendering from OCI ancestry
|
||||
- Hover card showing component diff (added/removed/changed)
|
||||
- Hover card showing VEX status deltas with reason
|
||||
- Evidence links in hover card
|
||||
|
||||
---
|
||||
|
||||
### Sprint 2: Compare + Replay (2 weeks)
|
||||
|
||||
**Objective:** Enable A⇄B comparison with replay verification and export
|
||||
|
||||
**Working Directories:**
|
||||
- `src/SbomService/` (replay hash)
|
||||
- `src/VexLens/` (Postgres migration)
|
||||
- `src/Attestor/` (delta attestations)
|
||||
- `src/ExportCenter/` (evidence pack)
|
||||
- `src/Web/StellaOps.Web/` (compare UI)
|
||||
|
||||
**Tasks:**
|
||||
|
||||
| # | Task | Module | Est. | Depends |
|
||||
|---|------|--------|------|---------|
|
||||
| 2.1 | Migrate `InMemoryConsensusProjectionStore` to Postgres | VexLens | 2d | - |
|
||||
| 2.2 | Add `vex_consensus_projections` table | VexLens | 1d | - |
|
||||
| 2.3 | Compute replay hash per lineage node | SbomService | 1.5d | - |
|
||||
| 2.4 | Add delta predicate types to `PredicateTypes.cs` | Attestor | 0.5d | - |
|
||||
| 2.5 | Create `IDeltaVerdictAttestationService` | Attestor | 1.5d | 2.4 |
|
||||
| 2.6 | Sign delta verdicts on VEX change | Attestor + VexLens | 1d | 2.5 |
|
||||
| 2.7 | Create `LineageCompareComponent` (A⇄B selector) | Web | 2d | - |
|
||||
| 2.8 | Create `ComparePanelComponent` (side-by-side) | Web | 2d | 2.7 |
|
||||
| 2.9 | Wire compare to SBOM diff with reachability | Web | 1d | 2.8 |
|
||||
| 2.10 | Add reachability notes to compare view | Web | 1d | 2.9 |
|
||||
| 2.11 | Create `LineageNodeEvidencePack` model | ExportCenter | 0.5d | - |
|
||||
| 2.12 | Implement evidence pack export (ZIP) | ExportCenter | 1.5d | 2.11 |
|
||||
| 2.13 | Add "Export Audit Pack" button to compare view | Web | 0.5d | 2.12 |
|
||||
| 2.14 | Add replay hash display in node detail | Web | 0.5d | 2.3 |
|
||||
| 2.15 | Create replay verification endpoint | SbomService | 1d | 2.3 |
|
||||
|
||||
**Sprint 2 Deliverables:**
|
||||
- Select any two nodes for comparison
|
||||
- Side-by-side SBOM/VEX diff with reachability notes
|
||||
- Signed delta verdict attestations
|
||||
- Exportable Audit Pack (ZIP) with SBOMs, VEX, policy, signatures
|
||||
- Replay hash for local verification
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
### Sprint 1 (Demoable)
|
||||
|
||||
- [ ] Lineage graph renders with lanes (base → derived)
|
||||
- [ ] Hover on node shows component diff in <150ms (cached)
|
||||
- [ ] Hover shows VEX status deltas (e.g., `CVE-2024-1234: not_affected → affected`)
|
||||
- [ ] Evidence links navigate to source documents
|
||||
- [ ] Badges show "N new vulns", "K resolved", "signature ✓/✗"
|
||||
|
||||
### Sprint 2 (Demoable)
|
||||
|
||||
- [ ] Click any two nodes to compare
|
||||
- [ ] Compare view shows reachability delta (paths added/removed)
|
||||
- [ ] "Why?" click shows policy rule + evidence that produced verdict
|
||||
- [ ] Export produces signed Delta Verdict with stable replay hash
|
||||
- [ ] Auditors can replay locally and get identical results
|
||||
|
||||
---
|
||||
|
||||
## Technical Specifications
|
||||
|
||||
### API Contracts
|
||||
|
||||
```yaml
|
||||
# GET /api/v1/lineage/{artifactDigest}
|
||||
LineageGraphResponse:
|
||||
artifact: string
|
||||
nodes:
|
||||
- id: string (version_id)
|
||||
digest: string
|
||||
createdAt: string (ISO-8601)
|
||||
sequenceNumber: int
|
||||
source: string
|
||||
badges:
|
||||
newVulns: int
|
||||
resolvedVulns: int
|
||||
signatureStatus: "valid" | "invalid" | "unsigned"
|
||||
edges:
|
||||
- from: string
|
||||
to: string
|
||||
relationship: "parent" | "build" | "base"
|
||||
|
||||
# GET /api/v1/lineage/diff?from={digest}&to={digest}
|
||||
LineageDiffResponse:
|
||||
sbomDiff:
|
||||
added: ComponentDiff[]
|
||||
removed: ComponentDiff[]
|
||||
versionChanged: VersionChange[]
|
||||
vexDiff:
|
||||
- cve: string
|
||||
fromStatus: string
|
||||
toStatus: string
|
||||
reason: string
|
||||
evidenceLink: string
|
||||
reachabilityDiff:
|
||||
- cve: string
|
||||
fromStatus: string
|
||||
toStatus: string
|
||||
addedPaths: int
|
||||
removedPaths: int
|
||||
replayHash: string
|
||||
|
||||
# POST /api/v1/lineage/export
|
||||
LineageExportRequest:
|
||||
artifactDigest: string
|
||||
includeAttestations: bool
|
||||
sign: bool
|
||||
|
||||
LineageExportResponse:
|
||||
downloadUrl: string
|
||||
bundleDigest: string
|
||||
expiresAt: string
|
||||
```
|
||||
|
||||
### Database Schema
|
||||
|
||||
```sql
|
||||
-- New tables for SBOM Lineage Graph
|
||||
|
||||
-- Persistent lineage edges
|
||||
CREATE TABLE sbom_lineage_edges (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
parent_digest TEXT NOT NULL,
|
||||
child_digest TEXT NOT NULL,
|
||||
relationship TEXT NOT NULL CHECK (relationship IN ('parent', 'build', 'base')),
|
||||
tenant_id UUID NOT NULL,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
UNIQUE (parent_digest, child_digest, tenant_id)
|
||||
);
|
||||
|
||||
CREATE INDEX idx_lineage_edges_parent ON sbom_lineage_edges(parent_digest, tenant_id);
|
||||
CREATE INDEX idx_lineage_edges_child ON sbom_lineage_edges(child_digest, tenant_id);
|
||||
|
||||
-- VEX delta tracking
|
||||
CREATE TABLE vex_deltas (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
from_artifact_digest TEXT NOT NULL,
|
||||
to_artifact_digest TEXT NOT NULL,
|
||||
cve TEXT NOT NULL,
|
||||
from_status TEXT NOT NULL,
|
||||
to_status TEXT NOT NULL,
|
||||
rationale JSONB,
|
||||
replay_hash TEXT NOT NULL,
|
||||
attestation_digest TEXT,
|
||||
tenant_id UUID NOT NULL,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
UNIQUE (from_artifact_digest, to_artifact_digest, cve, tenant_id)
|
||||
);
|
||||
|
||||
CREATE INDEX idx_vex_deltas_artifact ON vex_deltas(to_artifact_digest, tenant_id);
|
||||
CREATE INDEX idx_vex_deltas_cve ON vex_deltas(cve, tenant_id);
|
||||
|
||||
-- SBOM-verdict linking
|
||||
CREATE TABLE sbom_verdict_links (
|
||||
sbom_version_id UUID NOT NULL,
|
||||
cve TEXT NOT NULL,
|
||||
consensus_projection_id UUID NOT NULL,
|
||||
verdict_status TEXT NOT NULL,
|
||||
confidence_score DECIMAL(5,4) NOT NULL,
|
||||
tenant_id UUID NOT NULL,
|
||||
linked_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
PRIMARY KEY (sbom_version_id, cve, tenant_id)
|
||||
);
|
||||
|
||||
CREATE INDEX idx_verdict_links_cve ON sbom_verdict_links(cve, tenant_id);
|
||||
|
||||
-- Migrate VexLens consensus to Postgres
|
||||
CREATE TABLE vex_consensus_projections (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
vulnerability_id TEXT NOT NULL,
|
||||
product_key TEXT NOT NULL,
|
||||
tenant_id UUID NOT NULL,
|
||||
status TEXT NOT NULL,
|
||||
confidence_score DECIMAL(5,4) NOT NULL,
|
||||
outcome TEXT NOT NULL,
|
||||
statement_count INT NOT NULL,
|
||||
conflict_count INT NOT NULL,
|
||||
computed_at TIMESTAMPTZ NOT NULL,
|
||||
stored_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
previous_projection_id UUID REFERENCES vex_consensus_projections(id),
|
||||
status_changed BOOLEAN NOT NULL DEFAULT FALSE
|
||||
);
|
||||
|
||||
CREATE UNIQUE INDEX idx_consensus_unique ON vex_consensus_projections(
|
||||
tenant_id, vulnerability_id, product_key, computed_at
|
||||
);
|
||||
CREATE INDEX idx_consensus_status_changed ON vex_consensus_projections(
|
||||
tenant_id, status_changed, computed_at DESC
|
||||
) WHERE status_changed = TRUE;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|------|------------|--------|------------|
|
||||
| OCI manifest parsing complexity | Medium | Medium | Use existing `go-containerregistry` patterns; fallback to layer heuristics |
|
||||
| VexLens migration data loss | Low | High | Dual-write during transition; feature flag rollout |
|
||||
| Frontend performance (large graphs) | Medium | Medium | Virtual scrolling, canvas rendering, pagination (max 100 nodes) |
|
||||
| Replay hash collision | Very Low | High | Use SHA-256 with all inputs; include timestamp in hash |
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
The SBOM Lineage Graph advisory is **strongly recommended** for implementation. It:
|
||||
|
||||
1. **Leverages existing infrastructure** - SbomService ledger, VexLens consensus, Attestor signing, Evidence export
|
||||
2. **Fills a clear market gap** - No competitor offers hover-to-proof UX with signed deltas
|
||||
3. **Aligns with core differentiators** - Reproducibility, VEX-first, offline-capable
|
||||
4. **Provides immediate auditor value** - "Show me the proof" becomes explorable
|
||||
|
||||
The 2-sprint plan (4 weeks) delivers a demoable MVP with the core value proposition:
|
||||
- **Sprint 1:** Lineage graph + hover cards (foundation)
|
||||
- **Sprint 2:** Compare mode + signed exports (audit value)
|
||||
|
||||
---
|
||||
|
||||
*Generated by Claude Code analysis on 2025-12-28*
|
||||
Reference in New Issue
Block a user