Build Falco from source

Welcome to the guide on how to build Falco yourself! You are very brave! Since you are already doing all this, chances that you are willing to contribute are high! Please read our contributing guide.

1. Install the dependencies

• CentOS / RHEL
• Debian/ Ubuntu
• Arch Linux
• Alpine
• openSUSE

yum install gcc gcc-c++ git make autoconf automake pkg-config patch ncurses-devel libtool glibc-static libstdc++-static elfutils-libelf-devel

dnf install gcc gcc-c++ git make cmake autoconf automake pkg-config patch ncurses-devel libtool elfutils-libelf-devel diffutils which

apt install git cmake build-essential libncurses-dev pkg-config autoconf libtool libelf-dev -y

pacman -S git cmake make gcc wget
pacman -S zlib jq ncurses yaml-cpp openssl curl c-ares protobuf grpc libyaml

apk add g++ gcc cmake cmake make ncurses-dev git bash perl linux-headers autoconf automake m4 libtool elfutils-dev libelf-static patch binutils

zypper -n install gcc gcc-c++ git-core cmake libjq-devel ncurses-devel yaml-cpp-devel libopenssl-devel libcurl-devel c-ares-devel protobuf-devel grpc-devel patch which automake autoconf libtool libelf-devel libyaml-devel

2. Build Falco

• CentOS / RHEL
• Debian/ Ubuntu
• Arch Linux
• Alpine
• openSUSE

git clone https://github.com/falcosecurity/falco.git
cd falco
mkdir -p build
cd build
cmake -DUSE_BUNDLED_DEPS=ON ..
make falco

apt install libssl-dev libc-ares-dev libprotobuf-dev protobuf-compiler libjq-dev libgrpc++-dev protobuf-compiler-grpc libcurl4-openssl-dev libyaml-cpp-dev

git clone https://github.com/falcosecurity/falco.git
cd falco
mkdir -p build
cd build
cmake ..
make falco

git clone https://github.com/falcosecurity/falco.git
cd falco
mkdir -p build
cd build
cmake ..
make falco

git clone https://github.com/falcosecurity/falco.git
cd falco
mkdir -p build
cd build
cmake -DUSE_BUNDLED_DEPS=On -DMUSL_OPTIMIZED_BUILD=On ..
make falco

git clone https://github.com/falcosecurity/falco.git
cd falco
mkdir -p build
cd build
cmake ..
make falco

3. Build kernel module driver

• CentOS / RHEL
• Debian/ Ubuntu
• Arch Linux
• Alpine
• openSUSE

yum -y install kernel-devel-$(uname -r)
make driver

apt install linux-headers-$(uname -r)

make driver

pacman -S linux-headers
make driver

zypper -n install kernel-default-devel
make driver

4. Build eBPF driver (optional)

• CentOS / RHEL
• Debian/ Ubuntu
• Arch Linux
• Alpine
• openSUSE

dnf install clang llvm
cmake -DBUILD_BPF=ON ..
make bpf

apt install llvm clang
cmake -DBUILD_BPF=ON ..
make bpf

pacman -S llvm clang
cmake -DBUILD_BPF=ON ..
make bpf

zypper -n install clang llvm
cmake -DBUILD_BPF=ON ..
make bpf

Dependencies

By default Falco build bundles most of its runtime dependencies dynamically.

You can notice this observing that the option USE_BUNDLED_DEPS is OFF by default. Which means that, whether applicable, Falco build will try to link against libraries already existing into your machine.

Changing such option to ON causes Falco build to bundle all the dependencies statically.

For the sake of completeness this is the complete list of Falco dependencies:

• b64
• cares
• curl
• civetweb
• grpc
• jq
• libyaml
• lpeg
• luajit
• lyaml
• ncurses
• njson
• openssl
• protobuf
• tbb
• yamlcpp
• zlib
• libscap
• libsinsp

Build Falco

There are two supported ways to build Falco

• Build directly on host
• Build using a container

Build directly on host

To build Falco, you will need to create a build directory. It's common to have the build directory in the Falco working copy itself, however it can be anywhere in your filesystem.

There are three main steps to compile Falco.

1. Create the build directory and enter in it
2. Use cmake in the build directory to create the build files for Falco. .. was used because the source directory is a parent of the current directory, you can also use the absolute path for the Falco source code instead
3. Build using make

Build all

mkdir build
cd build
cmake ..
make

You can also build only specific targets:

Build Falco only

Do the build folder and cmake setup, then:

make falco

Build the Falco engine only

Do the build folder and cmake setup, then:

make falco_engine

Build libscap only

Do the build folder and cmake setup, then:

make scap

Build libsinsp only

Do the build folder and cmake setup, then:

make sinsp

Build the eBPF probe / kernel driver only

Do the build folder and cmake setup, then:

make driver

Build results

Once Falco is built, the three interesting things that you will find in your build folder are:

• userspace/falco/falco: the actual Falco binary
• driver/src/falco.ko: the Falco kernel driver
• driver/bpf/falco.o: if you built Falco with BPF support

If you'd like to build a debug version, run cmake as cmake -DCMAKE_BUILD_TYPE=Debug .. instead, see the CMake Options section for further customizations.

CMake Options

When doing the cmake command, we can pass additional parameters to change the behavior of the build files.

Here'are some examples, always assuming your build folder is inside the Falco working copy.

Generate verbose makefiles

-DCMAKE_VERBOSE_MAKEFILE=On

Specify C and CXX compilers

-DCMAKE_C_COMPILER=$(which gcc) -DCMAKE_CXX_COMPILER=$(which g++)

Enforce bundled dependencies

-DUSE_BUNDLED_DEPS=True

Read more about Falco dependencies here.

Treat warnings as errors

-DBUILD_WARNINGS_AS_ERRORS=True

Specify the build type

Debug build type

-DCMAKE_BUILD_TYPE=Debug

Release build type

-DCMAKE_BUILD_TYPE=Release

Notice this variable is case-insensitive and it defaults to release.

Specify the Falco version

Optionally the user can specify the version he wants Falco to have. Eg.,

 -DFALCO_VERSION=0.28.1-dirty

When not explicitly specifying it the build system will compute the FALCO_VERSION value from the git history.

In case the current git revision has a git tag, the Falco version will be equal to it (without the leading "v" character). Otherwise the Falco version will be in the form 0.<commit hash>[.dirty].

Enable BPF support

-DBUILD_BPF=True

When enabling this you will be able to make the bpf target after:

make bpf

Build using falco-builder container

An alternative way to build Falco is to run the falco-builder container. It contains the reference toolchain that can be used to build packages and all the dependencies are already satisfied.

The image depends on the following parameters:

• BUILD_TYPE: debug or release (case-insensitive, defaults to release)
• BUILD_DRIVER: whether or not to build the kernel module when building. This should usually be OFF, as the kernel module would be built for the files in the centos image, not the host.
• BUILD_BPF: Like BUILD_DRIVER but for the ebpf program.
• BUILD_WARNINGS_AS_ERRORS: consider all build warnings fatal
• MAKE_JOBS: passed to the -j argument of make

A typical way to run this builder is the following. Assuming you have checked out Falco and Sysdig to directories below /home/user/src, and want to use a build directory of /home/user/build/falco, you would run the following:

docker run --user $(id -u):$(id -g) -v /etc/passwd:/etc/passwd:ro -it -v /home/user/src:/source -v /home/user/build/falco:/build falcosecurity/falco-builder cmake
docker run --user $(id -u):$(id -g) -v /etc/passwd:/etc/passwd:ro -it -v /home/user/src:/source -v /home/user/build/falco:/build falcosecurity/falco-builder package

It's also possible to explicitly provide the FALCO_VERSION environment variable to use it as the version for any built package.

Otherwise the docker image will use the default FALCO_VERSION.

Load latest falco kernel module

If you have a binary version of Falco installed, an older Falco kernel module may already be loaded. To ensure you are using the latest version, you should unload any existing Falco kernel module and load the locally built version.

Unload any existing kernel module via:

rmmod falco

To load the locally built version, assuming you are in the build dir, use:

insmod driver/falco.ko

Run falco

Once Falco is built and the kernel module is loaded, assuming you are in the build dir, you can run falco as:

sudo ./userspace/falco/falco -c ../falco.yaml -r ../rules/falco_rules.yaml

By default, falco logs events to standard error.

Run regression tests

Test directly on host

To run regression tests, after building Falco, in the Falco root directory, you need to run the test/run_regression_tests.sh script.

Dependencies

You will need the following dependencies for the regression testing framework to work.

• Python 3
• Avocado Framework, version 69
• Avocado Yaml to Mux plugin
• JQ
• The unzip and xargs commands
• Docker CE

You will also need to obtain some test fixtures from the internet for the regression test suites to work.

For the python dependencies, how to setup the virtualenv, how to obtain test fixtures, read more here.

Run the tests

Change $PWD/build with the directory you built Falco in, if different.

./test/run_regression_tests.sh -d $PWD/build

Test using falco-tester container

If you'd like to run the regression test suite against your build, you can use the falco-tester container. Like the builder image, it contains the necessary environment to run the regression tests, but relies on a source directory and build directory that are mounted into the image. It's a different image than falco-builder as it doesn't need a compiler and needs a different base image to include the test runner framework avocado.

It does build a new container image falcosecurity/falco:test (which source is into docker/local directory into Falco GitHub repository) to test the process of buillding and running a container with the Falco packages built during the build step.

The image depends on the following parameters:

• FALCO_VERSION: The version of the Falco package to include in the test container image. It must match the version of the built packages.

A typical way to run this builder is the following. Assuming you have checked out Falco and Sysdig to directories below /home/user/src, and want to use a build directory of /home/user/build/falco, you would run the following:

docker run --user $(id -u):$(id -g) -v $HOME:$HOME:ro -v /boot:/boot:ro -v /var/run/docker.sock:/var/run/docker.sock -v /etc/passwd:/etc/passwd:ro -e FALCO_VERSION=${FALCO_VERSION} -v /home/user/src:/source -v /home/user/build/falco:/build falcosecurity/falco-tester

Mounting $HOME allows the test execution framework to run. You may need to replace $(id -g) with the right gid of the group that is allowed to access the docker socket (often the docker group).