git.stella-ops.org/docs/forensics/timeline.md

Timeline Forensics Guide

Imposed rule: Timeline is append-only; events may not be deleted or rewritten. Redactions require creating a compensating redaction_notice event that references the original ULID.

The Timeline Indexer service aggregates structured events (scanner runs, policy verdicts, runtime posture, evidence locker activity) so operators can audit changes over time. This guide summarises the event schema, query surfaces, and integration points.

1. Event Model

Field	Description
event_id	ULID identifying the event.
tenant	Tenant scope.
timestamp	UTC ISO-8601 time the event occurred.
category	Logical grouping (scanner, policy, runtime, evidence).
details	JSON payload describing the event; contract defined per producer.
trace_id	Optional distributed trace correlation ID.

Events are stored append-only with tenant-specific partitions. Producers include Scanner WebService, Policy Engine, Zastava Observer, Evidence Locker, and Notify.

Event kinds (normative)

• scan.completed – scanner job finished; includes SBOM digest, findings counts, determinism score.
• policy.verdict – policy engine decision with overlay cache version and allow/deny rationale.
• attestation.verified – attestation verification result with Rekor UUID and bundle digest.
• evidence.ingested – Evidence Locker write with WORM vault identifier.
• notify.sent – outbound notification with target channel and template id.
• runtime.alert – runtime enforcement or observation event from Zastava Observer.
• redaction_notice – compensating entry when data is logically withdrawn; must include supersedes ULID.

2. APIs

• GET /api/v1/timeline/events – paginated event stream with filters (tenant, category, time window, correlation IDs).
• GET /api/v1/timeline/events/{id} – fetch single event payload.
• GET /api/v1/timeline/export – NDJSON export for offline review.

API headers: X-Stella-Tenant, optional X-Stella-TraceId, and If-None-Match for cache revalidation.

3. Query Tips

• Use category + trace_id to follow a scan-to-policy-to-notification flow.
• Combine tenant and timestamp filters for SLA audits.
• CLI command stella timeline list mirrors the API for automation.
• For WORM verification, filter category=evidence and join on Evidence Locker bundle digest.
• Use category=attestation.verified and details.rekor_uuid to reconcile transparency proofs.

Example queries

# Recent scan → policy → notify chain for a digest
stella timeline list --tenant acme --category scan.completed --subject sha256:abc... --limit 5
stella timeline list --tenant acme --category policy.verdict --trace-id <trace>
stella timeline list --tenant acme --category notify.sent --trace-id <trace>

# Export window for audit
curl -H "X-Stella-Tenant: acme" \
  "https://console.example/api/v1/timeline/export?from=2025-11-01T00:00:00Z&to=2025-11-02T00:00:00Z" \
  -o timeline-2025-11-01.ndjson

4. Integration

• Evidence Locker attaches evidence bundle digests; the console links from timeline to evidence viewer.
• Notifier creates acknowledgement events for incident workflows.
• Offline kits package timeline exports for compliance reviews.

Retention: events are retained per-tenant for at least timeline.retention_days (default 400 days) and replicated to cold storage weekly. Index rebuilds must preserve ordering and ULIDs.

Privacy/PII: producers must redact PII before emission; once emitted, redactions occur via redaction_notice only.

5. References

• docs/modules/telemetry/architecture.md
• docs/modules/zastava/architecture.md
• docs/modules/export-center/architecture.md
• src/TimelineIndexer/StellaOps.TimelineIndexer