git.stella-ops.org/docs-archived/implplan/4300_explainable_triage_gap_analysis.md

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:

{
  "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