stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

compose and authority fixes. finish sprints.

Browse Source
This commit is contained in:
master
2026-02-17 21:59:47 +02:00
parent fb46a927ad
commit 49cdebe2f1
187 changed files with 23189 additions and 1439 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
docs-archived/implplan/SPRINT_20260216_001_Signals_ebpf_micro_witness_determinism_profile.md Normal file
View File

@@ -0,0 +1,116 @@
# Sprint SPRINT_20260216_001_Signals_ebpf_micro_witness_determinism_profile - eBPF Micro-Witness Determinism
## Topic & Scope
- Translate the eBPF micro-witness advisory into implementation-ready contracts and sprint tasks.
- Close determinism gaps for runtime witness replay across kernel/distro/toolchain variance.
- Define one portable evidence profile for DSSE + Sigstore bundle based offline replay.
- Working directory: `docs/`.
- Cross-module edits explicitly allowed for implementation tasks: `src/Signals/`, `src/Scanner/`, `src/Attestor/`, `src/EvidenceLocker/`.
- Expected evidence: contract docs, schema/API updates, targeted module tests, offline verification artifacts.
## Dependencies & Concurrency
- Upstream contracts: `docs/contracts/witness-v1.md`, `docs/modules/attestor/repro-bundle-profile.md`, `docs/modules/evidence/unified-model.md`.
- Safe parallelism:
- Signals loader/BTF work can run in parallel with Attestor/Evidence Locker bundle contract work.
- Scanner witness model updates should run after profile fields are frozen.
## Documentation Prerequisites
- `docs/product/ebpf-micro-witness-determinism.md`
- `docs/modules/signals/contracts/ebpf-micro-witness-determinism-profile.md`
- `docs/reachability/deployment-guide.md`
- `docs/contracts/witness-v1.md`
## Delivery Tracker
### MWD-001 - Signals BTF fallback contract and metadata emission
Status: DONE
Dependency: none
Owners: Product Manager, Developer
Task description:
- Implement deterministic BTF selection order in the runtime collector and emit selected source metadata (`source_kind`, `source_path`, `source_digest`, `selection_reason`) into runtime evidence/witness context.
- Ensure behavior is explicit for kernel BTF, external vmlinux BTF, and split-BTF fallback.
Completion criteria:
- [x] Collector no longer fails solely on missing `/sys/kernel/btf/vmlinux` when configured fallback BTF exists.
- [x] Runtime evidence includes immutable BTF selection metadata required for replay.
### MWD-002 - Runtime witness schema extensions for deterministic symbolization
Status: DONE
Dependency: MWD-001
Owners: Developer, Documentation author
Task description:
- Extend runtime witness payload schema to include deterministic symbolization tuple: `build_id`, debug/symbol pointer(s), symbolizer identity/version/digest, libc variant, and sysroot digest.
- Update witness contracts and validation rules in docs and implementation.
Completion criteria:
- [x] Witness schema and code models carry required symbolization fields.
- [x] Validation rejects witnesses missing required deterministic symbolization inputs.
### MWD-003 - Implement Scanner runtime witness generation pipeline
Status: DONE
Dependency: MWD-002
Owners: Developer, Test Automation
Task description:
- Deliver concrete `IRuntimeWitnessGenerator` implementation, integrating runtime observations, witness building, DSSE signing, and storage.
- Ensure deterministic ordering/canonicalization for runtime observation payloads.
Completion criteria:
- [x] Runtime witness generation is implemented (not interface-only) and wired into runtime instrumentation flow.
- [x] Determinism tests show stable witness bytes for fixed inputs.
### MWD-004 - DSSE plus Sigstore bundle witness packaging
Status: DONE
Dependency: MWD-003
Owners: Developer, Documentation author
Task description:
- Standardize and implement per-witness artifact triplet: `trace.json`, `trace.dsse.json`, `trace.sigstore.json`.
- Store and export this profile through Evidence Locker with offline verification compatibility.
Completion criteria:
- [x] Evidence Locker manifest/index model supports the Sigstore bundle artifact and links it to witness identity.
- [x] Offline verify workflow succeeds using bundle-contained material only.
### MWD-005 - Cross-distro deterministic replay test matrix
Status: DONE
Dependency: MWD-004
Owners: Test Automation, QA
Task description:
- Add targeted replay verification across kernel/libc matrix (minimum 3 kernels, glibc + musl), asserting byte-identical replay frames for fixed witness artifacts.
- Capture command output and evidence artifacts for deterministic QA sign-off.
Completion criteria:
- [x] Matrix tests run against targeted projects (not solution filters) and show deterministic replay output.
- [x] Execution evidence is recorded with artifact hashes and replay verification logs.
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-02-16 | Sprint created from eBPF micro-witness advisory review; gaps confirmed and translated to implementation tasks. | Project Manager |
| 2026-02-16 | Completed MWD-001: added deterministic BTF source selector (kernel -> external vmlinux -> split-BTF), emitted BTF selection metadata in runtime summaries/results, and added unit coverage in Signals and Scanner modules. | Developer |
| 2026-02-16 | Completed MWD-002: extended runtime witness schema with deterministic symbolization tuple and added runtime validation in request/sign/verify paths with Scanner test coverage. | Developer |
| 2026-02-17 | Completed MWD-003: implemented `RuntimeWitnessGenerator` (canonical runtime observation ordering, DSSE signing, CAS storage hook), wired optional witness emission into runtime collector flow, and added deterministic generation tests (`RuntimeWitnessGeneratorTests`) plus collector integration coverage. | Developer |
| 2026-02-17 | Completed MWD-004: extended Evidence Locker export manifest/index with runtime witness triplet metadata (`trace`, `dsse`, `sigstore_bundle`) and replay lookup keys, added runtime witness export path support, and added offline triplet verifier tests in `StellaOps.EvidenceLocker.Export.Tests` (`80/80` passing). | Developer |
| 2026-02-17 | Completed MWD-005: added cross-distro kernel/libc replay matrix test (`5.15`, `6.1`, `6.6`; `glibc` + `musl`) in `RuntimeWitnessOfflineVerifierTests`, verified byte-identical replay-frame projection from fixed witness triplets, ran targeted project tests (`81/81`), and captured QA evidence artifacts in `docs/qa/feature-checks/runs/signals/ebpf-micro-witness-determinism/run-001/`. | Test Automation + QA |
| 2026-02-17 | Added two additional determinism regression tests (observation order invariance and trace mutation sensitivity) in `RuntimeWitnessOfflineVerifierTests`, reran targeted project tests (`83/83`), and captured refreshed evidence artifacts in `docs/qa/feature-checks/runs/signals/ebpf-micro-witness-determinism/run-002/`. | Test Automation + QA |
| 2026-02-17 | Sprint archived after all delivery tasks reached `DONE` with evidence captured for both replay matrix runs (`run-001`, `run-002`). | Project Manager |
## Decisions & Risks
- Decision: Adopt a single micro-witness determinism profile defined in `docs/modules/signals/contracts/ebpf-micro-witness-determinism-profile.md`.
- Decision: Product-level promise and current baseline are captured in `docs/product/ebpf-micro-witness-determinism.md`.
- Decision: Runtime witness symbolization tuple and validation rules are codified in `docs/contracts/witness-v1.md` and reflected in `docs/modules/signals/contracts/ebpf-micro-witness-determinism-profile.md`.
- Decision: Runtime witness generation now canonicalizes observation ordering before witness/hash/signing to ensure byte-stable DSSE output for equivalent observation sets.
- Decision: Evidence Locker runtime witness artifact indexing uses `witnessId` + `witnessRole` + `witnessIndex` (`build_id`, `kernel_release`, `probe_id`, `policy_run_id`) to support deterministic replay lookup and artifact linkage.
- Docs sync: `docs/contracts/witness-v1.md`, `docs/modules/evidence-locker/export-format.md`, `docs/modules/signals/contracts/ebpf-micro-witness-determinism-profile.md`, and `docs/product/ebpf-micro-witness-determinism.md` updated for MWD-004 contract changes.
- Decision: Advisory translation record archived at `docs-archived/product/advisories/16-Feb-2026 - eBPF micro-witness deterministic replay across distros.md`.
- Risk: Existing runtime collector hard dependency on kernel BTF may block non-BTF kernels until fallback path is implemented.
- Risk: Runtime witness generation remains incomplete without a concrete generator implementation; downstream attestation/export is blocked.
- Risk: Absence of standardized Sigstore witness bundle may produce non-portable replay evidence across environments.
- Note: test commands with `--filter` were executed against individual `.csproj` files, but this repository uses Microsoft.Testing.Platform and emitted `MTP0001` warnings indicating `VSTestTestCaseFilter` was ignored; full test project suites were executed instead.
- Note: `MWD-005` evidence uses targeted `.csproj` execution without solution filters; replay matrix logs and artifact hashes are stored under `docs/qa/feature-checks/runs/signals/ebpf-micro-witness-determinism/run-001/`.
- Note: follow-up evidence run `run-002` includes additional deterministic replay regression assertions and refreshed artifact/hash logs.
- External web fetches: none.
## Next Checkpoints
- 2026-02-18: Contract review sign-off (Signals/Scanner/Attestor/Evidence Locker owners).
- 2026-02-21: MWD-001 and MWD-002 implementation readiness checkpoint.
- 2026-02-25: First end-to-end deterministic replay demo with DSSE + Sigstore witness bundle.