falco.yaml

# SPDX-License-Identifier: Apache-2.0
#
# Copyright (C) 2023 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.
#

################
# Config index #
################

# Here is an index of the configuration categories to help you navigate
# the Falco configuration file:
#
#     (Falco command-line arguments)
#     (Falco environment variables)
# Falco rules files
#     rules_file
# Falco plugins
#     load_plugins
#     plugins
# Falco config files
#     watch_config_files
# Falco outputs settings
#     time_format_iso_8601
#     priority
#     json_output
#     json_include_output_property
#     json_include_tags_property
#     buffered_outputs
#     outputs (throttling)
#     rule_matching
#     outputs_queue
# Falco outputs channels
#     stdout_output
#     syslog_output
#     file_output
#     http_output
#     program_output
#     grpc_output
# Falco exposed services
#     grpc
#     webserver
# Falco logging / alerting / metrics related to software functioning (basic)
#     log_stderr
#     log_syslog
#     log_level
#     libs_logger
# Falco logging / alerting / metrics related to software functioning (advanced)
#     output_timeout
#     syscall_event_timeouts
#     syscall_event_drops
#     metrics
# Falco performance tuning (advanced)
#     syscall_buf_size_preset
#     syscall_drop_failed_exit
#     base_syscalls
#     modern_bpf.cpus_for_each_syscall_buffer
# Falco cloud orchestration systems integration
#     metadata_download
#     (Guidance for Kubernetes container engine command-line args settings)


################################
# Falco command-line arguments #
################################

# To explore the latest command-line arguments supported by Falco for additional
# configuration, you can run `falco --help` in your terminal. You can also pass
# configuration options from this config file as command-line arguments by using
# the `-o` flag followed by the option name and value. In the following example,
# three config options (`json_output`, `log_level`, and
# `modern_bpf.cpus_for_each_syscall_buffer`) are passed as command-line
# arguments with their corresponding values: falco -o "json_output=true"
# -o "log_level=debug" -o "modern_bpf.cpus_for_each_syscall_buffer=4" 
# Please note that command-line arguments take precedence over the options
# specified in this config file.


###############################
# Falco environment variables #
###############################

# Customize Falco settings using environment variables:
#
# - "HOST_ROOT": Specifies the prefix to the underlying host `/proc` filesystem
#   when deploying Falco over a container with read-only host mounts instead of
#   directly on the host. Defaults to "/host". 
# - "FALCO_BPF_PROBE": Specify a custom path to the BPF object code file (`bpf`
#   driver). This is not needed for the modern_bpf driver. 
# - "FALCO_HOSTNAME": Customize the hostname output field logged by Falco by
#   setting the "FALCO_HOSTNAME" environment variable.
# - "FALCO_CGROUP_MEM_PATH": Specifies the file path holding the container
#   memory usage metric for the `metrics` feature. Defaults to
#   "/sys/fs/cgroup/memory/memory.usage_in_bytes" (Kubernetes).


#####################
# Falco rules files #
#####################

# [Stable] `rules_file`
#
# Falco rules can be specified using files or directories, which are loaded at
# startup. The name "rules_file" is maintained for backwards compatibility. If
# the entry is a file, it will be read directly. If the entry is a directory,
# all files within that directory will be read in alphabetical order.
#
# The falco_rules.yaml file ships with the Falco package and is overridden with
# every new software version. falco_rules.local.yaml is only created if it
# doesn't already exist.
#
# To customize the set of rules, you can add your modifications to any file.
# It's important to note that the files or directories are read in the order
# specified here. In addition, rules are loaded by Falco in the order they
# appear within each rule file.
#
# If you have any customizations intended to override a previous configuration,
# make sure they appear in later files to take precedence. On the other hand, if
# the conditions of rules with the same event type(s) have the potential to
# overshadow each other, ensure that the more important rule appears first. This
# is because rules are evaluated on a "first match wins" basis, where the first
# rule that matches the conditions will be applied, and subsequent rules will
# not be evaluated for the same event type.
#
# By arranging the order of files and rules thoughtfully, you can ensure that
# desired customizations and rule behaviors are prioritized and applied as
# intended.
# 
# With Falco 0.36 and beyond, it's now possible to apply multiple rules that match 
# the same event type, eliminating concerns about rule prioritization based on the 
# "first match wins" principle. However, enabling the `all` matching option may result
# in a performance penalty. We recommend carefully testing this alternative setting  
# before deploying it in production. Read more under the `rule_matching` configuration.
rules_file:
  - /etc/falco/falco_rules.yaml
  - /etc/falco/falco_rules.local.yaml
  - /etc/falco/rules.d

#################
# Falco plugins #
#################

# [Stable] `load_plugins` and `plugins`
#
# --- [Description]
#
# Falco plugins enable integration with other services in your ecosystem.
# They allow Falco to extend its functionality and leverage data sources such as
# Kubernetes audit logs or AWS CloudTrail logs. This enables Falco to perform
# fast on-host detections beyond syscalls and container events. The plugin
# system will continue to evolve with more specialized functionality in future
# releases.
#
# Please refer to the plugins repo at
# /~https://github.com/falcosecurity/plugins/blob/master/plugins/ for detailed
# documentation on the available plugins. This repository provides comprehensive
# information about each plugin and how to utilize them with Falco.
#
# Please note that if your intention is to enrich Falco syscall logs with fields
# such as `k8s.ns.name`, `k8s.pod.name`, and `k8s.pod.*`, you do not need to use
# the `k8saudit` plugin nor the `-k`/`-K` Kubernetes metadata enrichment. This
# information is automatically extracted from the container runtime socket. The
# `k8saudit` plugin is specifically designed to integrate with Kubernetes audit
# logs and is not required for basic enrichment of syscall logs with
# Kubernetes-related fields.
#
# --- [Usage]
#
# Disabled by default, indicated by an empty `load_plugins` list. Each plugin meant
# to be enabled needs to be listed as explicit list item.
# 
# For example, if you want to use the `k8saudit` plugin,
# ensure it is configured appropriately and then change this to: 
# load_plugins: [k8saudit, json]
load_plugins: []

# Customize subsettings for each enabled plugin. These settings will only be
# applied when the corresponding plugin is enabled using the `load_plugins`
# option.
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


######################
# Falco config files #
######################

# [Stable] `watch_config_files`
#
# Falco monitors configuration and rule files for changes and automatically
# reloads itself to apply the updated configuration when any modifications are
# detected. This feature is particularly useful when you want to make real-time
# changes to the configuration or rules of Falco without interrupting its
# operation or losing its state. For more information about Falco's state
# engine, please refer to the `base_syscalls` section.
watch_config_files: true


##########################
# Falco outputs settings #
##########################

# [Stable] `time_format_iso_8601`
#
# When enabled, Falco will display log and output messages with times in the ISO
# 8601 format. By default, times are shown in the local time zone determined by
# the /etc/localtime configuration.
time_format_iso_8601: false

# [Stable] `priority`
#
# Any rule with a priority level more severe than or equal to the specified
# minimum level will be loaded and run by Falco. This allows you to filter and
# control the rules based on their severity, ensuring that only rules of a
# certain priority or higher are active and evaluated by Falco. Supported
# levels: "emergency", "alert", "critical", "error", "warning", "notice",
# "info", "debug"
priority: debug

# [Stable] `json_output`
#
# When enabled, Falco will output alert messages and rules file
# loading/validation results in JSON format, making it easier for downstream
# programs to process and consume the data. By default, this option is disabled.
json_output: false

# [Stable] `json_include_output_property`
#
# When using JSON output in Falco, you have the option to include the "output"
# property itself in the generated JSON output. The "output" property provides
# additional information about the purpose of the rule. To reduce the logging
# volume, it is recommended to turn it off if it's not necessary for your use
# case.
json_include_output_property: true

# [Stable] `json_include_tags_property`
#
# When using JSON output in Falco, you have the option to include the "tags"
# field of the rules in the generated JSON output. The "tags" field provides
# additional metadata associated with the rule. To reduce the logging volume,
# if the tags associated with the rule are not needed for your use case or can
# be added at a later stage, it is recommended to turn it off.
json_include_tags_property: true

# [Stable] `buffered_outputs`
#
# Enabling buffering for the output queue can offer performance optimization,
# efficient resource usage, and smoother data flow, resulting in a more reliable
# output mechanism. By default, buffering is disabled (false).
buffered_outputs: false

# [Stable] `outputs`
#
# [DEPRECATED]
# This config is deprecated and it will be removed in Falco 0.37
#
# A throttling mechanism, implemented as a token bucket, can be used to control
# the rate of Falco outputs. Each event source has its own rate limiter,
# ensuring that alerts from one source do not affect the throttling of others.
# The following options control the mechanism:
#  - 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.
#
# For example, setting the rate to 1 allows Falco to send up to 1000
# notifications initially, followed by 1 notification per second. The burst
# capacity is fully restored after 1000 seconds of no activity.
#
# Throttling can be useful in various scenarios, such as preventing notification
# floods, managing system load, controlling event processing, or complying with
# rate limits imposed by external systems or APIs. It allows for better resource
# utilization, avoids overwhelming downstream systems, and helps maintain a
# balanced and controlled flow of notifications.
#
# With the default settings, the throttling mechanism is disabled.
outputs:
  rate: 0
  max_burst: 1000

# [Experimental] `rule_matching`
#
# The `rule_matching` configuration key's values are:
#  - `first`: Falco stops checking conditions of rules against upcoming event
#    at the first matching rule
#  - `all`: Falco will continue checking conditions of rules even if a matching 
#    one was already found
#
# Rules conditions are evaluated in the order they are defined in the rules files.
# For this reason, when using `first` as value, only the first defined rule will 
# trigger, possibly shadowing other rules.
# In case `all` is used as value, rules still trigger in the order they were
# defined.
# 
# Effectively, with this setting, it is now possible to apply multiple rules that match
# the same event type. This eliminates concerns about rule prioritization based on the
# "first match wins" principle. However, enabling the `all` matching option may result in
# a performance penalty. We recommend carefully testing this alternative setting before
# deploying it in production.
rule_matching: first

# [Experimental] `outputs_queue`
#
# Falco utilizes tbb::concurrent_bounded_queue for handling outputs, and this parameter
# allows you to customize the queue capacity. Please refer to the official documentation:
# https://oneapi-src.github.io/oneTBB/main/tbb_userguide/Concurrent_Queue_Classes.html.
# On a healthy system with optimized Falco rules, the queue should not fill up.
# If it does, it is most likely happening due to the entire event flow being too slow,
# indicating that the server is under heavy load.
# 
# Lowering the number of items can prevent memory from steadily increasing until the OOM
# killer stops the Falco process. We provide recovery actions to self-limit or self-kill
# in order to handle this situation earlier, similar to how we expose the kernel buffer size
# as a parameter. However, it will not address the root cause of the event pipe not keeping up.
# 
# `capacity`: the maximum number of items allowed in the queue is determined by this value. 
# Setting the value to 0 (which is the default) is equivalent to keeping the queue unbounded. 
# In other words, when this configuration is set to 0, the number of allowed items is effectively 
# set to the largest possible long value, disabling this setting.
# 
# `recovery`: strategy to follow when the queue becomes filled up. It applies only when the
# queue is bounded and there is still available system memory. In the case of an unbounded
# queue, if the available memory on the system is consumed, the Falco process would be
# OOM killed. The value `exit` is the default, `continue` does nothing special and `empty` 
# empties the queue and then continues.
outputs_queue:
  capacity: 0
  recovery: exit


##########################
# Falco outputs channels #
##########################

# Falco supports various output channels, such as syslog, stdout, file, gRPC,
# webhook, and more. You can enable or disable these channels as needed to
# control where Falco alerts and log messages are directed. This flexibility
# allows seamless integration with your preferred logging and alerting systems.
# Multiple outputs can be enabled simultaneously.

# [Stable] `stdout_output`
#
# Redirect logs to standard output.
stdout_output:
  enabled: true

# [Stable] `syslog_output`
#
# Send logs to syslog.
syslog_output:
  enabled: true

# [Stable] `file_output`
#
# When appending Falco alerts to a file, each new alert will be added to a new
# line. It's important to note that Falco does not perform log rotation for this
# file. If the `keep_alive` option is set to `true`, the file will be opened once
# and continuously written to, else the file will be reopened for each output
# message. Furthermore, the file will be closed and reopened if Falco receives
# the SIGUSR1 signal.
file_output:
  enabled: false
  keep_alive: false
  filename: ./events.txt

# [Stable] `http_output`
#
# Send logs to an HTTP endpoint or webhook.
#
# When using falcosidekick, it is necessary to set `json_output` to true, which is
# conveniently done automatically for you when using `falcosidekick.enabled=true`.
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"
  # Tell Falco to use mTLS
  mtls: false
  # Path to the client cert.
  client_cert: "/etc/ssl/certs/client.crt"
  # Path to the client key.
  client_key: "/etc/ssl/certs/client.key"
  # Whether to echo server answers to stdout
  echo: false

# [Stable] `program_output`
#
# Redirect the output to another program or command.
#
# 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. Furthermore, the program will be re-spawned if Falco receives
# the SIGUSR1 signal.
program_output:
  enabled: false
  keep_alive: false
  program: "jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX"

# [Stable] `grpc_output`
#
# Use gRPC as an output service.
#
# gRPC is a modern and high-performance framework for remote procedure calls
# (RPC). It utilizes protocol buffers for efficient data serialization. The gRPC
# output in Falco provides a modern and efficient way to integrate with other
# systems. By default the setting is turned off. Enabling this option stores
# output events in memory until they are consumed by a gRPC client. Ensure that
# you have a consumer for the output events or leave it disabled.
grpc_output:
  enabled: false


##########################
# Falco exposed services #
##########################

# [Stable] `grpc`
#
# Falco provides support for running a gRPC server using two main binding types:
# 1. Over the network with mandatory mutual TLS authentication (mTLS), which
#    ensures secure communication
# 2. Local Unix socket binding with no authentication. By default, the
#    gRPCserver in Falco is turned off with no enabled services (see
#    `grpc_output`setting). 
#
# To configure the gRPC server in Falco, you can make the following changes to
# the options:
#
# - Uncomment the relevant configuration options related to the gRPC server.
# - Update the paths of the generated certificates for mutual TLS authentication
#   if you choose to use mTLS.
# - Specify the address to bind and expose the gRPC server.
# - Adjust the threadiness configuration to control the number of threads and
#   contexts used by the server.
#
# Keep in mind that if any issues arise while creating the gRPC server, the
# information will be logged, but it will not stop the main Falco daemon.

# gRPC server using mTLS
# grpc:
#   enabled: true
#   bind_address: "0.0.0.0:5060"
#   # When the `threadiness` value is set to 0, Falco will automatically determine
#   # the appropriate number of threads based on the number of online cores in the system.
#   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 a local unix socket
grpc:
  enabled: false
  bind_address: "unix:///run/falco/falco.sock"
  # When the `threadiness` value is set to 0, Falco will automatically determine
  # the appropriate number of threads based on the number of online cores in the system.
  threadiness: 0

# [Stable] `webserver`
#
# Falco supports an embedded webserver that runs within the Falco process,
# providing a lightweight and efficient way to expose web-based functionalities
# without the need for an external web server. The following endpoints are
# exposed:
# - /healthz: designed to be used for checking the health and availability of
#   the Falco application (the name of the endpoint is configurable).
# - /versions: responds with a JSON object containing the version numbers of the
#   internal Falco components (similar output as `falco --version -o
#   json_output=true`).
#
# Please note that the /versions endpoint is particularly useful for other Falco
# services, such as `falcoctl`, to retrieve information about a running Falco
# instance. If you plan to use `falcoctl` locally or with Kubernetes, make sure
# the Falco webserver is enabled.
#
# The behavior of the webserver can be controlled with the following options,
# which are enabled by default:
#
# The `ssl_certificate` option specifies a combined SSL certificate and
# corresponding key that are 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 the `threadiness` value is set to 0, Falco will automatically determine
  # the appropriate number of threads based on the number of online cores in the system.
  threadiness: 0
  listen_port: 8765
  k8s_healthz_endpoint: /healthz
  ssl_enabled: false
  ssl_certificate: /etc/falco/falco.pem


##############################################################################
# Falco logging / alerting / metrics related to software functioning (basic) #
##############################################################################

# [Stable] `log_stderr` and `log_syslog`
#
# Falco's logs related to the functioning of the software, which are not related
# to Falco alert outputs but rather its lifecycle, settings and potential
# errors, can be directed to stderr and/or syslog.
log_stderr: true
log_syslog: true

# [Stable] `log_level`
#
# The `log_level` setting determines the minimum log level to include in Falco's
# logs related to the functioning of the software. This setting is separate from
# the `priority` field of rules and specifically controls the log level of
# Falco's operational logging. By specifying a log level, you can control the
# verbosity of Falco's operational logs. Only logs of a certain severity level
# or higher will be emitted. Supported levels: "emergency", "alert", "critical",
# "error", "warning", "notice", "info", "debug".
log_level: info

# [Stable] `libs_logger`
#
# The `libs_logger` setting in Falco determines the minimum log level to include
# in the logs related to the functioning of the software of the underlying
# `libs` library, which Falco utilizes. This setting is independent of the
# `priority` field of rules and the `log_level` setting that controls Falco's
# operational logs. It allows you to specify the desired log level for the `libs`
# library specifically, providing more granular control over the logging
# behavior of the underlying components used by Falco. Only logs of a certain
# severity level or higher will be emitted. Supported levels: "fatal",
# "critical", "error", "warning", "notice", "info", "debug", "trace". It is not
# recommended for production use.
libs_logger:
  enabled: false
  severity: debug


#################################################################################
# Falco logging / alerting / metrics related to software functioning (advanced) #
#################################################################################

# [Stable] `output_timeout`
#
# Generates Falco operational logs when `log_level=notice` at minimum
#
# A timeout error occurs when a process or operation takes longer to complete
# than the allowed or expected time limit. In the context of Falco, an output
# timeout error refers to the situation where an output channel fails to deliver
# an alert within a specified deadline. Various reasons, such as network issues,
# resource constraints, or performance bottlenecks can cause timeouts.
#
# The `output_timeout` parameter specifies the duration, in milliseconds, to
# wait before considering the deadline exceeded. By default, the timeout is set
# to 2000ms (2 seconds), meaning that the consumer of Falco outputs can block
# the Falco output channel for up to 2 seconds without triggering a timeout
# error.
#
# Falco actively monitors the performance of output channels. With this setting
# the timeout error can be logged, but please note that this requires setting
# Falco's operational logs `log_level` to a minimum of `notice`.
#
# It's important to note that Falco outputs will not be discarded from the
# output queue. This means that if an output channel becomes blocked
# indefinitely, it indicates a potential issue that needs to be addressed by the
# user.
output_timeout: 2000

# [Stable] `syscall_event_timeouts`
#
# Generates Falco operational logs when `log_level=notice` at minimum
#
# Falco utilizes a shared buffer between the kernel and userspace to receive
# events, such as system call information, in userspace. However, there may be
# cases where timeouts occur in the underlying libraries due to issues in
# reading events or the need to skip a particular event. While it is uncommon
# for Falco to experience consecutive event timeouts, it has the capability to
# detect such situations. You can configure the maximum number of consecutive
# timeouts without an event after which Falco will generate an alert, but please
# note that this requires setting Falco's operational logs `log_level` to a
# minimum of `notice`. The default value is set to 1000 consecutive timeouts
# without receiving any events. The mapping of this value to a time interval
# depends on the CPU frequency.
syscall_event_timeouts:
  max_consecutives: 1000

# [Stable] `syscall_event_drops`
#
# Generates "Falco internal: syscall event drop" rule output when `priority=debug` at minimum
#
# --- [Description]
#
# 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]). If you want to be alerted on any
# drops, set the threshold to 0.
#
# For debugging/testing it is possible to simulate the drops using the
# `simulate_drops: true`. In this case the threshold does not apply.
#
# --- [Usage]
#
# Enabled by default, but requires Falco rules config `priority` set to `debug`.
# Emits a Falco rule named "Falco internal: syscall event drop" as many times in
# a given time period as dictated by the settings. Statistics here reflect the
# delta in a 1s time period.
#
# If instead you prefer periodic metrics of monotonic counters at a regular
# interval, which include syscall drop statistics and additional metrics,
# explore the `metrics` configuration option.
syscall_event_drops:
  threshold: .1
  actions:
    - log
    - alert
  rate: .03333
  max_burst: 1
  simulate_drops: false

# [Stable] `metrics`
#
# Generates "Falco internal: metrics snapshot" rule output when `priority=info` at minimum
# By selecting `output_file`, equivalent JSON output will be appended to a file.
#
# periodic metric snapshots (including stats and resource utilization) captured
# at regular intervals
#
# --- [Warning]
#
# Due to a regression (/~https://github.com/falcosecurity/falco/issues/2821) some metrics
# like `falco.host_num_cpus` or `falco.start_ts` will not be available when you use
# source plugins (like k8saudit).
#
# --- [Description]
#
# Consider these key points about the `metrics` feature in Falco:
#
# - It introduces a redesigned stats/metrics system.
# - Native support for resource utilization metrics and specialized performance
#   metrics.
# - Metrics are emitted as monotonic counters at predefined intervals
#   (snapshots).
# - All metrics are consolidated into a single log message, adhering to the
#   established rules schema and naming conventions.
# - Additional info fields complement the metrics and facilitate customized
#   statistical analyses and correlations.
# - The metrics framework is designed for easy future extension.
#
# The `metrics` feature follows a specific schema and field naming convention.
# All metrics are collected as subfields under the `output_fields` key, similar
# to regular Falco rules. Each metric field name adheres to the grammar used in
# Falco rules. There are two new field classes introduced: `falco.` and `scap.`.
# The `falco.` class represents userspace counters, statistics, resource
# utilization, or useful information fields. The `scap.` class represents
# counters and statistics mostly obtained from Falco's kernel instrumentation
# before events are sent to userspace, but can include scap userspace stats as
# well.
#
# It's important to note that the output fields and their names can be subject
# to change until the metrics feature reaches a stable release.
# In addition, the majority of fields represent an instant snapshot, with the
# exception of event rates per second and drop percentage stats. These values
# are computed based on the delta between two snapshots.
#
# To customize the hostname in Falco, you can set the environment variable
# `FALCO_HOSTNAME` to your desired hostname. This is particularly useful in
# Kubernetes deployments where the hostname can be set to the pod name.
#
# --- [Usage]
#
# `enabled`: Disabled by default.
#
# `interval`: The stats interval in Falco follows the time duration definitions
# used by Prometheus.
# https://prometheus.io/docs/prometheus/latest/querying/basics/#time-durations
#
# Time durations are specified as a number, followed immediately by one of the
# following units:
# 
# ms - millisecond
# s - second
# m - minute
# h - hour
# d - day - assuming a day has always 24h
# w - week - assuming a week has always 7d
# y - year - assuming a year has always 365d
#
# Example of a valid time duration: 1h30m20s10ms
#
# A minimum interval of 100ms is enforced for metric collection. However, for
# production environments, we recommend selecting one of the following intervals
# for optimal monitoring:
# 
# 15m
# 30m
# 1h
# 4h
# 6h
#
# `output_rule`: To enable seamless metrics and performance monitoring, we
# recommend emitting metrics as the rule "Falco internal: metrics snapshot".
# This option is particularly useful when Falco logs are preserved in a data
# lake. Please note that to use this option, the Falco rules config `priority`
# must be set to `info` at a minimum.
#
# `output_file`: Append stats to a `jsonl` file. Use with caution in production
# as Falco does not automatically rotate the file. It can be used in combination
# with `output_rule`.
#
# `resource_utilization_enabled`: Emit CPU and memory usage metrics. CPU usage
# is reported as a percentage of one CPU and can be normalized to the total
# number of CPUs to determine overall usage. Memory metrics are provided in raw
# units (`kb` for `RSS`, `PSS` and `VSZ` or `bytes` for `container_memory_used`)
# and can be uniformly converted to megabytes (MB) using the
# `convert_memory_to_mb` functionality. In environments such as Kubernetes, it
# is crucial to track Falco's container memory usage. To customize the path of
# the memory metric file, you can create an environment variable named
# `FALCO_CGROUP_MEM_PATH` and set it to the desired file path. By default, Falco
# uses the file `/sys/fs/cgroup/memory/memory.usage_in_bytes` to monitor
# container memory usage, which aligns with Kubernetes'
# `container_memory_working_set_bytes` metric.
#
# `kernel_event_counters_enabled`: Emit kernel side event and drop counters, as
# an alternative to `syscall_event_drops`, but with some differences. These
# counters reflect monotonic values since Falco's start and are exported at a
# constant stats interval.
#
# `libbpf_stats_enabled`: Exposes statistics similar to `bpftool prog show`,
# providing information such as the number of invocations of each BPF program
# attached by Falco and the time spent in each program measured in nanoseconds.
# To enable this feature, the kernel must be >= 5.1, and the kernel
# configuration `/proc/sys/kernel/bpf_stats_enabled` must be set. This option,
# or an equivalent statistics feature, is not available for non `*bpf*` drivers.
# Additionally, please be aware that the current implementation of `libbpf` does
# not support granularity of statistics at the bpf tail call level.
#
# `include_empty_values`: When the option is set to true, fields with an empty
# numeric value will be included in the output. However, this rule does not
# apply to high-level fields such as `n_evts` or `n_drops`; they will always be
# included in the output even if their value is empty. This option can be
# beneficial for exploring the data schema and ensuring that fields with empty
# values are included in the output.
#
# todo: prometheus export option
# todo: syscall_counters_enabled option
metrics:
  enabled: false
  interval: 1h
  # Typically, in production, you only use `output_rule` or `output_file`, but not both. 
  # However, if you have a very unique use case, you can use both together.
  output_rule: true
  # output_file: /tmp/falco_stats.jsonl
  resource_utilization_enabled: true
  kernel_event_counters_enabled: true
  libbpf_stats_enabled: true
  convert_memory_to_mb: true
  include_empty_values: false


#######################################
# Falco performance tuning (advanced) #
#######################################

# [Stable] `syscall_buf_size_preset`
#
# --- [Description]
#
# The syscall buffer index determines the size of the shared space between Falco
# and its drivers. This shared space serves as a temporary storage for syscall
# events, allowing them to be transferred from the kernel to the userspace
# efficiently. The buffer size for each online CPU is determined by the buffer
# index, and each CPU has its own dedicated buffer. Adjusting this index allows
# you to control the overall size of the syscall buffers.
#
# --- [Usage]
#
# The index 0 is reserved, and each subsequent index corresponds to an
# increasing size in bytes. For example, index 1 corresponds to a size of 1 MB,
# index 2 corresponds to 2 MB, and so on:
#
# [(*), 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
#
#
# The buffer dimensions in bytes are determined by the following requirements:
# (1) a power of 2.
# (2) a multiple of your system_page_dimension.
# (3) greater than `2 * (system_page_dimension).
#
# The buffer size constraints may limit the usability of certain indexes. Let's
# consider an example to illustrate this:
#
# If your system has a page size of 1 MB, the first available buffer size would
# be 4 MB because 2 MB is exactly equal to 2 * (system_page_size), which is not
# sufficient as we require more than 2 * (system_page_size). In this example, it
# is evident that if the page size is 1 MB, the first index that can be used is 3.
#
# However, in most cases, these constraints do not pose a limitation, and all
# indexes from 1 to 10 can be used. You can check your system's page size using
# the Falco `--page-size` command-line option.
# 
# --- [Suggestions]
#
# The buffer size was previously fixed at 8 MB (index 4). You now have the
# option to adjust the size based on your needs. Increasing the size, such as to
# 16 MB (index 5), can reduce syscall drops in heavy production systems, but may
# impact performance. Decreasing the size can speed up the system but may
# increase syscall drops. It's important to note 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 virtual memory. Use this parameter with caution and only modify it
# if the default size is not suitable for your use case.
syscall_buf_size_preset: 4

# [Experimental] `syscall_drop_failed_exit`
#
# Enabling this option in Falco allows it to drop failed system call exit events
# in the kernel driver before pushing them onto the ring buffer. This
# optimization can result in lower CPU usage and more efficient utilization of
# the ring buffer, potentially reducing the number of event losses. However, it
# is important to note that enabling this option also means sacrificing some
# visibility into the system.
syscall_drop_failed_exit: false

# [Stable] `base_syscalls`, use with caution, read carefully
#
# --- [Description]
#
# This option configures the set of syscalls that Falco traces.
#
# --- [Falco's State Engine]
#
# Falco requires a set of syscalls to build up state in userspace. For example,
# when spawning a new process or network connection, multiple syscalls are
# involved. Furthermore, properties of a process during its lifetime can be
# modified by syscalls. Falco accounts for this by enabling the collection of
# additional syscalls than the ones defined in the rules and by managing a smart
# process cache table in userspace. Processes are purged from this table when a
# process exits.
#
# By default, with
#   ```
#   base_syscalls.custom_set = []
#   base_syscalls.repair = false
#   ```
# Falco enables tracing for a syscall set gathered: (1) from (enabled) Falco
#   rules (2) from a static, more verbose set defined in
#   `libsinsp::events::sinsp_state_sc_set` in
#   libs/userspace/libsinsp/events/sinsp_events_ppm_sc.cpp This allows Falco to
#   successfully build up it's state engine and life-cycle management.
#
# If the default behavior described above does not fit the user's use case for
# Falco, the `base_syscalls` option allows for finer end-user control of
# syscalls traced by Falco.
#
# --- [base_syscalls.custom_set]
#
# CAUTION: Misconfiguration of this setting may result in incomplete Falco event
# logs or Falco being unable to trace events entirely.
#
# `base_syscalls.custom_set` allows the user to explicitly define an additional
# set of syscalls to be traced in addition to the syscalls from each enabled
# Falco rule.
#
# This is useful in lowering CPU utilization and further tailoring Falco to
# specific environments according to your threat model and budget constraints.
#
# --- [base_syscalls.repair]
#
# `base_syscalls.repair` is an alternative to Falco's default state engine
# enforcement. When enabled, this option is designed to (1) ensure that Falco's
# state engine is correctly and successfully built-up (2) be the most system
# resource-friendly by activating the least number of additional syscalls
# (outside of those enabled for enabled rules)
#
# Setting `base_syscalls.repair` to `true` allows Falco to automatically
# configure what is described in the [Suggestions] section below.
#
# `base_syscalls.repair` can be enabled with an empty custom set, meaning with
# the following,
#   ```
#   base_syscalls.custom_set = []
#   base_syscalls.repair = true
#   ```
# Falco enables tracing for a syscall set gathered: (1) from (enabled) Falco
#   rules (2) from minimal set of additional syscalls needed to "repair" the
#   state engine and properly log event conditions specified in enabled Falco
#   rules
#
# --- [Usage]
#
# List of system calls names (<syscall-name>), negative ("!<syscall-name>")
# notation supported.
#
# Example: base_syscalls.custom_set: [<syscall-name>, <syscall-name>,
# "!<syscall-name>"] base_syscalls.repair: <bool>
#
# 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" -o "log_stderr=true" --dry-run` to Falco's cmd
# args will print the final set of syscalls to STDOUT.
#
# --- [Suggestions]
#
# NOTE: setting `base_syscalls.repair: true` automates the following suggestions
# for you.
#
# These suggestions are subject to change as Falco and its state engine evolve.
#
# For execve* events: Some Falco fields for an execve* syscall are retrieved
# from the associated `clone`, `clone3`, `fork`, `vfork` syscalls when spawning
# a new process. The `close` syscall is used to purge file descriptors from
# Falco's internal thread / process cache table and is necessary for rules
# relating to file descriptors (e.g. open, openat, openat2, socket, connect,
# accept, accept4 ... and many more)
#
# Consider enabling the following syscalls in `base_syscalls.custom_set` for
# process rules: [clone, clone3, fork, vfork, execve, execveat, close]
#
# For networking related events: While you can log `connect` or `accept*`
# syscalls without the socket syscall, the log will not contain the ip tuples.
# Additionally, for `listen` and `accept*` syscalls, the `bind` syscall is also
# necessary.
#
# We recommend the following as the minimum set for networking-related rules:
# [clone, clone3, fork, vfork, execve, execveat, close, socket, bind,
# getsockopt]
#
# Lastly, for tracking 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 to the above recommended syscall sets: ... setresuid,
# setsid, setuid, setgid, setpgid, setresgid, setsid, capset, chdir, chroot,
# fchdir ...
base_syscalls:
  custom_set: []
  repair: false

# [Stable] `modern_bpf.cpus_for_each_syscall_buffer`, modern_bpf only
#
# --- [Description]
#
# The modern_bpf driver in Falco utilizes the new BPF ring buffer, which has a
# different memory footprint compared to the current BPF driver that uses the
# perf buffer. The Falco core maintainers have discussed the differences and
# their implications, particularly in Kubernetes environments where limits need
# to be carefully set to avoid interference with the Falco daemonset deployment
# from the OOM killer. Based on guidance received from the kernel mailing list,
# it is recommended to assign multiple CPUs to one buffer instead of allocating
# a buffer for each CPU individually. This helps optimize resource allocation
# and prevent potential issues related to memory usage.
#
# This is an index that controls how many CPUs you want to assign to a single
# syscall buffer (ring buffer). By default, for modern_bpf 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, changing the value to `1`
# results in a 1:1 mapping and would mean one syscall buffer for each CPU (this
# is the default for the `bpf` driver).
#
# --- [Usage]
#
# You can choose an index from 0 to MAX_NUMBER_ONLINE_CPUs to set the dimension
# of the syscall buffers. The value 0 represents a single buffer shared among
# all online CPUs. It serves as a flexible option when the exact number of
# online CPUs is unknown. Here's an example to illustrate this:
#
# 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 in this example, there are 4 buffers in total. Three of the
# buffers are associated with pairs of CPUs, while the last buffer is mapped to
# a single CPU. This arrangement is necessary because 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 have the option to combine this parameter with
# `syscall_buf_size_preset` index. For instance, you can create a large shared
# syscall buffer of 512 MB (using syscall_buf_size_preset=10) that is
# allocated among all the online CPUs.
#
# --- [Suggestions]
#
# The default choice of index 2 (one syscall buffer for each CPU pair) was made
# because the modern bpf probe utilizes a different memory allocation strategy
# compared to the other two drivers (bpf and kernel module). However, you have
# the flexibility to experiment and find the optimal configuration for your
# system.
# 
# When considering a fixed syscall_buf_size_preset and a fixed buffer dimension:
# - Increasing this configs value results in lower number of buffers and you can
#   speed up your system and reduce memory usage
# - However, using too few buffers may increase contention in the kernel,
#   leading to a slowdown.
# 
# If you have low event throughputs and minimal drops, reducing the number of
# buffers (higher `cpus_for_each_syscall_buffer`) can lower the memory footprint.
modern_bpf:
  cpus_for_each_syscall_buffer: 2


#################################################
# Falco cloud orchestration systems integration #
#################################################

# [Stable] `metadata_download`
#
# When connected to an orchestrator like Kubernetes, Falco has the capability to
# collect metadata and enrich system call events with contextual data. The
# parameters mentioned here control the downloading process of this metadata.
#
# Please note that support for Mesos is deprecated, so these parameters
# currently apply only to Kubernetes. When using Falco with Kubernetes, you can
# enable this functionality by using the `-k` or `-K` command-line flag.
#
# However, it's worth mentioning that for important Kubernetes metadata fields
# such as namespace or pod name, these fields are automatically extracted from
# the container runtime, providing the necessary enrichment for common use cases
# of syscall-based threat detection.
#
# In summary, the `-k` flag is typically not required for most scenarios involving
# Kubernetes workload owner enrichment. The `-k` flag is primarily used when
# additional metadata is required beyond the standard fields, catering to more
# specific use cases, see https://falco.org/docs/reference/rules/supported-fields/#field-class-k8s.
metadata_download:
  max_mb: 100
  chunk_wait_us: 1000
  watch_freq_sec: 1

# [Stable] Guidance for Kubernetes container engine command-line args settings
#
# Modern cloud environments, particularly Kubernetes, heavily rely on
# containerized workload deployments. When capturing events with Falco, it
# becomes essential to identify the owner of the workload for which events are
# being captured, such as syscall events. Falco integrates with the container
# runtime to enrich its events with container information, including fields like
# `container.image.repository`, `container.image.tag`, ... , `k8s.ns.name`,
# `k8s.pod.name`, `k8s.pod.*` in the Falco output (Falco retrieves Kubernetes
# namespace and pod name directly from the container runtime, see
# https://falco.org/docs/reference/rules/supported-fields/#field-class-container).
#
# Furthermore, Falco exposes container events themselves as a data source for
# alerting. To achieve this integration with the container runtime, Falco
# requires access to the runtime socket. By default, for Kubernetes, Falco
# attempts to connect to the following sockets:
# "/run/containerd/containerd.sock", "/run/crio/crio.sock",
# "/run/k3s/containerd/containerd.sock". If you have a custom path, you can use
# the `--cri` option to specify the correct location.
#
# In some cases, you may encounter empty fields for container metadata. To
# address this, you can explore the `--disable-cri-async` option, which disables
# asynchronous fetching if the fetch operation is not completing quickly enough.
#
# To get more information on these command-line arguments, you can run `falco
# --help` in your terminal to view their current descriptions.
#
# !!! The options mentioned here are not available in the falco.yaml
# configuration file. Instead, they can can be used as a command-line argument
# when running the Falco command.