up

docs/modules/scanner/design/runtime-alignment-scanner-zastava.md

@@ -0,0 +1,40 @@
+# 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.