From f49f51d09299e2678ab160f3c8656955bba010a2 Mon Sep 17 00:00:00 2001 From: ErenAri Date: Thu, 2 Jul 2026 13:36:40 +0300 Subject: [PATCH] =?UTF-8?q?chore(release):=20prepare=20v0.3.0=20=E2=80=94?= =?UTF-8?q?=20changelog=20+=20version=20refs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The GitHub Action's new command-mode inputs (and built-in matrix names) exist only on main; README/doc examples pinned @v0.2.0, whose action.yml predates them. Bump all examples and the install snippet to v0.3.0 and promote the Unreleased changelog to [0.3.0] covering everything since v0.2.0: command/binary validation mode, the kernel quirk library, Action command mode, the public Pages matrix, the ebpf-go recipe, the Marketplace webhook, security hardening, and the experimental-docs consolidation. Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 38 ++++++++++++++++++++++++++++++++++++++ README.md | 10 +++++----- docs/command-validation.md | 2 +- docs/ebpf-go-validation.md | 2 +- 4 files changed, 45 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 86feefd..02c64f6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,14 +7,52 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) once a ## [Unreleased] +## [0.3.0] - 2026-07-02 + ### Added +- **Command/binary validation mode**: `bpfcompat test-command` (and + `test --command`) runs *your own* loader binary/command inside each matrix + kernel VM; the per-kernel verdict is its exit code and the bundled validator + is not used. Guest env exposes `$BPFCOMPAT_BIN`, `$BPFCOMPAT_ARTIFACT`, + `$BPFCOMPAT_REMOTE_ROOT`. See `docs/command-validation.md`. +- **Library of known-tricky vendor kernels** (`matrices/quirk-library.yaml` + + `docs/kernel-quirk-library.md`): 11 evidenced kernels where "version ≠ + feature support" bites (ring-buffer boundary, enterprise backports, no-BTF, + vendor rebases, program-variant bands). +- **GitHub Action command mode**: new `command`, `command-binary`, and + `command-expect-exit` inputs (`artifact` becomes optional when `command` is + set); free-text inputs pass through the step environment, never inline + interpolation. A bare `matrix` name (e.g. `quirk-library`) resolves to the + `matrices/` directory shipped with the action. +- **Public compatibility matrix**: `compatibility-matrix-publish` now runs + weekly on a hosted runner and deploys the quirk-library matrix (validated + against a ringbuf/simple-pass contrast pair) to GitHub Pages: + . +- **ebpf-go validation recipe**: `examples/ebpf-go-loader` (standalone module, + static ~50-line cilium/ebpf loader) + `docs/ebpf-go-validation.md` — a libbpf + load-pass does not guarantee an ebpf-go load-pass on the same kernel. +- GitHub Marketplace purchase webhook (ingestion-only, HMAC-verified JSONL + ledger) with a Cloudflare Tunnel on-ramp. - `examples/preload-gate`: a complete, runnable example of using the `pkg/bpfcompat` library — `ValidateBeforeLoad` as a bpfman-style pre-load gate (real load on the node's own kernel, no VM). README gains a "Library mode" section with the example and a real pass/blocked run. +### Changed +- Experimental tracks (virtme-ng lane, Firecracker backend, Web UI/API, runtime + decisioning) consolidated into `docs/experimental.md`; the README leads with + the CI gate, command mode, and the quirk library. +- README no longer claims modern_bpf is validated "exactly as Falco's loader + runs it" — reworded to "mirrors libpman's loader contract", pointing at + command mode as the way to run the real loader binary. + +### Security +- Shell-quote interpolated values in guest command strings. +- Harden data-derived file paths and check writable `Close()` errors. + ### Fixed - README install snippet pinned the stale `v0.1.6` release; bumped to `v0.2.0`. +- Readable contrast in the `test-command` README screenshot. ## [0.2.0] - 2026-06-27 diff --git a/README.md b/README.md index 8ebd7f4..cb2882e 100644 --- a/README.md +++ b/README.md @@ -192,7 +192,7 @@ A complete, real example is [`examples/preload-gate`](examples/preload-gate): ![preload-gate.go — a real program using ValidateBeforeLoad](docs/images/library/library-code.png) ```sh -go get github.com/kernel-guard/bpfcompat@v0.2.0 +go get github.com/kernel-guard/bpfcompat@v0.3.0 go build -tags hostload -o preload-gate ./examples/preload-gate sudo ./preload-gate probe.bpf.o ``` @@ -299,7 +299,7 @@ guest-side validator binary and the kernel matrices that ship in this repo. the static validator, checksum-verified: ```bash -VER=v0.2.0 +VER=v0.3.0 base="https://github.com/Kernel-Guard/bpfcompat/releases/download/$VER" curl -fsSLO "$base/bpfcompat-linux-amd64" curl -fsSLO "$base/bpfcompat-validator-static-linux-amd64" @@ -545,7 +545,7 @@ or the Firecracker lane. See Suite mode (recommended — gates the whole collection): ```yaml -- uses: Kernel-Guard/bpfcompat@v0.2.0 +- uses: Kernel-Guard/bpfcompat@v0.3.0 with: suite: suites/project.yaml suite-out: reports/suite.json @@ -559,7 +559,7 @@ are alive and adds the result to the suite-level collection matrix. Single artifact: ```yaml -- uses: Kernel-Guard/bpfcompat@v0.2.0 +- uses: Kernel-Guard/bpfcompat@v0.3.0 with: artifact: path/to/program.bpf.o manifest: path/to/manifest.yaml @@ -575,7 +575,7 @@ per-kernel verdict is the loader's exit code), against the built-in [library of known-tricky vendor kernels](docs/kernel-quirk-library.md): ```yaml -- uses: Kernel-Guard/bpfcompat@v0.2.0 +- uses: Kernel-Guard/bpfcompat@v0.3.0 with: command: $BPFCOMPAT_BIN --self-test command-binary: build/myloader # static or fully self-contained binary diff --git a/docs/command-validation.md b/docs/command-validation.md index 4864afc..1bacbff 100644 --- a/docs/command-validation.md +++ b/docs/command-validation.md @@ -109,7 +109,7 @@ on its own loader with one step. A bare `matrix` name resolves to the to copy: ```yaml -- uses: Kernel-Guard/bpfcompat@v0.2.0 +- uses: Kernel-Guard/bpfcompat@v0.3.0 with: command: $BPFCOMPAT_BIN --self-test command-binary: build/myloader diff --git a/docs/ebpf-go-validation.md b/docs/ebpf-go-validation.md index b1f96db..a026bed 100644 --- a/docs/ebpf-go-validation.md +++ b/docs/ebpf-go-validation.md @@ -50,7 +50,7 @@ Or in CI with the GitHub Action: ```yaml - run: cd examples/ebpf-go-loader && CGO_ENABLED=0 go build -o ebpf-go-loader . -- uses: Kernel-Guard/bpfcompat@v0.2.0 +- uses: Kernel-Guard/bpfcompat@v0.3.0 with: command: $BPFCOMPAT_BIN $BPFCOMPAT_ARTIFACT command-binary: examples/ebpf-go-loader/ebpf-go-loader