falcosecurity/libs

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

These components are at the foundation of Falco and other projects that work with the same kind of data.

This component stack mainly operates on syscall events. We monitor syscalls using either a kernel module or an eBPF probe, which we call drivers. On top of the drivers, libscap manages the data capture process, while libsinsp enriches the data, and provides a rich set of API to consume the data. Furthermore, these two libraries also implement a plugin framework that extends this stack to potentially any other data sources. For further details, please refer to Falco's official documentation.

An image is worth a thousand words, they say:

Project Layout

driver/ contains kernel module and modern eBPF probe source code, so-called drivers.
userspace/ contains libscap and libsinsp libraries code.
- libscap (aka lib for System CAPture) is the userspace library that directly communicates with the drivers, reading syscall events from the ring buffer (where drivers place them), and forwarding them up to libsinsp. Moreover, libscap implements OS state collection and supports reading/writing to scap files.
- libsinsp (aka lib for System INSPection) receives events from libscap and enriches them with machine state: moreover, it performs events filtering with rule evaluation through its internal rule engine. Finally, it manages outputs.
proposals/ unexpectedly contains the list of proposals.
cmake/modules/ contains modules to build external dependencies, plus the libscap and libsinsp ones; consumers (like Falco) use those modules to build the libs in their projects.

Drivers Officially Supported Architectures

Our drivers officially support the following architectures:

| | Kernel module | Modern eBPF probe | Status | | ----------- |----------------------------------------------------------------------------------------------| ----------------- | ------ | | x86_64 | >= 3.10 | >= 5.8 | STABLE | | aarch64 | >= 3.16 | >= 5.8 | STABLE | | s390x | >= 3.10 | >= 5.8 | EXPERIMENTAL | | riscv64 | >= 5.0 |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. It provides a list of supported syscalls as well as the report.

NOTE: while we strive to achieve maximum compatibility, we cannot assure that drivers correctly build against a new kernel version minutes after it gets released, since we might need to make some adjustments.
To get properly notified whenever drivers stop building, we have a CI workflow that tests the build against the latest mainline kernel (RC too!)

NOTE: STABLE state means that we have CI covering drivers tests on the architecture. EXPERIMENTAL means that we are not able to run any CI test against it.

</br>

Versioning

<details> <summary>Expand Versioning Details</summary>

This project utilizes two different numbering series for the libs and drivers components, both in accordance with Semantic Versioning 2.0.0. In particular, the drivers component versions include a driver suffix in the build metadata part of the SemVer string (ie. 5.1.0+driver) to differentiate them from the libs versions (ie. 0.12.0). Further details about how we manage the versioning of these components can be found in our release process documentation.

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

For officially 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 for driver versions.

For example, 0.13.0-2+abcdef0 means that the current HEAD (G, commit hash abcdef0) is the second commit ahead of the common ancestor (E) with the release branch that holds the tag for 0.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 correct precedence 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 appropriate cmake variables. For example, use -DFALCOSECURITY_LIBS_VERSION=x.y.z -DDRIVER_VERSION=a.b.c+driver.

</details> </br>

Build

<details> <summary>Expand Build Instructions</summary>

For your convenience, we have included the instructions for building the libs modules here, in addition to the information available in Falco's official documentation. These instructions are designed for building and testing libs 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 the cmake build system, and the key make targets are as follows:

driver -> build the kmod
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)
sinsp-example -> build a small example binary for libsinsp to test the drivers and/or libsinsp functionality (dependent on scap and sinsp)

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

To start, first create and move inside build/ folder:

mkdir build && cd build

Build userspace using bundled deps

The easiest way to build the project is to use BUNDLED_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).

Build userspace using system deps

To build using the system deps instead, first, make sure to have all the needed packages installed. Refer to Falco's official 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.

Build driver - kmod

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

make driver
# Verify the

Libs

Install / Use

README