# 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](./23-Dec-2026%20-%20Competitor%20Scanner%20UI%20Breakdown.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](../policy/verdict-attestations.md)** | API, CLI, implementation guide, troubleshooting | Complete |
| **[Evidence Pack Schema](../evidence-locker/evidence-pack-schema.md)** | 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

```bash
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

```bash
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`