eBPF Micro-Witness Determinism Profile v1.0.0

Status: IMPLEMENTED
Version: 1.0.0
Effective: 2026-02-16
Owner: Signals Guild + Scanner Guild + Attestor Guild + Evidence Locker Guild
Sprint: docs-archived/implplan/SPRINT_20260216_001_Signals_ebpf_micro_witness_determinism_profile.md

1. Purpose

This profile defines the minimum deterministic contract for runtime eBPF "micro-witnesses" so replay yields the same symbolized result across distros/toolchains and in offline environments.

2. Contract Scope

Runtime collection and BTF selection (Signals).
Runtime witness payload schema and signing (Scanner).
DSSE and transparency evidence shape (Attestor).
Portable storage/export/indexing (Evidence Locker).

3. Runtime Loader Contract (BTF Selection)

3.1 Selection order (mandatory)

/sys/kernel/btf/vmlinux
configured full-kernel BTF path (for example distro debug package path)
split-BTF selected by {kernel_release, arch}

3.2 Required emitted metadata

{
  "kernel_release": "6.8.0-45-generic",
  "kernel_arch": "x86_64",
  "btf": {
    "source_kind": "kernel|external-vmlinux|split-btf",
    "source_path": "/sys/kernel/btf/vmlinux",
    "source_digest": "sha256:...",
    "selection_reason": "kernel_btf_present"
  }
}

source_path and source_digest are mandatory for deterministic replay.

4. Deterministic Symbolization Contract

Each runtime witness must carry deterministic symbolization inputs:

{
  "symbolization": {
    "build_id": "gnu-build-id:...",
    "debug_artifact_uri": "cas://symbols/by-build-id/gnu-build-id:.../artifact.debug",
    "symbol_table_uri": "cas://symbols/by-build-id/gnu-build-id:.../symtab.json",
    "symbolizer": {
      "name": "llvm-symbolizer",
      "version": "18.1.7",
      "digest": "sha256:..."
    },
    "libc_variant": "glibc|musl",
    "sysroot_digest": "sha256:..."
  }
}

At least one of debug_artifact_uri or symbol_table_uri must be present.

5. Witness Packaging Contract

Each micro-witness must be exportable as:

trace.json (canonical payload)
trace.dsse.json (DSSE envelope)
trace.sigstore.json (Sigstore bundle with signature/cert/transparency proof)

Offline verification must use only bundle-contained material (no network dependency).

6. Evidence Locker Index Contract

Evidence Locker must index runtime witness artifacts by:

build_id
kernel_release
probe_id
policy_run_id

These keys are required for deterministic replay lookup and audit search.

7. Validation Matrix (minimum)

Kernel matrix: at least 3 supported kernel lines.
libc matrix: glibc + musl.
Verification modes: online + offline.
Determinism check: byte-identical replayed frame output for fixed input evidence.

8. Confirmed Gaps (2026-02-16 Baseline)

Resolved in MWD-001 (2026-02-16): deterministic BTF selection order and metadata emission are now implemented in runtime collector:
- src/Signals/__Libraries/StellaOps.Signals.Ebpf/Services/RuntimeSignalCollector.cs
- src/Signals/__Libraries/StellaOps.Signals.Ebpf/Services/RuntimeBtfSourceSelector.cs
Probe load path is simulated and does not record selected BTF source:
- src/Signals/__Libraries/StellaOps.Signals.Ebpf/Probes/CoreProbeLoader.cs
Resolved in MWD-002 (2026-02-16): runtime witness payload and validation now enforce deterministic symbolization tuple fields.
- src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/PathWitness.cs
- src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/RuntimeWitnessRequest.cs
- src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/WitnessDsseSigner.cs
Resolved in MWD-003 (2026-02-17): runtime witness generation is implemented with deterministic observation canonicalization, DSSE signing, storage hook, and collector wiring.
- src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/RuntimeWitnessGenerator.cs
- src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/IRuntimeWitnessStorage.cs
- src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/IRuntimeWitnessSigningKeyProvider.cs
- src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Runtime/EbpfRuntimeReachabilityCollector.cs
Resolved in MWD-004 (2026-02-17): Evidence Locker manifest/export now supports runtime witness triplets and witness-index linkage keys for deterministic replay lookup, with offline bundle-contained verification checks.
- src/EvidenceLocker/__Libraries/StellaOps.EvidenceLocker.Export/Models/BundleManifest.cs
- src/EvidenceLocker/__Libraries/StellaOps.EvidenceLocker.Export/TarGzBundleExporter.cs
- src/EvidenceLocker/__Libraries/StellaOps.EvidenceLocker.Export/RuntimeWitnessOfflineVerifier.cs
Resolved in MWD-005 (2026-02-17): cross-distro deterministic replay matrix coverage now runs in targeted tests (3 kernel releases, glibc + musl) and asserts byte-identical replay-frame bytes for fixed witness artifacts with recorded artifact hashes/logs.
- src/EvidenceLocker/__Tests/StellaOps.EvidenceLocker.Export.Tests/RuntimeWitnessOfflineVerifierTests.cs
- docs/qa/feature-checks/runs/signals/ebpf-micro-witness-determinism/run-001/tier2-replay-matrix-summary.json

5.2 KiB Raw Blame History