chore(release): prepare v0.3.1 — changelog + version refs

CHANGELOG.md

@@ -7,13 +7,41 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) once a
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-07-16
+
 ### Added
 - Project governance and sustainability documents: Code of Conduct,
   governance, maintainers, roadmap, adopters, funding, and sponsor ledger.
 - GitHub Sponsors repository funding configuration and sponsor badge.
 - Structured adopter issue form for confirmed use and public evaluations.
 - Sponsor brief and explicit review ownership for external outreach and project
   accountability.
+- Docs: bpfcompat now runs upstream — `falcosecurity/libs` merged a scheduled
+  compatibility lane that validates Falco's real loader (`scap-open`) per
+  kernel via command mode (falcosecurity/libs#3024); README, the Falco case
+  study, and `docs/command-validation.md` document it.
+
+### Fixed
+- **GitHub Action: commit-SHA pins now use prebuilt release binaries.** The
+  prebuilt resolution only matched `v*` tag refs, so pinning the action by
+  full commit SHA (the recommended practice for third-party actions) silently
+  fell back to building the validator from source — failing on runners
+  without `libbpf-dev`. A 40-hex action ref is now resolved to the release
+  tag pointing at that commit via the GitHub API (authenticated with the
+  workflow's `github.token`) and the release's checksum-verified binaries are
+  used; any API failure or unknown SHA still falls back to the source build,
+  and `prebuilt: never` still forces it.
+- **VM runner: fail fast when a cidata-seed distro lacks `cloud-localds`.**
+  RHEL-family, Amazon Linux, Oracle, and SUSE guests need a cidata seed ISO;
+  without `cloud-image-utils` installed the runner previously fell back to a
+  vvfat config drive those images never boot from (0-byte serial, SSH
+  timeout reported as an infra error). This is now a clear pre-boot error
+  naming the missing tool; set `BPFCOMPAT_ALLOW_VVFAT_SEED=1` to restore the
+  old fallback.
+
+### Security
+- Release binaries are built with Go 1.25.12, picking up the fix for
+  GO-2026-5856 (Encrypted Client Hello privacy leak in `crypto/tls`).
 
 ## [0.3.0] - 2026-07-02
 

README.md

@@ -199,7 +199,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.3.0
+go get github.com/kernel-guard/bpfcompat@v0.3.1
 go build -tags hostload -o preload-gate ./examples/preload-gate
 sudo ./preload-gate probe.bpf.o
 ```
@@ -315,7 +315,7 @@ guest-side validator binary and the kernel matrices that ship in this repo.
 the static validator, checksum-verified:
 
 ```bash
-VER=v0.3.0
+VER=v0.3.1
 base="https://github.com/Kernel-Guard/bpfcompat/releases/download/$VER"
 curl -fsSLO "$base/bpfcompat-linux-amd64"
 curl -fsSLO "$base/bpfcompat-validator-static-linux-amd64"
@@ -561,7 +561,7 @@ or the Firecracker lane. See
 Suite mode (recommended — gates the whole collection):
 
 ```yaml
-- uses: Kernel-Guard/bpfcompat@v0.3.0
+- uses: Kernel-Guard/bpfcompat@v0.3.1
   with:
     suite: suites/project.yaml
     suite-out: reports/suite.json
@@ -575,7 +575,7 @@ are alive and adds the result to the suite-level collection matrix.
 Single artifact:
 
 ```yaml
-- uses: Kernel-Guard/bpfcompat@v0.3.0
+- uses: Kernel-Guard/bpfcompat@v0.3.1
   with:
     artifact: path/to/program.bpf.o
     manifest: path/to/manifest.yaml
@@ -591,7 +591,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.3.0
+- uses: Kernel-Guard/bpfcompat@v0.3.1
   with:
     command: $BPFCOMPAT_BIN --self-test
     command-binary: build/myloader   # static or fully self-contained binary

docs/case-study-falco-modern-bpf.md

@@ -67,7 +67,7 @@ keep in sync with the loader: the loader is the contract.
 
 ```bash
 # In CI (GitHub Action), against your kernel matrix:
-- uses: Kernel-Guard/bpfcompat@v0.3.0
+- uses: Kernel-Guard/bpfcompat@v0.3.1
   with:
     artifact: build/bpf_probe.o
     matrix: matrices/mvp.yaml

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.3.0
+- uses: Kernel-Guard/bpfcompat@v0.3.1
   with:
     command: $BPFCOMPAT_BIN --self-test
     command-binary: build/myloader

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.3.0
+- uses: Kernel-Guard/bpfcompat@v0.3.1
   with:
     command: $BPFCOMPAT_BIN $BPFCOMPAT_ARTIFACT
     command-binary: examples/ebpf-go-loader/ebpf-go-loader

docs/quickstart.md

@@ -35,7 +35,7 @@ jobs:
     runs-on: ubuntu-latest          # exposes /dev/kvm for KVM acceleration
     steps:
       - uses: actions/checkout@v4
-      - uses: Kernel-Guard/bpfcompat@v0.3.0
+      - uses: Kernel-Guard/bpfcompat@v0.3.1
         with:
           artifact: build/program.bpf.o     # your compiled object
           matrix: matrices/mvp.yaml          # the kernels you support
@@ -57,7 +57,7 @@ What you get:
 Shipping a whole product? Use **suite mode** to gate a collection in one run:
 
 ```yaml
-      - uses: Kernel-Guard/bpfcompat@v0.3.0
+      - uses: Kernel-Guard/bpfcompat@v0.3.1
         with:
           suite: suites/project.yaml
           suite-out: reports/suite.json