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: > bin_dir and evt.dir = < and open_write 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.
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: > bin_dir and evt.dir = < and open_write 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] - name: container_writer fields: [container.image.repository, fd.directory] comps: [=, startswith] - name: proc_filenames fields: [proc.name, fd.name] comps: [=, in] - 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
- 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 link together the list of field names with the list of field values that exist in the exception object.
proc_writer does not have any comps property, so the fields are directly compared to values using the = operator. container_writer does have a comps property, so each field will be compared to the corresponding exception items using the corresponding comparison operator.
proc_filenames uses the in comparison operator, so the corresponding values entry should be a list of filenames.
filenames differs from the others in that it names a single field and single comp operator. This changes how the exception condition snippet is constructed (see 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).
Exception values will most commonly be defined in rules with append: true. 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] append: true
A rule exception applies if for a given event, the fields in a rule.exception match all of the values in some exception.item. For example, if a program
apk writes to a file below
/usr/lib/alpine, the rule will not trigger, even if the condition is met.
Notice that an item in a values list can be a list. This allows building exceptions with operators like "in", "pmatch", etc. that work on a list of items. The item can also be a name of an existing list. If not present surrounding parantheses will be added.
Finally, note that the structure of the values property differs between the items where fields is a list of fields (proc_writer/container_writer/proc_filenames) and when it is a single field (procs_only). This changes how the condition snippet is constructed.
Exceptions: Syntatic Sugar For Conditions
For exception items where the fields property is a list of field names, each exception can be thought of as an implicit "and not (field1 cmp1 val1 and field2 cmp2 val2 and...)" appended to the rule's condition. For exception items where the fields property is a single field name, the exception can be thought of as an implict "and not field cmp (val1, val2, ...)". That's how exceptions are implemented--when parsing rules, exceptions are converted to a string like the above and appended to the condition, before the condition is compiled.
When a rule is parsed, the original condition is wrapped in an extra layer of parentheses and all exception values are appended to the condition. For example, using the example above, the resulting condition is:
(<Write below binary dir condition>) and not ( (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.directory startswith /usr/libexec/alpine) or (proc.name=apt and fd.name in (apt_files))) or (fd.filename in (python, go))))
The exceptions are effectively syntatic sugar that allows expressing sets of exceptions in a concise way.
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:
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
container.image.repository for a file-based exception, also include the file being acted on via
fd.directory, etc. Similarly, if a rule is container-specific, don't only include the image
container.image.repository, also include the processs 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
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.
The original proposal describes the benefits of exceptions in more detail.
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.