Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ jobs:
name: [system_deps, bundled_deps, sanitizers, zig]
include:
- name: system_deps
cmake_opts: -DBUILD_WARNINGS_AS_ERRORS=On -DBUILD_BPF=On -DUSE_BUNDLED_DEPS=False
cmake_opts: -DBUILD_WARNINGS_AS_ERRORS=On -DUSE_BUNDLED_DEPS=False
- name: bundled_deps
cmake_opts: -DBUILD_WARNINGS_AS_ERRORS=On -DBUILD_BPF=On -DUSE_BUNDLED_DEPS=True
cmake_opts: -DBUILD_WARNINGS_AS_ERRORS=On -DUSE_BUNDLED_DEPS=True
- name: sanitizers
cmake_opts: -DUSE_ASAN=On -DUSE_UBSAN=On -DUSE_BUNDLED_DEPS=False
- name: zig
Expand Down Expand Up @@ -116,7 +116,6 @@ jobs:
- name: Build and test 🏗️🧪
run: |
cmake -B build -S . \
-DBUILD_BPF=On \
-DBUILD_DRIVER=Off \
-DUSE_BUNDLED_DEPS=On \
-DUSE_BUNDLED_LIBELF=Off \
Expand Down Expand Up @@ -262,7 +261,6 @@ jobs:
-DUSE_BUNDLED_DEPS=On \
-DBUILD_DRIVER=ON \
-DBUILD_LIBSCAP_MODERN_BPF=ON \
-DBUILD_BPF=On \
-DBUILD_LIBSCAP_GVISOR=On \
-DCREATE_TEST_TARGETS=Off \
-DENABLE_LIBSCAP_TESTS=Off
Expand Down
1 change: 0 additions & 1 deletion .github/workflows/driver-api-version.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ on:
- 'userspace/libscap/engine/modern_bpf/**'
- 'userspace/libscap/engine/kmod/**'
- 'driver/ppm_events_public.h'
- 'driver/bpf/maps.h'
- 'driver/modern_bpf/maps/maps.h'

jobs:
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/driverkit.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ jobs:
steps:
- name: Test drivers build on ${{ matrix.name }}
run: |
driverkit docker --kernelrelease ${{ matrix.kernelrelease }} --target ${{ matrix.target }} --output-module /tmp/libs.ko --output-probe /tmp/libs.o --driverversion $GITHUB_SHA --loglevel debug --kernelurls ${{ matrix.kernelurls }}
driverkit docker --kernelrelease ${{ matrix.kernelrelease }} --target ${{ matrix.target }} --output-module /tmp/libs.ko --driverversion $GITHUB_SHA --loglevel debug --kernelurls ${{ matrix.kernelurls }}

build-drivers-arm64:
strategy:
Expand All @@ -57,4 +57,4 @@ jobs:
steps:
- name: Test drivers build on ${{ matrix.name }}
run: |
driverkit docker --kernelrelease ${{ matrix.kernelrelease }} --target ${{ matrix.target }} --output-module /tmp/libs.ko --output-probe /tmp/libs.o --driverversion $GITHUB_SHA --loglevel debug --kernelurls ${{ matrix.kernelurls }} --architecture arm64 --timeout 600
driverkit docker --kernelrelease ${{ matrix.kernelrelease }} --target ${{ matrix.target }} --output-module /tmp/libs.ko --driverversion $GITHUB_SHA --loglevel debug --kernelurls ${{ matrix.kernelurls }} --architecture arm64 --timeout 600
29 changes: 5 additions & 24 deletions .github/workflows/drivers_ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -83,26 +83,19 @@ jobs:
-DUSE_BUNDLED_DEPS=On \
-DBUILD_DRIVER=ON \
-DBUILD_LIBSCAP_MODERN_BPF=ON \
-DBUILD_BPF=On \
-DBUILD_LIBSCAP_GVISOR=${{ matrix.enable_gvisor }} \
-DCREATE_TEST_TARGETS=On \
-DENABLE_LIBSCAP_TESTS=On \
-DUSE_ASAN=On \
-DUSE_UBSAN=On
cmake --build build --target scap-open driver bpf libscap_test --parallel $(nproc)
cmake --build build --target scap-open driver libscap_test --parallel $(nproc)

- name: Run scap-open with modern bpf 🏎️
if: needs.paths-filter.outputs.driver == 'true' || needs.paths-filter.outputs.libscap == 'true' || needs.paths-filter.outputs.libpman == 'true'
run: |
cd build
sudo ./libscap/examples/01-open/scap-open --modern_bpf --num_events 10

- name: Run scap-open with bpf 🏎️
if: needs.paths-filter.outputs.driver == 'true' || needs.paths-filter.outputs.libscap == 'true' || needs.paths-filter.outputs.libpman == 'true'
run: |
cd build
sudo ./libscap/examples/01-open/scap-open --bpf ./driver/bpf/probe.o --num_events 10

- name: Run scap-open with kmod 🏎️
if: needs.paths-filter.outputs.driver == 'true' || needs.paths-filter.outputs.libscap == 'true' || needs.paths-filter.outputs.libpman == 'true'
run: |
Expand Down Expand Up @@ -169,22 +162,15 @@ jobs:
-DENABLE_DRIVERS_TESTS=ON \
-DBUILD_LIBSCAP_MODERN_BPF=ON \
-DMODERN_BPF_DEBUG_MODE=ON \
-DBUILD_BPF=True \
-DBUILD_LIBSCAP_GVISOR=OFF
cmake --build build --target drivers_test driver bpf --parallel $(nproc)
cmake --build build --target drivers_test driver --parallel $(nproc)

- name: Run drivers_test with modern bpf 🏎️
if: needs.paths-filter.outputs.driver == 'true' || needs.paths-filter.outputs.libscap == 'true' || needs.paths-filter.outputs.libpman == 'true'
run: |
cd build
sudo ./test/drivers/drivers_test -m

- name: Run drivers_test with bpf 🏎️
if: needs.paths-filter.outputs.driver == 'true' || needs.paths-filter.outputs.libscap == 'true' || needs.paths-filter.outputs.libpman == 'true'
run: |
cd build
sudo ./test/drivers/drivers_test -b

- name: Run drivers_test with kmod 🏎️
if: needs.paths-filter.outputs.driver == 'true' || needs.paths-filter.outputs.libscap == 'true' || needs.paths-filter.outputs.libpman == 'true'
run: |
Expand Down Expand Up @@ -225,17 +211,14 @@ jobs:
-DENABLE_DRIVERS_TESTS=ON \
-DBUILD_LIBSCAP_MODERN_BPF=ON \
-DMODERN_BPF_DEBUG_MODE=ON \
-DBUILD_BPF=True \
-DBUILD_LIBSCAP_GVISOR=OFF \
-DUSE_BUNDLED_LIBELF=OFF
cmake --build . --target drivers_test driver bpf --parallel $(nproc)
cmake --build . --target drivers_test driver --parallel $(nproc)
sudo ./test/drivers/drivers_test -m
rc_modern=$?
sudo ./test/drivers/drivers_test -b
rc_bpf=$?
sudo ./test/drivers/drivers_test -k
rc_kmod=$?
exit $(($rc_modern + $rc_bpf +$rc_kmod))
exit $(($rc_modern + $rc_kmod))

build-drivers-s390x:
name: build-drivers-s390x 😁 (bundle_deps)
Expand Down Expand Up @@ -272,9 +255,8 @@ jobs:
-DENABLE_DRIVERS_TESTS=ON \
-DBUILD_LIBSCAP_MODERN_BPF=ON \
-DMODERN_BPF_DEBUG_MODE=ON \
-DBUILD_BPF=ON \
-DBUILD_LIBSCAP_GVISOR=OFF
cmake --build build --target drivers_test driver bpf --parallel $(nproc)
cmake --build build --target drivers_test driver --parallel $(nproc)

build-modern-bpf-skeleton:
needs: paths-filter
Expand Down Expand Up @@ -346,7 +328,6 @@ jobs:
-DBUILD_LIBSCAP_MODERN_BPF=ON \
-DMODERN_BPF_SKEL_DIR=/tmp \
-DBUILD_DRIVER=Off \
-DBUILD_BPF=Off

- name: Build project
run: |
Expand Down
5 changes: 2 additions & 3 deletions .github/workflows/e2e_ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,6 @@ jobs:
cmake -B build -S . \
-DCMAKE_C_COMPILER_LAUNCHER=sccache \
-DCMAKE_CXX_COMPILER_LAUNCHER=sccache \
-DBUILD_BPF=ON \
-DUSE_BUNDLED_DEPS=ON \
-DUSE_ASAN=ON \
-DUSE_UBSAN=ON \
Expand All @@ -103,7 +102,7 @@ jobs:
strategy:
matrix:
arch: [amd64, arm64]
driver: [ {name: kmod, option: -k}, {name: bpf, option: -b}, {name: modern-bpf, option: -m} ]
driver: [ {name: kmod, option: -k}, {name: modern-bpf, option: -m} ]
fail-fast: false
steps:
- name: Checkout Libs ⤵️
Expand Down Expand Up @@ -145,7 +144,7 @@ jobs:
# different workers, so we rebuild the drivers.
- name: Rebuild drivers
run: |
cmake --build build --target driver bpf --parallel $(nproc) -- -B # -B only works if make is the generator.
cmake --build build --target driver --parallel $(nproc) -- -B # -B only works if make is the generator.
pushd build/test/libsinsp_e2e/resources/
sudo tar xzf fake-proc.tar.gz

Expand Down
1 change: 0 additions & 1 deletion .github/workflows/latest-kernel.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,6 @@ jobs:
echo "driverversion: ${{ github.sha }}" >> dk.yaml
echo "output:" >> dk.yaml
echo " module: mod.ko" >> dk.yaml
echo " probe: probe.o" >> dk.yaml
if [ "${{ inputs.linux-version }}" = "" ]; then
krel=$(grep "_tag" PKGBUILD | head -n1 | awk -F"=" '{print $2}')
echo "kernelrelease: ${krel:1}" >> dk.yaml
Expand Down
3 changes: 1 addition & 2 deletions .github/workflows/reusable_e2e_tests.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -91,13 +91,12 @@ jobs:
- name: Build tests 🏗️
run: |
cmake -B build -S . \
-DBUILD_BPF=ON \
-DBUILD_LIBSCAP_MODERN_BPF=ON \
-DBUILD_LIBSCAP_GVISOR=OFF \
-DENABLE_E2E_TESTS=ON \
${{ matrix.cmake_opts }} \
-DUSE_BUNDLED_LIBBPF=ON
cmake --build build --target sinsp-example driver bpf container_plugin --parallel $(nproc)
cmake --build build --target sinsp-example driver container_plugin --parallel $(nproc)
sudo -E cmake --build build --target e2e-install-deps

- name: Download overriding custom container plugin
Expand Down
2 changes: 1 addition & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ option(USE_BUNDLED_DRIVER
"Use the driver/ subdirectory in the build process (only available in Linux)" ON
)
option(ENABLE_E2E_TESTS "Enable e2e tests" OFF)
option(ENABLE_DRIVERS_TESTS "Enable driver tests (bpf, kernel module, modern bpf)" OFF)
option(ENABLE_DRIVERS_TESTS "Enable driver tests (kernel module, modern bpf)" OFF)
option(ENABLE_LIBSCAP_TESTS "Enable libscap unit tests" OFF)
option(ENABLE_LIBSINSP_E2E_TESTS "Enable libsinsp e2e tests" OFF)
option(BUILD_SHARED_LIBS "Build libscap and libsinsp as shared libraries" OFF)
Expand Down
3 changes: 1 addition & 2 deletions CMakePresets.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,14 @@
"CMAKE_BUILD_TYPE": "Release",
"CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
"BUILD_DRIVER": "ON",
"BUILD_BPF": "ON",
"BUILD_WARNINGS_AS_ERRORS": "ON"
}
},
{
"name": "scap-drivers",
"inherits": "base",
"displayName": "Build scap drivers and their tests",
"description": "Build all scap drivers (modern eBPF, legacy eBPF, kmod) and their tests",
"description": "Build all scap drivers (modern eBPF, kmod) and their tests",
"binaryDir": "${sourceDir}/build-scap-drivers",
"cacheVariables": {
"USE_BUNDLED_DEPS": "ON",
Expand Down
41 changes: 11 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
[![Drivers](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/FedeDP/1cbc5d42edf8e3a02fb75e76625f1072/raw/kernel.json)](https://github.com/falcosecurity/libs/actions/workflows/latest-kernel.yml)
[![Github Pages](https://github.com/falcosecurity/libs/actions/workflows/pages.yml/badge.svg)](https://falcosecurity.github.io/libs/)

This repository contains **libsinsp**, **libscap**, the **kernel module** and the **eBPF probes** sources.
This repository contains **libsinsp**, **libscap**, the **kernel module** and the **modern eBPF probe** sources.

These components are at the foundation of [Falco](https://github.com/falcosecurity/falco) and other projects that work with the same kind of data.

Expand All @@ -20,7 +20,7 @@ An image is worth a thousand words, they say:

## Project Layout

* [_driver/_](./driver) contains kernel module and eBPF probe source code,
* [_driver/_](./driver) contains kernel module and modern eBPF probe source code,
so-called **drivers**.
* [_userspace/_](./userspace) contains libscap and libsinsp libraries code.
* **libscap** (aka lib for *System CAPture*) is the userspace library
Expand All @@ -41,13 +41,13 @@ external dependencies, plus the libscap and libsinsp ones; consumers

Our drivers officially support the following architectures:

| | Kernel module | eBPF probe | Modern eBPF probe | Status |
| ----------- |----------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------| ----------------- | ------ |
| **x86_64** | >= 3.10 | >= 4.14 | >= 5.8 | _STABLE_ |
| **aarch64** | >= [3.16](https://github.com/torvalds/linux/commit/055b1212d141f1f398fca548f8147787c0b6253f) | >= 4.17 | >= 5.8 | _STABLE_ |
| **s390x** | >= 3.10 | >= [5.5](https://github.com/torvalds/linux/commit/6ae08ae3dea) | >= 5.8 | _EXPERIMENTAL_ |
| **riscv64** | >= [5.0](https://github.com/torvalds/linux/commit/5aeb1b36cedd3a1dfdbfe368629fed52dee34103) | N/A | N/A | _EXPERIMENTAL_ |
| **ppc64le** | >= 3.10 | >= [5.1](https://github.com/torvalds/linux/commit/ed1cd6deb013a11959d17a94e35ce159197632da) | >= 5.8 | _STABLE_ |
| | Kernel module | Modern eBPF probe | Status |
| ----------- |----------------------------------------------------------------------------------------------| ----------------- | ------ |
| **x86_64** | >= 3.10 | >= 5.8 | _STABLE_ |
| **aarch64** | >= [3.16](https://github.com/torvalds/linux/commit/055b1212d141f1f398fca548f8147787c0b6253f) | >= 5.8 | _STABLE_ |
| **s390x** | >= 3.10 | >= 5.8 | _EXPERIMENTAL_ |
| **riscv64** | >= [5.0](https://github.com/torvalds/linux/commit/5aeb1b36cedd3a1dfdbfe368629fed52dee34103) |N/A | _EXPERIMENTAL_ |
| **ppc64le** | >= 3.10 | >= 5.8 | _STABLE_ |


To access up-to-date status reports on Falco drivers kernel testing, please visit this [page](https://falcosecurity.github.io/libs/). It provides a list of supported syscalls as well as the [report](https://falcosecurity.github.io/libs/report/).
Expand Down Expand Up @@ -109,7 +109,6 @@ For your convenience, we have included the instructions for building the `libs`
The project utilizes the `cmake` build system, and the key `make` targets are as follows:

* `driver` -> build the kmod
* `bpf` -> build the legacy `ebpf` probe
* `scap` -> build libscap (`modern_ebpf` driver will be bundled into `scap` if enabled)
* `sinsp` -> build libsinsp (depends upon `scap` target)
* `scap-open` -> build a small example binary for `libscap` to test the drivers (dependent on `scap`)
Expand Down Expand Up @@ -154,19 +153,6 @@ make driver
ls -l driver/src/scap.ko;
```

### Build driver - eBPF probe

To build the eBPF probe, you need `clang` and `llvm` packages and you also need your kernel headers installed. Check out Falco's [official documentation](https://falco.org/docs/install-operate/source/).

```bash
cmake -DBUILD_BPF=ON ../;
make bpf
# Verify the eBPF bytecode file was created, uses `.o` extension.
ls -l driver/bpf/probe.o;
```

>__WARNING__: **clang-7** is the oldest supported version to build our BPF probe.

### Build driver - modern eBPF probe

To build the modern eBPF probe, further prerequisites are necessary:
Expand All @@ -191,9 +177,7 @@ To build the modern eBPF probe, further prerequisites are necessary:

> __NOTE:__ These are not the requirements to use the modern BPF probe, but rather for building it from source.

Regarding the previously discussed legacy eBPF driver, it generates kernel-specific bytecode (`driver/bpf/probe.o`) tailored to your machine's kernel release (`uname -r`). The location of the bytecode file can then be passed as an argument for testing with the `scap-open` and `sinsp-example` binaries.

However, the modern eBPF driver build process doesn't require kernel headers, and it isn't tied to your kernel release. This is enabled by the CO-RE (Compile Once - Run Everywhere) feature of the modern eBPF driver.
The modern eBPF driver build process doesn't require kernel headers, and it isn't tied to your kernel release. This is enabled by the CO-RE (Compile Once - Run Everywhere) feature of the modern eBPF driver.

CO-RE allows the driver to work on kernels with backported BTF (BPF Type Format) support or kernel versions >= 5.8. The way the driver interprets kernel data structures without direct knowledge of the running kernel is not magic — it leverages predefined type information and BTF-based relocations. We maintain a [vmlinux.h](driver/modern_bpf/definitions/vmlinux.h) file containing essential kernel data structure definitions, allowing the eBPF program to reference fields dynamically. Additionally, for cases where macros or functions from system headers are required, we redefine them in [struct_flavors.h](driver/modern_bpf/definitions/struct_flavors.h). Combined with CO-RE (Compile Once, Run Everywhere), this enables the driver to remain portable across different kernel versions.

Expand Down Expand Up @@ -243,7 +227,7 @@ This repository includes convenient test example binaries for both `scap` and `s

When developing new features, you would run either one depending on what you're working on, in order to test and validate your changes.

> __NOTE:__ When you're working on driver development, it can be quite useful to make use of the kernel's built-in `printk` functionality. However, for the traditional bpf driver, you'll need to uncomment a line in the [bpf Makefile](driver/bpf/Makefile) first and use a dedicated build flag `BPF_DEBUG`. For modern eBPF, use the build flag `MODERN_BPF_DEBUG_MODE`. Any logs generated by `bpf_printk()` will be written to `/sys/kernel/debug/tracing/trace_pipe`. Just make sure you have the right permissions set up for this.
> __NOTE:__ When you're working on driver development, it can be quite useful to make use of the kernel's built-in `printk` functionality. For modern eBPF, use the build flag `MODERN_BPF_DEBUG_MODE`. Any logs generated by `bpf_printk()` will be written to `/sys/kernel/debug/tracing/trace_pipe`. Just make sure you have the right permissions set up for this.

Here's an example of a `cmake` command that will enable everything you need for all tests and components. By default, the following flags are disabled, with the exception of `USE_BUNDLED_DEPS` and `CREATE_TEST_TARGETS` (they are enabled by default).

Expand All @@ -252,10 +236,8 @@ cmake \
-DUSE_BUNDLED_DEPS=ON \
-DBUILD_LIBSCAP_MODERN_BPF=ON \
-DBUILD_LIBSCAP_GVISOR=ON \
-DBUILD_BPF=ON \
-DBUILD_DRIVER=ON \
-DMODERN_BPF_DEBUG_MODE=ON \
-DBPF_DEBUG=ON \
-DCREATE_TEST_TARGETS=ON \
-DENABLE_LIBSCAP_TESTS=ON \
-DENABLE_DRIVERS_TESTS=ON \
Expand All @@ -268,7 +250,6 @@ cmake \

```bash
nproc=$(grep processor /proc/cpuinfo | tail -n 1 | awk '{print $3}');
rm -f driver/bpf/probe.o; make bpf;
rm -f driver/src/scap.ko; make driver;
# scap-open binary
rm -f libscap/examples/01-open/scap-open; make -j$(($nproc-1)) scap-open;
Expand Down
2 changes: 0 additions & 2 deletions cmake/modules/engine_config.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,8 @@ set(HAS_ENGINE_SOURCE_PLUGIN On)

if(CMAKE_SYSTEM_NAME MATCHES "Linux")
option(ENABLE_ENGINE_KMOD "Enable kernel module engine" ON)
option(ENABLE_ENGINE_BPF "Enable bpf engine" ON)

set(HAS_ENGINE_KMOD ${ENABLE_ENGINE_KMOD})
set(HAS_ENGINE_BPF ${ENABLE_ENGINE_BPF})

option(BUILD_LIBSCAP_MODERN_BPF "Enable modern bpf probe" OFF)
if(BUILD_LIBSCAP_MODERN_BPF)
Expand Down
2 changes: 1 addition & 1 deletion driver/API_VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
8.0.4
9.0.0
2 changes: 0 additions & 2 deletions driver/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -216,5 +216,3 @@ if(ENABLE_DKMS)
COMPONENT ${DRIVER_KMOD_COMPONENT_NAME}
)
endif()

add_subdirectory(bpf)
1 change: 0 additions & 1 deletion driver/bpf/.gitignore

This file was deleted.

Loading
Loading