falco.yaml

#
# Copyright (C) 2022 The Falco Authors.
#
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

# File(s) or Directories containing Falco rules, loaded at startup.
# The name "rules_file" is only for backwards compatibility.
# If the entry is a file, it will be read directly. If the entry is a directory,
# every file in that directory will be read, in alphabetical order.
#
# falco_rules.yaml ships with the falco package and is overridden with
# every new software version. falco_rules.local.yaml is only created
# if it doesn't exist. If you want to customize the set of rules, add
# your customizations to falco_rules.local.yaml.
#
# The files will be read in the order presented here, so make sure if
# you have overrides they appear in later files.
rules_file:
  - /etc/falco/falco_rules.yaml
  - /etc/falco/falco_rules.local.yaml
  - /etc/falco/rules.d

#
# Plugins that are available for use. These plugins are not loaded by
# default, as they require explicit configuration to point to
# cloudtrail log files.
#

# To learn more about the supported formats for
# init_config/open_params for the cloudtrail plugin, see the README at
# https://github.com/falcosecurity/plugins/blob/master/plugins/cloudtrail/README.md.
plugins:
  - name: k8saudit
    library_path: libk8saudit.so
    init_config:
    #   maxEventSize: 262144
    #   webhookMaxBatchSize: 12582912
    #   sslCertificate: /etc/falco/falco.pem
    open_params: "http://:9765/k8s-audit"
  - name: cloudtrail
    library_path: libcloudtrail.so
    # see docs for init_config and open_params:
    # https://github.com/falcosecurity/plugins/blob/master/plugins/cloudtrail/README.md
  - name: json
    library_path: libjson.so

# Setting this list to empty ensures that the above plugins are *not*
# loaded and enabled by default. If you want to use the above plugins,
# set a meaningful init_config/open_params for the cloudtrail plugin
# and then change this to:
# load_plugins: [cloudtrail, json]
load_plugins: []

# Watch config file and rules files for modification.
# When a file is modified, Falco will propagate new config,
# by reloading itself.
watch_config_files: true

# If true, the times displayed in log messages and output messages
# will be in ISO 8601. By default, times are displayed in the local
# time zone, as governed by /etc/localtime.
time_format_iso_8601: false

# If "true", print falco alert messages and rules file
# loading/validation results as json, which allows for easier
# consumption by downstream programs. Default is "false".
json_output: false

# When using json output, whether or not to include the "output" property
# itself (e.g. "File below a known binary directory opened for writing
# (user=root ....") in the json output.
json_include_output_property: true

# When using json output, whether or not to include the "tags" property
# itself in the json output. If set to true, outputs caused by rules
# with no tags will have a "tags" field set to an empty array. If set to
# false, the "tags" field will not be included in the json output at all.
json_include_tags_property: true

# Send information logs to stderr and/or syslog Note these are *not* security
# notification logs! These are just Falco lifecycle (and possibly error) logs.
log_stderr: true
log_syslog: true

# Minimum log level to include in logs. Note: these levels are
# separate from the priority field of rules. This refers only to the
# log level of falco's internal logging. Can be one of "emergency",
# "alert", "critical", "error", "warning", "notice", "info", "debug".
log_level: info

# Falco is capable of managing the logs coming from libs. If enabled,
# the libs logger send its log records the same outputs supported by
# Falco (stderr and syslog). Disabled by default.
libs_logger:
  enabled: false
  # Minimum log severity to include in the libs logs. Note: this value is
  # separate from the log level of the Falco logger and does not affect it.
  # Can be one of "fatal", "critical", "error", "warning", "notice",
  # "info", "debug", "trace".
  severity: debug

# Minimum rule priority level to load and run. All rules having a
# priority more severe than this level will be loaded/run.  Can be one
# of "emergency", "alert", "critical", "error", "warning", "notice",
# "informational", "debug".
priority: debug

# Whether or not output to any of the output channels below is
# buffered. Defaults to false
buffered_outputs: false

# Falco uses a shared buffer between the kernel and userspace to pass
# system call information. When Falco detects that this buffer is
# full and system calls have been dropped, it can take one or more of
# the following actions:
#   - ignore: do nothing (default when list of actions is empty)
#   - log: log a DEBUG message noting that the buffer was full
#   - alert: emit a Falco alert noting that the buffer was full
#   - exit: exit Falco with a non-zero rc
#
# Notice it is not possible to ignore and log/alert messages at the same time.
#
# The rate at which log/alert messages are emitted is governed by a
# token bucket. The rate corresponds to one message every 30 seconds
# with a burst of one message (by default).
#
# The messages are emitted when the percentage of dropped system calls
# with respect the number of events in the last second
# is greater than the given threshold (a double in the range [0, 1]).
#
# For debugging/testing it is possible to simulate the drops using
# the `simulate_drops: true`. In this case the threshold does not apply.

syscall_event_drops:
  threshold: .1
  actions:
    - log
    - alert
  rate: .03333
  max_burst: 1
  simulate_drops: false

# Falco uses a shared buffer between the kernel and userspace to receive
# the events (eg., system call information) in userspace.
#
# Anyways, the underlying libraries can also timeout for various reasons.
# For example, there could have been issues while reading an event.
# Or the particular event needs to be skipped.
# Normally, it's very unlikely that Falco does not receive events consecutively.
#
# Falco is able to detect such uncommon situation.
#
# Here you can configure the maximum number of consecutive timeouts without an event
# after which you want Falco to alert.
# By default this value is set to 1000 consecutive timeouts without an event at all.
# How this value maps to a time interval depends on the CPU frequency.

syscall_event_timeouts:
  max_consecutives: 1000

# Enabling this option allows Falco to drop failed syscalls exit events
# in the kernel driver before the event is pushed onto the ring buffer.
# This can enable some small optimization both in CPU usage and ring buffer usage,
# possibly leading to lower number of event losses.
# Be careful: enabling it also means losing a bit of visibility on the system.
syscall_drop_failed_exit: false

# --- [Description]
#
# This is an index that controls the dimension of the syscall buffers.
# The syscall buffer is the shared space between Falco and its drivers where all the syscall events
# are stored.
# Falco uses a syscall buffer for every online CPU, and all these buffers share the same dimension.
# So this parameter allows you to control the size of all the buffers!
#
# --- [Usage]
#
# You can choose between different indexes: from `1` to `10` (`0` is reserved for future uses).
# Every index corresponds to a dimension in bytes:
#
# [(*), 1 MB, 2 MB, 4 MB, 8 MB, 16 MB, 32 MB, 64 MB, 128 MB, 256 MB, 512 MB]
#   ^    ^     ^     ^     ^     ^      ^      ^       ^       ^       ^
#   |    |     |     |     |     |      |      |       |       |       |
#   0    1     2     3     4     5      6      7       8       9       10
#
# As you can see the `0` index is reserved, while the index `1` corresponds to
# `1 MB` and so on.
#
# These dimensions in bytes derive from the fact that the buffer size must be:
# (1) a power of 2.
# (2) a multiple of your system_page_dimension.
# (3) greater than `2 * (system_page_dimension)`.
#
# According to these constraints is possible that sometimes you cannot use all the indexes, let's consider an
# example to better understand it:
# If you have a `page_size` of 1 MB the first available buffer size is 4 MB because 2 MB is exactly
# `2 * (system_page_size)` -> `2 * 1 MB`, but this is not enough we need more than `2 * (system_page_size)`!
# So from this example is clear that if you have a page size of 1 MB the first index that you can use is `3`.
#
# Please note: this is a very extreme case just to let you understand the mechanism, usually the page size is something
# like 4 KB so you have no problem at all and you can use all the indexes (from `1` to `10`).
#
# To check your system page size use the Falco `--page-size` command line option. The output on a system with a page
# size of 4096 Bytes (4 KB) should be the following:
#
# "Your system page size is: 4096 bytes."
#
# --- [Suggestions]
#
# Before the introduction of this param the buffer size was fixed to 8 MB (so index `4`, as you can see
# in the default value below).
# You can increase the buffer size when you face syscall drops. A size of 16 MB (so index `5`) can reduce
# syscall drops in production-heavy systems without noticeable impact. Very large buffers however could
# slow down the entire machine.
# On the other side you can try to reduce the buffer size to speed up the system, but this could
# increase the number of syscall drops!
# As a final remark consider that the buffer size is mapped twice in the process' virtual memory so a buffer of 8 MB
# will result in a 16 MB area in the process virtual memory.
# Please pay attention when you use this parameter and change it only if the default size doesn't fit your use case.

syscall_buf_size_preset: 4

############## [EXPERIMENTAL] Modern BPF probe specific ##############
# Please note: these configs regard only the modern BPF probe. They
# are experimental so they could change over releases.
#
# `cpus_for_each_syscall_buffer`
#
# --- [Description]
#
# This is an index that controls how many CPUs you want to assign to a single
# syscall buffer (ring buffer). By default, every syscall buffer is associated to
# 2 CPUs, so the mapping is 1:2. The modern BPF probe allows you to choose different
# mappings, for example, 1:1 would mean a syscall buffer for each CPU.
#
# --- [Usage]
#
# You can choose between different indexes: from `0` to `MAX_NUMBER_ONLINE_CPUs`.
# `0` is a special value and it means a single syscall buffer shared between all
# your online CPUs. `0` has the same effect as `MAX_NUMBER_ONLINE_CPUs`, the rationale
# is that `0` allows you to create a single buffer without knowing the number of online
# CPUs on your system.
# Let's consider an example to better understand it:
#
# Consider a system with 7 online CPUs:
#
#          CPUs     0  X  2  3  X  X  6  7  8  9   (X means offline CPU)
#
# - `1` means a syscall buffer for each CPU so 7 buffers
#
#          CPUs     0  X  2  3  X  X  6  7  8  9   (X means offline CPU)
#                   |     |  |        |  |  |  |
#       BUFFERs     0     1  2        3  4  5  6
#
# - `2` (Default value) means a syscall buffer for each CPU pair, so 4 buffers
#
#          CPUs     0  X  2  3  X  X  6  7  8  9   (X means offline CPU)
#                   |     |  |        |  |  |  |
#       BUFFERs     0     0  1        1  2  2  3
#
# Please note that we need 4 buffers, 3 buffers are associated with CPU pairs, the last
# one is mapped with just 1 CPU since we have an odd number of CPUs.
#
# - `0` or `MAX_NUMBER_ONLINE_CPUs` mean a syscall buffer shared between all CPUs, so 1 buffer
#
#          CPUs     0  X  2  3  X  X  6  7  8  9   (X means offline CPU)
#                   |     |  |        |  |  |  |
#       BUFFERs     0     0  0        0  0  0  0
#
# Moreover you can combine this param with `syscall_buf_size_preset`
# index, for example, you could create a huge single syscall buffer
# shared between all your online CPUs of 512 MB (so `syscall_buf_size_preset=10`).
#
# --- [Suggestions]
#
# We chose index `2` (so one syscall buffer for each CPU pair) as default because the modern bpf probe
# follows a different memory allocation strategy with respect to the other 2 drivers (bpf and kernel module).
# By the way, you are free to find the preferred configuration for your system.
# Considering a fixed `syscall_buf_size_preset` and so a fixed buffer dimension:
# - a lower number of buffers can speed up your system (lower memory footprint)
# - a too lower number of buffers could increase contention in the kernel causing an
#   overall slowdown of the system.
# If you don't have huge events throughputs and you are not experimenting with tons of drops
# you can try to reduce the number of buffers to have a lower memory footprint

modern_bpf:
  cpus_for_each_syscall_buffer: 2
############## [EXPERIMENTAL] Modern BPF probe specific ##############

# Falco continuously monitors outputs performance. When an output channel does not allow
# to deliver an alert within a given deadline, an error is reported indicating
# which output is blocking notifications.
# The timeout error will be reported to the log according to the above log_* settings.
# Note that the notification will not be discarded from the output queue; thus,
# output channels may indefinitely remain blocked.
# An output timeout error indeed indicate a misconfiguration issue or I/O problems
# that cannot be recovered by Falco and should be fixed by the user.
#
# The "output_timeout" value specifies the duration in milliseconds to wait before
# considering the deadline exceed.
#
# With a 2000ms default, the notification consumer can block the Falco output
# for up to 2 seconds without reaching the timeout.

output_timeout: 2000

# A throttling mechanism implemented as a token bucket limits the
# rate of Falco notifications. One rate limiter is assigned to each event
# source, so that alerts coming from one can't influence the throttling
# mechanism of the others. This is controlled by the following options:
#  - rate: the number of tokens (i.e. right to send a notification)
#    gained per second. When 0, the throttling mechanism is disabled.
#    Defaults to 0.
#  - max_burst: the maximum number of tokens outstanding. Defaults to 1000.
#
# With these defaults, the throttling mechanism is disabled.
# For example, by setting rate to 1 Falco could send up to 1000 notifications
# after an initial quiet period, and then up to 1 notification per second
# afterward. It would gain the full burst back after 1000 seconds of
# no activity.

outputs:
  rate: 0
  max_burst: 1000

# Where security notifications should go.
# Multiple outputs can be enabled.

syslog_output:
  enabled: true

# If keep_alive is set to true, the file will be opened once and
# continuously written to, with each output message on its own
# line. If keep_alive is set to false, the file will be re-opened
# for each output message.
#
# Also, the file will be closed and reopened if falco is signaled with
# SIGUSR1.

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

stdout_output:
  enabled: true

# Falco supports an embedded webserver and exposes the following endpoints:
# - /healthz: health endpoint useful for checking if Falco is up and running
#   (the endpoint name is configurable).
# - /versions: responds with a JSON object containing version numbers of the
#   internal Falco components (similar output as `falco --version -o json_output=true`).
# 
# # NOTE: the /versions endpoint is useful to other services (such as falcoctl)
# to retrieve info about a running Falco instance. Make sure the webserver is
# enabled if you're using falcoctl either locally or with Kubernetes.
# 
# The following options control the behavior of that webserver (enabled by default).
#
# The ssl_certificate is a combination SSL Certificate and corresponding
# key contained in a single file. You can generate a key/cert as follows:
#
# $ openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem
# $ cat certificate.pem key.pem > falco.pem
# $ sudo cp falco.pem /etc/falco/falco.pem
webserver:
  enabled: true
  # when threadiness is 0, Falco automatically guesses it depending on the number of online cores
  threadiness: 0
  listen_port: 8765
  k8s_healthz_endpoint: /healthz
  ssl_enabled: false
  ssl_certificate: /etc/falco/falco.pem

# Possible additional things you might want to do with program output:
#   - send to a slack webhook:
#         program: "jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX"
#   - logging (alternate method than syslog):
#         program: logger -t falco-test
#   - send over a network connection:
#         program: nc host.example.com 80

# If keep_alive is set to true, the program will be started once and
# continuously written to, with each output message on its own
# line. If keep_alive is set to false, the program will be re-spawned
# for each output message.
#
# Also, the program will be closed and reopened if falco is signaled with
# SIGUSR1.
program_output:
  enabled: false
  keep_alive: false
  program: "jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX"

http_output:
  enabled: false
  url: http://some.url
  user_agent: "falcosecurity/falco"
  # Tell Falco to not verify the remote server.
  insecure: false
  # Path to the CA certificate that can verify the remote server. 
  ca_cert: ""
  # Path to a specific file that will be used as the CA certificate store.
  ca_bundle: ""
  # Path to a folder that will be used as the CA certificate store. CA certificate need to be
  # stored as indivitual PEM files in this directory.
  ca_path: "/etc/ssl/certs"

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

# gRPC server using an unix socket
grpc:
  enabled: false
  bind_address: "unix:///run/falco/falco.sock"
  # when threadiness is 0, Falco automatically guesses it depending on the number of online cores
  threadiness: 0

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

# Container orchestrator metadata fetching params
metadata_download:
  max_mb: 100
  chunk_wait_us: 1000
  watch_freq_sec: 1


# base_syscalls ! Use with caution, read carefully !
#
# --- [Description]
#
# With this option you are in full control of the set of syscalls that
# Falco will enable in the kernel for active tracing.

# All syscalls and events from each enabled Falco rule are activated
# even when choosing this option. This option allows you to define a
# set of base syscalls that will be activated in addition to the
# syscalls defined in the rules.
#
# You may ask yourself why do we need to activate syscalls in addition to the rules?
#
# Falco requires a set of syscalls to build up state in userspace. This is because for
# example when spawning a new process or creating a network connection more than one syscall
# is involved. Furthermore, properties of a process during its life time can be modified
# by syscalls. Falco takes care of this by activating more syscalls than the ones defined
# in the rules and by managing a smart process cache table in userspace.
# Processes are purged when a process exits.
#
# Looking back to what this option does, it activates all syscalls from the rules
# (including resolved macros) and the ones specified here.
#
# This puts the end user in the driver seat to tell Falco what it needs, but if not used correctly
# Falco logs may be incomplete or wrong or Falco won't work at all. This option however can be
# very useful to lower CPU utilization and allowing you to tailor Falco to specific environments
# according to your organization's threat model and cost budget.
#
# !!! When NOT using this option, Falco defaults to adding a static (more verbose) set of syscalls
# in addition to the rules system calls Falco needs for its state engine build-up and life-cycle management.
#
# `base_syscalls.repair` is an experimental alternative to Falco's default state engine enforcement.
# `base_syscalls.repair` is designed to be the most resourceful option to ensure Falco runs correctly
# while activating a most minimal set of additional syscalls. The recommendations listed in the suggestions
# section is effectively what `base_syscalls.repair` is doing in an automated manner. `base_syscalls.repair`
# can be used with an empty custom set.
#
# --- [Usage]
#
# List of system calls names (<syscall-name>) plus negative ("!<syscall-name>") notation supported.
#
# base_syscalls.repair: <bool>
# base_syscalls.custom_set: [<syscall-name>, <syscall-name>, "!<syscall-name>"]
#
#
# --- [Suggestions]
#
# Here are a few recommendations that may help you.
# Setting `base_syscalls.repair: true` automates these recommendations for you.
#
# Consider to at minimum add the following syscalls regardless of the syscalls used in the rules.
#
# [clone, clone3, fork, vfork, execve, execveat, close]
#
# This is because some Falco fields for an execve* system call are retrieved
# from the associated `clone`, `clone3`, `fork`, `vfork` syscall when spawning a
# new process. The `close` system call is used to purge file descriptors from Falco's
# internal thread / process cache table and should always be added when you have
# rules around file descriptors.
# (e.g. open, openat, openat2, socket, connect, accept, accept4 ... and many more)
#
# When network syscalls are used in rules we recommend to at minimum set
#
# [clone, clone3, fork, vfork, execve, execveat, close, socket, bind, getsockopt]
#
# It turns out that while you can log `connect` or `accept*` syscalls without the
# socket system call, the log however would not contain the ip tuples.
# For `listen` and `accept*` system calls you also need the `bind` system call.
#
# Lastly, if you care about the correct `uid`, `gid` or `sid`, `pgid` of a process when the
# running process opens a file or makes a network connection, consider adding the following syscalls:
#
# setresuid, setsid, setuid, setgid, setpgid, setresgid, setsid, capset, chdir, chroot, fchdir
#
# We recommend to only exclude syscalls, e.g. "!mprotect" if you need a fast deployment update
# (overriding rules), else remove unwanted syscalls from the Falco rules.
#
# Passing `-o "log_level=debug"` to Falco's cmd args during a dry-run will print the
# final set of syscalls to STDOUT.

base_syscalls:
  repair: false
  custom_set: []