# 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)
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)

- 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`