Falco – Falco Rules

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: 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: 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: 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: 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.

Docs: Custom Ruleset

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

To write a custom rule for Falco from scratch, it is essential to understand the conditions that need to be met for Falco to trigger an alert. However, this task is complex as it requires considering the potential false positives and negatives arising from the rule.

Rules Placement

When adding a new rule to Falco, the first step is determining its placement. For instance, when loading syscall rules, Falco groups them per system call (evt.type) for faster matching and processes them later in sequential order, ensuring that two rules are not triggered simultaneously for the same evt.type field value. Consequently, more general rules should be positioned at the end of the rule set, while more specific rules should be placed at the beginning. This arrangement prevents general rules from capturing events that more specific rules should handle.

It's worth noting that Falco loads a set of predefined rules by default, followed by any custom rules located in the /etc/falco/rules.d directory. This configuration is specified in the /etc/falco/falco.yaml file, under the rules_files key, as follows:

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

It can nevertheless be adjusted to prioritize the rules in the rules.d directory, include different rule files or even add new directories. The customization options are flexible.

Considering this, it's important to remember that the default rules file includes reusable lists and macros that may help to create new rules. Therefore, you should carefully decide whether you want to delay the processing of those files or turn off a general rule that captures events intended for your custom rule. Alternatively, you can customize an existing rule within the rules.d directory by either rewriting the entire rule or using the "append" key to modify it.

If you are deploying Falco on a Kubernetes cluster, you will likely use Helm for the installation. In this scenario, instead of placing custom rules files directly in the /etc/falco/rules.d directory, you can add them to the values.yaml file provided to the helm command.

Locate the line customRules: {} in the values.yaml file and replace it with a configuration similar to the following:

customRules:
custom-rules.yaml: |-
- rule: Example rule
desc: ...
...
- rule: Example rule 2
...
more-custom-rules.yaml: |-
- rule: ...
...

That will instruct Helm to create as many rules files as you define here accessible inside the Falco Pods, under the directory /etc/falco/rules.d.

Finally, remember that keeping any previous ruleset and extending it, although sometimes recommended, is not enforced. It's acceptable to create a new ruleset by reorganizing the upstream rules, reordering and rewriting them, mixing in custom rules, splitting them into different sets and files, etc. Default Falco rules should be considered more of a guidance than a requirement to adopt.

To learn more about tweaking the Falco configuration to install new rules, see the documentation about default and local rules.

Rules Structure

Rules in Falco are defined using YAML syntax. Each rule is represented as an object in a YAML list, denoted by using a hyphen (-) before the first key in the rule. When creating a new rule, several essential keys should be included:

- rule:
desc:
condition:
output:
priority:
tags:

The rule key will indicate this is a rule to consider when processing the full set of rules. Without this key, Falco will ignore that entry. It has to be unique to create a new rule. Otherwise, it will overwrite any previously defined rule with the same value.
The desc key provides a detailed description of the rule's purpose, behavior, or the events it aims to detect. It helps with understanding the rule's intent and assists in documentation. Missing this key in the rule will make Falco show the error message:
```
LOAD_ERR_YAML_VALIDATE (Error validating internal structure of YAML file): Item has no mapping for key 'desc'
```
The priority key represents the severity of the alert triggered by Falco and corresponds with the well-known Syslog severities: emergency, alert, critical, error, warning, notice, informational, and debug. Missing this key in the rule will make Falco show the error message:
```
LOAD_ERR_YAML_VALIDATE (Error validating internal structure of YAML file): Item has no mapping for key 'priority'
```
The condition key defines the conditions that must be satisfied for the rule to trigger an alert. It consists of one or more expressions or statements that evaluate to true when the desired event occurs. Missing this key in the rule will make Falco show the error message:
```
LOAD_ERR_YAML_VALIDATE (Error validating internal structure of YAML file): Item has no mapping for key 'condition'
```
The output key determines the output format of the alert generated by the rule. It specifies how the alert should be formatted and what information should be included. Missing this key in the rule will make Falco show the error message:
```
LOAD_ERR_YAML_VALIDATE (Error validating internal structure of YAML file): Item has no mapping for key 'output'
```
The tags key categorizes the ruleset into groups of related rules. Although not mandatory when starting to write a rule, its use is highly recommended at a later stage for management purposes. For further information, refer to the [Tags section of the Style Guide of Falco Rules][/docs/rules/style-guide/#tags)

Refer to the Advanced Rule Syntax documentation to enhance your Falco rules further. The Style Guide of Falco Rules is also highly recommended to ensure your rules are easier to maintain and share with the community. These resources will provide you with valuable information about additional keys that can be used to augment and customize your Falco rules. Exploring these advanced options will allow you to expand the capabilities and effectiveness of your rules.

Building up the Condition

A condition in Falco acts as a checklist of requirements an event must meet to trigger the rule. To comprehend this evaluation process, it is essential to have a grasp of Boolean algebra. Ultimately, the condition will either evaluate to true, triggering the associated alert and bypassing the remaining rules, or evaluate to false, causing the next rule to be evaluated.

To achieve the desired effect, it is necessary to consider the Boolean operators: and, or, and not. These operators enable the condition to evaluate one or more situations and produce the desired outcome.

Each item on the checklist corresponds to a comparison involving the information in the syscall invocation and any relevant metadata that provides additional context. These comparisons employ operators such as =, !=, in, contains, and others. Refer to the section operators in the documentation for a more extensive list of available operators.

Before proceeding, it's recommended to refer to the condition syntax documentation, which provides detailed guidance on writing conditions. This resource will offer valuable information to ensure accurate and effective condition creation.

When constructing comparisons within conditions, an extensive set of fields is available for use. To simplify the process, you can consult this list, a handy cheat sheet for writing new rules.

Leveraging Macros and Lists

Additionally, the benefits of using macros and lists when writing rules are worth noting: leveraging these features allows for more straightforward and more concise rule creation while promoting the reuse of conditions that have been thoroughly tested. This approach enhances maintainability and efficiency in rule development.

Observe the following rule that detects when a bash shell is spawned inside a container:

- rule: Example Rule
condition: container.id != host and proc.name = bash and evt.type = execve and proc.pname exists and not proc.pname in (bash, docker)

could be rewritten as:

- rule: Example Rule
condition: container and proc.name = bash and spawned_process and proc.pname exists and not proc.pname in (bash, docker)

where container and spawned_process are macros already included in the default falco ruleset.

We can even go one step beyond adding a list of our own:

- list: allowed_binaries
items: [bash, docker]

Allowing us to rewrite the rule as:

- rule: Example Rule
condition: container and proc.name = bash and spawned_process and proc.pname exists and not proc.pname in allowed_binaries

Evaluation Priorities

When using the boolean operator or, it is crucial to include evaluation priorities by utilizing parentheses ( and ). These parentheses can be nested, and it is recommended to incorporate them within macros as they become part of larger conditions. Neglecting to use parentheses appropriately may lead to unexpected results that differ from the intended outcome.

Consider the following example to demonstrate the appropriate use of parentheses for setting evaluation priorities. Please note that the rule is quite extensive, indicated by the > symbol in YAML syntax, which signifies that it spans across multiple lines:

- rule: Example Rule
desc: An illustrative rule demonstrating evaluation priority with parentheses
condition: >
(syscall.type = execve and proc.name = "/bin/bash") or
(syscall.type = open and (fd.name contains "/etc/passwd" or fd.name contains "/etc/shadow"))
output: Log the relevant event.
priority: debug

In this example, the condition is structured to prioritize specific evaluations through the use of parentheses. It ensures that the rule triggers an alert when either the execve syscall type is matched and the process name is /bin/bash, or when the open syscall type is matched and the file descriptor name contains either /etc/passwd or /etc/shadow.

The proper placement of parentheses allows for accurate evaluation and ensures that the rule behaves as intended.

False Positives and Negatives

As previously explained, the condition key includes all the necessary checks an event must satisfy to trigger a specific rule. If there are too few checks in the condition, the rule might become too general and trigger frequently, potentially resulting in many false positives. These broad conditions can be useful for initial testing to ensure the rule is being reached and triggered. If the rule is never triggered, it suggests that a previous rule may be capturing the event before it reaches the intended rule.

An example of a rule that is too general is provided below:

- rule: Too General Rule
desc: An example of a rule that is an overly broad
condition: >
proc.name != "systemd" and evt.type = execve
output: Log the relevant event.
priority: debug

Another example would be a rule designed to monitor all activity generated by a specific process, like:

- rule: Monitor only a process named malicious
desc: Another example of an overly broad rule
condition: proc.name = malicious
output: The process %proc.name has used the syscall %evt.type
priority: debug

While these examples are useful for initial testing and gathering samples from certain commands, it's important to note that they are too general to yield reliable alerts. Instead, these broad examples are more likely to generate many false positives.

On the contrary, if a condition becomes overly specific or contradictory, it may fail to trigger when necessary, resulting in what is known as false negatives. To illustrate this point, consider the following example:

- rule: Example of a too-specific rule
...
condition: evt.type = execve and proc.name = malicious and proc.pid = 1
output: The process %proc.name has used the syscall %evt.type

The previous rule would seldom trigger because it relies on a specific PID (Process ID) for the process, which may only occur if executed within a container. While this example represents an extreme case, it highlights the consequences of being excessively specific when defining a condition. It emphasizes that overly specific conditions can lead to infrequent triggering or potentially not triggering in real-world scenarios.

Tuning a Rule by adding Exceptions to it

Adding exceptions to an existing Falco rule is a useful approach when you want to exclude specific scenarios from triggering that rule. Instead of using the and not operators in the condition, which can make the condition more complex and harder to understand, Falco provides a recommended method for handling exceptions.

To add exceptions to a rule, you can utilize the exceptions key within the rule definition. Specifying one or more conditions under the exceptions key allows you to define scenarios where the rule should not be triggered, even if the main condition is satisfied. This approach enhances the readability and maintainability of the rule by explicitly stating the exceptions separately.

Considering the following simplified rule:

- rule: Launch Privileged Container
desc: Detect the start of a privileged container.
condition: >
container_started and container
and container.privileged=true
output: Privileged container

One way of adding exceptions would be using the and not combination explained above:

- list: trusted_images
items: [docker.io/user/image1, quay.io/user/image2]
- rule: Launch Privileged Container
desc: Detect the start of a privileged container. Exceptions are made for known trusted images.
condition: >
container_started and container
and container.privileged=true
and not ( container.image.repository in (trusted_images) or
container.image.repository startswith registry.local/ )
output: Privileged container
priority: debug

The same example using the exceptions key:

- rule: Launch Privileged Container
desc: Detect the start of a privileged container.
condition: >
container_started and container
and container.privileged=true
output: Privileged container
priority: debug
exceptions:
- name: trusted_images
fields: [container.image.repository]
comps: [in]
values:
- [(trusted_images)]
- name: local_images
fields: [container.image.repository]
comps: [startswith]
values:
- [registry.local/]

While this may seem exaggerated for the provided exceptions, it highlights the true strength of the exceptions key when dealing with a larger number of variables. To demonstrate this, let's explore another example:

- rule: Launch Privileged Container
desc: Detect the start of a privileged container. Exceptions are made for known trusted images.
condition: >
container_started and container
and container.privileged=true
and not ((container.image.repository = registry.local/user/java-app and proc.name = /usr/bin/java ) or
(container.image.repository = docker.io/user/httpd and proc.name = /usr/bin/httpd ) or
(container.image.repository = quay.io/user/mysql and proc.name = /usr/bin/mysqld ))
output: Privileged container
priority: debug

Using the exceptions key it would now look like:

- rule: Launch Privileged Container
desc: Detect the start of a privileged container.
condition: >
container_started and container
and container.privileged=true
output: Privileged container
priority: debug
exceptions:
- name: trusted_images
fields: [container.image.repository, proc.name]
comps: [=,=]
values:
- [ registry.local/user/java-app, /usr/bin/java ]
- [ docker.io/user/httpd, /usr/bin/httpd ]
- [ quay.io/user/mysql, /usr/bin/mysqld ]

In the last rule provided, you can observe the inclusion of three exceptions, each containing two conditions. When the rules parser processes these conditions, it expands them into a format the rules engine can comprehend and utilize for evaluation. The values of the comps key may differ depending on the complexity of our conditions, and in some cases, multiple exception groups might be required to accommodate the rule's requirements.

Although this example remains relatively straightforward, it effectively demonstrates the capability and versatility of the exceptions key in handling various conditions and exceptions. This feature empowers you to create more sophisticated and specific rules while maintaining clarity and simplicity in the rule definition.

Selecting the System Call to monitor

The kernel provides many system calls that enable processes and libraries to interact with various system resources. These system calls cover a wide range of tasks, from starting new processes to opening files or network sockets, allowing us to gain insights into the actions attempted by processes.

To illustrate this, let's consider a fictional example. When given appropriate permissions, the following code can elevate privileges for a user executing it.

#define _GNU_SOURCE
#include <unistd.h>
#include <stdlib.h>
#include <sys/wait.h>
int main(int argc, char* argv[])
{
setresuid(0, 0, 0);
int pid = fork();
if (pid == 0) {
system("/bin/bash");
} else {
wait(&pid);
}
return 0;
}

To compile it, use your favorite Linux C compiler and set the SUID bit on the binary. We are doing a static compilation here to simplify our example here.

# cc -static -o /tmp/malicious malicious.c
# chmod u+s /tmp/malicious
# ls -l /tmp/malicious
-rwsr-xr-x 1 root root 16888 Jan 11:30 /tmp/malicious

Executed as a regular user, it should grant them a root shell:

$ /tmp/malicious
#

To observe what this program does once executed, we'll use strace:

$ strace /tmp/malicious
execve("/tmp/malicious", ["/tmp/malicious"], 0x7ffeaaf27690 /* 24 vars */) = 0
access("/etc/suid-debug", F_OK) = -1 ENOENT (No such file or directory)
arch_prctl(0x3001 /* ARCH_??? */, 0x7ffd8b18f0c0) = -1 EINVAL (Invalid argument)
brk(NULL) = 0x1f09000
brk(0x1f0a1c0) = 0x1f0a1c0
arch_prctl(ARCH_SET_FS, 0x1f09880) = 0
uname({sysname="Linux", nodename="vagrant", ...}) = 0
readlink("/proc/self/exe", "/tmp/malicious", 4096) = 14
brk(0x1f2b1c0) = 0x1f2b1c0
brk(0x1f2c000) = 0x1f2c000
mprotect(0x4bf000, 12288, PROT_READ) = 0
fcntl(0, F_GETFD) = 0
fcntl(1, F_GETFD) = 0
fcntl(2, F_GETFD) = 0
setresuid(0, 0, 0) = -1 EPERM (Operation not permitted)
clone(child_stack=NULL, flags=CLONE_CHILD_CLEARTID|CLONE_CHILD_SETTID|SIGCHLD, child_tidptr=0x1f09b50) = 18104
wait4(-1,

Pay attention to the Operation not permitted message when trying to run the command:

setresuid(0, 0, 0) = -1 EPERM (Operation not permitted)

The reason is that the command strace doesn't have enough permissions to let /tmp/malicious escalate privileges. But that doesn't mean we can't use that information to detect when a program tries it.

Let's now build a rule to detect that behavior.

- rule: Detect privilege escalation in /tmp
desc: Detect privilege escalationof binaries executed in /tmp
condition: >
evt.type = setresuid and proc.exepath startswith /tmp/
output: "The binary %proc.name has tried to escalate privileges: %evt.args"
priority: debug

When we execute our binary once more, the triggered rule should produce an output similar to the following:

Debug The binary malicious has tried to escalate privileges: ruid=0(root) euid=0(root) suid=0(root)

This rule may appear overly simplistic, potentially leading to numerous false positives or negatives. However, it illustrates how gaining a comprehensive understanding of binaries, their behaviors, and the associated threats can significantly improve the quality of our rule writing. By delving deeper into these aspects, we can craft more effective and accurate rules to enhance the detection capabilities of Falco.

Docs: Escaping Special Characters

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

In some cases, rules may need to contain special characters like (, spaces, etc. For example, you may need to look for a proc.name of (systemd), including the surrounding parentheses.

You can use " to capture these special characters. Here's an example:

- rule: Any Open Activity by Systemd
 desc: Detects all open events by systemd.
 condition: evt.type=open and proc.name="(systemd)" or proc.name=systemd
 output: "File opened by systemd | user=%user.name command=%proc.cmdline file=%fd.name
 priority: WARNING

When including items in lists, ensure that the double quotes are not interpreted from your YAML file by surrounding the quoted string with single quotes. Here's an example:

- list: systemd_procs
 items: [systemd, '"(systemd)"']

- rule: Any Open Activity by Systemd
 desc: Detects all open events by systemd.
 condition: evt.type=open and proc.name in (systemd_procs)
 output: "File opened by systemd | user=%user.name command=%proc.cmdline file=%fd.name"
 priority: WARNING

Docs: Style Guide of Falco Rules

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

This style guide only applies to Falco 0.36 and above.

Style Guide

Before diving in, read the sections on Falco rules Basics and Condition Syntax. Also, check out existing Falco Rules for best practices in writing rules.

In addition, the resources under references/rules provide complementary information. We highly recommend regularly revisiting each guide to stay up-to-date with the latest advancements of Falco.

A rule declaration is represented as a YAML object consisting of multiple keys. The suggested order for these keys is as follows:

- rule:
 desc:
 condition:
 output:
 priority:
 tags:

 ... other keys if applicable in no particular order

Naming

Choose a concise title that summarizes the essence of the rule's purpose. Rule's name must start with an upper-case letter. For macro and list, use lowercase_separated_by_underscores, for example, kernel_module_load.

Description

Aligning with Falco's Rules Maturity Framework, it is encouraged to not just include a longer description of what the rule detects but also to give advice on how to tune this rule and reduce possible noise. If applicable, elaborate on how to correlate the rule with other rules or data sources for incident response. However, keep them concise. The description should end with a period.

Condition Syntax

These recommendations prioritize performance impact while maintaining a consistent style for better understanding and easier customization. This approach ensures more manageable maintenance of the rules in the long run.

We explain the high-level principles using example rules or snippets.

Each upstream Falco rule must include an evt.type filter; otherwise, you will get a warning.

Rule no_evttype: warning (no-evttype):
proc.name=foo
did not contain any evt.type restriction, meaning that it will run for all event types.
This has a significant performance penalty. Consider adding an evt.type restriction if possible.

Prioritize the evt.type filter first; otherwise, you will get a warning. Falco buckets filters per evt.type for efficient rules matching through applying the rule's Abstract Syntax Tree (AST) to relevant event types only. A nice side effect is better readability as well.

Rule evttype_not_equals: warning (trailing-evttype):
evt.type!=execve
does not have all evt.type restrictions at the beginning of the condition,
or uses a negative match (i.e. "not"/"!=") for some evt.type restriction.
This has a performance penalty, as the rule can not be limited to specific event types.
Consider moving all evt.type restrictions to the beginning of the rule and/or
replacing negative matches with positive matches if possible.

To maintain performance, avoid mixing unrelated event types in one rule. Typically, only variants should be mixed together, for example: evt.type in (open, openat, openat2).
The best practice and requirement for upstream rules are to only define positive evt.type expressions. Using evt.type!=open, for example, would monitor each of the Supported Syscalls, resulting in a significant performance penalty. For more information, read the Adaptive Syscalls Selection in Falco blog post.
After the evt.type filter, place your positive expression filters to efficiently eliminate the most events step by step. An exception to this rule is the container macro, which can quickly eliminate many events. Therefore, the guiding principle of "divide and conquer" commonly used in database query recommendations, also applies to Falco's filter statements.

- macro: open_write
 condition: (evt.type in (open,openat,openat2) and evt.is_open_write=true and fd.typechar=`f` and fd.num>=0)
 ...

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

- rule: Detect release_agent File Container Escapes
 ...
 condition:
 open_write and container and fd.name endswith release_agent and (user.uid=0 or thread.cap_effective contains CAP_DAC_OVERRIDE) and thread.cap_effective contains CAP_SYS_ADMIN
 ...

Effective Falco rules should now already be in a good state. Additionally, use exclusionary statements mostly to filter out common anti-patterns and noise. Often, these statements are based on profiling. You will notice that many upstream rules provide an empty template macro for this purpose, which you can customize.

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

- list: known_drop_and_execute_containers
 items: []

- rule: Drop and execute new binary in container
 ...
 condition:
 spawned_process
 and container
 and proc.is_exe_upper_layer=true 
 and not container.image.repository in (known_drop_and_execute_containers)
 ...

Use existing macros for reusability purposes, if applicable (e.g. spawned_process macro).
Exercise caution when dealing with complicated nested statements in Falco rules, and ensure you use parentheses consistently to achieve the desired correct behavior. Remember, using too many parentheses does not cause any harm.
To avoid grammatical syntax errors or sub-optimal performance, refrain from combining or statements with negation. Instead, use or statements only for positive filters.


- macro: minerpool_https
 condition: (fd.sport="443" and fd.sip.name in (https_miner_domains))
 ...

condition: ... and ((minerpool_http) or (minerpool_https) or (minerpool_other))

Furthermore, it is preferred to use and not to consistently negate a positive sub-expression.
Avoid double-negation.

condition: ... and not fd.snet in (rfc_1918_addresses)

For operations involving string comparison, startswith or endswith should be preferred over contains whenever possible, as they are more efficient.
Whenever possible, try to avoid making a rule expression too long.
Upstream rules shall not contain any exceptions to ensure simpler rules and facilitate better adoption.

High-volume syscalls can increase CPU usage and cause kernel side event drops in production systems. When deploying Falco, consider trade-offs and experiments, particularly with I/O related syscalls, as it depends on your unique environment. The upstream rules do not include rules enabled by default regarding I/O syscalls.

Output Fields

Each rule must include output fields.

For the output fields, expect that each Falco release typically exposes new Supported Output Fields that can help you write more expressive rules and/or add more context to a rule for incident response.

Building upon the guide around writing rules with respect to Falco Outputs, when considering upstreaming your rule, core output fields relevant for this rule must be included. At the same time, we try to keep them to a minimum, and adopters can add more output fields as they see fit.

For each rule include the critical fields listed below related to process and user information, as well as the actual event type. For example, the tty field (terminal) can help determine if the process ran in an interactive shell. Additionally, examining the exepath alongside the process name provides insights into whether the binary might be located in more suspicious folders like tmp. Understanding the direct parent process is vital for basic process lineage analysis.

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

For rules involving only spawned_process, please also include %evt.arg.flags in the output fields. If a rule involves multiple syscalls beyond spawned_process, do not include %evt.arg.flags.

exe_flags=%evt.arg.flags

General tip: Refer to the Event Table Definitions for the evt.arg.* fields for each supported syscall, for which we extract and parse the arguments.

For network-related rules include:

connection=%fd.name lport=%fd.lport rport=%fd.rport fd_type=%fd.type fd_proto=fd.l4proto

For file-related rules include:

file=%fd.name

... and additional specialized fields from the raw args if applicable, such as newpath=%evt.arg.newpath for non-file descriptor events like symlinking or renaming. Alternatively, you can explore more recent fs.path.* variants to simplify the consistent logging of file or directory paths, even for non-file descriptor events. Previously, tapping into the raw args as described above was required for such events.

Supported Output Fields container.* retrieved from the container runtime socket
Supported Output Fields k8s.* also retrieved from the container runtime socket

All of these fields are incredibly crucial for effective incident response and play a vital role in determining the workload owner.

For specialized use cases, generic fields such as %container.ip or %container.cni.json can be further helpful for incident response, especially concerning non-network syscall related alerts in Kubernetes. These fields can be correlated, for example, with network proxy logs. Additionally, for certain rules, it can be important to traverse the parent process lineage for up to 7 levels. In some cases, instead of relying solely on the process name, it might be more effective to traverse the exepath, for example, proc.aexepath[2]. The process name and executable of the session leader (%proc.sname, %proc.sid.*) and process group leader (%proc.vpgid.*), or other specific process fields such as proc.is_exe_upper_layer, proc.is_exe_from_memfd or proc.is_vpgid_leader, can also hold considerable generic value for each rule. However, it is up to you as an adopter to decide.

We kindly ask you to add fields related to IDs later in your customization process to keep the upstream Falco output fields to a minimum. This is because there are many ID-related fields, such as %proc.pid %proc.ppid %proc.vpid %proc.pvpid %proc.sid %proc.vpgid .... You can explore the -p option for this purpose and add these fields to each rules' output fields.

Falco also supports outputting the output as a resolved string. Therefore, use a sentence style, first concisely re-iterating the rule's purpose, and then including the output field in parentheses after the = character, with its meaning explained before the = character, adhering to the snake_case variable naming convention.

output: "Read monitored file via directory traversal | file=%fd.name fileraw=%fd.nameraw gparent=%proc.aname[2] ggparent=%proc.aname[3] gggparent=%proc.aname[4] 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

Please refer to the relevant reference/rules section and the Basic Rules Guide for more information.

When considering upstreaming the rule to The Falco Project, the priority level shall not be set to DEBUG and instead shall be at a minimum of INFO.

Additional Information

Rule Types and Robustness

Some rules are more specific signatures, while others focus on behavior-based detection. When testing rules, it's essential to consider not only if the rule catches the intended attack or how much noise it could generate but also its robustness. Robustness refers to how easily an attacker can bypass the detection by making minor changes to their payload or approach. Exploring different approaches to catch an attack can help identify the most effective detection method.

Rules Loading

Refer to the up-to-date description in the falco.yaml file for rules_files to understand in which order rules are loaded. Keep in mind that Falco by default applies rules per event type on a "first match wins" basis. Starting from Falco Release 0.36.0, you have the option to modify the configuration to rule_matching: all. This change ensures that rules sharing the same event type cannot override each other, preventing inconsistent logging. Be aware, though, that this modification may lead to increased CPU usage.

Contributing Your Falco Rules

Refer to the Contributing page and the How to Share Your Falco Rules guide.

Docs: Accessing File System Paths in Falco Rules

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

Introduction

This section explains how the fields fs.path.* work and when they can be used.

Motivation

A variety of different syscalls take file system paths as arguments. However, there is little consistency in the fields that can access those file system paths. Depending on the syscall, the file system path might be available in evt.rawarg.path, evt.rawarg.pathname, evt.rawarg.name, fd.name, etc. This makes writing simple Falco rules that act on file system paths challenging because the field must depend on the syscall.

To help address this inconsistency, in Falco version 0.36, we added a new set of fields that normalize file system paths across various syscalls.

What Counts As A File System Path?

Lots of existing fields also refer to file system paths. For example, proc.exepath contains the file system path for an executable, and there are related fields proc.pexepath/proc.aexepath. container.mount.* fields all contain the file system paths for file systems mounted into a container.

The fs.path.* fields are only populated for syscalls generally related to reading, writing, or modifying some file system object and have a file system path as an argument. The goal is to have a single set of fields that can always be relied on to refer to those paths, compared to checking the widely varying per-event fields.

`fs.path.*` fields

The following fields are available for any syscall that operates on a file system path:

fs.path.name
fs.path.nameraw
fs.path.source
fs.path.sourceraw
fs.path.target
fs.path.targetraw

fs.path.name is for file operations that work on a path like open, unlink, rmdir, etc. For other file operations that have a source and target, like cp, symlink, link, mv, etc., there are fields fs.path.source and fs.path.target.

These convert relative paths to absolute paths when needed, using the thread's current working directory (cwd).

fs.path.nameraw/fs.path.sourceraw/fs.path.targetraw are like the above but do not convert relative paths to absolute paths. They always contain the original path, which may or may not be relative.

The fields only work for exit events and only return a value if the syscall succeeds.

The below tables show:

the specific syscalls that are are supported
the specific falco event identifiers are supported. The reason there are multiple event identifiers for the same syscall (e.g. MKDIR vs MKDIR_2) is that libs used to define new events every time we added/modified arguments to the event. Older applications using the older version of libs will use the older event identifier for the syscall name, while newer applications will use the newer event identifier.
the specific event fields that are mapped to fs.path.* fields

Single Argument File System Syscalls

Syscall	`fs.path.name` field
mkdir	`evt.rawarg.path`
mkdirat	`evt.rawarg.path`
rmdir	`evt.rawarg.path`
unlink	`evt.rawarg.path`
unlinkat	`evt.rawarg.name`
open	`evt.rawarg.name`
openat	`evt.rawarg.name`
openat2	`evt.rawarg.name`
fchmod	`fd.name`
fchmodat	`evt.rawarg.filename`
chmod	`evt.rawarg.filename`
chown	`evt.rawarg.path`
lchown	`evt.rawarg.path`
fchown	`fd.name`
fchownat	`evt.rawarg.pathname`
quotactl	`evt.rawarg.special`
umount	`evt.rawarg.name`
umount2	`evt.rawarg.name`

Source/Target File System Syscalls

Syscall	`fs.path.source` field	`fs.path.target` field
rename	`evt.rawarg.oldpath`	`evt.arg.newpath`
renameat	`evt.rawarg.oldpath`	`evt.arg.newpath`
renameat2	`evt.rawarg.oldpath`	`evt.arg.newpath`
link	`evt.arg.newpath`	`evt.rawarg.oldpath`
linkat	`evt.arg.newpath`	`evt.rawarg.oldpath`
symlink	`evt.arg.linkpath`	`evt.rawarg.target`
symlinkat	`evt.arg.linkpath`	`evt.rawarg.target`
mount	`evt.rawarg.dev`	`evt.rawarg.dir`

Example Rule Using `fs.path.*` Fields

Here is an example rule that allows monitoring a wide variety of different file related operations below a set of specifed root directories:

- list: file_operation_paths
items: [/tmp/example-dir]
- macro: file_operation
condition: (mkdir or rename or remove or open_write or create_symlink or evt.type in (link, linkat))
- rule: Any File Related Operation on Path
desc: Detect any file operation on a single path
condition: (fs.path.name pmatch (file_operation_paths) or fs.path.source pmatch (file_operation_paths) or fs.path.target pmatch (file_operation_paths)) and file_operation
output: >
Some File Related Operation on Path (evt.type=%evt.type path=%fs.path.name source=%fs.path.source
target=%fs.path.target %user.name=%user.name proc.cmdline=%proc.cmdline proc.pcmdline=%proc.pcmdline
container.id=%container.id container.name=%container.name image=%container.image.repository)
priority: DEBUG
source: syscall

Docs: Adoption of Falco Rules in Production

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

You have learned how to write Falco rules with best practices in mind and are now ready to deploy Falco to production and operationalize the rules. You might be wondering, "How do I go about this? How can I not only get the most value out of Falco but also maintain the rules effectively across varying infrastructure setups?"

The Falco Project has introduced the Rules Maturity Framework to precisely assist you in this process. The framework facilitates the adoption of the stable default rules more effectively while also providing guidance for custom rules. This framework ensures a smooth transition for adopters, whether they use rules generically or for specific use cases. A smooth adoption process is defined by making it easy for adopters to understand each rule and also gain an understanding of not just what the rule is doing, but also how beneficial it can be under various circumstances. As a result, adopters should have a clear idea of which rules can likely be adopted as-is versus which rules may require significant engineering efforts to evaluate and adopt.

To begin, allocate some time to assess the top cyber threats that are specific to your organization and require monitoring in place. One way to go about this is by exploring the already mentioned default rules tagged with the maturity level "stable" first. Explore the source falco_rules.yaml file and/or the latest rules overview document. These rules are designed to detect more universal system-level cyber threats, aligned with the Mitre Attack framework. Examples include remote code execution, generic malicious executions, container escapes, network pivots, privilege escalations, or credentials lifting. Some of these rules are also valuable for compliance-related monitoring.

Depending on your familiarity with security monitoring and detections, a little ramping up may be necessary to assess how useful a particular rule is in your environment. This includes determining the level of customization needed for a rule, for example, tuning out noise to reduce False Positives, and on the flip side, ensuring you are resilient against False Negatives. Additionally, it involves determining the appropriate output fields and the deployment configurations you need. It may also include finding the most optimal ways to maintain different deployment configurations across various infrastructures where you intend to deploy Falco. Existing descriptions of Falco rules, the official guides you've read, as well as the many blog posts hosted by The Falco Project, can provide you with further assistance.

High-level Phases

Newcomers to Falco will be encouraged to start by configuring their setup with introductory rules labeled as "Falco's default rules" (maturity_stable). These rules, which are currently based on syscall and container events, live in the established falco_rules.yaml file.
As users become more familiar with Falco and better understand their unique environments, they can gradually fine-tune the default rules to meet their specific requirements. Tuning rules goes hand in hand with assessing the performance overhead and adjusting Falco's configuration accordingly. This consideration is important to keep in mind as there are usually limitations to the budget allocated for security monitoring.
Once adopters have integrated the stable default rules with low false positives and acceptable performance consistently, they can add a next set of rules. This set may include rules with maturity_incubating or maturity_sandbox, offering more specific detections and/or broader monitoring, depending on the rule. The level of engineering effort needed to effectively use these rules at this stage is likely to increase.
Alongside each of these phases, creating custom rules early on often makes a lot of sense. For instance, enabling monitoring around sensitive files that are unique to your environment and ecosystem would be an appropriate example. The same approach could be applied to set up monitoring for crown jewel services with detailed knowledge of their usual execution patterns, and then set up alerts for any deviations.
Lastly, up until now, we focused on syscall and container event-based default rules. However, Falco also features a rich plugins system alongside plugin rules that you can explore to see if they are a fit for your ecosystem.

Disclaimer: The maturity level of the rules, however, does not directly reflect their potential for generating noise in the adopters' environment. This is due to the unique and constantly changing nature of each environment, especially in cloud environments, making it challenging to accurately predict the impact of rules.

Effective End-to-End Operationalization

Effective end-to-end operationalization is ideally accomplished through 24/7 detection triage by security analysts and pre-defined runbooks in the incident response workflows. This aspect is unique to your environment, and you can explore how Falco alerts can be augmented with additional data enrichments. Finding the right scope of monitoring can be achieved through experimentation. We also encourage you to find ways to perform continuous end-to-end testing or simulations to ensure the entire data pipeline is functional. This includes validating that Falco is logging the events, ensuring subsequent log transport to your end destination (which can be a data lake and compute platform or a SIEM) is working, and having effective triage and response mechanisms in place.

Continuous Learning and Maintenance

Falco continuously evolves and improves over time. This also means that for each Falco release, allocating time to explore the newest features can be beneficial. Furthermore, infrastructure, cloud environments, and your organization's applications keep evolving as well. Therefore, Falco rules require constant tuning and maintenance to ensure the desired monitoring quality.

Docs: Resolving Domain Names in Falco Rules

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

Introduction

This section explains how to use the fd.sip.name field and the related fd.{clr}ip.name fields in the default falco ruleset. For example:

- list: https_miner_domains
 items: [
 "ca.minexmr.com",
 "cn.stratum.slushpool.com",
 "de.minexmr.com",
 "fr.minexmr.com",
 "mine.moneropool.com",
 "mine.xmrpool.net",
 "pool.minexmr.com",
 "sg.minexmr.com",
 "stratum-eth.antpool.com",
 "stratum-ltc.antpool.com",
 "stratum-zec.antpool.com",
 "stratum.antpool.com",
 "xmr.crypto-pool.fr"
 ]

## Add rule based on crypto mining IOCs
- macro: minerpool_https
 condition: (fd.sport="443" and fd.sip.name in (https_miner_domains))

The fd.sip.name field and the related fd.{clr}ip.name fields behave differently than the other fields in the falco ruleset. See the following to learn more.

Resolve Domains First, Match IPs Later

When a rule contains a field fd.*ip.name, the domain names on the right hand side of the comparison (The foo.com in =foo.com or in (foo.com, bar.com)) are saved internally within the falco engine. The engine looks up the A records for those domains immediately and saves the set of returned IPs internally. This behavior prevents stalling the system call event loop to perform a blocking time-consuming DNS lookup at the time of the system call event.

Later, when a system call event is matched against the condition in the filter, the actual IP address associated with the system call event (the server IP for fd.sip.name, the client IP for fd.cip.name, etc) is compared against the previously looked up set of IPs for the domain name. The actual IP is compared against the set of resolved IPs, based on the comparison operator (=/!=/in, perhaps with a preceding not, etc) and results in a true/false result.

Here's an example. If a rule contains a predicate evt.type=connect and fd.sip.name=yahoo.com, the engine resolves the domain yahoo.com to a set of IPs (say 1.2.3.4, 1.2.3.5, 1.2.3.6) at the time the rules are loaded. Later, if a connect system call occurs (say to 1.2.3.5), the server side of the connection is compared against that set of IPs. Since the actual IP 1.2.3.5 is in the set of IPs for the domain yahoo.com, the rule snippet resolves to true.

The right hand side of a predicate can be in e.g. fd.sip.name in (yahoo.com, foo.com). In this case, the set of IPs for both domains are resolved and held. A later system call event will compare a given IP to the set of IPs for both sets of domains.

How Falco Engine Refreshes Domain/IP Mappings

The actual lookup of domains is done on a separate thread, to avoid stalling the main system call event loop. Additionally, the set of IPs for the domain is refreshed periodically, with the following strategy:

Domain names have a base refresh time of 10 seconds.
If after a refresh cycle the IP addresses haven't changed, the refresh timeout for that domain name is doubled until 320 seconds (~5mins).

There are a few caveats related to the use of fd.*ip.name fields that should be considered when writing Falco Rules.

The Right-Hand Side Must Be a Resolvable Domain Name

Since the right hand side of the predicate (e.g. the foo.com part of fd.sip.name=foo.com) is used to perform a DNS lookup at the time the rules are loaded, it must be a resolvable domain name. As a result, it's not possible to use domain substrings in conjunction with comparison operators like startswith/endswith/contains/etc. e.g. fd.sip.name contains company.com. Also, the falco engine must be able to resolve domain names in order for rules using fd.*ip.name fields to return accurate results.

Using fd.*ip.name Fields in Outputs

The fields fd.*ip.name can be used in rule outputs, but they will return meaningful values only when the actual IP for the system call event matches one of the IPs associated with the domain name for the field. For example, the following rule will display a meaningful output for ...IP=%fd.sip.name, as the rule condition has a positive comparison for a fd.sip.name field:

- rule: Connect to Yahoo
 desc: Detect Connects to yahoo.com IPs
 condition: evt.type=connect and fd.sip.name=yahoo.com
 output: Some connect to yahoo | command=%proc.cmdline connection=%fd.name IP=%fd.sip.name
 priority: INFO

In contrast, this rule will never display a meaningful output for ...IP=%fd.sip.name, as the comparison uses a negative match:

- rule: Connect to Anything but Yahoo
 desc: Detect Connects to anything other than yahoo.com IPs
 condition: evt.type=connect and fd.sip.name!=yahoo.com
 output: Some connect to something other than yahoo | command=%proc.cmdline connection=%fd.name IP=%fd.sip.name
 priority: INFO

The rule can match a given connect to an IP like 1.5.6.7, which is outside the known IPs 1.2.3.4/1.2.3.5/1.2.3.6 and generate an alert, but the value for %fd.sip.name will be blank. (The full connection information is still available in %fd.name, though.)

Limited Comparison Operators

Although the falco rules syntax supports a fairly wide set of comparison operators for IPs, including contains, the only allowed operators for fd.*ip.name fields are =/!=/in, with an optional preceding not.

Docs: Rule Format Version

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

From time to time, we make changes to the rules file format that are not backwards-compatible with older versions of Falco. Similarly, libsinsp and libscap may define new filtercheck fields, operators, etc. We want to denote that a given set of rules depends on the fields/operators from those libraries.

There are currently two optional fields in the falco rules file related to versioning:

Element	Description
`required_engine_version`	Used to track compatibility between rules content and the falco engine version.
`required_plugin_versions`	Used to track compatibility between rules content and plugin versions.

Falco Engine Versioning

The falco executable and the falco_engine C++ object now support returning a version number. The initial version is 2 (implying that prior versions were 1). We will increment this version whenever we make an incompatible change to the rules file format or add new fields, events or syntax elements to Falco. You can check the Falco engine version that your installation supports by running falco --version.

Falco Rules File Versioning

The Falco rules files included with Falco include a new top-level object, required_engine_version: N, that specifies the minimum engine version required to read this rules file. If not included, no version check is performed when reading the rules file. Here's an example:

# This rules file requires a falco with falco engine version 7.
- required_engine_version: 7

If a rules file has an engine_version greater than the Falco engine version, the rules file is loaded and an error is returned.

Official Rules File Versioning

If you use the official rules distributed by the Falco organization, they are versioned in the repository along with the relevant changelog.

Docs: IDE Support

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

For some Integrated Development Environment (IDE) Editors, there is support for falco rules files that allow for on-the-fly syntax checking and validation of rules content.

Emacs

For emacs, there is a Flycheck checker called flycheck-falco-rules:

Falco – Falco Rules

Docs: Basic Elements of Falco Rules

Rules

Conditions

Output

Priority

Advanced Rule Syntax

Macros

Lists

Visibility

Docs: Default and Local Rules Files

The configuration file

Falcoctl

Rules installed via the Helm chart

Use the rules embedded in the Falco image

Add custom rules with a configmap

Only use rules supplied via configmap

Docs: Condition Syntax

Operators

Logical operators

Comparison operators

pmatch operator

Transformers

Field evaluation (for right-hand side of comparisons)

Syscall event types, direction, and args

Syscall event context and metadata

Docs: Overriding Rules

Overview

Examples of using the override section

Append an item to a list

/etc/falco/falco_rules.yaml

/etc/falco/falco_rules.local.yaml

Replace items in a list

/etc/falco/falco_rules.yaml

/etc/falco/falco_rules.local.yaml

Append an item to a macro

/etc/falco/falco_rules.yaml

/etc/falco/falco_rules.local.yaml

Append and replace items in a rule

/etc/falco/falco_rules.yaml

/etc/falco/falco_rules.local.yaml

Enabling a disabled rule

/etc/falco/falco_rules.yaml

/etc/falco/falco_rules.local.yaml (incorrect usage example)

/etc/falco/falco_rules.yaml

/etc/falco/falco_rules.local.yaml (correct usage example)

Precedence of logical operators when appending

Appending to existing rules using append key (deprecated)

Redefining existing rules using append key (deprecated)

Examples of appending using append key (deprecated)

Appending to Lists

/etc/falco/falco_rules.yaml

/etc/falco/falco_rules.local.yaml

Appending to Macros

/etc/falco/falco_rules.yaml

/etc/falco/falco_rules.local.yaml

Appending to Rules

/etc/falco/falco_rules.yaml

/etc/falco/falco_rules.local.yaml

Append Exceptions to Rules

Docs: Rule Exceptions

Introduction

Rule Exceptions

Exception Syntax Shortcuts

Values are Optional

Fields/Comps Can Be a Single Value, Not a List

Comps is Optional

Appending Exception Values

Replacing Exception Values

Guidelines For Adding Exceptions To Rules

Be Specific

Use Set Operators

More Information

Docs: Controlling Rules

Disable Default Rules

Via Falco Configuration or Parameters

Via existing Macros

Via Custom Rule Definition

Rule Tags

Tags for Current Falco Ruleset

`pmatch` operator

Examples of using the `override` section

`/etc/falco/falco_rules.yaml`

`/etc/falco/falco_rules.local.yaml`

`/etc/falco/falco_rules.yaml`

`/etc/falco/falco_rules.local.yaml`

`/etc/falco/falco_rules.yaml`

`/etc/falco/falco_rules.local.yaml`

`/etc/falco/falco_rules.yaml`

`/etc/falco/falco_rules.local.yaml`

`/etc/falco/falco_rules.yaml`

`/etc/falco/falco_rules.local.yaml` (incorrect usage example)

`/etc/falco/falco_rules.yaml`

`/etc/falco/falco_rules.local.yaml` (correct usage example)

Appending to existing rules using `append` key (deprecated)

Redefining existing rules using `append` key (deprecated)

Examples of appending using `append` key (deprecated)

`/etc/falco/falco_rules.yaml`

`/etc/falco/falco_rules.local.yaml`

`/etc/falco/falco_rules.yaml`

`/etc/falco/falco_rules.local.yaml`

`/etc/falco/falco_rules.yaml`

`/etc/falco/falco_rules.local.yaml`

`fs.path.*` fields

Example Rule Using `fs.path.*` Fields