This project utilizes two different numbering series for thelibs anddrivers components, both in accordance withSemantic Versioning 2.0.0. In particular, thedrivers component versions include adriver suffix in thebuild metadata part of the SemVer string (ie.5.1.0+driver) to differentiate them from thelibs versions (ie.0.12.0). Further details about how we manage the versioning of these components can be found in ourrelease process documentation.

When building this project from a Git working directory, the build system (seeCMakeLists.txt) will automatically determine the correct version for all components.

Forofficially released builds, the corresponding Git tag will be used as the version.

For development versions, the following schema is applied:

<x>.<y>.<z>-<count>+<commit>[-driver]

Where:

• <x>.<y>.<z> represents the next version number, reflecting either a patch for release branches or a minor version for development branches.
• <count> is the number of commits ahead from either:
  • the latest tag on the branch, for release branches; or
  • the closest common ancestor with the branch holding the latest tagged version, for development branches.
• <commit> refers to the first 7 digits of the commit hash.
• [-driver] is an optional suffix used specifically fordriver versions.

For example,0.13.0-2+abcdef0 means that the currentHEAD (G, commit hashabcdef0) is the second commit ahead of the common ancestor (E) with the release branch that holds the tag for0.12.0 (C):

      A---B---C (tag: 0.12.0, branch: release/0.12.x)     /D---E---F---G (HEAD -> abcdef0)

This scheme ensures the correctprecedence when comparing build version numbers, regardless of whether they are released or development builds.

If you are building this project outside of a Git working directory, or if you want to override the version numbers, you must correctly set the appropriatecmake variables. For example, use-DFALCOSECURITY_LIBS_VERSION=x.y.z -DDRIVER_VERSION=a.b.c+driver.

For your convenience, we have included the instructions for building thelibs modules here, in addition to the information available in Falco'sofficial documentation. These instructions are designed for building and testinglibs on your own Linux development machine. However, if you intend to adopt CI or build within containers, there are additional considerations to take into account. The official website continually extends its guidance in this respect.

The project utilizes thecmake build system, and the keymake targets are as follows:

• driver -> build the kmod
• bpf -> build the legacyebpf probe
• scap -> build libscap (modern_ebpf driver will be bundled intoscap if enabled)
• sinsp -> build libsinsp (depends uponscap target)
• scap-open -> build a small example binary forlibscap to test the drivers (dependent onscap)
• sinsp-example -> build a small example binary forlibsinsp to test the drivers and/orlibsinsp functionality (dependent onscap andsinsp)

You can refer to the mainCMakeLists.txt file to explore the available targets and flags.

To start, first create and move insidebuild/ folder:

mkdir build&&cd build

The easiest way to build the project is to useBUNDLED_DEPS option (enabled by default),meaning that most of the dependencies will be fetched and compiled during the process:

cmake -DUSE_BUNDLED_DEPS=ON ../;make sinsp

NOTE: Take a break as this will take quite a bit of time (around 15 mins, dependent on the hardware).

To build using the system deps instead, first, make sure to have all the needed packages installed. Refer to Falco'sofficial documentation.

cmake -DUSE_BUNDLED_DEPS=OFF ../;make sinsp

NOTE: Using system libraries is useful to cut compile times down, as this way it will only build libs, and not all deps. On the other hand, system deps version may have an impact, and we cannot guarantee everything goes smoothly while using them.

To build the kmod driver, you need your kernel headers installed. Check out Falco'sofficial documentation.

make driver# Verify the kmod binary object file was created, uses `.ko` extension.ls -l driver/src/scap.ko;

To build the eBPF probe, you needclang andllvm packages and you also need your kernel headers installed. Check out Falco'sofficial documentation.

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.

To build the modern eBPF probe, further prerequisites are necessary:

• A recentclang version (>=12).

• A recentbpftool version, typingbpftool gen you should see at least these features:

  Usage: bpftool gen object OUTPUT_FILE INPUT_FILE [INPUT_FILE...]    <---       bpftool gen skeleton FILE [name OBJECT_NAME]                 <---       bpftool gen help

  If you want to use thebpftool mirror repo, version6.7 should be enough.

  If you want to compile it directly from the kernel tree you should pick at least the5.13 tag.

• BTF exposed by your kernel, you can check it throughls /sys/kernel/btf/vmlinux. You should see this line:

  /sys/kernel/btf/vmlinux

• A kernel version >=5.8.

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 thescap-open andsinsp-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.

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 avmlinux.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 instruct_flavors.h. Combined with CO-RE (Compile Once, Run Everywhere), this enables the driver to remain portable across different kernel versions.

The modern eBPF driver build process produces an eBPF header skeleton file usingbpftool. The skeleton file is a C header file that embeds the compiled eBPF program as bytecode.

cmake \-DUSE_BUNDLED_DEPS=ON \-DBUILD_LIBSCAP_MODERN_BPF=ON ../;make ProbeSkeleton# Verify the modern eBPF bytecode / final composed header file including all `.o` modern_ebpf files was created, uses `.h` extension.ls -l skel_dir/bpf_probe.skel.h;# Now includes skel_dir/bpf_probe.skel.h in `scap` during the linking process.make scap

Since modern eBPF is included inscap, runningmake scap automatically covers themake ProbeSkeleton build step.

You can also split the build process and specify the directory containing thebpf_probe.skel.h file.

cmake \-DUSE_BUNDLED_DEPS=ON \-DBUILD_LIBSCAP_MODERN_BPF=ON \-DMODERN_BPF_SKEL_DIR="/tmp/skel-dir" ../;

Libscap contains additional library functions to allow integration with system call events coming fromgVisor.Compilation of this functionality can be disabled with-DBUILD_LIBSCAP_GVISOR=OFF.

This repository includes convenient test example binaries for bothscap andsinsp:

• scap-open -> build a small example binary forlibscap to test the drivers (dependent onscap), checkout the program'sdocumentation
• sinsp-example -> build a small example binary forlibsinsp to test the drivers and/orlibsinsp functionality (dependent onscap andsinsp), checkout the program'sdocumentation

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-inprintk functionality. However, for the traditional bpf driver, you'll need to uncomment a line in thebpf Makefile first and use a dedicated build flagBPF_DEBUG. For modern eBPF, use the build flagMODERN_BPF_DEBUG_MODE. Any logs generated bybpf_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 acmake command that will enable everything you need for all tests and components. By default, the following flags are disabled, with the exception ofUSE_BUNDLED_DEPS andCREATE_TEST_TARGETS (they are enabled by default).

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 \-DENABLE_LIBSINSP_E2E_TESTS=ON ../;

NOTE: TheENABLE_LIBSINSP_E2E_TESTS flag enables the new e2e tests for libsinsp. Please keep in mind these tests are currently in heavy development and need some extra steps (see in the section below) to run correctly.

TIP: Installing and using the packageccache can optimize repeated testing, but we don't offer official support or testing for it.

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 binaryrm -f libscap/examples/01-open/scap-open; make -j$(($nproc-1)) scap-open;# sinsp-example binaryrm -f libsinsp/examples/sinsp-example; make -j$(($nproc-1)) sinsp-example;

These are the conventional unit tests that our CI system enforces:

# sinsp traditional unit testsmake -j$(($nproc-1)) unit-test-libsinsp;# Runmake run-unit-test-libsinsp;# scap traditional unit testsmake -j$(($nproc-1)) libscap_test;# Runsudo ./test/libscap/libscap_test;

Specialized driver tests can be found intest/drivers, but please be aware that certain limitations might apply, and we're making every effort to ensure compatibility across various distributions. Our CI system also enforces these tests, but do note that currently, the CI system for driver tests is designed exclusively for Ubuntu. Therefore, if you encounter some test failures that aren't related to your changes, don't worry too much.

make -j$(($nproc-1)) drivers_test;# Run each drivers test via changing flagssudo ./test/drivers/drivers_test -m;

The tests mentioned below expand beyond the scope of "unit tests". In this context as well, we are dedicated to making sure they run smoothly on yourlocalhost for pre-PR testing, to the best of our ability:

• test/e2e - enforced by our CI

For current status reports on the CI powered Falco drivers kernel testing, please visit thispage.

In general, The Falco Project'slibs repository includes numerous CI-powered checks. For the most current information, please refer to the CI definitions under theworkflows directory.

To correctly run the new libsinsp e2e tests on x86_64gcc-multilib andg++-multilib are needed. To run the tests, use the following commands:

make -j$(($nproc-1)) libsinsp_e2e_tests;# Run each drivers test via changing flagssudo ./test/libsinsp_e2e/libsinsp_e2e_tests -m;