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 theofficial 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 eBPF probe
• scap -> build libscap (modern_bpf 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 theofficial 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 theofficial documentation.

make driver# Verify the kmod object code 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 theofficial documentation.

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

WARNING:clang-7 is the oldest supported version to build our BPF probe.

Initial guidance for CI and building within containers: To build either the kmod or eBPF probe in a container, you will need to make the extracted kernel headers available. Thetest/vm directory contains examplescripts demonstrating how to pass them to themake command using the argumentKERNELDIR=${EXTRACTED_KERNEL_HEADERS_DIR}. You can also use thefalcosecurity/driverkit or explore the scripts within the driverkit repository. The mentioned resources also provide candidate builder containers.

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 bpf drivers, they create a kernel-specific object code (driver/bpf/probe.o) for your machine's kernel release (uname -r). This object code is then used as an argument for testing withscap-open andsinsp-example binaries.

However, the modern BPF driver operates differently. It doesn't require kernel headers, and its build isn't tied to your kernel release. This is enabled by the CO-RE (Compile Once - Run Everywhere) feature of the modern BPF driver. CO-RE allows the driver to work on kernels with backported BTF (BPF Type Format) support or kernel versions >= 5.8.

To comprehend how the driver understands kernel data structures without knowledge of the kernel it runs on, there's no black magic involved. We maintain avmlinux.h file in our project containing all necessary kernel data structure definitions. Additionally, we sometimes rely on macros or functions typically found in system header files, which we redefine instruct_flavors.h.

That being said, the modern BPF driver still produces an object file, which you can create using the target below. Nevertheless, we ultimately include it inscap regardless. Hence, when modern BPF is enabled, buildingscap will already cover this step for you.

cmake \-DUSE_BUNDLED_DEPS=ON \-DBUILD_LIBSCAP_MODERN_BPF=ON ../;make ProbeSkeleton# Verify the modern eBPF object code / final composed header file including all `.o` modern_bpf 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

Initial guidance for CI and building within containers: The Falco Project, for instance, compiles the final Falco userspace binary within older centos7falco-builder containers with bundled dependencies. This ensures compatibility across supported systems, mainly due to GLIBC versions and other intricacies. However, you won't be able to compile the modern BPF driver on such old systems or builder containers. One solution is to buildskel_dir/bpf_probe.skel.h in a more recent builder container. For example, you can refer to thiscontainer as a guide. Subsequently, you can provide the modern BPF header file as an artifact toscap during building in an older builder container. As an illustrative example, we use/tmp/skel-dir 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 BPF, 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 \-DENABLE_VM_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
• test/vm - our CI includes comparable tests, but it employs a distinct framework. For current status reports on Falco drivers kernel testing, please visit thispage.

As mentioned earlier, 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;