# Gap Analysis: Explainable Triage and Proof-Linked Evidence

**Date:** 2025-12-22
**Advisory:** 18-Dec-2025 - Designing Explainable Triage and Proof-Linked Evidence
**Analyst:** Agent

---

## 1. Executive Summary

The advisory "Designing Explainable Triage and Proof-Linked Evidence" defines a comprehensive vision for making security triage **explainable** and approvals **provably evidence-linked**. This gap analysis compares the advisory requirements against the current StellaOps implementation.

**Key Finding:** ~85% of the advisory is already implemented through prior sprint work (3800, 3801, 4100, 4200 series). Six specific gaps remain, addressed by the SPRINT_4300 series.

---

## 2. Advisory Requirements Summary

### 2.1 Explainable Triage UX
- Every risk row shows: Score, CVE, service, package
- Expand panel shows: Path, Boundary, VEX, Last-seen, Actions
- Data contract for evidence retrieval

### 2.2 Evidence-Linked Approvals
- Chain: SBOM → VEX → Policy Decision
- in-toto/DSSE attestations with signatures
- Gate merges/deploys on chain validation

### 2.3 Backend Requirements
- `/findings/:id/evidence` endpoint
- `/approvals/:artifact/attestations` endpoint
- Proof bundles as content-addressed blobs
- DSSE envelopes for signatures

### 2.4 CLI/API
- `stella verify image:<digest> --require sbom,vex,decision`
- Signed summary return
- Non-zero exit for CI/CD gates

### 2.5 Invariants
- Artifact anchoring (no "latest tag" approvals)
- Evidence closure (decision refs exact evidence)
- Signature chain (DSSE, signed, verifiable)
- Staleness (last_seen, expires_at, TTL)

### 2.6 Metrics
- % attestation completeness (target ≥95%)
- TTFE (time-to-first-evidence, target ≤30s)
- Post-deploy reversions (target: zero)

---

## 3. Implementation Status

### 3.1 Fully Implemented (No Action Needed)

| Requirement | Implementation | Evidence |
|-------------|----------------|----------|
| **Triage DB Schema** | TriageDbContext with 8 entities | `src/Scanner/__Libraries/StellaOps.Scanner.Triage/` |
| **Evidence Bundle** | EvidenceBundle with 6 evidence types | `src/__Libraries/StellaOps.Evidence.Bundle/` |
| **VEX Decision Models** | OpenVEX output with x-stellaops-evidence | `src/Policy/StellaOps.Policy.Engine/Vex/` |
| **Score Explanation** | ScoreExplanationService, additive model | `src/Signals/StellaOps.Signals/Services/` |
| **Trust Lattice Engine** | K4 evaluation, claim aggregation | `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/` |
| **Boundary Extractors** | K8s, Gateway, IaC extractors | SPRINT_3800_0002_* (archived, DONE) |
| **Human Approval Attestation** | stella.ops/human-approval@v1 | SPRINT_3801_0001_0004 (DONE) |
| **Risk Verdict Attestation** | RiskVerdictAttestation, RvaBuilder | SPRINT_4100_0003_0001 (DONE) |
| **OCI Referrer Push** | OciPushClient, RvaOciPublisher | SPRINT_4100_0003_0002 (DONE) |
| **Approve Button UI** | ApprovalButtonComponent (624 lines) | SPRINT_4100_0005_0001 (DONE) |
| **Decision Recording** | DecisionService, replay tokens | `src/Findings/StellaOps.Findings.Ledger/` |
| **Policy Gates** | PolicyGateEvaluator, Pass/Block/Warn | `src/Policy/StellaOps.Policy.Engine/Gates/` |
| **Exception Evaluation** | ExceptionEvaluator, compensating controls | SPRINT_3900 series (DONE) |
| **TTFS Telemetry** | TtfsIngestionService | `src/Telemetry/StellaOps.Telemetry.Core/Triage/` |

### 3.2 Planned (In Progress)

| Requirement | Sprint | Status |
|-------------|--------|--------|
| Proof Chain Verification UI | SPRINT_4200_0001_0001 | TODO |

### 3.3 Gaps Identified

| ID | Gap | Advisory Section | Priority |
|----|-----|------------------|----------|
| G1 | CLI Attestation Chain Verify | CLI/API, Pipeline gate | HIGH |
| G2 | Evidence Privacy Controls | Evidence privacy | MEDIUM |
| G3 | Evidence TTL Strategy API | Staleness invariant | MEDIUM |
| G4 | Predicate Type JSON Schemas | Predicate types | LOW |
| G5 | Metrics Dashboard | Metrics | LOW |
| G6 | Findings Evidence API | Backend, Data contract | MEDIUM |

---

## 4. Gap Details

### G1: CLI Attestation Chain Verify Command

**Advisory Requirement:**
```
stella verify image:<digest> --require sbom,vex,decision
```
Returns signed summary; pipelines fail on non-zero.

**Current State:**
- `stella verify offline` exists for offline verification
- No image-based attestation chain verification
- No `--require` attestation type filtering

**Gap:** Need online image verification with attestation requirements.

**Resolution:** SPRINT_4300_0001_0001

---

### G2: Evidence Privacy Controls

**Advisory Requirement:**
> Store file hashes, symbol names, and line ranges (no raw source required). Gate raw source behind elevated permissions.

**Current State:**
- Evidence contains full details
- No redaction service
- No permission-based access control

**Gap:** Need redaction levels and permission checks.

**Resolution:** SPRINT_4300_0002_0001

---

### G3: Evidence TTL Strategy Enforcement

**Advisory Requirement:**
> SBOM: long TTL (weeks/months). Boundary: short TTL (hours/days). Reachability: medium TTL. Staleness behavior in policy.

**Current State:**
- TTL fields exist on evidence entities
- No enforcement in policy gate
- No staleness warnings

**Gap:** Need TTL enforcer service integrated with policy.

**Resolution:** SPRINT_4300_0002_0002

---

### G4: Predicate Type JSON Schemas

**Advisory Requirement:**
> Predicate types: stella/sbom@v1, stella/vex@v1, stella/reachability@v1, stella/boundary@v1, stella/policy-decision@v1, stella/human-approval@v1

**Current State:**
- C# models exist for all predicate types
- No formal JSON Schema definitions
- No schema validation on attestation creation

**Gap:** Need JSON schemas and validation.

**Resolution:** SPRINT_4300_0003_0001

---

### G5: Attestation Completeness Metrics

**Advisory Requirement:**
> Metrics: % changes with complete attestations (target ≥95%), TTFE (target ≤30s), Post-deploy reversions (trend to zero)

**Current State:**
- TTFS telemetry exists (time-to-first-skeleton)
- No attestation completeness ratio
- No reversion tracking
- No Grafana dashboard

**Gap:** Need full metrics suite and dashboard.

**Resolution:** SPRINT_4300_0003_0002

---

### G6: Findings Evidence API Endpoint

**Advisory Requirement:**
> Backend: add `/findings/:id/evidence` (returns the contract).

Contract:
```json
{
  "finding_id": "f-7b3c",
  "cve": "CVE-2024-12345",
  "component": {...},
  "reachable_path": [...],
  "entrypoint": {...},
  "vex": {...},
  "last_seen": "...",
  "attestation_refs": [...]
}
```

**Current State:**
- EvidenceCompositionService exists internally
- No REST endpoint exposing advisory contract
- Different internal response format

**Gap:** Need REST endpoint with advisory-compliant contract.

**Resolution:** SPRINT_4300_0001_0002

---

## 5. Coverage Matrix

| Advisory Section | Subsection | Implemented | Gap Sprint |
|------------------|------------|-------------|------------|
| Explainable Triage UX | Row (collapsed) | ✅ | — |
| | Expand panel | ✅ | — |
| | Data contract | ⚠️ | 4300.0001.0002 |
| Evidence-Linked Approvals | Chain exists | ✅ | — |
| | in-toto/DSSE | ✅ | — |
| | Gate merges | ✅ | — |
| Backend | /findings/:id/evidence | ❌ | 4300.0001.0002 |
| | /approvals/:artifact/attestations | ✅ | — |
| | Proof bundles | ✅ | — |
| CLI/API | stella verify image | ❌ | 4300.0001.0001 |
| Invariants | Artifact anchoring | ✅ | — |
| | Evidence closure | ✅ | — |
| | Signature chain | ✅ | — |
| | Staleness | ⚠️ | 4300.0002.0002 |
| Data Model | artifacts table | ✅ | — |
| | findings table | ✅ | — |
| | evidence table | ✅ | — |
| | attestations table | ✅ | — |
| | approvals table | ✅ | — |
| Evidence Types | Reachable path proof | ✅ | — |
| | Boundary proof | ✅ | — |
| | VEX status | ✅ | — |
| | Score explanation | ✅ | — |
| Predicate Types | stella/sbom@v1 | ⚠️ | 4300.0003.0001 |
| | stella/vex@v1 | ⚠️ | 4300.0003.0001 |
| | stella/reachability@v1 | ⚠️ | 4300.0003.0001 |
| | stella/boundary@v1 | ⚠️ | 4300.0003.0001 |
| | stella/policy-decision@v1 | ⚠️ | 4300.0003.0001 |
| | stella/human-approval@v1 | ⚠️ | 4300.0003.0001 |
| Policy Gate | OPA/Rego | ✅ | — |
| | Signed decision | ✅ | — |
| Approve Button | Disabled until valid | ✅ | — |
| | Creates approval attestation | ✅ | — |
| Verification | Shared verifier library | ✅ | — |
| Privacy | Redacted proofs | ❌ | 4300.0002.0001 |
| | Elevated permissions | ❌ | 4300.0002.0001 |
| TTL Strategy | Per-type TTLs | ⚠️ | 4300.0002.0002 |
| Metrics | % completeness | ❌ | 4300.0003.0002 |
| | TTFE | ⚠️ | 4300.0003.0002 |
| | Reversions | ❌ | 4300.0003.0002 |
| UI Components | Findings list | ✅ | — |
| | Evidence drawer | ⏳ | 4200.0001.0001 |
| | Proof bundle viewer | ⏳ | 4200.0001.0001 |

**Legend:** ✅ Implemented | ⚠️ Partial | ❌ Missing | ⏳ Planned

---

## 6. Effort Estimation

| Sprint | Effort | Team | Parallelizable |
|--------|--------|------|----------------|
| 4300.0001.0001 | M (2-3d) | CLI | Yes |
| 4300.0001.0002 | S (1-2d) | Scanner | Yes |
| 4300.0002.0001 | M (2-3d) | Scanner | Yes |
| 4300.0002.0002 | S (1-2d) | Policy | Yes |
| 4300.0003.0001 | S (1-2d) | Attestor | Yes |
| 4300.0003.0002 | M (2-3d) | Telemetry | Yes |

**Total:** 10-14 days (can complete in 1-2 weeks with parallel execution)

---

## 7. Recommendations

1. **Prioritize G1 (CLI Verify)** - This is the only HIGH priority gap and enables CI/CD integration.

2. **Bundle G2+G3** - Evidence privacy and TTL can share context in Scanner/Policy teams.

3. **Defer G4+G5** - Predicate schemas and metrics are LOW priority; can follow after core functionality.

4. **Leverage 4200.0001.0001** - Proof Chain UI sprint is already planned; ensure it consumes new evidence API.

---

## 8. Appendix: Prior Sprint References

| Sprint | Topic | Status |
|--------|-------|--------|
| 3800.0000.0000 | Explainable Triage Master | DONE |
| 3800.0002.0001 | RichGraph Boundary Extractor | DONE |
| 3800.0002.0002 | K8s Boundary Extractor | DONE |
| 3800.0003.0001 | Evidence API Endpoint | DONE |
| 3801.0001.0001 | Policy Decision Attestation | DONE |
| 3801.0001.0004 | Human Approval Attestation | DONE |
| 4100.0003.0001 | Risk Verdict Attestation | DONE |
| 4100.0003.0002 | OCI Referrer Push | DONE |
| 4100.0005.0001 | Approve Button UI | DONE |
| 4200.0001.0001 | Proof Chain Verification UI | TODO |

---

**Analysis Complete:** 2025-12-22