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.

Usage example

Deny mount operation for all users.

    const BPF_MAPS_PATH: &str = "/sys/fs/bpf/example_sb_mount";

    // Create a directory where ebpfguard policy manager can store its BPF
    // objects (maps).
    std::fs::create_dir_all(BPF_MAPS_PATH)?;

    // Create a policy manager.
    let mut policy_manager = PolicyManager::new(BPF_MAPS_PATH)?;

    // Attach the policy manager to the mount LSM hook.
    let mut sb_mount = policy_manager.attach_sb_mount()?;

    // Get the receiver end of the alerts channel (for the `file_open` LSM
    // hook).
    let mut sb_mount_rx = sb_mount.alerts().await?;

    // Define policies which deny mount operations for all processes (except
    // for the specified subject, if defined).
    sb_mount
        .add_policy(SbMount {
            subject: PolicySubject::All,
            allow: false,
        })
        .await?;

    if let Some(alert) = sb_mount_rx.recv().await {
        info!(
            "sb_mount alert: pid={} subject={}",
            alert.pid, alert.subject
        );
    }

Imports and cargo file are available in example source code. For more examples check out EXAMPLES.md.

Supported 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

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

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.