# 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)
1. `/sys/kernel/btf/vmlinux`
2. configured full-kernel BTF path (for example distro debug package path)
3. split-BTF selected by `{kernel_release, arch}`

### 3.2 Required emitted metadata

```json
{
  "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:

```json
{
  "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:

1. `trace.json` (canonical payload)
2. `trace.dsse.json` (DSSE envelope)
3. `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`