125 lines
3.8 KiB
Markdown
125 lines
3.8 KiB
Markdown
# 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`
|