Falco – The Falco Project

Docs: Performance

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

First and foremost, if something goes seriously wrong during Falco deployment, it's usually noticeable immediately. On a longer time scale, continuous performance monitoring and quality assurance, driven by the right metrics, ensure Falco functions as expected 24/7.

As a security tool, Falco requires checking for a healthy deployment on multiple dimensions:

Resource utilization and system impact: Strive to minimize compute overhead while ensuring the desired monitoring scope is achieved.
Disruption/upgrades: Ensure minimal downtime and avoid interruptions to the service, minimizing restarts.
Data quality assurance: Verify that Falco outputs contain the desired quality with little to no missing data.
End-to-end data pipeline testing: Ensure alerts reach their end destination as quickly as possible.
Security monitoring capabilities: Adopting the right Falco rules and resilience to bypasses by attackers.

The Falco Project provides guidance on some of these aspects, and there are ongoing long-term efforts, including a partnership with the CNCF TAG Environmental Sustainability, aimed at enhancing Falco's performance and assessing its impact on the system. These efforts are intended to make it easier for adopters to assess the actual impact on their systems, enabling them to make informed decisions about the cost-security monitoring tradeoffs.

Resource Utilization and System Impact

The Falco Project provides native support for measuring resource utilization and statistics, including event drop counters, kernel tracepoint invocation counters, timeouts, and internal state handling. More detailed information is given in the Falco Metrics Guide.

CPU and Memory Utilization

On top of the mind for SREs or system admins is how much CPU and memory Falco will utilize on their hosts. They need to assess whether the cost is justified. To maintain excellent relationships with infrastructure teams, setting resource limits for your Falco deployment is crucial. This can be done through systemd or daemonset limits in a Kubernetes environment.

This is an essential consideration because running a kernel tool always comes with specific challenges and considerations. For example, it could slow down the kernel or the request rates of applications.

Top metrics:

CPU usage: Typically measured as a percentage of one CPU, it can be compared with the number of available CPUs on the host. Falco's hot path is single-threaded, so it should not be able to exceed the capacity of one full CPU.
Memory RSS: Resident Set Size is the portion of memory held in RAM by a process.
Memory VSZ: Virtual Memory Size is the total memory allocated to a process, including both RAM and swap space.
container_memory_working_set_bytes in Kubernetes settings: This is almost equivalent to the cgroups container memory_used metric natively exposed in Falco metrics.

Beyond monitoring the tool's utilization, check if your applications perform as before. This evaluation could include overall network, I/O, or general contention metrics.

Read Falco Metrics next.

Server Load and Falco Event Drops

A common misconception is to think that Falco has constant resource utilization. However, that is not accurate. Falco's utilization is directly dependent on the current workload on the host. The more system calls the applications make, the more work Falco has to handle. You can read our Kernel Testing Framework Proposal for more insights into this topic.

Read Falco Is Dropping Syscalls Events next.

Top metrics:

Kernel side and userspace event counts.
Kernel side and userspace event drop counts.
Kernel tracepoint invocation counts to deduce the overall server load.
Userspace timeouts.
Falco internal state counters.

Docs: Deploy on Kubernetes with the Operator

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

The Falco Operator is the recommended way to deploy and manage Falco on Kubernetes. It provides a declarative, Kubernetes-native experience for managing Falco instances, detection rules, plugins, and configuration through Custom Resources.

Going forward, the Falco Operator will become the standard deployment method for Falco on Kubernetes. The existing Helm chart remains fully supported during the transition period.

Overview

The Falco Operator manages the full Falco ecosystem through Kubernetes Custom Resources:

Falco Operator - Manages Falco instances (DaemonSet or Deployment mode) and ecosystem components
Artifact Operator - Manages rules, plugins, and configuration fragments (runs as a sidecar in each Falco pod)

The operator uses five Custom Resource Definitions (CRDs) across two API groups:

CRD	API Group	Purpose
`Falco`	`instance.falcosecurity.dev/v1alpha1`	Define and manage a Falco instance
`Component`	`instance.falcosecurity.dev/v1alpha1`	Deploy ecosystem components (Falcosidekick, Falcosidekick UI, k8s-metacollector)
`Rulesfile`	`artifact.falcosecurity.dev/v1alpha1`	Manage detection rules (OCI, inline YAML, or ConfigMap)
`Plugin`	`artifact.falcosecurity.dev/v1alpha1`	Manage Falco plugins from OCI registries
`Config`	`artifact.falcosecurity.dev/v1alpha1`	Manage configuration fragments (inline YAML or ConfigMap)

Prerequisites

Kubernetes 1.29+ (native sidecar support required)
kubectl installed and configured
Cluster admin privileges (for CRD and ClusterRole installation)

Install the Operator

Install the Falco Operator with a single command:

VERSION=latest
if [ "$VERSION" = "latest" ]; then
 kubectl apply --server-side -f https://github.com/falcosecurity/falco-operator/releases/latest/download/install.yaml
else
 kubectl apply --server-side -f https://github.com/falcosecurity/falco-operator/releases/download/${VERSION}/install.yaml
fi

This creates:

5 CRDs
The falco-operator namespace
A ServiceAccount, ClusterRole, and ClusterRoleBinding
The operator Deployment

Verify the operator is running:

kubectl get pods -n falco-operator
kubectl wait pods --for=condition=Ready --all -n falco-operator

Full Stack Quickstart

Want to deploy the entire Falco ecosystem in one command? The quickstart manifest deploys everything in the falco namespace: Falco, detection rules, container and k8smeta plugins, Falcosidekick, Falcosidekick UI with Redis, k8s-metacollector, and the configuration to wire them all together:

VERSION=latest
if [ "$VERSION" = "latest" ]; then
 kubectl apply --server-side -f https://github.com/falcosecurity/falco-operator/releases/latest/download/quickstart.yaml
else
 kubectl apply --server-side -f https://github.com/falcosecurity/falco-operator/releases/download/${VERSION}/quickstart.yaml
fi

Verify everything is running:

kubectl get falco,plugins,rulesfiles,configs,components -n falco
kubectl get pods -n falco

All resources should show Reconciled: True and Available: True. All pods should be Running.

To uninstall (order matters - artifacts first so the sidecar can process finalizer cleanup):

# 1. Artifacts first
kubectl delete configs,rulesfiles,plugins --all -n falco
# 2. Instances and components
kubectl delete components,falcos --all -n falco
# 3. Infrastructure
kubectl delete statefulset falcosidekick-ui-redis -n falco
kubectl delete svc falcosidekick-ui-redis -n falco
# 4. Namespace
kubectl delete namespace falco

To configure Falcosidekick outputs (Slack, Elasticsearch, S3, etc.), see the Falcosidekick documentation.

If you prefer to deploy components individually and customize each one, follow the step-by-step quickstart below.

Step-by-Step Quickstart

Deploy Falco

Create a Falco instance with default settings (DaemonSet mode, modern_ebpf driver):

cat <<EOF | kubectl apply -f -
apiVersion: instance.falcosecurity.dev/v1alpha1
kind: Falco
metadata:
 name: falco
spec: {}
EOF

Check that Falco pods are running on your nodes:

kubectl get falco
kubectl get pods -l app.kubernetes.io/name=falco

Falco starts in idle mode until you provide detection rules. The next steps add the container plugin and rules to activate monitoring.

Add the Container Plugin

The official Falco rules use fields like container.id and container.image.repository that require the container plugin. Without it, rules referencing container metadata fields will not work. Always load the container plugin before adding rules.

cat <<EOF | kubectl apply -f -
apiVersion: artifact.falcosecurity.dev/v1alpha1
kind: Plugin
metadata:
 name: container
spec:
 ociArtifact:
 image:
 repository: falcosecurity/plugins/plugin/container
 tag: latest
 registry:
 name: ghcr.io
EOF

Add Detection Rules

Load the official Falco rules from the OCI registry:

cat <<EOF | kubectl apply -f -
apiVersion: artifact.falcosecurity.dev/v1alpha1
kind: Rulesfile
metadata:
 name: falco-rules
spec:
 ociArtifact:
 image:
 repository: falcosecurity/rules/falco-rules
 tag: latest
 registry:
 name: ghcr.io
 priority: 50
EOF

Check the rulesfile status:

kubectl get rulesfiles

Falco will automatically pick up the rules and start monitoring.

The registry.name field defaults to ghcr.io when omitted. The image.tag field defaults to latest.

Rules can also come from inline YAML or Kubernetes ConfigMaps. See the Rulesfile CRD reference for all options.

Add Other Plugins

Load additional plugins from OCI registries. For example, the k8saudit plugin for Kubernetes audit log monitoring:

cat <<EOF | kubectl apply -f -
apiVersion: artifact.falcosecurity.dev/v1alpha1
kind: Plugin
metadata:
 name: k8saudit
spec:
 ociArtifact:
 image:
 repository: falcosecurity/plugins/plugin/k8saudit
 tag: latest
 registry:
 name: ghcr.io
EOF

See the Plugin CRD reference for configuration options.

Add Ecosystem Components

The operator can deploy ecosystem components alongside Falco using the Component CRD.

Falcosidekick

Deploy Falcosidekick to route Falco events to 70+ integrations:

cat <<EOF | kubectl apply -f -
apiVersion: instance.falcosecurity.dev/v1alpha1
kind: Component
metadata:
 name: sidekick
spec:
 component:
 type: falcosidekick
 replicas: 2
EOF

Then configure Falco to send events to Falcosidekick:

cat <<EOF | kubectl apply -f -
apiVersion: artifact.falcosecurity.dev/v1alpha1
kind: Config
metadata:
 name: sidekick-output
spec:
 config:
 json_output: true
 http_output:
 enabled: true
 url: "http://sidekick:2801"
 priority: 60
EOF

Falcosidekick UI

Deploy the web dashboard for event visualization. Requires a Redis instance:

cat <<EOF | kubectl apply -f -
apiVersion: instance.falcosecurity.dev/v1alpha1
kind: Component
metadata:
 name: sidekick-ui
spec:
 component:
 type: falcosidekick-ui
 replicas: 2
EOF

Falcosidekick UI requires an external Redis instance. If Redis is not available, pods will stay in Init:0/1 state until Redis becomes reachable. See the Component CRD reference for a complete example with a bundled Redis StatefulSet.

k8s-metacollector

Deploy the centralized Kubernetes metadata collector:

cat <<EOF | kubectl apply -f -
apiVersion: instance.falcosecurity.dev/v1alpha1
kind: Component
metadata:
 name: metacollector
spec:
 component:
 type: metacollector
 replicas: 1
EOF

Customize Configuration

Override Falco configuration with Config resources:

cat <<EOF | kubectl apply -f -
apiVersion: artifact.falcosecurity.dev/v1alpha1
kind: Config
metadata:
 name: custom-config
spec:
 config:
 engine:
 kind: modern_ebpf
 modern_ebpf:
 buf_size_preset: 4
 output_timeout: 2000
 priority: 50
EOF

Configuration fragments are applied in priority order (0–99) and merged with the base configuration. You can target specific nodes using label selectors. See the Config CRD reference.

Deployment Modes

The operator supports two deployment modes:

DaemonSet (default)

Runs Falco on every node for cluster-wide syscall monitoring using the modern_ebpf driver. This is the standard deployment for runtime security.

spec:
 type: DaemonSet

Deployment

Runs Falco as a regular Deployment instead of a DaemonSet.

spec:
 type: Deployment
 replicas: 2

Uninstall

Remove resources in the correct order, artifacts first (so the sidecar can clean up finalizers), then instances, then the operator:

# 1. Remove artifact resources first
kubectl delete rulesfiles --all --all-namespaces
kubectl delete plugins --all --all-namespaces
kubectl delete configs --all --all-namespaces

# 2. Remove instance resources
kubectl delete components --all --all-namespaces
kubectl delete falco --all --all-namespaces

# 3. Remove the operator and CRDs
kubectl delete -f https://github.com/falcosecurity/falco-operator/releases/latest/download/install.yaml

Deleting Falco instances before artifacts will terminate the Artifact Operator sidecar, leaving artifact finalizers unresolved. Always delete artifact resources (Rulesfile, Plugin, Config) before Falco instances.

Learn More

For complete documentation, including the CRD reference, architecture overview, migration guide, and contributing instructions, visit the Falco Operator repository.

Resource	Link
Full documentation	github.com/falcosecurity/falco-operator/docs
CRD reference	Falco, Rulesfile, Plugin, Config, Component
Architecture	Architecture overview
Sample manifests	config/samples/

Docs: Plugins Architecture Concepts

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

Overview

Plugins are dynamic shared libraries (.so files in Unix, .dll files in Windows) that export C calling convention functions. Programs like Falco dynamically load these libraries and call the exported functions to extend Falco's support for event sources/fields.

Plugins are versioned using semantic versioning to minimize regressions and compatibility issues.

Plugins can be written in any language, as long as they export the required functions. Go, however, is the preferred language to write plugins, followed by C/C++.

Plugins can implement one or more capabilities. In the scope of plugins, a capability is an extension of Falco's features in the form of a specific set of C function symbols exported by shared libraries. Currently, there are four plugin capabilities supported by the framework: event sourcing, field extraction, event parsing and async event

Plugins are Coresident with Falco

The libraries will do everything possible to validate the data coming from the plugins and protect Falco and the other consumers from corrupted data. However, for performance reasons, plugins are "trusted": they run in the same thread and address space as Falco and they could crash the program. We assume that the user will be in control of plugin loading and will make sure only trusted plugins are loaded/packaged with Falco.

Plugin SDKs

To make it easier to write plugins, there are Go, C++, and Rust SDKs that handle the details of memory management and type conversion. These SDKs provide a streamlined way to implement plugins without having to deal with all the details of the lower-level functions that make up the Plugin API.

These SDKs are optional, but using them is highly recommended.

Event Sourcing Capability

Plugins with event sourcing capability provide a new event source and make it available to libscap and libsinsp. They have the ability to "open" and "close" a stream of events and return those events to the plugin framework. They also provide a plugin ID, which is globally unique and is used in capture files (see below). Event sources provided by plugins with this capability are tied to the events they generate and can be used by plugins with field extraction capabilities and within Falco rules (see below).

Field Extraction Capability

Plugins with field extraction capability have the ability to extract information from events based on fields. For example, a field (e.g. proc.name) extracts a value (e.g. process name like nginx) from a syscall event. The plugin returns a set of supported fields, and there are functions to extract a value given an event and field. The plugin framework can then build filtering expressions (e.g. rule conditions) based on these fields combined with relational and/or logical operators. For example, given the expression ct.name=root and ct.region=us-east-1, the plugin framework handles parsing the expression, calling the plugin to extract values for fields ct.name/ct.region for a given event, and determining the result of the expression. In a Falco output string like An EC2 Node was created (name=%ct.name region=%ct.region), the plugin framework handles parsing the output string, calling the plugin to extract values for fields, and building the resolved string, replacing the template field names (e.g. %ct.region) with values (e.g. us-east-1).

Plugins with this capability only focus on field extraction from events generated by other plugins or by the core libraries. They do not provide an event source but can extract fields from other event sources. The supported field extraction can be generic or be tied to a specific event source. An example is json field extraction, where a plugin might be able to extract fields from generic json payloads.

Event Parsing Capability

Plugins with event parsing capability can hook into an event stream and receive all of its events sequentially. The parsing phase is the stage in the event processing loop in which the Falcosecurity libraries inspect the content of the events' payload and use it to apply internal state updates or implement additional logic. This phase happens before any field extraction for a given event. Each event in a given stream is guaranteed to be received at most once.

Async Events Capability

Plugins with async events capability can enrich an event stream from a given source (not necessarily implemented by itself) by injecting events asynchronously in the stream. Such a feature can be used for implementing notification systems or recording state transitions in the event-driven model of the Falcosecurity libraries, so that they can be available to other components at runtime or when the event stream is replayed through a capture file.

For example, the Falcosecurity libraries leverage this feature internally to implement metadata enrichment systems such as the one relative to container runtimes. In that case, the libraries implement asynchronous jobs responsible of retrieving such information externally outside of the main event processing loop so that it's non-blocking. The worker jobs produce a notification event every time a new container is detected and inject it asynchronously in the system event stream to be later processed for state updates and for evaluating Falco rules.

Composability of Capabilities

Plugin capabilities are composable, meaning that a single plugin can implement one or more capabilities. At loading time, the framework is able to recognize which capabilities the plugin correctly implements, and uses it accordingly inside Falco and the libraries. There can be plugins implementing event sourcing only, field extraction only, or both. For example, the AWS CloudTrail plugin implements both capabilities in order to provide the framework with the aws_cloudtrail event source and to allow extracting fields such as ct.name from the events it produces.

Plugin Event IDs

Every plugin with event sourcing capability requires its own, unique plugin event ID to interoperate with Falco and the other plugins. This ID is used in the following ways:

The ID is saved in in-memory event objects and is used to identify the associated plugin that injected the event.
The ID is saved in capture files and is used to recreate in-memory event objects when reading capture files.

The ID must be unique to ensure that events written by a given plugin will be properly associated with that plugin (and its event sources, see below).

Plugin authors must register the plugin with the Falcosecurity organization by creating a PR to modify the plugin registry with details on the new plugin. This ensures that a given ID is used by exactly one plugin.

Plugin Event Sources and Interoperability

Events returned by plugins with event sourcing capability have an event source that describes the event's information. This is distinct from the plugin name to allow for multiple plugin implementations to generate the same kind of events. For example, there might be plugins gke-k8saudit, eks-k8saudit, ibmcloud-k8saudit, etc. that all fetch K8s Audit information. The plugins would have different names and IDs but would have the same event source k8s_audit.

A plugin with field extraction capability optionally provides a set of compatible event sources. When the framework receives an event with an event source in the plugin's set of event sources, fields in expressions (i.e., fields included in the rule's output field) will be extracted from events using the plugin. The set of compatible event sources can also be omitted. In this case, all events will be presented to the plugin, regardless of their source. In this case, the plugin must detect the format of arbitrary payloads and be able to return NULL/no value when the payload is not supported. As such, given a specific event source such as k8s_audit, there is an implicit contract to honor regarding how data is formatted in each event of that source, such that compatible plugins with field extraction capability are able to parse events of a certain source even if they are produced by different plugins.

Plugin authors should register the plugin with the Falcosecurity organization by creating a PR to modify the plugin registry file with details on the new plugin. This allows plugin authors to coordinate about event source data formats.

Handling Duplicate/Overlapping Fields in Plugins/Libraries Core

At an initial glance, adding plugins introduces the possibility of tens/hundreds of new filtercheck fields that could potentially overlap/conflict. For example, what happens if a plugin defines a proc.name field? However, the notion of event source makes these potential conflicts manageable.

Remember that field extraction is always done in the context of an event, and each event can be mapped back to an event source. So we only need to ensure that filtercheck fields are non-overlapping for a given event source. For example, it's perfectly valid for an AWS CloudTrail plugin to define a proc.name field, as the events generated by that plugin are wholly separate from syscall events. For syscall events, the AWS CloudTrail plugin is not involved and the core libraries extract the process name for the tid performing a syscall. For AWS CloudTrail events, the core libraries are not involved in field extraction. Extraction is performed by the AWS CloudTrail plugin instead.

When managing plugins, we only need to ensure the following:

That only one plugin is loaded at a time that exports a given event source. For example, the libraries can load either a gke-k8saudit plugin with event source k8s_audit, or eks-k8saudit with event source k8s_audit, but not both.
That for a mix of plugins with event sourcing and field extraction capabilities having the same event source, that the fields are distinct. For example, a plugin event sourcing capability providing the source k8s_audit can export ka.* fields, and a plugin with field extractor capabilities with event source k8s_audit can export a jevt.value[/...] field, and the appropriate plugin will be used to extract fields from k8s_audit events as fields are parsed from condition expressions/output format strings.

Plugin API

Here is an overview of the functions that comprise the plugin API. This list is not extensive: the plugin API reference has full documentation of plugin APIs for all the capabilities supported by the framework.

In almost all cases, a plugin author can use the SDKs which provide a more streamlined interface. This still provides a good overview of the functionality a plugin provides.

Info Functions

A set of functions provide information about the plugin and its compatibility with the plugin framework:

plugin_get_required_api_version: Return the version of the plugin API used by a plugin.
plugin_get_name: Return the name of the plugin.
plugin_get_description: Return a short description of the plugin.
plugin_get_contact: Return a contact url/email/twitter account for the plugin authors.
plugin_get_version: Return the version of the plugin itself.
plugin_get_last_error: Return the error that was last generated by a plugin.
plugin_get_id: Return the unique ID of the plugin (event sourcing capability only).
plugin_get_event_source: Return a string describing the events generated by a plugin (event sourcing capability only).
plugin_get_async_events: Return a list of async events produced by a plugin (event parsing capability only).
plugin_get_init_schema: (Optional) Return a string describing a schema for the configuration passed to plugin_init.
plugin_list_open_params: (Optional) Return a list of suggested valid parameter values for plugin_open.
plugin_get_extract_event_sources: (Optional) Return a list of all compatible event sources (field extraction capability only).
plugin_get_extract_event_types: (Optional) Return a list of all compatible event types (field extraction capability only).
plugin_get_parse_event_sources: (Optional) Return a list of all compatible event sources (event parsing capability only).
plugin_get_parse_event_types: (Optional) Return a list of all compatible event types (event parsing capability only).
plugin_get_async_event_sources: (Optional) Return a list of all compatible event sources (async events capability only).

Instance/Capture Management Functions

Plugins have functions to initialize/destroy a plugin, as well as functions to open/close streams of events:

plugin_init: Initialize the plugin and, if needed, allocate its state.
plugin_destroy: Destroy the plugin and, if plugin state was allocated, free it.
plugin_open: Open the source and start a stream of events (event sourcing capability only).
plugin_close: Close a stream of events (event sourcing capability only).

Plugins with event sourcing capability have functions to provide events to the plugin framework:

plugin_next_batch: Return one or more events to the plugin framework.
plugin_get_progress: (Optional) Provide feedback on how much of the event stream has been read.
plugin_event_to_string: (Optional) Return a text representation of an event generated by a plugin.

Plugins with field extraction capability have functions to define the set of fields that can be used to extract information from events, to actually extract values from events, and to return printable representations of events:

plugin_get_fields: Return the list of extractor fields exported by a plugin.
plugin_extract_fields: Extract one or more filter field values from an event.

Other capabilities allow interacting with events for different scopes functionalities:

plugin_parse_event: Parses an event at most once before the extraction phase, and can perform state updates.
plugin_set_async_event_handler: Registers a callback that can be used to inject asynchronous events in an open event stream.

Docs: Basic Elements of Falco Rules

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

Rules

A rule is a YAML object, part of the rules file, whose definition contains at least the following fields:

- rule: shell_in_container
 desc: notice shell activity within a container
 condition: >
 (evt.type in (execve, execveat)) and
 container.id != host and
 (proc.name = bash or
 proc.name = ksh)
 output: >
 shell in a container |
 user=%user.name container_id=%container.id container_name=%container.name
 shell=%proc.name parent=%proc.pname cmdline=%proc.cmdline
 priority: WARNING

Conditions

The key part of a rule is the condition field. A condition is a Boolean predicate expressed using the condition syntax. It is possible to express conditions on all supported events using their respective supported fields.

Here's an example of a condition that alerts whenever a bash shell is run inside a container:

container.id != host and proc.name = bash

The first clause checks that the event happened in a container (where container.id is not equal to "host" as the event occurs in a container). The second clause checks that the process name is bash.

Since this condition does not include a clause with a system call it will only check event metadata.
Because of that, if a bash shell does start up in a container, Falco outputs events for every syscall that is performed by that shell.

If you want to be alerted only for each successful spawn of a shell in a container, add the appropriate event types to the condition:

(evt.type in (execve, execveat)) and container.id != host and proc.name = bash

Therefore, a complete rule using the above condition might be:

- rule: shell_in_container
 desc: notice shell activity within a container
 condition: >
 (evt.type in (execve, execveat)) and
 container.id != host and
 proc.name = bash
 output: >
 shell in a container |
 user=%user.name container_id=%container.id container_name=%container.name
 shell=%proc.name parent=%proc.pname cmdline=%proc.cmdline
 priority: WARNING

Conditions allow you to check for many aspects of each supported event.
To learn more, see the condition language.

Output

A rule output is a string that can use the same fields that conditions can use prepended by % to perform interpolation, akin to printf. For example:

Disallowed SSH Connection
(command=%proc.cmdline connection=%fd.name
user=%user.name user_loginuid=%user.loginuid container_id=%container.id
image=%container.image.repository)

could output:

Disallowed SSH Connection
(command=sshd connection=127.0.0.1:34705->10.0.0.120:22
user=root user_loginuid=-1 container_id=host
image=<NA>)

Outputs are usually written in a single line.
Modifying this output we try to present it to you in a more human-readable way.

Note that it's not necessary that all fields are set in the specific event. As you can see in the example above if the connection happens outside a container the field %container.image.repository would not be set and <NA> is displayed instead.

Outputs can also use the transform operators that are used in conditions. For example:

Disallowed SSH Connection
(command=%proc.cmdline connection=%fd.name
user=%toupper(user.name) user_loginuid=%user.loginuid container_id=%toupper(container.id)
image=%container.image.repository)

could output:

Disallowed SSH Connection
(command=sshd connection=127.0.0.1:34705->10.0.0.120:22
user=ROOT user_loginuid=-1 container_id=HOST
image=<NA>)

To learn more about how Falco processes the output and related settings, see the output formatting page.

Priority

Don't let the priority field name mislead you.
In a Falco Rule, it has nothing to do with overriding another rule or choosing the order in which rules will be triggered. The way to control the latter is achieved by changing the order the rules are defined and therefore loaded.

Every Falco rule has a priority which indicates how serious a violation of the rule is. This is similar to what we know as the severity of a syslog message. The priority is included in the message/JSON output/etc.

Here are the available priorities:

EMERGENCY
ALERT
CRITICAL
ERROR
WARNING
NOTICE
INFORMATIONAL
DEBUG

The general guidelines used to assign priorities to rules are the following:

If a rule is related to writing state (i.e. filesystem, etc.), its priority is ERROR.
If a rule is related to an unauthorized read of state (i.e. reading sensitive files, etc.), its priority is WARNING.
If a rule is related to unexpected behavior (spawning an unexpected shell in a container, opening an unexpected network connection, etc.), its priority is NOTICE.
If a rule is related to behaving against good practices (unexpected privileged containers, containers with sensitive mounts, running interactive commands as root), its priority is INFO.

One exception is that the rule "Run shell untrusted", which is fairly FP-prone, has a priority of DEBUG.

Advanced Rule Syntax

A Falco rule can contain several of the following keys:

Key	Required	Description	Default
`rule`	yes	A short, unique name for the rule.
`condition`	yes	A filtering expression that is applied against events to check whether they match the rule.
`desc`	yes	A longer description of what the rule detects.
`output`	yes	Specifies the message that should be output if a matching event occurs. See output.
`priority`	yes	A case-insensitive representation of the severity of the event. Should be one of the following: `emergency`, `alert`, `critical`, `error`, `warning`, `notice`, `informational`, `debug`.
`exceptions`	no	A set of exceptions that cause the rule to not generate an alert.
`enabled`	no	If set to `false`, a rule is neither loaded nor matched against any events.	`true`
`tags`	no	A list of tags applied to the rule (more on this here).
`warn_evttypes`	no	If set to `false`, Falco suppresses warnings related to a rule not having an event type (more on this here).	`true`
`skip-if-unknown-filter`	no	If set to `true`, if a rule conditions contains a filtercheck, e.g. `fd.some_new_field`, that is not known to this version of Falco, Falco silently accepts the rule but does not execute it; if set to `false`, Falco reports an error and exits when finding an unknown filtercheck.	`false`
`source`	no	The event source for which this rule should be evaluated. Typical values are `syscall`, `k8s_audit`, or the source advertised by a source plugin.	`syscall`

Macros

Macros provide a way to define common sub-portions of rules in a reusable way.

By looking at the condition above it looks like both evt.type in (execve, execveat) and container.id != host would be used by many other rules, so to make our job easier we can easily define macros for both:

- macro: container
 condition: (container.id != host)

- macro: spawned_process
 condition: (evt.type in (execve, execveat))

With these macros defined, we can then rewrite the above rule's condition as spawned_process and container and proc.name = bash.

- rule: shell_in_container
 desc: notice shell activity within a container
 condition: >
 spawned_process and
 container and
 proc.name = bash
 output: >
 shell in a container |
 user=%user.name container_id=%container.id container_name=%container.name
 shell=%proc.name parent=%proc.pname cmdline=%proc.cmdline
 priority: WARNING

For more examples of rules and macros, take a look the documentation on default macros and the rules/falco_rules.yaml file. In fact, both the macros above are part of the default list!

Macros can contain other macros that had been previously defined.

Lists

Lists are named collections of items that you can include in rules, macros, or even other lists.

Please note that lists cannot be parsed as filtering expressions.

Each list node has the following keys:

Key	Description
`list`	The unique name for the list (as a slug)
`items`	The list of values

Here are some example lists as well as a macro that uses them:

- list: shell_binaries
 items: [bash, csh, ksh, sh, tcsh, zsh, dash]

- list: userexec_binaries
 items: [sudo, su]

- list: known_binaries
 items: [shell_binaries, userexec_binaries]

- macro: safe_procs
 condition: proc.name in (known_binaries)

Lists can contain other lists that had been previously defined.

Referring to a list inserts the list items in the macro, rule, or list. Therefore, our rule could become more general replacing proc.name = bash with proc.name in (shell_binaries), or even better, using the already included macro shell_procs:

- list: shell_binaries
 items: [bash, csh, ksh, sh, tcsh, zsh, dash]

- macro: shell_procs
 condition: proc.name in (shell_binaries)

- rule: shell_in_container
 desc: notice shell activity within a container
 condition: >
 spawned_process and
 container and
 shell_procs
 output: >
 shell in a container |
 user=%user.name container_id=%container.id container_name=%container.name
 shell=%proc.name parent=%proc.pname cmdline=%proc.cmdline
 priority: WARNING

Visibility

As mentioned above, lists can reference other lists, and macros can reference other macros. The only requirement is that to reference an object of the same kind (a list including another list, or a macro including another macro) they must have been defined previously.

However, if a macro included a list, this list might have been defined earlier or be defined at a later stage in the rules files. The same happens with a rule referencing a macro. This one doesn't need to be previously defined.

In other words, visibility is defined in cascade and is quite important:

A list can only reference lists defined before it.
A macro can only reference macros defined before it.
A macro can reference any list.
A rule can reference any macro.

The same load-order principle applies across multiple rules files. See Overriding Rules for details on how the order of rules files affects appending and overriding existing lists, macros, and rules.

Docs: Build Falco from source

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

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.

Install the dependencies

CentOS 8 Stream / RHEL 8

dnf install git gcc gcc-c++ make cmake elfutils-libelf-devel perl-IPC-Cmd

apt update && apt install git cmake clang build-essential linux-tools-common linux-tools-generic libelf-dev bpftool

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

You'll also need kernel headers for building and making binaries properly.

pacman -S linux-headers

You can use uname -r to determine the kernel version and select the appropriate header.

Since Alpine ships with musl instead of glibc, to build on Alpine, we need to pass the -DMUSL_OPTIMIZED_BUILD=On CMake option.

If that option is used along with the -DUSE_BUNDLED_DEPS=On option, then the final build will be 100% statically-linked and portable across different Linux distributions.

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

zypper -n install git gcc12 gcc12-c++ cmake make libelf-devel gawk

Build Falco

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

More details here.

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

More details here.

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

More details here.

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

First, make sure that gcc and g++ are version 9 or above. If you have multiple versions installed you can set the preferred one.

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

More details here.

Build kernel module driver

In the build directory:

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

More details here.

Kernel headers are required to build the driver.

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

In the build directory:

make driver

In the build directory:

pacman -S --needed linux-headers
make driver

More details here.

NO STEP

In the build directory:

zypper -n install kernel-default-devel
make driver

Build eBPF driver (deprecated)

If you do not want to use the kernel module driver you can, alternatively, build the eBPF driver as follows.

In the build directory:

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

If you do not want to use the kernel module driver you can, alternatively, build the eBPF driver as follows.

In the build directory:

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

If you do not want to use the kernel module driver you can, alternatively, build the eBPF driver as follows.

In the build directory:

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

NO STEP

If you do not want to use the kernel module driver you can, alternatively, build the eBPF driver as follows.

In the build directory:

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.

Build Falco

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.

Create the build directory and enter in it
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
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 eBPF 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.43.0-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 eBPF support

-DBUILD_BPF=True

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

make bpf

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.

Docs: Output Channels

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

Standard Output

When configured to send alerts via standard output, a line is printed for each alert.

Here is an example:

stdout_output:
 enabled: true

10:20:05.408091526: Warning Sensitive file opened for reading by non-trusted program (user=root command=cat /etc/shadow file=/etc/shadow)

Standard output is useful when using Fluentd or Logstash to capture logs from containers. Alerts can then be stored in Elasticsearch, and dashboards can be created to visualize the alerts. For more information, read this blog post.

Standard Output buffering

If the logs are inspected by tailing container logs (e.g. kubectl logs -f in Kubernetes) it might look like events can take a long time to appear, sometimes longer than 15 minutes. This is not an issue with Falco but is simply a side effect of the system output buffering.

However, if realtime update of these logs is necessary it can be forced with the -U/--unbuffered command line option which will ensure the output is flushed for every event at the cost of higher CPU usage.

File Output

When configured to send alerts to a file, a message is written to the file for each alert. The configuration is very similar to the Standard Output format:

file_output:
 enabled: true
 keep_alive: false
 filename: ./events.txt

When the field keep_alive is set to false (default value), for each single alert:

the file is opened for appending
the single alert is written
the file is closed

If keep_alive is set to true, the file is opened before the first alert, and kept open for all subsequent alerts. Output is buffered and will be flushed only on close. (This can be changed with the --unbuffered command line option).

Notice that, regardless keep_alive settings, Falco neither rotates nor truncates the output file. If you'd like to use a program like logrotate to rotate the output file, an example logrotate config is available here.

As of Falco 0.10.0, Falco will close and reopen its file output when signaled with SIGUSR1. The logrotate example above depends on it.

Syslog Output

When configured to send alerts to syslog, a syslog message is sent for each alert. The actual format depends on your syslog daemon, but here's a simple configuration example:

syslog_output:
 enabled: true

And its respective entry in the syslog service:

Jun 7 10:20:05 ubuntu falco: Sensitive file opened for reading by non-trusted program (user=root command=cat /etc/shadow file=/etc/shadow)

Syslog messages are sent with a facility of LOG_USER.
The rule's priority is used as the priority of the syslog message.

Program Output

When configured to send alerts to a program, Falco normally starts the program for each alert and writes its contents to the program's standard input. You can only configure a single program output (e.g. route alerts to a single program) at a time.

Here you can find an example of how to configure the program_output inside the falco.yaml file:

program_output:
 enabled: true
 keep_alive: false
 program: mail -s "Falco Notification" someone@example.com

If the program cannot normally accept an input from standard input, xargs can be used to pass the Falco events with an argument. For example:

program_output:
 enabled: true
 keep_alive: false
 program: "xargs -I {} aws --region ${region} sns publish --topic-arn ${falco_sns_arn} --message {}"

When keep_alive is set to false (default value), for each alert Falco will run the program mail -s ... and write the alert to the program. The program is run via a shell, so it's possible to specify a command pipeline if you wish to add additional formatting.

If keep_alive is set to true, before the first alert Falco will spawn the program and write the alert. The program pipe will be kept open for subsequent alerts. Output is buffered and will be flushed only on close. (This can be changed with the --unbuffered command line option).

Controlling the program output

The program spawned by Falco is in the same process group as Falco and will receive all signals that Falco receives. If you want to, say, ignore SIGTERM to allow for a clean shutdown in the face of buffered outputs, you must override the signal handler yourself.
As of Falco 0.10.0, Falco will close and reopen its file output when signaled with SIGUSR1.

Example 1: Posting to a Slack Incoming Webhook

If you'd like to send Falco notifications to a slack channel, here's the required configuration to massage the JSON output to a form required for the slack webhook endpoint:

# Whether to output events in json or text
json_output: true
…
program_output:
 enabled: true
 program: "jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX"

Example 2: Sending Alerts to Network Channel

If you'd like to send a stream of alerts over a network connection, here's an example:

# Whether to output events in json or text
json_output: true
…
program_output:
 enabled: true
 keep_alive: true
 program: "nc host.example.com 1234"

Note the use of keep_alive: true to keep the network connection persistent.

HTTP/HTTPS Output

If you'd like to send alerts to an HTTP(S) endpoint, you can use the http_output option:

json_output: true
...
http_output:
 enabled: true
 url: http://some.url/some/path/

Currently, only unencrypted HTTP endpoints and valid HTTPS endpoints are supported (i.e., invalid or self-signed certificates are not supported).

JSON Output

For all output channels, you can switch to JSON output either in the configuration file or on the command line. For each alert, Falco will print a JSON object, on a single line, containing the following properties:

time: the time of the alert, in ISO8601 format.
rule: the rule that resulted in the alert.
priority: the priority of the rule that generated the alert.
output: the formatted output string for the alert.
hostname: the name of the host running Falco (can be the hostname inside the container).
tags: the list of tags associated with the rule.
output_fields: for each templated value in the output expression, the value of that field from the event that triggered the alert.

Notice that, besides the ones included automatically, you can also include additional fields to output_fields through append_output settings in the configuration.

Here's an example:

{"hostname":"falco-xczjd","output":"13:44:05.478445995: Critical A shell was spawned in a container with an attached terminal (user=root user_loginuid=-1 k8s.ns=default k8s.pod=kubecon container=ee97d9c4186f shell=sh parent=runc cmdline=sh -c clear; (bash || ash || sh) terminal=34816 container_id=ee97d9c4186f image=docker.io/library/alpine)","priority":"Critical","rule":"Terminal shell in container","source":"syscall","tags":["container","mitre_execution","shell"],"time":"2023-05-25T13:44:05.478445995Z", "output_fields": {"container.id":"ee97d9c4186f","container.image.repository":"docker.io/library/alpine","evt.time":1685022245478445995,"k8s.ns.name":"default","k8s.pod.name":"kubecon","proc.cmdline":"sh -c clear; (bash || ash || sh)","proc.name":"sh","proc.pname":"runc","proc.tty":34816,"user.loginuid":-1,"user.name":"root"}}

Here's the same output, pretty-printed:

{
 "hostname": "falco-xczjd",
 "output": "13:44:05.478445995: Critical A shell was spawned in a container with an attached terminal (user=root user_loginuid=-1 k8s.ns=default k8s.pod=kubecon container=ee97d9c4186f shell=sh parent=runc cmdline=sh -c clear; (bash || ash || sh) terminal=34816 container_id=ee97d9c4186f image=docker.io/library/alpine)",
 "priority": "Critical",
 "rule": "Terminal shell in container",
 "source": "syscall",
 "tags": [
 "container",
 "mitre_execution",
 "shell"
 ],
 "time": "2023-05-25T13:44:05.478445995Z",
 "output_fields": {
 "container.id": "ee97d9c4186f",
 "container.image.repository": "docker.io/library/alpine",
 "evt.time": 1685022245478445995,
 "k8s.ns.name": "default",
 "k8s.pod.name": "kubecon",
 "proc.cmdline": "sh -c clear; (bash || ash || sh)",
 "proc.name": "sh",
 "proc.pname": "runc",
 "proc.tty": 34816,
 "user.loginuid": -1,
 "user.name": "root"
 }
}

gRPC Output

The gRPC Output as well as the embedded gRPC server have been deprecated in Falco 0.43.0 and will be removed in a future release. Until removal and since Falco 0.43.0, using any of them will result in a warning informing the user about the deprecation. Users are encouraged to leverage another output and/or Falcosidekick, as the usage will result in an error after the removal.

If you'd like to send alerts to an external program connected via gRPC API, you need to enable both the grpc and grpc_output options as described under the gRPC Configuration section.

Docs: Configuration

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

Enabling the Server

The Falco gRPC server and the Falco gRPC Outputs APIs are not enabled by default.

To enable them, edit the falco.yaml Falco configuration file. A sample Falco configuration file is given below:

# Falco supports running a gRPC server with two main binding types
# 1. Over the network with mandatory mutual TLS authentication (mTLS)
# 2. Over a local unix socket with no authentication
# By default, the gRPC server is disabled, with no enabled services (see grpc_output)
# please comment/uncomment and change accordingly the options below to configure it.
# Important note: if Falco has any troubles creating the gRPC server
# this information will be logged, however the main Falco daemon will not be stopped.
# gRPC server over network with (mandatory) mutual TLS configuration.
# This gRPC server is secure by default so you need to generate certificates and update their paths here.
# By default the gRPC server is off.
# You can configure the address to bind and expose it.
# By modifying the threadiness configuration you can fine-tune the number of threads (and context) it will use.
grpc:
 enabled: true
 bind_address: "0.0.0.0:5060"
 threadiness: 8
 private_key: "/etc/falco/certs/server.key"
 cert_chain: "/etc/falco/certs/server.crt"
 root_certs: "/etc/falco/certs/ca.crt"

As you can see, binding to a network address requires you to generate and specify a set of TLS certificates as shown in the next section.

Alternatively, if you want something simpler, you can tell Falco to bind the gRPC server to a local unix socket, this does not require you to generate certificates for mTLS but also comes without any authentication mechanism.

# gRPC server using an unix socket
grpc:
 enabled: true
 bind_address: "unix:///run/falco/falco.sock"
 threadiness: 8

Then, remember to enable the services you need. Otherwise, the gRPC server won't expose anything.

For the outputs use:

# gRPC output service.
# By default it is off.
# By enabling this all the output events will be kept in memory until you read them with a gRPC client.
# Make sure to have a consumer for them or leave this disabled.
grpc_output:
 enabled: true

Certificates

When configured to bind to a network address, the Falco gRPC server works only with mutual TLS by design. Therefore, you have to generate the certificates and update the paths in the above configuration.

The Falco authors plan to automate the certificate generation soon.

In the meantime, use the following script to generate the certificates.

Note: Ensure that you configure the -passin, -passout, and -subj flags according to your settings.

Generate CA

Run the following commands:

$ openssl genrsa -des3 -passout pass:1234 -out ca.key 4096

$ openssl req -new \
 -x509 \
 -days 365 \
 -key ca.key \
 -out ca.crt \
 -passin pass:1234 \
 -subj "/C=SP/ST=Italy/L=Ornavasso/O=Test/OU=Test/CN=Root CA"

Generate Server Key/Cert

Run the following command:

$ openssl genrsa -des3 -passout pass:1234 -out server.key 4096

$ openssl req -new \
 -key server.key \
 -out server.csr \
 -passin pass:1234 \
 -subj "/C=SP/ST=Italy/L=Ornavasso/O=Test/OU=Server/CN=localhost"

$ openssl x509 -req \
 -days 365 \
 -CA ca.crt \
 -CAkey ca.key \
 -in server.csr \
 -out server.crt \
 -set_serial 01 \
 -passin pass:1234

Remove passphrase from Server Key

Run the following command:

$ openssl rsa -in server.key -out server.key -passin pass:1234

Generate Client Key/Cert

Run the following command:

$ openssl genrsa -des3 -passout pass:1234 -out client.key 4096

$ openssl req -new \
 -passin pass:1234 \
 -key client.key \
 -out client.csr \
 -subj "/C=SP/ST=Italy/L=Ornavasso/O=Test/OU=Client/CN=localhost"

$ openssl x509 -req \
 -days 365 \
 -CA ca.crt \
 -CAkey ca.key \
 -set_serial 01 \
 -in client.csr \
 -out client.crt \
 -passin pass:1234

Remove passphrase from Client Key

Run the following command:

$ openssl rsa -in client.key -out client.key -passin pass:1234

Usage

When the configuration is complete, Falco is ready to expose its gRPC server and its Outputs APIs.

To do so, simply run Falco. For example:

$ falco -c falco.yaml -r rules/falco_rules.yaml -r rules/falco_rules.local.yaml

Refer to the Go client documentation to learn how to receive and consume Falco output events.

Docs: Deploy on Kubernetes with Helm

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

The Falco Operator is now the recommended way to deploy Falco on Kubernetes. It provides a declarative, Kubernetes-native experience with Custom Resources for managing Falco instances, rules, plugins, and configuration. The Helm chart method described on this page remains fully supported.

Falco consumes streams of events and evaluates them against a set of security rules to detect abnormal behavior. By default, Falco is pre-configured to consume events from the Linux Kernel. This default installation scenario will add Falco to all nodes in your cluster using a DaemonSet. This scenario requires Falco to be privileged, and depending on the kernel version installed on the node, a driver will be installed on the node.

For other installation scenarios, such as consuming cloud events or other data sources using plugins, please refer to the Plugins section.

A well-established method to deploy Falco on a Kubernetes cluster is to use the provided Helm chart. The official Falco charts repository is hosted at:

https://falcosecurity.github.io/charts

If needed, you can consult the Installing Helm guide for information about how to download and install Helm. Before deploying Falco on Kubernetes, ensure you can access the targeted cluster running with Linux nodes, either x86_64 or ARM64. Also, you will need to have kubectl and helm installed and configured.

Alternatively, Falco can be installed in Kubernetes without Helm by providing manifest files and deploying them to your cluster. For details, see the example here.

Install

First, add the Helm repository:

helm repo add falcosecurity https://falcosecurity.github.io/charts
helm repo update

Then install Falco:

helm install --replace falco --namespace falco --create-namespace --set tty=true falcosecurity/falco

And check that the Falco pods are running:

kubectl get pods -n falco

Falco pod(s) might need a few seconds to start. Wait until they are ready:

kubectl wait pods --for=condition=Ready --all -n falco

Configuration

When deploying Falco via Helm, you will use Helm values to pass the Falco configuration. For further details, see the Falco Helm Chart documentation.

Upgrade

If you wish to upgrade Falco to a new version, you need to find the corresponding version in the Falco Helm Chart repository (e.g., 4.8.1 is for Falco 0.38.2) then run:

helm upgrade falco -n falco --version 4.8.1

To avoid any possible disruption, before upgrading to a new version, consult the Falco Helm chart Breaking Changes page.

Uninstall

If you wish to remove Falco from your cluster, you can simply run:

helm uninstall falco -n falco

Docs: How to develop a plugin

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

Introduction

This section explains how to develop a plugin from scratch with the official Go SDK.

We'll create a plugin for the docker events from a local docker daemon. It is a basic example of an event stream with a basic format and without specific authentication.

To know more about the available feature of the Go SDK and how to see use, you can refer to this page.

Awaited result

At the end, your plugin will allow you to get that kind of alerts:

2022-02-08T10:58:56.370816183+01:00 container create e327f1fa52a90d79421e416aed60e6de6872231f31101a1cc63401e90cef4bd6 (image=alpine, name=confident_kirch)
2022-02-08T10:58:56.371818906+01:00 container attach e327f1fa52a90d79421e416aed60e6de6872231f31101a1cc63401e90cef4bd6 (image=alpine, name=confident_kirch)
2022-02-08T10:58:56.482094215+01:00 network connect 5864a44bccca4e0963dfe9c3087919bf8f8e5c3aa7db33dd6d9ae7138c5ee3f3 (container=e327f1fa52a90d79421e416aed60e6de6872231f31101a1cc63401e90cef4bd6, name=bridge, type=bridge)
2022-02-08T10:58:56.804166856+01:00 container start e327f1fa52a90d79421e416aed60e6de6872231f31101a1cc63401e90cef4bd6 (image=alpine, name=confident_kirch)
2022-02-08T10:58:56.831912702+01:00 container die e327f1fa52a90d79421e416aed60e6de6872231f31101a1cc63401e90cef4bd6 (exitCode=0, image=alpine, name=confident_kirch)
2022-02-08T10:58:57.072125878+01:00 network disconnect 5864a44bccca4e0963dfe9c3087919bf8f8e5c3aa7db33dd6d9ae7138c5ee3f3 (container=e327f1fa52a90d79421e416aed60e6de6872231f31101a1cc63401e90cef4bd6, name=bridge, type=bridge)
2022-02-08T10:58:57.132390363+01:00 container destroy e327f1fa52a90d79421e416aed60e6de6872231f31101a1cc63401e90cef4bd6 (image=alpine, name=confident_kirch)

The Docker SDK

For reducing the complexity to communicate with the docker daemon, we'll use the official docker sdk.

Requirements

The only requirements for this examples are:

a docker daemon running in your local system
falco >=0.35 installed in your local system
go >= 1.19

Code Organization

To simplify contributions and keep a consistency between plugins, we propose a specific organization for the repositories of plugins:

.
├── LICENSE
├── Makefile
├── README.md
├──
├── go.mod
├── go.sum
├── pkg
│   └── docker.go
├── plugin
│   └── main.go
└── rules
 └── docker_rules.yaml

The directories:

pkg: Contains all modules for our plugin, we use a pkg folder because they might be imported and used by other plugins.
plugin: Contains the main.go of our plugin.
rules: Contains one or more .yaml files with default rules for the plugin.

The files:

LICENSE: The license file, most of the plugins are under Apache License 2.0.
README: The README, see in the repository for an example.
Makefile: Allows to easily build and install the plugin, see in the repository for an example.
falco.yaml: (optional) An example file with the minimal configuration to use the plugin.
rules/docker_rules.yaml: An example rule file, its name must respect <plugin_name>_rules.yaml.
go.mod, go.sum: Classic go module files.

The plugin codebase

plugin/main.go

This is the entrypoint of our plugin.

This is where we declare the details of our plugin:

package main

import (
 docker "github.com/Issif/docker-plugin/pkg"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/extractor"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/source"
)

const (
 PluginID uint32 = 5
 PluginName = "docker"
 PluginDescription = "Docker Events"
 PluginContact = "github.com/falcosecurity/plugins/"
 PluginVersion = "0.2.0"
 PluginEventSource = "docker"
)

func init() {
 plugins.SetFactory(func() plugins.Plugin {
 p := &docker.Plugin{}
 p.SetInfo(
 PluginID,
 PluginName,
 PluginDescription,
 PluginContact,
 PluginVersion,
 PluginEventSource,
 )
 extractor.Register(p)
 source.Register(p)
 return p
 })
}

func main() {}

Few requirements:

PluginID (Sourcing Capability Only) The ID field is mandatory and must be unique in the registry across all the plugins with event source capability
PluginName: The name field is mandatory and must be unique across all the plugins in the registry. The plugin name must match this regular expression: ^[a-z]+[a-z0-9-_\-]*$ (however, its not recommended to use _ in the name, unless you are trying to match the name of a source or for particular reasons)
PluginEventSource: The source (Sourcing Capability Only) and sources (Extraction Capability Only) must match this regular expression: ^[a-z]+[a-z0-9_]*$

The imports

Despite basic Go modules, we'll have to import the different plugin-sdk-go modules (>= 0.5.0) and other modules we need for our plugin:

import (
 docker "github.com/Issif/docker-plugin/pkg"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/extractor"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/source"
)

We'll import these different components of plugin-sdk-go in almost every plugin we'll write. They're really convenient and provide a much easier way to deal with the Falco plugin framework.

The const

const (
 ID uint32 = 5
 Name = "docker"
 Description = "Docker Events"
 Contact = "github.com/Issif/docker-plugin"
 Version = "0.2.0"
 EventSource = "docker"
)

The const are used to declare all mandatory information of our plugin through the docker.SetInfo() method:

ID: Must be unique among all plugins, it's used by the framework in captures to know which plugin is the source of events. It's also important for avoiding collisions if you want to share your plugin in the registry, see the main repository for more details.
Name: The name of our plugin, will be used in plugins section of falco.yaml. The plugin name must match this regular expression: ^[a-z]+[a-z0-9-_\-]*$ (however, its not recommended to use _ in the name, unless you are trying to match the name of a source or for particular reasons).
Description: The description of our plugin.
Contact: A contact link, often a link to the repository.
Version: All plugins must be versioned for compatibility with Falco, the versioning must follow the semantic versioning.
EventSource: This represents the value we'll set in Falco rules for mapping, in our case, all rules we'll set will have source: docker. The source must match this regular expression: ^[a-z]+[a-z0-9_]*$.

The functions

`main()`

The main() function is mandatory for any go program, but because we'll build the plugin as a library for the Falco plugin framework which is written in C, we can let it empty.

// main is mandatory but empty, because the plugin will be used as C library by Falco plugin framework
func main() {}

`init()`

The init() function is used for registering our plugin to the Falco plugin framework, as a source and an extractor. We also use it to set the info of the plugin:

func init() {
 plugins.SetFactory(func() plugins.Plugin {
 p := &docker.Plugin{}
 p.SetInfo(
 ID,
 Name,
 Description,
 Contact,
 Version,
 EventSource,
 )
 extractor.Register(p)
 source.Register(p)
 return p
 })
}

The init() contains also some specific functions and methods:

plugins.SetFactory() is a method to register our plugin to the framework
SetInfo() is a method to set the details of our plugin before it's registered to the Falco plugin framework
source.Register() allows to declare our plugin as a source to the framework, ie, a plugin to collect events from a source
extractor.Register() allows to declare our plugin as an extractor to the framework, ie, a plugin to extract fields from an event

pkg/docker.go

The module used by our main.go, it can also be imported by other plugins, especially when it's an extractor.

package docker

import (
 "context"
 "encoding/json"
 "fmt"
 "io"
 "io/ioutil"

 "github.com/alecthomas/jsonschema"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/source"

 dockerTypes "github.com/docker/docker/api/types"
 dockerEvents "github.com/docker/docker/api/types/events"
 docker "github.com/moby/docker/client"
)

var (
 ID uint32
 Name string
 Description string
 Contact string
 Version string
 EventSource string
)

type PluginConfig struct {
 FlushInterval uint64 `json:"flushInterval" jsonschema:"description=Flush Interval in ms (Default: 30)"`
}

// Plugin represents our plugin
type Plugin struct {
 plugins.BasePlugin
 Config PluginConfig
 lastDockerEventMessage dockerEvents.Message
 lastDockerEventNum uint64
}

// setDefault is used to set default values before mapping with InitSchema()
func (p *PluginConfig) setDefault() {
 p.FlushInterval = 30
}

// SetInfo is used to set the Info of the plugin
func (p *Plugin) SetInfo(id uint32, name, description, contact, version, eventSource string) {
 ID = id
 Name = name
 Contact = contact
 Version = version
 EventSource = eventSource
}

// Info displays information of the plugin to Falco plugin framework
func (p *Plugin) Info() *plugins.Info {
 return &plugins.Info{
 ID: ID,
 Name: Name,
 Description: Description,
 Contact: Contact,
 Version: Version,
 EventSource: EventSource,
 }
}

// InitSchema map the configuration values with Plugin structure through JSONSchema tags
func (p *Plugin) InitSchema() *sdk.SchemaInfo {
 reflector := jsonschema.Reflector{
 RequiredFromJSONSchemaTags: true, // all properties are optional by default
 AllowAdditionalProperties: true, // unrecognized properties don't cause a parsing failures
 }
 if schema, err := reflector.Reflect(&PluginConfig{}).MarshalJSON(); err == nil {
 return &sdk.SchemaInfo{
 Schema: string(schema),
 }
 }
 return nil
}

// Init is called by the Falco plugin framework as first entry,
// we use it for setting default configuration values and mapping
// values from `init_config` (json format for this plugin)
func (p *Plugin) Init(config string) error {
 p.Config.setDefault()
 return json.Unmarshal([]byte(config), &p.Config)
}

// Fields exposes to Falco plugin framework all availables fields for this plugin
func (p *Plugin) Fields() []sdk.FieldEntry {
 return []sdk.FieldEntry{
 {Type: "string", Name: "docker.status", Desc: "Status of the event"},
 {Type: "string", Name: "docker.id", Desc: "ID of the event"},
 {Type: "string", Name: "docker.from", Desc: "From of the event (deprecated)"},
 {Type: "string", Name: "docker.type", Desc: "Type of the event"},
 {Type: "string", Name: "docker.action", Desc: "Action of the event"},
 {Type: "string", Name: "docker.stack.namespace", Desc: "Stack Namespace"},
 {Type: "string", Name: "docker.node.id", Desc: "Swarm Node ID"},
 {Type: "string", Name: "docker.swarm.task", Desc: "Swarm Task"},
 {Type: "string", Name: "docker.swarm.taskid", Desc: "Swarm Task ID"},
 {Type: "string", Name: "docker.swarm.taskname", Desc: "Swarm Task Name"},
 {Type: "string", Name: "docker.swarm.servicename", Desc: "Swarm Service Name"},
 {Type: "string", Name: "docker.node.statenew", Desc: "Node New State"},
 {Type: "string", Name: "docker.node.stateold", Desc: "Node Old State"},
 {Type: "string", Name: "docker.attributes.container", Desc: "Attribute Container"},
 {Type: "string", Name: "docker.attributes.image", Desc: "Attribute Image"},
 {Type: "string", Name: "docker.attributes.name", Desc: "Attribute Name"},
 {Type: "string", Name: "docker.attributes.type", Desc: "Attribute Type"},
 {Type: "string", Name: "docker.attributes.exitcode", Desc: "Attribute Exit Code"},
 {Type: "string", Name: "docker.attributes.signal", Desc: "Attribute Signal"},
 {Type: "string", Name: "docker.scope", Desc: "Scope"},
 }
}

// Extract allows Falco plugin framework to get values for all available fields
func (p *Plugin) Extract(req sdk.ExtractRequest, evt sdk.EventReader) error {
 msg := p.lastDockerEventMessage

 // For avoiding to Unmarshal the same message for each field to extract
 // we store it with its EventNum. When it's a new event with a new message, we
 // update the Plugin struct.
 if evt.EventNum() != p.lastDockerEventNum {
 rawData, err := ioutil.ReadAll(evt.Reader())
 if err != nil {
 fmt.Println(err.Error())
 return err
 }

 err = json.Unmarshal(rawData, &msg)
 if err != nil {
 return err
 }

 p.lastDockerEventMessage = msg
 p.lastDockerEventNum = evt.EventNum()
 }

 switch req.Field() {
 case "docker.status":
 req.SetValue(msg.Status)
 case "docker.id":
 req.SetValue(msg.ID)
 case "docker.from":
 req.SetValue(msg.From)
 case "docker.type":
 req.SetValue(msg.Type)
 case "docker.action":
 req.SetValue(msg.Action)
 case "docker.scope":
 req.SetValue(msg.Scope)
 case "docker.actor.id":
 req.SetValue(msg.Actor.ID)
 case "docker.stack.namespace":
 req.SetValue(msg.Actor.Attributes["com.docker.stack.namespace"])
 case "docker.swarm.task":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.task"])
 case "docker.swarm.taskid":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.task.id"])
 case "docker.swarm.taskname":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.task.name"])
 case "docker.swarm.servicename":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.service.name"])
 case "docker.node.id":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.node.id"])
 case "docker.node.statenew":
 req.SetValue(msg.Actor.Attributes["state.new"])
 case "docker.node.stateold":
 req.SetValue(msg.Actor.Attributes["state.old"])
 case "docker.attributes.container":
 req.SetValue(msg.Actor.Attributes["container"])
 case "docker.attributes.image":
 req.SetValue(msg.Actor.Attributes["image"])
 case "docker.attributes.name":
 req.SetValue(msg.Actor.Attributes["name"])
 case "docker.attributes.type":
 req.SetValue(msg.Actor.Attributes["type"])
 default:
 return fmt.Errorf("no known field: %s", req.Field())
 }

 return nil
}

// Open is called by Falco plugin framework for opening a stream of events, we call that an instance
func (Plugin *Plugin) Open(params string) (source.Instance, error) {
 dclient, err := docker.NewClientWithOpts()
 if err != nil {
 return nil, err
 }

 eventC := make(chan source.PushEvent)
 ctx, cancel := context.WithCancel(context.Background())
 // launch an async worker that listens for Docker events and pushes them
 // to the event channel
 go func() {
 defer close(eventC)
 msgC, errC := dclient.Events(ctx, dockerTypes.EventsOptions{})
 var msg dockerEvents.Message
 var err error
 for {
 select {
 case msg = <-msgC:
 bytes, err := json.Marshal(msg)
 if err != nil {
 eventC <- source.PushEvent{Err: err}
 // errors are blocking, so we can stop here
 return
 }
 eventC <- source.PushEvent{Data: bytes}
 case err = <-errC:
 if err == io.EOF {
 // map EOF to sdk.ErrEOF, which is recognized by the Go SDK
 err = sdk.ErrEOF
 }
 eventC <- source.PushEvent{Err: err}
 // errors are blocking, so we can stop here
 return
 }
 }
 }()
 return source.NewPushInstance(eventC, source.WithInstanceClose(cancel))
}

// String represents the raw value of on event
// (not currently used by Falco plugin framework, only there for future usage)
func (Plugin *Plugin) String(in io.ReadSeeker) (string, error) {
 evtBytes, err := ioutil.ReadAll(in)
 if err != nil {
 return "", err
 }
 evtStr := string(evtBytes)
 return fmt.Sprintf("%v", evtStr), nil
}

The imports

Despite basic Go modules, we'll have to import the different modules from plugin-sdk-go and from Docker SDK to docker events:

import (
 "context"
 "encoding/json"
 "fmt"
 "io"
 "io/ioutil"

 "github.com/alecthomas/jsonschema"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/source"

 dockerTypes "github.com/docker/docker/api/types"
 dockerEvents "github.com/docker/docker/api/types/events"
 docker "github.com/moby/docker/client"
)

The global variables

Global variables are declared and filled with the SetInfo() method called by the init() of the main.go. These variables are then used to declare the details of the plugin to Falco:

var (
 ID uint32
 Name string
 Description string
 Contact string
 Version string
 EventSource string
)

The structures

The structure to declare the plugin is mandatory and must respect the interface declared in the SDK:

type PluginConfig struct {
 FlushInterval uint64 `json:"flushInterval" jsonschema:"description=Flush Interval in ms (Default: 30)"`
}

// Plugin represents our plugin
type Plugin struct {
 plugins.BasePlugin
 Config PluginConfig
 lastDockerEventMessage dockerEvents.Message
 lastDockerEventNum uint64
}

Plugin represents our plugin that will be loaded by the framework. It contains some fields:

plugins.BasePlugin: Allows to respect the Plugin interface of the SDK.
Config: Contains the configuration of our plugin, represented by the PluginConfig structure.
lastDockerEventMessage: Contains the result of the last unmarshalled event.
lastDockerEventNum: Contains the number of the unmarshalled event, by comparing it, we avoid to unmarshal the same event several times.

PluginConfig represents the configuration of our plugin, we'll use the module alecthomas/jsonschema to map the content of init_config from the plugin section of falco.yaml and check its validity:

plugins:
 - name: docker
 library_path: /etc/falco/audit/libdocker.so
 init_config: '{"flushinterval": 10}'
 open_params: ''

The functions and methods

`SetInfo()`

It's used to set the global variables which represent the details of our plugin, this method is called by the init() of the main.go:

// SetInfo is used to set the Info of the plugin
func (p *Plugin) SetInfo(id uint32, name, description, contact, version, eventSource string) {
 ID = id
 Name = name
 Contact = contact
 Version = version
 EventSource = eventSource
}

`Info()`

This method is mandatory and all plugins must respect that. It allows the Falco plugin framework to have all intel about the plugin itself, we use the global variables and the SetInfo() method to set the values:

// Info displays information of the plugin to Falco plugin framework
func (p *Plugin) Info() *plugins.Info {
 return &plugins.Info{
 ID: ID,
 Name: Name,
 Description: Description,
 Contact: Contact,
 Version: Version,
 EventSource: EventSource,
 }
}

`Init()`

This method (different from the function init()) will be the first one called by the Falco plugin framework, we use setDefault() to set the default values of the config. In our case, these default values are overridden by the values from init_config:.

// Init is called by the Falco plugin framework as first entry,
// we use it for setting default configuration values and mapping
// values from `init_config` (json format for this plugin)
func (p *Plugin) Init(config string) error {
 p.Config.setDefault()
 return json.Unmarshal([]byte(config), &p.Config)
}

`InitSchema()`

InitSchema() and the jsonschema tags from the fields of PluginConfig struct are used to check the validity of the content of init_config from falco.yaml.

// InitSchema map the configuration values with Plugin structure through JSONSchema tags
func (p *Plugin) InitSchema() *sdk.SchemaInfo {
 reflector := jsonschema.Reflector{
 RequiredFromJSONSchemaTags: true, // all properties are optional by default
 AllowAdditionalProperties: true, // unrecognized properties don't cause a parsing failures
 }
 if schema, err := reflector.Reflect(&PluginConfig{}).MarshalJSON(); err == nil {
 return &sdk.SchemaInfo{
 Schema: string(schema),
 }
 }
 return nil
}

It uses a json schema reflector, see jsonschema for more details about how it works.

`Fields()`

This method declares to the Falco plugin framework all fields that will be available for the rules, with their names and their types.

// Fields exposes to Falco plugin framework all availables fields for this plugin
func (dockerPlugin *DockerPlugin) Fields() []sdk.FieldEntry {
 return []sdk.FieldEntry{
 {Type: "string", Name: "docker.status", Desc: "Status"},
 {Type: "string", Name: "docker.id", Desc: "ID"},
 {Type: "string", Name: "docker.from", Desc: "From"},
 {Type: "string", Name: "docker.type", Desc: "Type"},
 {Type: "string", Name: "docker.action", Desc: "Action"},
 {Type: "string", Name: "docker.stack.namespace", Desc: "Stack Namespace"},
 {Type: "string", Name: "docker.node.id", Desc: "Swarm Node ID"},
 {Type: "string", Name: "docker.swarm.task", Desc: "Swarm Task"},
 {Type: "string", Name: "docker.swarm.taskid", Desc: "Swarm Task ID"},
 {Type: "string", Name: "docker.swarm.taskname", Desc: "Swarm Task Name"},
 {Type: "string", Name: "docker.swarm.servicename", Desc: "Swarm Service Name"},
 {Type: "string", Name: "docker.node.statenew", Desc: "Node New State"},
 {Type: "string", Name: "docker.node.stateold", Desc: "Node Old State"},
 {Type: "string", Name: "docker.attributes.container", Desc: "Attribute Container"},
 {Type: "string", Name: "docker.attributes.image", Desc: "Attribute Image"},
 {Type: "string", Name: "docker.attributes.name", Desc: "Attribute Name"},
 {Type: "string", Name: "docker.attributes.type", Desc: "Attribute Type"},
 {Type: "string", Name: "docker.attributes.exitcode", Desc: "Attribute Exit Code"},
 {Type: "string", Name: "docker.attributes.signal", Desc: "Attribute Signal"},
 {Type: "string", Name: "docker.scope", Desc: "Scope"},
 }
}

`String()`

Even if this method is mandatory, it's not used by Falco for now but must be set up for future usage. It simply retrieves the events, it can be in JSON or any format as long it contains the whole content of the source event.

// String represents the raw value of on event
// (not currently used by Falco plugin framework, only there for future usage)
func (dockerPlugin *DockerPlugin) String(in io.ReadSeeker) (string, error) {
 evtBytes, err := ioutil.ReadAll(in)
 if err != nil {
 return "", err
 }
 evtStr := string(evtBytes)

 return fmt.Sprintf("%v", evtStr), nil
}

`Extract()`

This method is called by the Falco plugin framework for getting the values of fields:

// Extract allows Falco plugin framework to get values for all available fields
func (p *Plugin) Extract(req sdk.ExtractRequest, evt sdk.EventReader) error {
 msg := p.lastDockerEventMessage

 // For avoiding to Unmarshal the same message for each field to extract
 // we store it with its EventNum. When it's a new event with a new message, we
 // update the Plugin struct.
 if evt.EventNum() != p.lastDockerEventNum {
 rawData, err := ioutil.ReadAll(evt.Reader())
 if err != nil {
 fmt.Println(err.Error())
 return err
 }

 err = json.Unmarshal(rawData, &msg)
 if err != nil {
 return err
 }

 p.lastDockerEventMessage = msg
 p.lastDockerEventNum = evt.EventNum()
 }

 switch req.Field() {
 case "docker.status":
 req.SetValue(msg.Status)
 case "docker.id":
 req.SetValue(msg.ID)
 case "docker.from":
 req.SetValue(msg.From)
 case "docker.type":
 req.SetValue(msg.Type)
 case "docker.action":
 req.SetValue(msg.Action)
 case "docker.scope":
 req.SetValue(msg.Scope)
 case "docker.actor.id":
 req.SetValue(msg.Actor.ID)
 case "docker.stack.namespace":
 req.SetValue(msg.Actor.Attributes["com.docker.stack.namespace"])
 case "docker.swarm.task":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.task"])
 case "docker.swarm.taskid":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.task.id"])
 case "docker.swarm.taskname":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.task.name"])
 case "docker.swarm.servicename":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.service.name"])
 case "docker.node.id":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.node.id"])
 case "docker.node.statenew":
 req.SetValue(msg.Actor.Attributes["state.new"])
 case "docker.node.stateold":
 req.SetValue(msg.Actor.Attributes["state.old"])
 case "docker.attributes.container":
 req.SetValue(msg.Actor.Attributes["container"])
 case "docker.attributes.image":
 req.SetValue(msg.Actor.Attributes["image"])
 case "docker.attributes.name":
 req.SetValue(msg.Actor.Attributes["name"])
 case "docker.attributes.type":
 req.SetValue(msg.Actor.Attributes["type"])
 default:
 return fmt.Errorf("no known field: %s", req.Field())
 }

 return nil
}

Try to not overlap the fields created by other plugins, for eg, in this example we can use docker. prefix because Falco libs use container. fields which are more generic, so we've not a conflict.

For this plugin, we use the modules provided by the Docker SDK, all retrieved events will be unmarshaled into the events.Message struct which simplifies the mapping and the extraction of fields.

To avoid to unmarshall for each field extraction the same message and impact the performances, we store the number (=~ event ID) and the result of the last unmarshalled message. When the number change, it means it's not the same event and we can unmarshall its message and store it with its number.

 msg := p.lastDockerEventMessage

 // For avoiding to Unmarshal the same message for each field to extract
 // we store it with its EventNum. When it's a new event with a new message, we
 // update the Plugin struct.
 if evt.EventNum() != p.lastDockerEventNum {
 rawData, err := ioutil.ReadAll(evt.Reader())
 if err != nil {
 fmt.Println(err.Error())
 return err
 }

 err = json.Unmarshal(rawData, &msg)
 if err != nil {
 return err
 }

 p.lastDockerEventMessage = msg
 p.lastDockerEventNum = evt.EventNum()
 }

`Open()`

This methods is used by the Falco plugin framework for opening a new stream of events, what is called an instance (source.Instance). The current implementation creates only one instance per plugin but it's possible in future that same plugin allows to open several streams, and so several instances at once.

To simplify the creation of this source.Instance, the Go SDK provides two easy functions, see the docs:

source.NewPullInstance: for when the event source can be implemented sequentially and the time required to generate a sequence of event is deterministic, eg: periodic calls to an external API
source.NewPushInstance: for when the event source can be suspensive and there is no time guarantee regarding when an event gets produced, eg: we wait a webhook from an external service

For collecting events from docker, we'll use source.NewPushInstance as the docker SDK creates a channel and sends the events into when they happened.

// Open is called by Falco plugin framework for opening a stream of events, we call that an instance
func (Plugin *Plugin) Open(params string) (source.Instance, error) {
 dclient, err := docker.NewClientWithOpts()
 if err != nil {
 return nil, err
 }

 eventC := make(chan source.PushEvent)
 ctx, cancel := context.WithCancel(context.Background())
 // launch an async worker that listens for Docker events and pushes them
 // to the event channel
 go func() {
 defer close(eventC)
 msgC, errC := dclient.Events(ctx, dockerTypes.EventsOptions{})
 var msg dockerEvents.Message
 var err error
 for {
 select {
 case msg = <-msgC:
 bytes, err := json.Marshal(msg)
 if err != nil {
 eventC <- source.PushEvent{Err: err}
 // errors are blocking, so we can stop here
 return
 }
 eventC <- source.PushEvent{Data: bytes}
 case err = <-errC:
 if err == io.EOF {
 // map EOF to sdk.ErrEOF, which is recognized by the Go SDK
 err = sdk.ErrEOF
 }
 eventC <- source.PushEvent{Err: err}
 // errors are blocking, so we can stop here
 return
 }
 }
 }()
 return source.NewPushInstance(eventC, source.WithInstanceClose(cancel))
}

We'll not describe with details the docker relative part, see the documentation of the Docker SDK for more info. You just have to know it creates a channel to receive the events from the engine and we use same context than the whole plugin.

Here's the most important things to notice:

eventC := make(chan source.PushEvent): we create a channel, it will be used by the instance to listen incoming events, we'll push into it the events from the docker client
ctx, cancel := context.WithCancel(context.Background()): we create a context, and more important, a Done channel for this context
eventC <- source.PushEvent{Data: bytes}: this is how to push an event to the instance
return source.NewPushInstance(eventC, source.WithInstanceClose(cancel)): the Open() method must return a source.Instance, and source.NewPushInstance() requires a channel where the events will pushed and may have optional settings, in our case, we pass also the Done channel of the context with the source.WithInstanceClose() function

Passing to the instance the same Done channel than the docker client uses, allows to correctly stop the plugin when we ask Falco to stop (CTRL+C or systemctl stop falco).

Build the plugin

The plugin is built as a c-shared library, it means a .so:

go build -buildmode=c-shared -o libdocker.so

If you use make from the repository:

make build

Installation

The plugins are commonly installed in /usr/share/falco/plugins, just move the libdocker.so you built or run make install.

Makefile

To simplify the build and the installation of the plugin, we can use a Makefile like this one:

SHELL=/bin/bash -o pipefail
GO ?= go

NAME := docker
OUTPUT := lib$(NAME).so
DESTDIR := /usr/share/falco/plugins

ifeq ($(DEBUG), 1)
 GODEBUGFLAGS= GODEBUG=cgocheck=2
else
 GODEBUGFLAGS= GODEBUG=cgocheck=0
endif

all: build

clean:
 @rm -f lib$(NAME).so

build: clean
 @$(GODEBUGFLAGS) $(GO) build -buildmode=c-shared -buildvcs=false -o $(OUTPUT) ./plugin

install: build
 mv $(OUTPUT) $(DESTDIR)/

This makefile will work for any plugin, just change the NAME variable.

Configuration

Now we have our plugin, we must declare it to Falco in falco.yaml:

plugins:
 - name: docker
 library_path: /usr/share/falco/plugins/libdocker.so
 init_config: '{"flushinterval": 1}'

load_plugins: [docker]

stdout_output:
 enabled: true

For more details about this configuration, see how to load and configure a plugin.

Rules

We create a simple rule, for checking that the fields and source work as expected:

- rule: Container status changed
 desc: Container status changed
 condition: docker.status in (create,start,die)
 output: status=%docker.status from=%docker.from type=%docker.type action=%docker.action name=%docker.attributes.name
 priority: DEBUG
 source: docker
 tags: [docker]

Test and Results

Let's run Falco with our configuration and rules files:

falco -c falco.yaml -r rules/docker_rules.yaml

17:17:24.008405000: Debug status=create from=alpine type=container action=create name=bold_keller
17:17:24.008953000: Debug status=start from=alpine type=container action=start name=bold_keller
17:17:24.009076000: Debug status=die from=alpine type=container action=die name=bold_keller

Events detected: 3
Rule counts by severity:
 DEBUG: 3
Triggered rules by rule name:
 Container status changed: 3
Syscall event drop monitoring:
 - event drop detected: 0 occurrences
 - num times actions taken: 0

It works!

Docs: Falco Is Not Starting Up

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

Action Items (TL;DR)

Read Install and Operate Guides and review falco.yaml and any local configuration file for necessary preconditions.
Address common startup issues by verifying and correcting config misconceptions.
Monitor for potential kernel driver bugs, though less frequent.
Be aware of userspace bugs that can also interfere with Falco startup.
First, always try running Falco with the default and/or easiest configuration without any plugins.

Let's find out!

Debugging Tips

Please acknowledge that The Falco Project performs a wide range of tests and provides pre-built kernel drivers, but perfection is not guaranteed.

How do I determine if Falco does not start up because of a kernel driver or userspace or pure config issue?

When you start Falco, watch the print statements.
If Falco crashes after passing load config stages, especially during syscall source setup, it signals potential kernel driver issues. These issues may include device unavailability, permission problems, or strange printouts. Alternatively, it could suggest that the kernel driver is not present in the first place, for instance, due to a download failure or missing mounts.
If Falco started up, but then crashed after, it's likely a genuine bug somewhere, we would have to find out.

Kernel Drivers

Falco kernel driver issues are the most common source of frustrating errors. Please note that since Falco 0.38.0, modern_ebpf driver is the new default driver, and it will be automatically used wherever is supported; this should help mitigate most of the following issues. Here are a few tips to demystify what can go wrong with respect to Falco's kernel drivers:

Check if all preconditions to start up the kernel drivers are met. Common issues include:
- For ebpf based drivers, the bpf syscall needs to be allowed and not blocked by SELinux or similar.
- Ensure the DKMS package is installed for the kmod driver, and your system may require custom-signed kernel modules. Also, verify the availability of the host /dev mount (e.g. /dev:/host/dev when running Falco over a container).
- In general, check that Falco has all host mounts when running from a container or as a daemonset in Kubernetes. Critical mounts for running Falco, assuming the kernel driver is available, include: /etc:/host/etc, /proc:/host/proc, /boot:/host/boot, /dev:/host/dev.
For ebpf and kmod drivers, the kernel object code needs to be available for the exact kernel release (uname -r) of your system. This invites a wide range of possible issues:
- If you use the Falco open source binary on Linux distributions such as stock Ubuntu, Fedora, Debian, Arch Linux, Oracle Linux, Rocky Linux, AlmaLinux, etc., you may encounter an issue if the pre-built kernel driver from The Falco Project is not available for download. Verify on the Driver Index page if the driver is available for your specific OS and kernel.
- Your network ACLs may be blocking the download.
- In case the download fails, building the driver on the fly (over the init container in Kubernetes, for example) can fail for many reasons.
- Lastly, if you run a custom kernel, you'll need to build your own drivers (ebpf or kmod only) or explore the option of using the modern_ebpf driver if applicable.
If your kernel version is >= 5.8 and you are enforcing either kmod or ebpf driver, consider switching to the modern_ebpf driver. It's 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).
If you are using the ebpf or modern_ebpf driver and encounter verbose and lengthy instruction printouts, you may have encountered a dreaded eBPF verifier failure. In such cases, kindly reach out to the Falco maintainers, providing the kernel release (uname -r). Resolving such instances involves modifying the driver code to ensure the eBPF verifier is happy again.

Userspace

Errors associated with Falco's rules or configurations are generally more understandable, and we provide warnings with clear instructions.
Historically, we have encountered edge case bugs with some newer features. Please bear with us in such cases, and we typically release patches to address them.
In the past, there have been instances where regressions were introduced, and certain configurations or combinations thereof may exhibit unexpected behavior. However, Falco's core functionality undergoes comprehensive testing, and we are committed to ensuring its continued reliability.

Restarts

Falco is a C/C++ application for performance reasons, and as such, it is not unheard of for Falco to crash and restart in some rare code paths or edge case conditions. However, if you deploy Falco with resource limits, for example the OOM killer can also kill the process and force a restart. Read more in the Falco Performance Guide.

References and Community Discussions

Docs: Glossary

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

Docs: Rule fields

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

A Falco rule can contain the following keys:

Key	Required	Description	Default
`rule`	yes	A short, unique name for the rule.
`condition`	yes	A filtering expression that is applied against events to check whether they match the rule.
`desc`	yes	A longer description of what the rule detects.
`output`	yes	Specifies the message that should be output if a matching event occurs. See output.
`priority`	yes	A case-insensitive representation of the severity of the event. Should be one of the following: `emergency`, `alert`, `critical`, `error`, `warning`, `notice`, `informational`, `debug`.
`exceptions`	no	A set of exceptions that cause the rule to not generate an alert.
`enabled`	no	If set to `false`, a rule is neither loaded nor matched against any events.	`true`
`tags`	no	A list of tags applied to the rule (more on this below).
`warn_evttypes`	no	If set to `false`, Falco suppresses warnings related to a rule not having an event type (more on this below).	`true`
`skip-if-unknown-filter`	no	If set to `true`, if a rule conditions contains a filtercheck, e.g. `fd.some_new_field`, that is not known to this version of Falco, Falco silently accepts the rule but does not execute it; if set to `false`, Falco reports an error and exists when finding an unknown filtercheck.	`false`
`source`	no	The event source for which this rule should be evaluated. Typical values are `syscall`, `k8s_audit`, or the source advertised by a source plugin.	`syscall`
`append`	no	When set to `true`, it adds conditions and/or exceptions to a previously defined rule or macro instead of overseeding it. Not used when the goal is just to enable an already existing rule. In case of appending to a list, it adds new elements to it.

Docs: Try Falco with Docker

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

Install Falco

First, ensure you have a Linux machine with a recent version of Docker installed. Note that the following will not work on Windows or macOS running Docker Desktop.

Run the following command:

docker run --rm -it \
 --name falco \
 --privileged \
 -v /sys/kernel/tracing:/sys/kernel/tracing:ro \
 -v /var/run/docker.sock:/host/var/run/docker.sock \
 -v /proc:/host/proc:ro \
 -v /etc:/host/etc:ro \
 falcosecurity/falco:0.43.0

Falco is now monitoring your system using the pre-installed set of rules that alert you upon suspicious behavior.

Trigger a rule

Open another terminal on the same machine and run:

sudo cat /etc/shadow

Now go back to Falco, and you'll see a message like:

2024-06-21T08:54:23.812791015+0000: Warning Sensitive file opened for reading by non-trusted program (file=/etc/shadow gparent=sudo ggparent=bash gggparent=tmux: evt_type=openat user=root user_uid=0 user_loginuid=1000 process=cat proc_exepath=/usr/bin/cat parent=sudo command=cat /etc/shadow terminal=34826 container_id=host container_name=host)

This is your first Falco event 🦅! If you are curious, this is the rule that describes it.

Create a custom rule

Now it's time to create our own rule and load it into Falco. We can be pretty creative with them, but let's stick with something simple. This time, we want to be alerted when any file is opened for writing in the /etc directory, either on the host or inside containers.

Stop the Falco container with Ctrl-C, copy the following text in a file and call it falco_custom_rules.yaml:

- rule: Write below etc
 desc: An attempt to write to /etc directory
 condition: >
 (evt.type in (open,openat,openat2) and evt.is_open_write=true and fd.typechar='f' and fd.num>=0)
 and fd.name startswith /etc
 output: "File below /etc opened for writing | file=%fd.name pcmdline=%proc.pcmdline gparent=%proc.aname[2] ggparent=%proc.aname[3] gggparent=%proc.aname[4] evt_type=%evt.type user=%user.name user_uid=%user.uid user_loginuid=%user.loginuid process=%proc.name proc_exepath=%proc.exepath parent=%proc.pname command=%proc.cmdline terminal=%proc.tty"
 priority: WARNING
 tags: [filesystem, mitre_persistence]

Then start Falco again, this time mounting the new rule file:

docker run --rm -it \
 --name falco \
 --privileged \
 -v /sys/kernel/tracing:/sys/kernel/tracing:ro \
 -v /var/run/docker.sock:/host/var/run/docker.sock \
 -v /proc:/host/proc:ro \
 -v /etc:/host/etc:ro \
 -v $(pwd)/falco_custom_rules.yaml:/etc/falco/falco_rules.local.yaml \
 falcosecurity/falco:0.43.0

Finally, open another terminal and write a file in /etc:

sudo touch /etc/test_file_falco_rule

You should see an alert in the Falco terminal, just as before. As you can see, a lot of contextual information is displayed, as it was specified in the output field of the rule. There are many such fields that you can use both in the condition and the output to build your rule.

Docs: Plugins SDKs

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

Plugins SDKs

To facilitate the development of plugins, The Falco Project provides SDKs for multiple programming languages: Go, C++, and Rust. These SDKs provide flexibility for developers to choose the programming language they are most comfortable with while ensuring a consistent and streamlined experience when building Falco plugins.

C++ SDK

The C++ SDK provides abstract base classes for plugin development. Plugin authors can derive from these base classes and implement abstract methods to:

Supply plugin metadata and capabilities.
Provide events.
Extract fields from events.

Go SDK

We offer a Go SDK that simplifies plugin development by providing support code and abstractions. This SDK includes:

Go structs and enums corresponding to the C structs and enums used by the plugin API.
Utility packages to handle memory management and type conversions.
Abstract interfaces that provide a streamlined and user-friendly way to implement plugins.

For a detailed explanation of the architecture and usage of the Go SDK, refer to the Go SDK walkthrough section.

Rust SDK

We recently introduced a Rust SDK, enabling developers to write plugins in Rust. The Rust SDK offers a safe, idiomatic interface for interacting with the Falco plugin API while leveraging Rust’s strong type system and memory safety guarantees.

Docs: Falco Plugins API Reference

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

Introduction

This page documents the functions that make up the Falco plugins API. In most cases, you will not need to implement these functions directly. There are Go and C++ SDKs that provide an easier-to-use interface for plugin authors.

At a high level, the API functions are grouped as follows:

Functions that are commons to all plugins
Functions that implement one specific capability

The C header files plugin_api.h numerate all the API functions and associated structs/types as they are used by the plugins framework. The whole plugin API and the loader used in Falco are implemented in C in a standalone module located inside falcosecurity/libs/userspace/plugin, and can be imported and reused in other projects using the falcosecurity plugin system (e.g. we have a plugin loader written in Go developed on top of the C one).

Remember, however, that from the perspective of the plugin, each function name has a prefix plugin_ e.g. plugin_get_required_api_version, plugin_get_name, etc.

Since Falco v0.33.0, some function symbols of the plugin API started supporting concurrent invocations from multiple threads. If not explicitly specified in each symbol's API reference, the plugin API assumes that functions are invoked always from the same thread with no concurrency.

Plugin API Versioning

The current version of the plugin API is 3.6.0.

The plugin API is a formal contract between the framework and the plugins, and it is versioned using semantic versioning. The framework exposes the plugin API version it supports, and each plugin expresses a required plugin API version. If the version required by a plugin does not pass the semantic check with the one supported by the framework, then the plugin cannot be loaded. See the section about plugin_get_required_api_version for more details.

Conventions

The following conventions apply for all of the below API functions:

Every function that returns a const char* must return a null-terminated C string.
All string values returned across the API are considered owned by the plugin and must remain valid for use by the plugin framework. Specifically, this means:
- For demographic functions like plugin_get_name, plugin_get_description, the returned strings must remain valid until the plugin is destroyed.
- When returning events via plugin_next_batch, both the array of structs and the data payloads inside each struct must remain valid until the next call to plugin_next_batch.
- When returning extracted string values via plugin_extract_fields, every extracted string must remain valid until the next call to plugin_extract_fields.
For every function that returns an error, the plugin should save a meaningful error string that the framework can retrieve via a call to plugin_get_last_error.

Inversion of Control and Callbacks to the Plugin's Owner

All functions from the plugin API define functionalities that the plugin offers to the framework. In the default execution path, the plugin is always the "passive" actor, with the framework being the orchestrator determining when and how often a given plugin function gets invoked.

The plugin API also supports an occasional inversion of control in which plugins can actively invoke functions exposed by the framework that owns it. For those cases, the execution flow generally proceeds as follows. First, the framework invokes a function exported by the plugin according its supported version of the plugin API. As one of the function arguments the framework passes to the plugin a vtable struct allocated and owned by the framework itself, containing one or more function pointers referring to code functions of the framework that the plugin is allowed to invoke. Permissions about retaining such function pointers inside the plugin's state after the execution of the plugin API symbol may vary depending on the API symbol itself and its related capabilities. Alongside the function pointers, the framework also provides the plugin with a ss_plugin_owner_t* opaque handle, which the plugin must pass to the framework's functions. The opaque handle represents an instance of the plugin's owner, which is an abstract component that the framework allocates for managing the plugin's requests. If the framework passes one of the function pointers defined in the vtable structs as NULL, then the plugin must assume that the related piece of functionality is not supported by the framework in that context. Plugins must always check whether the function pointers passed by the framework are NULL or not.

An example of functionality provided in the form of inversion of control is the access to state tables. The C++ example below shows how a plugin can interact with its owner during the execution of its init function. In this case, the plugin iterates over the list of state tables registered in the framework and catches errors arising during the invocations of the owner's callbacks:

extern "C" ss_plugin_t* plugin_init(const ss_plugin_init_input* in, ss_plugin_rc* rc)
{
 *rc = SS_PLUGIN_SUCCESS;
 my_plugin *ret = new my_plugin();

 if (!in || !in->tables)
 {
 *rc = SS_PLUGIN_FAILURE;
 ret->lasterr = "access to the state tables is not supported by the owner";
 return ret;
 }

 uint32_t ntables = 0;
 auto tables = in->tables->list_tables(in->owner, &ntables);
 if (!tables)
 {
 *rc = SS_PLUGIN_FAILURE;
 ret->lasterr = "can't list state tables: " + std::string(in->get_owner_last_error(in->owner));
 return ret;
 }

 for (uint32_t i = 0; i < ntables; i++)
 {
 auto& ti = tables[i];
 printf("table='%s', key_type=%d\n", ti.name, ti.key_type);
 }

 return ret;
}

Logging

Another functionality that makes use of inversion of control is logging.

The framework provides a log function during the plugin initialization, which the plugin can use to invoke the framework-provided logger at any time during the plugin life-cycle.

The following C++ example shows how a plugin can retain the owner's handle and the log function to invert control and invoke the framework logger:

struct my_plugin
{
 ss_plugin_owner_t* owner;
 ss_plugin_log_fn_t log;
};

extern "C" ss_plugin_t* plugin_init(const ss_plugin_init_input* in, ss_plugin_rc* rc)
{
 *rc = SS_PLUGIN_SUCCESS;
 my_plugin *ret = new my_plugin();

 ret->log = in->log_fn;
 ret->owner = in->owner;

 ret->log(ret->owner, NULL, "initializing plugin...", SS_PLUGIN_LOG_SEV_INFO);

 return ret;
}

extern "C" void plugin_destroy(ss_plugin_t* s)
{
 my_plugin *ps = (my_plugin *) s;
 ps->log(ps->owner, NULL, "destroying plugin...", SS_PLUGIN_LOG_SEV_INFO);

 delete ((my_plugin *) s);
}

The signature of the log function is:

void log(ss_plugin_owner_t* owner, const char* component, const char* msg, ss_plugin_log_severity sev);

where owner is the handle of the owner, component is a string representing the plugin's component name that is invoking the logger (falls back to the plugin name when NULL), msg is the log message and sev is the log severity as defined in API.

Common Plugin API

get_required_api_version

const char* plugin_get_required_api_version() [Required: yes]

This function returns a string containing a semver version number e.g. "3.0.0", reflecting the version of the plugin API framework that this plugin requires. This is different than the version of the plugin itself, and should only have to change when the plugin API changes.

This is the first function the framework calls when loading a plugin. If the returned value is not semver-compatible with the version of the plugin API framework, the plugin will not be loaded.

For example, if the code implementing the plugin framework has version 1.1.0, and a plugin's plugin_get_required_api_version function returns 1.0.0, the plugin API is compatible and the plugin will be loaded. If the code implementing the plugin framework has version 3.0.0, and a plugin's plugin_get_required_api_version function returns 1.0.0, the API is not compatible and the plugin will not be loaded.

get_{name,description,contact,version}

const char* plugin_get_name() [Required: yes]
const char* plugin_get_description() [Required: yes]
const char* plugin_get_contact() [Required: yes]
const char* plugin_get_version() [Required: yes]

These functions all return an C string, with memory owned by the plugin, that describe the plugin:

plugin_get_name: Return the name of the plugin.
plugin_get_description: Return a short description of the plugin.
plugin_get_contact: Return a contact url/email/twitter account for the plugin authors.
plugin_get_version: Return the version of the plugin itself.

For get_version, note that increasing the major version signals breaking changes in the plugin implementation but must not change the serialization format of the event data. For example, events written in pre-existing capture files must always be readable by newer versions of the plugin.

init

ss_plugin_t* plugin_init(const ss_plugin_init_input *input, ss_plugin_rc *rc) [Required: yes]

This function passes plugin-level configuration to the plugin to create its plugin-level state. The plugin then returns a pointer to that state, as a ss_plugin_t * handle. The handle is never examined by the plugin framework and is never freed. It is only provided as the argument to later API functions.

When managing plugin-level state, keep the following in mind:

It is the plugin's responsibility to allocate plugin state (memory, open files, etc) and free that state later in plugin_destroy.
The plugin state should be the only location for state (e.g. no globals, no per-thread state). Although unlikely, the framework may choose to call plugin_init multiple times for the same plugin, and this should be supported by the plugin.
The returned rc value should be SS_PLUGIN_SUCCESS (0) on success, SS_PLUGIN_FAILURE (1) on failure.
On failure, make sure to return a meaningful error message in the next call to plugin_get_last_error.
On failure, plugins can decide whether to return an allocated state or not. In the first case, the plugin framework will use the allocated state to retrieve the failure error with plugin_get_last_error, and will then free the state with plugin_destroy. In the second case, plugin_destroy will not be called and the plugin framework will return a generic error.

The format of the config string is entirely determined by the plugin author, and by default is passed unchanged from Falco/the application using the plugin framework to the plugin. However, semi-structured formats like JSON/YAML are preferable to free-form text. In those cases, the plugin author can provide a schema describing the config string contents by implementing the optional get_init_schema function. If so, the init function can assume the passed-in configuration string to always be well-formed, and can avoid performing any error handling. The plugin framework will take care of automatically parsing it against the provided schema and generating ad-hoc errors accordingly. Please refer to the documentation of get_init_schema for more details.

If a non-NULL ss_plugin_t* state is returned, then subsequent invocations of init must not return the same ss_plugin_t * value again, unless it has been disposed with destroy first.

destroy

void plugin_destroy(ss_plugin_t *s) [Required: yes]

This function frees any resources held in the ss_plugin_t struct. Afterwards, the handle should be considered destroyed and no further API functions will be called with that handle.

get_last_error

const char* plugin_get_last_error(ss_plugin_t* s) [Required: yes]

This function is called by the framework after a prior call returned an error. The plugin should return a meaningful error string providing more information about the most recent error.

get_init_schema

const char* plugin_get_init_schema(ss_plugin_schema_type* schema_type) [Required: no]

This function returns a schema that describes the configuration to be passed to init during plugin initialization. The return value is a C string, with memory owned by the plugin, representing the configuration schema. The type of schema returned is compliant with the ss_plugin_schema_type enumeration, and is written inside the schema_type output argument.

Although this function is non-required, it is common to implement it due to the benefits it brings. If get_init_schema is correctly implemented, the init function can assume the passed-in configuration string to always be well-formed. The plugin framework will take care of automatically parsing it against the provided schema and generating ad-hoc errors accordingly. This also serves as a piece of documentation for users about how the plugin needs to be configured.

Currently, the plugin framework only supports the JSON Schema format, which is represented by the SS_PLUGIN_SCHEMA_JSON enum value. If a plugin defines a JSON Schema, the framework will require the init configuration string to be a valid json-formatted string.

Writing the dummy enum value SS_PLUGIN_SCHEMA_NONE inside schema_type is equivalent to avoiding implementing the get_init_schema function itself, which ends up with the framework treating the init configuration as an opaque string with no additional checks.

set_config

ss_plugin_rc plugin_set_config(ss_plugin_t* s, const ss_plugin_set_config_input* i) [Required: no]

Sets a new plugin configuration when provided by the framework. The new configuration is provided by config as a string in ss_plugin_set_config_input* i.

This function should return:

SS_PLUGIN_SUCCESS (0) if the config is accepted
SS_PLUGIN_FAILURE (1) if the config is rejected

If rejected, the plugin should provide context in the string returned by get_last_error() before returning.

get_metrics

ss_plugin_metric* plugin_get_metrics(ss_plugin_t* s, uint32_t* num_metrics) [Required: no]

This function returns the pointer to the first element of an array containing plugin-provided custom metrics.

Each element of the array is a ss_plugin_metric which is defined in the plugin API as follows:

typedef struct ss_plugin_metric
{
 const char* name; //Opaque string representing the metric name.
 ss_plugin_metric_type type; // Metric type, indicates whether the metric value is monotonic or non-monotonic.
 ss_plugin_metric_value value; // Metric numeric value.
 ss_plugin_metric_value_type value_type; // Metric value data type, e.g. `uint64_t`.
} ss_plugin_metric;

Each metric defines its own name, value, type (monotonic or non-monotonic) and value type (data type of its numeric value).

The argument num_metrics is a return argument and must be set to the length of the array before returning. It can be set to 0 if no metrics are provided.

Event Sourcing Capability API

get_id

uint32_t plugin_get_id() [Required: varies]

This should return the event ID allocated to your plugin. During development and before receiving an official event ID, you can use the "Test" value of 999.

This function is required if get_event_source is defined and returns a non-empty string, otherwise it is considered optional. Returning zero is equivalent to not implementing the function. If the plugin has a non-zero ID and a non-empty event source, then its next_batch function is allowed to only return events of plugin type (code 322) with its own plugin ID and event source.

get_event_source

const char* plugin_get_event_source() [Required: varies]

This function returns a C string, with memory owned by the plugin, containing the plugin's event source. This event source is used for:

Associating Falco rules with plugin events--A Falco rule with a source: gizmo property will run on all events returned by the gizmo plugin's next_batch function.
Linking together plugins with field extraction capability and plugins with event sourcing capability. The first can list a given event source like gizmo in its get_extract_event_sources function, and they will get an opportunity to extract fields from all events returned by the "gizmo" plugin.
Ensuring that only one plugin at a time is loaded for a given source.

When defining a source, make sure it accurately describes the events from your plugin (e.g. use aws_cloudtrail for AWS CloudTrail events, not json or logs) and doesn't overlap with the source of any other plugin with event sourcing capability.

The only time where duplicate sources make sense are when a group of plugins can use a standard data format for a given event. For example, plugins might extract k8s_audit events from multiple cloud sources like gcp, azure, aws, etc. If they all format their events as json objects that have identical formats as one could obtain by using K8s Audit hooks, then it would make sense for the plugins to use the same source.

This function is required if get_id is defined and returns a non-zero ID, otherwise it is considered optional. Returning an empty string is equivalent to not implementing the function. If the plugin has a non-zero ID and a non-empty event source, then its next_batch function is allowed to only return events of plugin type (code 322) with its own plugin ID and event source.

open

ss_instance_t* plugin_open(ss_plugin_t* s, const char* params, int32_t* rc) [Required: yes]

This function is called to "open" a stream of events. The interpretation of a stream of events is up to the plugin author, but think of plugin_init as initializing the plugin software, and plugin_open as configuring the software to return events. Using a streaming audio analogy, plugin_init turns on the app, and plugin_open starts a streaming audio channel.

The same general guidelines apply for plugin_open as do for plugin_init:

All state related to sourcing a stream of events should be in the returned ss_instance_t pointer.
Return 0 on success, 1 on error. Be ready to return an error via plugin_get_last_error on error.
The plugin should support concurrent open sessions at once. Unlike plugin-level state, it's very likely that the plugin framework might call plugin_open multiple times for a given plugin.
On error, do not return any instance struct, as the plugin framework will not call plugin_close.

If a non-NULL ss_instance_t* instance is returned, then subsequent invocations of open must not return the same ss_instance_t* value again, unless it has been disposed with close first.

close

void plugin_close(ss_plugin_t* s, ss_instance_t* h) [Required: yes]

This function closes a stream of events previously started via a call to plugin_open. Afterwards, the stream should be considered closed and the framework will not call plugin_next_batch/plugin_extract_fields with the same ss_instance_t pointer.

next_batch

int32_t plugin_next_batch(ss_plugin_t* s, ss_instance_t* h, uint32_t *nevts, ss_plugin_event ***evts) [Required: yes]

This function is used to return a set of next events to the plugin framework, given a plugin state and open instance.

*evts should be updated to an allocated contiguous array of ss_plugin_event pointers. The memory for the structs array is owned by the plugin and should be held until the next call to plugin_next_batch. *nevts should be updated with the number of events returned.

An event is represented by a ss_plugin_event struct, which observes the same format of the libscap event block specification.

This function should return:

SS_PLUGIN_SUCCESS (0) on success
SS_PLUGIN_FAILURE (1) on failure
SS_PLUGIN_TIMEOUT (-1) on non-error but there are no events to return.
SS_PLUGIN_EOF (6) when the stream of events is complete.

If the plugin receives a SS_PLUGIN_FAILURE, it will close the stream of events by calling plugin_close.

If a plugin implements a specific event source (get_id is non-zero and get_event_source is non-empty), then, it is only allowed to produce events of type plugin (code 322) containing its own plugin ID (as returned by get_id). In such a case, when an event contains a zero plugin ID, the framework automatically sets the plugin ID of the event to the one of the plugin. If a plugin does not implement a specific event source, it is allowed to produce events of any of the types supported by the libscap specific.

SS_PLUGIN_TIMEOUT should be returned whenever no events can be returned immediately. This ensures that the plugin framework is not stalled waiting for a response from plugin_next_batch. When the framework receives a SS_PLUGIN_TIMEOUT, it will keep the stream of events open and call plugin_next_batch again later.

This function can be invoked concurrently by multiple threads, each with distinct and unique parameter values. The value of the ss_plugin_event*** output parameter must be uniquely attached to the ss_instance_t* parameter value. The pointer must not be shared across multiple distinct ss_instance_t* values.

get_progress

const char* plugin_get_progress(ss_plugin_t* s, ss_instance_t* h, uint32_t* progress_pct) [Required: no]

If the plugin exports this function, the framework will periodically call it after open to return how much of the event stream has been read. If a plugin does not provide a bounded stream of events (for example, events coming from a file or other source that has an ending), it should not export this function.

If not exported, the plugin framework will not print meaningful process indicators while processing event streams.

When called, the progress_pct pointer should be updated with the read progress, as a number between 0 (no data has been read) and 10000 (100% of the data has been read). This encoding allows the engine to print progress decimals without requiring to deal with floating point numbers (which could cause incompatibility problems with some languages).

The return value is an string representation of the read progress, with the memory owned by the plugin. This might include the progress percentage combined with additional context added by the plugin. The plugin can return NULL. In this case, the framework will use the progress_pct value instead.

This function can be invoked concurrently by multiple threads, each with distinct and unique parameter values. If the returned pointer is non-NULL, then it must be uniquely attached to the ss_instance_t* parameter value. The pointer must not be shared across multiple distinct ss_instance_t* values.

event_to_string

const char* plugin_event_to_string(ss_plugin_t *s, const ss_plugin_event_input *evt) [Required: no]

This function is used to return a printable representation of an event. The memory is owned by the plugin and can be freed on the next call to plugin_event_to_string. It is used in filtering/output expressions as the built-in field evt.plugininfo. Even if implemented, this function is ignored if a plugin does not implement a specific event source (get_id is undefined or returns zero, and get_event_source is undefined or returns an empty string).

The string representation should be on a single line and contain important information about the event. It is not necessary to return all information from the event. Simply return the most important fields/properties of the event that provide a useful default representation.

Here is an example output, from the cloudtrail plugin:

us-east-1 masters.some-demo.k8s.local s3 GetObject Size=0 URI=s3://some-demo-env/some-demo.k8s.local/backups/etcd/events/control/etcd-cluster-created

This function can be invoked concurrently by multiple threads, each with distinct and unique parameter values. If the returned pointer is non-NULL, then it must be uniquely attached to the ss_plugin_t* parameter value. The pointer must not be shared across multiple distinct ss_plugin_t* values.

list_open_params

const char* plugin_list_open_params(ss_plugin_t* s, ss_plugin_rc* rc) [Required: no]

This function returns a list of suggested values that are valid parameters for the open plugin function. Although non-required, this function is useful to instruct users about potential valid parameters for opening a stream of events. Implementing this function also brings additional usage documentation for the plugin, and allows makes it more usable with automated tools.

The returned value is a json string, with memory owned by the plugin, which contains an array of objects. Each object describes one suggested value for the open function. Here's an example:

[
 {"value": "resource1", "desc": "An example of openable resource"},
 {"value": "resource2", "desc": "Another example of openable resource"}
 {
 "value": "res1;res2;res3",
 "desc": "Some names",
 "separator": ";"
 }
]

Each object has the following properties:

value: a string usable as a parameter for open
desc: (optional) a string with that describes the meaning of value.
separator: (optional) a string representing a separator string in case value represents a list of concatenated values. This can be used by plugins to specify an open param that represents more than one source, in which case they can be separated by the separator substring. It's a plugin responsibility to specify the separator string.

Field Extraction Capability API

get_fields

const char* plugin_get_fields() [Required: yes]

This function should return the set of fields supported by the plugin. Remember, a field is a name (e.g. proc.name) that can extract a value (e.g. nginx) from an event (e.g. a syscall event involving a process). The return value is a string whose memory is owned by the plugin. The string is json formatted and contains an array of objects. Each object describes one field. Here's an example:

[
 {"type": "string", "name": "gizmo.field1", "arg": {"isRequired": true, "isKey": true}, "desc": "Describing field 1"},
 {"type": "uint64", "name": "gizmo.field2", "desc": "Describing field 2", properties: ["hidden"]}
]

Each object has the following properties:

type: one of "string", "uint64", "bool", "reltime", "abstime", "ipaddr", "ipnet"
name: a string with a name for the field. By convention, this is a dot-separated path of names. Use a consistent first name e.g. "ct.xxx" to help filter authors associate the field with a given plugin.
isList: (optional) If present and set to true, notes that the field extracts a list of values. Fields of this kind can only be used with the in and intersects filtering operators. For list fields, extracting single values means extracting lists of length equal to 1.
arg: (optional) if present, notes that the field can accept an argument e.g. field[arg]. More precisely, the following flags could be specified:
- isRequired: if true, the argument is required.
- isIndex: if true, the field is numeric.
- isKey: if true, the field is a string. If isRequired is true, one between isIndex and isKey must be true, to specify the argument type. If isRequired is false, but one between isIndex and isKey is true, the argument is allowed but not required.
display: (optional) If present, a string that will be used to display the field instead of the name. Used in tools like wireshark.
desc: a string with a short description of the field. This will be used in help output so be concise and descriptive.
properties: (optional) If present, an array of additional properties that apply to the field. The value is an array of strings that can be one of the following:
- hidden: Do not display the field when using programs like falco --list to list the set of supported fields.
- conversation: This field is applicable for use in wireshark conversations, and denotes that the field represents one half of a "conversation" that can be shown in the conversations or endpoints view.
- info: Also applicable for use in wireshark, and denotes that it should be appended to the "info" column in the wireshark event list.

When defining fields, keep the following guidelines in mind:

Field names should generally have the plugin name/event source as the first component, and usually have one or two additional components. For example, gizmo.pid is preferred over gizmo.process.id.is. If a plugin has a moderately large set of fields, using components to group fields may make sense (e.g. cloudtrail.s3.bytes.in and cloudtrail.s3.bytes.out).
Fields should be idempotent: for a given event, the value for a field should be the same regardless of when/where the event was generated.
Fields should be neutral: define fields that extract properties of the event (e.g. "source ip address") rather than judgements (e.g. "source ip address is associated with a botnet").

extract_fields

int32_t plugin_extract_fields(ss_plugin_t *s, const ss_plugin_event_input *evt, const ss_plugin_field_extract_input* in) [Required: yes]

This function is used to return the value for one or more field names that were returned in plugin_get_fields. The framework provides an event and an input containing an array of ss_plugin_extract_field structs. Each struct has one field name/type, and the plugin fills in each struct with the corresponding value for that field.

The format of the ss_plugin_extract_field struct is the following:

// The noncontiguous numbers are to maintain equality with underlying
// falcosecurity/libs types.
typedef enum ss_plugin_field_type
{
 // A 64bit unsigned integer.
 FTYPE_UINT64 = 8,
 // A printable buffer of bytes, NULL terminated
 FTYPE_STRING = 9,
 // A relative time. Seconds * 10^9 + nanoseconds. 64bit.
 FTYPE_RELTIME = 20,
 // An absolute time interval. Seconds from epoch * 10^9 + nanoseconds. 64bit.
 FTYPE_ABSTIME = 21,
 // A boolean value, 4 bytes.
 FTYPE_BOOL = 25,
 // Either an IPv4 or IPv6 address. The length indicates which one it is.
 FTYPE_IPADDR = 40,
 // Either an IPv4 or IPv6 network. The length indicates which one it is.
 // The field encodes only the IP address, so this differs from FTYPE_IPADDR,
 // from the way the framework perform runtime checks and comparisons.
 FTYPE_IPNET = 41,
}ss_plugin_field_type;

typedef struct ss_plugin_extract_field
{
 union {
 const char** str;
 uint64_t* u64;
 uint32_t* u32;
 ss_plugin_bool* boolean;
 ss_plugin_byte_buffer* buf;
 } res;
 uint64_t res_len;

 uint32_t field_id;
 const char* field;
 const char* arg_key;
 uint64_t arg_index;
 bool arg_present;
 uint32_t ftype;
 bool flist;
} ss_plugin_extract_field;

For each struct, the plugin fills in field_id/field/arg/ftype with the field. field_id is the index into the original list of fields returned by plugin_get_fields, and allows for faster mapping to a plugin's set of fields. The plugin should fill in res_len and res with a pointer to an array of values of appropriate type for the field, depending on the field type ftype. If the field type is FTYPE_STRING, res should be updated to point to an string with the string value, with memory owned by the plugin. The plugin should retain this memory until the next call to plugin_extract_fields.

If res_len is set to zero, the plugin framework assumes that res is undefined and will not use it. Setting a res_len value grater than 1 is allowed only for fields for which isList is defined as true.

This function can be invoked concurrently by multiple threads, each with distinct and unique parameter values. The value of the ss_plugin_extract_field* output parameter must be uniquely attached to the ss_plugin_t* parameter value. The pointer must not be shared across multiple distinct ss_plugin_t* values.

get_extract_event_sources

const char* plugin_get_extract_event_sources() [Required: no]

This function allows the plugin to restrict the kinds of events where the plugin's extract_fields method will be called. Valid event source names are the ones returned by the get_event_source function of plugins with event sourcing capability, or syscall for indicating support to non-plugin events. The return value should be a string containing a json array of compatible event sources, with memory owned by the plugin. Here's an example:

["aws_cloudtrail", "gcp_cloudtrail"]

This implies that the plugin can potentially extract values from events that have a source aws_cloudtrail or gcp_cloudtrail.

This function is optional. If the plugin does not export this function or if it returns an empty array (or NULL), then if the plugin has sourcing capability, and implements a specific event source, it will only receive events matching its event source, otherwise the framework will assume the plugin can receive events from all event sources.

get_extract_event_types

uint16_t* plugin_get_extract_event_types(uint32_t* numtypes) [Required: no]

This function allows the plugin to restrict the kinds of events where the plugin's extract_fields method will be called. The return value is an array of integers representing the event types that the plugin is capable of processing for field extraction. Events with types that are not present in the returned list will not be received by the plugin. The event types follow the enumeration from the libscap specific.

This function is optional. If the plugin does not export this function or if it returns an empty array (or NULL), the plugin will receive every event type if the result of get_extract_event_sources (either default or custom) is compatible with the syscall event source, otherwise the plugin will only receive events of plugin type (code 322).

Event Parsing Capability API

parse_event

ss_plugin_rc plugin_parse_event(ss_plugin_t *s, const ss_plugin_event_input *evt, const ss_plugin_event_parse_input* in) [Required: yes]

Receives an event from the current capture and parses its content. The plugin is guaranteed to receive an event at most once, after any operation related the event sourcing capability, and before any other operation related to the field extraction capability. The returned rc value should be SS_PLUGIN_SUCCESS (0) on success, SS_PLUGIN_FAILURE (1) on failure.

The framework provides an event and an input. The event pointer is allocated and owner by the framework, and it is not guaranteed that to refer to the same memory or data returned by the last next_batch call (in case the same plugin also supports the event sourcing capability). The input is a vtable containing callbacks towards the plugin's owner that can be used by the plugin for performing read/write operations on state tables not owned by itself, for which it obtained accessors at initialization time. The plugin does not need to go through this vtable in order to read and write from a table it owns.

This function can be invoked concurrently by multiple threads, each with distinct and unique parameter values. The value of the ss_plugin_event_parse_input* output parameter must be uniquely attached to the ss_plugin_t* parameter value. The pointer must not be shared across multiple distinct ss_plugin_t* values.

get_parse_event_sources

const char* plugin_get_parse_event_sources() [Required: no]

This function allows the plugin to restrict the kinds of events where the plugin's parse_event method will be called. Valid event source names are the ones returned by the get_event_source function of plugins with event sourcing capability, or syscall for indicating support to non-plugin events. The return value should be a string containing a json array of compatible event sources, with memory owned by the plugin.

get_parse_event_types

uint16_t* plugin_get_parse_event_types(uint32_t* numtypes) [Required: no]

This function allows the plugin to restrict the kinds of events where the plugin's parse_event method will be called. The return value is an array of integers representing the event types that the plugin is capable of processing for field extraction. Events with types that are not present in the returned list will not be received by the plugin. The event types follow the enumeration from the libscap specific.

This function is optional. If the plugin does not export this function or if it returns an empty array (or NULL), the plugin will receive every event type if the result of get_parse_event_sources (either default or custom) is compatible with the syscall event source, otherwise the plugin will only receive events of plugin type (code 322).

Async Events Capability API

get_async_event_sources

const char* plugin_get_async_event_sources() [Required: no]

The return value should be a string containing a json array of compatible event sources, with memory owned by the plugin. The list describes the event sources for which this plugin is capable of injecting async events in the event stream of a capture.

This function is optional. If the plugin does not export this function or if it returns an empty array (or NULL), then the async events produced by a plugin will be injected in the event stream of any source.

get_async_events

const char* plugin_get_async_events() [Required: yes]

Return a string describing the name list of all asynchronous events that this plugin is capable of pushing into a live event stream. The framework can reject async events produced by a plugin if their name is not on the name list returned by this function. The return value should be a string containing a json array of compatible event sources, with memory owned by the plugin.

set_async_event_handler

ss_plugin_rc plugin_set_async_event_handler(ss_plugin_t* s, ss_plugin_owner_t* owner, const ss_plugin_async_event_handler_t handler) [Required: yes]

Sets a function handler that allows the plugin to send events asynchronously to its owner during a live event capture. The handler is a thread-safe function that can be invoked concurrently by multiple threads. The asynchronous events must be encoded as an async event type (code 402) as for the libscap specific. The returned rc value should be SS_PLUGIN_SUCCESS (0) on success, SS_PLUGIN_FAILURE (1) on failure.

The memory of events sent to the async event handler function must be owned by the plugin and is not retained by the owner after the event handler returns. The async event handler function is defined as follows:

// Function handler used by plugin for sending asynchronous events to the
// Falcosecurity libs during a live event capture. The asynchronous events
// must be encoded as an async event type (code 402) as for the libscap specific.
// The function returns SS_PLUGIN_SUCCESS in case of success, or
// SS_PLUGIN_FAILURE otherwise. If a non-NULL char pointer is passed for
// the "err" argument, it will be filled with an error message string
// in case the handler function returns SS_PLUGIN_FAILURE. The error string
// has a max length of PLUGIN_MAX_ERRLEN (termination char included) and its
// memory must be allocated and owned by the plugin.
typedef ss_plugin_rc (*ss_plugin_async_event_handler_t)(ss_plugin_owner_t* o, const ss_plugin_event *evt, char* err);

The plugin can start sending async events through the passed-in handler right from the moment this function is invoked. set_async_event_handler can be invoked multiple times during the lifetime of a plugin. In that case, the registered function handler remains valid up until the next invocation of set_async_event_handler on the same plugin, after which the new handler set must replace any already-set one. If the handler is set to a NULL function pointer, the plugin is instructed about disabling or stopping the production of async events. If a NULL handler is set, and an asynchronous job has been started by the plugin before, the plugin should stop the job and wait for it to be finished before returning from this function. Although the event handler is thread-safe and can be invoked concurrently, this function is still invoked by the framework sequentially from the same thread.

The C++ example below shows how an async event handler can be correctly used from an asynchronous thread with proper start and stop conditions:

typedef struct my_plugin
{
 std::thread async_thread;
 std::atomic<bool> async_thread_run;
} my_plugin;

extern "C" ss_plugin_t* plugin_init(const ss_plugin_init_input* in, ss_plugin_rc* rc)
{
 my_plugin *ret = new my_plugin();
 ret->async_thread_run = false;
 *rc = SS_PLUGIN_SUCCESS;
 return ret;
}

extern "C" void plugin_destroy(ss_plugin_t* s)
{
 // stop the async thread if it's running
 my_plugin *ps = (my_plugin *) s;
 if (ps->async_thread_run)
 {
 ps->async_thread_run = false;
 if (ps->async_thread.joinable())
 {
 ps->async_thread.join();
 }
 }
 delete ps;
}

...

extern "C" ss_plugin_rc plugin_set_async_event_handler(ss_plugin_t* s, ss_plugin_owner_t* owner, const ss_plugin_async_event_handler_t handler)
{
 my_plugin *ps = (my_plugin *) s;

 // stop the async thread if it's running
 if (ps->async_thread_run)
 {
 ps->async_thread_run = false;
 if (ps->async_thread.joinable())
 {
 ps->async_thread.join();
 }
 }

 // if an handler is provided, launch an async worker
 if (handler)
 {
 ps->async_thread_run = true;
 ps->async_thread = std::thread([ps, owner, handler]()
 {
 char err[PLUGIN_MAX_ERRLEN];
 while (ps->async_thread_run;)
 {
 ss_plugin_event* evt = ps->do_some_work();
 if (handler(owner, evt, err) != SS_PLUGIN_SUCCESS)
 {
 // report the error somehow
 }
 }
 });
 }

 return SS_PLUGIN_SUCCESS;
}

Async events encode a plugin ID that defines its event source. However, this value is set by the framework when the async event is received, and is set to the ID associated to the plugin-defined event source currently open during a live capture, or zero in case of the syscall event source. The event source assigned by the framework to the async event can only be among the ones compatible with the list returned by get_async_event_sources.

Async events encode a string representing their event name, which is used for runtime matching and define the encoded data payload. Plugins are allowed to only send async events with one of the names expressed in the list returned by get_async_events. The name of an async event acts as a contract on the encoding of the data payload of all async events with the same name.

Libscap Event Block Specification

Libscap, the Falcosecurity libs component responsible of event captures and control, proposes and supports a specification that regulates the way system, kernel, and plugin events are encoded. The same specification also defines the encoding of SCAP capture files, that can be used by the Falcosecurity libs to record and replay event streams. In the specification, events are defined as a specific block type of the pcap-ng file format. All the event types and the associated parameters supported by libscap are defined by the libscap's event table. The plugin API fully shares and observes the libscap's event definitions, and uses them for both reading and writing events from/to the framework.

As for the libscap specific, an event is represented as a contiguous region of memory composed by a header and a list of parameters appended to it, in the form of:

// | evt header | len param 1 (2B/4B) | ... | len param N (2B/4B) | data param 1 | ... | data param N |
typedef struct ss_plugin_event {
 uint64_t ts; /* timestamp, in nanoseconds from epoch */
 uint64_t tid; /* the tid of the thread that generated this event */
 uint32_t len; /* the event len, including the header */
 uint16_t type; /* the event type */
 uint32_t nparams; /* the number of parameters of the event */
} ss_plugin_event;

The event header is composed of:

ts: the event timestamp, in nanoseconds since the epoch. Can be (uint64_t)-1, in which case the framework will automatically fill the event time with the current time.
tid: the tid of the thread that generated this event. Can be (uint64_t)-1 in case no thread is specified, such as when generating a plugin event (type code 322).
len: the event len, including the header
type: the code of the event, as per the ones supported by the libscap specific. This dictates the number and kind of parameters, and whether the length is encoded as a 2 bytes or 4 bytes integer.
nparams: the number of parameters of the event

Further and more formal documentation will be available in the future...

State Tables API

In the plugin framework, state tables are simple key-value mappings representing a piece of state owned by a component of the Falcosecurity libs or defined by a plugin. The plugin API declares formal abstract definitions for state tables and provides means for plugins to access the state owned by other components of the framework, define and own their own state, and make it accessible externally. In this context, a component of the framework is an abstract entity that could represent a given piece of machinery within the Falco libraries or any other plugin loaded at runtime.

Basic Concepts

A state table is a key-value map that can be used for storing pieces of state within the plugin framework. State tables are an abstract concept, and the plugin API does not enforce any specific implementation. Instead, the API specifies interface boundaries in the form of C virtual tables of methods representing the behavior of state tables. This allows the plugin API to remain flexible, abstract, and multi-language by nature. The model by which state tables work is defined by the notions of ownership, registration, and discovery.

Every state table must have an owner, which is responsible of managing the table's memory and of implementing all the functions of the state tables API. Owners can either be plugins or any of the other actors that are part of the Falcosecurity libraries. For example, libsinsp is the owner of the threads table, which is a key-value store where the key is a thread ID of a Linux machine and the value is a set of information describing a Linux thread. Plugins can access the threads table of libsinsp for retrieving thread information given a thread ID, reading and writing the info fields, extending the info with additional metadata, and do much more. However, plugins are never responsible of managing the memory and the implementation of the threads table, as it is owned by libsinsp only. Instead, plugins can do the same by defining their own stateful components and implementing the required interface functions to register them as "state tables". Stateful components must be registered in the framework in order to be considered "state tables". Libsinsp, which owns the plugins loaded at runtime, also holds a "table registry" that is the source of truth for all the state tables known at runtime. Once a state table is registered in the table registry, it is discoverable by all the actors and plugins running in the context of the same Falcosecurity libs instance.

The way plugins can interact with state tables is through discovery and the usage of accessors. At initialization time (in the init function), plugins are provided interface functions that allow them to list all the state tables available at runtime and obtaining "accessors" for later usage. An accessor is an opaque pointers obtained at initialization time and that can be used later (e.g. when parsing an event or when extracting a field) for accessing a given table or the fields of its entries. Considering the example of the threads table, in its init function a given plugin could obtain an accessor to the table and to some of the fields of each thread info (such as the pid or the comm) and store them in its plugin state. Later, when extracting a field, the same plugin would be available to query the threads table for a given thread ID (perhaps obtained by reading the event payload of a syscall) by using the table accessor, and then reading the pid of the obtained thread by using the field accessor.

Inherently, the plugin API also enable plugins to define their own state tables and register them in the table registry. Once that's done, the registered state table will be visible to all other plugins just like the threads table, without knowing nor caring about which actor is owning it. The state table owned by the plugin will be discoverable through the table registry by the plugin itself too. However, plugins owning a given table are not forced to go through the state tables interface in order to operate on it (conversely, this could also be the less efficient choice). Plugins can implement their own state as they prefer, whereas the purpose of the state tables interface is solely to make that state available to other actors in the framework. Coherently, table owners can also decide "how much" of a table they want the other components to have visibility of. For example, libsinsp can access more info and functionalities on the threads table than what it makes available through the state table interface, which is also natural considering that its implementation is hidden and can be arbitrary.

The set of state tables made available by a given plugin or Falcosecurity libs actor, and the set of fields and operations available for each of those table, take part of the semantic versioned UX contract of that plugin or actor. For example, removing a given table or table field from libsinsp can be considered a breaking change that must reflected by the version number of the Falcosecurity libs. The same applies for the version of each plugin and the state tables declared by them.

Access and Consistency

State tables are dynamic structures. Each table is defined by a given key type, which can be any of the types supported by the ss_plugin_state_type enumeration. Then, the each key-value mappings contained in the table are referred to as table entries. Each entry has a specific set of information fields, which is shared across all the entries of the same table. Each field is named and has a specific type. The set of fields for the entries of a given table is defined dynamically at runtime and can be extended by different actors. For example, libsinsp populates the threads table with a given set of information fields for each table's entry (representing a given thread info), and plugins can read and write the value of those fields by obtaining accessors for those. However, plugins also have the opportunity of defining new fields inside the threads table, with a new unique name and a specific type, and libsinsp will be responsible of hosting that new piece of information for each thread and make it available to all actors in the framework. The same can happen for tables defined by any plugin.

Given that state tables can get modified by different actors at runtime, there has to be a deterministic disambiguation about consistency of table edits and visibility of those changes. The plugin API implements this by guaranteeing a deterministic and non-changing total ordering of all the actors in the system. Considering a given ordering, an actor will have visibility only over the changes applied by actors coming before it in the given ordering. In the Falcosecurity libs and the plugin framework, the guaranteed order is the one by which plugins are loaded at runtime. The first actor in the order is always libsinsp itself, which means that all plugins will always see all the table modifications authored by libsinsp at a given point in time. Then, plugins are ordered by following their loading order at runtime. This means that if Plugin B is loaded in Falco after Plugin A, then Plugin B will see all the table changes performed by Plugin A at runtime, but not the contrary (however, they'll both have visibility over the changes performed by libsinsp). As such the plugins loading order in Falco can be functionally relevant.

Subtables and complex data types

The plugin framework supports a special table field type which is the table type. Table entries can use this field to store the handle to another table, which means each entry can have its own subtables.

For example, the threads table has a field named file_descriptors. This field allows accessing the file descriptor table of every thread, making it possible to access useful information about a specific open file descriptor like file name, pid, and much more.

This also unlocks the ability for tables to store/access arrays, maps or even more complex data types. The plugin can "wrap" the complex type in a table by implementing the interface functions for that type, allowing the complex data types to be stored as a subtable.

Obtaining Accessors

Before performing any operation over state tables, plugins must first obtain accessors for each of them. This can happen only at initialization time through a vtable that is passed only to the init plugin function. The vtable allows plugins to discover all the tables registered in the framework, get accessors for them, and register their own tables. Once an accessor is obtained, plugins must maintain it up until they are destroyed, and use it during functions related to specific capabilities (e.g. field extraction, event parsing). The vtable passed to init is reported below.

// Vtable for controlling and the fields for the entries of a state table.
// This allows discovering the fields available in the table, defining new ones,
// and obtaining accessors usable at runtime for reading and writing the fields'
// data from each entry of a given state table.
typedef struct
{
 // Returns a pointer to an array containing info about all the fields
 // available in the entries of the table. nfields will be filled with the number
 // of elements of the returned array. The array's memory is owned by the
 // tables's owner. Returns NULL in case of error.
 ss_plugin_table_fieldinfo* (*list_table_fields)(ss_plugin_table_t* t, uint32_t* nfields);
 //
 // Returns an opaque pointer representing an accessor to a data field
 // present in all entries of the table, given its name and type.
 // This can later be used for read and write operations for all entries of
 // the table. The pointer is owned by the table's owner.
 // Returns NULL in case of issues (including when the field is not defined
 // or it has a type different than the specified one).
 ss_plugin_table_field_t* (*get_table_field)(ss_plugin_table_t* t, const char* name, ss_plugin_state_type data_type);
 //
 // Defines a new field in the table given its name and data type,
 // which will then be available in all entries contained in the table.
 // Returns an opaque pointer representing an accessor to the newly-defined
 // field. This can later be used for read and write operations for all entries of
 // the table. The pointer is owned by the table's owner.
 // Returns NULL in case of issues (including when a field is defined multiple
 // times with different data types).
 ss_plugin_table_field_t* (*add_table_field)(ss_plugin_table_t* t, const char* name, ss_plugin_state_type data_type);
} ss_plugin_table_fields_vtable;

typedef struct
{
 // Returns a pointer to an array containing info about all the tables
 // registered in the plugin's owner. ntables will be filled with the number
 // of elements of the returned array. The array's memory is owned by the
 // plugin's owner. Returns NULL in case of error.
 ss_plugin_table_info* (*list_tables)(ss_plugin_owner_t* o, uint32_t* ntables);
 //
 // Returns an opaque accessor to a state table registered in the plugin's
 // owner, given its name and key type. Returns NULL if an case of error.
 ss_plugin_table_t* (*get_table)(ss_plugin_owner_t* o, const char* name, ss_plugin_state_type key_type);
 //
 // Registers a new state table in the plugin's owner. Returns
 // SS_PLUGIN_SUCCESS in case of success, and SS_PLUGIN_FAILURE otherwise.
 // The state table is owned by the plugin itself, and the input will be used
 // by other actors of the plugin's owner to interact with the state table.
 ss_plugin_rc (*add_table)(ss_plugin_owner_t* o, const ss_plugin_table_input* in);
 //
 // Vtable for controlling operations related to fields on the state tables
 // registered in the plugin's owner.
 ss_plugin_table_fields_vtable fields;
} ss_plugin_init_tables_input;

Obtaining subtables accessors

Obtaining table accessors is a bit different for subtables.

Table accessors can be only obtained at initialization time, however tables may be empty at this time, which means subtables may not yet exist. The solution to this problem is to create a table entry just to get its subtables.

Please note that this newly created entry is temporary and it should be used only at initialization time to obtain subtable accessors.

The following example shows how to obtain accessors for the file descriptor subtable:

struct plugin_state
{
 ss_plugin_table_t* thread_table;
 ss_plugin_table_field_t* table_field_fdtable;
 ss_plugin_table_field_t* table_field_fdtable_name;
};

static ss_plugin_t* plugin_init(const ss_plugin_init_input* in, ss_plugin_rc* rc)
{
 plugin_state *ret = new plugin_state();

 // get the accessor to the threads table
 ret->thread_table = in->tables->get_table(in->owner, "threads", ss_plugin_state_type::SS_PLUGIN_ST_INT64);

 // get an accessor to the subtable field
 ret->table_field_fdtable = in->tables->fields.get_table_field(ret->thread_table, "file_descriptors", ss_plugin_state_type::SS_PLUGIN_ST_TABLE);

 // create a new table entry
 auto entry = in->tables->writer_ext->create_table_entry(ret->thread_table);

 // read the subtable handle from the new entry
 ss_plugin_state_data data;
 in->tables->reader_ext->read_entry_field(ret->thread_table, entry, ret->table_field_fdtable, &data);
 auto fdtable = data.table;

 //obtain the accessor to one of the subtable fields
 ret->table_field_fdtable_name = in->tables->fields_ext->get_table_field(fdtable, "name", ss_plugin_state_type::SS_PLUGIN_ST_STRING);

 //destroy the temporary entry
 in->tables->writer_ext->destroy_table_entry(ret->thread_table, entry);
}

Accessing Tables

After obtaining accessors for all the tables and fields a given plugin is interested into, they can be used for performing operations over tables at runtime. Table operations are split in the two "reading" and "writing" categories, each having their own vtable and set of functions. The "reader" and the "writer" vtables are passed to the interested plugin functions for different capabilities, depending on their scope. For example, the extract_fields function of the field extraction capability gets passed the state tables reader vtable, whereas the parse_event function of the event parsing capability has access to both the reader and writer vtables. This enforces users to only apply state tables modifications at event parsing time, leaving field extraction a "stateless" code path. The reader and writer vtables and their respective functions are reported below.

// Vtable for controlling a state table for read operations.
typedef struct
{
 // Returns the table's name, or NULL in case of error.
 // The returned pointer is owned by the table's owner.
 const char* (*get_table_name)(ss_plugin_table_t* t);
 //
 // Returns the number of entries in the table, or ((uint64_t) -1) in
 // case of error.
 uint64_t (*get_table_size)(ss_plugin_table_t* t);
 //
 // Returns an opaque pointer to an entry present in the table at the given
 // key, or NULL in case of issues (including if no entry is found at the
 // given key). The returned pointer is owned by the table's owner.
 ss_plugin_table_entry_t* (*get_table_entry)(ss_plugin_table_t* t, const ss_plugin_state_data* key);
 //
 // Reads the value of an entry field from a table's entry.
 // The field accessor must be obtained during plugin_init().
 // The read value is stored in the "out" parameter.
 // Returns SS_PLUGIN_SUCCESS if successful, and SS_PLUGIN_FAILURE otherwise.
 ss_plugin_rc (*read_entry_field)(ss_plugin_table_t* t, ss_plugin_table_entry_t* e, const ss_plugin_table_field_t* f, ss_plugin_state_data* out);
} ss_plugin_table_reader_vtable;

// Vtable for controlling a state table for write operations.
typedef struct
{
 // Erases all the entries of the table.
 // Returns SS_PLUGIN_SUCCESS if successful, and SS_PLUGIN_FAILURE otherwise.
 ss_plugin_rc (*clear_table)(ss_plugin_table_t* t);
 //
 // Erases an entry from a table at the given key.
 // Returns SS_PLUGIN_SUCCESS if successful, and SS_PLUGIN_FAILURE otherwise.
 ss_plugin_rc (*erase_table_entry)(ss_plugin_table_t* t, const ss_plugin_state_data* key);
 //
 // Creates a new entry that can later be added to the same table it was
 // created from. The entry is represented as an opaque pointer owned
 // by the plugin. Once obtained, the plugin can either add the entry
 // to the table through add_table_entry(), or destroy it through
 // destroy_table_entry(). Returns an opaque pointer to the newly-created
 // entry, or NULL in case of error.
 ss_plugin_table_entry_t* (*create_table_entry)(ss_plugin_table_t* t);
 //
 // Destroys a table entry obtained by from previous invocation of create_table_entry().
 void (*destroy_table_entry)(ss_plugin_table_t* t, ss_plugin_table_entry_t* e);
 //
 // Adds a new entry to a table obtained by from previous invocation of
 // create_table_entry() on the same table. The entry is inserted in the table
 // with the given key. If another entry is already present with the same key,
 // it gets replaced. After insertion, table will be come the owner of the
 // entry's pointer. Returns an opaque pointer to the newly-added table's entry,
 // or NULL in case of error.
 ss_plugin_table_entry_t* (*add_table_entry)(ss_plugin_table_t* t, const ss_plugin_state_data* key, ss_plugin_table_entry_t* entry);
 //
 // Updates a table's entry by writing a value for one of its fields.
 // The field accessor must be obtained during plugin_init().
 // The written value is read from the "in" parameter.
 // Returns SS_PLUGIN_SUCCESS if successful, and SS_PLUGIN_FAILURE otherwise.
 ss_plugin_rc (*write_entry_field)(ss_plugin_table_t* t, ss_plugin_table_entry_t* e, const ss_plugin_table_field_t* f, const ss_plugin_state_data* in);
} ss_plugin_table_writer_vtable;

Accessing subtables

Subtables handles can be obtained just like any other field, by reading the table type field of an entry.

After obtaining subtables handles and fields accessors, accessing subtables is the same as accessing regular tables.

The following example shows how to access fields from the file_descriptors subtable from one of the entries of the threads table:

ss_plugin_rc plugin_parse_event(ss_plugin_t *s, const ss_plugin_event_input *ev, const ss_plugin_event_parse_input* in)
{
 plugin_state *ps = (plugin_state *) s;
 ss_plugin_state_data tmp;

 // get an entry from the thread table
 tmp.s64 = ev->evt->tid;
 ss_plugin_table_entry_t* thread_entry = in->table_reader_ext->get_table_entry(ps->thread_table, &tmp);

 // read the file_descriptors field from the entry
 in->table_reader_ext->read_entry_field(ps->thread_table, thread_entry, ps->table_field_fdtable, &tmp);
 ss_plugin_table_t* fdtable = tmp.table;

 // get an entry from the file descriptors table of the previously read thread
 tmp.s64 = 0;
 ss_plugin_table_entry_t* fd_entry = in->table_reader_ext->get_table_entry(fdtable, &tmp);

 // read a field from the entry in the file descriptors table
 in->table_reader_ext->read_entry_field(fdtable, fd_entry, ps->table_field_fdtable_name, &tmp);
}

Registering State Tables

On top of accessing tables owned by the framework or other plugins, each plugin can also make part (or all) of its state available to other actors in the framework in the form of state tables. In this case, the plugin is responsible of providing all the necessary vtables and their respective functions, just like the Falcosecurity libraries do for the tables owned by them (e.g. the threads table). Plugins have total freedom towards how the table is actually implemented, as long as they respect the API functions in the vtables and they own all the memory related to the table and its entries. Plugins also have the freedom of not supporting some of the functions of the vtables, however they are not allowed to pass NULL-pointing function references. The struct by which plugins register their state table and the related vtable functions is reported below.

// Plugin-provided input passed to the add_table() callback of
// ss_plugin_init_tables_input, that can be used by the plugin to inform its
// owner about one of the state tables owned by the plugin. The plugin
// is responsible of owning all the memory pointed by this struct and
// of implementing all the API functions. These will be used by other
// plugins loaded by the falcosecurity libraries to interact with the state
// of a given plugin to implement cross-plugin state access.
typedef struct
{
 // The name of the state table.
 const char* name;
 //
 // The type of the sta table's key.
 ss_plugin_state_type key_type;
 //
 // A non-NULL opaque pointer to the state table.
 // This will be passed as parameters to all the callbacks defined below.
 ss_plugin_table_t* table;
 //
 // Vtable for controlling read operations on the state table.
 ss_plugin_table_reader_vtable reader;
 //
 // Vtable for controlling write operations on the state table.
 ss_plugin_table_writer_vtable writer;
 //
 // Vtable for controlling operations related to fields on the state table.
 ss_plugin_table_fields_vtable fields;
} ss_plugin_table_input;

Thread-safety and Reproducibility

State access is not thread-safe. Operations related to either discovery, reading, or writing, must all be executed in the synchronous context and within the thread in which the framework invokes the given plugin function that is capable of accessing tables. For example, plugins are only allowed to read from a table during the execution of extract_fields or parse_event, but they are not allowed to launch an asynchronous thread that reuses the same accessors to read from a table after any of those functions have returned.

Also, the previous sections imply that state tables can be operated on during the execution of various plugin functions, but that however only the parse_event function of the event parsing capability can perform write operations. This is by purpose and design due to the architecture of the Falcosecurity libraries themselves.

There may be use cases when the state update results of some asynchronous job and computation. For example, the Falcosecurity libraries implement the container metadata enrichment support by connecting to one or more container runtime sockets and fetching information asynchronously using a separate thread of the main event processing loop. In those cases, state updates must still happen synchronously. The async events capability is the strategy provided by the plugin framework. With that, plugins are provided with a thread-safe callback that they can use to inject asynchronous events in the currently-open event stream, and the framework will guarantee those events to be later received by functions such as parse_event or extract_fields just like any other events. Plugins can only safely utilize asynchronously-obtained information for state updates and field extraction through this messaging-like communication mode.

An additional effect of injecting asynchronous events in an event stream is that they can so be recorded in SCAP capture files, thus being reproducible when reading events later from that capture files. By having the asynchronous information recorded in the event stream, the event parsing and field extraction plugin functions will be able to work just like in live capture mode by also making all the state transitions reproducible and deterministic.

Docs: Default and Local Rules Files

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

Falco comes with a default rules file that is loaded if no specific configuration is provided. However, that can be completely customized in several ways, depending on how Falco is installed. There are several ways to specify the location of your custom rules, download them, and keep them up to date.

The configuration file

The default configuration file, /etc/falco/falco.yaml makes Falco load rules from the /etc/falco/falco_rules.yaml file, followed by any custom rules located in the /etc/falco/falco_rules.local.yaml file, followed by any custom rules located in the /etc/falco/rules.d directory. This configuration is governed by the rules_files key:

rules_files:
- /etc/falco/falco_rules.yaml
- /etc/falco/falco_rules.local.yaml
- /etc/falco/rules.d

Changing these configuration entries will affect the location and loading order of the rules files.

You can find the details of the available default rules in this page or in the Falco rules auto-generated documentation.

If you are running Falco directly from the command line, you can use the -r switch to load as many rules files as needed. Is it possible to provide -r with the path of a single file or directory (in this latter case, all the rules files in the directory will be loaded). The switch can be specified multiple times; if is specified at least once, the rules_files key in the configuration file is ignored. e.g.:

# falco -r /path/to/my/rules1.yaml -r /path/to/my/rules2.yaml

Falcoctl

The falcoctl tool provides functionality to download and update rules files distributed as OCI artifacts. The install command of the falcoctl tool will download rules files to a configurable directory (by default, that is /etc/falco). For instance, to install a specific version of the default rules file in /etc/falco you can run the following commands:

# falcoctl index add falcosecurity https://falcosecurity.github.io/falcoctl/index.yaml
# falcoctl artifact install falco-rules:3.2.0

Falcoctl is available as a standalone tool, included in Falco packages and container images, automatically installed as a systemd unit or deployed as an init container via the Helm chart.

Rules installed via the Helm chart

If you install the Helm chart, at least version 3.0.0 with:

helm install falco

Falco, by default, will load the latest rules file that is compatible with your Falco version and keep it up to date automatically via falcoctl. These are published on GitHub Packages.

Use the rules embedded in the Falco image

The Falco image ships with a snapshot of the latest version of the official Falco rules. If you wish to use that without downloading anything at runtime, you can install Falco with:

helm install falco \
--set falcoctl.artifact.install.enabled=false \
--set falcoctl.artifact.follow.enabled=false

Add custom rules with a configmap

You can always use the customRules value to add your own custom rules in a configmap. For instance, if we create a file as described in the documentation, and then add it to our install command above as follows:

helm install falco \
--set falcoctl.artifact.install.enabled=false \
--set falcoctl.artifact.follow.enabled=false \
-f custom_rules.yaml

or if you have already installed falco, you can use the helm upgrade -i

helm upgrade -i falco \
--set falcoctl.artifact.install.enabled=false \
--set falcoctl.artifact.follow.enabled=false \
-f custom_rules.yaml

it will be loaded and configured in our Falco instance and you can verify changes by checking the falco daemonset container logs with the command below:

kubectl logs -n falco daemonsets/falco

Notice: the new rule files described in customRules will be placed in the /etc/falco/rules.d directory, and will be loaded following the order specified in the configuration file: in the default configuration, this means that will be loaded after /etc/falco/falco.yaml and /etc/falco/falco_rules.local.yaml rules files.

Only use rules supplied via configmap

If you only want to use the rules that you add via configmap, discarding all automated updates and default rules shipped in the image, you have to remove the falco_rules.yaml and falco_rules.local.yaml entries from the Falco configuration. Assuming you have your custom rules in custom_rules.yaml:

helm install falco -f ./custom_rules.yaml \
--set "falco.rules_files={/etc/falco/rules.d}" \
--set falcoctl.artifact.install.enabled=false \
--set falcoctl.artifact.follow.enabled=false

Docs: Default Macros

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

The default Falco rule set defines a number of macros that makes it easier to start writing rules. These macros provide shortcuts for a number of common scenarios and can be used in any user defined rule sets.

Falco also provide Macros that should be overridden. Refer here for further information.

File Opened for Writing

- macro: open_write
 condition: (evt.type=open or evt.type=openat) and evt.is_open_write=true and fd.typechar='f' and fd.num>=0

File Opened for Reading

- macro: open_read
 condition: (evt.type=open or evt.type=openat) and evt.is_open_read=true and fd.typechar='f' and fd.num>=0

Never True

- macro: never_true
 condition: (evt.num=0)

Always True

- macro: always_true
 condition: (evt.num=>0)

Proc Name is Set

- macro: proc_name_exists
 condition: (proc.name!="<NA>")

File System Object Renamed

- macro: rename
 condition: evt.type in (rename, renameat)

New Directory Created

- macro: mkdir
 condition: evt.type = mkdir

File System Object Removed

- macro: remove
 condition: evt.type in (rmdir, unlink, unlinkat)

File System Object Modified

- macro: modify
 condition: rename or remove

New Process Spawned

- macro: spawned_process
 condition: (evt.type in (execve, execveat))

Common Directories for Binaries

- macro: bin_dir
 condition: fd.directory in (/bin, /sbin, /usr/bin, /usr/sbin)

Shell is Started

- macro: shell_procs
 condition: (proc.name in (shell_binaries))

Known Sensitive Files

- macro: sensitive_files
 condition: >
 fd.name startswith /etc and
 (fd.name in (sensitive_file_names)
 or fd.directory in (/etc/sudoers.d, /etc/pam.d))

Newly Created Process

- macro: proc_is_new
 condition: proc.duration <= 5000000000

Inbound Network Connections

- macro: inbound
 condition: >
 ((evt.type in (accept,listen)) or
 (fd.typechar = 4 or fd.typechar = 6) and
 (fd.ip != "0.0.0.0" and fd.net != "127.0.0.0/8") and (evt.rawres >= 0 or evt.res = EINPROGRESS))

Outbound Network Connections

- macro: outbound
 condition: >
 ((evt.type = connect) or
 (fd.typechar = 4 or fd.typechar = 6) and
 (fd.ip != "0.0.0.0" and fd.net != "127.0.0.0/8") and (evt.rawres >= 0 or evt.res = EINPROGRESS))

Inbound or Outbound Network Connections

- macro: inbound_outbound
 condition: >
 ((evt.type in (accept,listen,connect)) or
 (fd.typechar = 4 or fd.typechar = 6) and
 (fd.ip != "0.0.0.0" and fd.net != "127.0.0.0/8") and (evt.rawres >= 0 or evt.res = EINPROGRESS))

Object is a Container

- macro: container
 condition: container.id != host

Interactive Process Spawned

- macro: interactive
 condition: >
 ((proc.aname=sshd and proc.name != sshd) or
 proc.name=systemd-logind or proc.name=login)

Docs: Deploy as a container

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

Falco consumes streams of events and evaluates them against a set of security rules to detect abnormal behavior. By default, Falco is pre-configured to consume events from the Linux Kernel. This scenario requires Falco to be privileged, and depending on the kernel version installed on the node, a driver will be installed on the node. Since orchestration systems like Kubernetes are out of scope for this section, it's up to the user to manage the container lifecycle and deployment across the nodes.

For other installation scenarios, such as consuming cloud events or other data sources using plugins, please refer to the Plugins section.

Install

This section describes how to run the Falco userspace process in a container using one of the released container images.

By default, Falco is pre-configured to consume events from the Linux Kernel. For this default installation scenario, Falco can be run in two ways:

Different instructions apply to each method depending on the driver used. Note that the Modern eBPF does not require driver installation.

Fully Privileged

To run Falco in a container using Docker with full privileges, use the following commands:

Modern eBPF

The Modern eBPF is bundled into the Falco binary. This allows you to run Falco without dependencies by using the following command:

docker pull falcosecurity/falco:0.43.0
docker run --rm -it \
 --privileged \
 -v /sys/kernel/tracing:/sys/kernel/tracing:ro \
 -v /var/run/docker.sock:/host/var/run/docker.sock \
 -v /proc:/host/proc:ro \
 -v /etc:/host/etc:ro \
 falcosecurity/falco:0.43.0

On some systems, tracefs is available at /sys/kernel/debug/tracing instead of /sys/kernel/tracing. If this is the case, please replace -v /sys/kernel/tracing:/sys/kernel/tracing:ro with -v /sys/kernel/debug/tracing:/sys/kernel/tracing:ro.

Mounting the host's tracefs (i.e.: mounting the host /sys/kernel/tracing path) is an optional but recommended pre-requisite. By removing the -v /sys/kernel/tracing:/sys/kernel/tracing:ro line from the above command, you will reduce the amount of accesses granted to the container, but will not benefit anymore from TOCTOU mitigation support.

Kernel Module

For the Kernel Module driver, Falco requires the driver to be installed on the host system first.

Install the driver on the host system using the falcosecurity/falco-driver-loader image, as described in the Driver Installation section.

Run Falco:

docker pull falcosecurity/falco:0.43.0
docker run --rm -it \
 --privileged \
 -v /var/run/docker.sock:/host/var/run/docker.sock \
 -v /dev:/host/dev \
 -v /proc:/host/proc:ro \
 -v /etc:/host/etc:ro \
 falcosecurity/falco:0.43.0 falco -o engine.kind=kmod

eBPF Probe

For the eBPF probe driver, Falco requires the probe to be prepared and stored on the host system first (under /root/.falco).

Install the driver on the host system using the falcosecurity/falco-driver-loader image, as described in the Driver Installation section.

Run Falco:

docker pull falcosecurity/falco:0.43.0
docker run --rm -it \
 --privileged \
 -v /var/run/docker.sock:/host/var/run/docker.sock \
 -v /root/.falco:/root/.falco \
 -v /proc:/host/proc:ro \
 -v /etc:/host/etc:ro \
 falcosecurity/falco:0.43.0 falco -o engine.kind=ebpf

# If running a kernel version < 4.14, add '-v /sys/kernel/debug:/sys/kernel/debug:ro \' to the above docker command.

Least Privileged (Recommended)

To run Falco in a container using Docker with the principle of least privilege, you can use the following commands depending on the driver you want to use.

Modern eBPF

docker pull falcosecurity/falco:0.43.0
docker run --rm -it \
 --cap-drop all \
 --cap-add sys_admin \
 --cap-add sys_resource \
 --cap-add sys_ptrace \
 -v /sys/kernel/tracing:/sys/kernel/tracing:ro \
 -v /var/run/docker.sock:/host/var/run/docker.sock \
 -v /proc:/host/proc:ro \
 -v /etc:/host/etc:ro \
 falcosecurity/falco:0.43.0

The minimum set of capabilities to run Falco with the Modern eBPF driver are:

CAP_SYS_PTRACE
CAP_SYS_RESOURCE
CAP_BPF
CAP_PERFMON

However, in the command above, we use CAP_SYS_ADMIN because Docker does not yet support CAP_BPF and CAP_PERFMON.

Kernel Module

For the Kernel Module driver, Falco requires the driver to be installed on the host system first. This step requires full privileges, while the Falco container can then run with the least privileges.

Install the driver on the host system using the falcosecurity/falco-driver-loader image, as described in the Driver Installation section.

Run Falco using the falcosecurity/falco image with the least privileges:

docker pull falcosecurity/falco:0.43.0
docker run --rm -it \
 -e HOST_ROOT=/ \
 --cap-add SYS_PTRACE --pid=host $(ls /dev/falco* | xargs -I {} echo --device {}) \
 -v /var/run/docker.sock:/var/run/docker.sock \
 -v /etc:/host/etc:ro \
 falcosecurity/falco:0.43.0 falco -o engine.kind=kmod

Note that ls /dev/falco* | xargs -I {} echo --device {} outputs a --device /dev/falcoX option per CPU (i.e., just the devices created by the Falco's kernel module). Also, -e HOST_ROOT=/ is necessary since with --device there is no way to remap devices to /host/dev/.

If you are running Falco on a system with the AppArmor LSM enabled (e.g., Ubuntu), you must also pass --security-opt apparmor:unconfined to the docker run command above.

You can verify if you have AppArmor enabled using the command below:

docker info | grep -i apparmor

eBPF Probe

For the eBPF probe driver, Falco requires the probe to be prepared and stored on the host system first (under /root/.falco). This step requires full privileges, after which the Falco container can run with the least privileges.

Install the driver on the host system using the falcosecurity/falco-driver-loader image, as described in the Driver Installation section.

Run Falco using the falcosecurity/falco image with the least privileges:

docker pull falcosecurity/falco:0.43.0
docker run --rm -it \
 --cap-drop all \
 --cap-add sys_admin \
 --cap-add sys_resource \
 --cap-add sys_ptrace \
 -v /var/run/docker.sock:/host/var/run/docker.sock \
 -v /root/.falco:/root/.falco \
 -v /proc:/host/proc:ro \
 -v /etc:/host/etc \
 falcosecurity/falco:0.43.0 falco -o engine.kind=ebpf

# If running a kernel version < 4.14, add '-v /sys/kernel/debug:/sys/kernel/debug:ro \' to the above Docker command.

If you are running Falco on a system with the AppArmor LSM enabled (e.g., Ubuntu), you must also pass --security-opt apparmor:unconfined to the docker run command above.

To verify if AppArmor is enabled, use the command below:

docker info | grep -i apparmor

To run Falco with the least privileges using the eBPF probe, the following capabilities are required:

On kernels <5.8, Falco requires CAP_SYS_ADMIN, CAP_SYS_RESOURCE, and CAP_SYS_PTRACE.
On kernels >=5.8, CAP_BPF and CAP_PERFMON were separated from CAP_SYS_ADMIN, so the required capabilities are CAP_BPF, CAP_PERFMON, CAP_SYS_RESOURCE, CAP_SYS_PTRACE. Unfortunately, Docker does not yet support adding the two newly introduced capabilities with the --cap-add option. For this reason, we continue using CAP_SYS_ADMIN, which still allows performing the same operations granted by CAP_BPF and CAP_PERFMON. In the near future, Docker will support adding these two capabilities, and we will be able to replace CAP_SYS_ADMIN.

Driver Installation

This section provides instructions for installing the driver on the host system using the falcosecurity/falco-driver-loader image. This approach is helpful if you prefer to install the driver on the host first and then run Falco in a container later.

Driver installation on the host is only required for the Kernel Module and eBPF probe drivers.

You can skip this section if you plan to use the Modern eBPF.

When using the eBPF probe or kernel module drivers, the driver loader attempts to either download a prebuilt driver or build it on the fly as a fallback. Starting with Falco 0.38, the driver loader has improved functionality to automatically retrieve the required kernel headers for distributions supported by driverkit. This enhancement ensures that the necessary kernel headers are available to dynamically build the appropriate driver—whether it is the Kernel Module or the eBPF probe.

However, if the driver loader cannot automatically fetch the required kernel headers, you may need to install them manually on the host as a prerequisite. For detailed instructions on manual installation, refer to the Installation section.

The falcosecurity/falco-driver-loader:0.43.0 is based on a recent Debian image. For ancient kernel versions, this might not work. The alternative falcosecurity/falco-driver-loader:0.43.0-buster (based on an older Debian image) may work in such a case.

Kernel Module

To install the kernel module driver on the host system, you can use the following command:

docker pull falcosecurity/falco-driver-loader:0.43.0
docker run --rm -it \
 --privileged \
 -v /root/.falco:/root/.falco \
 -v /boot:/host/boot:ro \
 -v /lib/modules:/host/lib/modules \
 -v /usr:/host/usr:ro \
 -v /proc:/host/proc:ro \
 -v /etc:/host/etc:ro \
 falcosecurity/falco-driver-loader:0.43.0 kmod

eBPF Probe

To install the eBPF probe driver on the host system, you can use the following command:

docker pull falcosecurity/falco-driver-loader:0.43.0
docker run --rm -it \
 --privileged \
 -v /root/.falco:/root/.falco \
 -v /boot:/host/boot:ro \
 -v /lib/modules:/host/lib/modules:ro \
 -v /usr:/host/usr:ro \
 -v /proc:/host/proc:ro \
 -v /etc:/host/etc:ro \
 falcosecurity/falco-driver-loader:0.43.0 ebpf

Verify Image Signing

All official container images for Falco, starting from version 0.35.0, are signed with cosign. To verify the signature, you can run the following command:

cosign verify docker.io/falcosecurity/falco:0.43.0 \
 --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
 --certificate-identity-regexp=https://github.com/falcosecurity/falco/ \
 --certificate-github-workflow-ref=refs/tags/0.43.0

Replace docker.io/falcosecurity/falco with any official Falco image (falco, falco-driver-loader) from any official container registry to verify other images.

If you have your own container registry and wish to retain the signature while copying Falco images, you can simply use the cosign copy command:

cosign copy docker.io/falcosecurity/falco:0.43.0 your-registry/falco:0.43.0

And you'll be able to easily verify that the image in your registry was not tampered with!

Configuration

You can configure Falco by either:

Passing the -o command line flag to the Docker run command
Or by mounting a custom configuration file into the container (e.g., -v /path/to/falco.yaml:/etc/falco/falco.yaml)

Further configurable options via environment variables include (to be passed with -e with Docker):

FALCOCTL_DRIVER_REPOS - See the Installing the Driver section.
SKIP_DRIVER_LOADER - Set this environment variable to avoid running falcoctl driver tool when the falcosecurity/falco image starts. Useful when the driver has already been installed on the host by other means.

Docs: How to distribute a plugin

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

Introduction

In this article, we'll focus on the steps to build the OCI artifacts containing the plugin and its rules and how to distribute them on Github Packages.

To get more familiar with the OCI artifacts, you can read our blog posts about falcoctl and GitOps for rules

In the next sections we'll describe how to:

set up a Github Actions workflow to:
- create a release with GoReleaser when a tag is pushed
- build the OCI artifacts of the plugin and its rules
create the index.yaml used by falcoctl

Requirements

This tutorial is based on a Github repo, with the possibility to run workflows in Github Actions and store OCI artifacts in Github Packages. If you use a different system or even just private repositories, you'll need to adapt the examples to your context.

To make it work, you must have the code organization proposed in how to develop a plugin page.

GoReleaser

GoReleaser is a famous tool to build and create releases for projects on Github or else. We'll use it to build and archive the binaries at each release.

At the root of your repo, create a .goreleaser.yaml file with the following content:

builds:
 - env:
 - GODEBUG=cgocheck=0
 main: ./plugin
 binary: lib{PLUGIN_NAME}.so
 goos:
 - linux
 goarch:
 - amd64
 flags: -buildmode=c-shared
checksum:
 name_template: "checksums.txt"

With PLUGIN_NAME as the name of your plugin.

Makefile

Makefiles are a convenient way to script actions. We'll use it to pass all the required flags to create the final .so library files used by the Falco plugin framework:

SHELL=/bin/bash -o pipefail
GO ?= go

NAME := {PLUGIN_NAME}
OUTPUT := lib$(NAME).so

ifeq ($(DEBUG), 1)
 GODEBUGFLAGS= GODEBUG=cgocheck=2
else
 GODEBUGFLAGS= GODEBUG=cgocheck=0
endif

all: build

clean:
 @rm -f lib$(NAME).so

build: clean
 @$(GODEBUGFLAGS) $(GO) build -buildmode=c-shared -buildvcs=false -o $(OUTPUT) ./plugin

With PLUGIN_NAME as the name of your plugin.

You can test it by running make build and see the lib{PLUGIN_NAME}.so appearing at the root of your folder.

Github Actions Workflow

The first step is to create the .github/workflows folder and the release.yaml file describing our workflow.

Headers

Each workflow starts with, at least, a name and a on:

name: Release Plugins

on:
 push:
 tags:
 - '[0-9]+\.[0-9]+\.[0-9]+'

env:
 OCI_REGISTRY: ghcr.io
 PLUGIN_NAME: {PLUGIN_NAME}

permissions:
 contents: write
 packages: write

The workflow will be triggered each time a tag following semantic versioning (major.minor.patch) is created.

Once again PLUGIN_NAME is the name of your plugin, it will be set as env var to be reused all over the file. It's the only thing to adapt to your context. We also set the registry (Github Packages) URL with OCI_REGISTRY.

The permissions are required to allow Github Actions to read the content of your repo, create the release and push the artifacts into Github Packages.

The jobs

Once we have set the "headers" of the workflow file, it's time to set the actions that will be run. We'll split them into 2:

Publish the OCI artifacts
Create the release

Publish the OCI artifacts

To publish the artifacts, we'll use falcoctl, the official CLI to manage Falco artifacts.

The steps to publishing the artifacts will be, in this order:

Get the falcoctl sources
Prepare the Go env
Build falcoctl (guarantees the latest version)
Get the plugin sources
Build the plugin (.so file)
Get the repo name in lower case
Push the artifacts with all their tags:
- push the plugin
- push the rules with a dependency to the plugin

jobs:
 publish-oci-artifacts:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout Falcoctl Repo
 uses: actions/checkout@v3
 with:
 repository: falcosecurity/falcoctl
 ref: main
 path: tools/falcoctl
 - name: Setup Golang
 uses: actions/setup-go@v4
 with:
 go-version: '^1.20'
 cache-dependency-path: tools/falcoctl/go.sum
 - name: Build falcoctl
 run: make
 working-directory: tools/falcoctl
 - name: Checkout
 uses: actions/checkout@v3
 with:
 path: plugin
 - name: Build the plugin
 run: make build
 working-directory: plugin
 - id: StringRepoName
 uses: ASzc/change-string-case-action@v5
 with:
 string: ${{ github.repository }}
 - name: Upload OCI artifacts to GitHub packages
 run: |
 MAJOR=$(echo ${{ github.ref_name }} | cut -f1 -d".")
 MINOR=$(echo ${{ github.ref_name }} | cut -f1,2 -d".")
 DIR=$(pwd)

 cd plugin/
 $DIR/tools/falcoctl/falcoctl registry push \
 ${{ env.OCI_REGISTRY }}/${{ steps.StringRepoName.outputs.lowercase }}/plugin/${{ env.PLUGIN_NAME }}:${{ github.ref_name }} \
 --config /dev/null \
 --type plugin \
 --version "${{ github.ref_name }}" \
 --tag latest --tag $MAJOR --tag $MINOR \
 --platform linux/amd64 \
 --requires plugin_api_version:2.0.0 \
 --depends-on ${{ env.PLUGIN_NAME }}-rules:${{ github.ref_name }} \
 --name ${{ env.PLUGIN_NAME }} \
 lib${{ env.PLUGIN_NAME }}.so

 cd rules/
 $DIR/tools/falcoctl/falcoctl registry push \
 ${{ env.OCI_REGISTRY }}/${{ steps.StringRepoName.outputs.lowercase }}/ruleset/${{ env.PLUGIN_NAME }}:${{ github.ref_name }} \
 --config /dev/null \
 --type rulesfile \
 --version "${{ github.ref_name }}" \
 --tag latest --tag $MAJOR --tag $MINOR \
 --depends-on ${{ env.PLUGIN_NAME }}:${{ github.ref_name }} \
 --name ${{ env.PLUGIN_NAME }}-rules \
 ${{ env.PLUGIN_NAME }}_rules.yaml
 env:
 FALCOCTL_REGISTRY_AUTH_BASIC: ${{ env.OCI_REGISTRY }},${{ github.repository_owner }},${{ secrets.GITHUB_TOKEN }}

Create the release

GoReleaser can automatically generate a Changelog at the same time we publish the new artifacts. This step isn't imperative to generate the OCI artifacts but it's a good practice among Go developers. To achieve that, make sure to have a correct .goreleaser.yml file as explained here.

 release:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout
 uses: actions/checkout@v3
 with:
 fetch-depth: 0
 - name: Setup Golang
 uses: actions/setup-go@v3
 with:
 go-version: '1.19'
 - name: Run GoReleaser
 uses: goreleaser/goreleaser-action@v4
 with:
 version: latest
 args: release --clean --timeout 120m
 env:
 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 LDFLAGS: "-buildmode=c-shared"
 GOPATH: /home/runner/go

Final result

name: Release Plugins

on:
 push:
 tags:
 - '[0-9]+\.[0-9]+\.[0-9]+'

env:
 OCI_REGISTRY: ghcr.io
 PLUGIN_NAME: {PLUGIN_NAME}

permissions:
 contents: write
 packages: write

jobs:
 publish-oci-artifacts:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout Falcoctl Repo
 uses: actions/checkout@v3
 with:
 repository: falcosecurity/falcoctl
 ref: 0.5.0 # adapt to the latest version
 path: tools/falcoctl
 - name: Setup Golang
 uses: actions/setup-go@v4
 with:
 go-version: '^1.20'
 cache-dependency-path: tools/falcoctl/go.sum
 - name: Build falcoctl
 run: make
 working-directory: tools/falcoctl
 - name: Checkout
 uses: actions/checkout@v3
 with:
 path: plugin
 - name: Build the plugin
 run: make build
 working-directory: plugin
 - id: StringRepoName
 uses: ASzc/change-string-case-action@v5
 with:
 string: ${{ github.repository }}
 - name: Upload OCI artifacts to GitHub packages
 run: |
 MAJOR=$(echo ${{ github.ref_name }} | cut -f1 -d".")
 MINOR=$(echo ${{ github.ref_name }} | cut -f1,2 -d".")
 DIR=$(pwd)

 cd plugin/
 $DIR/tools/falcoctl/falcoctl registry push \
 ${{ env.OCI_REGISTRY }}/${{ steps.StringRepoName.outputs.lowercase }}/plugin/${{ env.PLUGIN_NAME }}:${{ github.ref_name }} \
 --config /dev/null \
 --type plugin \
 --version "${{ github.ref_name }}" \
 --tag latest --tag $MAJOR --tag $MINOR \
 --platform linux/amd64 \
 --requires plugin_api_version:2.0.0 \
 --depends-on ${{ env.PLUGIN_NAME }}-rules:${{ github.ref_name }} \
 --name ${{ env.PLUGIN_NAME }} \
 lib${{ env.PLUGIN_NAME }}.so

 cd rules/
 $DIR/tools/falcoctl/falcoctl registry push \
 ${{ env.OCI_REGISTRY }}/${{ steps.StringRepoName.outputs.lowercase }}/ruleset/${{ env.PLUGIN_NAME }}:${{ github.ref_name }} \
 --config /dev/null \
 --type rulesfile \
 --version "${{ github.ref_name }}" \
 --tag latest --tag $MAJOR --tag $MINOR \
 --depends-on ${{ env.PLUGIN_NAME }}:${{ github.ref_name }} \
 --name ${{ env.PLUGIN_NAME }}-rules \
 ${{ env.PLUGIN_NAME }}_rules.yaml
 env:
 FALCOCTL_REGISTRY_AUTH_BASIC: ${{ env.OCI_REGISTRY }},${{ github.repository_owner }},${{ secrets.GITHUB_TOKEN }}

 release:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout
 uses: actions/checkout@v3
 with:
 fetch-depth: 0
 - name: Setup Golang
 uses: actions/setup-go@v3
 with:
 go-version: '1.19'
 - name: Run GoReleaser
 uses: goreleaser/goreleaser-action@v4
 with:
 version: latest
 args: release --clean --timeout 120m
 env:
 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 LDFLAGS: "-buildmode=c-shared"
 GOPATH: /home/runner/go

Replace PLUGIN_NAME with the name of your plugin.

The index.yaml file for falcoctl

This file is used by falcoctl to know where to download your plugin and rules. Please read this blog post to understand better how it works.

We'll create our own file to allow like the following:

- name: {PLUGIN_NAME}
 type: plugin
 registry: ghcr.io
 repository: {OWNER_NAME}/{REPO_NAME}/plugin/{PLUGIN_NAME}
 description: {DESCRIPTION}
 home: https://github.com/{OWNER_NAME}/{PLUGIN_NAME}
 keywords:
 - {PLUGIN_NAME}
 license: Apache-2.0
 maintainers:
 - email: {OWNER_EMAIL}
 name: {OWNER_REAL_NAME}
 sources:
 - https://github.com/{OWNER_NAME}/{PLUGIN_NAME}
- name: {PLUGIN_NAME}-rules
 type: rulesfile
 registry: ghcr.io
 repository: {OWNER_NAME}/{REPO_NAME}/ruleset/docker
 description: Rules for the {PLUGIN_NAME} plugin
 home: https://github.com/{OWNER_NAME}/{REPO_NAME}/tree/main/rules
 keywords:
 - {PLUGIN_NAME}
 license: Apache-2.0
 maintainers:
 - email: {OWNER_EMAIL}
 name: {OWNER_REAL_NAME}
 sources:
 - https://github.com/{OWNER_NAME}/{REPO_NAME}/tree/main/rules/{PLUGIN_NAME}_rules.yaml

With:

PLUGIN_NAME: the name of you plugin
OWNER_NAME: your nickname on Github
REPO_NAME: the name of your repo for your plugin on Github
OWNER_EMAIL: an email for contact
OWNER_REAL_NAME: your real name or not
DESCRIPTION: description of your plugin

falcoctl uses the keywords field to perform a search among your plugins. Leverage this functionality by adding relevant terms to your plugin.

The repository structure should look like the following:

├── .github
│ └── workflows
│ └── release.yaml
├── .gitignore
├── go.mod
├── .goreleaser.yml
├── go.sum
├── index.yaml
├── LICENSE
├── Makefile
├── README.md
├── pkg
│ └── {PLUGIN_NAME}.go
├── plugin
│ └── main.go
└── rules
 └── {PLUGIN_NAME}_rules.yaml

There are 2 ways to expose the index.yaml file:

exposing the raw file: https://raw.githubusercontent.com/{OWNER_NAME}/{REPO_NAME}/main/index.yaml
exposing the file through Github Page: https://{OWNER_NAME}.github.io/{REPO_NAME}/index.yaml (make sure to enable the Pages)

Create our first version

Everything is now ready to publish a first version of our plugin.

In the main branch, run:

git tag 0.1.0 -m "0.1.0" && git push origin 0.1.0

Few seconds after, your workflow should be started and you will have your first published version with associated artifacts.

Installation of your plugin and rules

The process is now the same as the one described here, except we'll use your specific index.yaml to register a new index:

sudo falcoctl index add {PLUGIN_NAME} https://{OWNER_NAME}.github.io/{REPO_NAME}/index.yaml
sudo falcoctl artifact install {PLUGIN_NAME}
sudo falcoctl artifact install {PLUGIN_NAME}-rules

For the docker plugin, for example:

❯ sudo falcoctl index add docker http://issif.github.io/docker-plugin/index.yaml

❯ sudo falcoctl artifact search docker
INDEX ARTIFACT TYPE REGISTRY REPOSITORY
docker docker plugin ghcr.io issif/docker-plugin/plugin/docker
docker docker-rules rulesfile ghcr.io issif/docker-plugin/ruleset/docker

❯ sudo falcoctl artifact install docker-rules
 INFO Reading all configured index files from "/root/.config/falcoctl/indexes.yaml"
 INFO Resolving dependencies ...
 INFO Installing the following artifacts: [docker:0.3.3 ghcr.io/issif/docker-plugin/ruleset/docker:latest]
 INFO Preparing to pull "ghcr.io/issif/docker-plugin/plugin/docker:0.3.3"
 INFO Pulling 9145239be00e: ############################################# 100%
 INFO Pulling 2073e106ba07: ############################################# 100%
 INFO Pulling 01ecf22a3821: ############################################# 100%
 INFO Artifact successfully installed in "/usr/share/falco/plugins"
 INFO Preparing to pull "ghcr.io/issif/docker-plugin/ruleset/docker:latest"
 INFO Pulling 3482c7ca931f: ############################################# 100%
 INFO Pulling 433ad24cb056: ############################################# 100%
 INFO Pulling e449b880035d: ############################################# 100%
 INFO Artifact successfully installed in "/etc/falco"

Docs: Falco Daemon Arguments

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

This page lists all arguments you can pass to Falco in your command line:

Falco Arguments

Falco - Cloud Native Runtime Security
Usage:
falco [OPTION...]
-h, --help Print this help list and exit.
-c <path> Configuration file. If not specified tries /etc/falco/falco.yaml.
--config-schema Print the config json schema and exit.
--rule-schema Print the rule json schema and exit.
--disable-source <event_source>
Turn off a specific <event_source>. By default, all loaded sources get enabled. Available sources are
'syscall' plus all sources defined by loaded plugins supporting the event sourcing capability. This option
can be passed multiple times, but turning off all event sources simultaneously is not permitted. This
option can not be mixed with --enable-source. This option has no effect when reproducing events from a
capture file.
--dry-run Run Falco without processing events. It can help check that the configuration and rules do not have any
errors.
--enable-source <event_source>
Enable a specific <event_source>. By default, all loaded sources get enabled. Available sources are
'syscall' plus all sources defined by loaded plugins supporting the event sourcing capability. This option
can be passed multiple times. When using this option, only the event sources specified by it will be
enabled. This option can not be mixed with --disable-source. This option has no effect when reproducing
events from a capture file.
--gvisor-generate-config [=<socket_path>(=/run/falco/gvisor.sock)]
DEPRECATED: Generate a configuration file that can be used for gVisor and exit. See --gvisor-config for
more details.
-i Print those events that are ignored by default for performance reasons and exit.
-L Show the name and description of all rules and exit. If json_output is set to true, it prints details about
all rules, macros, and lists in JSON format.
-l <rule> Show the name and description of the rule specified <rule> and exit. If json_output is set to true, it
prints details about the rule in JSON format.
--list [=<source>(=)] List all defined fields and exit. If <source> is provided, only list those fields for the source <source>.
Current values for <source> are "syscall" or any source from a configured plugin with event sourcing
capability.
--list-events List all defined syscall events, metaevents, tracepoint events and exit.
--list-plugins Print info on all loaded plugins and exit.
-M <num_seconds> Stop Falco execution after <num_seconds> are passed. (default: 0)
--markdown Print output in Markdown format when used in conjunction with --list or --list-events options. It has no
effect when used with other options.
-N Only print field names when used in conjunction with the --list option. It has no effect when used with
other options.
-o, --option <opt>=<val> Set the value of option <opt> to <val>. Overrides values in the configuration file. <opt> can be identified
using its location in the configuration file using dot notation. Elements of list entries can be accessed
via square brackets [].
E.g. base.id = val
base.subvalue.subvalue2 = val
base.list[1]=val
--plugin-info <plugin_name>
Print info for the plugin specified by <plugin_name> and exit.
This includes all descriptive information like name and author, along with the
schema format for the init configuration and a list of suggested open parameters.
<plugin_name> can be the plugin's name or its configured 'library_path'.
-p, --print <output_format> DEPRECATED: use -o append_output... instead. Print additional information in the rule's output.
Use -pc or -pcontainer to append container details to syscall events.
Use -pk or -pkubernetes to add both container and Kubernetes details to syscall events.
The details will be directly appended to the rule's output.
Alternatively, use -p <output_format> for a custom format. In this case, the given <output_format> will be
appended to the rule's output without any replacement to all events, including plugin events.
-P, --pidfile <pid_file> Write PID to specified <pid_file> path. By default, no PID file is created. (default: "")
-r <rules_file> Rules file or directory to be loaded. This option can be passed multiple times. Falco defaults to the
values in the configuration file when this option is not specified. Only files with .yml or .yaml extension
are considered.
--support Print support information, including version, rules files used, loaded configuration, etc., and exit. The
output is in JSON format.
-U, --unbuffered Turn off output buffering for configured outputs. This causes every single line emitted by Falco to be
flushed, which generates higher CPU usage but is useful when piping those outputs into another process or a
script.
-V, --validate <rules_file> Read the contents of the specified <rules_file> file(s), validate the loaded rules, and exit. This option
can be passed multiple times to validate multiple files.
-v Enable verbose output.
--version Print version information and exit.
--page-size Print the system page size and exit. This utility may help choose the right syscall ring buffer size.

Docs: Falco Is Dropping Syscalls Events

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

Action Items (TL;DR)

Adjust the buf_size_preset in the falco.yaml config.
Utilize base_syscalls to limit the syscalls under monitoring.
Audit and optimize Falco rules to prevent unnecessary backpressure on the kernel, considering that Falco's main event stream is single-threaded.
Try running Falco without any plugins.

Background

Falco monitors each syscall based on deployed Falco rules. Additionally, Falco requires a few more syscalls to function properly, see Adaptive Syscalls Selection:

The default configuration is conservative; consequently, there is an opportunity that you could optimize and even eliminate Falco dropping events, depending on the scope of monitoring you are seeking.
Utilize the base_syscalls config for precise override control alongside a resource-friendly suggestion of the absolute minimum additional syscalls needed to ensure proper functioning of Falco (set repair: true).

Falco monitors syscalls by hooking into kernel tracepoints. To transfer events from the kernel to userspace, it uses buffers. For each CPU, Falco allocates separate buffers. If you're using the modern_ebpf driver, you can choose to have fewer, larger buffers shared among multiple CPUs (contention, according to kernel experts, should not be a problem). The buffer size is fixed but can be adjusted in the buf_size_preset config. Increasing the size helps, but keep in mind that the benefits may not increase proportionally. Also, remember that a larger buffer means more preallocated memory.

buf_size_preset of 5 or 6 could be a valid option for large machines assuming you use the kmod or ebpf drivers.
For the modern_ebpf driver try a modern_ebpf.buf_size_preset of 6 or 7, along with a modern_ebpf.cpus_for_each_buffer of 4 or 6. Feel free to experiment and adjust these values as needed.

Lastly, while it may sound appealing to push all filtering into the kernel, it is not that straightforward. In the kernel, you are in the application context, and yes, you can slow down both the kernel and the application (for example, apps may then experience lower request rates). Checkout the Driver Kernel Testing Framework for more information. Additionally, in the kernel, you only have raw syscall arguments and can't easily correlate them with other events. All this being said, we are actively looking into ways to improve this and make the kernel logic smarter without sacrificing performance.

Kernel-side Syscalls Drops Metrics

Falco's metrics config (see also Falco Metrics) enables you to measure Falco's kernel-side syscall drops and provides a range of useful metrics related to software functioning. Key settings include:

kernel_event_counters_enabled: true
libbpf_stats_enabled: true (for ebpf or modern_ebpf drivers, enable /proc/sys/kernel/bpf_stats_enabled)

Here is an example metrics log snippet highlighting the fields crucial for this analysis. Pay close attention to falco.evts_rate_sec and scap.evts_rate_sec, as well as the monotonic drop counters categorizing syscalls into coarse-grained (non-comprehensive) categories. For more details, refer to the dedicated metrics section in the Falco Performance guide for a more detailed explanation.

{
 "output_fields": {
 "evt.source": "syscall",
 "falco.host_num_cpus": 96, # Divide *rate_sec by CPUs
 "falco.evts_rate_sec": 93345.1, # Taken between 2 metrics snapshots
 "falco.num_evts": 44381403800,
 "falco.num_evts_prev": 44045361392,
 # scap kernel-side counters
 "scap.evts_drop_rate_sec": 0.0, # Taken between 2 metrics snapshots
 "scap.evts_rate_sec": 93546.8, # Taken between 2 metrics snapshots
 "scap.n_drops": 0, # Monotonic counter all-time kernel side drops
 # Coarse-grained (non-comprehensive) categories for more granular insights
 "scap.n_drops_buffer_clone_fork_exit": 0,
 "scap.n_drops_buffer_close_exit": 0,
 "scap.n_drops_buffer_connect_enter": 0,
 "scap.n_drops_buffer_connect_exit": 0,
 "scap.n_drops_buffer_dir_file_exit": 0,
 "scap.n_drops_buffer_execve_exit": 0,
 "scap.n_drops_buffer_open_enter": 0,
 "scap.n_drops_buffer_open_exit": 0,
 "scap.n_drops_buffer_other_interest_exit": 0,
 "scap.n_drops_buffer_proc_exit": 0,
 "scap.n_drops_buffer_total": 0,
 "scap.n_drops_bug": 0,
 "scap.n_drops_page_faults": 0,
 "scap.n_drops_perc": 0.0, # Taken between 2 metrics snapshots
 "scap.n_drops_prev": 0,
 "scap.n_drops_scratch_map": 0,
 "scap.n_evts": 48528636923,
 "scap.n_evts_prev": 48191868502,
 # libbpf stats -> all-time kernel tracepoints invocations stats for a x86_64 machine
 "scap.sched_process_e.avg_time_ns": 2041, # scheduler process exit tracepoint
 "scap.sched_process_e.run_cnt": 151463770,
 "scap.sched_process_e.run_time_ns": 181866667867268,
 "scap.sys_enter.avg_time_ns": 194, # syscall enter (raw) tracepoint
 "scap.sys_enter.run_cnt": 933995602769,
 "scap.sys_enter.run_time_ns": 181866667867268,
 "scap.sys_exit.avg_time_ns": 205, # syscall exit (raw) tracepoint
 "scap.sys_exit.run_cnt": 934000454069,
 "scap.sys_exit.run_time_ns": 192201218598457
 },
 "rule": "Falco internal: metrics snapshot"
}

Precise Control Over Monitored Syscalls

Since Falco 0.35.0, you have precise control over the syscalls Falco monitors. Refer to the Adaptive Syscalls Selection blog post and carefully read the base_syscalls config description for detailed information.

Run Tests for Data-Driven Insights

Falco's current metrics system lacks direct syscalls counters to pinpoint high-volume culprits. In the meantime, deriving insights step by step is necessary until syscall counters become available in Falco's metrics system.

Generate a dummy rule designed not to trigger any alerts:

- macro: spawned_process
 condition: (evt.type in (execve, execveat))

- rule: TEST Simple Spawned Process
 desc: "Test base_syscalls config option"
 enabled: true
 condition: spawned_process and proc.name=iShouldNeverAlert
 output: "%evt.type"
 priority: WARNING

Now, run Falco with the dummy rule and the specified test cases (edit base_syscalls config). If you're open to it, consider sharing anonymized logs for further assessment by Falco maintainers or the community to explore potential solutions.

For each test, run Falco in dry-run debug mode initially to print the final set of syscalls.

sudo /usr/bin/falco -c /etc/falco/falco.yaml -r falco_rules_dummy.yaml -o "log_level=debug" -o "log_stderr=true" --dry-run

# Example Output for Test 2
XXX: (2) syscalls in rules: execve, execveat
XXX: +(16) syscalls (Falco's state engine set of syscalls): capset, chdir, chroot, clone, clone3, fchdir, fork, prctl, procexit, setgid, setpgid, setresgid, setresuid, setsid, setuid, vfork
XXX: (18) syscalls selected in total (final set): capset, chdir, chroot, clone, clone3, execve, execveat, fchdir, fork, prctl, procexit, setgid, setpgid, setresgid, setresuid, setsid, setuid, vfork

Subsequently, run Falco normally.

sudo /usr/bin/falco -c /etc/falco/falco.yaml -r falco_rules_dummy.yaml

Test 1: spawned_process only

base_syscalls:
 custom_set: [clone, clone3, fork, vfork, execve, execveat, procexit]
 repair: false

If Test 1 already fails, and you see drops even after adjusting the buf_size_preset and other parameters, Falco may be less usable on this particular system, unfortunately.

Test 2: spawned_process + minimum syscalls needed for Falco state (internal process cache table)

base_syscalls:
 custom_set: []
 repair: true

Test 3: network accept*

base_syscalls:
 custom_set: [clone, clone3, fork, vfork, execve, execveat, getsockopt, socket, bind, accept, accept4, close]
 repair: false

Test 4: network connect

base_syscalls:
 custom_set: [clone, clone3, fork, vfork, execve, execveat, getsockopt, socket, connect, close]
 repair: false

Test 5: open* syscalls

base_syscalls:
 custom_set: [clone, clone3, fork, vfork, execve, execveat, open, openat, openat2, close]
 repair: false

Test n

Continue custom testing to ensure effective monitoring of all desired syscalls on your servers without experiencing event drops or with minimal acceptable drops.

At What Kernel Event Rates Do Problems Generally Start?

This question presents a challenge as it's not solely about the pure "kernel event rate". In less realistic benchmarking tests, you could artificially drive the rates very high without dropping events. Therefore, we believe it is more complex in real-life production, involving not just event rates but also the actual nature of the events, and possibly bursts of events in very short periods of time.

Additionally, we believe it's best to normalize the event rates by the number of CPUs (e.g. scap.evts_rate_sec / falco.host_num_cpus). Busier servers with 96, 128, or more CPUs naturally have higher event rates than VMs with 12 CPUs, for instance.

Nevertheless, here are some numbers we have heard from various adopters. Please take them with a grain of salt:

Less than ~1K kernel events per second per one CPU usually is not a problem, but it depends.
Less than ~1.5K kernel events per second per one CPU should not be a problem, but it depends.
More than 3K kernel events per second per one CPU likely could be more difficult to keep up, but it depends.
Consider 1-2% of all events dropped on a smaller subset of servers in your fleet (your busy servers/clusters) as acceptable.
More than 164K kernel events per second per CPU have been observed on a 128-CPU machine. Currently under exploration is how to solve this.

References and Community Discussions

Docs: Alert Formatting

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

Previous guides introduced the Output Fields of Falco Rules and provided Guidelines on how to use them. This section highlights additional global formatting options for your deployment, complementing the information previously provided.

Adding the same output field to multiple rules by manually editing rule files can be tedious. Fortunately, Falco provides several ways to simplify this process:

Using the append_output configuration option in falco.yaml to add output text or fields to a subset of loaded rules
Adding an override to a specific rule to replace its output

Appending Extra Output and Fields with `append_output`

The append_output option can be specified in the falco.yaml configuration file. You can use it to add extra output to rules specified by source, tag, name, or to all rules unconditionally. The append_output section is a list of items that are applied in the order they appear.

Example:

append_output:
 - match:
 source: syscall
 extra_output: "on CPU %evt.cpu"
 extra_fields:
 - home_directory: "${HOME}"
 - evt.hostname

In this example:

Every rule with the syscall source will have on CPU %evt.cpu appended at the end of the regular output line.
The rule will also include the additional fields (home_directory and evt.hostname) in the JSON output under output_fields. These extra fields do not appear in the regular (text) output.
Environment variables (like $HOME) expansion is supported in the configuration file, so for extra_fields as well.

Matching Rules

The match section allows you to filter which rules are modified:

source: filters rules by source (e.g., syscall or plugin names)
rule: filters by the complete rule name
tags: filters by a list of tags (all listed tags must be present)

If multiple conditions are specified under match, all must be met for the entry to apply. If no conditions are specified—or match is omitted—then the entry applies to all rules.

Adding an Override to a Specific Rule

Note that append_output only adds output to an existing rule; it does not remove or replace existing fields. To remove or replace output fields, you can add another rule file (loaded after the original) that uses an override. For example:

- rule: Read sensitive file trusted after startup
 output: A file (user=%user.name command=%proc.cmdline file=%fd.name) was read after startup
 override:
 output: replace

Suggested Output Fields

By default, Falco can also include "suggested" fields from plugins implementing the extraction capabilities. This is especially useful if certain plugins mark some fields as recommended for output. Those fields will appear automatically in your alerts.

Below is an example configuration entry that enables suggested output fields unconditionally for any source:

append_output:
 - suggested_output: true # Enable the use of extractor plugins' suggested fields for all matching sources.

When suggested_output is set to true, any extractor plugin that provides "suggested" fields will add them to the output in the form plugin_field_name=$plugin.field_name.

Command-Line Usage

You can also specify this option on the command line via the -o flag, for example:

falco ... \
 -o 'append_output[]={"match": {"source": "syscall"}, "extra_output": "on CPU %evt.cpu", "extra_fields": ["evt.hostname"]}'

Docs: How to Share Your Falco Rules

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

You can open a PR against the rules repo to share your rule with the community. The PR review process ensures that the rules align with the project's best interests as per our governance, follow the style guide, and meet the additional requirements, including testing and maturity level outlined in the rules repo contributing guide. Reviewers will support you throughout the process.

Docs: Kernel Events Architecture

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

This document describes the overall architecture that allows events from kernel sources to be ingested by Falco, how to use the libraries to inspect the data collection flow and how Falco manages the boundary between the kernel and userspace. In order to make Falco compatible with a very large number of Linux Kernel versions, the internal APIs and low level communication mechanisms that are employed to cross the kernel and userspace boundary vary greatly between driver types and may be different between driver versions or kernel versions. However, they all implement the same event collection interface as described below.

How Falco interacts with kernel components

The component of the Falco libraries that gathers data from the syscalls and interacts with the kernel is called libscap. Internally, it implements all functionality required to use the drivers to collect kernel events.

When using the kernel module or legacy eBPF probe (deprecated), the driver will need to be installed and deployed separately as a kernel object or probe, while the modern eBPF probe can be installed directly by libscap.

Upon connection to its kernel counterpart, libscap will need to negotiate the API Version and Schema Version that the driver recognizes. These versions are expressed with a semver subset and are documented in the libs repository.

The API version refers to the communication mechanism between the kernel and userspace. Every driver has a different communication mechanism which changes between versions. The kernel module may use ioctls and a ring buffer, while the eBPF probe can use maps and different APIs depending on the kernel version and eBPF probe edition. Since some drivers can be deployed separately from Falco, at startup libscap will verify if the driver it's connecting to is compatible.
The Schema version refers to the type of events that the specific driver supports. The Syscall Events documentation page shows the list of fields that are supported for each version of Falco. Every time that list changes the version number is updated as well.

When running Falco it is possible to verify the currently compatible version numbers with falco --version. For instance, this is the output for Falco 0.35.1:

# falco --version
2023-07-01T16:23:43+0000: Falco version: 0.35.1 (x86_64)
2023-07-01T16:23:43+0000: Falco initialized with configuration file: /etc/falco/falco.yaml
Falco version: 0.35.1
Libs version: 0.11.3
Plugin API: 3.0.0
Engine: 17
Driver:
API version: 4.0.0
Schema version: 2.0.0
Default driver: 5.0.1+driver

Once Falco is running, a stream of events is returned directly from the kernel. libscap's API allow the data to flow with a consistent format from the kernel to userspace.

The main interface that governs this is the scap event format. Once the chosen driver is loaded and initialized in the kernel, the events are encoded with a specific header and a payload:

struct ppm_evt_hdr {
uint64_t ts; /* timestamp, in nanoseconds from epoch */
uint64_t tid; /* the tid of the thread that generated this event */
uint32_t len; /* the event len, including the header */
uint16_t type; /* the event type */
uint32_t nparams; /* the number of parameters of the event */
};

The payload contains an array of lengths of each parameter followed by the content of the parameters themselves. The parameter type is a numeric identifer that maps with each event documented in the reference.

For example, the dup3 event is defined in the reference as:

dup3(FD res, FD oldfd, FD newfd, FLAGS32 flags: O_LARGEFILE, O_DIRECTORY, O_DIRECT, O_TRUNC, O_SYNC, O_NONBLOCK, O_EXCL, O_DSYNC, O_APPEND, O_CREAT, O_RDWR, O_WRONLY, O_RDONLY, O_CLOEXEC, O_NONE, O_TMPFILE)

Meaning that its encoding will be composed of an header containing the timestamp and tid, nparams will be 4 and the complete encoding will be:

[header] [uint16(8)] [uint16(8)] [uint16(8)] [uint16(32)] [res] [oldfd] [newfd] [flags]

Use scap-open to inspect kernel data collection

Contributors and expert users can find a tool called scap-open in the libs repo. This tool allows to dump raw events from a variety of drivers. Building and usage instructions are included in the repository.

Docs: Try Falco on Kubernetes

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

First, ensure you can access a test Kubernetes cluster running with Linux nodes, either x86_64 or ARM64. Note that using Docker Desktop on Windows or macOS will not work for this purpose. Also, you will need to have kubectl and helm installed and configured.

Deploy Falco

First, install the helm repository:

helm repo add falcosecurity https://falcosecurity.github.io/charts
helm repo update

Then install Falco:

helm install --replace falco --namespace falco --create-namespace --set tty=true falcosecurity/falco

And check that the Falco pods are running:

kubectl get pods -n falco

Falco pod(s) might need a few seconds to start. Wait until they are ready:

kubectl wait pods --for=condition=Ready --all -n falco

Falco comes with a pre-installed set of rules that alert you upon suspicious behavior.

Trigger a rule

Let's create a deployment:

kubectl create deployment nginx --image=nginx

And execute a command that would trigger a rule:

kubectl exec -it $(kubectl get pods --selector=app=nginx -o name) -- cat /etc/shadow

Now let's take a look at the Falco logs:

kubectl logs -l app.kubernetes.io/name=falco -n falco -c falco | grep Warning

You will see logs for all the Falco pods deployed on the system. The Falco pod corresponding to the node in which our nginx deployment is running has detected the event, and you'll be able to read a line like:

09:46:05.727801343: Warning Sensitive file opened for reading by non-trusted program (file=/etc/shadow gparent=systemd ggparent=<NA> gggparent=<NA> evt_type=openat user=root user_uid=0 user_loginuid=-1 process=cat proc_exepath=/usr/bin/cat parent=containerd-shim command=cat /etc/shadow terminal=34816 container_id=bf74f1749e23 container_image=docker.io/library/nginx container_image_tag=latest container_name=nginx k8s_ns=default k8s_pod_name=nginx-7854ff8877-h97p4)

This is your first Falco event 🦅! If you are curious, this is the rule that describes it.

Create a custom rule

Create a file and call it falco_custom_rules_cm.yaml with the following content:

customRules:
 custom-rules.yaml: |-
 - rule: Write below etc
 desc: An attempt to write to /etc directory
 condition: >
 (evt.type in (open,openat,openat2) and evt.is_open_write=true and fd.typechar='f' and fd.num>=0)
 and fd.name startswith /etc
 output: "File below /etc opened for writing | file=%fd.name pcmdline=%proc.pcmdline gparent=%proc.aname[2] ggparent=%proc.aname[3] gggparent=%proc.aname[4] evt_type=%evt.type user=%user.name user_uid=%user.uid user_loginuid=%user.loginuid process=%proc.name proc_exepath=%proc.exepath parent=%proc.pname command=%proc.cmdline terminal=%proc.tty"
 priority: WARNING
 tags: [filesystem, mitre_persistence]

And load it into Falco:

helm upgrade --namespace falco falco falcosecurity/falco --set tty=true -f falco_custom_rules_cm.yaml

Falco pod(s) might need a few seconds to restart. Wait until they are ready:

kubectl wait pods --for=condition=Ready --all -n falco

Then trigger our new rule:

kubectl exec -it $(kubectl get pods --selector=app=nginx -o name) -- touch /etc/test_file_for_falco_rule

And look at the logs:

kubectl logs -l app.kubernetes.io/name=falco -n falco -c falco | grep Warning

You should see a log entry like the one below:

13:14:27.811647863: Warning File below /etc opened for writing (file=/etc/test_file_for_falco_rule pcmdline=containerd-shim -namespace k8s.io -id d5438fedb274ac82963d99987313dae8da512236ace2f70472a772d95090b607 -address /run/containerd/containerd.sock gparent=systemd ggparent=<NA> gggparent=<NA> evt_type=openat user=root user_uid=0 user_loginuid=-1 process=touch proc_exepath=/usr/bin/touch parent=containerd-shim command=touch /etc/test_file_for_falco_rule terminal=34816 container_id=bf74f1749e23 container_image=docker.io/library/nginx container_image_tag=latest container_name=nginx k8s_ns=default k8s_pod_name=nginx-7854ff8877-h97p4)

Deploy Falcosidekick and Falcosidekick UI

In the previous step we displayed the rule output by examining the Falco log for the pod in the cluster that is running on the node. Now we will see how we can forward these alerts to a custom location or display them in a clean GUI. There are many ways to accomplish this but one is by using Falcosidekick which can easily be deployed with the same Helm chart.

Install Falcosidekick and Falcosidekick-UI in your test cluster:

helm upgrade --namespace falco falco falcosecurity/falco -f falco_custom_rules_cm.yaml --set falcosidekick.enabled=true --set falcosidekick.webui.enabled=true

Now check that it is running and its service is set up:

kubectl -n falco get svc

You should see something like this:

NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
falco-falcosidekick ClusterIP 10.43.212.119 <none> 2801/TCP 61s
falco-falcosidekick-ui ClusterIP 10.43.35.87 <none> 2802/TCP 60s

Display events in the Falcosidekick UI

Forward the UI port, which is 2802:

kubectl -n falco port-forward svc/falco-falcosidekick-ui 2802

And point your browser to http://localhost:2802 . The default username and password are admin / admin.

Now click on "Events" on top of the page and trigger an event again:

kubectl exec -it $(kubectl get pods --selector=app=nginx -o name) -- cat /etc/shadow

You should see an event appearing in the Falcosidekick UI

The Falcosidekick UI can be used to quickly display events but most likely on a production system you will want to forward events to a centralized location. Falcosidekick supports more than 60 integrations. You can find an example below but you can refer to the forwarding documentation to learn more.

Forward events to a Slack webhook

Deploy Falco again, this time disabling the web UI and enabling Slack forwarding. Of course, you can enable both if you wish.

helm upgrade --namespace falco falco falcosecurity/falco \
 --set falcosidekick.enabled=true \
 --set falcosidekick.config.slack.webhookurl=YOUR_WEBHOOK_URL_HERE \
 --set falcosidekick.config.slack.minimumpriority=notice

If Slack is configured correctly, when an event is triggered you should receive a message like the following:

Cleanup

If you wish to remove Falco from your cluster you can simply run:

helm -n falco uninstall falco

Docs: How Falco Uses Plugins

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

Falco loads plugins based on configuration in falco.yaml. Currently, if a plugin with event sourcing capability is loaded then the only events processed are from that plugin; syscall events are disabled. There are other restrictions on loaded plugins (see below).

Loading plugins in Falco

The new plugins property in falco.yaml will define the set of plugins that Falco can load, and a new load_plugins property will control which plugins are actually loaded when Falco starts.

Here's an example:

plugins:
 - name: cloudtrail
 library_path: libcloudtrail.so
 init_config: ""
 open_params: ""
 - name: json
 library_path: libjson.so
 init_config: ""

# Optional
load_plugins: [cloudtrail, json]

For more information, see Falco Config Options.

The mechanics of loading a plugin are implemented in the libraries and leverage the dynamic library functionality of the operating system (dlopen/dlsym in unix, LoadLibrary/GetProcAddress in Windows). The plugin loading code also ensures that:

The plugin is valid, i.e. that it exports the set of expected symbols
The plugin has an API version number that is compatible with the plugin framework.
That only one plugin with event sourcing capability is loaded at a time for a given event source
If a mix of plugins for both event sourcing and field extraction are loaded for a given event source, that the exported fields have unique names that don't overlap across plugins

Event Sources and Falco Rules

Falco rules already have the notion of a source, using the source property in YAML rules objects. There is primarily one kind of event source: syscall. The source property in Falco rules maps a given rule to the event source on which the rule runs.

For example, given a plugin providing events with source aws_cloudtrail, and a Falco rule with source property aws_cloudtrail, the rule will be evaluated for any events returned by the AWS CloudTrail plugin.

Similarly, a plugin with field extraction capability that includes aws_cloudtrail in its set of event sources will have the opportunity to extract information from CloudTrail events. As a result, fields exported by the plugin can be put in a rule's condition, exception, or output properties when the rule has a source aws_cloudtrail.

Falco compiles rules/macros/lists selectively based on the set of loaded plugins (specifically, their event sources), instead of unconditionally as Falco is started. This is especially important for macros, which do not contain a source property, but might contain fields that are only implemented by a given plugin.

Plugin Versions and Falco Rules

To allow rules files to document the plugin versions they are compatible with, rules files can have a new top-level field required_plugin_versions. The field is optional, and if not provided no plugin compatibility checks will be performed. The syntax of required_plugin_versions is the following:

- required_plugin_versions:
 - name: <plugin_name>
 version: x.y.z
 ...

Below required_plugin_versions is a list of objects, where each object has name and version properties. If a plugin is loaded, and if an entry in required_plugin_versions has a matching name, then the loaded plugin version must be semver compatible with the version property.

Falco can load multiple rules files, and each file may contain its own required_plugin_versions property. In this case, name+version pairs across all files will be merged, and in the case of duplicate names all provided versions must be compatible.

Plugin Developer's Guide

If you are interested in authoring your own plugin, or modifying an existing plugin to add new functionality, we've written a developer's guide that documents the full plugin APIs and walks through two existing plugins to show how the API is used.

Docs: Macros to Override

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

Falco also provide Macros that should be overridden by the user to provide settings that are specific to a user's environment. The provided Macros can also be appended to in a local rules file.

The below macros contain values that can be overridden for a user's specific environment.

Common SSH Port

Override this macro to reflect ports in your environment that provide SSH services.

- macro: ssh_port
 condition: fd.sport=22

Allowed SSH Hosts

Override this macro to reflect hosts that can connect to known SSH ports (ie a bastion or jump box).

- macro: allowed_ssh_hosts
 condition: ssh_port

User Trusted Containers

Allowlist containers that are allowed to run in privileged mode.

- macro: user_trusted_containers
 condition: (container.image startswith sysdig/agent)

Containers Allowed to Spawn Shells

Allowlist containers that are allowed to spawn shells, which may be needed if containers are used in the CI/CD pipeline.

- macro: user_shell_container_exclusions
 condition: (never_true)

Containers Allowed to Communicate with EC2 Metadata Services

Allowlist containers that are allowed to communicate with the EC2 metadata service. Default: any container.

- macro: ec2_metadata_containers
 condition: container

Kubernetes API Server

Set the IP of your Kubernetes API Service here.

- macro: k8s_api_server
 condition: (fd.sip="1.2.3.4" and fd.sport=8080)

Containers Allowed to Communicate with the Kubernetes API

Allowlist containers that are allowed to communicate with the Kubernetes API Service. Requires k8s_api_server being set.

- macro: k8s_containers
 condition: >
 (container.image startswith gcr.io/google_containers/hyperkube-amd64 or
 container.image startswith gcr.io/google_containers/kube2sky or
 container.image startswith sysdig/agent or
 container.image startswith sysdig/falco or
 container.image startswith sysdig/sysdig)

Containers Allowed to Communicate with Kubernetes Service NodePorts

- macro: nodeport_containers
 condition: container

Docs: Advanced Performance Tuning

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

This document provides advanced performance tuning options for the syscall data source in Falco. It is intended for users who want to optimize the performance of their Falco deployment by customizing the syscall monitoring behavior.

Adaptive syscalls selection

Falco provides users flexibility to select different syscall monitoring behaviors tailored to their specific use cases. These options offer various degrees of control over system calls, directly configured through the falco.yaml file.

This section outlines the available configurations and their implications.

Default behavior

By default, Falco traces syscalls derived from:

Syscalls explicitly required by enabled Falco rules.
A predefined set essential for maintaining Falco's internal state engine, defined at compile-time.

With the default configuration:

base_syscalls.custom_set: []
base_syscalls.repair: false
base_syscalls.all: false

This ensures accurate state engine management but offers no end-user customization of the additional syscalls.

Monitoring all syscalls (`base_syscalls.all`)

Setting this option to true enables monitoring all events supported by Falco, including typically ignored events such as write:

base_syscalls.all: true

Use with caution, as this may negatively impact performance due to increased resource usage.

User-defined syscall set (`base_syscalls.custom_set`)

CAUTION: Misconfiguration may result in incomplete event logs or disrupt Falco's tracing capabilities.

This option allows you to explicitly define an additional set of syscalls to trace, supplementing those required by active Falco rules:

base_syscalls.custom_set: [clone, clone3, fork, execve, execveat, close]

It offers fine-grained control and can help optimize resource utilization according to your threat model and performance constraints.

Recommended syscall sets for typical scenarios:

Process monitoring: [clone, clone3, fork, vfork, execve, execveat, close]
Networking monitoring: [clone, clone3, fork, vfork, execve, execveat, close, socket, bind, getsockopt]
Accurate UID/GID tracking: Add [setresuid, setsid, setuid, setgid, setpgid, setresgid, capset, chdir, chroot, fchdir] to the relevant set.

Negative notation ("!syscall_name") is supported to explicitly exclude specific syscalls.

Automatic state engine management (`base_syscalls.repair`)

Recommended for most scenarios, enabling this option allows Falco to automatically select the minimal necessary set of syscalls beyond those explicitly required by enabled rules:

base_syscalls.repair: true
base_syscalls.custom_set: []
base_syscalls.all: false

This option ensures Falco's internal state engine integrity with minimal performance overhead, automatically incorporating best-practice syscall configurations.

Scenarios

Different configurations address various monitoring scenarios effectively:

Monitoring spawned processes under resource constraints
- Default: Insufficient
- custom_set and repair: Both viable, but repair is recommended for automatic correctness.
Monitoring spawned processes and network activity, excluding file opens
- Default: Insufficient
- custom_set and repair: Both suitable, with repair ensuring automatic correctness without manual intervention.
Flexible configurability for tailored monitoring
- Useful in environments requiring selective monitoring to optimize resources.
- Allows coexistence with other monitoring tools by minimizing duplication of work.
Comprehensive syscall monitoring
- All three configurations (default, custom_set, repair) can achieve complete syscall monitoring.
- Choice depends on user preference and performance trade-offs.

Notes

Use falco -i to list all events typically ignored in the default configuration.
Events marked EF_OLD_VERSION are not generated during live monitoring but may appear in .scap files.

Docs: CloudTrail Events

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

The Falco cloudtrail plugin can read AWS CloudTrail logs and emit events for each CloudTrail log entry.

This plug-in also includes out-of-the-box rules that can be used to identify interesting/suspicious/notable events in CloudTrail logs, including:

Console logins that do not use multi-factor authentication
Disabling multi-factor authentication for users
Disabling encryption for S3 buckets

Configuration

See the README for information on how to configure the plugin. The plugin initialization and open params strings/objects can be added to falco.yaml under the plugins configuration key.

Methods to read AWS CloudTrail logs

The plugin can be configured to read log files from:

A S3 bucket
A SQS queue that passes along SNS notifications about new log files
A local filesystem path

For more information on the open params syntax, see open params.

Terraform Module for CloudTrail | Prerequisites

In order to use the AWS CloudTrail plugin, you must enable CloudTrail logging for the account(s) you want to monitor. This must be done before using the plugin.

In addition, of the three options above, using an SQS queue provides the easiest-to-consume source of logs. With the SQS queue, the plugin can detect when the new log files are written and can automatically consume them.

However, this also requires creating multiple AWS cloud resources, such as SQS queues, SNS topics/subscriptions, IAM policy documents, etc., outside of Falco, which involve multiple manual steps.

To make this process easier, we've created a Terraform module that automatically creates these resources.

Docs: Alerts Forwarding

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

Falco alerts can easily be forwarded to third-party systems. Their JSON format allows them to be easily consumed for storage, analysis and reaction.

Falcosidekick

Falcosidekick is a proxy forwarder that acts as a central point for any fleet of Falco instances, using their HTTP outputs to send alerts.

It supports forwarding alerts to various outputs such as chat platforms, alerting systems, logs, storage services, and streaming systems.

Falcosidekick can also add custom fields to the alerts, filter them by priority and expose a Prometheus metrics endpoint.

The full documentation and the project repository are here.

Falcosidekick can be deployed with Falco in Kubernetes clusters with the official Falco Helm chart.

Its configuration can be made through a yaml file and/or env vars.

Outputs

Follow the links to know what are the settings of each output.

The available outputs in Falcosidekick are:

Chat

Metrics / Observability

Datadog
Influxdb
StatsD (for monitoring of falcosidekick)
DogStatsD (for monitoring of falcosidekick)
Prometheus (for both events and monitoring of falcosidekick)
Wavefront
Spyderbat
TimescaleDB
Dynatrace
OTEL Metrics (for both events and monitoring of falcosidekick)

Alerting

Logs

Object Storage

FaaS / Serverless

Message queue / Streaming

Email

SMTP

Database

Redis

Web

SIEM

AWS Security Lake

Workflow

n8n

Traces

OTEL Traces

Response engine

Falco Talon

Other

Policy Report

Installation in Kubernetes with Helm

See the available Helm values to configure Falcosidekick.

helm install falco falcosecurity/falco \
-n falco --create-namespace \
--set falcosidekick.enabled=true \
--set tty=true

Installation in Docker

Use the env vars to configure Falcosidekick.

docker run -d -p 2801:2801 -e SLACK_WEBHOOKURL=XXXX falcosecurity/falcosidekick:2.27.0

Installation on the host

Adapt the version and the architecture to your environment. You can find all the releases here.

sudo mkdir -p /etc/falcosidekick
wget https://github.com/falcosecurity/falcosidekick/releases/download/2.27.0/falcosidekick_2.27.0_linux_amd64.tar.gz && sudo tar -C /usr/local/bin/ -xzf falcosidekick_2.27.0_linux_amd64.tar.gz

See the example config file to create your own in /etc/falcosidekick/config.yaml.

To enable and start the service, you can use a systemd unit /etc/systemd/system/falcosidekick.service like this one:

[Unit]
Description=Falcosidekick
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
ExecStart=/usr/local/bin/falcosidekick -c /etc/falcosidekick/config.yaml
EOF

systemctl enable falcosidekick
systemctl start falcosidekick

Falcosidekick UI

Falcosidekick comes with its own interface to visualize the events and get statistics.

Installation in Kubernetes with Helm

You can install the UI at the same moment as Falcosidekick by adding the argument --set falcosidekick.webui.enabled=true.

helm install falco falcosecurity/falco \
-n falco --create-namespace \
--set falcosidekick.enabled=true \
--set falcosidekick.webui.enabled=true \
--set tty=true

Then create a port-forward to access it: kubectl port-forward svc falco-falcosidekick-ui 2802:2802 -n falco. The default credentials are admin/admin.

The full documentation and the repository of the project are here.

Docs: Falco Plugins Go SDK Walkthrough

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

Introduction

The Go SDK provides prebuilt constructs and definitions that help developing plugins by abstracting all the complexities related to the bridging between the C and the Go runtimes. The Go SDK takes care of satisfying all the plugin framework requirements without having to deal with the low-level details, by also optimizing the most critical code paths.

The SDK allows developers to choose either from a low-level set of abstractions, or from a more high-level set of packages designed for simplicity and ease of use. The best way to approach the Go SDK is to start by importing a few high-level packages, which is enough to satisfy the majority of use cases.

This section documents the Go SDK at a high-level, please refer to the official Go SDK documentation for deeper details.

Architecture of the Go SDK

Since Falcosecurity plugins run in a C runtime, the Go SDK has been designed to abstract most of the complexity related to writing C-compliant code acceptable by the plugin framework, so that developers can focus on writing Go code only.

At a high level, the SDK is on top of three fundamental packages with different levels of abstractions:

Package sdk is a container for all the basic types, definitions, and helpers that are reused across all the SDK parts.
Package sdk/symbols contains prebuilt implementations for all the C symbols that plugins must export to be accepted by the framework. The prebuilt C symbols are divided in many subpackages, so that each of them can be imported individually to opt-in/opt-out each symbol.
Package sdk/plugins provide high-level definition and base types for implementing plugin capabilities. This uses sdk/symbols internally and takes care of importing all the prebuilt C symbols required each plugin capability respectively. This is the main entrypoint for developers to write plugins in Go.

Two additional packages ptr and cgo are used internally to simplify and optimize the state management and the usage of C-allocated memory pointers.

For some use cases, developers can consider using the SDK layers selectively. This is meaningful only if developers wish to manually write part of the low-level C details of the framework in their plugins, but still want to use some parts of the SDK. However, this is discouraged if not for advanced use cases only. Developers are encouraged to use the sdk/plugins to build Falcosecurity plugins, which is easier to use and will have less frequent breaking changes.

Further details can be found in the documentation of each package: sdk, sdk/symbols, and sdk/plugins.

Getting Started

The SDK is built on top of a set of minimal composable interfaces describing the behavior of plugins and plugin instances. As such, developing plugins is as easy as defining a struct type representing the plugin itself, ensuring that the mandatory interface methods are defined on it, and then registering it to the SDK.

To use the Go SDK, all you need to import are the sdk and sdk/plugins packages. The first contains all the core types and definitions used across the rest of the SDK packages, whereas the latter contains built-in constructs to develop plugins. The subpackages sdk/plugins/source and sdk/plugins/extractor contain specialized definitions for the event sourcing and the field extraction capabilities respectively.

The dummy plugin, documented in the next sections, is a simple example that helps understand how to start writing Go plugins with this SDK. The SDK also provides a set of base examples to get you started with plugin development.

Defining a Plugin with Field Extraction Capability

In the Go SDK, a plugin with field extraction capability is a type implementing the following interface:

// sdk/plugins/extractor
type Plugin interface {
 ...
 Info() *sdk.Info
 Init(config string) error
 Fields() []sdk.FieldEntry
 Extract(req sdk.ExtractRequest, evt sdk.EventReader) error
}

Info() returns all the info about the plugin. The returned plugins.Info struct should be filled in by the plugin author and contains fields such as the plugin ID, name, description, etc.

Init() method is called to initialize a plugin when the framework allocates it. A user-defined configuration string is passed by the framework. This is where the plugin can initialize its internal state and acquire all the resources it needs.

Fields() returns an array of sdk.FieldEntry representing all the fields supported by a plugin for extraction. The order of the fields is relevant, as their index is used as an identifier during extraction.

Extract() extracts the value of one of the supported fields from a given event passed in by the framework. The sdk.ExtractRequest argument should be used to set the extracted value.

Optional Interfaces

type Destroyer interface {
 Destroy()
}

type InitSchema interface {
 InitSchema() *SchemaInfo
}

Plugins with field extraction capability can optionally implement the sdk.Destroyer interface. In that case, Destroy() will be called when the plugin gets destroyed and can be used to release any allocated resource. they can also also optionally implement the sdk.InitSchema interface. In that case, InitSchema() will be used to to return a schema describing the data expected to be passed as a configuration during the plugin initialization. This follows the semantics documented for get_init_schema. Currently, the schema must follow the JSON Schema specific, which in Go can also be easily auto-generated with external packages (e.g. alecthomas/jsonschema).

Defining a Plugin with Event Sourcing Capability

In the Go SDK, a plugin with event sourcing capability must specify two types, one of the plugin itself and one for the plugin instances, implementing the following interfaces respectively:

// sdk/plugins/source
type Plugin interface {
 ...
 Info() *sdk.Info
 Init(config string) error
 Open(params string) (Instance, error)
}

// sdk/plugins/source
type Instance interface {
 ...
 NextBatch(pState PluginState, evts EventWriters) (int, error)
}

The source.Plugin interface has many functions in common with extractor.Plugin.

Open() creates a new plugin instance to open a new stream of events. The framework provides the user-defined open parameters to customize the event source. The return value must implement the source.Instance interface, and its lifecycle ends when the event stream is closed.

The source.Instance interface represents plugin instances for an opened event stream, and has one mandatory method and a few optional ones.

NextBatch creates a new batch of events to be pushed in the event stream. The SDK provides a pre-allocated batch to write events into, in order to manage the used memory optimally.

Optional Interfaces

type Destroyer interface {
 Destroy()
}

type Closer interface {
 Close()
}

type InitSchema interface {
 InitSchema() *SchemaInfo
}

type OpenParams interface {
 OpenParams() ([]OpenParam, error)
}

type Progresser interface {
 Progress(pState sdk.PluginState) (float64, string)
}

type Stringer interface {
 String(evt sdk.EventReader) (string, error)
}

Plugins with event sourcing capabilities can optionally implement the sdk.Destroyer and sdk.InitSchema interfaces, just like mentioned in the section above.

Additionally, they can also implement the sdk.OpenParams interface. If requested by the application, the framework may call OpenParams() before opening the event stream to obtains some suggested values that would valid parameters for Open(). For more details, see the documentation of list_open_params.

Plugin instances can optionally implement the sdk.Closer, sdk.Progresser, and sdk.Stringer interfaces. If sdk.Closer is implemented, the Close() method is called while closing the event stream and can be used to release the resources used by the plugin instance. If sdk.Progresser is implemented, the Progress() method is called by the SDK when the framework requests progress data about the event stream of the plugin instance. Progress() must return a float64 with a value between 0 and 1 representing the current progress percentage, and a string representation of the same progress value. If sdk.Stringer is implemented, the String() method must return a string representation of an event created by the plugin, which is used by the framework as an extraction value of the evt.plugininfo field. The string representation should be on a single line and contain important information about the event.

Best Practices and Go SDK Prebuilts for Source Instances

Although the Go SDK gives developers high control and flexibility, in the general case implementing the sdk.NextBatcher interface is not trivial. Custom definitions of source.Instance require developers to be mindful of the following while implementing the NextBatch() function:

It should return as fast as possible and should try to fill-up event batch up to its maximum capacity
Listen for a timeout of few milliseconds and return the batch in its current state once the timeout is expired
Conceive the case in which Close() is called before NextBatch() has returned. This can potentially happen if the plugin framework receives signals such as SIGINT or SIGTERM
Minimize the number of memory allocations
Keep returning sdk.ErrEOF after returning it the first time

Considering the above, the SDK provides prebuilt implementations of source.Instance that satisfy a broad range of use cases, so that developers need to define their own type only if they have advanced or custom requirements.

// sdk/plugins/source

func NewPullInstance(pull source.PullFunc, options ...func(*<unexported-type>)) (source.Instance, error)

func NewPushInstance(evtC <-chan source.PushEvent, options ...func(*<unexported-type>)) (source.Instance, error)

source.NewPullInstance and source.NewPushInstance are two constructors for SDK-provided source.Instance implementations that cover the following use cases:

Pull Model: for when the event source can be implemented sequentially and the time required to generate a sequence of event is deterministic. This is implemented with a functional design, where the passed-in callback is expected to be non-suspensive and to return quickly
Push Model: for when the event source can be suspensive and there is no time guarantee regarding when an event gets produced. For instance, this applies for all event sources that generate events from webhook events. Given the event-driven nature of this use case, this is implemented by passing event data in the form of byte slices through a channel

The prebuilt source.Instances can be configured in the function constructors by using the Go options pattern. The SDK provides options for configuring and overriding all the default values:

// sdk/plugins/source

func WithInstanceContext(ctx context.Context) func(*<unexported-type>)

func WithInstanceTimeout(timeout time.Duration) func(*<unexported-type>)

func WithInstanceClose(close func()) func(*<unexported-type>)

func WithInstanceBatchSize(size uint32) func(*<unexported-type>)

func WithInstanceEventSize(size uint32) func(*<unexported-type>)

func WithInstanceProgress(progress func() (float64, string)) func(*<unexported-type>)

Here's an example of how the Pull Model prebuilt can be used to implement an event source:

func (m *MyPlugin) Open(params string) (source.Instance, error) {
 counter := uint64(0)
 pull := func(ctx context.Context, evt sdk.EventWriter) error {
 counter++
 if err := gob.NewEncoder(evt.Writer()).Encode(counter); err != nil {
 return err
 }
 evt.SetTimestamp(uint64(time.Now().UnixNano()))
 return nil
 }
 return source.NewPullInstance(pull)
}

Registering a Plugin in the SDK

After defining proper types for the plugin, the only thing remaining is to register it in the SDK so that it can be used in the plugin framework.

// sdk/plugins
type FactoryFunc func() plugins.Plugin

// sdk/plugins
func SetFactory(plugins.FactoryFunc)

// sdk/plugins/extractor
func Register(extractor.Plugin)

// sdk/plugins/source
func Register(source.Plugin)

The newly created plugin type need to be registered to the SDK in a Go init function and through the plugins.SetFactory() function. plugins.FactoryFunc is a function type that is used by the SDK to create plugins when requested by the plugin framework. Then, the source.Register() and extractor.Register() functions should be invoked inside the body of plugins.FactoryFunc functions to implement the event sourcing and the field extraction capabilities respectively.

The defined plugin types are expected to implement a given set of methods. Compilation will fail at the Register() functions if any of the required methods is not defined. Developers are encouraged to compose their structs with plugins.BasePlugin, and source.BaseInstance, which provide prebuilt boilerplate for many of those methods. In this way, developers just need to focus on implementing the few plugin-specific methods remaining.

Besides the interface requirements, the defined types can contain arbitrary fields and methods. State variable that must be maintained during the plugin lifecycle (or in the lifecycle of an opened event stream) must be contained in the defined types. In this way, the SDK can guarantee that the state variables are not disposed by the garbage collector.

Interacting with Events

Generating new events, and extracting field values from them, are the hottest path in the plugin framework and can happen at a very high rate. For this reason, the Go SDK optimizes the memory usage as much as possible, avoiding reallocations and copies wherever possible. Internally, this sometimes means reading and writing on C-allocated memory from Go code directly, which is efficient but also very unsafe and can lead to unstable code.

As such, the SDK provides the two sdk.EventReader and sdk.EventWriter interfaces, which enable developers to safely read and write from events while still fully leveraging the underlying memory optimizations. sdk.EventReader gives a read-only view of an event, with accessor methods for all the internal fields, and sdk.EventWriter does the same in read-only mode.

type EventReader interface {
 EventNum() uint64
 Timestamp() uint64
 Reader() io.ReadSeeker
}

type EventWriter interface {
 SetTimestamp(value uint64)
 Writer() io.Writer
}

Event data can either be read or written through the standard io.SeekReader and io.Writer interfaces, returned by the Reader() and Writer() methods respectively. The SDK hides behind these interfaces all the safety and optimization mechanisms.

For plugins with event sourcing capability, a reusable batch of sdk.EventWriters is automatically allocated in each plugin source instance after the Open() method returns. This slab-allocator creates reusable event data by using the default sdk.DefaultBatchSize and sdk.DefaultEvtSize constants. Developers can override the automatic allocation to define batches of arbitrary sizes in the Open() method, by calling the SetEvents() method on the newly opened plugin instance before returning it. The reusable event batch can be created with the sdk.NewEventWriters function, that takes the event data size and batch size as arguments.

func NewEventWriters(size, dataSize int64) (EventWriters, error)

Note that the size of the reusable event batch defines the maximum size of each event batch created by the plugin in NextBatch.

Compiling Plugins

After successfully writing a plugin, all you need is to compile it. Go allows compiling binaries as a C-compliant shared library with the -buildmode=c-shared flag. The build command will be something looking like:

go build -buildmode=c-shared -o <outname>.so *.go

The SDK takes care of generating all the required C exported functions that the plugin framework needs to load the plugin. Once built, your plugin is ready to be used in the Falcosecurity plugin system.

Example Go Plugin: `dummy`

This section walks through the implementation of the dummy. This plugin returns events that are just a number value that increases with each event generated. Each increase is 1 plus a random "jitter" value that ranges from [0:jitter]. The jitter value is provided as configuration to the plugin in plugin_init. The starting value and the maximum number of events are provided as open parameters to the plugin in plugin_open.

This will show how the above API functions are actually used in a functional plugin. The source code for this plugin can be found at dummy.go.

Initial Imports

package main

import (
 ...

 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/extractor"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/source"
)

Importing the sdk and sdk/plugins packages is the first step for developing a Falcosecurity plugin in Go. The sdk package contains all the core types and definitions used across the other packages of the SDK. The sdk/plugins package contains prebuilt constructs for defining new plugins.

The sdk/plugins/source and sdk/plugins/extractor packages are required to register the event sourcing and field extraction capabilities. dummy implements both of them.

The Go module falcosecurity/plugin-sdk-go has its own documentation, which gives deeper insights about the internal architecture of the SDK.

Defining the Plugin

In the Go SDK, plugins are defined by a set of composable tiny interfaces. To define a new plugin, the first step is to define a new struct type representing the plugin itself, and then register it to the SDK. Plugins with event sourcing capability, like dummy, must define an additional type representing the opened instance of the plugin event stream.

type PluginConfig struct {
 // This reflects potential internal state for the plugin. In
 // this case, the plugin is configured with a jitter.
 Jitter uint64 `json:"jitter" jsonschema:"description=A random amount added to the sample of each event (Default: 10)"`
}

type Plugin struct {
 plugins.BasePlugin
 // Will be used to randomize samples
 rand *rand.Rand
 // Contains the init configuration values
 config PluginConfig
}

type PluginInstance struct {
 source.BaseInstance
 // Copy of the init params from plugin_open()
 initParams string
 // The number of events to return before EOF
 maxEvents uint64
 // A count of events returned. Used to count against maxEvents.
 counter uint64
 // A semi-random numeric value, derived from this value and
 // jitter. This is put in every event as the data property.
 sample uint64
}

func init() {
 plugins.SetFactory(func() plugins.Plugin {
 p := &Plugin{}
 source.Register(p)
 extractor.Register(p)
 return p
 })
}

Plugin Info

An Info() method is needed to return a data struct containing all the plugin info. Info() is a required method for the defined plugin struct type. This plugin defined its info as a set of constants for simplicity, but it's not a requirement.

const (
 PluginID uint32 = 3
 PluginName = "dummy"
 PluginDescription = "Reference plugin for educational purposes"
 PluginContact = "github.com/falcosecurity/plugins"
 PluginVersion = "0.4.0"
 PluginEventSource = "dummy"
)

...

func (m *Plugin) Info() *plugins.Info {
 return &plugins.Info{
 ID: PluginID,
 Name: PluginName,
 Description: PluginDescription,
 Contact: PluginContact,
 Version: PluginVersion,
 RequiredAPIVersion: PluginRequiredApiVersion,
 EventSource: PluginEventSource,
 }
}

...

Initializing/Destroying the Plugin

The mandatory Init() method serves as an initialization entrypoint for plugins. This is where the user-defined configuration string is passed in by the framework. The internal state of the plugin should be initialized at this level. An error can be returned to abort the plugin initialization.

Defining the Destroy() method is optional but can be useful if some resource needs to be released before the plugin gets destroyed. The InitSchema() method is optional too, but it allows the framework to parse the init config automatically, thus avoiding the need of doing it manually inside Init().

// Set the config default values.
func (p *PluginConfig) setDefault() {
 p.Jitter = 10
}

// This returns a schema representing the configuration expected by the
// plugin to be passed to the Init() method. Defining InitSchema() allows
// the framework to automatically validate the configuration, so that the
// plugin can assume that it to be always be well-formed when passed to Init().
func (p *Plugin) InitSchema() *sdk.SchemaInfo {
 // We leverage the jsonschema package to autogenerate the
 // JSON Schema definition using reflection from our config struct.
 reflector := jsonschema.Reflector{
 // all properties are optional by default
 RequiredFromJSONSchemaTags: true,
 // unrecognized properties don't cause a parsing failures
 AllowAdditionalProperties: true,
 }
 if schema, err := reflector.Reflect(&PluginConfig{}).MarshalJSON(); err == nil {
 return &sdk.SchemaInfo{
 Schema: string(schema),
 }
 }
 return nil
}

// Since this plugin defines the InitSchema() method, we can assume
// that the configuration is pre-validated by the framework and
// always well-formed according to the provided schema.
func (m *Plugin) Init(cfg string) error {
 // initialize state
 m.rand = rand.New(rand.NewSource(time.Now().UnixNano()))
 // The format of cfg is a json object with a single param
 // "jitter", e.g. {"jitter": 10}
 // Empty configs are allowed, in which case the default is used.
 // Since we provide a schema through InitSchema(), the framework
 // guarantees that the config is always well-formed json.
 m.config.setDefault()
 json.Unmarshal([]byte(cfg), &m.config)
 return nil
}

func (m *Plugin) Destroy() {
 // nothing to do here
}

Opening/Closing a Stream of Events

A plugin instance is created when the plugin event stream is opened, which can happen more than once during the plugin lifecycle. Plugins with event sourcing capability are required to define an Open() method that creates a returns a new plugin instance. This is where the framework passes in the user-defined open parameters string.

The plugin instance type returned by Open() can define an optional Close() method bundling any additional deinitialization logic to run while closing the event stream.

func (m *Plugin) Open(prms string) (source.Instance, error) {
 // The format of params is a json object with two params:
 // - "start", which denotes the initial value of sample
 // - "maxEvents": which denotes the number of events to return before EOF.
 // Example:
 // {"start": 1, "maxEvents": 1000}
 var obj map[string]uint64
 err := json.Unmarshal([]byte(prms), &obj)
 if err != nil {
 return nil, fmt.Errorf("params %s could not be parsed: %v", prms, err)
 }
 if _, ok := obj["start"]; !ok {
 return nil, fmt.Errorf("params %s did not contain start property", prms)
 }

 if _, ok := obj["maxEvents"]; !ok {
 return nil, fmt.Errorf("params %s did not contain maxEvents property", prms)
 }

 return &PluginInstance{
 initParams: prms,
 maxEvents: obj["maxEvents"],
 counter: 0,
 sample: obj["start"],
 }, nil
}

func (m *PluginInstance) Close() {
 // nothing to do here
}

Returning new Events

New events are generated in batch by the NextBatch function. The function is mandatory for plugins with event sourcing capability and must be defined as a method of the plugin instance struct type. The pState argument is the plugin struct type initialized in Init(), passed in by the framework for ease of access. The plugin state is passed as an instance of the sdk.PluginState interface, so a manual cast is required to access the internal state variables defined in the struct type.

The evts parameter is a sdk-managed batch of events to be used for creating new events. For that, the SDK uses a slab allocator and reuses the same event batch at every iteration to improve performance. The length of the evts list represents the maximum size of each event batch. Each element of the batch is an instance of sdk.EventWriter that provides handy methods to write the event info and data. Event data can be written with the Go io.Writer interface.

If an error is returned, the SDK returns a failure to the framework and invalidates the current batch. The special errors sdk.ErrTimeout and sdk.ErrEOF have a special meaning, and are used to either advise the framework that no new events are currently available, or that the event stream is terminated.

func (m *PluginInstance) NextBatch(pState sdk.PluginState, evts sdk.EventWriters) (int, error) {
 // Return EOF if reached maxEvents
 if m.counter >= m.maxEvents {
 return 0, sdk.ErrEOF
 }

 // access the plugin state
 plugin := pState.(*Plugin)

 var n int
 var evt sdk.EventWriter
 for n = 0; m.counter < m.maxEvents && n < evts.Len(); n++ {
 evt = evts.Get(n)
 m.counter++

 // Increment sample by 1, also add a jitter of [0:jitter]
 m.sample += 1 + uint64(plugin.rand.Int63n(int64(plugin.config.Jitter+1)))

 // The representation of a dummy event is the sample as a string.
 str := strconv.Itoa(int(m.sample))

 // It is not mandatory to set the Timestamp of the event (it
 // would be filled in by the framework if set to uint_max),
 // but it's a good practice.
 evt.SetTimestamp(uint64(time.Now().UnixNano()))

 _, err := evt.Writer().Write([]byte(str))
 if err != nil {
 return 0, err
 }
 }
 return n, nil
}

Printing Events As Strings

Plugins with event sourcing capability can optionally have a String() method to format the contents of events created with a previous call to NextBatch(). The event data is readable through an instance of sdk.EventReader provided by the SDK. Internally, this allows safe memory access and an optimal reusage of the same buffer to maximize the performance of hot framework paths.

func (m *Plugin) String(evt sdk.EventReader) (string, error) {
 evtBytes, err := ioutil.ReadAll(evt.Reader())
 if err != nil {
 return "", err
 }
 evtStr := string(evtBytes)

 // The string representation of an event is a json object with the sample
 return fmt.Sprintf("{\"sample\": \"%s\"}", evtStr), nil
}

Defining Fields

This dummy plugin has field extraction capability and exports 3 fields:

dummy.value: the value in the event, as a uint64
dummy.strvalue: the value in the event, as a string
dummy.divisible: this field takes an argument and returns 1 if the value in the event is divisible by the argument (a numeric divisor). For example, if the value was 12, dummy.divisible[3] would return 1 for that event.

The Fields() method returns a slice of sdk.FieldEntry representing all the supported fields.

func (m *Plugin) Fields() []sdk.FieldEntry {
 return []sdk.FieldEntry{
 {
 Type: "uint64",
 Name: "dummy.divisible",
 Desc: "Return 1 if the value is divisible by the provided divisor, 0 otherwise",
 Arg: sdk.FieldEntryArg{IsRequired: true, IsKey: true},
 },
 {
 Type: "uint64",
 Name: "dummy.value",
 Desc: "The sample value in the event",
 },
 {
 Type: "string",
 Name: "dummy.strvalue",
 Desc: "The sample value in the event, as a string",
 },
 }
}

Extracting Fields

The Extract method extracts all of the supported fields. The req parameter allows accessing all the info regarding the field request, such as the field id or name, and the optional user-passed argument. The evt parameter is an interface that helps reading the event info and data.

The extracted field value must be set through the SetValue method of sdk.ExtractRequest. Returning from Extract without calling SetValue will signal the SDK that the requested field is not present in the given event.

func (m *Plugin) Extract(req sdk.ExtractRequest, evt sdk.EventReader) error {
 evtBytes, err := ioutil.ReadAll(evt.Reader())
 if err != nil {
 return err
 }
 evtStr := string(evtBytes)
 evtVal, err := strconv.Atoi(evtStr)
 if err != nil {
 return err
 }
 switch req.FieldID() {
 case 0: // dummy.divisible
 divisor, err := strconv.Atoi(req.ArgKey())
 if err != nil {
 return fmt.Errorf("argument to dummy.divisible %s could not be converted to number", req.ArgKey())
 }
 if evtVal%divisor == 0 {
 req.SetValue(uint64(1))
 } else {
 req.SetValue(uint64(0))
 }
 case 1: // dummy.value
 req.SetValue(uint64(evtVal))
 case 2: // dummy.strvalue
 req.SetValue(evtStr)
 default:
 return fmt.Errorf("no known field: %s", req.Field())
 }
 return nil
}

Running the Plugin

This plugin can be configured in Falco by adding the following to falco.yaml file:

plugins:
 - name: dummy
 library_path: /tmp/my-plugins/dummy/libdummy.so
 init_config:
 jitter: 10
 open_params: '{"start": 1, "maxEvents": 20}'

## Optional
load_plugins: [dummy]

This simple rule prints a Falco alert any time the event number is between 0 and 10, and the sample value is divisible by 3:

- rule: My Dummy Rule
 desc: My Desc
 condition: evt.num > 0 and evt.num < 10 and dummy.divisible[3] = 1
 output: A dummy event | event=%evt.plugininfo sample=%dummy.value sample_str=%dummy.strvalue num=%evt.num
 priority: INFO
 source: dummy

Here's what it looks like when run:

$ ./falco -r ../falco-files/dummy_rules.yaml -c ../falco-files/falco.yaml
Wed Feb 2 16:26:35 2022: Falco version 0.31.0 (driver version 319368f1ad778691164d33d59945e00c5752cd27)
Wed Feb 2 16:26:35 2022: Falco initialized with configuration file ../falco-files/falco.yaml
Wed Feb 2 16:26:35 2022: Loading plugin (dummy) from file /tmp/my-plugins/dummy/libdummy.so
Wed Feb 2 16:26:35 2022: Loading rules from file ../rules/dummy_rules.yaml:
Wed Feb 2 16:26:35 2022: Starting internal webserver, listening on port 8765
16:26:35.527827816: Notice A dummy event (event={"sample": "6"} sample=6 sample_str=6 num=1)
16:26:35.527829658: Notice A dummy event (event={"sample": "18"} sample=18 sample_str=18 num=3)
16:26:35.527831048: Notice A dummy event (event={"sample": "33"} sample=33 sample_str=33 num=8)
Events detected: 3
Rule counts by severity:
INFO: 3
Triggered rules by rule name:
My Dummy Rule: 3
Syscall event drop monitoring:
- event drop detected: 0 occurrences
- num times actions taken: 0

Docs: Install on a host (DEB, RPM)

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

For other installation scenarios, such as consuming cloud events or other data sources using plugins, please refer to the Plugins section.

There are two main methods to install Falco on your host using the released Falco packages:

RPM or DEB package (includes Systemd setup): This method is detailed on this page.
Tarball archive: For instructions, refer to the Install on a host (tarball) page.

System requirements

Falco runs on Linux and is available for the x86_64 and aarch64 architectures. Falco with its bundled plugins requires GLIBC 2.28 or newer. You can check your system's GLIBC version by running ldd --version.

Install

This installation method is for Linux distributions with a package manager that supports DEB (Debian, Ubuntu) or RPM (CentOS, RHEL, Fedora, Amazon Linux) packages.

In interactive installations, the Falco installation package uses the dialog binary for configuration prompts. The dialog allows the user to complete the Systemd setup which includes:

The driver selection (kmod, ebpf, modern_ebpf) or automatic selection
The Falcoctl service setup

In non-interactive installations (e.g., dialog is not available, or if the user disables it by setting FALCO_FRONTEND=noninteractive when installing Falco using the package manager), the automatic driver selection is enabled by default and for other options, the user needs to manually configure the Systemd services.

Env variables

The following environment variables can be used to customize the installation process:

FALCO_FRONTEND: Set to noninteractive to disable the dialog prompts. The default is dialog.
FALCO_DRIVER_CHOICE: Set to kmod, ebpf, or modern_ebpf to choose a driver; set to none to disable service installation. If one of the previous option is selected, the dialog will be skipped too. The default (empty) is automatic selection.
FALCOCTL_ENABLED: Set to no to disable the automatic rules update provided by falcoctl. The default (empty) or any value other than no will keep the option enabled.

These environment variables can be used in conjunction with the package manager (as described in the following sections) to customize the installation process as needed.

Examples:

No dialog, no driver, no automatic rules update:

FALCO_DRIVER_CHOICE=none apt-get install -y falco

Install with kmod driver and automatic rules update:

FALCO_DRIVER_CHOICE=kmod apt-get install -y falco

No dialog, automatic selection and automatic rules update:
```
FALCO_FRONTEND=noninteractive apt-get install -y falco
```

No dialog, automatic selection and no automatic rules update:

FALCO_FRONTEND=noninteractive FALCOCTL_ENABLED=no apt-get install -y falco

`apt` (Debian/Ubuntu)

The following steps are for Debian and Debian-based distributions, such as Ubuntu, which use the apt package manager.

Trust the falcosecurity GPG key

curl -fsSL https://falco.org/repo/falcosecurity-packages.asc | \
sudo gpg --dearmor -o /usr/share/keyrings/falco-archive-keyring.gpg

Configure the apt repository

echo "deb [signed-by=/usr/share/keyrings/falco-archive-keyring.gpg] https://download.falco.org/packages/deb stable main" | \
sudo tee -a /etc/apt/sources.list.d/falcosecurity.list

In older releases of Debian (Debian 9 and older ones), you might need to additionally install the package apt-transport-https to allow access to the Falco repository using the https protocol.

The following command will install that package on your system:

sudo apt-get install apt-transport-https

Update the package list
```
sudo apt-get update -y
```

Install some required dependencies that are needed to build the Kernel Module and the eBPF probe

Note: You don't need to install these dependencies if you want to use the Modern eBPF.

sudo apt install -y dkms make linux-headers-$(uname -r)
# If you use falcoctl driver loader to build the eBPF probe locally you need also clang toolchain
sudo apt install -y clang llvm
# You can install also the dialog package if you want it
sudo apt install -y dialog

Install the Falco package
```
sudo apt-get install -y falco
```

`yum` (CentOS/RHEL/Fedora/Amazon Linux)

Trust the falcosecurity GPG key

sudo rpm --import https://falco.org/repo/falcosecurity-packages.asc

Configure the yum repository

sudo curl -o /etc/yum.repos.d/falcosecurity.repo https://falco.org/repo/falcosecurity-rpm.repo

Update the package list
```
sudo yum update -y
```

Install some required dependencies that are needed to build the Kernel Module and the eBPF probe

Note: You don't need to install these dependencies if you want to use the Modern eBPF.

# If necessary install it using: `yum install epel-release` (or `amazon-linux-extras install epel` in case of amzn2), then `yum install make dkms`.
sudo yum install -y dkms make
# If the package was not found by the below command, you might need to run `yum distro-sync` in order to fix it. Rebooting the system may be required.
sudo yum install -y kernel-devel-$(uname -r)
# If you use falcoctl driver loader to build the eBPF probe locally you need also clang toolchain
sudo yum install -y clang llvm
# You can install also the dialog package if you want it
sudo yum install -y dialog

Install the Falco package
```
sudo yum install -y falco
```

You might need to validate the driver signature if your system has UEFI SecureBoot enabled. Follow these steps to do so:

Import the DKMS Machine Owner Key

 ```shell
sudo mokutil --import /var/lib/dkms/mok.pub
```

Restart the system and wait for the MOK key enrollment prompt
Choose the option: Enroll MOK

Load the Falco driver

 ```shell
sudo insmod /var/lib/dkms/falco/<driver-version>/$(uname -r)/x86_64/module/falco.ko.xz
```

RHEL 8 / UBI 8 users: Starting from Falco 0.42, you may need to set the LD_PRELOAD environment variable due to a glibc compatibility issue:

LD_PRELOAD=/lib64/libresolv.so.2 falco

When using systemd, you can add this to your service override or edit the unit file to include Environment="LD_PRELOAD=/lib64/libresolv.so.2".

`zypper` (openSUSE)

Trust the falcosecurity GPG key

sudo rpm --import https://falco.org/repo/falcosecurity-packages.asc

Configure the zypper repository

sudo curl -o /etc/zypp/repos.d/falcosecurity.repo https://falco.org/repo/falcosecurity-rpm.repo

Update the package list
```
sudo zypper -n update
```

Install some required dependencies that are needed to build the Kernel Module and the eBPF probe

Note: You don't need to install these dependencies if you want to use the Modern eBPF.

sudo zypper -n install dkms make
# If the package was not found by the below command, you might need to run `zypper -n dist-upgrade` in order to fix it. Rebooting the system may be required.
sudo zypper -n install kernel-default-devel-$(uname -r | sed s/\-default//g)
# If you use falcoctl driver loader to build the eBPF probe locally you need also clang toolchain
sudo zypper -n install clang llvm
# You can install also the dialog package if you want it
sudo zypper -n install dialog

Install Falco:
```
sudo zypper -n install falco
```
Uninstall Falco:
```
sudo zypper rm falco
```

Systemd setup

Setup with dialog

By default, if you have the dialog binary installed on your system, you will be prompted with this:

From here you can choose one of our 3 drivers Kmod, eBPF, Modern eBPF, a Manual configuration or the Automatic selection (recommended) to trigger the automatic logic to select the best driver for you. When you choose a driver from the dialog, the systemd service is always enabled by default so it will start at every system reboot. If you want to disable this behavior type systemctl disable falco-kmod.service (if you are using the kernel module like in this example).

After the first dialog, you should see a second one:

If you choose Yes, falcoctl will periodically check for ruleset updates and, if a new update is available, will pull and install it.

Manual configuration

If you chose Manual configuration from the dialog, you need to complete the setup configuration.

First, let's verify the available services:

$ sudo systemctl list-unit-files "falco*"

UNIT FILE STATE PRESET
falco-bpf.service disabled enabled
falco-custom.service disabled enabled
falco-kmod-inject.service static enabled
falco-kmod.service disabled enabled
falco-modern-bpf.service disabled enabled
falcoctl-artifact-follow.service disabled enabled

Using the systemctl command, you can now enable the desired unit to start at boot time.

Let's say you want to enable the modern eBPF probe:

$ sudo systemctl enable falco-modern-bpf.service
Created symlink /etc/systemd/system/falco.service → /usr/lib/systemd/system/falco-modern-bpf.service.
Created symlink /etc/systemd/system/multi-user.target.wants/falco-modern-bpf.service → /usr/lib/systemd/system/falco-modern-bpf.service.

$ sudo systemctl list-unit-files "falco*"

UNIT FILE STATE PRESET
falco-bpf.service disabled enabled
falco-custom.service disabled enabled
falco-kmod-inject.service static -
falco-kmod.service disabled enabled
falco-modern-bpf.service enabled enabled
falco.service alias -
falcoctl-artifact-follow.service disabled enabled

Or you'd like to switch to using the kernel module:

$ sudo systemctl disable falco-modern-bpf.service
Removed "/etc/systemd/system/multi-user.target.wants/falco-modern-bpf.service".
Removed "/etc/systemd/system/falco.service".

$ sudo systemctl enable falco-kmod.service
Created symlink /etc/systemd/system/falco.service → /usr/lib/systemd/system/falco-kmod.service.
Created symlink /etc/systemd/system/multi-user.target.wants/falco-kmod.service → /usr/lib/systemd/system/falco-kmod.service.

$ sudo systemctl list-unit-files "falco*"

UNIT FILE STATE PRESET
falco-bpf.service disabled enabled
falco-custom.service disabled enabled
falco-kmod-inject.service static -
falco-kmod.service enabled enabled
falco-modern-bpf.service disabled enabled
falco.service alias -
falcoctl-artifact-follow.service disabled enabled

7 unit files listed.

As you can see, enabling the falco-kmod.service, falco-modern-bpf.service or falco-custom.service also creates a new alias/service called falco.service that can be used in place of the aliased ones.

As a side note, if you prefer not to use the falcoctl tool to automatically update your rules, you can mask it as follows. Otherwise, as explained here, Falco will enable it too.

$ sudo systemctl mask falcoctl-artifact-follow.service
Created symlink /etc/systemd/system/falcoctl-artifact-follow.service → /dev/null.

Configuring services

If you installed the Falco packages using the dialog option, all your services should already be up and running. However, if you chose the Manual configuration option, you need to configure the services manually.

If you need to switch from one service to another, ensure that the current service is properly stopped before starting the new one. This can be done by using the appropriate service management commands for your system (e.g., systemctl stop <service_name> and systemctl start <new_service_name>).

For example, if you want to use the service for the eBPF probe:

Type systemctl list-units | grep falco to check that no unit is running. Stop the current services, if any.
Now you have to decide whether you want the Falcoctl service running together with the Falco one. If yes you don't have to do anything, else you will need to mask the Falcoctl service with systemctl mask falcoctl-artifact-follow.service. The Falcoctl service is strictly related to the Falco one so if you don't mask it, it will be started together with the Falco service.
Type falcoctl driver config --type ebpf to configure Falco to use eBPF probe, then falcoctl driver install to download/compile the eBPF probe.

Now running systemctl start falco-bpf.service and typing systemctl list-units | grep falco you should see something like that (supposing you didn't mask the Falcoctl service):

falco-bpf.service loaded active running Falco: Container Native Runtime Security with ebpf
falcoctl-artifact-follow.service loaded active running Falcoctl Artifact Follow: automatic artifacts update service

If you want to stop both services in one shot
```
systemctl stop falco-bpf.service
```

Falcoctl service (automatic rules update)

If this service is enabled (as default), typing systemctl list-units | grep falco you should see something similar to this:

falco-kmod-inject.service loaded active exited Falco: Container Native Runtime Security with kmod, inject.
falco-kmod.service loaded active running Falco: Container Native Runtime Security with kmod
falcoctl-artifact-follow.service loaded active running Falcoctl Artifact Follow: automatic artifacts update service

falco-kmod-inject.service injects the kernel module and exits. This unit remains after exit to detach the kernel module when the falco-kmod.service will be stopped.
falco-kmod.service instance of Falco running the kernel module.
falcoctl-artifact-follow.service instance of Falcoctl that searches for new rulesets. This unit will be stopped when falco-kmod.service terminates.

The Falcoctl service is strictly related to the Falco one:

when the Falco service starts it searches for a unit called falcoctl-artifact-follow.service and if present it starts it. Please note that following this pattern, if you enable the Falco service and you reboot your system, Falcoctl will start again with Falco even if you don't enable it through systemd enable! You can disable this behavior by stopping the Falcoctl service and masking it systemctl mask falcoctl-artifact-follow.service.
when the Falco service stops also the Falcoctl service is stopped.

In case the Falcoctl service is not enabled, the Falco package will only start the falco-kmod.service. Typing systemctl list-units | grep falco you should see something similar to this:

falco-kmod-inject.service loaded active exited Falco: Container Native Runtime Security with kmod, inject.
falco-kmod.service loaded active running Falco: Container Native Runtime Security with kmod

In this mode, the Falcoctl service is masked by default so if you want to enable it in a second step you need to type systemctl unmask falcoctl-artifact-follow.service.

Custom service

You may have noticed a Falco unit called falco-custom.service. You should use it when you want to run Falco with a custom configuration like a plugin. Please note that in this case you have to modify this template according to how you want to run Falco, the unit should not be used as is!

Configuration

The Falco configuration file is located at /etc/falco/falco.yaml. You can edit it to customize Falco's behavior.

Since Falco 0.38.0, a new config key, config_files, allows the user to load additional configuration files to override main config entries. This allows user to keep local customization between Falco upgrades. Its default value points to a new folder, /etc/falco/config.d/ that gets installed by Falco and will be processed to look for local configuration files.

Hot Reload

By default, with the watch_config_files configuration option enabled, Falco automatically monitors changes to configuration and rule files. When these files are modified, Falco will automatically reload the updated configuration without requiring a restart.

If this option is disabled, you can manually restart the Falco systemd service to apply the changes:

systemctl restart falco

Upgrade

`apt` (Debian/Ubuntu)

If you configured the apt repository by having followed the instructions for Falco 0.27.0 or older, you may need to update the repository URL, otherwise, feel free to ignore this message

sed -i 's,https://dl.bintray.com/falcosecurity/deb,https://download.falco.org/packages/deb,' /etc/apt/sources.list.d/falcosecurity.list
apt-get clean
apt-get -y update

Check in the apt-get update log that https://download.falco.org/packages/deb is present.

If you installed Falco by following the provided instructions:

apt-get --only-upgrade install falco

`yum` (CentOS/RHEL/Fedora/Amazon Linux)

If you configured the yum repository by having followed the instructions for Falco 0.27.0 or older, you may need to update the repository URL, otherwise, feel free to ignore this message

sudo sed -i 's,https://dl.bintray.com/falcosecurity/rpm,https://download.falco.org/packages/rpm,' /etc/yum.repos.d/falcosecurity.repo
sudo yum clean all

Then check that the falcosecurity-rpm repository is pointing to https://download.falco.org/packages/rpm/:

sudo sudo yum repolist -v falcosecurity-rpm

If you installed Falco by following the provided instructions:

Check for updates:
```
sudo yum check-update
```
If a newer Falco version is available:
```
sudo yum update falco
```

`zypper` (openSUSE)

If you configured the zypper repository by having followed the instructions for Falco 0.27.0 or older, you may need to update the repository URL, otherwise, feel free to ignore this message

sudo sed -i 's,https://dl.bintray.com/falcosecurity/rpm,https://download.falco.org/packages/rpm,' /etc/zypp/repos.d/falcosecurity.repo
sudo zypper refresh

Then check that the falcosecurity-rpm repository is pointing to https://download.falco.org/packages/rpm/:

sudo zypper lr falcosecurity-rpm

If you installed Falco by following the provided instructions:

sudo zypper update falco

Kernel Upgrades

When performing kernel upgrades on your host, a reboot is required. When using a eBPF probe or a Kernel Module driver, the Falco driver loader (i.e., falcoctl driver) should be able to automatically find a pre-built driver (or build it on the fly) corresponding to the updated kernel release (uname -r), making it easy to handle kernel upgrades. The Falco Project features a kernel crawler and automated CI, ensuring you can always obtain the necessary pre-built driver artifact, even for the latest kernel releases we support.

Uninstall

`apt` (Debian/Ubuntu)

sudo apt-get --purge autoremove falco

`yum` (CentOS/RHEL/Fedora/Amazon Linux)

sudo yum remove falco

`zypper` (openSUSE)

sudo zypper remove falco

Package signing

On December, 2025 we started rotating the GPG key used to sign Falco packages. Check out the related blog post and make sure you're using the most up-to-date key available at falco.org/repo/falcosecurity-packages.asc.

Most Falco packages available at download.falco.org are provided with a detached signature that can be used to verify that the package information downloaded from the remote repository can be trusted.

The latest trusted public GPG key used for packages signing can be downloaded from falco.org/repo/falcosecurity-packages.asc. The following table lists all the keys employed by the organization currently and in the past, including the revoked ones. We recommend updating the revoked keys to download their revocation certificate, and eventually removing them from your package verification system due to the signature made with them not being trustable anymore.

Fingerprint	Expiration	Usage	Status	Download
`478B2FBBC75F4237B731DA4365106822B35B1B1F`	2028-12-10	Signing Falco Packages	Trusted	falcosecurity-B35B1B1F.asc
`2005399002D5E8FF59F28CE64021833E14CB7A8D`	2026-01-17	Signing Falco Packages	Revoked	falcosecurity-14CB7A8D.asc
`15ED05F191E40D74BA47109F9F76B25B3672BA8F`	2023-02-24	Signing Falco Packages	Revoked	falcosecurity-3672BA8F.asc

Troubleshooting

This section aims to offer further guidance when something doesn't go as expected in the installation of Falco.

Unable to find a prebuilt driver

ERROR failed: unable to find a prebuilt driver

This error message appears when the falcoctl driver loader tool, which looks for the Falco driver and loads it in memory, is not able to find a pre-built driver, neither as an eBPF probe nor as a kernel module, at the [Falco driver repository] (https://download.falco.org).

You can easily browse and search the supported targets at download.falco.org/driver/site.

This means that there's no prebuilt driver available for the kernel running on the machine where Falco is going to be installed.

However, you can add your kernel release version to the build grid the pipeline refers to building the drivers. Follow this tutorial to contribute the required configuration.

There are a limited set of Linux distributions whose kernels are supported by the current prebuilt driver distribution pipeline.

driverkit is the tool used to build those drivers. Hence, it needs to support the specific Linux distribution. Find whether your Linux distribution is supported here.

Enable the BPF JIT Compiler

If you are using the eBPF probe, in order to ensure that performance is not degraded, make sure that:

Your kernel has CONFIG_BPF_JIT enabled
net.core.bpf_jit_enable is set to 1 (enable the BPF JIT Compiler)

This can be verified via sysctl -n net.core.bpf_jit_enable.

Docs: Missing Fields in Falco Logs

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

Action Items (TL;DR)

Read Install and Operate Guides and review falco.yaml for necessary preconditions.
Refer to the relevant debugging guide based on suspected missing fields.
Acknowledge that certain missing fields or data in Falco are legitimate.

Background

Many of the Supported Output Fields are derived from multiple events and mechanisms. To provide a more concrete explanation, for each spawned process, Falco extracts and derives fields from the clone*/*fork/execve* syscalls. Falco generates a struct in userspace, stores the relevant information within this struct, and then adds it to the process cache table in memory. If a process makes additional system calls during its lifetime, such as opening a file, in a Falco rule, you typically also export process fields — assuming we haven't missed the spawned process event and the information is available. These details extend to various use cases, and, in essence, dropped events can lead to missing fields as well as race conditions.

As a result, Falco logs can never be perfect, and null values can occur. We are constantly aiming to improve the robustness in this regard. We encourage you to contribute to the project if you encounter such cases or have improvement ideas. Also be aware that, unfortunately, missing fields can have different natures. Sometimes the field may be an empty string, or the string <NA>, or, if numeric, the default numeric value. These inconsistencies may be more difficult to address, as many Falco rules rely on legacy declarations.

Furthermore, sometimes Linux may not operate exactly as expected. One concrete example is that shell built-ins like echo do not cause a new spawned process, and the echo command does not get logged with Falco. Similarly, if a base64 encoded string gets interpreted during decoding, you do not have the original base64 blob in the command args unless the command was passed with the sh -c flag. Lastly, some fields only work for certain kernel versions or system configs (e.g. proc.is_exe_upper_layer requires a container overlayfs).

Missing Container Images

Check the basics:

Is the container runtime socket correctly mounted? For Kubernetes, mount with the HOST_ROOT prefix: /host/run/k3s/containerd/containerd.sock. See deploy-kubernetes example template.
Is a custom path specified for the container runtime socket in Kubernetes? If yes, use the -o container_engines.cri.sockets[]=<socket_path> command line option when running Falco. The default paths include: /run/containerd/containerd.sock, /run/k3s/containerd/containerd.sock, /run/crio/crio.sock.
To expedite lookups, attempt to disable asynchronous CRI API calls by using the -o container_engines.cri.disable_async=true command line option when running Falco.
Falco monitors both host and container processes. If the container.id is set to host, it indicates that the process is running on the host, and therefore, no container image is associated with it.

The k8s.* fields are extracted from the container runtime socket simultaneously as we look up the container.* fields from the CRI API calls responses.

Using CRI with containerd

When using containerd as your container runtime, you should configure Falco to use the CRI engine to consume the containerd socket (/run/containerd/containerd.sock). This is important because:

The native containerd protocol does not support container names - it only provides container IDs
Containerd typically exposes two interfaces on the same socket: the native containerd protocol and the CRI (Container Runtime Interface) protocol
The CRI protocol provides richer metadata, including container names

If you are missing container.name or other container metadata fields while using containerd, ensure you are using the CRI engine configuration (not the containerd engine) in your Falco setup. For example, configure the container plugin with:

engines:
 cri:
 enabled: true
 sockets:
 - /run/containerd/containerd.sock
 containerd:
 enabled: false

Carefully read the field description documentation:

Supported Output Fields container.* retrieved from the container runtime socket
Supported Output Fields k8s.* also retrieved from the container runtime socket

The container info enrichment, while robust, depends on the speed of making API requests against the container runtime socket.

Falco's metrics config (see also Falco Metrics) provides a range of useful metrics related to software functioning, now also featuring metrics around Falco's internal state:

state_counters_enabled: true

Here is an example metrics log snippet highlighting the fields crucial for this analysis.

{
 "output_fields": {
 "evt.source": "syscall",
 "falco.n_containers": 50,
 "falco.n_missing_container_images": 0,
 },
 "rule": "Falco internal: metrics snapshot"
}

falco.n_containers indicates how many containers are running at a given time, typically less than 100-300 at maximum. falco.n_missing_container_images is an updated snapshot of how many containers are internally stored in Falco without a container image at any given time.

To complicate matters, some processes in Kubernetes run in the pod sandbox container, which has no container image in the API responses. In such cases, the container.id is the same as the k8s.pod.sandbox_id. If the container image is consistently missing throughout the lifetime of the container, it's likely a process in a pod sandbox container in the majority of the cases. However, sandbox containers likely constitute less than 1% of the distinct containers in your overall Falco logs. Note that this comparison will be fully supported by Falco 0.38 and is a work in progress.

Additionally, the improvement of the overall efficiency of the container engine, especially for the -o container_engines.cri.disable_async=true option, is also a work in progress. A more performant implementation is expected to be available by Falco 0.38. This improvement aims to address missing images observed by adopters and resolve most cases, leaving only some edge cases of race conditions where the lookup hasn't happened yet.

Missing User Names

Ensure proper mounts (e.g., /etc:/host/etc) when running Falco as a daemonset in Kubernetes, for example.
If you expect Falco to be aware of Kubernetes Control Plane users, especially when execing into a pod (kubectl exec), we must disappoint you. The Linux kernel lacks knowledge of the control plane. However, we are actively exploring ways to support this. Refer to this issue for more details.

Missing Process Tree Fields

Let's consider another example: the fields related to the process tree lineage (e.g. proc.aname*).

Falco adds processes to a cache in userspace when a new process starts and removes them when the process exits. The goal is to maintain a current view of running processes on the Linux host at any time. However, this also means that there are cases where the parent legitimately exits, re-parenting occurs, and/or PIDs get replaced or re-used.
As a result, missing processes in the process ancestry (process tree) may be due to dropped or missed events, failure to store the event, or the process exiting without proper tracking of re-parenting or orphan process cases by Falco.
Furthermore, a history of all spawned_process events is not equivalent to the current process tree on the system. Check out the Falco rules macro container_entrypoint for one such example and explore this resource.
In summary, Falco aims to closely preserve the true system state, similar to the Linux kernel itself.

Falco's metrics config (see also Falco Metrics) provides a range of useful metrics related to software functioning, now also featuring metrics around Falco's internal state:

state_counters_enabled: true

Here is an example metrics log snippet highlighting the fields crucial for this analysis.

{
 "output_fields": {
 "evt.source": "syscall",
 "falco.n_drops_full_threadtable": 0,
 "falco.n_store_evts_drops": 0,
 "falco.n_failed_fd_lookups": 0,
 "falco.n_failed_thread_lookups": 0,
 "falco.n_retrieve_evts_drops": 0
 },
 "rule": "Falco internal: metrics snapshot"
}

falco.n_drops_full_threadtable and falco.n_store_evts_drops reflect similar occurrences. They are monotonic counters indicating how often a spawned process event was dropped due to a full table (configurable by Falco 0.38 with a higher default value) and how frequently store actions to update the process structs in memory failed and were subsequently dropped. On the flip side, there are also counters keeping track of failed lookup or retrieve actions. Internally, Falco is granular and talks about threads, not processes.

References and Community Discussions

Docs: How to register a plugin

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

Plugin Registry

The registry is a GitHub repository that provides metadata and information about all plugins recognized by The Falco Project. It includes plugins hosted within this repository as well as those located in other repositories. These plugins are developed for Falco and shared with the community.

Registering your plugin

In this section, we’ll outline the key steps to get your plugin registered successfully.

To complete the registration process, you’ll need to:

Create a clear and well-structured README for your plugin.
Fill in all the required fields in the plugins section of the registry.yaml file, like in the below example.

plugins:
 source:
 - id: 2
 source: aws_cloudtrail
 name: cloudtrail
 description: Reads Cloudtrail JSON logs from files/S3 and injects as events
 authors: The Falco Authors
 contact: https://falco.org/community
 url: https://github.com/falcosecurity/plugins/tree/master/plugins/cloudtrail
 license: Apache-2.0

License

You're free to choose the open source license you want, you can check https://choosealicense.com/ for help. Most of the current plugins are under Apache License 2.0.

ID

Every source plugin requires its own unique plugin event ID to interoperate with Falco and the other plugins. This ID is used in the following ways:

It is stored inside in-memory event objects and used to identify the associated plugin that injected the event.
It is stored in capture files and used to recreate in-memory event objects when reading capture files.

It must be unique to ensure that events written by a given plugin will be properly associated with that plugin (and its event sources, see below).

Name

Each plugin in the registry must have its own name and can be different from event source, which can be shared across multiple plugins (e.g., for k8s audit logs, there might be several plugins but only one type of event source).

The name should match this regular expression ^[a-z]+[a-z0-9_]*$.

Fields

The fields are used for conditions in rules. Describe the available fields of your plugin in the README.

For example:

Name	Type	Description
`docker.status`	string	Status of the event
`docker.id`	string	ID of the event
`docker.from`	string	From of the event (deprecated)
`docker.type`	string	Type of the event
`docker.action`	string	Action of the event
`docker.stack.namespace`	string	Stack Namespace

Propose your Plugin

Once you're ready, follow these steps to submit your plugin for registration:

Fork the falcosecurity/plugins repository.
Update the registry.yaml file by adding your plugin to the plugins section.
Make sure to follow our Contributing Guide, e.g. all commits must be signed-off.
Submit a Pull Request (PR) to the falcosecurity/plugins repository.

For more details, check out the plugin registration documentation.

Docs: Try Falco on Linux

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

In this scenario, you will learn how to install Falco on an Ubuntu host, trigger a Falco rule by generating a suspicious event, and then examine the output.

This activity aims to give you a quick example of how Falco works. After you complete it, you should be able to move on to trying Falco on Kubernetes or spend some time reading some additional resources.

Prerequisites

This lab is based on installing Falco on a virtual machine.

The scenario has been tested using VirtualBox and Lima (for MacBooks running Apple Silicon).

While this tutorial may work with Ubuntu running on a cloud provider or another virtualization platform, it has not been tested.

VirtualBox setup

The following steps will set up a VirtualBox virtual machine running Ubuntu 24.04.

Install VirtualBox and Vagrant according to the instructions appropriate for your local system.
Issue the following commands from the command line to create an Ubuntu 24.04 virtual machine.

vagrant init bento/ubuntu-24.04
vagrant up

Log into the newly launched virtual machine and continue to the Install Falco section below (the default password is vagrant).

vagrant ssh

Lima setup for Apple silicon (M1/M2)

This section explains how to create an Ubuntu 24.04 VM on Apple computers running M1 silicon (as opposed to Intel).

If you are unsure what processor your Apple machine is running, you can find out by clicking the Apple icon in the upper left and choosing "About this Mac". The first item listed, Chip, tells you what silicon you're running on.

Install Homebrew according to the project's documentation.
Use Homebrew to install Lima.

brew install lima

Create an Ubuntu 24.04 VM with Lima.

limactl start --name=falco-quickstart template://ubuntu-lts

Shell into the Ubuntu VM, and once you're in the VM, continue to the Install Falco section.

limactl shell falco-quickstart

Install Falco

Regardless of which setup you used above, this section will show you how to install Falco on a host system. You'll begin by updating the package repository. Next, you'll install the dialog package. Then you'll install Falco and ensure it's up and running.

Set up the package repository

Add the Falco repository key.

curl -fsSL https://falco.org/repo/falcosecurity-packages.asc | \
sudo gpg --dearmor -o /usr/share/keyrings/falco-archive-keyring.gpg

Add the Falco repository.

sudo bash -c 'cat << EOF > /etc/apt/sources.list.d/falcosecurity.list
deb [signed-by=/usr/share/keyrings/falco-archive-keyring.gpg] https://download.falco.org/packages/deb stable main
EOF'

Read the repository contents.

sudo apt-get update -y

Install dialog

Install dialog, which is used by the Falco installer.

sudo apt-get install -y dialog

Install Falco

Install the latest Falco version.

sudo apt-get install -y falco

When prompted, choose the Modern eBPF option. This will enable the usage of the modern eBPF-based driver.
When prompted, choose Yes. Although we won't use the functionality in this exercise, this option allows Falco to update its rules automatically.

Wait for the Falco installation to complete - this should only take a few minutes.

Verify Falco is running

Make sure the Falco service is running.

sudo systemctl status falco-modern-bpf.service

The output should be similar to the following:

● falco-modern-bpf.service - Falco: Container Native Runtime Security with modern ebpf
 Loaded: loaded (/usr/lib/systemd/system/falco-modern-bpf.service; enabled; preset: enabled)
 Active: active (running) since Wed 2024-09-18 08:40:04 UTC; 11min ago
 Docs: https://falco.org/docs/
 Main PID: 4751 (falco)
 Tasks: 7 (limit: 2275)
 Memory: 24.7M (peak: 37.1M)
 CPU: 3.913s
 CGroup: /system.slice/falco-modern-bpf.service
 └─4751 /usr/bin/falco -o engine.kind=modern_ebpf

Sep 18 08:40:12 vagrant falco[4751]: /etc/falco/falco.yaml
Sep 18 08:40:12 vagrant falco[4751]: System info: Linux version 6.8.0-31-generic (buildd@lcy02-amd64-080) (x86_64-linux-gnu-gcc-13 (Ubuntu 13.2.0-23ubuntu4) 13.2.0, GNU ld (GNU Binutils for Ubuntu) 2.42) #31-Ubuntu SMP PREEMPT_DYNAMIC Sat Apr 20 00:40:06 UTC 2024
Sep 18 08:40:12 vagrant falco[4751]: Loading rules from file /etc/falco/falco_rules.yaml
Sep 18 08:40:12 vagrant falco[4751]: Loading rules from file /etc/falco/falco_rules.local.yaml
Sep 18 08:40:12 vagrant falco[4751]: The chosen syscall buffer dimension is: 8388608 bytes (8 MBs)
Sep 18 08:40:12 vagrant falco[4751]: Starting health webserver with threadiness 2, listening on 0.0.0.0:8765
Sep 18 08:40:12 vagrant falco[4751]: Loaded event sources: syscall
Sep 18 08:40:12 vagrant falco[4751]: Enabled event sources: syscall
Sep 18 08:40:12 vagrant falco[4751]: Opening 'syscall' source with modern BPF probe.
Sep 18 08:40:12 vagrant falco[4751]: One ring buffer every '2' CPUs.

See Falco in action

Generate a suspicious event

There is a Falco rule that is designed to trigger whenever someone accesses a sensitive file (of which, /etc/shadow is one). Run the following command to trigger that rule.

sudo cat /etc/shadow > /dev/null

Examine Falco's output

One of the endpoints that Falco can write output to is syslog. There are multiple ways to examine the system logs, but we have featured two for our exercise: using journalctl and simply using cat on the log file.

Using journalctl

Run the following command to retrieve Falco messages that have been generated with a priority of warning:

sudo journalctl _COMM=falco -p warning

You should see output similar to the following:

...
Sep 18 12:50:52 vagrant falco[4751]: 11:48:24.195279773: Warning Sensitive file opened for
reading by non-trusted program (file=/etc/shadow gparent=sudo ggparent=bash gggparent=sshd
evt_type=openat user=root user_uid=0 user_loginuid=1000 process=cat proc_exepath=/usr/bin/cat
parent=sudo command=cat /etc/shadow terminal=34818 container_id=host container_name=host)
...

Using /var/log/syslog

Log messages describing Falco's activity are logged to syslog. Run the following command to retrieve Falco logs:

sudo grep Sensitive /var/log/syslog

You should see output similar to the following:

...
2024-09-18T12:50:52.164570+00:00 vagrant falco: 11:48:24.195279773: Warning Sensitive file opened for
reading by non-trusted program (file=/etc/shadow gparent=sudo ggparent=bash gggparent=sshd
evt_type=openat user=root user_uid=0 user_loginuid=1000 process=cat proc_exepath=/usr/bin/cat
parent=sudo command=cat /etc/shadow terminal=34818 container_id=host container_name=host)

Cleanup

Remove the Lima virtual machine

If you wish, remove the Lima virtual machine
```
limactl delete falco-quickstart --force
```

Remove the Virtualbox virtual machine

If you wish, remove the Virtualbox virtual machine
```
vagrant destroy
```

Be sure you are in same subdirectory as the Vagrantfile

Docs: Condition Syntax

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

A Falco rule’s condition defines the filter that determines which events are detected by the rule. This condition is a boolean expression that evaluates to true or false for each event. If it evaluates to true, the rule triggers and generates an alert.

A condition can be viewed as a sequence of comparisons, each joined by logical operators. Parentheses can be used to define precedence. Each comparison uses a comparison operator between a field (on the left side), extracted from the input event, and a static or computed value (on the right side). You can also apply transformers to the field to modify its extracted values before comparison.

The set of fields available depends on the data source. For simplicity, this page focuses on syscalls, as they are among the most common.

For example, the following condition triggers for each execution of cat or grep:

evt.type = execve and (proc.name = cat or proc.name = grep)

Operators

You can use the below operators in Falco rule conditions.

Logical operators

Operators	Description
`and`	Logical AND operator to connect two or more comparisons (ie. `evt.type = open and fd.typechar='f'`).
`or`	Logical OR operator to connect two or more comparisons (ie. `proc.name = bash or proc.name = zsh`).
`not`	Logical NOT operator to negate a comparison (ie. `not proc.name = bash`).

Comparison operators

Operators	Description
`=`, `!=`	Equality and inequality operators.
`<=`, `<`, `>=`, `>`	Comparison operators for numeric values.
`contains`, `bcontains`, `icontains`	Strings are evaluated to be true if a string contains another. For flags, `contains` evaluates to true if the specified flag is set. For example: `proc.cmdline contains "-jar"`, `evt.arg.flags contains O_TRUNC`. The `icontains` variant works similarly but is case-insensitive. The `bcontains` variant allows byte matching against a raw string of bytes, taking a hexadecimal string as input. For example: `evt.buffer bcontains CAFEBABE`
`endswith`	Checks if a string ends with a given suffix.
`exists`	Checks whether a field is set. Example: `k8s.pod.name exists`.
`glob`	Evaluates standard glob patterns. Example: `fd.name glob "/home//.ssh/"`.
`in`	Evaluates whether the first set is completely contained in the second set. Example: `(b,c,d) in (a,b,c)` is `FALSE` because `d` is not found in `(a,b,c)`.
`intersects`	Evaluates whether the first set has at least one element in common with the second set. Example: `(b,c,d) intersects (a,b,c)` is `TRUE` because both sets contain `b` and `c`.
`pmatch`	Compares a file path against a set of file or directory prefixes. Example: `fd.name pmatch (/tmp/hello)` evaluates to true for `/tmp/hello`, `/tmp/hello/world` but not `/tmp/hello_world`. More details in the below section.
`regex`	Checks whether a string field matches a regular expression. The regex engine is Google RE2 configured in POSIX mode, which restricts patterns to POSIX extended (egrep) syntax (backreferences are not supported). Note that `regex` can be considerably slower than simpler string operations. The `regex` operator performs a full match only, not a partial match (i.e., anchored to both the beginning and the end). Example: `fd.name regex '[a-z]*/proc/[0-9]+/cmdline'`.
`startswith`, `bstartswith`	Checks if a string starts with a given prefix. The `bstartswith` variant allows byte matching against a raw string of bytes, taking a hexadecimal string as input. For example: `evt.buffer bstartswith 012AB3CC`.

`pmatch` operator

pmatch checks if any given path prefix matches a filesystem path in Falco fields like fd.name, evt.rawarg.path, or fs.path.name. For example:

fd.name pmatch (/var/run, /var/spool, /etc, /boot)

If fd.name is /var/spool/maillog, this expression is true; if it is /opt/data/file.txt, it is false. Internally, pmatch builds a tree-like structure from the right-hand side paths and traverses it with the left-hand side path components, returning true at the first matching leaf.

pmatch can also include glob wildcards:

fd.name pmatch (/var/*/*.txt, /etc, /boot)

This still performs a prefix match. Unlike glob, which must fully match the path, pmatch succeeds if the path starts with one of the specified prefixes. Hence, fd.name pmatch (/var/*) matches /var/run/file.txt, while fd.name glob /var/* does not. Wildcards do not cross directory separators (see glob.7).

Transformers

Falco supports basic transformations on fields within rule conditions. For instance, if you want to check for a case-insensitive process name, you can use:

tolower(proc.name) = bash

The following transform operators are supported:

Transformer	Description
`tolower(<field>)`	Converts the input field to lowercase.
`toupper(<field>)`	Converts the input field to uppercase.
`b64(<field>)`	Decodes the input field from Base64.
`basename(<field>)`	Extracts the filename without its directory path from the input field. Unlike the Unix `basename` program, `basename()` in Falco returns `""` if no filename is present. For example, `basename(proc.exepath)` is `"cat"` for `/usr/bin/cat` but `""` for `/usr/bin/`.
`len(<field>)`	Returns the length of the field: for LIST fields, the number of elements; for CHARBUF fields, the number of characters; and for BYTEBUF fields, the number of bytes.

Field evaluation (for right-hand side of comparisons)

Falco also lets you compare field values with other field values by using the val() special transformer on the right-hand side of a comparison. For instance, to detect processes that have the same name as their parent:

proc.name = val(proc.pname)

Similarly, using transformations on both sides is supported:

tolower(proc.name) = tolower(proc.pname)

Syscall event types, direction, and args

The evt.dir field, as well as the concept of "direction", have been deprecated in Falco 0.42.0 and will be removed in a future release. Until field removal and since Falco 0.42.0, specifying evt.dir='>' will match nothing, while specifying evt.dir='<' will match everything, with a warning informing the user about the deprecation. Users are encouraged to get rid of any reference to evt.dir, as its presence will result in an error at rules loading time after its removal.

Every syscall event includes the evt field class. Each condition you write for these events typically begins with an evt.type expression or macro. This is practical because security rules often focus on one syscall type at a time. For instance, you might consider open or openat to detect suspicious activity when files are opened, or execve to inspect newly spawned processes. You do not have to guess the syscall name—simply refer to the complete list of supported system call events for an overview of what you can use.

Each syscall has an entry event and an exit event, tracked by the evt.dir field, also referred to as the "direction" of the system call. A value of > indicates entry (when the syscall is invoked), while < marks exit (when the call has returned). By looking at the supported system call list, you will see that events have both entry and exit forms. For example:

> setuid(UID uid)
< setuid(ERRNO res)

In many cases, it is most useful to filter on exit events, because you want to know the outcome of the syscall once it has completed. For example, consider the file-opening events:

> open()
< open(FD fd, FSPATH name, FLAGS32 flags, UINT32 mode, UINT32 dev)
> openat()
< openat(FD fd, FD dirfd, FSRELPATH name, FLAGS32 flags, UINT32 mode, UINT32 dev)

Each event has a list of arguments that you can access through evt.arg.<argname>. For instance, if you want to detect a process opening a file to overwrite it, check if the list of flags contains O_TRUNC:

evt.type in (open, openat) and evt.dir = < and evt.arg.flags contains O_TRUNC

Note that arguments do not necessarily match the raw parameters used in the Linux kernel; Falco may parse them in ways that make rule-writing more straightforward. By using the evt fields, you can inspect many other aspects common across different events.

Syscall event context and metadata

While the evt fields allow you to write expressive conditions, arguments and common fields alone are often insufficient for complete security rules. You might also need to consider the process context in which the event occurred, whether or not it happened inside a container, or how it correlates with Kubernetes metadata. To enable this, Falco enriches many events with additional field classes. Not all field classes are available for all events, and the list grows over time. Each field class’s documentation clarifies when those fields are expected to be present, but some are so common that rules often rely on them.

The proc field class gives you context about the process and thread generating a specific syscall. This information is frequently very important. For example, you can use proc.name and proc.pid, or even traverse the process hierarchy with proc.aname[<n>] and proc.apid[<n>]. You can also see which user performed the action with the user field class.

An example rule that detects whenever bash is executed inside a container could look like this:

evt.type = execve and container.id != host and proc.name = bash

Notice that you do not need to check the execve arguments. Once execve has returned, Falco updates the process context, so all proc.* fields refer to the new process that was just spawned, including command line, executable path, arguments, and so on.

Docs: Falco Configuration Options

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

Falco's configuration file is a YAML file containing a collection of key: value or key: [value list] pairs. Depending on your installation type the configuration file could be located in /etc/falco/falco.yaml or loaded as a configmap in Kubernetes deployments.

The full list of configuration items is documented in the file itself that you can find in your Falco distribution or in the Falco repository.

Any configuration option can be overridden on the command line via the -o/--option key=value flag. For key: [value list] options, you can specify individual list items using --option key.subkey=value.

If a configuration entry (e.g. key.subkey) is a list you can override a specific entry by index, e.g.: --option key.subkey[0]=value. Since Falco 0.38.0 you can also append new elements to a list by adding --option key.subkey[]=value and/or --option key.subkey[].newitem=value.

`config_files`

Since Falco 0.38.0 you can also load additional configuration files after the main one with the config_files configuration entry, which can accept both files and directories. By default this option contains the /etc/falco/config.d directory.

Merge strategy

Since Falco 0.41.0, it is possible to specify a merge strategy for each entry provided in the config_files option. The loading of these files is assumed to happen after the main config file has been processed and then in the order they are specified. If a folder is specified, the files within that path are loaded in lexicographical order, and the merge strategy is applied for all files within that path. There are three merge strategies available, with append being the default merge strategy.

append
- Existing sequence keys will be appended
- Existing scalar keys will be overridden
- Non-existing keys will be added
override
- Existing keys will be overridden
- Non-existing keys will be added
add-only
- Existing keys will be ignored
- Non-existing keys will be added

To utilize these merge strategies in the config_files option, add the strategy alongside the path:

config_files:
 - /etc/falco/config.d
 - path: /etc/falco/config.append.d/
 strategy: append
 - path: /etc/falco/extra_config.yaml
 strategy: add-only

Important: Configuration merging occurs only at the root key level, not for nested keys. This means that if a configuration file in config.d/ contains a root-level key (e.g., engine:), the entire section from the main falco.yaml will be replaced, not merged.

For example, if you have engine-falcoctl.yaml in /etc/falco/config.d/ that sets the engine.kind option, and you try to modify engine.buf_size_preset in /etc/falco/falco.yaml, your change will be ignored because the entire engine: section is overridden by the file in config.d/.

To modify nested configuration options, you should either:

Edit the file in config.d/ that contains the root key you want to modify
Or remove/rename that file from config.d/ and make all changes directly in falco.yaml

Docs: Install on a host (tarball)

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

For other installation scenarios, such as consuming cloud events or other data sources using plugins, please refer to the Plugins section.

There are two main methods to install Falco on your host using the released Falco packages:

RPM or DEB package (includes Systemd setup): For instructions, refer to the Install on a host (DEB, RPM) page.
Tarball archive: This method is detailed on this page.

System requirements

Install

In these steps, we are targeting a Debian-like system on x86_64 architecture. You can easily extrapolate similar steps for other distros or architectures.

Download the latest binary:

curl -L -O https://download.falco.org/packages/bin/x86_64/falco-0.43.0-x86_64.tar.gz

Install Falco:

tar -xvf falco-0.43.0-x86_64.tar.gz
cp -R falco-0.43.0-x86_64/* /

Install some required dependencies that are needed to build the kernel module and the eBPF probe. If you want to use other sources like the modern eBPF probe or plugins, you can skip this step.

apt update -y
apt install -y dkms make linux-headers-$(uname -r)
# If you use falcoctl driver loader to build the eBPF probe locally you need also clang toolchain
apt install -y clang llvm

Use the falcoctl driver tool to configure Falco and install the kernel module or the eBPF probe. If you want to use other sources like the modern eBPF probe or plugins, you can skip this step.

To install the driver, write and execute permissions on the /tmp directory are required, since falcoctl will try to create and execute a script from there.

# If you want to use the kernel module, configure Falco for it
falcoctl driver config --type kmod
# If you want to use the eBPF probe, configure Falco for it
falcoctl driver config --type ebpf
# Install the chosen driver
falcoctl driver install

By default, the falcoctl driver install command tries to download a prebuilt driver from the official Falco download s3 bucket. If a driver is found, it is inserted into ${HOME}/.falco/. Otherwise, the script tries to compile the driver locally; for this reason, you need the dependencies in step [3].

You can use the environment variable FALCOCTL_DRIVER_REPOS to override the default repository URL for prebuilt drivers. The URL must not have a trailing slash, i.e., https://myhost.mydomain.com or, if the server has a subdirectory structure, https://myhost.mydomain.com/drivers. The drivers must be hosted with the following structure:

/${driver_version}/${arch}/falco_${target}_${kernelrelease}_${kernelversion}.[ko|o]

where ko and o stand for Kernel module and eBPF probe, respectively. This is an example:

/7.0.0+driver/x86_64/falco_amazonlinux2022_5.10.75-82.359.amzn2022.x86_64_1.ko

If you wish to print some debug info, you can use:

# If you want to use the kernel module, configure Falco for it
falcoctl driver printenv

Manual Systemd setup

The Falco .tar.gz archive doesn't include the Systemd setup. If you want to enable Falco to start automatically at boot time, you can still download systemd files from the Falco repo and place them in the /lib/systemd/system directory. Finally, you can follow the same instructions for enabling Systemd manually under the Install on a host (DEB, RPM) section.

Configuration

The Falco configuration file is located at /etc/falco/falco.yaml. You can edit it to customize Falco's behavior.

Since Falco 0.38.0, a new config key, config_files, allows the user to load additional configuration files to override main config entries; it allows users to keep local customization between Falco upgrades. Its default value points to a new folder, /etc/falco/config.d/, that gets installed by Falco and will be processed to look for local configuration files.

You can also override the default configuration by passing options to the falco binary. For example, to force the eBPF probe or the kernel module:

# Force eBPF probe
falco -o engine.kind=ebpf
# Force kernel module
falco -o engine.kind=kmod

Hot Reload

If this option is disabled, you can manually reload the configuration by sending a SIGHUP signal to the Falco process. To do this, use the following command:

kill -1 $(pidof falco)

Upgrade

If you are using the Kernel Module driver, please remove it with root privileges before upgrading Falco to avoid issues during the upgrade.

rmmod falco

When utilizing the eBPF probe driver, although not strictly required, you can remove the corresponding previous object files:

rm /root/.falco/*.o

With Modern eBPF, there is no requirement when updating Falco, as the driver is bundled within the Falco binary.

Once the driver is removed, ensure the falco daemon is not running, then you can follow the same steps as the Install section.

Uninstall

For the Falco binary, we don't provide specific update paths; you just have to remove files installed by the old tar.gz.

Docs: Kubernetes Audit Events

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

Falco v0.13.0 adds Kubernetes Audit Events to the list of supported event sources. This is in addition to the existing support for system call events. An improved implementation of audit events was introduced in Kubernetes v1.11 and it provides a log of requests and responses to kube-apiserver. Because almost all the cluster management tasks are performed through the API server, the audit log can effectively track the changes made to your cluster.

Examples of this include:

Creating and destroying pods, services, deployments, daemonsets, etc.
Creating, updating, and removing ConfigMaps or secrets
Subscribing to the changes introduced to any endpoint

To cover these scenarios, additional set of falco rules have been added that monitor for notable or suspicious activity, including:

Creating pods that are privileged, mount sensitive host paths, or use host networking.
Granting overly broad permissions such as cluster-admin to users.
Creating ConfigMaps with sensitive information.

Once your cluster is configured with audit logging and the events are selected to be sent to falco, you can write falco rules that can read these events and send notifications for suspicious or other notable activity.

What's New in Falco

Since Falco 0.32.0, the Kubernetes Audit Events support has been refactored to become a plugin and is compliant to the Falco Plugin System. Previously, this feature was supported as a parallel independent stream of events that was read separately from system calls, and was matched separately against its own sets of rules.

To receive Kubernetes audit events, the plugin embeds a webserver that listens on a configurable port and accepts POST requests on a configurable endpoint. The posted JSON object comprises the event. The webserver embedded inside Falco to implement endpoints such as /healthz is totally unrelated and independent from the webserver of the plugin. The webserver of the plugin can be configured as part of the plugin's init configuration and open parameters.

See configuration page for information on how plugins can be configured in Falco, and refer to the plugin's readme for more specifics.

The new plugin-based implementation has been developed to be as similar as possible to the legacy K8S Audit Events feature introduced in Falco 0.13.0. However, due to technical constraints, there are few user-facing differences. Although the most up-to-date setups should work as they used to, there are few user-facing differences to be mindful of:

K8S Audit Events support must be configured in falco.yaml through the plugins section through the plugin's init configuration and open parameters.
In the legacy implementation, the extraction of list of values was supported implicitly. When extracting a field for a rule condition or output, the check used to be able to extract single values or list of values, and use them with operators such as in, intersect, etc. However, the concept of "list" was totally implicity and there was no distinction between single values and lists of values with length equal to 1.
Now, the plugin-based implementation is compliant to the new semantics supported in the libs since Falco 0.32, which allows fields to be of explicit list type. A field of list type will always extract list of values, containing one or more entries, or fail the extraction.
Fields of list type now only support the in and intersects operators. For example, checks such as ka.req.role.rules.verbs contains create would be rejected and would need to be changed in the equivalent ka.req.role.rules.verbs intersects (create).
Failed field value extraction should now be checked with the exists operator, and not by comparing with the <NA> string.
The <NA> string literal is not returned anymore, neither in single-valued fields nor in list fields. In the legacy implementation, field existence was occasionally checked with expressions like ka.target.subresource != <NA>, which would now inherently be always false, because if the field was absent the string comparison ends up failing. Instead, prefer using the analogous ka.target.subresource exists, which explicitly checks for missing values
The /healthz endpoint of Falco cannot bind to the same port of the K8S Audit Log endpoint (e.g. /k8s-audit), due to the fact that they are now managed by two different webservers (one in Falco, one in the plugin).
In Falco versions 0.32.x (Falco v0.32.0, v0.32.1, and v0.32.2), Falco didn't allow the use of Syscalls and K8S Audit event sources on the same instance. Starting from version 0.33.0, Falco introduced the capability of consuming events from multiple event sources simultaneously within the same Falco instance.

Kubernetes Audit Rules

Rules devoted to Kubernetes audit events are given in the default k8saudit plugin rules. When installed as a daemon, falco installs this rules file to /etc/falco/, so they are available for use.

Example

One of the rules in k8s_audit_rules.yaml is as follows:

- list: k8s_audit_stages
 items: ["ResponseComplete"]

# This macro selects the set of Audit Events used by the below rules.
- macro: kevt
 condition: (jevt.value[/stage] in (k8s_audit_stages))

- macro: kmodify
 condition: (ka.verb in (create,update,patch))

- macro: configmap
 condition: ka.target.resource=configmaps

- macro: contains_private_credentials
 condition: >
 (ka.req.configmap.obj contains "aws_access_key_id" or
 ka.req.configmap.obj contains "aws-access-key-id" or
 ka.req.configmap.obj contains "aws_s3_access_key_id" or
 ka.req.configmap.obj contains "aws-s3-access-key-id" or
 ka.req.configmap.obj contains "password" or
 ka.req.configmap.obj contains "passphrase")

- rule: Configmap contains private credentials
 desc: >
 Detect configmap operations with map containing a private credential (aws key, password, etc.)
 condition: kevt and configmap and modify and contains_private_credentials
 output: K8s configmap with private credential | user=%ka.user.name verb=%ka.verb name=%ka.req.configmap.name configmap=%ka.req.configmap.name config=%ka.req.configmap.obj
 priority: WARNING
 source: k8s_audit
 tags: [k8s]

The Configmap contains private credentials rule checks for a ConfigMap created with possibly sensitive items, such as AWS keys or passwords.

Let's see how the rule works in such cases. This topic assumes that Kubernetes audit logging is configured in your environment.

Create a ConfigMap containing AWS credentials:

apiVersion: v1
data:
 ui.properties: |
 color.good=purple
 color.bad=yellow
 allow.textmode=true
 access.properties: |
 aws_access_key_id = MY-ID
 aws_secret_access_key = MY-KEY
kind: ConfigMap
metadata:
 creationTimestamp: 2016-02-18T18:52:05Z
 name: my-config
 namespace: default
 resourceVersion: "516"
 selfLink: /api/v1/namespaces/default/configmaps/my-config
 uid: b4952dc3-d670-11e5-8cd0-68f728db1985

Creating this ConfigMap results in the following json object in the audit log:

{
 "kind": "Event",
 "apiVersion": "audit.k8s.io/v1beta1",
 "metadata": {
 "creationTimestamp": "2018-10-20T00:18:28Z"
 },
 "level": "RequestResponse",
 "timestamp": "2018-10-20T00:18:28Z",
 "auditID": "33fa264e-1124-4252-af9e-2ce6e45fe07d",
 "stage": "ResponseComplete",
 "requestURI": "/api/v1/namespaces/default/configmaps",
 "verb": "create",
 "user": {
 "username": "minikube-user",
 "groups": [
 "system:masters",
 "system:authenticated"
 ]
 },
 "sourceIPs": [
 "192.168.99.1"
 ],
 "objectRef": {
 "resource": "configmaps",
 "namespace": "default",
 "name": "my-config",
 "uid": "b4952dc3-d670-11e5-8cd0-68f728db1985",
 "apiVersion": "v1"
 },
 "responseStatus": {
 "metadata": {
 },
 "code": 201
 },
 "requestObject": {
 "kind": "ConfigMap",
 "apiVersion": "v1",
 "metadata": {
 "name": "my-config",
 "namespace": "default",
 "selfLink": "/api/v1/namespaces/default/configmaps/my-config",
 "uid": "b4952dc3-d670-11e5-8cd0-68f728db1985",
 "creationTimestamp": "2016-02-18T18:52:05Z"
 },
 "data": {
 "access.properties": "aws_access_key_id = MY-ID\naws_secret_access_key = MY-KEY\n",
 "ui.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
 }
 },
 "responseObject": {
 "kind": "ConfigMap",
 "apiVersion": "v1",
 "metadata": {
 "name": "my-config",
 "namespace": "default",
 "selfLink": "/api/v1/namespaces/default/configmaps/my-config",
 "uid": "ab04e510-d3fd-11e8-8645-080027728ac4",
 "resourceVersion": "45437",
 "creationTimestamp": "2018-10-20T00:18:28Z"
 },
 "data": {
 "access.properties": "aws_access_key_id = MY-ID\naws_secret_access_key = MY-KEY\n",
 "ui.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
 }
 },
 "requestReceivedTimestamp": "2018-10-20T00:18:28.420807Z",
 "stageTimestamp": "2018-10-20T00:18:28.428398Z",
 "annotations": {
 "authorization.k8s.io/decision": "allow",
 "authorization.k8s.io/reason": ""
 }
}

When the ConfigMap contains private credentials, the rule uses the following fields in the given order:

kevt: Checks whether the stage property of the object is present in the k8s_audit_stages list.
configmap: Checks whether the value of the objectRef > resource property equals to "configmap".
kmodify: Checks whether the value of verb is one of the following: create,update,patch.
contains-private-credentials: Search the ConfigMap contents at requestObject > data for any of the sensitive strings named in the contains_private_credentials macro.

If they do, a falco alert is generated:

17:18:28.428398080: Warning K8s ConfigMap with private credential
(user=minikube-user verb=create configmap=my-config
config={"access.properties":"aws_access_key_id = MY-ID\naws_secret_access_key = MY-KEY\n",
"ui.properties":"color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"})

The output string is used to print essential information about the audit event, including:

user: %ka.user.name
verb: %ka.verb
ConfigMap name: %ka.req.configmap.name
ConfigMap contents: %ka.req.configmap.obj

Enabling Kubernetes Audit Logs

To enable Kubernetes audit logs, you need to change the arguments to the kube-apiserver process to add --audit-policy-file and --audit-webhook-config-file arguments and provide files that implement an audit policy/webhook configuration.

It is beyond the scope of Falco documentation to give a detailed description of how to do this, but this step-by-step guide will show you how to configure kubernetes audit logs on minikube and deploy Falco. Managed Kubernetes providers will usually provide a mechanism to configure the audit system.

Dynamic Audit Webhooks were removed from Kubernetes. However, static audit configuration continues to work.

Docs: Supported Events

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

Here are the system call event types and args supported by the kernel module and eBPF probes via libscap included in the Falco libs. Note that, for performance reasons, by default Falco will only consider a subset of them indicated in the table below with "yes". However, it's possible to make Falco consider all events by using the -A command line switch.

Note that several event types exist:

Syscall events correspond to Linux system calls. Most of them have parameters, documented below, while some are detected as generic and they only offer the syscall ID.
Tracepoint events represent internal kernel events that may be significant but don't directly translate to any syscall.
Metaevents are generated from supplementary data sources, for instance, during data enrichment procedures or when the need for asynchronous actions arises. This group also encompasses some of Falco's internally produced events (such as the drop event) that are unavailable for rules.
Plugin events act as an envelope for actual plugin event data. In order to write rules that use plugins use the fields documented in the individual plugin.

The events below are valid for Falco Schema Version: 4.1.0

Syscall events

Default	Dir	Name	Params
Yes	`>`	`open`	FSPATH name, FLAGS32 flags: O_LARGEFILE, O_DIRECTORY, O_DIRECT, O_TRUNC, O_SYNC, O_NONBLOCK, O_EXCL, O_DSYNC, O_APPEND, O_CREAT, O_RDWR, O_WRONLY, O_RDONLY, O_CLOEXEC, O_NONE, O_TMPFILE, O_F_CREATED, FD_UPPER_LAYER, FD_LOWER_LAYER, UINT32 mode
Yes	`<`	`open`	FD fd, FSPATH name, FLAGS32 flags: O_LARGEFILE, O_DIRECTORY, O_DIRECT, O_TRUNC, O_SYNC, O_NONBLOCK, O_EXCL, O_DSYNC, O_APPEND, O_CREAT, O_RDWR, O_WRONLY, O_RDONLY, O_CLOEXEC, O_NONE, O_TMPFILE, O_F_CREATED, FD_UPPER_LAYER, FD_LOWER_LAYER, UINT32 mode, UINT32 dev, UINT64 ino
Yes	`<`	`close`	ERRNO res, FD fd
No	`<`	`read`	ERRNO res, BYTEBUF data, FD fd, UINT32 size
No	`<`	`write`	ERRNO res, BYTEBUF data, FD fd, UINT32 size
Yes	`<`	`socket`	FD fd, ENUMFLAGS32 domain: AF_NFC, AF_ALG, AF_CAIF, AF_IEEE802154, AF_PHONET, AF_ISDN, AF_RXRPC, AF_IUCV, AF_BLUETOOTH, AF_TIPC, AF_CAN, AF_LLC, AF_WANPIPE, AF_PPPOX, AF_IRDA, AF_SNA, AF_RDS, AF_ATMSVC, AF_ECONET, AF_ASH, AF_PACKET, AF_ROUTE, AF_NETLINK, AF_KEY, AF_SECURITY, AF_NETBEUI, AF_DECnet, AF_ROSE, AF_INET6, AF_X25, AF_ATMPVC, AF_BRIDGE, AF_NETROM, AF_APPLETALK, AF_IPX, AF_AX25, AF_INET, AF_LOCAL, AF_UNIX, AF_UNSPEC, UINT32 type, UINT32 proto
Yes	`<`	`bind`	ERRNO res, SOCKADDR addr, FD fd
Yes	`>`	`connect`	FD fd, SOCKADDR addr
Yes	`<`	`connect`	ERRNO res, SOCKTUPLE tuple, FD fd, SOCKADDR addr
Yes	`<`	`listen`	ERRNO res, FD fd, INT32 backlog
No	`<`	`send`	ERRNO res, BYTEBUF data, FD fd, UINT32 size, SOCKTUPLE tuple
Yes	`<`	`sendto`	ERRNO res, BYTEBUF data, FD fd, UINT32 size, SOCKTUPLE tuple
No	`<`	`recv`	ERRNO res, BYTEBUF data, FD fd, UINT32 size, SOCKTUPLE tuple
Yes	`<`	`recvfrom`	ERRNO res, BYTEBUF data, SOCKTUPLE tuple, FD fd, UINT32 size
Yes	`<`	`shutdown`	ERRNO res, FD fd, ENUMFLAGS8 how: SHUT_UNKNOWN, SHUT_RDWR, SHUT_WR, SHUT_RD
Yes	`<`	`getsockname`
Yes	`<`	`getpeername`
Yes	`<`	`socketpair`	ERRNO res, FD fd1, FD fd2, UINT64 source, UINT64 peer, ENUMFLAGS32 domain: AF_NFC, AF_ALG, AF_CAIF, AF_IEEE802154, AF_PHONET, AF_ISDN, AF_RXRPC, AF_IUCV, AF_BLUETOOTH, AF_TIPC, AF_CAN, AF_LLC, AF_WANPIPE, AF_PPPOX, AF_IRDA, AF_SNA, AF_RDS, AF_ATMSVC, AF_ECONET, AF_ASH, AF_PACKET, AF_ROUTE, AF_NETLINK, AF_KEY, AF_SECURITY, AF_NETBEUI, AF_DECnet, AF_ROSE, AF_INET6, AF_X25, AF_ATMPVC, AF_BRIDGE, AF_NETROM, AF_APPLETALK, AF_IPX, AF_AX25, AF_INET, AF_LOCAL, AF_UNIX, AF_UNSPEC, UINT32 type, UINT32 proto
Yes	`<`	`setsockopt`	ERRNO res, FD fd, ENUMFLAGS8 level: SOL_SOCKET, SOL_TCP, UNKNOWN, ENUMFLAGS8 optname: SO_COOKIE, SO_MEMINFO, SO_PEERGROUPS, SO_ATTACH_BPF, SO_INCOMING_CPU, SO_BPF_EXTENSIONS, SO_MAX_PACING_RATE, SO_BUSY_POLL, SO_SELECT_ERR_QUEUE, SO_LOCK_FILTER, SO_NOFCS, SO_PEEK_OFF, SO_WIFI_STATUS, SO_RXQ_OVFL, SO_DOMAIN, SO_PROTOCOL, SO_TIMESTAMPING, SO_MARK, SO_TIMESTAMPNS, SO_PASSSEC, SO_PEERSEC, SO_ACCEPTCONN, SO_TIMESTAMP, SO_PEERNAME, SO_DETACH_FILTER, SO_ATTACH_FILTER, SO_BINDTODEVICE, SO_SECURITY_ENCRYPTION_NETWORK, SO_SECURITY_ENCRYPTION_TRANSPORT, SO_SECURITY_AUTHENTICATION, SO_SNDTIMEO, SO_RCVTIMEO, SO_SNDLOWAT, SO_RCVLOWAT, SO_PEERCRED, SO_PASSCRED, SO_REUSEPORT, SO_BSDCOMPAT, SO_LINGER, SO_PRIORITY, SO_NO_CHECK, SO_OOBINLINE, SO_KEEPALIVE, SO_RCVBUFFORCE, SO_SNDBUFFORCE, SO_RCVBUF, SO_SNDBUF, SO_BROADCAST, SO_DONTROUTE, SO_ERROR, SO_TYPE, SO_REUSEADDR, SO_DEBUG, UNKNOWN, DYNAMIC val, UINT32 optlen
Yes	`<`	`getsockopt`	ERRNO res, FD fd, ENUMFLAGS8 level: SOL_SOCKET, SOL_TCP, UNKNOWN, ENUMFLAGS8 optname: SO_COOKIE, SO_MEMINFO, SO_PEERGROUPS, SO_ATTACH_BPF, SO_INCOMING_CPU, SO_BPF_EXTENSIONS, SO_MAX_PACING_RATE, SO_BUSY_POLL, SO_SELECT_ERR_QUEUE, SO_LOCK_FILTER, SO_NOFCS, SO_PEEK_OFF, SO_WIFI_STATUS, SO_RXQ_OVFL, SO_DOMAIN, SO_PROTOCOL, SO_TIMESTAMPING, SO_MARK, SO_TIMESTAMPNS, SO_PASSSEC, SO_PEERSEC, SO_ACCEPTCONN, SO_TIMESTAMP, SO_PEERNAME, SO_DETACH_FILTER, SO_ATTACH_FILTER, SO_BINDTODEVICE, SO_SECURITY_ENCRYPTION_NETWORK, SO_SECURITY_ENCRYPTION_TRANSPORT, SO_SECURITY_AUTHENTICATION, SO_SNDTIMEO, SO_RCVTIMEO, SO_SNDLOWAT, SO_RCVLOWAT, SO_PEERCRED, SO_PASSCRED, SO_REUSEPORT, SO_BSDCOMPAT, SO_LINGER, SO_PRIORITY, SO_NO_CHECK, SO_OOBINLINE, SO_KEEPALIVE, SO_RCVBUFFORCE, SO_SNDBUFFORCE, SO_RCVBUF, SO_SNDBUF, SO_BROADCAST, SO_DONTROUTE, SO_ERROR, SO_TYPE, SO_REUSEADDR, SO_DEBUG, UNKNOWN, DYNAMIC val, UINT32 optlen
Yes	`<`	`sendmsg`	ERRNO res, BYTEBUF data, FD fd, UINT32 size, SOCKTUPLE tuple
Yes	`<`	`sendmmsg`	ERRNO res, FD fd, UINT32 size, BYTEBUF data, SOCKTUPLE tuple
Yes	`<`	`recvmsg`	ERRNO res, UINT32 size, BYTEBUF data, SOCKTUPLE tuple, BYTEBUF msgcontrol, FD fd
Yes	`<`	`recvmmsg`	ERRNO res, FD fd, UINT32 size, BYTEBUF data, SOCKTUPLE tuple, BYTEBUF msgcontrol
Yes	`>`	`creat`	FSPATH name, UINT32 mode
Yes	`<`	`creat`	FD fd, FSPATH name, UINT32 mode, UINT32 dev, UINT64 ino, FLAGS16 creat_flags: FD_UPPER_LAYER_CREAT, FD_LOWER_LAYER_CREAT
Yes	`<`	`pipe`	ERRNO res, FD fd1, FD fd2, UINT64 ino
Yes	`<`	`eventfd`	FD res, UINT64 initval, UINT32 flags
Yes	`<`	`futex`	ERRNO res, UINT64 addr, FLAGS16 op: FUTEX_CLOCK_REALTIME, FUTEX_PRIVATE_FLAG, FUTEX_CMP_REQUEUE_PI, FUTEX_WAIT_REQUEUE_PI, FUTEX_WAKE_BITSET, FUTEX_WAIT_BITSET, FUTEX_TRYLOCK_PI, FUTEX_UNLOCK_PI, FUTEX_LOCK_PI, FUTEX_WAKE_OP, FUTEX_CMP_REQUEUE, FUTEX_REQUEUE, FUTEX_FD, FUTEX_WAKE, FUTEX_WAIT, UINT64 val
Yes	`<`	`stat`	ERRNO res, FSPATH path
Yes	`<`	`lstat`	ERRNO res, FSPATH path
Yes	`<`	`fstat`	ERRNO res, FD fd
Yes	`<`	`stat64`	ERRNO res, FSPATH path
Yes	`<`	`lstat64`	ERRNO res, FSPATH path
Yes	`<`	`fstat64`	ERRNO res
Yes	`<`	`epoll_wait`	ERRNO res, ERRNO maxevents
Yes	`<`	`poll`	ERRNO res, FDLIST fds, INT64 timeout
Yes	`<`	`select`	ERRNO res
Yes	`<`	`lseek`	ERRNO res, FD fd, UINT64 offset, ENUMFLAGS8 whence: SEEK_END, SEEK_CUR, SEEK_SET
Yes	`<`	`llseek`	ERRNO res, FD fd, UINT64 offset, ENUMFLAGS8 whence: SEEK_END, SEEK_CUR, SEEK_SET
Yes	`<`	`getcwd`	ERRNO res, CHARBUF path
Yes	`<`	`chdir`	ERRNO res, CHARBUF path
Yes	`<`	`fchdir`	ERRNO res, FD fd
No	`<`	`pread`	ERRNO res, BYTEBUF data, FD fd, UINT32 size, UINT64 pos
No	`<`	`pwrite`	ERRNO res, BYTEBUF data, FD fd, UINT32 size, UINT64 pos
No	`<`	`readv`	ERRNO res, UINT32 size, BYTEBUF data, FD fd
No	`<`	`writev`	ERRNO res, BYTEBUF data, FD fd, UINT32 size
No	`<`	`preadv`	ERRNO res, UINT32 size, BYTEBUF data, FD fd, UINT64 pos
No	`<`	`pwritev`	ERRNO res, BYTEBUF data, FD fd, UINT32 size, UINT64 pos
Yes	`<`	`signalfd`	FD res, FD fd, UINT32 mask, UINT8 flags
Yes	`<`	`kill`	ERRNO res, PID pid, SIGTYPE sig
Yes	`<`	`tkill`	ERRNO res, PID tid, SIGTYPE sig
Yes	`<`	`tgkill`	ERRNO res, PID pid, PID tid, SIGTYPE sig
Yes	`<`	`nanosleep`	ERRNO res, RELTIME interval
Yes	`<`	`timerfd_create`	FD res, UINT8 clockid, UINT8 flags
Yes	`<`	`inotify_init`	FD res, UINT8 flags
Yes	`<`	`getrlimit`	ERRNO res, INT64 cur, INT64 max, ENUMFLAGS8 resource: RLIMIT_UNKNOWN, RLIMIT_RTTIME, RLIMIT_RTPRIO, RLIMIT_NICE, RLIMIT_MSGQUEUE, RLIMIT_SIGPENDING, RLIMIT_LOCKS, RLIMIT_AS, RLIMIT_MEMLOCK, RLIMIT_NOFILE, RLIMIT_NPROC, RLIMIT_RSS, RLIMIT_CORE, RLIMIT_STACK, RLIMIT_DATA, RLIMIT_FSIZE, RLIMIT_CPU
Yes	`<`	`setrlimit`	ERRNO res, INT64 cur, INT64 max, ENUMFLAGS8 resource: RLIMIT_UNKNOWN, RLIMIT_RTTIME, RLIMIT_RTPRIO, RLIMIT_NICE, RLIMIT_MSGQUEUE, RLIMIT_SIGPENDING, RLIMIT_LOCKS, RLIMIT_AS, RLIMIT_MEMLOCK, RLIMIT_NOFILE, RLIMIT_NPROC, RLIMIT_RSS, RLIMIT_CORE, RLIMIT_STACK, RLIMIT_DATA, RLIMIT_FSIZE, RLIMIT_CPU
Yes	`<`	`prlimit`	ERRNO res, INT64 newcur, INT64 newmax, INT64 oldcur, INT64 oldmax, INT64 pid, ENUMFLAGS8 resource: RLIMIT_UNKNOWN, RLIMIT_RTTIME, RLIMIT_RTPRIO, RLIMIT_NICE, RLIMIT_MSGQUEUE, RLIMIT_SIGPENDING, RLIMIT_LOCKS, RLIMIT_AS, RLIMIT_MEMLOCK, RLIMIT_NOFILE, RLIMIT_NPROC, RLIMIT_RSS, RLIMIT_CORE, RLIMIT_STACK, RLIMIT_DATA, RLIMIT_FSIZE, RLIMIT_CPU
Yes	`<`	`fcntl`	FD res, FD fd, ENUMFLAGS8 cmd: F_GETPIPE_SZ, F_SETPIPE_SZ, F_NOTIFY, F_DUPFD_CLOEXEC, F_CANCELLK, F_GETLEASE, F_SETLEASE, F_GETOWN_EX, F_SETOWN_EX, F_SETLKW64, F_SETLK64, F_GETLK64, F_GETSIG, F_SETSIG, F_GETOWN, F_SETOWN, F_SETLKW, F_SETLK, F_GETLK, F_SETFL, F_GETFL, F_SETFD, F_GETFD, F_DUPFD, F_OFD_GETLK, F_OFD_SETLK, F_OFD_SETLKW, UNKNOWN
Yes	`<`	`brk`	UINT64 res, UINT32 vm_size, UINT32 vm_rss, UINT32 vm_swap, UINT64 addr
Yes	`<`	`mmap`	ERRNO res, UINT32 vm_size, UINT32 vm_rss, UINT32 vm_swap, UINT64 addr, UINT64 length, FLAGS32 prot: PROT_READ, PROT_WRITE, PROT_EXEC, PROT_SEM, PROT_GROWSDOWN, PROT_GROWSUP, PROT_SAO, PROT_NONE, FLAGS32 flags: MAP_SHARED, MAP_PRIVATE, MAP_FIXED, MAP_ANONYMOUS, MAP_32BIT, MAP_RENAME, MAP_NORESERVE, MAP_POPULATE, MAP_NONBLOCK, MAP_GROWSDOWN, MAP_DENYWRITE, MAP_EXECUTABLE, MAP_INHERIT, MAP_FILE, MAP_LOCKED, FD fd, UINT64 offset
Yes	`<`	`mmap2`	ERRNO res, UINT32 vm_size, UINT32 vm_rss, UINT32 vm_swap, UINT64 addr, UINT64 length, FLAGS32 prot: PROT_READ, PROT_WRITE, PROT_EXEC, PROT_SEM, PROT_GROWSDOWN, PROT_GROWSUP, PROT_SAO, PROT_NONE, FLAGS32 flags: MAP_SHARED, MAP_PRIVATE, MAP_FIXED, MAP_ANONYMOUS, MAP_32BIT, MAP_RENAME, MAP_NORESERVE, MAP_POPULATE, MAP_NONBLOCK, MAP_GROWSDOWN, MAP_DENYWRITE, MAP_EXECUTABLE, MAP_INHERIT, MAP_FILE, MAP_LOCKED, FD fd, UINT64 pgoffset
Yes	`<`	`munmap`	ERRNO res, UINT32 vm_size, UINT32 vm_rss, UINT32 vm_swap, UINT64 addr, UINT64 length
Yes	`<`	`splice`	ERRNO res, FD fd_in, FD fd_out, UINT64 size, FLAGS32 flags: SPLICE_F_MOVE, SPLICE_F_NONBLOCK, SPLICE_F_MORE, SPLICE_F_GIFT
Yes	`<`	`ptrace`	ERRNO res, DYNAMIC addr, DYNAMIC data, ENUMFLAGS16 request: PTRACE_SINGLEBLOCK, PTRACE_SYSEMU_SINGLESTEP, PTRACE_SYSEMU, PTRACE_ARCH_PRCTL, PTRACE_SET_THREAD_AREA, PTRACE_GET_THREAD_AREA, PTRACE_OLDSETOPTIONS, PTRACE_SETFPXREGS, PTRACE_GETFPXREGS, PTRACE_SETFPREGS, PTRACE_GETFPREGS, PTRACE_SETREGS, PTRACE_GETREGS, PTRACE_SETSIGMASK, PTRACE_GETSIGMASK, PTRACE_PEEKSIGINFO, PTRACE_LISTEN, PTRACE_INTERRUPT, PTRACE_SEIZE, PTRACE_SETREGSET, PTRACE_GETREGSET, PTRACE_SETSIGINFO, PTRACE_GETSIGINFO, PTRACE_GETEVENTMSG, PTRACE_SETOPTIONS, PTRACE_SYSCALL, PTRACE_DETACH, PTRACE_ATTACH, PTRACE_SINGLESTEP, PTRACE_KILL, PTRACE_CONT, PTRACE_POKEUSR, PTRACE_POKEDATA, PTRACE_POKETEXT, PTRACE_PEEKUSR, PTRACE_PEEKDATA, PTRACE_PEEKTEXT, PTRACE_TRACEME, PTRACE_UNKNOWN, PID pid
Yes	`<`	`ioctl`	ERRNO res, FD fd, UINT64 request, UINT64 argument
Yes	`<`	`rename`	ERRNO res, FSPATH oldpath, FSPATH newpath
Yes	`<`	`renameat`	ERRNO res, FD olddirfd, FSRELPATH oldpath, FD newdirfd, FSRELPATH newpath
Yes	`<`	`symlink`	ERRNO res, CHARBUF target, FSPATH linkpath
Yes	`<`	`symlinkat`	ERRNO res, CHARBUF target, FD linkdirfd, FSRELPATH linkpath
No	`<`	`sendfile`	ERRNO res, UINT64 offset, FD out_fd, FD in_fd, UINT64 size
Yes	`<`	`quotactl`	ERRNO res, CHARBUF special, CHARBUF quotafilepath, UINT64 dqb_bhardlimit, UINT64 dqb_bsoftlimit, UINT64 dqb_curspace, UINT64 dqb_ihardlimit, UINT64 dqb_isoftlimit, RELTIME dqb_btime, RELTIME dqb_itime, RELTIME dqi_bgrace, RELTIME dqi_igrace, FLAGS8 dqi_flags: DQF_NONE, V1_DQF_RSQUASH, FLAGS8 quota_fmt_out: QFMT_NOT_USED, QFMT_VFS_OLD, QFMT_VFS_V0, QFMT_VFS_V1, FLAGS16 cmd: Q_QUOTAON, Q_QUOTAOFF, Q_GETFMT, Q_GETINFO, Q_SETINFO, Q_GETQUOTA, Q_SETQUOTA, Q_SYNC, Q_XQUOTAON, Q_XQUOTAOFF, Q_XGETQUOTA, Q_XSETQLIM, Q_XGETQSTAT, Q_XQUOTARM, Q_XQUOTASYNC, FLAGS8 type: USRQUOTA, GRPQUOTA, UINT32 id, FLAGS8 quota_fmt: QFMT_NOT_USED, QFMT_VFS_OLD, QFMT_VFS_V0, QFMT_VFS_V1
Yes	`<`	`setresuid`	ERRNO res, UID ruid, UID euid, UID suid
Yes	`<`	`setresgid`	ERRNO res, GID rgid, GID egid, GID sgid
Yes	`<`	`setuid`	ERRNO res, UID uid
Yes	`<`	`setgid`	ERRNO res, GID gid
Yes	`<`	`getuid`	UID uid
Yes	`<`	`geteuid`	UID euid
Yes	`<`	`getgid`	GID gid
Yes	`<`	`getegid`	GID egid
Yes	`<`	`getresuid`	ERRNO res, UID ruid, UID euid, UID suid
Yes	`<`	`getresgid`	ERRNO res, GID rgid, GID egid, GID sgid
Yes	`<`	`clone`	PID res, CHARBUF exe, BYTEBUF args, PID tid, PID pid, PID ptid, CHARBUF cwd, INT64 fdlimit, UINT64 pgft_maj, UINT64 pgft_min, UINT32 vm_size, UINT32 vm_rss, UINT32 vm_swap, CHARBUF comm, BYTEBUF cgroups, FLAGS32 flags: CLONE_FILES, CLONE_FS, CLONE_IO, CLONE_NEWIPC, CLONE_NEWNET, CLONE_NEWNS, CLONE_NEWPID, CLONE_NEWUTS, CLONE_PARENT, CLONE_PARENT_SETTID, CLONE_PTRACE, CLONE_SIGHAND, CLONE_SYSVSEM, CLONE_THREAD, CLONE_UNTRACED, CLONE_VM, CLONE_INVERTED, NAME_CHANGED, CLOSED, CLONE_NEWUSER, CLONE_CHILD_CLEARTID, CLONE_CHILD_SETTID, CLONE_SETTLS, CLONE_STOPPED, CLONE_VFORK, CLONE_NEWCGROUP, CLONE_CHILD_IN_PIDNS, UINT32 uid, UINT32 gid, PID vtid, PID vpid, UINT64 pidns_init_start_ts
Yes	`<`	`fork`	PID res, CHARBUF exe, BYTEBUF args, PID tid, PID pid, PID ptid, CHARBUF cwd, INT64 fdlimit, UINT64 pgft_maj, UINT64 pgft_min, UINT32 vm_size, UINT32 vm_rss, UINT32 vm_swap, CHARBUF comm, BYTEBUF cgroups, FLAGS32 flags: CLONE_FILES, CLONE_FS, CLONE_IO, CLONE_NEWIPC, CLONE_NEWNET, CLONE_NEWNS, CLONE_NEWPID, CLONE_NEWUTS, CLONE_PARENT, CLONE_PARENT_SETTID, CLONE_PTRACE, CLONE_SIGHAND, CLONE_SYSVSEM, CLONE_THREAD, CLONE_UNTRACED, CLONE_VM, CLONE_INVERTED, NAME_CHANGED, CLOSED, CLONE_NEWUSER, CLONE_CHILD_CLEARTID, CLONE_CHILD_SETTID, CLONE_SETTLS, CLONE_STOPPED, CLONE_VFORK, CLONE_NEWCGROUP, CLONE_CHILD_IN_PIDNS, UINT32 uid, UINT32 gid, PID vtid, PID vpid, UINT64 pidns_init_start_ts
Yes	`<`	`vfork`	PID res, CHARBUF exe, BYTEBUF args, PID tid, PID pid, PID ptid, CHARBUF cwd, INT64 fdlimit, UINT64 pgft_maj, UINT64 pgft_min, UINT32 vm_size, UINT32 vm_rss, UINT32 vm_swap, CHARBUF comm, BYTEBUF cgroups, FLAGS32 flags: CLONE_FILES, CLONE_FS, CLONE_IO, CLONE_NEWIPC, CLONE_NEWNET, CLONE_NEWNS, CLONE_NEWPID, CLONE_NEWUTS, CLONE_PARENT, CLONE_PARENT_SETTID, CLONE_PTRACE, CLONE_SIGHAND, CLONE_SYSVSEM, CLONE_THREAD, CLONE_UNTRACED, CLONE_VM, CLONE_INVERTED, NAME_CHANGED, CLOSED, CLONE_NEWUSER, CLONE_CHILD_CLEARTID, CLONE_CHILD_SETTID, CLONE_SETTLS, CLONE_STOPPED, CLONE_VFORK, CLONE_NEWCGROUP, CLONE_CHILD_IN_PIDNS, UINT32 uid, UINT32 gid, PID vtid, PID vpid, UINT64 pidns_init_start_ts
Yes	`<`	`getdents`	ERRNO res, FD fd
Yes	`<`	`getdents64`	ERRNO res, FD fd
Yes	`<`	`setns`	ERRNO res, FD fd, FLAGS32 nstype: CLONE_FILES, CLONE_FS, CLONE_IO, CLONE_NEWIPC, CLONE_NEWNET, CLONE_NEWNS, CLONE_NEWPID, CLONE_NEWUTS, CLONE_PARENT, CLONE_PARENT_SETTID, CLONE_PTRACE, CLONE_SIGHAND, CLONE_SYSVSEM, CLONE_THREAD, CLONE_UNTRACED, CLONE_VM, CLONE_INVERTED, NAME_CHANGED, CLOSED, CLONE_NEWUSER, CLONE_CHILD_CLEARTID, CLONE_CHILD_SETTID, CLONE_SETTLS, CLONE_STOPPED, CLONE_VFORK, CLONE_NEWCGROUP, CLONE_CHILD_IN_PIDNS
Yes	`<`	`flock`	ERRNO res, FD fd, FLAGS32 operation: LOCK_SH, LOCK_EX, LOCK_NB, LOCK_UN, LOCK_NONE
Yes	`<`	`accept`	FD fd, SOCKTUPLE tuple, UINT8 queuepct, UINT32 queuelen, UINT32 queuemax
Yes	`<`	`semop`	ERRNO res, UINT32 nsops, UINT16 sem_num_0, INT16 sem_op_0, FLAGS16 sem_flg_0: IPC_NOWAIT, SEM_UNDO, UINT16 sem_num_1, INT16 sem_op_1, FLAGS16 sem_flg_1: IPC_NOWAIT, SEM_UNDO, INT32 semid
Yes	`<`	`semctl`	ERRNO res, INT32 semid, INT32 semnum, FLAGS16 cmd: IPC_STAT, IPC_SET, IPC_RMID, IPC_INFO, SEM_INFO, SEM_STAT, GETALL, GETNCNT, GETPID, GETVAL, GETZCNT, SETALL, SETVAL, INT32 val
Yes	`<`	`ppoll`	ERRNO res, FDLIST fds, RELTIME timeout, SIGSET sigmask
Yes	`<`	`mount`	ERRNO res, CHARBUF dev, FSPATH dir, CHARBUF type, FLAGS32 flags: RDONLY, NOSUID, NODEV, NOEXEC, SYNCHRONOUS, REMOUNT, MANDLOCK, DIRSYNC, NOATIME, NODIRATIME, BIND, MOVE, REC, SILENT, POSIXACL, UNBINDABLE, PRIVATE, SLAVE, SHARED, RELATIME, KERNMOUNT, I_VERSION, STRICTATIME, LAZYTIME, NOSEC, BORN, ACTIVE, NOUSER
Yes	`<`	`semget`	ERRNO res, INT32 key, INT32 nsems, FLAGS32 semflg: IPC_EXCL, IPC_CREAT
Yes	`<`	`access`	ERRNO res, FSPATH name, FLAGS32 mode: F_OK, R_OK, W_OK, X_OK
Yes	`<`	`chroot`	ERRNO res, FSPATH path
Yes	`<`	`setsid`	PID res
Yes	`<`	`mkdir`	ERRNO res, FSPATH path, UINT32 mode
Yes	`<`	`rmdir`	ERRNO res, FSPATH path
Yes	`<`	`unshare`	ERRNO res, FLAGS32 flags: CLONE_FILES, CLONE_FS, CLONE_IO, CLONE_NEWIPC, CLONE_NEWNET, CLONE_NEWNS, CLONE_NEWPID, CLONE_NEWUTS, CLONE_PARENT, CLONE_PARENT_SETTID, CLONE_PTRACE, CLONE_SIGHAND, CLONE_SYSVSEM, CLONE_THREAD, CLONE_UNTRACED, CLONE_VM, CLONE_INVERTED, NAME_CHANGED, CLOSED, CLONE_NEWUSER, CLONE_CHILD_CLEARTID, CLONE_CHILD_SETTID, CLONE_SETTLS, CLONE_STOPPED, CLONE_VFORK, CLONE_NEWCGROUP, CLONE_CHILD_IN_PIDNS
Yes	`<`	`execve`	ERRNO res, CHARBUF exe, BYTEBUF args, PID tid, PID pid, PID ptid, CHARBUF cwd, UINT64 fdlimit, UINT64 pgft_maj, UINT64 pgft_min, UINT32 vm_size, UINT32 vm_rss, UINT32 vm_swap, CHARBUF comm, BYTEBUF cgroups, BYTEBUF env, UINT32 tty, PID vpgid, UID loginuid, FLAGS32 flags: EXE_WRITABLE, EXE_UPPER_LAYER, EXE_FROM_MEMFD, EXE_LOWER_LAYER, UINT64 cap_inheritable, UINT64 cap_permitted, UINT64 cap_effective, UINT64 exe_ino, ABSTIME exe_ino_ctime, ABSTIME exe_ino_mtime, UID uid, FSPATH trusted_exepath, PID pgid, GID gid, FSPATH filename
Yes	`<`	`setpgid`	ERRNO res, PID pid, PID pgid
Yes	`<`	`seccomp`	ERRNO res, UINT64 op, UINT64 flags
Yes	`<`	`unlink`	ERRNO res, FSPATH path
Yes	`<`	`unlinkat`	ERRNO res, FD dirfd, FSRELPATH name, FLAGS32 flags: AT_REMOVEDIR
Yes	`<`	`mkdirat`	ERRNO res, FD dirfd, FSRELPATH path, UINT32 mode
Yes	`>`	`openat`	FD dirfd, FSRELPATH name, FLAGS32 flags: O_LARGEFILE, O_DIRECTORY, O_DIRECT, O_TRUNC, O_SYNC, O_NONBLOCK, O_EXCL, O_DSYNC, O_APPEND, O_CREAT, O_RDWR, O_WRONLY, O_RDONLY, O_CLOEXEC, O_NONE, O_TMPFILE, O_F_CREATED, FD_UPPER_LAYER, FD_LOWER_LAYER, UINT32 mode
Yes	`<`	`openat`	FD fd, FD dirfd, FSRELPATH name, FLAGS32 flags: O_LARGEFILE, O_DIRECTORY, O_DIRECT, O_TRUNC, O_SYNC, O_NONBLOCK, O_EXCL, O_DSYNC, O_APPEND, O_CREAT, O_RDWR, O_WRONLY, O_RDONLY, O_CLOEXEC, O_NONE, O_TMPFILE, O_F_CREATED, FD_UPPER_LAYER, FD_LOWER_LAYER, UINT32 mode, UINT32 dev, UINT64 ino
Yes	`<`	`link`	ERRNO res, FSPATH oldpath, FSPATH newpath
Yes	`<`	`linkat`	ERRNO res, FD olddir, FSRELPATH oldpath, FD newdir, FSRELPATH newpath, FLAGS32 flags: AT_SYMLINK_FOLLOW, AT_EMPTY_PATH
Yes	`<`	`fchmodat`	ERRNO res, FD dirfd, FSRELPATH filename, MODE mode
Yes	`<`	`chmod`	ERRNO res, FSPATH filename, MODE mode
Yes	`<`	`fchmod`	ERRNO res, FD fd, MODE mode
Yes	`<`	`renameat2`	ERRNO res, FD olddirfd, FSRELPATH oldpath, FD newdirfd, FSRELPATH newpath, FLAGS32 flags: RENAME_NOREPLACE, RENAME_EXCHANGE, RENAME_WHITEOUT
Yes	`<`	`userfaultfd`	ERRNO res, FLAGS32 flags: O_LARGEFILE, O_DIRECTORY, O_DIRECT, O_TRUNC, O_SYNC, O_NONBLOCK, O_EXCL, O_DSYNC, O_APPEND, O_CREAT, O_RDWR, O_WRONLY, O_RDONLY, O_CLOEXEC, O_NONE, O_TMPFILE, O_F_CREATED, FD_UPPER_LAYER, FD_LOWER_LAYER
Yes	`>`	`openat2`	FD dirfd, FSRELPATH name, FLAGS32 flags: O_LARGEFILE, O_DIRECTORY, O_DIRECT, O_TRUNC, O_SYNC, O_NONBLOCK, O_EXCL, O_DSYNC, O_APPEND, O_CREAT, O_RDWR, O_WRONLY, O_RDONLY, O_CLOEXEC, O_NONE, O_TMPFILE, O_F_CREATED, FD_UPPER_LAYER, FD_LOWER_LAYER, UINT32 mode, FLAGS32 resolve: RESOLVE_BENEATH, RESOLVE_IN_ROOT, RESOLVE_NO_MAGICLINKS, RESOLVE_NO_SYMLINKS, RESOLVE_NO_XDEV, RESOLVE_CACHED
Yes	`<`	`openat2`	FD fd, FD dirfd, FSRELPATH name, FLAGS32 flags: O_LARGEFILE, O_DIRECTORY, O_DIRECT, O_TRUNC, O_SYNC, O_NONBLOCK, O_EXCL, O_DSYNC, O_APPEND, O_CREAT, O_RDWR, O_WRONLY, O_RDONLY, O_CLOEXEC, O_NONE, O_TMPFILE, O_F_CREATED, FD_UPPER_LAYER, FD_LOWER_LAYER, UINT32 mode, FLAGS32 resolve: RESOLVE_BENEATH, RESOLVE_IN_ROOT, RESOLVE_NO_MAGICLINKS, RESOLVE_NO_SYMLINKS, RESOLVE_NO_XDEV, RESOLVE_CACHED, UINT32 dev, UINT64 ino
Yes	`<`	`mprotect`	ERRNO res, UINT64 addr, UINT64 length, FLAGS32 prot: PROT_READ, PROT_WRITE, PROT_EXEC, PROT_SEM, PROT_GROWSDOWN, PROT_GROWSUP, PROT_SAO, PROT_NONE
Yes	`<`	`execveat`	ERRNO res, CHARBUF exe, BYTEBUF args, PID tid, PID pid, PID ptid, CHARBUF cwd, UINT64 fdlimit, UINT64 pgft_maj, UINT64 pgft_min, UINT32 vm_size, UINT32 vm_rss, UINT32 vm_swap, CHARBUF comm, BYTEBUF cgroups, BYTEBUF env, UINT32 tty, PID vpgid, UID loginuid, FLAGS32 flags: EXE_WRITABLE, EXE_UPPER_LAYER, EXE_FROM_MEMFD, EXE_LOWER_LAYER, UINT64 cap_inheritable, UINT64 cap_permitted, UINT64 cap_effective, UINT64 exe_ino, ABSTIME exe_ino_ctime, ABSTIME exe_ino_mtime, UID uid, FSPATH trusted_exepath, PID pgid, GID gid
Yes	`<`	`copy_file_range`	ERRNO res, FD fdout, UINT64 offout, FD fdin, UINT64 offin, UINT64 len
Yes	`<`	`clone3`	PID res, CHARBUF exe, BYTEBUF args, PID tid, PID pid, PID ptid, CHARBUF cwd, INT64 fdlimit, UINT64 pgft_maj, UINT64 pgft_min, UINT32 vm_size, UINT32 vm_rss, UINT32 vm_swap, CHARBUF comm, BYTEBUF cgroups, FLAGS32 flags: CLONE_FILES, CLONE_FS, CLONE_IO, CLONE_NEWIPC, CLONE_NEWNET, CLONE_NEWNS, CLONE_NEWPID, CLONE_NEWUTS, CLONE_PARENT, CLONE_PARENT_SETTID, CLONE_PTRACE, CLONE_SIGHAND, CLONE_SYSVSEM, CLONE_THREAD, CLONE_UNTRACED, CLONE_VM, CLONE_INVERTED, NAME_CHANGED, CLOSED, CLONE_NEWUSER, CLONE_CHILD_CLEARTID, CLONE_CHILD_SETTID, CLONE_SETTLS, CLONE_STOPPED, CLONE_VFORK, CLONE_NEWCGROUP, CLONE_CHILD_IN_PIDNS, UINT32 uid, UINT32 gid, PID vtid, PID vpid, UINT64 pidns_init_start_ts
Yes	`<`	`open_by_handle_at`	FD fd, FD mountfd, FLAGS32 flags: O_LARGEFILE, O_DIRECTORY, O_DIRECT, O_TRUNC, O_SYNC, O_NONBLOCK, O_EXCL, O_DSYNC, O_APPEND, O_CREAT, O_RDWR, O_WRONLY, O_RDONLY, O_CLOEXEC, O_NONE, O_TMPFILE, O_F_CREATED, FD_UPPER_LAYER, FD_LOWER_LAYER, FSPATH path, UINT32 dev, UINT64 ino
Yes	`<`	`io_uring_setup`	ERRNO res, UINT32 entries, UINT32 sq_entries, UINT32 cq_entries, FLAGS32 flags: IORING_SETUP_IOPOLL, IORING_SETUP_SQPOLL, IORING_SQ_NEED_WAKEUP, IORING_SETUP_SQ_AFF, IORING_SETUP_CQSIZE, IORING_SETUP_CLAMP, IORING_SETUP_ATTACH_RW, IORING_SETUP_R_DISABLED, UINT32 sq_thread_cpu, UINT32 sq_thread_idle, FLAGS32 features: IORING_FEAT_SINGLE_MMAP, IORING_FEAT_NODROP, IORING_FEAT_SUBMIT_STABLE, IORING_FEAT_RW_CUR_POS, IORING_FEAT_CUR_PERSONALITY, IORING_FEAT_FAST_POLL, IORING_FEAT_POLL_32BITS, IORING_FEAT_SQPOLL_NONFIXED, IORING_FEAT_ENTER_EXT_ARG, IORING_FEAT_NATIVE_WORKERS, IORING_FEAT_RSRC_TAGS
Yes	`<`	`io_uring_enter`	ERRNO res, FD fd, UINT32 to_submit, UINT32 min_complete, FLAGS32 flags: IORING_ENTER_GETEVENTS, IORING_ENTER_SQ_WAKEUP, IORING_ENTER_SQ_WAIT, IORING_ENTER_EXT_ARG, SIGSET sig
Yes	`<`	`io_uring_register`	ERRNO res, FD fd, ENUMFLAGS16 opcode: IORING_REGISTER_BUFFERS, IORING_UNREGISTER_BUFFERS, IORING_REGISTER_FILES, IORING_UNREGISTER_FILES, IORING_REGISTER_EVENTFD, IORING_UNREGISTER_EVENTFD, IORING_REGISTER_FILES_UPDATE, IORING_REGISTER_EVENTFD_ASYNC, IORING_REGISTER_PROBE, IORING_REGISTER_PERSONALITY, IORING_UNREGISTER_PERSONALITY, IORING_REGISTER_RESTRICTIONS, IORING_REGISTER_ENABLE_RINGS, IORING_REGISTER_FILES2, IORING_REGISTER_FILES_UPDATE2, IORING_REGISTER_BUFFERS2, IORING_REGISTER_BUFFERS_UPDATE, IORING_REGISTER_IOWQ_AFF, IORING_UNREGISTER_IOWQ_AFF, IORING_REGISTER_IOWQ_MAX_WORKERS, IORING_REGISTER_RING_FDS, IORING_UNREGISTER_RING_FDS, UINT64 arg, UINT32 nr_args
Yes	`<`	`mlock`	ERRNO res, UINT64 addr, UINT64 len
Yes	`<`	`munlock`	ERRNO res, UINT64 addr, UINT64 len
Yes	`<`	`mlockall`	ERRNO res, FLAGS32 flags: MCL_CURRENT, MCL_FUTURE, MCL_ONFAULT
Yes	`<`	`munlockall`	ERRNO res
Yes	`<`	`capset`	ERRNO res, UINT64 cap_inheritable, UINT64 cap_permitted, UINT64 cap_effective
Yes	`<`	`dup2`	FD res, FD oldfd, FD newfd
Yes	`<`	`dup3`	FD res, FD oldfd, FD newfd, FLAGS32 flags: O_LARGEFILE, O_DIRECTORY, O_DIRECT, O_TRUNC, O_SYNC, O_NONBLOCK, O_EXCL, O_DSYNC, O_APPEND, O_CREAT, O_RDWR, O_WRONLY, O_RDONLY, O_CLOEXEC, O_NONE, O_TMPFILE, O_F_CREATED, FD_UPPER_LAYER, FD_LOWER_LAYER
Yes	`<`	`dup`	FD res, FD oldfd
Yes	`<`	`bpf`	FD fd, ENUMFLAGS32 cmd: BPF_MAP_CREATE, BPF_MAP_LOOKUP_ELEM, BPF_MAP_UPDATE_ELEM, BPF_MAP_DELETE_ELEM, BPF_MAP_GET_NEXT_KEY, BPF_PROG_LOAD, BPF_OBJ_PIN, BPF_OBJ_GET, BPF_PROG_ATTACH, BPF_PROG_DETACH, BPF_PROG_TEST_RUN, BPF_PROG_RUN, BPF_PROG_GET_NEXT_ID, BPF_MAP_GET_NEXT_ID, BPF_PROG_GET_FD_BY_ID, BPF_MAP_GET_FD_BY_ID, BPF_OBJ_GET_INFO_BY_FD, BPF_PROG_QUERY, BPF_RAW_TRACEPOINT_OPEN, BPF_BTF_LOAD, BPF_BTF_GET_FD_BY_ID, BPF_TASK_FD_QUERY, BPF_MAP_LOOKUP_AND_DELETE_ELEM, BPF_MAP_FREEZE, BPF_BTF_GET_NEXT_ID, BPF_MAP_LOOKUP_BATCH, BPF_MAP_LOOKUP_AND_DELETE_BATCH, BPF_MAP_UPDATE_BATCH, BPF_MAP_DELETE_BATCH, BPF_LINK_CREATE, BPF_LINK_UPDATE, BPF_LINK_GET_FD_BY_ID, BPF_LINK_GET_NEXT_ID, BPF_ENABLE_STATS, BPF_ITER_CREATE, BPF_LINK_DETACH, BPF_PROG_BIND_MAP
Yes	`<`	`mlock2`	ERRNO res, UINT64 addr, UINT64 len, FLAGS32 flags: MLOCK_ONFAULT
Yes	`<`	`fsconfig`	ERRNO res, FD fd, ENUMFLAGS32 cmd: FSCONFIG_SET_FLAG, FSCONFIG_SET_STRING, FSCONFIG_SET_BINARY, FSCONFIG_SET_PATH, FSCONFIG_SET_PATH_EMPTY, FSCONFIG_SET_FD, FSCONFIG_CMD_CREATE, FSCONFIG_CMD_RECONFIGURE, CHARBUF key, BYTEBUF value_bytebuf, CHARBUF value_charbuf, INT32 aux
Yes	`<`	`epoll_create`	ERRNO res, INT32 size
Yes	`<`	`epoll_create1`	ERRNO res, FLAGS32 flags: EPOLL_CLOEXEC
Yes	`<`	`chown`	ERRNO res, FSPATH path, UINT32 uid, UINT32 gid
Yes	`<`	`lchown`	ERRNO res, FSPATH path, UINT32 uid, UINT32 gid
Yes	`<`	`fchown`	ERRNO res, FD fd, UINT32 uid, UINT32 gid
Yes	`<`	`fchownat`	ERRNO res, FD dirfd, FSRELPATH pathname, UINT32 uid, UINT32 gid, FLAGS32 flags: AT_SYMLINK_NOFOLLOW, AT_EMPTY_PATH
Yes	`<`	`umount`	ERRNO res, FSPATH name
Yes	`<`	`accept4`	FD fd, SOCKTUPLE tuple, UINT8 queuepct, UINT32 queuelen, UINT32 queuemax, INT32 flags
Yes	`<`	`umount2`	ERRNO res, FSPATH name, FLAGS32 flags: FORCE, DETACH, EXPIRE, NOFOLLOW
Yes	`<`	`pipe2`	ERRNO res, FD fd1, FD fd2, UINT64 ino, FLAGS32 flags: O_LARGEFILE, O_DIRECTORY, O_DIRECT, O_TRUNC, O_SYNC, O_NONBLOCK, O_EXCL, O_DSYNC, O_APPEND, O_CREAT, O_RDWR, O_WRONLY, O_RDONLY, O_CLOEXEC, O_NONE, O_TMPFILE, O_F_CREATED, FD_UPPER_LAYER, FD_LOWER_LAYER
Yes	`<`	`inotify_init1`	FD res, FLAGS16 flags: O_LARGEFILE, O_DIRECTORY, O_DIRECT, O_TRUNC, O_SYNC, O_NONBLOCK, O_EXCL, O_DSYNC, O_APPEND, O_CREAT, O_RDWR, O_WRONLY, O_RDONLY, O_CLOEXEC, O_NONE, O_TMPFILE, O_F_CREATED, FD_UPPER_LAYER, FD_LOWER_LAYER
Yes	`<`	`eventfd2`	FD res, FLAGS16 flags: O_LARGEFILE, O_DIRECTORY, O_DIRECT, O_TRUNC, O_SYNC, O_NONBLOCK, O_EXCL, O_DSYNC, O_APPEND, O_CREAT, O_RDWR, O_WRONLY, O_RDONLY, O_CLOEXEC, O_NONE, O_TMPFILE, O_F_CREATED, FD_UPPER_LAYER, FD_LOWER_LAYER, UINT64 initval
Yes	`<`	`signalfd4`	FD res, FLAGS16 flags: O_LARGEFILE, O_DIRECTORY, O_DIRECT, O_TRUNC, O_SYNC, O_NONBLOCK, O_EXCL, O_DSYNC, O_APPEND, O_CREAT, O_RDWR, O_WRONLY, O_RDONLY, O_CLOEXEC, O_NONE, O_TMPFILE, O_F_CREATED, FD_UPPER_LAYER, FD_LOWER_LAYER, FD fd, UINT32 mask
Yes	`<`	`prctl`	ERRNO res, ENUMFLAGS32 option: PR_GET_DUMPABLE, PR_SET_DUMPABLE, PR_GET_KEEPCAPS, PR_SET_KEEPCAPS, PR_SET_NAME, PR_GET_NAME, PR_GET_SECCOMP, PR_SET_SECCOMP, PR_CAPBSET_READ, PR_CAPBSET_DROP, PR_GET_SECUREBITS, PR_SET_SECUREBITS, PR_MCE_KILL, PR_MCE_KILL, PR_SET_MM, PR_SET_CHILD_SUBREAPER, PR_GET_CHILD_SUBREAPER, PR_SET_NO_NEW_PRIVS, PR_GET_NO_NEW_PRIVS, PR_GET_TID_ADDRESS, PR_SET_THP_DISABLE, PR_GET_THP_DISABLE, PR_CAP_AMBIENT, CHARBUF arg2_str, INT64 arg2_int
Yes	`<`	`memfd_create`	FD fd, CHARBUF name, FLAGS32 flags: MFD_CLOEXEC, MFD_ALLOW_SEALING, MFD_HUGETLB
Yes	`<`	`pidfd_getfd`	FD fd, FD pid_fd, FD target_fd, UINT32 flags
Yes	`<`	`pidfd_open`	FD fd, PID pid, FLAGS32 flags: PIDFD_NONBLOCK
Yes	`<`	`init_module`	ERRNO res, BYTEBUF img, UINT64 length, CHARBUF uargs
Yes	`<`	`finit_module`	ERRNO res, FD fd, CHARBUF uargs, FLAGS32 flags: MODULE_INIT_IGNORE_MODVERSIONS, MODULE_INIT_IGNORE_VERMAGIC, MODULE_INIT_COMPRESSED_FILE
Yes	`<`	`mknod`	ERRNO res, FSPATH path, MODE mode, UINT32 dev
Yes	`<`	`mknodat`	ERRNO res, FD dirfd, FSRELPATH path, MODE mode, UINT32 dev
Yes	`<`	`newfstatat`	ERRNO res, FD dirfd, FSRELPATH path, FLAGS32 flags: AT_EMPTY_PATH, AT_NO_AUTOMOUNT, AT_SYMLINK_NOFOLLOW
Yes	`<`	`process_vm_readv`	INT64 res, PID pid, BYTEBUF data
Yes	`<`	`process_vm_writev`	INT64 res, PID pid, BYTEBUF data
Yes	`<`	`delete_module`	ERRNO res, CHARBUF name, FLAGS32 flags: O_NONBLOCK, O_TRUNC
Yes	`<`	`setreuid`	ERRNO res, UID ruid, UID euid
Yes	`<`	`setregid`	ERRNO res, UID rgid, UID egid
Yes	`>`	`adjtimex`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`adjtimex`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`exit`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`exit`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sethostname`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sethostname`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`getsid`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`getsid`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fstatfs`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fstatfs`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`pivot_root`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`pivot_root`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`oldstat`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`oldstat`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`umask`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`umask`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`madvise`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`madvise`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`statfs64`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`statfs64`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`iopl`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`iopl`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`swapon`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`swapon`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`utime`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`utime`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`getpid`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`getpid`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`setdomainname`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`setdomainname`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`semtimedop`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`semtimedop`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`mq_notify`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`mq_notify`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`nfsservctl`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`nfsservctl`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`pkey_mprotect`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`pkey_mprotect`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fgetxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fgetxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sysinfo`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sysinfo`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`uselib`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`uselib`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`olduname`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`olduname`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`set_mempolicy`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`set_mempolicy`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`getppid`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`getppid`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sched_yield`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sched_yield`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`getrusage`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`getrusage`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sigsuspend`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sigsuspend`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`riscv_hwprobe`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`riscv_hwprobe`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`bdflush`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`bdflush`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`get_kernel_syms`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`get_kernel_syms`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`pause`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`pause`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`getpmsg`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`getpmsg`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`clock_gettime`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`clock_gettime`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`mq_getsetattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`mq_getsetattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`spu_run`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`spu_run`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`personality`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`personality`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`request_key`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`request_key`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`readlink`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`readlink`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`times`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`times`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`reboot`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`reboot`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`syslog`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`syslog`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`ipc`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`ipc`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`create_module`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`create_module`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`listxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`listxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`setxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`setxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`setpriority`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`setpriority`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sigreturn`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sigreturn`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`setgroups`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`setgroups`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`preadv2`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`preadv2`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`setitimer`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`setitimer`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`shmat`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`shmat`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`getitimer`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`getitimer`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`removexattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`removexattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`msgget`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`msgget`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`spu_create`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`spu_create`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`capget`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`capget`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`rt_sigsuspend`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`rt_sigsuspend`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`mseal`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`mseal`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fanotify_init`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fanotify_init`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`readdir`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`readdir`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`getxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`getxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`mq_timedreceive`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`mq_timedreceive`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`nice`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`nice`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fsopen`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fsopen`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`rt_sigpending`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`rt_sigpending`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sysfs`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sysfs`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`acct`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`acct`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`setfsgid`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`setfsgid`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sync`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sync`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`clock_adjtime`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`clock_adjtime`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`io_getevents`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`io_getevents`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`query_module`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`query_module`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`remap_file_pages`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`remap_file_pages`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`rt_sigprocmask`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`rt_sigprocmask`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`mincore`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`mincore`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`getpgid`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`getpgid`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`msgsnd`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`msgsnd`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sched_getparam`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sched_getparam`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`getgroups`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`getgroups`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`ustat`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`ustat`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`uname`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`uname`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`epoll_ctl`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`epoll_ctl`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`lgetxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`lgetxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`_sysctl`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`_sysctl`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`rt_sigtimedwait`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`rt_sigtimedwait`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`flistxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`flistxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`pkey_alloc`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`pkey_alloc`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`time`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`time`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`kcmp`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`kcmp`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`epoll_pwait`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`epoll_pwait`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`oldlstat`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`oldlstat`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sched_setscheduler`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sched_setscheduler`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`statfs`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`statfs`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fdatasync`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fdatasync`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`set_robust_list`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`set_robust_list`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`swapoff`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`swapoff`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`quotactl_fd`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`quotactl_fd`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`exit_group`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`exit_group`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`listmount`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`listmount`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`timerfd_settime`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`timerfd_settime`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sched_getscheduler`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sched_getscheduler`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sched_get_priority_min`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sched_get_priority_min`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`ftruncate`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`ftruncate`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`pkey_free`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`pkey_free`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sched_rr_get_interval`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sched_rr_get_interval`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`open_tree`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`open_tree`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`idle`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`idle`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`mremap`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`mremap`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`rt_sigaction`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`rt_sigaction`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`stime`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`stime`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sched_getattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sched_getattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`rt_sigqueueinfo`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`rt_sigqueueinfo`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sync_file_range`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sync_file_range`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`mq_unlink`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`mq_unlink`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`alarm`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`alarm`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`inotify_rm_watch`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`inotify_rm_watch`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`lsetxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`lsetxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`timer_delete`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`timer_delete`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`msync`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`msync`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`timer_settime`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`timer_settime`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sigprocmask`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sigprocmask`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`lremovexattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`lremovexattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fremovexattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fremovexattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sched_setaffinity`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sched_setaffinity`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fsetxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fsetxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`settimeofday`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`settimeofday`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`gettimeofday`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`gettimeofday`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`io_setup`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`io_setup`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`llistxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`llistxattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fsync`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fsync`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`pidfd_send_signal`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`pidfd_send_signal`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`getrandom`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`getrandom`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`s390_sthyi`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`s390_sthyi`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`io_destroy`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`io_destroy`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sigaltstack`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sigaltstack`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`riscv_flush_icache`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`riscv_flush_icache`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`mount_setattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`mount_setattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`getpgrp`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`getpgrp`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`vhangup`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`vhangup`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`set_tid_address`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`set_tid_address`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`timer_create`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`timer_create`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`timer_gettime`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`timer_gettime`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`timer_getoverrun`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`timer_getoverrun`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`clock_settime`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`clock_settime`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`clock_getres`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`clock_getres`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`utimes`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`utimes`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`vm86`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`vm86`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`lsm_set_self_attr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`lsm_set_self_attr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`clock_nanosleep`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`clock_nanosleep`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`futimesat`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`futimesat`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`signal`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`signal`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`mq_open`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`mq_open`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`keyctl`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`keyctl`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`ioprio_set`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`ioprio_set`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`landlock_add_rule`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`landlock_add_rule`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`add_key`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`add_key`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`set_thread_area`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`set_thread_area`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`ioprio_get`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`ioprio_get`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sync_file_range2`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sync_file_range2`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`ioperm`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`ioperm`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sigaction`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sigaction`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`inotify_add_watch`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`inotify_add_watch`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fallocate`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fallocate`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`get_thread_area`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`get_thread_area`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`readlinkat`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`readlinkat`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`name_to_handle_at`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`name_to_handle_at`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`perf_event_open`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`perf_event_open`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`kexec_load`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`kexec_load`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`truncate`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`truncate`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`faccessat`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`faccessat`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`mq_timedsend`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`mq_timedsend`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`restart_syscall`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`restart_syscall`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`map_shadow_stack`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`map_shadow_stack`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`pselect6`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`pselect6`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`epoll_ctl_old`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`epoll_ctl_old`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`get_robust_list`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`get_robust_list`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`tee`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`tee`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`vmsplice`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`vmsplice`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`getcpu`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`getcpu`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`utimensat`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`utimensat`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`rseq`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`rseq`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`timerfd_gettime`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`timerfd_gettime`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`syncfs`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`syncfs`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`msgctl`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`msgctl`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`io_submit`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`io_submit`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`oldolduname`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`oldolduname`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`shmdt`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`shmdt`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sched_getaffinity`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sched_getaffinity`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fstatat64`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fstatat64`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`socketcall`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`socketcall`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`waitid`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`waitid`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sgetmask`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sgetmask`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`io_cancel`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`io_cancel`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sched_setparam`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sched_setparam`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`cachestat`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`cachestat`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sched_setattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sched_setattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`ssetmask`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`ssetmask`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`_newselect`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`_newselect`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`setfsuid`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`setfsuid`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sigpending`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sigpending`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`wait4`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`wait4`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`process_mrelease`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`process_mrelease`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`waitpid`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`waitpid`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`arch_prctl`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`arch_prctl`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`rt_sigreturn`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`rt_sigreturn`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fadvise64`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fadvise64`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`msgrcv`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`msgrcv`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`move_mount`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`move_mount`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`lookup_dcookie`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`lookup_dcookie`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fspick`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fspick`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`shmget`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`shmget`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fsmount`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fsmount`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`epoll_pwait2`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`epoll_pwait2`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`move_pages`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`move_pages`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`shmctl`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`shmctl`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`memfd_secret`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`memfd_secret`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`landlock_restrict_self`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`landlock_restrict_self`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sched_get_priority_max`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sched_get_priority_max`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`sys_debug_setcontext`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`sys_debug_setcontext`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`kexec_file_load`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`kexec_file_load`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`process_madvise`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`process_madvise`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`landlock_create_ruleset`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`landlock_create_ruleset`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`rt_tgsigqueueinfo`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`rt_tgsigqueueinfo`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`migrate_pages`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`migrate_pages`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fstatfs64`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fstatfs64`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`pwritev2`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`pwritev2`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`mbind`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`mbind`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`modify_ldt`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`modify_ldt`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`gettid`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`gettid`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`statx`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`statx`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`getpriority`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`getpriority`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`io_pgetevents`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`io_pgetevents`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`listxattrat`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`listxattrat`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`set_mempolicy_home_node`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`set_mempolicy_home_node`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`readahead`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`readahead`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`futex_waitv`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`futex_waitv`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`epoll_wait_old`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`epoll_wait_old`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`faccessat2`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`faccessat2`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`get_mempolicy`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`get_mempolicy`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`membarrier`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`membarrier`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`pciconfig_iobase`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`pciconfig_iobase`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`close_range`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`close_range`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fanotify_mark`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fanotify_mark`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`open_tree_attr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`open_tree_attr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`timerfd`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`timerfd`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`s390_pci_mmio_read`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`s390_pci_mmio_read`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`s390_pci_mmio_write`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`s390_pci_mmio_write`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`s390_runtime_instr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`s390_runtime_instr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`s390_guarded_storage`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`s390_guarded_storage`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`fchmodat2`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`fchmodat2`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`futex_wake`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`futex_wake`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`futex_requeue`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`futex_requeue`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`futex_wait`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`futex_wait`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`switch_endian`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`switch_endian`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`multiplexer`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`multiplexer`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`oldfstat`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`oldfstat`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`lsm_get_self_attr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`lsm_get_self_attr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`swapcontext`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`swapcontext`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`pciconfig_write`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`pciconfig_write`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`rtas`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`rtas`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`pciconfig_read`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`pciconfig_read`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`subpage_prot`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`subpage_prot`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`statmount`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`statmount`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`lsm_list_modules`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`lsm_list_modules`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`uretprobe`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`uretprobe`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`removexattrat`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`removexattrat`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`getxattrat`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`getxattrat`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`setxattrat`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`setxattrat`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`file_getattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`file_getattr`	SYSCALLID ID, UINT16 nativeID
Yes	`>`	`file_setattr`	SYSCALLID ID, UINT16 nativeID
Yes	`<`	`file_setattr`	SYSCALLID ID, UINT16 nativeID

Tracepoint events

Default	Dir	Name	Params
Yes	`>`	`switch`	PID next, UINT64 pgft_maj, UINT64 pgft_min, UINT32 vm_size, UINT32 vm_rss, UINT32 vm_swap
Yes	`>`	`procexit`	ERRNO status, ERRNO ret, SIGTYPE sig, UINT8 core, PID reaper_tid
Yes	`>`	`signaldeliver`	PID spid, PID dpid, SIGTYPE sig
Yes	`>`	`page_fault`	UINT64 addr, UINT64 ip, FLAGS32 error: PROTECTION_VIOLATION, PAGE_NOT_PRESENT, WRITE_ACCESS, READ_ACCESS, USER_FAULT, SUPERVISOR_FAULT, RESERVED_PAGE, INSTRUCTION_FETCH

Plugin events

Default	Dir	Name	Params
Yes	`>`	`pluginevent`	UINT32 plugin_id, BYTEBUF event_data

Metaevents

Default	Dir	Name	Params
Yes	`>`	`drop`	UINT32 ratio
Yes	`<`	`drop`	UINT32 ratio
Yes	`>`	`scapevent`	UINT32 event_type, UINT64 event_data
Yes	`>`	`procinfo`	UINT64 cpu_usr, UINT64 cpu_sys
Yes	`>`	`cpu_hotplug`	UINT32 cpu, UINT32 action
Yes	`>`	`notification`	CHARBUF id, CHARBUF desc
Yes	`>`	`infra`	CHARBUF source, CHARBUF name, CHARBUF description, CHARBUF scope
Yes	`>`	`container`	CHARBUF json
Yes	`>`	`useradded`	UINT32 uid, UINT32 gid, CHARBUF name, CHARBUF home, CHARBUF shell, CHARBUF container_id
Yes	`>`	`userdeleted`	UINT32 uid, UINT32 gid, CHARBUF name, CHARBUF home, CHARBUF shell, CHARBUF container_id
Yes	`>`	`groupadded`	UINT32 gid, CHARBUF name, CHARBUF container_id
Yes	`>`	`groupdeleted`	UINT32 gid, CHARBUF name, CHARBUF container_id
Yes	`>`	`asyncevent`	UINT32 plugin_id, CHARBUF name, BYTEBUF data

Docs: Contributor of the Month

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

Hundreds of developers around the world contribute to Falco open source projects. Our Hall of Fame honors the best of the best.

Falco Contributor of the Month

The title of “Contributor of the Month” is awarded to an outstanding contributor for the month of the year.

Month of the Year	Contributor of the Month
November, 2020	Thomas Labarussias
December, 2020	Massimiliano Giovagnoli, and Jonah Jones
January, 2021	Carlos Panato, KeisukeYamashita, and Rajakavitha Kodhandapani
February, 2021	Scott Nichols
March, 2021	Frank Jogeleit
April, 2021	Batuhan Apaydın and Yuvraj
May, 2021	Batuhan Apaydın and Yuvraj
June, 2021	Ismail Yenigul
July, 2021	Furkan Türkal
August, 2021	Teryl Taylor and Frederico Araujo
September and October, 2021	Leo Di Donato
November and December, 2021	Pablo Lopez Zaldivar
January and February, 2022	Alban Créquy
January 2023	Logan Bond
February 2023	Melissa Kilby and David Windsor

Docs: Go Client

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

The client-go Go library provides:

type and service mappings for the Falco gRPC API. For more information, see output schema.
Client and Config structs that simplify the connection to the gRPC server. For more information, see documentation.

Refer to the fully-functional example to see how the Go client connects to the Falco gRPC Outputs API and displays the events in JSON.

Additional examples for various APIs are located in the examples directory of the client-go repository.

Ensure that you have the certificates in the example's path at /etc/falco/certs/{client.crt,client.key,ca.crt}.

In the client-go root directory, run:

$ go run examples/output/main.go | jq

The output events start flowing in depending on the set of rules in the Falco instance.

{
 "time": {
 "seconds": 1570094449,
 "nanos": 259268899
 },
 "priority": 3,
 "rule": "Modify binary dirs",
 "output": "09:20:49.259268899: Error File below known binary directory renamed/removed (user=vagrant command=lua /home/vagrant/.dotfiles/zsh/.config/zsh/plugins/z.lua/z.lua --init zsh once enhanced pcmdline=zsh operation=rena
me file=<NA> res=0 oldpath=/usr/bin/realpath newpath=/usr/bin/realpath container_id=host image=<NA>)",
 "output_fields": {
 "container.id": "host",
 "container.image.repository": "<NA>",
 "evt.args": "res=0 oldpath=/usr/bin/realpath newpath=/usr/bin/realpath ",
 "evt.time": "09:20:49.259268899",
 "evt.type": "rename",
 "fd.name": "<NA>",
 "proc.cmdline": "lua /home/vagrant/.dotfiles/zsh/.config/zsh/plugins/z.lua/z.lua --init zsh once enhanced",
 "proc.pcmdline": "zsh",
 "user.name": "vagrant"
 }
}
{
 "time": {
 "seconds": 1570094449,
 "nanos": 620298462
 },
 "priority": 4,
 "rule": "Delete or rename shell history",
 "output": "09:20:49.620298462: Warning Shell history had been deleted or renamed (user=vagrant type=unlink command=zsh fd.name=<NA> name=<NA> path=/home/vagrant/.zsh_history.LOCK oldpath=<NA> host (id=host))",
 "output_fields": {
 "container.id": "host",
 "container.name": "host",
 "evt.arg.name": "<NA>",
 "evt.arg.oldpath": "<NA>",
 "evt.arg.path": "/home/vagrant/.zsh_history.LOCK",
 "evt.time": "09:20:49.620298462",
 "evt.type": "unlink",
 "fd.name": "<NA>",
 "proc.cmdline": "zsh",
 "user.name": "vagrant"
 }
}

Docs: Okta Events

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

The Falco Okta plugin can read Okta logs and emit events for each Okta log entry.

Falco also distributes out-of-the-box rules that can be used to identify interesting/suspicious/notable events in Okta logs, including:

Creating a new OKTA user account
Detecting a locked-out user
Assigning admin permissions to an okta user

Configuration

See the README for information on configuring the plugin. This simply involves providing the organization/api token as part of init params. These can be added to falco.yaml under the plugins configuration key key.

The plugin does not use any open params configuration.

Sample Output

For example, when using a dummy rule as follows:

- rule: Dummy
desc: Dummy
condition: okta.app!=""
output: "evt=%okta.evt.type user=%okta.actor.name ip=%okta.client.ip app=%okta.app"
priority: DEBUG
source: okta
tags: [okta]

The dummy rule will emit an alert for each Okta log entry, like the following:

19:12:25.439350000: Debug evt=user.authentication.sso user=User1 ip=x.x.x.x app=google
19:12:30.675628000: Debug evt=user.authentication.sso user=User2 ip=x.x.x.x app=github
19:12:35.918456000: Debug evt=user.authentication.sso user=User3 ip=x.x.x.x app=office365

Docs: Overriding Rules

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

Overview

There may be cases where you need to adjust the behavior of the Falco-supplied list, macro, and rule.

You can override (modify) rules in Falco two different ways:

Define multiple rules files. The additional rules files can be used to add new lists, macros and rules or to override existing ones.
You can override lists, macros, and rules in the same file so long as the override happens after the initial definition.

Note that when overriding existing lists, macro, or rule the order of the rule configuration files matters. For example if you append to an existing default rule, you must ensure your custom rules file (e.g. /etc/falco/rules.d/custom-rules.yaml) is loaded after the default rules file (/etc/falco/falco_rules.yaml).

The load order can be configured from the command line using multiple -r parameters in the right order, directly inside the Falco configuration file (falco.yaml) via the rules_files section or through the official Helm chart, using the falco.rules_files value.

To facilitate modifying existing lists, macros and rules Falco provides an override section that can be added to your custom rules file. Within the override section you can specify whether you want to append or replace information for the given rule, list or macro.

append allows you to add additional values to a list, macro, or rule key

replace allows you to replace the value of a list, macro or macro key

append and replace cannot be used together. Trying to apply both will result in an error.

The keys that can be overridden vary by rules component and action being taken:

Lists (append or replace): items
Macros (append or replace): condition
Rules (append): condition, output, desc, tags, exceptions
Rules (replace): condition, output desc, priority, tags, exceptions, enabled, warn_evttypes, skip-if-unknown-filter

Examples of using the `override` section

The following examples illustrate how you can use the override section to modify existing lists, macros, and rules.

In all the examples below, it's assumed one is running Falco via falco -r /etc/falco/falco_rules.yaml -r /etc/falco/falco_rules.local.yaml, or has the default entries for rules_files in falco.yaml, which has /etc/falco/falco.yaml first and /etc/falco/falco_rules.local.yaml second.

Append an item to a list

`/etc/falco/falco_rules.yaml`

- list: my_programs
 items: [ls, cat, pwd]

- rule: my_programs_opened_file
 desc: Track whenever a set of programs opens a file
 condition: proc.name in (my_programs) and (evt.type=open or evt.type=openat)
 output: A tracked program opened a file | user=%user.name command=%proc.cmdline file=%fd.name
 priority: INFO

`/etc/falco/falco_rules.local.yaml`

- list: my_programs
 items: [cp]
 override:
 items: append

The rule my_programs_opened_file would trigger whenever any of ls, cat, pwd, or cp opened a file.

Replace items in a list

`/etc/falco/falco_rules.yaml`

- list: my_programs
 items: [ls, cat, pwd]

- rule: my_programs_opened_file
 desc: Track whenever a set of programs opens a file
 condition: proc.name in (my_programs) and (evt.type=open or evt.type=openat)
 output: A tracked program opened a file | user=%user.name command=%proc.cmdline file=%fd.name
 priority: INFO

`/etc/falco/falco_rules.local.yaml`

- list: my_programs
 items: [vi, vim, nano] 
 override:
 items: replace

The rule my_programs_opened_file would trigger whenever any of vi, vim, or nano opened a file.

Append an item to a macro

`/etc/falco/falco_rules.yaml`

- macro: access_file
 condition: evt.type=open

- rule: program_accesses_file
 desc: Track whenever a set of programs opens a file
 condition: (access_file) and proc.name in (cat, ls)
 output: A tracked program opened a file | user=%user.name command=%proc.cmdline file=%fd.name
 priority: INFO

`/etc/falco/falco_rules.local.yaml`

- macro: access_file
 condition: or evt.type=openat
 override:
 condition: append

The rule program_accesses_file would trigger when ls/cat either used open/openat on a file.

Append and replace items in a rule

`/etc/falco/falco_rules.yaml`

- rule: program_accesses_file
 desc: Yrack whenever a set of programs opens a file
 condition: evt.type=open and proc.name in (cat, ls) 
 output: A tracked program opened a file | user=%user.name command=%proc.cmdline file=%fd.name
 priority: INFO

`/etc/falco/falco_rules.local.yaml`

- rule: program_accesses_file
 condition: and not user.name=root
 output: A file (user=%user.name command=%proc.cmdline file=%fd.name) was opened by a monitored program
 override:
 condition: append
 output: replace

The rule program_accesses_file would trigger when ls/cat either used open on a file, but not if the user was root.

The new output message would be A file (user=%user.name command=%proc.cmdline file=%fd.name) was opened by a monitored program

Enabling a disabled rule

Using enabled: true is deprecated, and should be avoided. Falco 0.37.0 and later will display a warning if enabled: true is used.

`/etc/falco/falco_rules.yaml`

- rule: test_rule
 desc: test rule description
 condition: evt.type = close
 output: user=%user.name command=%proc.cmdline file=%fd.name
 priority: INFO
 enabled: false

`/etc/falco/falco_rules.local.yaml` (incorrect usage example)

- rule: test_rule
 enabled: true

Use the new override section to enable the rule instead.

`/etc/falco/falco_rules.yaml`

- rule: test_rule
 desc: test rule description
 condition: evt.type = close
 output: user=%user.name command=%proc.cmdline file=%fd.name
 priority: INFO
 enabled: false

`/etc/falco/falco_rules.local.yaml` (correct usage example)

- rule: test_rule
 enabled: true
 override:
 enabled: replace

Precedence of logical operators when appending

Remember that when appending rules and macros, the content of the referring rule or macro is simply added to the condition of the referred one. This can result in unintended results if the original rule/macro has potentially ambiguous logical operators.

Here's an example:

- rule: my_rule
 desc: ...
 condition: evt.type=open and proc.name=apache
 output: ...

- rule: my_rule
 append: true
 condition: or proc.name=nginx

Should proc.name=nginx be interpreted as relative to the and proc.name=apache, that is to allow either apache/nginx to open files, or relative to the evt.type=open, that is to allow apache to open files or to allow nginx to do anything?

In cases like this, be sure to scope the logical operators of the original condition with parentheses when possible, or avoid appending conditions when not possible.

Appending to existing rules using `append` key (deprecated)

The append key has been deprecated and will be removed in Falco 1.0.0. Use the override section instead.

If you use multiple Falco rules files, you might want to append new items to an existing lists, macros or rules. To do that, define an item with the same name as an existing item and add an append: true attribute to the YAML object.

When appending to lists, items are automatically added to the end of the list.
When appending to rules or macros, the additional content is appended to the field of the referred object.

Note that when appending to lists, rules or macros, the order of the rule configuration files matters! For example if you append to an existing default rule (e.g. Terminal shell in container), you must ensure your custom configuration file (e.g. /etc/falco/rules.d/custom-rules.yaml) is loaded after the default configuration file (/etc/falco/falco_rules.yaml).

This can be configured with multiple -r parameters in the right order, directly inside the Falco configuration file (falco.yaml) via rules_files or if you use the official Helm chart, via the falco.rules_files value.

Redefining existing rules using `append` key (deprecated)

The append key has been deprecated and will be removed in Falco 1.0.0. Use the override section instead.

If append is set to false (default value), the whole object will be redefined. This can be used to empty a list, apply user-specific settings to a macro or even change a rule completely.

Take into account that when redefining a rule, it will entirely replace the previous rule, so if the new object defines fewer fields than required, Falco could return an error.

The only exceptions to this are the enabled field, that when defined as a single accompanying field, it simply enables or disables a previously-defined rule. And obviously, the append field, that when set to true for either macros or rules, it just appends the condition/exceptions field.

Examples of appending using `append` key (deprecated)

The append key has been deprecated and will be removed in Falco 1.0.0. Use the override section instead.

Appending to Lists

Here's an example of appending to lists:

`/etc/falco/falco_rules.yaml`

- list: my_programs
 items: [ls, cat, pwd]

- rule: my_programs_opened_file
 desc: Track whenever a set of programs opens a file
 condition: proc.name in (my_programs) and (evt.type=open or evt.type=openat)
 output: A tracked program opened a file | user=%user.name command=%proc.cmdline file=%fd.name
 priority: INFO

`/etc/falco/falco_rules.local.yaml`

- list: my_programs
 append: true
 items: [cp]

The rule my_programs_opened_file would trigger whenever any of ls, cat, pwd, or cp opened a file.

Appending to Macros

Here's an example of appending to macros:

`/etc/falco/falco_rules.yaml`

- macro: access_file
 condition: evt.type=open

- rule: program_accesses_file
 desc: Track whenever a set of programs opens a file
 condition: proc.name in (cat, ls) and (access_file)
 output: A tracked program opened a file | user=%user.name command=%proc.cmdline file=%fd.name
 priority: INFO

`/etc/falco/falco_rules.local.yaml`

- macro: access_file
 append: true
 condition: or evt.type=openat

The rule program_accesses_file would trigger when ls/cat either used open/openat on a file.

Appending to Rules

Here's an example of appending to rules:

`/etc/falco/falco_rules.yaml`

- rule: program_accesses_file
 desc: track whenever a set of programs opens a file
 condition: proc.name in (cat, ls) and evt.type=open
 output: A tracked program opened a file | user=%user.name command=%proc.cmdline file=%fd.name
 priority: INFO

`/etc/falco/falco_rules.local.yaml`

- rule: program_accesses_file
 append: true
 condition: and not user.name=root

The rule program_accesses_file would trigger when ls/cat either used open on a file, but not if the user was root.

Append Exceptions to Rules

It is also possible to append exceptions to rules.
Here you can find further information.

Docs: Registered Plugins

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

You can find below the officially registered plugins, more details on https://github.com/falcosecurity/plugins.

ID	Plugin	Type	Source	Description	Authors	URL	Rules URL	Licence
1	k8saudit	sourcing	k8s_audit	Read Kubernetes Audit Events and monitor Kubernetes Clusters	The Falco Authors	🔗	🔗	Apache-2.0
2	cloudtrail	sourcing	aws_cloudtrail	Reads Cloudtrail JSON logs from files/S3 and injects as events	The Falco Authors	🔗	🔗	Apache-2.0
-	json	extraction		Extract values from any JSON payload	The Falco Authors	🔗		Apache-2.0
3	dummy	sourcing	dummy	Reference plugin used to document interface	The Falco Authors	🔗		Apache-2.0
4	dummy_c	sourcing	dummy_c	Like dummy, but written in C++	The Falco Authors	🔗		Apache-2.0
5	docker	sourcing	docker	Docker Events	Thomas Labarussias	🔗	🔗	Apache-2.0
6	seccompagent	sourcing	seccompagent	Seccomp Agent Events	Alban Crequy	🔗		Apache-2.0
7	okta	sourcing	okta	Okta Log Events	The Falco Authors	🔗	🔗	Apache-2.0
8	github	sourcing	github	Github Webhook Events	The Falco Authors	🔗	🔗	Apache-2.0
9	k8saudit-eks	sourcing	k8s_audit	Read Kubernetes Audit Events from AWS EKS Clusters	The Falco Authors	🔗	🔗	Apache-2.0
10	nomad	sourcing	nomad	Read Hashicorp Nomad Events Stream	Alberto Llamas	🔗	🔗	Apache-2.0
11	dnscollector	sourcing	dnscollector	DNS Collector Events	Daniel Moloney	🔗	🔗	Apache-2.0
12	gcpaudit	sourcing	gcp_auditlog	Read GCP Audit Logs	The Falco Authors	🔗	🔗	Apache-2.0
13	syslogsrv	sourcing	syslogsrv	Syslog Server Events	Maksim Nabokikh	🔗	🔗	Apache-2.0
14	salesforce	sourcing	salesforce	Falco plugin providing basic runtime threat detection and auditing logging for Salesforce	Andy	🔗	🔗	Apache-2.0
15	box	sourcing	box	Falco plugin providing basic runtime threat detection and auditing logging for Box	Andy	🔗	🔗	Apache-2.0
-	k8smeta	extraction		Enriche Falco syscall flow with Kubernetes Metadata	The Falco Authors	🔗		Apache-2.0
16	k8saudit-gke	sourcing	k8s_audit	Read Kubernetes Audit Events from GKE Clusters	The Falco Authors	🔗	🔗	Apache-2.0
17	journald	sourcing	journal	Read Journald events into Falco	Grzegorz Nosek	🔗		Apache-2.0
18	kafka	sourcing	kafka	Read events from Kafka topics into Falco	Hunter Madison	🔗	🔗	Apache-2.0
19	gitlab	sourcing	gitlab	Falco plugin providing basic runtime threat detection and auditing logging for GitLab	Andy	🔗	🔗	Apache-2.0
20	keycloak	sourcing	keycloak	Falco plugin for sourcing and extracting Keycloak user/admin events	Mattia Forcellese	🔗	🔗	Apache-2.0
21	k8saudit-aks	sourcing	k8s_audit	Read Kubernetes Audit Events from Azure AKS Clusters	The Falco Authors	🔗	🔗	Apache-2.0
22	k8saudit-ovh	sourcing	k8s_audit	Read Kubernetes Audit Events from OVHcloud MKS Clusters	Aurélie Vache	🔗	🔗	Apache-2.0
23	dummy_rs	sourcing	dummy_rs	Like dummy, but written in Rust	The Falco Authors	🔗		Apache-2.0
-	container	extraction		Enriche Falco syscall flow with Container Metadata	The Falco Authors	🔗		Apache-2.0
-	krsi	extraction		Security (KRSI) events support for Falco	The Falco Authors	🔗		Apache-2.0
24	collector	sourcing	collector	Generic collector to ingest raw payloads into Falco	The Falco Authors	🔗		Apache-2.0
25	awselb	sourcing	awselb	AWS Elastic Load Balancer access logs events	Yuki Nakamura	🔗	🔗	Apache-2.0
26	edera	sourcing	edera_zone	A Falco plugin for forwarding libscap events out of Edera zones.	Edera	🔗	🔗	Apache-2.0
27	nginx	sourcing	nginx	Real-time nginx access log monitoring for security threats. Detects SQL injection, XSS, path traversal, command injection, brute force attacks, and OWASP Top 10 vulnerabilities.	takaosgb3	🔗	🔗	Apache-2.0
28	coding_agent	sourcing	coding_agent	Runtime detection for AI coding agents with Falco (part of the Prempti project). Intercepts tool calls (shell commands, file operations, web fetches, MCP calls) before they run and produces allow/deny/ask verdicts via customizable Falco rules, with a full audit trail of agent activity.	The Falco Authors	🔗	🔗	Apache-2.0

Docs: Actions For Dropped System Call Events

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

Introduction

With the enhancements introduced in v0.15.0, Falco can now intelligently detect dropped system call events and take remedial actions, such as alerting or even exiting Falco entirely. When system call events are dropped, Falco might encounter problems building its internal view of the processes, files, containers, and orchestrator metadata in use, which in turn might affect the rules that depend on that metadata. The explicit signals that Falco now provides make it easier to detect dropped system calls.

For more information on this feature, see our blog post on CVE-2019-8339.

Implementation

Every second, Falco reads system call event counts that are populated by the kernel module/eBPF program. The reading includes the number of system calls processed, and most importantly, the number of times the kernel tried to write system call information to the shared buffer between the kernel and user space, but found the buffer was full. These failed write attempts are considered dropped system call events.

When at least one dropped event is detected, Falco takes one of the following actions:

ignore: no action is taken. If an empty list is provided, ignore is assumed.
log: log a CRITICAL message noting that the buffer was full.
alert: emit a Falco alert stating that the buffer was full.
exit: exit Falco with a non-zero rc.

Given below are a sample log message, an alert, and an exit message:

Wed Mar 27 15:28:22 2019: Falco initialized with configuration file /etc/falco/falco.yaml
Wed Mar 27 15:28:22 2019: Loading rules from file /etc/falco/falco_rules.yaml:
Wed Mar 27 15:28:24 2019: Falco internal: syscall event drop. 1 system calls dropped in last second.
15:28:24.000207862: Critical Falco internal: syscall event drop. 1 system calls dropped in last second.(n_drops=1 n_evts=1181)
Wed Mar 27 15:28:24 2019: Falco internal: syscall event drop. 1 system calls dropped in last second.
Wed Mar 27 15:28:24 2019: Exiting.

Actions Rate Throttling

To reduce the likelihood of a flood of log messages/alerts, Falco provides an alert throttling mechanism disabled by default. This feature can be enabled through the Falco configuration (see the outputs entry).

Before v0.33.0 this feature was enabled by default.

Configuration

The actions to take on a dropped system call event and the throttling parameters for the token bucket are configurable in the file falco.yaml. You can find them in syscall_event_drops.

Docs: Supported Fields for Conditions and Outputs

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

Here are the fields supported by Falco. These fields can be used in the condition key of a Falco rule and well as the output key. Any fields included in the output key of a rule will also be included in the alert's output_fields object when json_output is set to true.

You can also see this set of fields via falco --list=<source>, with <source> being one of the Falco event sources.

System Calls (source `syscall`)

syscall event source fields are provided by the Falco Drivers. See the supported events documentation to learn about all the available event types. The field evt.arg, evt.args and evt.rawarg is used to access arguments for each event. For example, in order to access the target arg of a symlinkat exit event you can use evt.arg.target.

# System Kernel Fields
$ falco --list=syscall

Field Class: evt

These fields can be used for all event types

Name	Type	Description
`evt.num`	UINT64	event number.
`evt.time`	CHARBUF	event timestamp as a time string that includes the nanosecond part.
`evt.time.s`	CHARBUF	event timestamp as a time string with no nanoseconds.
`evt.time.iso8601`	CHARBUF	event timestamp in ISO 8601 format, including nanoseconds and time zone offset (in UTC).
`evt.datetime`	CHARBUF	event timestamp as a time string that includes the date.
`evt.datetime.s`	CHARBUF	event timestamp as a datetime string with no nanoseconds.
`evt.rawtime`	ABSTIME	absolute event timestamp, i.e. nanoseconds from epoch.
`evt.rawtime.s`	ABSTIME	integer part of the event timestamp (e.g. seconds since epoch).
`evt.rawtime.ns`	ABSTIME	fractional part of the absolute event timestamp.
`evt.reltime`	RELTIME	number of nanoseconds from the beginning of the capture.
`evt.reltime.s`	RELTIME	number of seconds from the beginning of the capture.
`evt.reltime.ns`	RELTIME	fractional part (in ns) of the time from the beginning of the capture.
`evt.pluginname`	CHARBUF	if the event comes from a plugin-defined event source, the name of the plugin that generated it. The plugin must be currently loaded.
`evt.plugininfo`	CHARBUF	if the event comes from a plugin-defined event source, a summary of the event as formatted by the plugin. The plugin must be currently loaded.
`evt.source`	CHARBUF	the name of the source that produced the event.
`evt.is_async`	BOOL	'true' for asynchronous events, 'false' otherwise.
`evt.asynctype`	CHARBUF	If the event is asynchronous, the type of the event (e.g. 'container').
`evt.hostname`	CHARBUF	The hostname of the underlying host can be customized by setting an environment variable (e.g. FALCO_HOSTNAME for the Falco agent). This is valuable in Kubernetes setups, where the hostname can match the pod name particularly in DaemonSet deployments. To achieve this, assign Kubernetes' spec.nodeName to the environment variable. Notably, spec.nodeName generally includes the cluster name.

Field Class: evt (for system calls)

Event fields applicable to syscall events. Note that for most events you can access the individual arguments/parameters of each syscall via evt.arg, e.g. evt.arg.filename.

Name	Type	Description
`evt.deltatime`	RELTIME	delta between this event and the previous event, in nanoseconds.
`evt.deltatime.s`	RELTIME	integer part of the delta between this event and the previous event.
`evt.deltatime.ns`	RELTIME	fractional part of the delta between this event and the previous event.
`evt.type`	CHARBUF	The name of the event (e.g. 'open').
`evt.type.is`	UINT32	allows one to specify an event type, and returns 1 for events that are of that type. For example, evt.type.is.open returns 1 for open events, 0 for any other event.
`syscall.type`	CHARBUF	For system call events, the name of the system call (e.g. 'open'). Unset for other events (e.g. switch or internal events). Use this field instead of evt.type if you need to make sure that the filtered/printed value is actually a system call.
`evt.category`	CHARBUF	The event category. Example values are 'file' (for file operations like open and close), 'net' (for network operations like socket and bind), memory (for things like brk or mmap), and so on.
`evt.cpu`	INT16	number of the CPU where this event happened.
`evt.args`	CHARBUF	all the event arguments, aggregated into a single string.
`evt.arg`	CHARBUF	one of the event arguments specified by name or by number. Some events (e.g. return codes or FDs) will be converted into a text representation when possible. E.g. 'evt.arg.fd' or 'evt.arg[0]'.
`evt.rawarg`	DYNAMIC	one of the event arguments specified by name. E.g. 'evt.rawarg.fd'.
`evt.info`	CHARBUF	Currently, this field returns the same value as 'evt.args'.
`evt.buffer`	BYTEBUF	the binary data buffer for events that have one, like read(), recvfrom(), etc. Use this field in filters with 'contains' to search into I/O data buffers.
`evt.buflen`	UINT64	the length of the binary data buffer for events that have one, like read(), recvfrom(), etc.
`evt.res`	CHARBUF	event return value, as a string. If the event failed, the result is an error code string (e.g. 'ENOENT'), otherwise the result is the string 'SUCCESS'.
`evt.rawres`	INT64	event return value, as a number (e.g. -2). Useful for range comparisons.
`evt.failed`	BOOL	'true' for events that returned an error status.
`evt.is_io`	BOOL	'true' for events that read or write to FDs, like read(), send, recvfrom(), etc.
`evt.is_io_read`	BOOL	'true' for events that read from FDs, like read(), recv(), recvfrom(), etc.
`evt.is_io_write`	BOOL	'true' for events that write to FDs, like write(), send(), etc.
`evt.io_dir`	CHARBUF	'r' for events that read from FDs, like read(); 'w' for events that write to FDs, like write().
`evt.is_wait`	BOOL	'true' for events that make the thread wait, e.g. sleep(), select(), poll().
`evt.is_syslog`	BOOL	'true' for events that are writes to /dev/log.
`evt.count`	UINT32	This filter field always returns 1.
`evt.count.error`	UINT32	This filter field returns 1 for events that returned with an error.
`evt.count.error.file`	UINT32	This filter field returns 1 for events that returned with an error and are related to file I/O.
`evt.count.error.net`	UINT32	This filter field returns 1 for events that returned with an error and are related to network I/O.
`evt.count.error.memory`	UINT32	This filter field returns 1 for events that returned with an error and are related to memory allocation.
`evt.count.error.other`	UINT32	This filter field returns 1 for events that returned with an error and are related to none of the previous categories.
`evt.count.exit`	UINT32	This filter field returns 1 for exit events.
`evt.around`	UINT64	Accepts the event if it's around the specified time interval. The syntax is evt.around[T]=D, where T is the value returned by %evt.rawtime for the event and D is a delta in milliseconds. For example, evt.around[1404996934793590564]=1000 will return the events with timestamp with one second before the timestamp and one second after it, for a total of two seconds of capture.
`evt.abspath`	CHARBUF	Absolute path calculated from dirfd and name during syscalls like renameat and symlinkat. Use 'evt.abspath.src' or 'evt.abspath.dst' for syscalls that support multiple paths.
`evt.is_open_read`	BOOL	'true' for open/openat/openat2/open_by_handle_at events where the path was opened for reading
`evt.is_open_write`	BOOL	'true' for open/openat/openat2/open_by_handle_at events where the path was opened for writing
`evt.is_open_exec`	BOOL	'true' for open/openat/openat2/open_by_handle_at or creat events where a file is created with execute permissions
`evt.is_open_create`	BOOL	'true' for for open/openat/openat2/open_by_handle_at events where a file is created.

Field Class: process

Additional information about the process and thread executing the syscall event.

Name	Type	Description
`proc.exe`	CHARBUF	The first command-line argument (i.e., argv[0]), typically the executable name or a custom string as specified by the user. It is primarily obtained from syscall arguments, truncated after 4096 bytes, or, as a fallback, by reading /proc/PID/cmdline, in which case it may be truncated after 1024 bytes. This field may differ from the last component of proc.exepath, reflecting how command invocation and execution paths can vary.
`proc.pexe`	CHARBUF	The proc.exe (first command line argument argv[0]) of the parent process.
`proc.aexe`	CHARBUF	The proc.exe (first command line argument argv[0]) for a specific process ancestor. You can access different levels of ancestors by using indices. For example, proc.aexe[1] retrieves the proc.exe of the parent process, proc.aexe[2] retrieves the proc.exe of the grandparent process, and so on. The current process's proc.exe line can be obtained using proc.aexe[0]. When used without any arguments, proc.aexe is applicable only in filters and matches any of the process ancestors. For instance, you can use `proc.aexe endswith java` to match any process ancestor whose proc.exe ends with the term `java`.
`proc.exepath`	CHARBUF	The full executable path of a process, resolving to the canonical path for symlinks. This is primarily obtained from the kernel, or as a fallback, by reading /proc/PID/exe (in the latter case, the path is truncated after 1024 bytes). For eBPF drivers, due to verifier limits, path components may be truncated to 24 for legacy eBPF on kernel <5.2, 48 for legacy eBPF on kernel >=5.2, or 96 for modern eBPF.
`proc.pexepath`	CHARBUF	The proc.exepath (full executable path) of the parent process.
`proc.aexepath`	CHARBUF	The proc.exepath (full executable path) for a specific process ancestor. You can access different levels of ancestors by using indices. For example, proc.aexepath[1] retrieves the proc.exepath of the parent process, proc.aexepath[2] retrieves the proc.exepath of the grandparent process, and so on. The current process's proc.exepath line can be obtained using proc.aexepath[0]. When used without any arguments, proc.aexepath is applicable only in filters and matches any of the process ancestors. For instance, you can use `proc.aexepath endswith java` to match any process ancestor whose path ends with the term `java`.
`proc.name`	CHARBUF	The process name (truncated after 16 characters) generating the event (task->comm). Truncation is determined by kernel settings and not by Falco. This field is collected from the syscalls args or, as a fallback, extracted from /proc/PID/comm. The name of the process and the name of the executable file on disk (if applicable) can be different if a process is given a custom name which is often the case for example for java applications.
`proc.pname`	CHARBUF	The proc.name (truncated after 16 characters) of the parent process.
`proc.aname`	CHARBUF	The proc.name (truncated after 16 characters) for a specific process ancestor. You can access different levels of ancestors by using indices. For example, proc.aname[1] retrieves the proc.name of the parent process, proc.aname[2] retrieves the proc.name of the grandparent process, and so on. The current process's proc.name line can be obtained using proc.aname[0]. When used without any arguments, proc.aname is applicable only in filters and matches any of the process ancestors. For instance, you can use `proc.aname=bash` to match any process ancestor whose name is `bash`.
`proc.args`	CHARBUF	The arguments passed on the command line when starting the process generating the event excluding argv[0] (truncated after 4096 bytes). This field is collected from the system call arguments, or as a fallback, extracted from /proc/PID/cmdline, can be accessed by specifying proc.args[INDEX], e.g., proc.args[0] or proc.args[1]. The indexing is zero-based, meaning proc.args[0] refers to the first command-line argument passed, rather than argv[0].
`proc.aargs`	CHARBUF	The arguments passed on the command line when starting the process generating the event for a specific process ancestor. You can access different levels of ancestors by using indices. For example, proc.aargs[1] retrieves the arguments passed on the command line of the parent process, proc.aargs[2] retrieves the proc.args of the grandparent process, and so on. The current process's arguments passed on the command line can be obtained using proc.aargs[0]. When used without any arguments, proc.aargs is applicable only in filters and matches any of the process ancestors. For instance, you can use `proc.aargs contains base64` to match any process ancestor whose arguments passed on the command line contains the term base64.
`proc.cmdline`	CHARBUF	The concatenation of `proc.name + proc.args` (truncated after 4096 bytes) when starting the process generating the event.
`proc.pcmdline`	CHARBUF	The proc.cmdline (full command line (proc.name + proc.args)) of the parent process.
`proc.acmdline`	CHARBUF	The full command line (proc.name + proc.args) for a specific process ancestor. You can access different levels of ancestors by using indices. For example, proc.acmdline[1] retrieves the full command line of the parent process, proc.acmdline[2] retrieves the proc.cmdline of the grandparent process, and so on. The current process's full command line can be obtained using proc.acmdline[0]. When used without any arguments, proc.acmdline is applicable only in filters and matches any of the process ancestors. For instance, you can use `proc.acmdline contains base64` to match any process ancestor whose command line contains the term base64.
`proc.cmdnargs`	UINT64	The number of command line args (proc.args).
`proc.cmdlenargs`	UINT64	The total count of characters / length of the command line args (proc.args) combined excluding whitespaces between args.
`proc.exeline`	CHARBUF	The full command line, with exe as first argument (proc.exe + proc.args) when starting the process generating the event.
`proc.env`	CHARBUF	The environment variables of the process generating the event as concatenated string 'ENV_NAME=value ENV_NAME1=value1'. Can also be used to extract the value of a known env variable, e.g. proc.env[ENV_NAME].
`proc.aenv`	CHARBUF	[EXPERIMENTAL] This field can be used in three flavors: (1) as a filter checking all parents, e.g. 'proc.aenv contains xyz', which is similar to the familiar 'proc.aname contains xyz' approach, (2) checking the `proc.env` of a specified level of the parent, e.g. 'proc.aenv[2]', which is similar to the familiar 'proc.aname[2]' approach, or (3) checking the first matched value of a known ENV_NAME in the parent lineage, such as 'proc.aenv[ENV_NAME]' (across a max of 20 ancestor levels). This field may be deprecated or undergo breaking changes in future releases. Please use it with caution.
`proc.cwd`	CHARBUF	The current working directory of the event.
`proc.loginshellid`	INT64	The pid of the oldest shell among the ancestors of the current process, if there is one. This field can be used to separate different user sessions.
`proc.tty`	UINT32	The controlling terminal of the process. 0 for processes without a terminal.
`proc.pid`	INT64	The id of the process generating the event.
`proc.ppid`	INT64	The pid of the parent of the process generating the event.
`proc.apid`	INT64	The pid for a specific process ancestor. You can access different levels of ancestors by using indices. For example, proc.apid[1] retrieves the pid of the parent process, proc.apid[2] retrieves the pid of the grandparent process, and so on. The current process's pid can be obtained using proc.apid[0]. When used without any arguments, proc.apid is applicable only in filters and matches any of the process ancestors. For instance, you can use `proc.apid=1337` to match any process ancestor whose pid is equal to 1337.
`proc.vpid`	INT64	The id of the process generating the event as seen from its current PID namespace.
`proc.pvpid`	INT64	The id of the parent process generating the event as seen from its current PID namespace.
`proc.sid`	INT64	The session id of the process generating the event.
`proc.sname`	CHARBUF	The name of the current process's session leader. This is either the process with pid=proc.sid or the eldest ancestor that has the same sid as the current process.
`proc.sid.exe`	CHARBUF	The first command line argument argv[0] (usually the executable name or a custom one) of the current process's session leader. This is either the process with pid=proc.sid or the eldest ancestor that has the same sid as the current process.
`proc.sid.exepath`	CHARBUF	The full executable path of the current process's session leader. This is either the process with pid=proc.sid or the eldest ancestor that has the same sid as the current process.
`proc.vpgid`	INT64	The process group id of the process generating the event, as seen from its current PID namespace.
`proc.vpgid.name`	CHARBUF	The name of the current process's process group leader. This is either the process with proc.vpgid == proc.vpid or the eldest ancestor that has the same vpgid as the current process. The description of `proc.is_vpgid_leader` offers additional insights.
`proc.vpgid.exe`	CHARBUF	The first command line argument argv[0] (usually the executable name or a custom one) of the current process's process group leader. This is either the process with proc.vpgid == proc.vpid or the eldest ancestor that has the same vpgid as the current process. The description of `proc.is_vpgid_leader` offers additional insights.
`proc.vpgid.exepath`	CHARBUF	The full executable path of the current process's process group leader. This is either the process with proc.vpgid == proc.vpid or the eldest ancestor that has the same vpgid as the current process. The description of `proc.is_vpgid_leader` offers additional insights.
`proc.pgid`	INT64	The process group id of the process generating the event, as seen from host PID namespace.
`proc.pgid.name`	CHARBUF	The name of the current process's process group leader. This is either the process with proc.pgid == proc.pid or the eldest ancestor that has the same pgid as the current process. The description of `proc.is_pgid_leader` offers additional insights.
`proc.pgid.exe`	CHARBUF	The first command line argument argv[0] (usually the executable name or a custom one) of the current process's process group leader. This is either the process with proc.pgid == proc.pid or the eldest ancestor that has the same pgid as the current process. The description of `proc.is_pgid_leader` offers additional insights.
`proc.pgid.exepath`	CHARBUF	The full executable path of the current process's process group leader. This is either the process with proc.pgid == proc.pid or the eldest ancestor that has the same pgid as the current process. The description of `proc.is_pgid_leader` offers additional insights.
`proc.duration`	RELTIME	Number of nanoseconds since the process started.
`proc.ppid.duration`	RELTIME	Number of nanoseconds since the parent process started.
`proc.pid.ts`	RELTIME	Start of process as epoch timestamp in nanoseconds.
`proc.ppid.ts`	RELTIME	Start of parent process as epoch timestamp in nanoseconds.
`proc.is_exe_writable`	BOOL	'true' if this process' executable file is writable by the same user that spawned the process.
`proc.is_exe_upper_layer`	BOOL	'true' if this process' executable file is in upper layer in overlayfs. This field value can only be trusted if the underlying kernel version is greater or equal than 3.18.0, since overlayfs was introduced at that time.
`proc.is_exe_lower_layer`	BOOL	'true' if this process' executable file is in lower layer in overlayfs. This field value can only be trusted if the underlying kernel version is greater or equal than 3.18.0, since overlayfs was introduced at that time.
`proc.is_exe_from_memfd`	BOOL	'true' if the executable file of the current process is an anonymous file created using memfd_create() and is being executed by referencing its file descriptor (fd). This type of file exists only in memory and not on disk. Relevant to detect malicious in-memory code injection. Requires kernel version greater or equal to 3.17.0.
`proc.is_sid_leader`	BOOL	'true' if this process is the leader of the process session, proc.sid == proc.vpid. For host processes vpid reflects pid.
`proc.is_vpgid_leader`	BOOL	'true' if this process is the leader of the virtual process group, proc.vpgid == proc.vpid. For host processes vpgid and vpid reflect pgid and pid. Can help to distinguish if the process was 'directly' executed for instance in a tty (similar to bash history logging, `is_vpgid_leader` would be 'true') or executed as descendent process in the same process group which for example is the case when subprocesses are spawned from a script (`is_vpgid_leader` would be 'false').
`proc.is_pgid_leader`	BOOL	'true' if this process is the leader of the process group, proc.pgid == proc.pid. Can help to distinguish if the process was 'directly' executed for instance in a tty (similar to bash history logging, `is_pgid_leader` would be 'true') or executed as descendent process in the same process group which for example is the case when subprocesses are spawned from a script (`is_pgid_leader` would be 'false').
`proc.exe_ino`	INT64	The inode number of the executable file on disk. Can be correlated with fd.ino.
`proc.exe_ino.ctime`	ABSTIME	Last status change time of executable file (inode->ctime) as epoch timestamp in nanoseconds. Time is changed by writing or by setting inode information e.g. owner, group, link count, mode etc.
`proc.exe_ino.mtime`	ABSTIME	Last modification time of executable file (inode->mtime) as epoch timestamp in nanoseconds. Time is changed by file modifications, e.g. by mknod, truncate, utime, write of more than zero bytes etc. For tracking changes in owner, group, link count or mode, use proc.exe_ino.ctime instead.
`proc.exe_ino.ctime_duration_proc_start`	ABSTIME	Number of nanoseconds between modifying status of executable image and spawning a new process using the changed executable image.
`proc.exe_ino.ctime_duration_pidns_start`	ABSTIME	Number of nanoseconds between PID namespace start ts and ctime exe file if PID namespace start predates ctime.
`proc.pidns_init_start_ts`	UINT64	Start of PID namespace (container or non container pid namespace) as epoch timestamp in nanoseconds.
`thread.cap_permitted`	CHARBUF	The permitted capabilities set
`thread.cap_inheritable`	CHARBUF	The inheritable capabilities set
`thread.cap_effective`	CHARBUF	The effective capabilities set
`proc.fdopencount`	UINT64	Number of open FDs for the process
`proc.fdlimit`	INT64	Maximum number of FDs the process can open.
`proc.fdusage`	DOUBLE	The ratio between open FDs and maximum available FDs for the process.
`proc.vmsize`	UINT64	Total virtual memory for the process (as kb).
`proc.vmrss`	UINT64	Resident non-swapped memory for the process (as kb).
`proc.vmswap`	UINT64	Swapped memory for the process (as kb).
`thread.pfmajor`	UINT64	Number of major page faults since thread start.
`thread.pfminor`	UINT64	Number of minor page faults since thread start.
`thread.tid`	INT64	The id of the thread generating the event.
`thread.ismain`	BOOL	'true' if the thread generating the event is the main one in the process.
`thread.vtid`	INT64	The id of the thread generating the event as seen from its current PID namespace.
`thread.exectime`	RELTIME	CPU time spent by the last scheduled thread, in nanoseconds. Exported by switch events only.
`thread.totexectime`	RELTIME	Total CPU time, in nanoseconds since the beginning of the capture, for the current thread. Exported by switch events only.
`thread.cgroups`	CHARBUF	All cgroups the thread belongs to, aggregated into a single string.
`thread.cgroup`	CHARBUF	The cgroup the thread belongs to, for a specific subsystem. e.g. thread.cgroup.cpuacct.
`proc.nthreads`	UINT64	The number of alive threads that the process generating the event currently has, including the leader thread. Please note that the leader thread may not be here, in that case 'proc.nthreads' and 'proc.nchilds' are equal
`proc.nchilds`	UINT64	The number of alive not leader threads that the process generating the event currently has. This excludes the leader thread.
`thread.cpu`	DOUBLE	The CPU consumed by the thread in the last second.
`thread.cpu.user`	DOUBLE	The user CPU consumed by the thread in the last second.
`thread.cpu.system`	DOUBLE	The system CPU consumed by the thread in the last second.
`thread.vmsize`	UINT64	For the process main thread, this is the total virtual memory for the process (as kb). For the other threads, this field is zero.
`thread.vmrss`	UINT64	For the process main thread, this is the resident non-swapped memory for the process (as kb). For the other threads, this field is zero.
`proc.stdin.type`	CHARBUF	The type of file descriptor 0, corresponding to stdin, of the process generating the event.
`proc.stdout.type`	CHARBUF	The type of file descriptor 1, corresponding to stdout, of the process generating the event.
`proc.stderr.type`	CHARBUF	The type of file descriptor 2, corresponding to stderr, of the process generating the event.
`proc.stdin.name`	CHARBUF	The name of the file descriptor 0, corresponding to stdin, of the process generating the event.
`proc.stdout.name`	CHARBUF	The name of the file descriptor 1, corresponding to stdout, of the process generating the event.
`proc.stderr.name`	CHARBUF	The name of the file descriptor 2, corresponding to stderr, of the process generating the event.

Field Class: user

Information about the user executing the specific event.

Name	Type	Description
`user.uid`	UINT32	user ID.
`user.name`	CHARBUF	user name.
`user.homedir`	CHARBUF	home directory of the user.
`user.shell`	CHARBUF	user's shell.
`user.loginuid`	INT64	audit user id (auid), internally the loginuid is of type `uint32_t`. However, if an invalid uid corresponding to UINT32_MAX is encountered, it is returned as -1 to support familiar filtering conditions.
`user.loginname`	CHARBUF	audit user name (auid).

Field Class: group

Information about the user group.

Name	Type	Description
`group.gid`	UINT32	group ID.
`group.name`	CHARBUF	group name.

Field Class: fd

Every syscall that has a file descriptor in its arguments has these fields set with information related to the file.

Name	Type	Description
`fd.num`	INT64	the unique number identifying the file descriptor.
`fd.type`	CHARBUF	type of FD. Can be 'file', 'directory', 'ipv4', 'ipv6', 'unix', 'pipe', 'event', 'signalfd', 'eventpoll', 'inotify' 'signalfd' or 'memfd'.
`fd.typechar`	CHARBUF	type of FD as a single character. Can be 'f' for file, 4 for IPv4 socket, 6 for IPv6 socket, 'u' for unix socket, p for pipe, 'e' for eventfd, 's' for signalfd, 'l' for eventpoll, 'i' for inotify, 'b' for bpf, 'u' for userfaultd, 'r' for io_uring, 'm' for memfd ,'o' for unknown.
`fd.name`	CHARBUF	FD full name. If the fd is a file, this field contains the full path. If the FD is a socket, this field contain the connection tuple.
`fd.directory`	CHARBUF	If the fd is a file, the directory that contains it.
`fd.filename`	CHARBUF	If the fd is a file, the filename without the path.
`fd.ip`	IPADDR	matches the ip address (client or server) of the fd.
`fd.cip`	IPADDR	client IP address.
`fd.sip`	IPADDR	server IP address.
`fd.lip`	IPADDR	local IP address.
`fd.rip`	IPADDR	remote IP address.
`fd.port`	PORT	matches the port (either client or server) of the fd.
`fd.cport`	PORT	for TCP/UDP FDs, the client port.
`fd.sport`	PORT	for TCP/UDP FDs, server port.
`fd.lport`	PORT	for TCP/UDP FDs, the local port.
`fd.rport`	PORT	for TCP/UDP FDs, the remote port.
`fd.l4proto`	CHARBUF	the IP protocol of a socket. Can be 'tcp', 'udp', 'icmp' or 'raw'.
`fd.sockfamily`	CHARBUF	the socket family for socket events. Can be 'ip' or 'unix'.
`fd.is_server`	BOOL	'true' if the process owning this FD is the server endpoint in the connection.
`fd.uid`	CHARBUF	a unique identifier for the FD, created by chaining the FD number and the thread ID.
`fd.containername`	CHARBUF	chaining of the container ID and the FD name. Useful when trying to identify which container an FD belongs to.
`fd.containerdirectory`	CHARBUF	chaining of the container ID and the directory name. Useful when trying to identify which container a directory belongs to.
`fd.proto`	PORT	matches the protocol (either client or server) of the fd.
`fd.cproto`	CHARBUF	for TCP/UDP FDs, the client protocol.
`fd.sproto`	CHARBUF	for TCP/UDP FDs, server protocol.
`fd.lproto`	CHARBUF	for TCP/UDP FDs, the local protocol.
`fd.rproto`	CHARBUF	for TCP/UDP FDs, the remote protocol.
`fd.net`	IPNET	matches the IP network (client or server) of the fd.
`fd.cnet`	IPNET	matches the client IP network of the fd.
`fd.snet`	IPNET	matches the server IP network of the fd.
`fd.lnet`	IPNET	matches the local IP network of the fd.
`fd.rnet`	IPNET	matches the remote IP network of the fd.
`fd.connected`	BOOL	for TCP/UDP FDs, 'true' if the socket is connected.
`fd.name_changed`	BOOL	True when an event changes the name of an fd used by this event. This can occur in some cases such as udp connections where the connection tuple changes.
`fd.cip.name`	CHARBUF	Domain name associated with the client IP address.
`fd.sip.name`	CHARBUF	Domain name associated with the server IP address.
`fd.lip.name`	CHARBUF	Domain name associated with the local IP address.
`fd.rip.name`	CHARBUF	Domain name associated with the remote IP address.
`fd.dev`	INT32	device number (major/minor) containing the referenced file
`fd.dev.major`	INT32	major device number containing the referenced file
`fd.dev.minor`	INT32	minor device number containing the referenced file
`fd.ino`	INT64	inode number of the referenced file
`fd.nameraw`	CHARBUF	FD full name raw. Just like fd.name, but only used if fd is a file path. File path is kept raw with limited sanitization and without deriving the absolute path.
`fd.types`	LIST(CHARBUF)	List of FD types in used. Can be passed an fd number e.g. fd.types[0] to get the type of stdout as a single item list.
`fd.is_upper_layer`	BOOL	'true' if the fd is of a file in the upper layer of an overlayfs.
`fd.is_lower_layer`	BOOL	'true' if the fd is of a file in the lower layer of an overlayfs.

Field Class: fs.path

Every syscall that has a filesystem path in its arguments has these fields set with information related to the path arguments. This differs from the fd.* fields as it includes syscalls like unlink, rename, etc. that act directly on filesystem paths as compared to opened file descriptors.

Name	Type	Description
`fs.path.name`	CHARBUF	For any event type that deals with a filesystem path, the path the file syscall is operating on. This path is always fully resolved, prepending the thread cwd when needed.
`fs.path.nameraw`	CHARBUF	For any event type that deals with a filesystem path, the path the file syscall is operating on. This path is always the path provided to the syscall and may not be fully resolved.
`fs.path.source`	CHARBUF	For any event type that deals with a filesystem path, and specifically for a source and target like mv, cp, etc, the source path the file syscall is operating on. This path is always fully resolved, prepending the thread cwd when needed.
`fs.path.sourceraw`	CHARBUF	For any event type that deals with a filesystem path, and specifically for a source and target like mv, cp, etc, the source path the file syscall is operating on. This path is always the path provided to the syscall and may not be fully resolved.
`fs.path.target`	CHARBUF	For any event type that deals with a filesystem path, and specifically for a target and target like mv, cp, etc, the target path the file syscall is operating on. This path is always fully resolved, prepending the thread cwd when needed.
`fs.path.targetraw`	CHARBUF	For any event type that deals with a filesystem path, and specifically for a target and target like mv, cp, etc, the target path the file syscall is operating on. This path is always the path provided to the syscall and may not be fully resolved.

Field Class: fdlist

Poll event related fields.

Name	Type	Description
`fdlist.nums`	CHARBUF	for poll events, this is a comma-separated list of the FD numbers in the 'fds' argument, returned as a string.
`fdlist.names`	CHARBUF	for poll events, this is a comma-separated list of the FD names in the 'fds' argument, returned as a string.
`fdlist.cips`	CHARBUF	for poll events, this is a comma-separated list of the client IP addresses in the 'fds' argument, returned as a string.
`fdlist.sips`	CHARBUF	for poll events, this is a comma-separated list of the server IP addresses in the 'fds' argument, returned as a string.
`fdlist.cports`	CHARBUF	for TCP/UDP FDs, for poll events, this is a comma-separated list of the client TCP/UDP ports in the 'fds' argument, returned as a string.
`fdlist.sports`	CHARBUF	for poll events, this is a comma-separated list of the server TCP/UDP ports in the 'fds' argument, returned as a string.

Field Class: container (plugin)

Name	Type	Description
`container.id`	CHARBUF	The truncated container ID (first 12 characters), e.g. 3ad7b26ded6d is extracted from the Linux cgroups by Falco within the kernel. Consequently, this field is reliably available and serves as the lookup key for Falco's synchronous or asynchronous requests against the container runtime socket to retrieve all other 'container.' information. One important aspect to be aware of is that if the process occurs on the host, meaning not in the container PID namespace, this field is set to a string called 'host'. In Kubernetes, pod sandbox container processes can exist where `container.id` matches `k8s.pod.sandbox_id`, lacking other 'container.' details.
`container.full_id`	CHARBUF	The full container ID, e.g. 3ad7b26ded6d8e7b23da7d48fe889434573036c27ae5a74837233de441c3601e. In contrast to `container.id`, we enrich this field as part of the container engine enrichment. In instances of userspace container engine lookup delays, this field may not be available yet.
`container.name`	CHARBUF	The container name. In instances of userspace container engine lookup delays, this field may not be available yet. One important aspect to be aware of is that if the process occurs on the host, meaning not in the container PID namespace, this field is set to a string called 'host'.
`container.image`	CHARBUF	The container image name (e.g. falcosecurity/falco:latest for docker). In instances of userspace container engine lookup delays, this field may not be available yet.
`container.image.id`	CHARBUF	The container image id (e.g. 6f7e2741b66b). In instances of userspace container engine lookup delays, this field may not be available yet.
`container.type`	CHARBUF	The container type, e.g. docker, cri-o, containerd etc.
`container.privileged`	BOOL	'true' for containers running as privileged, 'false' otherwise. In instances of userspace container engine lookup delays, this field may not be available yet.
`container.mounts`	CHARBUF	A space-separated list of mount information. Each item in the list has the format 'source:dest:mode:rdrw:propagation'. In instances of userspace container engine lookup delays, this field may not be available yet.
`container.mount`	CHARBUF	Information about a single mount, specified by number (e.g. container.mount[0]) or mount source (container.mount[/usr/local]). The pathname can be a glob (container.mount[/usr/local/*]), in which case the first matching mount will be returned. The information has the format 'source:dest:mode:rdrw:propagation'. If there is no mount with the specified index or matching the provided source, returns the string "none" instead of a NULL value. In instances of userspace container engine lookup delays, this field may not be available yet.
`container.mount.source`	CHARBUF	The mount source, specified by number (e.g. container.mount.source[0]) or mount destination (container.mount.source[/host/lib/modules]). The pathname can be a glob. In instances of userspace container engine lookup delays, this field may not be available yet.
`container.mount.dest`	CHARBUF	The mount destination, specified by number (e.g. container.mount.dest[0]) or mount source (container.mount.dest[/lib/modules]). The pathname can be a glob. In instances of userspace container engine lookup delays, this field may not be available yet.
`container.mount.mode`	CHARBUF	The mount mode, specified by number (e.g. container.mount.mode[0]) or mount source (container.mount.mode[/usr/local]). The pathname can be a glob. In instances of userspace container engine lookup delays, this field may not be available yet.
`container.mount.rdwr`	CHARBUF	The mount rdwr value, specified by number (e.g. container.mount.rdwr[0]) or mount source (container.mount.rdwr[/usr/local]). The pathname can be a glob. In instances of userspace container engine lookup delays, this field may not be available yet.
`container.mount.propagation`	CHARBUF	The mount propagation value, specified by number (e.g. container.mount.propagation[0]) or mount source (container.mount.propagation[/usr/local]). The pathname can be a glob. In instances of userspace container engine lookup delays, this field may not be available yet.
`container.image.repository`	CHARBUF	The container image repository (e.g. falcosecurity/falco). In instances of userspace container engine lookup delays, this field may not be available yet.
`container.image.tag`	CHARBUF	The container image tag (e.g. stable, latest). In instances of userspace container engine lookup delays, this field may not be available yet.
`container.image.digest`	CHARBUF	The container image registry digest (e.g. sha256:d977378f890d445c15e51795296e4e5062f109ce6da83e0a355fc4ad8699d27). In instances of userspace container engine lookup delays, this field may not be available yet.
`container.healthcheck`	CHARBUF	The container's health check. Will be the null value ("N/A") if no healthcheck configured, "NONE" if configured but explicitly not created, and the healthcheck command line otherwise. In instances of userspace container engine lookup delays, this field may not be available yet.
`container.liveness_probe`	CHARBUF	The container's liveness probe. Will be the null value ("N/A") if no liveness probe configured, the liveness probe command line otherwise. In instances of userspace container engine lookup delays, this field may not be available yet.
`container.readiness_probe`	CHARBUF	The container's readiness probe. Will be the null value ("N/A") if no readiness probe configured, the readiness probe command line otherwise. In instances of userspace container engine lookup delays, this field may not be available yet.
`container.start_ts`	ABSTIME	Container start as epoch timestamp in nanoseconds based on proc.pidns_init_start_ts and extracted in the kernel and not from the container runtime socket / container engine.
`container.duration`	RELTIME	Number of nanoseconds since container.start_ts.
`container.ip`	CHARBUF	The container's / pod's primary ip address as retrieved from the container engine. Only ipv4 addresses are tracked. Consider container.cni.json (CRI use case) for logging ip addresses for each network interface. In instances of userspace container engine lookup delays, this field may not be available yet.
`container.cni.json`	CHARBUF	The container's / pod's CNI result field from the respective pod status info. It contains ip addresses for each network interface exposed as unparsed escaped JSON string. Supported for CRI container engine (containerd, cri-o runtimes), optimized for containerd (some non-critical JSON keys removed). Useful for tracking ips (ipv4 and ipv6, dual-stack support) for each network interface (multi-interface support). In instances of userspace container engine lookup delays, this field may not be available yet.
`container.host_pid`	BOOL	'true' if the container is running in the host PID namespace, 'false' otherwise.
`container.host_network`	BOOL	'true' if the container is running in the host network namespace, 'false' otherwise.
`container.host_ipc`	BOOL	'true' if the container is running in the host IPC namespace, 'false' otherwise.
`container.label`	CHARBUF	Container label. E.g. 'container.label.foo'.
`container.labels`	CHARBUF	Container comma-separated key/value labels. E.g. 'foo1:bar1,foo2:bar2'.
`proc.is_container_healthcheck`	BOOL	'true' if this process is running as a part of the container's health check.
`proc.is_container_liveness_probe`	BOOL	'true' if this process is running as a part of the container's liveness probe.
`proc.is_container_readiness_probe`	BOOL	'true' if this process is running as a part of the container's readiness probe.
`k8s.pod.name`	CHARBUF	The Kubernetes pod name. This field is extracted from the container runtime socket simultaneously as we look up the 'container.*' fields. In cases of lookup delays, it may not be available yet.
`k8s.ns.name`	CHARBUF	The Kubernetes namespace name. This field is extracted from the container runtime socket simultaneously as we look up the 'container.*' fields. In cases of lookup delays, it may not be available yet.
`k8s.pod.id`	CHARBUF	[LEGACY] The Kubernetes pod UID, e.g. 3e41dc6b-08a8-44db-bc2a-3724b18ab19a. This legacy field points to `k8s.pod.uid`; however, the pod ID typically refers to the pod sandbox ID. We recommend using the semantically more accurate `k8s.pod.uid` field. This field is extracted from the container runtime socket simultaneously as we look up the 'container.*' fields. In cases of lookup delays, it may not be available yet.
`k8s.pod.uid`	CHARBUF	The Kubernetes pod UID, e.g. 3e41dc6b-08a8-44db-bc2a-3724b18ab19a. Note that the pod UID is a unique identifier assigned upon pod creation within Kubernetes, allowing the Kubernetes control plane to manage and track pods reliably. As such, it is fundamentally a different concept compared to the pod sandbox ID. This field is extracted from the container runtime socket simultaneously as we look up the 'container.*' fields. In cases of lookup delays, it may not be available yet.
`k8s.pod.sandbox_id`	CHARBUF	The truncated Kubernetes pod sandbox ID (first 12 characters), e.g 63060edc2d3a. The sandbox ID is specific to the container runtime environment. It is the equivalent of the container ID for the pod / sandbox and extracted from the Linux cgroups. As such, it differs from the pod UID. This field is extracted from the container runtime socket simultaneously as we look up the 'container.' fields. In cases of lookup delays, it may not be available yet. In Kubernetes, pod sandbox container processes can exist where `container.id` matches `k8s.pod.sandbox_id`, lacking other 'container.' details.
`k8s.pod.full_sandbox_id`	CHARBUF	The full Kubernetes pod / sandbox ID, e.g 63060edc2d3aa803ab559f2393776b151f99fc5b05035b21db66b3b62246ad6a. This field is extracted from the container runtime socket simultaneously as we look up the 'container.*' fields. In cases of lookup delays, it may not be available yet.
`k8s.pod.label`	CHARBUF	The Kubernetes pod label. The label can be accessed either with the familiar brackets notation, e.g. 'k8s.pod.label[foo]' or by appending a dot followed by the name, e.g. 'k8s.pod.label.foo'. The label name itself can include the original special characters such as '.', '-', '_' or '/' characters. For instance, 'k8s.pod.label[app.kubernetes.io/name]', 'k8s.pod.label.app.kubernetes.io/name' or 'k8s.pod.label[custom-label_one]' are all valid. This field is extracted from the container runtime socket simultaneously as we look up the 'container.*' fields. In cases of lookup delays, it may not be available yet.
`k8s.pod.labels`	CHARBUF	The Kubernetes pod comma-separated key/value labels. E.g. 'foo1:bar1,foo2:bar2'. This field is extracted from the container runtime socket simultaneously as we look up the 'container.*' fields. In cases of lookup delays, it may not be available yet.
`k8s.pod.ip`	CHARBUF	The Kubernetes pod ip, same as container.ip field as each container in a pod shares the network stack of the sandbox / pod. Only ipv4 addresses are tracked. Consider k8s.pod.cni.json for logging ip addresses for each network interface. This field is extracted from the container runtime socket simultaneously as we look up the 'container.*' fields. In cases of lookup delays, it may not be available yet.
`k8s.pod.cni.json`	CHARBUF	The Kubernetes pod CNI result field from the respective pod status info, same as container.cni.json field. It contains ip addresses for each network interface exposed as unparsed escaped JSON string. Supported for CRI container engine (containerd, cri-o runtimes), optimized for containerd (some non-critical JSON keys removed). Useful for tracking ips (ipv4 and ipv6, dual-stack support) for each network interface (multi-interface support). This field is extracted from the container runtime socket simultaneously as we look up the 'container.*' fields. In cases of lookup delays, it may not be available yet.
`k8s.rc.name`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.rc.id`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.rc.label`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.rc.labels`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.svc.name`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.svc.id`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.svc.label`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.svc.labels`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.ns.id`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.ns.label`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.ns.labels`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.rs.name`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.rs.id`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.rs.label`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.rs.labels`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.deployment.name`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.deployment.id`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.deployment.label`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.
`k8s.deployment.labels`	CHARBUF	Deprecated. Use `k8smeta` plugin instead.

Docs: Generating sample events

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

If you'd like to check if Falco is working properly, we have the event-generator tool that can perform an activity for both our syscalls and k8s audit related rules.

The tool provides a command to run either some or all sample events.

event-generator run [regexp]

Without arguments it runs all actions, otherwise only those actions matching the given regular expression.

The full command line documentation is here.

Downloads

Artifacts		Version
binaries	download link
container images	`docker pull falcosecurity/event-generator:latest`

Sample events

WARNING

Since some commands might alter your system, we strongly recommend that you run the program within a container (see below).
For example, some actions modify files and directories below /bin, /etc, /dev, etc.

System Call Activity

The syscall collection performs a variety of suspect actions that are detected by the default Falco ruleset.

docker run -it --rm falcosecurity/event-generator run syscall --loop

The above command loops forever, incessantly generating a sample event each second.

Kubernetes Auditing Activity

The k8saudit collection generates activity that matches the k8s audit event ruleset.

event-generator run k8saudit --loop

The above command loops forever, creating resources in the current namespace and deleting them after each iteration. Use the --namespace option to choose a different namespace.

Running the Event Generator in K8s

We've also provided a helm chart that make it easy to run the event generator in K8s Clusters.

First thing, we need to add the falcosecurity charts repository:

helm repo add falcosecurity https://falcosecurity.github.io/charts
helm repo update

Once you have the helm repo configured, you can run the following to create the necessary objects in the event-generator namespace and then generate events continuously:

helm install event-generator falcosecurity/event-generator \
 --namespace event-generator \
 --create-namespace \
 --set config.loop=false \
 --set config.actions=""

The above command applies to the event-generator namespace. Use the --namespace option to deploy in a different namespace. Events will be generated in the same namespace.

You can also find more examples in the event-generator and charts repositories.

Docs: Rule Exceptions

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

Introduction

Almost all Falco Rules have cases where the behavior detected by the rule should be allowed. For example, the rule Write below binary dir has exceptions for specific programs that are known to write below these directories as a part of software installation/management:

- rule: Write below binary dir
 desc: an attempt to write to any file below a set of binary directories
 condition: >
 open_write
 and bin_dir
 and not package_mgmt_procs
 and not exe_running_docker_save
 and not python_running_get_pip
 and not python_running_ms_oms
 and not user_known_write_below_binary_dir_activities
...

Previously, these exceptions were expressed as concatenations to the original rule's condition. For example, looking at the macro package_mgmt_procs:

- macro: package_mgmt_procs
 condition: proc.name in (package_mgmt_binaries)

The result is appending and not proc.name in (package_mgmt_binaries) to the condition of the rule.

A more extreme case of this is the write_below_etc macro used by Write below etc rule. It had tens of exceptions:

 ...
and not sed_temporary_file
and not exe_running_docker_save
and not ansible_running_python
and not python_running_denyhosts
and not fluentd_writing_conf_files
and not user_known_write_etc_conditions
and not run_by_centrify
and not run_by_adclient
and not qualys_writing_conf_files
and not git_writing_nssdb
...

The exceptions all generally follow the same structure: naming a program and a directory prefix below /etc where that program is allowed to write files.

Rule Exceptions

Starting in 0.28.0, Falco supports an optional exceptions property to rules. The exceptions key is a list of identifier plus list of tuples of filtercheck fields. Here's an example:

- rule: Write below binary dir
 desc: an attempt to write to any file below a set of binary directories
 condition: >
 open_write
 and bin_dir
 and not package_mgmt_procs
 and not exe_running_docker_save
 and not python_running_get_pip
 and not python_running_ms_oms
 and not user_known_write_below_binary_dir_activities
 exceptions:
 - name: proc_writer
 fields: [proc.name, fd.directory]
 comps: [=, =]
 values:
 - [my-custom-yum, /usr/bin]
 - [my-custom-apt, /usr/local/bin]
 - name: cmdline_writer
 fields: [proc.cmdline, fd.directory]
 comps: [startswith, =]
 - name: container_writer
 fields: [container.image.repository, fd.directory]
 - name: proc_filenames
 fields: [proc.name, fd.name]
 comps: [=, in]
 values:
 - [my-custom-dpkg, [/usr/bin, /bin]]
 - name: filenames
 fields: fd.filename
 comps: in

This rule defines four kinds of exceptions:

proc_writer: uses a combination of proc.name and fd.directory
cmdline_writer: uses a combination of proc.cmeline and fd.directory
container_writer: uses a combination of container.image.repository and fd.directory
proc_filenames: uses a combination of process and list of filenames.
filenames: uses a list of filenames

The specific strings proc_writer/container_writer/proc_filenames/filenames are arbitrary strings and don't have a special meaning to the rules file parser. They're only used to provide a handy name, and to potentially link together values in a later rule override (more on that below).

Notice that exceptions are defined as a part of the rule. This is important because the author of the rule defines what construes a valid exception to the rule. In this case, an exception can consist of a process and file directory (actor and target), but not a process name only (too broad).

The fields property contains one or more fields that will extract a value from the events. The comps property contains comparison operators that align 1-1 with the items in the fields property. The values property contains tuples of values. Each item in the tuple should align 1-1 with the corresponding field and comparison operator. Together, each tuple of values is combined with the fields/comps to modify the condition to add an exclusion to the rule's condition.

For example, for the exception proc_writer above, the fields/comps/values are the equivalent of adding the following to the rule's condition:

... and not ((proc.name=my-custom-yum and fd.directory=/usr/bin) or (proc.name=my-custom-apt and fd.directory=/usr/local/bin))

Note that when a comparison operator is in, the corresponding values tuple item should be a list. proc_filenames above uses that syntax, and is the equivalent of:

... and not (proc.name=my-custom-dpkg and fd.name in (/usr/bin, /bin))

Exception Syntax Shortcuts

In general, the value for an exceptions fields property should always be a list of fields. The comps property must be an equal-length list of comparison operators, and the values property must be a list of tuples, where each tuple has the same length as the fields/comps lists.

However, there are a few shortcuts that can be used when defining an exception:

Values are Optional

A rule may define fields and comps, but not define values. This allows a later rule override to add values to an exception (more on that below). The exception cmdline_writer above has this format:

 - name: cmdline_writer
fields: [proc.cmdline, fd.directory]
comps: [startswith, =]

Fields/Comps Can Be a Single Value, Not a List

An alternative way to define an exception is to have fields containing a single field and comps containing a single comparison operator (which must be one of in, pmatch, intersects). In this format, values is a list of values rather than list of tuples. The exception filenames above has this format:

 - name: filenames
fields: fd.filename
comps: in

In this case, the exception is the equivalent of:

... and not (fd.filename in (...))

Comps is Optional

If comps is not provided, a default value is filled in. When fields is a list, comps will be set to an equal-length list of = operators. The exception container_writer above has that format, and is equivalent to:

 - name: container_writer
fields: [container.image.repository, fd.directory]
comps: [=, =]

When fields is a single field, comps is set to a single in operator.

Appending Exception Values

Exception values will most commonly be defined in rules overrides. Here's an example:

- list: apt_files
 items: [/bin/ls, /bin/rm]

- rule: Write below binary dir
 exceptions:
 - name: proc_writer
 values:
 - [apk, /usr/lib/alpine]
 - [npm, /usr/node/bin]
 - name: container_writer
 values:
 - [docker.io/alpine, /usr/libexec/alpine]
 - name: proc_filenames
 values:
 - [apt, [apt_files]]
 - [rpm, [/bin/cp, /bin/pwd]]
 - name: filenames
 values: [python, go]
 override:
 exceptions: append

In this case, the values are appended to any values for the base rule, and then the fields/comps/values are added to the rule's condition.

Putting it all together, the effective rule condition for this rule is:

... and not ((proc.name=my-custom-yum and fd.directory=/usr/bin) or # proc_writer
(proc.name=my-custom-apt and fd.directory=/usr/local/bin) or
(proc.name=apk and fd.directory=/usr/lib/alpine) or
(proc.name=npm and fd.directory=/usr/node/bin) or
(container.image.repository=docker.io/alpine and fd.name=/usr/libexec/alpine) or # container_writer
(proc.name=apt and fd.name in (apt_files)) or # proc_filenames
(proc.name=rpm and fd.name in (/bin/cp, /bin/pwd)) or
(fd.filename in (python, go)) # filenames

Replacing Exception Values

It's possible to replace the entire list(s) of values tuples for specific exception(s) by following the rules overriding syntax and specifying exceptions: replace. Here's an example:

- list: apt_files
 items: [/bin/ls, /bin/rm]

- rule: Write below binary dir
 exceptions:
 - name: proc_writer
 values:
 - [apk, /usr/lib/alpine]
 - [npm, /usr/node/bin]
 - name: container_writer
 values:
 - [docker.io/alpine, /usr/libexec/alpine]
 - name: proc_filenames
 values:
 - [apt, [apt_files]]
 - [rpm, [/bin/cp, /bin/pwd]]
 - name: filenames
 values: [python, go]
 override:
 exceptions: replace

Here, the values lists for the proc_writer, container_writer, proc_filenames and filenames exceptions will be replaced (or initialized) with the corresponding values lists, Putting it all together, the effective rule condition for this rule will be:

... and not ((proc.name=apk and fd.directory=/usr/lib/alpine) or # proc_writer
(proc.name=npm and fd.directory=/usr/node/bin) or
(container.image.repository=docker.io/alpine and fd.name=/usr/libexec/alpine) or # container_writer
(proc.name=apt and fd.name in (apt_files)) or # proc_filenames
(proc.name=rpm and fd.name in (/bin/cp, /bin/pwd)) or
(fd.filename in (python, go)) # filenames

Guidelines For Adding Exceptions To Rules

The default rules files have been revamped to use exceptions whenever possible, and are a good reference for best practices when defining exceptions for rules. Here are some other guidelines to follow:

Be Specific

When defining an exception, try to think about the actor, action, and target, and whenever possible use all three items for an exception. For example, instead of simply using proc.name or container.image.repository for a file-based exception, also include the file being acted on via fd.name, fd.directory, etc. Similarly, if a rule is container-specific, don't only include the image container.image.repository, also include the process name proc.name.

Use Set Operators

If an exception involves a set of process names, file paths, etc., combine the process names into a list and use the in/pmatch operator to handle the values in a single exception. Here's an example:

 - name: proc_file
 fields: [proc.name, fd.name]
 comps: [in, in]
 values:
 - [[qualys-cloud-ag], [/etc/qualys/cloud-agent/qagent-log.conf]]
 - [[update-haproxy-,haproxy_reload.], [/etc/openvpn/client.map]]
 - [[start-fluentd], [/etc/fluent/fluent.conf, /etc/td-agent/td-agent.conf]]

This exception matches process name and path, but allows for multiple process names writing to any of a set of files.

More Information

The original proposal describes the benefits of exceptions in more detail.

Docs: Controlling Rules

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

Disable Default Rules

Even though Falco provides a quite powerful default ruleset, you sometimes need to disable some of these default rules since they do not work properly in your environment. Luckily Falco offers you multiple possibilities to do so.

Via Falco Configuration or Parameters

Since Falco 0.38.0, you can control which rules are loaded by adding relevant entries to the rules section of the falco.yaml configuration file or by passing appropriate command line parameters. In the rules section you can add any number of enable or disable entries:

- enable:
 rule: <wildcard pattern>

- disable:
 rule: <wildcard pattern>

- enable:
 tag: <tag>

- disable:
 tag: <tag>

All the entries are treated as commands and evaluated in order, thus controlling the enabled status of the loaded rules. For instance, in order to only enable the rules called Netcat Remote Code Execution in Container and Delete or rename shell history you can supply the following configuration:

rules:
 - disable:
 rule: "*"
 - enable:
 rule: Netcat Remote Code Execution in Container
 - enable:
 rule: Delete or rename shell history

The above instructs Falco to first disable all rules (regardless of their enabled status in the files or any override), then enable the Netcat rule and finally enable the deletion rule.

Alternatively, this configuration can be supplied on the Falco command line by using the -o option.

falco -o "rules[].enable.tag=network" -o "rules[].enable.rule=Directory traversal monitored file" -o "rules[].enable.rule=k8s_*" -o "rules[].disable.rule=k8s_noisy_rule"

In the above example, all the rules tagged network are enabled, the Directory traversal monitored file will also be enabled alongside any rule matching the pattern k8s_*, and then the rule k8s_noisy_rule will be disabled; all of this happens regardless of any enabled status specified in the rules files. If both yaml configuration and -o options are specified, the CLI options are applied last.

These parameters can also be specified as Helm chart value (extraArgs) if you are deploying Falco via the official Helm chart.

Via existing Macros

Most of the default rules offer some kind of user_* macros which are already part of the rule conditions. These user_* macros are usually set to (never_true) or (always_true) which basically enables or disables the regarding rule. Now if you want to disable a default rule (e.g. Read sensitive file trusted after startup), you just have to override the rule's user_* macro (user_known_read_sensitive_files_activities in this case) inside your custom Falco configuration.

Example for your custom Falco configuration (note the (always_true) condition):

- macro: user_known_read_sensitive_files_activities
 condition: (always_true)

Please note again that the order of the specified configuration file matters! The last defined macro with the same name wins.

Via Custom Rule Definition

The enabled attribute used as an override is deprecated and it will be removed in Falco 1.0.0. Use the override.enabled attribute instead. Please note that the enabled key is only deprecated when used as an override! So a rule like this is perfectly legit:

- rule: legit_rule
 desc: legit rule description
 condition: evt.type=open
 output: user=%user.name command=%proc.cmdline file=%fd.name
 priority: INFO
 enabled: false

Last but not the least, you can just disable a rule that is enabled by default using the enabled: false rule property. This is especially useful for rules which do not provide a user_* macro in the default condition.

Ensure that the custom configuration file loads after the default configuration file. You can configure the right order using multiple -r parameters or directly inside the falco configuration file falco.yaml through rules_files. If you are using the official Helm chart, then configure the order with the falco.rules_files value.

For example to disable the User mgmt binaries default rule in /etc/falco/falco_rules.yaml define a custom rule in /etc/falco/rules.d/custom-rules.yaml:

- rule: User mgmt binaries
 enabled: false

At the same time, disabled rules can be re-enabled by using the enabled: true rule property. For instance, the Change thread namespace rule in /etc/falco/falco_rules.yaml that is disabled by default, can be manually enabled with:

- rule: Change thread namespace
 enabled: true

Rule Tags

As of 0.6.0, rules have an optional set of tags that are used to categorize the ruleset into groups of related rules. Here's an example:

- rule: File Open by Privileged Container
 desc: Any open by a privileged container. Exceptions are made for known trusted images.
 condition: (open_read or open_write) and container and container.privileged=true and not trusted_containers
 output: File opened for read/write by privileged container | user=%user.name command=%proc.cmdline file=%fd.name
 priority: WARNING
 tags: [container, cis]

In this case, the rule "File Open by Privileged Container" has been given the tags "container" and "cis". If the tags key is not present for a given rule or the list is empty, a rule has no tags.

Here's how you can use tags:

You can use the -T <tag> argument to disable rules having a given tag. -T can be specified multiple times. For example, to skip all rules with the "filesystem" and "cis" tags you would run falco with falco -T filesystem -T cis .... -T can not be specified with -t.
You can use the -t <tag> argument to only run those rules having a given tag. -t can be specified multiple times. For example, to only run those rules with the "filesystem" and "cis" tags, you would run falco with falco -t filesystem -t cis .... -t can not be specified with -T or -D <pattern> (disable rules by rule name regex).

Tags for Current Falco Ruleset

We've also gone through the default ruleset and tagged all the rules with an initial set of tags. Here are the tags we've used:

Tag	Description
`filesystem`	The rule relates to reading/writing files
`software_mgmt`	The rule relates to any software/package management tool like rpm, dpkg, etc.
`process`	The rule relates to starting a new process or changing the state of a current process
`database`	The rule relates to databases
`host`	The rule only works outside of containers
`shell`	The rule specifically relates to starting shells
`container`	The rule only works inside containers
`cis`	The rule is related to the CIS Docker benchmark
`users`	The rule relates to management of users or changing the identity of a running process
`network`	The rule relates to network activity

Rules can have multiple tags if they relate to multiple of the above. Every rule in the falco ruleset currently has at least one tag.

Ignored system calls

For performance reasons, some system calls are currently discarded before Falco processes them.
You can see the complete list by running falco with -i.

If you'd like to run Falco against all events, including system calls in the above list,
you can run Falco with the -A flag.

For more information, see supported events.

Falco – The Falco Project

Docs: Performance

Resource Utilization and System Impact

CPU and Memory Utilization

Server Load and Falco Event Drops

Docs: Deploy on Kubernetes with the Operator

Overview

Prerequisites

Install the Operator

Full Stack Quickstart

Step-by-Step Quickstart

Deploy Falco

Add the Container Plugin

Add Detection Rules

Add Other Plugins

Add Ecosystem Components

Falcosidekick

Falcosidekick UI

k8s-metacollector

Customize Configuration

Deployment Modes

DaemonSet (default)

Deployment

Uninstall

Learn More

Docs: Plugins Architecture Concepts

Overview

Plugins are Coresident with Falco

Plugin SDKs

Event Sourcing Capability

Field Extraction Capability

Event Parsing Capability

Async Events Capability

Composability of Capabilities

Plugin Event IDs

Plugin Event Sources and Interoperability

Handling Duplicate/Overlapping Fields in Plugins/Libraries Core

Plugin API

Info Functions

Instance/Capture Management Functions

Events/Fields Related Functions

Docs: Basic Elements of Falco Rules

Rules

Conditions

Output

Priority

Advanced Rule Syntax

Macros

Lists

Visibility

Docs: Build Falco from source

Dependencies

Build Falco

Build all

Build Falco only

Build the Falco engine only

Build libscap only

Build libsinsp only

Build the eBPF probe / kernel driver only

Build results

CMake Options

Generate verbose makefiles

Specify C and CXX compilers

Enforce bundled dependencies

Treat warnings as errors

Specify the build type

Specify the Falco version

Enable eBPF support

Load latest falco kernel module

Run falco

Docs: Output Channels

Standard Output

Standard Output buffering

File Output

Syslog Output

Program Output

Controlling the program output

Example 1: Posting to a Slack Incoming Webhook

Example 2: Sending Alerts to Network Channel

HTTP/HTTPS Output

`main()`

`init()`

`SetInfo()`

`Info()`

`Init()`

`InitSchema()`

`Fields()`

`String()`

`Extract()`

`Open()`