/awesome-ebpf

A curated list of awesome projects related to eBPF.

Creative Commons Zero v1.0 UniversalCC0-1.0

Awesome eBPF Awesome

A curated list of awesome projects related to eBPF.

BPF, as in Berkeley Packet Filter, is an in-kernel virtual machine running programs passed from user space. Initially implemented on BSD, then Linux, the (now legacy) "classic BPF" or cBPF machine would be used with tools like tcpdump for filtering packets in the kernel to avoid useless copies to user space. More recently, the BPF infrastructure in Linux has been completely reworked and gave life to the "extended BPF", or eBPF, which gained new features (safety and termination checks, JIT-compiling for programs, persistent maps, a standard library, hardware offload support, etc.) and is now used for many tasks. Processing packets at a very low level (XDP), tracing and monitoring events on the system, or enforcing access control over cgroups are but a few examples to which eBPF brings performance, programmability and flexibility.

Recently Cilium launched a great website about eBPF called ebpf.io. It serves a similar purpose to this list, with an introduction to eBPF and links to related projects.

Note: eBPF is an exciting piece of technology, and its ecosystem is constantly evolving. We'd love help from you to keep this awesome list up to date, and improve its signal-to-noise ratio in anyway we can. Please feel free to leave any feedback.

Contents

Reference Documentation

eBPF Essentials

  • ebpf.io - A gateway to discover all the basics of eBPF, including a listing of the main related projects and of community resources.
  • Cilium's BPF and XDP Reference Guide - In-depth documentation about most features and aspects of eBPF.

Kernel Documentation

Manual Pages

  • bpf(2) - Manual page about the bpf() system call, used to manage BPF programs and maps from userspace.
  • tc-bpf(8) - Manual page about using BPF with tc, including example commands and samples of code.
  • bpf-helpers(7) man page - Description of the in-kernel helper functions forming the BPF standard library.

Other

Articles and Presentations

Generic eBPF Presentations and Articles

If you are new to eBPF, you may want to try the links described as "introductions" in this section.

BPF Internals

Kernel Tracing

XDP

AF_XDP

bpfilter

BTF

cBPF

Hardware Offload

Tutorials

Examples

  • linux/samples/bpf/ - In the kernel tree: some sample eBPF programs.
  • linux/tools/testing/selftests/bpf - In the kernel tree: Linux BPF selftests, with many eBPF programs.
  • prototype-kernel/kernel/samples/bpf - Jesper Dangaard Brouer's prototype-kernel repository contains some additional examples that can be compiled outside of kernel infrastructure.
  • iproute2/examples/bpf/ - Some networking programs to attach to the TC interface.
  • Netronome sample network applications - Provides basic but complete examples of eBPF applications also compatible with hardware offload.
  • bcc/examples - Examples coming along with the bcc tools, mostly about tracing.
  • bcc/tools - These tools themselves can be seen as example use cases for BPF programs, mostly for tracing and monitoring. bcc tools have been packaged for some Linux distributions.
  • MPLSinIP sample - A heavily commented sample demonstrating how to encapsulate & decapsulate MPLS within IP. The code is commented for those new to BPF development.
  • ebpf-samples - A collection of compiled (as ELF object files) samples gathered from several projects, primarily intended to serve as test cases for user space verifiers.
  • ebpf-kill-example - A fully documented and tested example of an eBPF probe that logs all force-kills and prints them out in user-space.
  • redbpf examples - Example programs for using RedBPF to write eBPF programs in Rust.
  • XDP/TC-eBPF example - Program that uses XDP/TC-eBPF to provide statefull firewalling and socket redirection.

eBPF Workflow: Tools and Utilities

bcc

  • bcc - Framework and set of tools - One way to handle BPF programs, in particular for tracing and monitoring. Also includes some utilities that may help inspect maps or programs on the system.
  • Lua front-end for BCC - Another alternative to C, and even to most of the Python code used in bcc.

iproute2

  • iproute2 - Package containing tools for network management on Linux. In particular, it contains tc, used to manage eBPF filters and actions, and ip, used to manage XDP programs. Most of the code related to BPF is in lib/bpf.c.
  • iproute2-next - The development tree, synchronised with net-next.

LLVM

  • LLVM - Contains several tools used in eBPF workflows. Snapshots of the latest versions for Ubuntu/Debian can be retrieved from here.

    • clang is used to compile C to eBPF object file under the ELF format (clang v3.7.1+). The BPF backend was added with this commit.
    • llvm-objdump is used to dump the content of an object file in human-readable format, possibly with the initial C source code (llvm-objdump v4.0+).
    • llvm-mc is used to compile from LLVM intermediate representation to eBPF object file, so that one can compile from C to eBPF assembly, tinker with assembly, then compile to ELF file.

libbpf

  • libbpf - A C library used for handling BPF objects (programs and maps), and manipulating ELF object files containing them. It is shipped with the kernel and mirrored on GitHub.
  • libbpf-bootstrap - Scaffolding for BPF application development with libbpf and BPF CO-RE.

Go libraries

  • cilium/ebpf - Pure-Go library to read, modify and load eBPF programs and attach them to various hooks in the Linux kernel.
  • libbpfgo - eBPF library for Go, powered by libbpf.
  • gobpf - Go bindings for BCC for creating eBPF programs.

Aya

  • aya - A pure Rust library for writing, loading, and managing eBPF objects, with a focus on developer experience and operability. It supports writing eBPF programs in Rust and distributing library code over crates.io to share it between eBPF programs. Aya does not depend on libbpf.
  • aya-template - Templates for writing BPF applications in Aya that can be used with cargo generate.
  • Ebpfguard - Rust library for writing Linux security policies using eBPF.

zbpf

  • zbpf - A pure Zig framework for writing cross platform eBPF programs, powered by libbpf and Zig toolchain.

eunomia-bpf

  • eunomia-bpf - A compilation framework and runtime library to build, distribute, dynamically load, and run CO-RE eBPF applications in multiple languages and WebAssembly. It supports writing eBPF kernel code only (to build simple CO-RE libbpf eBPF applications), writing the kernel part in both BCC and libbpf styles, and writing userspace in multiple languages in a WASM module and distributing it with simple JSON data or WASM OCI images. The runtime is based on libbpf only and provides CO-RE to BCC-style eBPF programs without depending on the LLVM library.

oxidebpf

  • oxidebpf - A pure Rust library for managing eBPF programs, designed for security use cases. The featureset is more limited than other libraries but emphasizes stability across a wide range of kernels and backwards-compatible compile-once-run-most-places.

bpftool and Other Tools from the Kernel Tree

  • bpftool - Also some other tools in the kernel tree, under linux/tools/net/ for versions earlier than 4.15, or linux/tools/bpf/ after that:

    • bpftool - A generic utility that can be used to interact with eBPF programs and maps from userspace, for example to show, dump, load, disassemble, pin programs, or to show, create, pin, update, delete maps, or to attach and detach programs to cgroups.
    • bpf_asm - A minimal cBPF assembler.
    • bpf_dbg - A small debugger for cBPF programs.
    • bpf_jit_disasm - A disassembler for both BPF flavors and could be highly useful for JIT debugging.

User Space eBPF

  • uBPF - Written in C. Contains an interpreter, a JIT compiler for x86_64 architecture, an assembler and a disassembler.
  • A generic implementation - With support for FreeBSD kernel, FreeBSD user space, Linux kernel, Linux user space and macOS user space. Used for the VALE software switch's BPF extension module.
  • rbpf - Written in Rust. Interpreter for Linux, macOS and Windows, and JIT-compiler for x86_64 under Linux.
  • PREVAIL - A user space verifier for eBPF using an abstract interpretation layer, with support for loops.
  • oster - Written in Go. A tool for tracing execution of Go programs by attaching eBPF to uprobes.
  • wachy - A tracing profiler that aims to make eBPF uprobe-based debugging easier to use. This is done by displaying traces in a UI next to the source code and allowing interactive drilldown analysis.

eBPF on Other Platforms

  • eBPF for Windows - This project is a work-in-progress that allows using existing eBPF toolchains and APIs familiar in the Linux ecosystem to be used on top of Windows.

Testing in Virtual Environments

Projects Related to eBPF

Networking

Observability

  • InKeV: In-Kernel Distributed Network Virtualization for DCN
  • DEEP-mon - Helps with measuring power consumption for servers and uses eBPF programs for in-kernel aggregation of data.
  • pixie - Observability for Kubernetes using eBPF. Features include protocol tracing, application profiling, and support for distributed bpftrace deployments.
  • SkyWalking Rover - Apache SkyWalking is an open-source Application Performance Monitoring (APM) platform specially designed for distributed systems with microservices, cloud-native and container-based (Kubernetes) architectures. SkyWalking Rover is an eBPF-based profiler and metrics collector for C, C++, Golang, and Rust applications.
  • parca-agent - eBPF based always-on continuous profiler for analysis of CPU and memory usage, down to the line number and throughout time.
  • rbperf - Sampling profiler and tracer for Ruby.
  • Hubble - Network, service and security observability for Kubernetes using eBPF.
  • Caretta - Instant Kubernetes service dependency map generated by eBPF, right to a Grafana instance.

Security

  • Falco - A cloud-native runtime security project used as a Kubernetes threat detection engine.
  • Sysmon for Linux - A security monitoring tool. It depends on SysinternalsEBPF.
  • Red Canary Linux Agent - Red Canary has started to incorporate eBPF to their Linux security sensor.
  • Tracee - A runtime security and forensics tool for Linux which uses eBPF technology to trace the system and applications at runtime, and analyze collected events to detect suspicious behavioral patterns.
  • redcanary-ebpf-sensor - A set of BPF programs that gather security relevant event data from the Linux kernel. The BPF programs are combined into a single ELF file from which individual probes can be selectively loaded, depending on the running operating system and kernel version.
  • bpflock - Lock Linux machines - An eBPF driven security tool for locking and auditing Linux machines.
  • Tetragon - Kubernetes-aware, eBPF-based security observability and runtime enforcement.

Tools

  • ply - A small but flexible open source dynamic tracer for Linux, with features similar to the bcc tools, but with a simpler language inspired by awk and DTrace.
  • bpftrace - A tool for tracing with its own high-level tracing language. It is flexible enough to be envisioned as a Linux replacement for DTrace and SystemTap.
    • bpftrace Cheat Sheet - Summary and cheat sheet for programming in bpftrace. Contains information about syntax, probe types, variables and functions.
  • kubectl trace - A kubectl plug-in for executing bpftrace programs in a Kubernetes cluster.
  • inspektor-gadget - A collection of eBPF-based tools to debug and inspect Kubernetes resources and applications.
  • bpfd - Framework for running BPF programs with rules on Linux as a daemon. Container aware.
  • BPFd - A distinct BPF daemon, trying to leverage the flexibility of the bcc tools to trace and debug remote targets, and in particular devices running with Android.
  • adeb - A Linux shell environment for using tracing tools on Android with BPFd.
  • greggd - System daemon to compile and load eBPF programs into the kernel, and forward program output to socket for metric aggregation.
  • FUSE - Considers using eBPF.
  • upf-bpf - An in-kernel solution based on XDP for 5G UPF.
  • redbpf - Tooling and framework to write eBPF code in Rust efficiently.
  • ebpf-explorer - A web interface to explore system's maps and programs.
  • ebpfmon - A TUI (terminal user interface) application for real time monitoring of eBPF programs.

eBPF in Security

  • Embrace The Red: Offensive BPF! - A series of posts around the introduction into BPF with a focus to an offensive setting, and also how its misuse can be detected. Posts include discussions on the rootkit capabilities of eBPF, or on which tracing type is needed for different use cases.
  • eBPF: Block Linux Fileless Payload "Malware" Execution with BPF LSM - Blog post about how BPF can help detection and blocking fileless malware.
  • Blackhat 2021: With Friends Like eBPF, Who Needs Enemies? - Talk about an eBPF rootkit and how the capabilities of eBPF could be abused. The rootkit was also the object of a talk at Defcon, eBPF, I thought we were friends !.
  • ebpfkit - A rootkit that leverages multiple eBPF features to implement offensive security techniques.
  • ebpfkit-monitor - An utility to statically analyze eBPF bytecode or monitor suspicious eBPF activity at runtime. It was specifically designed to detect ebpfkit.
  • Bad BPF - A collection of malicious eBPF programs that make use of eBPF's ability to read and write user data in between the usermode program and the kernel.
  • TripleCross - A Linux eBPF rootkit with a backdoor, C2, library injection, execution hijacking, persistence and stealth capabilities.

The Code

Development and Community

Other Lists of Resources on eBPF

Acknowledgement

Thank you to Quentin Monnet and Daniel Borkmann for their original work on Dive into BPF: A List of Reading Material which became the basis for this list.

Contributing

Contributions welcome! Read the contribution guidelines first.

License

CC0

To the extent possible under law, zoidbergwill has waived all copyright and related or neighboring rights to this work.