git.stella-ops.org/docs/modules/scanner/design/runtime-alignment-scanner-zastava.md

Runtime Alignment (Scanner ↔ Zastava) · SCANNER-ENG-0014 (2025-12-08)

Objective

Align Kubernetes/VM target coverage between Scanner and Zastava so runtime signals, job orchestration, and evidence exports stay consistent across clusters and on-prem installs.

Scope

• Scanner: Worker runtime capture (EntryTrace), Surface.Env/FS detectors, analyzer job manifests, and policy predicates that rely on runtime/container metadata.
• Zastava: runtime observation feeds (system call/ebpf), workload labeling, and admission hooks.

Alignment Plan

1. Workload identity contract
   • Standardize labels/annotations for scan jobs and Zastava monitors:
     • stellaops.workload/id, tenant, project, component, channel.
     • Container image digest required; tag optional.
   • Shared manifest snippet lives in deploy/helm/stellaops overlays; reuse in job templates.
2. Runtime evidence channels
   • Scanner EntryTrace publishes runtime.events with fields: workloadId, namespace, node, edgeType (syscall/net/fs), timestamp (UTC, ISO-8601), code_id (when available).
   • Zastava observers mirror the same schema on zastava.runtime.events; controller stitches by workloadId and imageDigest.
   • Determinism: sort edge batches by (workloadId, timestamp, edgeType).
3. Kubernetes defaults
   • Namespace allowlist scanner-runtime/zastava-runtime; service accounts share RBAC for pods/exec, pods/log, nodes/proxy (read-only).
   • Feature flags: scanner.runtime.capture.enabled (default false), zastava.attach.enabled (default false) to keep sealed-mode/offline safe.
4. VM/bare-metal
   • Use node agent mode: Scanner jobs emit host metadata hostId, osRelease; Zastava tailers tag events with same ids.
   • Shared log shipper config uses file socket paths under /var/log/stellaops/runtime/*.ndjson.
5. Evidence export
   • Export Center receives combined runtime bundle with two streams: scanner.entrytrace.ndjson, zastava.runtime.ndjson; manifest includes hash of each and workload identity table.
   • Offline kit: bundle path offline/runtime/<runId>/; deterministic manifests/hashes.
6. SLOs & alerts
   • Target: runtime event lag < 30s P95; drop rate < 0.5%.
   • Alerts wired via Prometheus: stella_runtime_events_lag_seconds, stella_runtime_events_dropped_total.

Deliverables

• Update job/observer templates (Helm/Compose) to include shared labels and feature flags.
• Documented schema alignment (this note) referenced from sprint log.
• Tests: determinism checks on merged runtime bundle; label presence asserted in integration harness.

Next Steps

• Wire labels/flags into deploy/helm/stellaops templates and Scanner Worker job manifests.
• Add integration test to ensure EntryTrace and Zastava events with same workload id are coalesced without reordering.