eBPF Micro-Witness Determinism Profile v1.0.0

Status: PLANNED
Version: 1.0.0
Effective: 2026-02-16
Owner: Signals Guild + Scanner Guild + Attestor Guild + Evidence Locker Guild
Sprint: docs/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)

Hard BTF dependency with no split-BTF fallback metadata contract in collector:
- src/Signals/__Libraries/StellaOps.Signals.Ebpf/Services/RuntimeSignalCollector.cs
Probe load path is simulated and does not record selected BTF source:
- src/Signals/__Libraries/StellaOps.Signals.Ebpf/Probes/CoreProbeLoader.cs
Runtime witness payload lacks required symbolization tuple fields:
- src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/PathWitness.cs
- src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/RuntimeObservation.cs
Runtime witness generator implementation is missing:
- src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/IRuntimeWitnessGenerator.cs
Sigstore bundle (trace.sigstore.json) is not yet standardized in witness storage/export:
- src/Scanner/__Libraries/StellaOps.Scanner.Storage/Postgres/Migrations/013_witness_storage.sql
- src/EvidenceLocker/__Libraries/StellaOps.EvidenceLocker.Export/Models/BundleManifest.cs

3.8 KiB Raw Blame History