git.stella-ops.org/docs/modules/platform/explainable-triage-implementation-plan.md

Explainable Triage Workflows - Implementation Plan

Executive Summary

This document outlines the implementation plan for delivering Explainable Triage Workflows as defined in the product advisory dated 21-Dec-2025. The capability set enables vulnerability-first, policy-backed, reachability-informed verdicts with full explainability and auditability.

Vision

Every vulnerability finding must resolve to a policy-backed, reachability-informed, runtime-corroborated verdict that is exportable as one signed attestation attached to the built artifact.

Current State Analysis

Already Implemented (75%)

Capability	Implementation	Completeness
Reachability analysis	10 language analyzers, binary, runtime	95%
VEX processing	OpenVEX, CSAF, CycloneDX with lattice	90%
Explainability	ExplainTrace with rule steps	95%
Evidence generation	Path witnesses, rich graphs	90%
Audit trails	Immutable ledger with chain integrity	85%
Policy gates	4-stage gate system	95%
Attestations	7 predicate types with DSSE	90%
Runtime capture	eBPF, dyld, ETW	85%

Already Planned (15%)

Capability	Sprint	Status
Risk Verdict Attestation	SPRINT_4100_0003_0001	TODO
OCI Attachment	SPRINT_4100_0003_0002	TODO
Counterfactuals	SPRINT_4200_0002_0005	TODO
Replay Engine	SPRINT_4100_0002_0002	TODO
Knowledge Snapshot	SPRINT_4100_0002_0001	TODO
Audit Pack Export	SPRINT_5100_0006_0001	TODO
Unknown Budgets	SPRINT_4100_0001_0002	TODO

Net New Gaps (10%)

Gap	Sprint	Story Points
Unified Confidence Model	7000.0002.0001	13
Vulnerability-First UX API	7000.0002.0002	13
Evidence Graph API	7000.0003.0001	8
Reachability Mini-Map	7000.0003.0002	5
Runtime Timeline	7000.0003.0003	5
Progressive Fidelity	7000.0004.0001	13
Evidence Size Budgets	7000.0004.0002	8
Quality KPIs	7000.0005.0001	8

Implementation Roadmap

Phase 1: Foundation (Existing + New)

Objective: Establish core verdict and confidence infrastructure.

Sprints:

• SPRINT_4100_0003_0001: Risk Verdict Attestation
• SPRINT_4100_0002_0001: Knowledge Snapshot Manifest
• SPRINT_7000_0002_0001: Unified Confidence Model
• SPRINT_7000_0004_0001: Progressive Fidelity (parallel)
• SPRINT_7000_0004_0002: Evidence Budgets (parallel)

Key Deliverables:

• RiskVerdictAttestation model with PASS/FAIL/PASS_WITH_EXCEPTIONS/INDETERMINATE
• ConfidenceScore with 5-factor breakdown
• FidelityLevel enum with Quick/Standard/Deep modes
• EvidenceBudget with retention tiers

Phase 2: UX Layer

Objective: Deliver vulnerability-first presentation layer.

Sprints:

• SPRINT_7000_0002_0002: Vulnerability-First UX API

Key Deliverables:

• FindingSummaryResponse with verdict chip, confidence, one-liner
• ProofBadges (Reachability, Runtime, Policy, Provenance)
• GET /api/v1/findings list endpoint
• GET /api/v1/findings/{id}/summary detail endpoint

Phase 3: Visualization APIs

Objective: Enable evidence exploration and click-through.

Sprints (parallelizable):

• SPRINT_7000_0003_0001: Evidence Graph API
• SPRINT_7000_0003_0002: Reachability Mini-Map API
• SPRINT_7000_0003_0003: Runtime Timeline API

Key Deliverables:

• GET /api/v1/findings/{id}/evidence-graph
• GET /api/v1/findings/{id}/reachability-map
• GET /api/v1/findings/{id}/runtime-timeline

Phase 4: Metrics & Observability

Objective: Track quality KPIs for continuous improvement.

Sprints:

• SPRINT_7000_0005_0001: Quality KPIs Tracking

Key Deliverables:

• TriageQualityKpis model
• GET /api/v1/metrics/kpis dashboard endpoint
• Trend tracking over time

Architecture Changes

New Libraries

src/
├── Policy/
│   └── __Libraries/
│       └── StellaOps.Policy.Confidence/     # NEW: Confidence model
│           ├── Models/
│           ├── Services/
│           └── Configuration/
├── Scanner/
│   └── __Libraries/
│       └── StellaOps.Scanner.Orchestration/ # NEW: Fidelity orchestration
│           └── Fidelity/
├── Findings/
│   └── StellaOps.Findings.WebService/       # EXTEND: UX APIs
│       ├── Contracts/
│       ├── Services/
│       └── Endpoints/
├── Evidence/                                 # NEW: Evidence management
│   └── StellaOps.Evidence/
│       ├── Budgets/
│       └── Retention/
└── Metrics/                                  # NEW: KPI tracking
    └── StellaOps.Metrics/
        └── Kpi/

Database Changes

Table	Purpose
confidence_factors	Store factor breakdown per verdict
evidence_items	Track evidence with size and tier
kpi_counters	Real-time KPI counters
kpi_snapshots	Daily KPI snapshots

API Surface

Endpoint	Method	Purpose
/api/v1/findings	GET	List findings with summaries
/api/v1/findings/{id}/summary	GET	Detailed finding summary
/api/v1/findings/{id}/evidence-graph	GET	Evidence graph
/api/v1/findings/{id}/reachability-map	GET	Reachability mini-map
/api/v1/findings/{id}/runtime-timeline	GET	Runtime timeline
/api/v1/scan/analyze	POST	Analyze with fidelity level
/api/v1/scan/findings/{id}/upgrade	POST	Upgrade fidelity
/api/v1/metrics/kpis	GET	Quality KPIs

Non-Negotiables

From the advisory:

1. Vulnerability-first UX: Users start from CVE/finding and immediately see applicability, reachability, runtime corroboration, and policy rationale.

2. Single canonical verdict artifact: One built-in, signed verdict attestation per subject (OCI digest), replayable.

3. Deterministic evidence: Evidence objects are content-hashed and versioned.

4. Unknowns are first-class: "Unknown reachability/runtime/config" is not hidden; it is budgeted and policy-controlled.

Quality KPIs

KPI	Target	Measurement
% non-UNKNOWN reachability	>80%	Weekly
% runtime corroboration	>50% (where sensor deployed)	Weekly
Explainability completeness	>95%	Weekly
Replay success rate	>99%	Weekly
Median time to verdict	<5 min	Daily

Risk Management

Risk	Impact	Mitigation
Confidence model complexity	High	Start simple (3 factors), iterate
Deep analysis performance	Medium	Progressive fidelity with timeouts
Evidence storage growth	Medium	Budget enforcement + tier pruning
API backward compatibility	Low	Versioned endpoints

Definition of Done

Per advisory, a release is "done" only if:

• Build produces OCI artifact with attached signed verdict attestation
• Each verdict is explainable (reason steps + proof pointers)
• Reachability evidence stored as reproducible subgraph (or explicitly UNKNOWN with reason)
• Replay verification reproduces same verdict with pinned inputs
• UX starts from vulnerabilities and links directly to proofs and audit export

References

• Advisory: docs/product-advisories/archived/21-Dec-2025 - Designing Explainable Triage Workflows.md
• Sprint Summary: docs/implplan/SPRINT_7000_SUMMARY.md
• Individual Sprints: docs/implplan/SPRINT_7000_*.md

Revision History

Date	Change	Author
2025-12-22	Initial implementation plan	Claude