bpfvet: analyzes compiled .bpf.o files and reports minimum kernel version, helpers, maps, and portability issues

eBPF programs power kernel-level monitoring, networking, and security tools, but kernel compatibility trips up deployments. Kernels range from 4.x relics to 6.x, and eBPF helpers, maps, and program types land in specific versions. Reading changelogs or source code wastes time. Enter bpfvet: a tool that dissects compiled .bpf.o ELF files to report the minimum kernel version required, dependencies on helpers and maps, data transport methods, CO-RE portability, and red flags like direct kernel struct access.

It computes the minimum kernel by cross-referencing every helper (e.g., bpf_ringbuf_output needs 5.8+), program type (kprobe since 4.1+), and map type (RingBuf from 5.8+). This beats manual audits, especially for Rust, Go, or Zig-compiled programs—it’s fully language-agnostic as long as they spit out standard BPF ELF with BTF.

Why this matters: eBPF shines in production for its efficiency—no modules to load, verifier-enforced safety. But mismatched kernels crash loaders or silently fail. Security teams pushing Falco or Cilium variants across clouds hit this daily. bpfvet flags superseded helpers like bpf_probe_read (now bpf_probe_read_kernel since 5.5) and checks BTF presence for CO-RE relocations. Zero relocations? It warns on raw struct offsets, which break across kernel builds.

Hands-On: Install and Run

Grab pre-built binaries from GitHub releases—no build hassle. For Linux amd64:

curl -L https://github.com/boratanrikulu/bpfvet/releases/latest/download/bpfvet-linux-amd64 -o bpfvet
chmod +x bpfvet
./bpfvet program.bpf.o

Or go install github.com/boratanrikulu/bpfvet/cmd/bpfvet@latest. Output is crisp:

Minimum kernel: 5.8
License: GPL
BTF: yes, CO-RE relocations: 2 (vmlinux.h likely used)
Transport: event streaming via RingBuf
Kernel Requirements:
  bpf_ringbuf_output -> 5.8+
  bpf_probe_read_kernel -> 5.5+
  bpf_get_current_task -> 4.8+
  Kprobe program type -> 4.1+
Maps: events RingBuf key=0B val=0B max=262144 (5.8+)
Programs: my_probe (kprobe/do_sys_openat2, Kprobe, 29 insns)

Feed it multiple .bpf.o files for tiered kernels—handy for projects compiling legacy (4.7+) and modern (5.8+) variants. It summarizes the fleet’s minimum: all good at 5.8, but one drags to 4.7.

Portability Checks and Gotchas

bpfvet classifies memory accesses: CO-RE protected, map values, context args, or risky kernel-direct. Direct field pokes at offset 1496? ERROR—use BPF_CORE_READ(). Programs with vmlinux.h auto-get relocations via preserve_access_index, dodging warnings even on raw access. No vmlinux.h? Manual structs fail portability.

It spots transports: RingBuf (5.8+ for fast events), PerfEventArray (4.3+), or shared maps. License extraction ensures GPL compliance. JSON mode suits CI pipelines; verbose spills per-program helpers.

Skeptical take: It’s not magic. Relies on accurate BTF in the ELF—botched libbpf builds mislead it. Maps kernel intros from history, but edge cases like backports (e.g., RHEL kernels) might skew mins. Still, beats grep(changelogs). For security tooling, it quantifies deploy footprints: a 5.8+ RingBuf probe skips 20% of LTS kernels (4.18-5.4). Tier your builds, validate CO-RE, ship wider.

In context, eBPF’s growth (now in 90%+ distros) amplifies this need. Tools like bpftrace or bpftool lack static analysis depth. bpfvet fills the gap, source-free. Deploy it pre-release: catch a 5.15 helper on 5.10 hosts early. Open-source at github.com/boratanrikulu/bpfvet—fork and extend for your maps/helpers.