ebpf

ebpf-go is a pure Go library, maintained by Cilium and its community, for loading, verifying, and managing eBPF programs and maps entirely from Go — no cgo or libbpf binding required. It parses compiled eBPF ELF objects into typed specs, loads them into the kernel, and provides a full BPF Type Format (BTF) implementation so a single compiled program can adapt to different kernel struct layouts via CO-RE (Compile Once – Run Everywhere) relocation.

Beyond the core load path, the project ships a dedicated link package with typed attachment helpers for kprobes, uprobes, tracepoints, XDP, cgroups, tc/tcx, netfilter, and struct_ops, plus ringbuf and perf readers for streaming kernel events into userspace, a pin package for persisting objects on bpffs, and the bpf2go code generator that turns a C source file into ready-to-use Go bindings. It targets both Linux and Windows (via eBPF for Windows) and is the library underneath Cilium itself as well as many other observability and networking tools in the eBPF ecosystem.

What You Get

• Programmatic loading, verification, and management of eBPF programs and maps from compiled ELF objects
• A full BTF (BPF Type Format) implementation for CO-RE (Compile Once – Run Everywhere) relocations
• A dedicated link package with typed attachment helpers for kprobes, uprobes, tracepoints, XDP, cgroups, tc/tcx, netfilter, and struct_ops
• The bpf2go code generator that turns a C source file into ready-to-use Go bindings
• Cross-platform support for both Linux and Windows via eBPF for Windows

Common Use Cases

• Building observability/tracing agents that hook into kernel probes to collect metrics
• Implementing network policy and packet filtering (XDP, tc/tcx) without writing raw syscalls
• Embedding compiled eBPF programs directly into a Go binary via bpf2go for self-contained deployment
• Reading BPF ring buffers or perf event arrays to stream kernel events into userspace

Under The Hood

Architecture The top-level ebpf package (collection.go, map.go, prog.go, linker.go) implements the core object model — CollectionSpec/MapSpec/ProgramSpec describe an ELF-derived eBPF object graph, and Collection/Map/Program are the loaded, live-kernel counterparts backed by file descriptors from the internal/sys syscall wrappers. elf_reader.go parses compiled ELF objects into these specs, linker.go resolves references between programs, maps, and BTF prior to load, and the btf/ package implements a full BTF type-graph decoder and relocator (core.go for CO-RE) that map.go and prog.go consume for cross-kernel compatibility. The link/ package is a separate attachment layer built around a common Link interface with per-hook-type implementations (kprobe.go, xdp.go, tcx.go, cgroup.go, etc.) — swapping which file is used changes what kernel hook a Program attaches to without touching how it was loaded. Cross-cutting concerns like Linux/Windows differences are isolated via internal/platform and build-tag-suffixed files, while asm/ provides an independent instruction-encoding layer used by tests and the bpf2go codegen path.

Tech Stack A Go module (go 1.25+) with a deliberately minimal runtime dependency set — jsimonetti/rtnetlink for netlink-based link attachment, golang.org/x/sync and golang.org/x/sys, plus go-quicktest/qt and google/go-cmp for tests. Additional dependencies (go-containerregistry’s crane, stringer, staticcheck) are declared as build-time tool directives rather than linked into consumers. This is a low-level systems library that talks directly to the kernel via bpf(2) and perf_event_open through internal/unix and internal/sys wrappers, with a parallel internal/efw path for eBPF-for-Windows. CI runs a real kernel-version matrix (up to kernel.org LTS 7.1) alongside Windows Server 2022, driven by a Makefile and golangci-lint v2 plus staticcheck.

Code Quality An extensive test suite of 132 _test.go files uses go-quicktest/qt and gotest.tools/v3 assertion helpers rather than stdlib-only testing, with internal/testutils gating tests on actual kernel feature availability. Errors are explicit sentinel values (ErrKeyNotExist, ErrNotSupported, ErrProgIncompatible) wrapped with fmt.Errorf %w, and heuristic cases like a bad CO-RE relocation are named and documented as best-effort rather than silently misreported. CI enforces staticcheck and golangci-lint (govet, ineffassign, misspell, unused, plus a custom depguard rule banning direct golang.org/x/sys/unix imports outside internal/unix) on every push and PR, alongside kernel-version-matrixed integration tests — a notably rigorous setup for a library this close to the kernel boundary.

API Design A consistent Spec-then-Load pattern across every kernel object (CollectionSpec→Collection, MapSpec→Map, ProgramSpec→Program) keeps the API predictable once learned, and BTF-driven CO-RE relocation lets one compiled object run across kernel versions without recompilation. The bpf2go companion tool removes further boilerplate by generating typed Go bindings directly from C source, so most consumers never touch the raw ELF/BTF layers. Documentation is dense — per-package doc.go files, a dedicated docs site, and 17 runnable examples covering kprobes, XDP, ring buffers, and struct_ops — though object-lifetime rules (closing Map/Collection to avoid kernel-side resource leaks) remain a real sharp edge for newcomers.