stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
05833e0af21a44cf323e627808141fce0d84ca2f
git.stella-ops.org/docs-archived/product-advisories/23-Dec-2026 - Implementation Summary - Competitor Gap Closure.md
master d0a7b88398 move docs/**/archived/* to docs-archived/**/*
2026-01-05 16:02:11 +02:00

16 KiB
Raw Blame History

Implementation Summary: Competitor Scanner UI Gap Closure

Date: 2025-12-23 Status: Planning Complete, Implementation Ready Related Advisory: 23-Dec-2026 - Competitor Scanner UI Breakdown.md

Executive Summary

This document summarizes the comprehensive planning and design work completed to close competitive gaps identified in the "Competitor Scanner UI Breakdown" advisory. We've created 5 sprint plans, 2 JSON schemas, and 2 comprehensive documentation guides that establish Stella Ops differentiators against Snyk Container, Anchore Enterprise, and Prisma Cloud.

Gap Analysis Results

Gaps Identified Against src/**/*.md

Feature Advisory Source Stella Ops Status Priority Artifacts Created
Signed Delta-Verdicts N/A (differentiator) Foundation exists, integration missing HIGH Sprint, Schema, Docs
Replayable Evidence Packs N/A (differentiator) Primitives exist, bundle missing HIGH Sprint, Schema, Docs
Reachability Proof Panels N/A (differentiator) Backend exists, UI missing MEDIUM Sprint
UI Vulnerability Annotation Anchore Enterprise API exists, UI workflow missing MEDIUM Sprint
Base Image Detection/Recs Snyk Container Missing MEDIUM Sprint
Admin Audit Trail UI Prisma Cloud Partial (decisions only) LOW Deferred

Deliverables Created

Sprint Plans (5 Total)

Sprint ID Title Priority Components Status
SPRINT_3000_0100_0001 Signed Delta-Verdicts HIGH Policy Engine, Attestor, Evidence Locker Planning
SPRINT_3000_0100_0002 Replayable Evidence Packs HIGH Evidence Locker, Policy Engine, Replay Planning
SPRINT_4000_0100_0001 Reachability Proof Panels UI MEDIUM Web (Angular), Policy APIs Planning
SPRINT_4000_0100_0002 UI-Driven Vulnerability Annotation MEDIUM Web, Findings Ledger, Excititor Planning
SPRINT_3000_0100_0003 Base Image Detection & Recommendations MEDIUM Scanner, Policy Engine Planning

Location: docs/implplan/SPRINT_3000_0100_*.md, docs/implplan/SPRINT_4000_0100_*.md

JSON Schemas (2 Total)

Schema URI Purpose Status
Policy Verdict Predicate https://stellaops.dev/predicates/policy-verdict@v1 DSSE predicate for signed verdicts Complete
Evidence Pack Manifest https://stellaops.dev/evidence-pack@v1 Replayable bundle manifest Complete

Location: docs/schemas/stellaops-policy-verdict.v1.schema.json, docs/schemas/stellaops-evidence-pack.v1.schema.json

Documentation (2 Comprehensive Guides)

Document Scope Status
Policy Verdict Attestations API, CLI, implementation guide, troubleshooting Complete
Evidence Pack Schema Pack format, replay workflow, air-gap transfer Complete

Competitive Differentiation Matrix

Stella Ops vs Competitors

Feature Snyk Anchore Prisma Stella Ops
Signed Verdicts ❌ No ❌ No ❌ No ✅ DSSE-wrapped, Rekor-anchored
Evidence Packs ❌ Separate exports ❌ Separate exports ❌ Separate exports ✅ Single signed bundle
Replayable Policy ❌ No ❌ No ❌ No ✅ Deterministic re-evaluation
Proof Visualization ℹ️ Basic ℹ️ Basic ℹ️ Basic ✅ Cryptographic verification UI
VEX Auto-Generation ❌ Manual ⚠️ UI annotation ❌ Manual ✅ Smart-Diff auto-emit + approval
Base Image Detection ✅ Yes ❌ No ⚠️ Limited 🚧 Planned (Sprint 3000_0100_0003)
Custom Base Recs ✅ Yes ❌ No ❌ No 🚧 Policy-driven from internal registry
Admin Audit Trail ⚠️ Limited ⚠️ Limited ✅ Yes ⚠️ Decisions only (future enhancement)
Offline Support ❌ Cloud-only ⚠️ Limited ❌ Cloud-only ✅ Air-gap first

Legend:

  • ✅ Full support
  • ⚠️ Partial support
  • ℹ️ Basic/limited
  • ❌ Not supported
  • 🚧 Planned/in progress

Architecture Overview

Signed Delta-Verdicts Flow

Policy Engine Evaluation
    ↓
PolicyExplainTrace (per finding)
    ↓
VerdictPredicateBuilder
    ↓
VerdictAttestation Request → Attestor Service
    ↓
DSSE Signing + Optional Rekor Anchoring
    ↓
Evidence Locker Storage (PostgreSQL + Object Store)
    ↓
API: GET /api/v1/verdicts/{verdictId}

Key Differentiators:

  • Cryptographic Binding: Each verdict cryptographically signed, tamper-evident
  • Granular Attestations: One attestation per finding (not batch)
  • Transparency Option: Rekor anchoring for public auditability
  • Offline Verification: Signature verification without network

Replayable Evidence Packs Flow

Policy Run Completion
    ↓
Pack Assembly Trigger
    ↓
Collect: Policy + SBOMs + Advisories + VEX + Verdicts + Reachability
    ↓
Generate Manifest (content index + determinism hash)
    ↓
Sign Manifest (DSSE)
    ↓
Compress to Tarball (.tar.gz)
    ↓
Store in Object Store + Index in PostgreSQL
    ↓
Download → Transfer → Replay on Any Environment

Key Differentiators:

  • Complete Context: Single bundle contains all evaluation inputs
  • Deterministic Replay: Bit-for-bit reproducible verdicts
  • Queryable Offline: Inspect without external APIs
  • Air-Gap Transfer: Sign once, verify anywhere

Implementation Roadmap

Phase 1: HIGH Priority (Weeks 1-4)

SPRINT_3000_0100_0001 — Signed Delta-Verdicts

Week 1-2:

  • Implement VerdictPredicateBuilder in Policy Engine
  • Wire Policy Engine → Attestor integration
  • Implement VerdictAttestationHandler in Attestor
  • Evidence Locker storage schema + API endpoints

Week 3-4:

  • CLI commands (stella verdict get/verify/list)
  • Integration tests (Policy Run → Verdict Attestation → Retrieval → Verification)
  • Rekor anchoring integration (optional)
  • Documentation finalization

SPRINT_3000_0100_0002 — Replayable Evidence Packs

Week 1-2:

  • Implement EvidencePackAssembler in Evidence Locker
  • Pack assembly workflow (collect artifacts, generate manifest, sign, compress)
  • Pack storage (object store + PostgreSQL index)
  • API endpoints (POST /runs/{id}/evidence-pack, GET /packs/{id}, etc.)

Week 3-4:

  • Implement ReplayService in Policy Engine
  • Replay workflow (extract → deserialize → re-evaluate → compare)
  • CLI commands (stella pack create/download/inspect/verify/replay)
  • Integration tests (determinism validation, air-gap transfer)

Success Metrics:

  • ✅ Every policy run produces signed verdicts
  • ✅ Evidence packs replay with 100% determinism
  • ✅ CLI can verify signatures offline
  • ✅ API endpoints documented and tested

Phase 2: MEDIUM Priority (Weeks 5-8)

SPRINT_4000_0100_0001 — Reachability Proof Panels UI

Dependencies: SPRINT_3000_0100_0001 (verdict attestation API)

  • Design UI mockups for proof panel
  • Implement VerdictProofPanelComponent (Angular)
  • Integrate with verdict API + signature verification
  • Render evidence chain (advisory → SBOM → VEX → reachability → verdict)
  • Storybook stories + E2E tests

SPRINT_4000_0100_0002 — UI-Driven Vulnerability Annotation

  • Define vulnerability state machine in Findings Ledger
  • Implement triage dashboard UI (Angular)
  • VEX candidate review/approval workflow
  • API: PATCH /findings/{id}/state, POST /vex-candidates/{id}/approve
  • E2E tests for annotation workflow

SPRINT_3000_0100_0003 — Base Image Detection & Recommendations

  • Create StellaOps.Scanner.BaseImage library
  • Implement Dockerfile parser + OCI manifest analyzer
  • Build approved image registry schema
  • Recommendation engine logic
  • API endpoints + CLI commands

Success Metrics:

  • ✅ Proof panel visualizes verdict evidence chain
  • ✅ Triage dashboard enables UI-driven VEX approval
  • ✅ Base image recommendations from internal registry

Phase 3: Enhancements (Weeks 9+)

  • Admin audit trail UI (comprehensive activity logging)
  • Pack retention policies + automated archiving
  • Batch verdict signing optimization
  • Evidence pack incremental updates
  • Policy replay diff visualization

Technical Specifications

Verdict Attestation Predicate

Type: https://stellaops.dev/predicates/policy-verdict@v1

Key Fields:

  • verdict.status: passed | warned | blocked | quieted | ignored
  • ruleChain: Ordered policy rule execution trace
  • evidence: Advisory, VEX, reachability, SBOM evidence with digests
  • reachability.status: confirmed | likely | present | unreachable | unknown
  • metadata.determinismHash: SHA256 of verdict computation

Signing: DSSE envelope, Ed25519/ECDSA/RSA-PSS

Storage: PostgreSQL (verdict_attestations table) + optional Rekor

Evidence Pack Manifest

Type: https://stellaops.dev/evidence-pack@v1

Structure:

  • contents.policy: Policy definition + run metadata
  • contents.sbom: SPDX/CycloneDX SBOMs
  • contents.advisories: Timestamped CVE snapshots
  • contents.vex: OpenVEX statements
  • contents.verdicts: DSSE-wrapped verdict attestations
  • contents.reachability: Drift + slice analysis

Determinism: determinismHash = SHA256(sorted content digests)

Signing: Manifest signature covers all content digests

Format: Compressed tarball (.tar.gz)

API Summary

Verdict Attestation APIs

Method Endpoint Purpose
GET /api/v1/verdicts/{verdictId} Retrieve verdict attestation (DSSE envelope)
GET /api/v1/runs/{runId}/verdicts List verdicts for policy run (filters: status, severity)
POST /api/v1/verdicts/{verdictId}/verify Verify signature + optional Rekor inclusion proof

Evidence Pack APIs

Method Endpoint Purpose
POST /api/v1/runs/{runId}/evidence-pack Create evidence pack for policy run
GET /api/v1/evidence-packs/{packId} Download pack tarball
GET /api/v1/evidence-packs/{packId}/manifest Inspect manifest (no download)
POST /api/v1/evidence-packs/{packId}/replay Replay policy evaluation from pack
POST /api/v1/evidence-packs/{packId}/verify Verify pack signature + content integrity

CLI Summary

Verdict Commands

stella verdict get <verdictId>                          # Retrieve verdict
stella verdict verify <verdict.json> --public-key <key> # Verify signature (offline)
stella verdict list --run <runId> --status blocked      # List verdicts for run
stella verdict download <verdictId> --output <file>     # Download DSSE envelope

Evidence Pack Commands

stella pack create <runId>                              # Create pack
stella pack download <packId> --output <file>           # Download pack tarball
stella pack inspect <pack.tar.gz>                       # Display manifest + stats
stella pack list <pack.tar.gz>                          # List all files in pack
stella pack export <pack.tar.gz> --artifact <path>      # Extract single artifact
stella pack verify <pack.tar.gz>                        # Verify signature + integrity
stella pack replay <pack.tar.gz>                        # Replay policy evaluation

Testing Strategy

Unit Tests

  • Verdict predicate builder (canonical JSON, determinism)
  • Evidence pack assembler (manifest generation, determinism hash)
  • Replay service (deserialization, comparison logic)
  • Schema validation (JSON schema compliance)

Integration Tests

  • End-to-end: Policy Run → Verdict Attestation → Storage → Retrieval → Verification
  • End-to-end: Pack Assembly → Storage → Download → Replay → Determinism Validation
  • Cross-environment: Create pack on env A, replay on env B (air-gap scenario)
  • Signature verification (offline, no network)

Performance Tests

  • Verdict attestation throughput (1M verdicts/hour target)
  • Pack assembly time (< 2min for 10K findings)
  • Replay time (< 60s for 10K verdicts)
  • Storage scaling (100K packs, query performance)

Security Considerations

Cryptographic Guarantees

  • Verdict Attestations: DSSE-signed, tamper-evident, optional Rekor transparency
  • Evidence Packs: Manifest signature, per-file digests, determinism hash
  • Key Management: KMS, CryptoPro (GOST), offline signing ceremonies
  • Verification: Offline-capable, no network required

Access Control

  • RBAC Scopes:

    • policy:verdict:read — View verdict attestations
    • policy:pack:create — Create evidence packs
    • policy:pack:read — Download evidence packs
    • policy:replay — Replay policy evaluations

  • Tenant Isolation: All artifacts scoped by tenantId, cross-tenant queries blocked

Audit Trail

  • All verdict retrievals logged with actor, timestamp, tenant
  • Pack creation/download/replay logged for compliance
  • Signature verification failures alerted

Determinism Validation

Verdict Determinism

Inputs:

  • Policy definition (P-7 v4)
  • SBOM (sbom:S-42)
  • Advisory snapshot (at cursor timestamp)
  • VEX snapshot (at cursor timestamp)
  • Environment context

Output: Verdict with determinismHash = SHA256(sorted evidence digests)

Validation: Re-evaluate with identical inputs → same determinismHash

Pack Replay Determinism

Inputs: Evidence pack manifest (all artifacts bundled)

Output: Replay verdicts

Validation: Compare replay verdicts to original verdicts:

  • Count match: 234 original, 234 replay ✓
  • Status match: All verdicts have identical status ✓
  • Hash match: All determinismHash values identical ✓

Next Steps

Immediate Actions (This Week)

  1. Review & Approve: Technical designs for SPRINT_3000_0100_0001 and SPRINT_3000_0100_0002
  2. Kickoff: SPRINT_3000_0100_0001 (Signed Delta-Verdicts) implementation
  3. Code Generation: Create C# models from JSON schemas
  4. Database Migrations: Prepare PostgreSQL schema for verdict_attestations and evidence_packs tables

Week 1 Milestones

  • VerdictPredicateBuilder implemented with unit tests
  • Policy Engine → Attestor integration wired (feature-flagged)
  • VerdictAttestationHandler accepts and signs predicates
  • Evidence Locker storage + API endpoints (basic CRUD)

Month 1 Goal

  • ✅ Every policy run produces signed verdict attestations
  • ✅ CLI can retrieve and verify verdicts offline
  • ✅ Evidence packs can be created for policy runs
  • ✅ Integration tests pass with 100% determinism

Success Metrics

Adoption Metrics

  • Verdict Attestations: 100% of policy runs emit signed verdicts
  • Evidence Pack Usage: 10+ packs created per day per tenant
  • Replay Success Rate: 99%+ determinism verification

Performance Metrics

  • Verdict Attestation Latency: < 100ms per verdict
  • Pack Assembly Time: < 2min for 10K findings
  • Replay Time: < 60s for 10K verdicts
  • API Latency: p95 < 500ms for verdict/pack retrieval

Quality Metrics

  • Test Coverage: > 90% for attestation + pack code
  • Schema Compliance: 100% of artifacts validate against JSON schemas
  • Determinism Rate: 100% replay verdicts match original

References

  • Sprint Plans: docs/implplan/SPRINT_3000_0100_*.md, docs/implplan/SPRINT_4000_0100_*.md
  • Schemas: docs/schemas/stellaops-policy-verdict.v1.schema.json, docs/schemas/stellaops-evidence-pack.v1.schema.json
  • Documentation: docs/policy/verdict-attestations.md, docs/evidence-locker/evidence-pack-schema.md
  • Advisory: docs/product-advisories/23-Dec-2026 - Competitor Scanner UI Breakdown.md