Ebpfguard
Ebpfguard is a library for managing Linux security policies. It is based on LSM hooks, but without necessity to write any kernel modules or eBPF programs directly. It allows to write policies in Rust (or YAML) in user space.
It's based on eBPF and Aya library, but takes away the need to use them directly.
Prerequisites
kernel capabilities
First, you need to have a Linux kernel:
- with BTF support
- with BPF LSM support (kernels >= 5.7)
You can check if your kernel has BTF support by checking whether file
/sys/kernel/btf/vmlinux
exists. You can also check the kernel configuration:
$ zgrep CONFIG_DEBUG_INFO_BTF /proc/config.gz
CONFIG_DEBUG_INFO_BTF=y
Next, you need to check if your kernel has BPF LSM support:
$ cat /sys/kernel/security/lsm
lockdown,capability,selinux,bpf
If the output doesn't contain bpf
, you need to enable BPF LSM by adding
lsm=[...],bpf
to your kernel config parameters. That can be achieved by
executing the enable-bpf-lsm.py script.
This script will print modified contents of /etc/default/grub
file to stdout.
Either pipe it back directly to /etc/default/grub
or save it somewhere
and compare contents before swapping to a new version.
Whole command with direct pipe:
$ ./enable-bpf.lsm.py | sudo tee /etc/default/grub 1>/dev/null
This file is used by grub2 to assemble final grub.cfg
. To trigger reconfiguration
use grub's mkconfig command with -o <path to grub.cfg>
switch.
Both command name and path to grub.cfg
are distribution dependent.
On ubuntu:
$ sudo grub-mkconfig -o /boot/grub/grub.cfg
On fedora:
$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
After that's done reboot your system.
rust toolchain and packages
You need the Rust stable and nightly toolchains installed on your system, bpf-linker and bpftool binary.
Install nightly toolchain:
$ rustup toolchain install nightly --component rust-src
Optionally add miri:
$ rustup component add miri --toolchain nightly
Finally install bpf-linker:
$ cargo install bpf-linker
This bpf-linker installation method works on linux x86_64 systems. For others refer to aya-rs documentation.
To install bpftool either use distro provided package or build it from source.
On ubuntu it is a part of linux-tools:
$ sudo apt install linux-tools-$(uname -r)
Development
All commands should be executed from repository/workspace root folder unless noted otherwise.
Compilation
First compile ebpf bytecode with the following command. It will be embedded in userspace binary using aya.
$ cargo xtask build-ebpf
Then userspace code.
$ cargo build
Tests
Commands in this subsection mirror state of CI pipeline.
Regular tests
$ cargo test
Formatting gateway. Drop check subflag to autoformat.
$ cargo fmt --all -- --check
Clippy lints.
$ cargo clippy --workspace -- --deny warnings
Miri verification.
$ cargo +nightly miri test --all-targets
Note that miri verification requires nightly toolchain as well as miri component. To add them execute:
$ rustup toolchain install nightly --component rust-src
$ rustup component add miri --toolchain nightly
LSM hooks
LSM hooks supported by Ebpfguard are:
bprm_check_security
file_open
sb_mount
sb_remount
sb_umount
socket_bind
socket_connect
task_fix_setuid
Examples
For usage examples check EXAMPLES.md.
Get in touch
Thank you for using Ebpfguard. Please feel welcome to participate in the Deepfence community.
- Deepfence Community Website
- Got a question, need some help? Find the Deepfence team on Slack
- Got a feature request or found a bug? Raise an issue
- Find out more at deepfence.io
License
Ebpfguard's userspace part is licensed under Apache License, version 2.0.
eBPF programs inside ebpfguard-ebpf directory are licensed under GNU General Public License, version 2.