Falco – Event Sources

Docs: Kernel Events

Mon, 01 Jan 0001 00:00:00 +0000

Falco uses different instrumentations to analyze the system workload and pass security events to userspace. We usually refer to these instrumentations as drivers since a driver runs in kernelspace. The driver provides the syscall event source since the monitored events are strictly related to the syscall context.

There are several supported drivers:

Modern eBPF probe (default)
Legacy eBPF probe (deprecated)
Kernel module

	Kernel module	Legacy eBPF probe (deprecated)	Modern eBPF probe
x86_64	>= 3.10	>= 4.14	Minimal set of features
aarch64	>= 3.10	>= 4.17	Minimal set of features

Kernel module

By default, the kernel module will be installed when installing the Falco debian/rpm package, when running the falcoctl driver tool shipped within the binary package, or when running the falcosecurity/falco-driver-loader docker image (that just wraps the aforementioned tool).

To install the kernel module, please refer to the installation page.

Least privileged mode

The kernel module requires full privileges and cannot run with Linux capabilities

Modern eBPF probe

The modern eBPF probe is an alternative driver for Falco. The main advantage it brings to the table is that it is embedded into Falco, which means that you don't have to download or build anything, if your kernel is recent enough Falco will automatically inject it!

What's new

The new probe is highly customizable, you are not obliged to use one buffer for each CPU you can also use just one huge buffer for all your CPUs! And obviously, also the buffer size is customizable! All this is possible thanks to new outstanding features like the CO-RE paradigm, the BPF ring buffer and many others, if you are curious you can read more about them in this blog post.

Requirements

The modern eBPF probe doesn't require a specific kernel version. Usually, all versions >=5.8 are enough but there are cases in which the required features could also be backported into older kernels, so it wouldn't be completely fair to define 5.8 as the first supported version. The 2 main required features are:

BPF ring buffer support.
A kernel that exposes BTF.

Falco can automatically detect if these features are available on the running machine and can notify you if something is missing. As an alternative, you could always use bpftool, you just need to type the following commands:

sudo bpftool feature probe kernel | grep -q "map_type ringbuf is available" && echo "true" || echo "false"
sudo bpftool feature probe kernel | grep -q "program_type tracing is available" && echo "true" || echo "false"

How to run it

Modern eBPF probe is bundled into the userspace binary and works out of the box, regardless of the kernel release, thanks to the eBPF feature called 'Compile Once Run Everywhere' (CO-RE). To enable it in Falco, just set the engine.kind configuration key to modern_ebpf.

It is supported in all the installation methods of other drivers:

Useful resources

Least privileged mode

The minimal set of capabilities required by Falco to run the modern eBPF probe is the following:

CAP_SYS_BPF
CAP_SYS_PERFMON
CAP_SYS_RESOURCE
CAP_SYS_PTRACE

Let's see them in detail:

CAP_SYS_RESOURCE: Falco needs this capability to be able to call the setrlimit syscall. The setrlimit syscall is used together with the RLIMIT_MEMLOCK flag to change the amount of memory that can be mlocked into RAM. The default value for this memory limit is very low, so even a very simple eBPF program would fail. The workaround is to increase the default value to something acceptable so eBPF maps can be correctly mlocked in memory.
CAP_SYS_PTRACE: Falco needs this capability because it accesses paths like /proc/<pid>/environ. From the userspace standpoint, the permission to do so is mapped to the CAP_SYS_PTRACE capability. For the curious reader, see environ_open implementation in the kernel.
CAP_SYS_ADMIN: Falco needs this capability to load eBPF programs and maps, and to interact with the system using the bpf syscall.

This set of capabilities should work most of the time but under some conditions, it is possible to replace the CAP_SYS_ADMIN with two more granular capabilities: CAP_SYS_BPF and CAP_SYS_PERFMON.

The only condition needed is a kernel version that supports these capabilities. The Linux Kernel version 5.8 is the first one that officially supports them but they could have been backported on older versions on some distributions.

Please note: we will try to do our best to keep this as the minimum required set but due to some issues with CO-RE relocations it is possible that this changes in the future.

Legacy eBPF probe

The Legacy eBPF probe has been deprecated in Falco 0.43.0 and will be removed in a future release. Until removal and since Falco 0.43.0, using it will result in a warning informing the user about the deprecation. Users are encouraged to switch to another engine, such as the modern eBPF probe, as the usage will result in an error after the removal.

The legacy eBPF probe is an alternative source to the ones described above, leveraging greater compatibility than the modern eBPF one, since it requires older kernel versions.

To install the eBPF probe, please refer to the installation page.

To enable the eBPF support in Falco set the engine.kind configuration key to ebpf and eventually customize engine.ebpf.probe to the path where the eBPF probe resides; the default path is the location used by falcoctl driver tool to install the eBPF probe, ie: ${HOME}/.falco/falco-bpf.o, where ${HOME} will expand to the home dir of the user running Falco.

Least privileged mode

The minimal set of capabilities required by Falco to run the legacy eBPF probe is the following:

CAP_SYS_ADMIN
CAP_SYS_RESOURCE
CAP_SYS_PTRACE

The mentioned capabilities require no further explanation since they were already discussed in detail in the modern eBPF probe section. Moreover, for legacy eBPF probe the kernel.perf_event_paranoid sysctl value must also be double checked: reading the manual it is stated that perf_event_paranoid influences only the behavior of unprivileged users, but under the hood, some distributions like Debian or Ubuntu introduce additional perf_event_paranoid levels. Consider Ubuntu as an example:

if (perf_paranoid_any() && !capable(CAP_SYS_ADMIN))
 return -EACCES;

// where perf_paranoid_any is defined as:
static inline bool perf_paranoid_any(void) {
 return sysctl_perf_event_paranoid > 2;
}

As you can notice, when your kernel.perf_event_paranoid is >2 the capability CAP_PERFMON won't suffice, you would still need CAP_SYS_ADMIN. So before disabling CAP_SYS_ADMIN check your perf_event_paranoid value with sysctl kernel.perf_event_paranoid and make sure their values are compatible with your distribution enforcement.

Docs: Plugin Events

Mon, 01 Jan 0001 00:00:00 +0000

Since the introduction of the Plugin System, additional event sources can serve as input for Falco. Those event sources are provided by plugins implementing the event sourcing capability.

Examples of event source defined by officially-supported plugins are:

In addition to these plugins hosted by the Falcosecurity organization, others have written third-party plugins that support additional event sources. Please refer to the official Plugin Registry for the most up-to-date information regarding the Falco plugins acknowledged by the community.

At the implementation level, the plugin system sends events to Falco using the same protocol that is used for syscalls, but the encoding and decoding of the payload is performed by the plugin itself according to its own data format representation. Every plugin exposes the necessary functionality to seamlessly integrate its events with Falco.

Docs: gVisor

Mon, 01 Jan 0001 00:00:00 +0000

The gVisor engine has been deprecated in Falco 0.43.0 and will be removed in a future release. Until removal and since Falco 0.43.0, using it will result in a warning informing the user about the deprecation. Users are encouraged to switch to another engine, such as the modern eBPF probe, as the usage will result in an error after the removal.

Falco can work with gVisor.

gVisor, quoting the official documentation, is an application kernel that provides an additional layer of isolation between running applications and the host operating system. It delivers an additional security boundary for containers by intercepting and monitoring workload runtime instructions in user space before they can reach the underlying host.

How Falco and gVisor work together

When running containers with gVisor, there are several components that interact with our workload:

The Sentry is the gVisor component that implements all the application kernel functionalities. Whenever a syscall gets executed inside the sandboxed application, the Sentry will manage it as usual, plus it will send a message to Falco through a UDS (Unix Domain Socket).

Messages are serialized through Protocol Buffers so that gVisor and Falco can communicate even if they are written in different programming languages.

Setup gVisor Docker sandbox monitoring with Falco

First, install Falco and install the gVisor runsc tool. Any version of runsc released in 2023 or later is compatible with Falco.

gVisor needs to be configured to send events to Falco. Generate the appropriate configuration file:

falco --gvisor-generate-config > /tmp/runsc_falco_config.json
sudo mv /tmp/runsc_falco_config.json /etc/docker/runsc_falco_config.json

# Don't forget to protect this configuration
sudo chmod 640 /etc/docker/runsc_falco_config.json

The easiest way to run a gVisor sandbox is by using Docker. You need to first configure Docker to work with gVisor via runsc install, and then we're going to update the runsc pod init config configuration for our Docker containers:

sudo -e /etc/docker/daemon.json

Then, add the runtimeArgs key with the --pod-init-config= parameter like in the example below:

{
 "runtimes": {
 "runsc": {
 "path": "/usr/local/bin/runsc",
 "runtimeArgs": [
 "--pod-init-config=/etc/docker/runsc_falco_config.json"
 ]
 }
 }
}

Then, restart the Docker daemon to let it use the new configuration:

sudo systemctl restart docker

Run Falco by command line

Simply run Falco by the command line:

sudo falco -o "engine.kind=gvisor" -o "engine.gvisor.config=/etc/docker/runsc_falco_config.json"

or edit the file /etc/falco/falco.yaml to have these settings and run Falco with sudo falco:

engine:
 kind: gvisor
 gvisor:
 config: "/etc/docker/runsc_falco_config.json"

You're now monitoring your gVisor sandboxes.

Permanent configuration with Systemd

Alternatively, for a more permanent configuration:

sudo mkdir /etc/systemd/system/falco.service.d
cat << EOF | sudo tee /etc/systemd/system/falco.service.d/gvisor.conf
[Service]
ExecStartPre=
ExecStopPost=
ExecStart=
ExecStart=/usr/bin/falco -o "engine.kind=gvisor" -o "engine.gvisor.config=/etc/docker/runsc_falco_config.json"
EOF

sudo systemctl daemon-reload
sudo systemctl restart falco

Falco will load the configuration indicating it with a line similar to:

Thu Jul 21 15:41:58 2022: Enabled event collection from gVisor. Configuration path: /etc/docker/runsc_falco_config.json

Test the detection

Run any container with gVisor:

sudo docker run --runtime=runsc -it ubuntu bash

The container will start properly configured to be monitored by Falco.

To test the detection capabilities, try to trigger a simple rule like Read sensitive file untrusted:

cat /etc/shadow

You will see Falco alerting:

16:01:49.596019827: Warning Sensitive file opened for reading by non-trusted program (file=/etc/shadow gparent=<NA> ggparent=<NA> gggparent=<NA> evt_type=openat user=root user_uid=0 user_loginuid=-1 process=cat proc_exepath=/usr/bin/cat parent=<NA> command=cat /etc/shadow terminal=0 container_id=797eed9cf9c7 container_name=pedantic_elgamal)

Falco and gVisor on Kubernetes with GKE

gVisor can be used to sandbox pods on GKE for higher security. If your cluster has node pools with gVisor support enabled and k8s version at least 1.24.4-gke.1800 or 1.25.0-gke.200, you can deploy an instance of Falco to monitor them via the Helm chart.

helm install falco-gvisor falcosecurity/falco -f https://raw.githubusercontent.com/falcosecurity/charts/master/charts/falco/values-gvisor-gke.yaml --namespace falco-gvisor --create-namespace

Note that this Falco instance is completely independent of other Falco instances that you might have that monitor your regular nodes (w/o gVisor sandboxing), so you can decide whether you want to monitor regular node pools, gVisor-enabled node pools or both.

For more information about these use cases and more check out the related sections of the Falco Helm chart documentation.

Limitations and syscall support

Falco supports many system call events but gVisor does not support all of them. The most important events used in the default rulesets are covered and enough information flows about processes, file descriptors, and connections to maintain consistency of the data throughout the analysis and rule are processed anyway.

Webinar

A CNCF Webinar has been recorded by the Falco authors and Google to explain all the steps above:

Some information in this webinar may be outdated, it gives anyway a good overview of the principle