falco.yaml

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

#############################
# Documentation style guide #
#############################

# This file uses a structured, helm-docs–friendly comment style:
# - Macro sections use banner headers to group topics.
# - Feature titles use "# [Maturity] `key`" and leaf docs use "# -- ..." lines.
# - Subsections use "################### `subkey`" and may include "--- [Usage]/[Suggestions]".
# - For booleans, add a "# -- Enable ..." line above "enabled:" flags.
# - Empty string values indicate "unset"; comments may clarify semantics.
# Note: This style is a superset of Helm-docs and is fully compatible with helm-docs,
# because this file is also consumed by the Falco Helm chart.

################
# 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 config files settings
#     config_files [Stable]
#     watch_config_files [Stable]
# Falco rules
#     rules_files [Stable]
#     rules [Incubating]
# Falco engine
#     engine [Stable]
# Falco captures
#     capture [Sandbox]
# Falco plugins
#     load_plugins [Stable]
#     plugins [Stable]
# Falco outputs settings
#     time_format_iso_8601 [Stable]
#     buffer_format_base64 [Stable]
#     priority [Stable]
#     json_output [Stable]
#     json_include_output_property [Stable]
#     json_include_message_property [Stable]
#     json_include_output_fields_property [Stable]
#     json_include_tags_property [Stable]
#     buffered_outputs [Stable]
#     rule_matching [Incubating]
#     outputs_queue [Stable]
#     append_output [Stable]
# Falco outputs channels
#     stdout_output [Stable]
#     syslog_output [Stable]
#     file_output [Stable]
#     http_output [Stable]
#     program_output [Stable]
# Falco exposed services
#     webserver [Stable]
# Falco logging / alerting / metrics related to software functioning (basic)
#     log_stderr [Stable]
#     log_syslog [Stable]
#     log_level [Stable]
#     libs_logger [Stable]
# Falco logging / alerting / metrics related to software functioning (advanced)
#     output_timeout [Stable]
#     syscall_event_timeouts [Stable]
#     syscall_event_drops [Stable] -> [CHANGE NOTICE] Automatic notifications will be simplified in Falco 0.38! If you depend on the detailed drop counters payload, use 'metrics.output_rule' along with 'metrics.kernel_event_counters_enabled' instead
#     metrics [Stable]
# Falco performance tuning (advanced)
#     base_syscalls [Stable]
# Falco libs
#     falco_libs [Incubating]

########################
# Config maturity tags #
########################

# As per features adoption and deprecation proposal we support 4 levels of configuration keys maturity:
# * Sandbox -> Experimental/alpha features, not recommended for production use, can be removed at any time without further notice.
# * Incubating -> Beta features, long-term support is not guaranteed.
# * Stable -> General Availability (GA) features for which long-term support is expected.
# * Deprecated -> Deprecated keys, soon to be removed.
#
# For more info, please take a look at the proposal: https://github.com/falcosecurity/falco/blob/master/proposals/20231220-features-adoption-and-deprecation.md.

################################
# 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
# `engine.kind`) are passed as command-line
# arguments with their corresponding values: falco -o "json_output=true"
# -o "log_level=debug" -o "engine.kind=kmod"
# 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_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).
#
# - SKIP_DRIVER_LOADER is used by the Falco fat image to skip the driver loading part.
#
# - FALCO_FRONTEND is useful when set to noninteractive to skip the dialog choice during
# the installation of Falco deb/rpm packages. This setting is somewhat similar to DEBIAN_FRONTEND.
#
# - FALCO_DRIVER_CHOICE is useful when set to kmod, ebpf, or modern_ebpf (matching the names
# used in engine.kind in the Falco config) during the installation of Falco deb/rpm packages.
# It skips the dialog choice but retains the driver configuration.
#
# - FALCOCTL_ENABLED is useful when set to 'no' during the installation of Falco deb/rpm packages,
# disabling the automatic artifacts followed by falcoctl.

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

# [Stable] `config_files`
#
# -- Allow to load additional configs files, beside the main one.
#
# Their loading is assumed to be made *after* main config file has been processed,
# exactly in the order they are specified.
# Therefore, loaded config files *can* override values from main config file.
# Also, nested include is not allowed, ie: included config files won't be able to include other config files.
#
# Like for 'rules_files', specifying a folder will load all the configs files present in it in a lexicographical order.
#
# 3 merge-strategies are available:
# `append` (default):
#   * existing sequence keys will be appended
#   * existing scalar keys will be overridden
#   * non-existing keys will be added
# `override`:
#   * existing keys will be overridden
#   * non-existing keys will be added
# `add-only`:
#   * existing keys will be ignored
#   * non-existing keys will be added
#
# Each item on the list can be either a yaml map or a simple string.
# The simple string will be interpreted as the config file path, and the `append` merge-strategy will be enforced.
# When the item is a yaml map instead, it will be of the form: `   path: foo\n   strategy: X`.
# When `strategy` is omitted, once again `append` is used.
#
# When a merge-strategy is enabled for a folder entry, all the included config files will use that merge-strategy.
config_files:
  - /etc/falco/config.d
  # Example of config file specified as yaml map with strategy made explicit.
  # - path: $HOME/falco_local_configs/
  #   strategy: add-only

# [Stable] `watch_config_files`
#
# -- Falco monitors configuration and rules 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 rules #
###############

# [Stable] `rules_files`
#
# -- The locations of rules files (or directories) to load.
#
# If the entry is a yaml file, it will be read directly. If the entry is a directory,
# all yaml 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.
#
# Since Falco 0.41 only files with .yml and .yaml extensions are considered,
# including directory contents. This means that you may specify directories that
# contain yaml files for rules and other files which will be ignored.
#
# NOTICE: Before Falco 0.38, this config key was `rules_file` (singular form),
# which is now deprecated in favor of `rules_files` (plural form).
rules_files:
  - /etc/falco/falco_rules.yaml
  - /etc/falco/falco_rules.local.yaml
  - /etc/falco/rules.d

# [Incubating] `rules`
#
# -- Falco rules can be enabled or disabled by name (with wildcards *) and/or by tag.
#
# This configuration is applied after all rules files have been loaded, including
# their overrides, and will take precedence over the enabled/disabled configuration
# specified or overridden in the rules files.
#
# The ordering matters and selections are evaluated in order. For instance, if you
# need to only enable a rule you would first disable all of them and then only
# enable what you need, regardless of the enabled status in the files.
#
# --- [Examples]
#
# Only enable two rules:
#
# rules:
#   - disable:
#       rule: "*"
#   - enable:
#       rule: Netcat Remote Code Execution in Container
#   - enable:
#       rule: Delete or rename shell history
#
# Disable all rules with a specific tag:
#
# rules:
#   - disable:
#       tag: network
#

################
# Falco engine #
################

# [Stable] `engine`
#
# -- Falco supports different engines to generate events.
# Choose the appropriate engine kind based on your system's configuration and requirements.
#
# Available engines:
# - `kmod`: Kernel Module
# - `modern_ebpf`: Modern eBPF (CO-RE eBPF probe)
# - `replay`: Replay a scap trace file
# - `nodriver`: No driver is injected into the system.
#   This is useful to debug and to run plugins with 'syscall' source.
#
# Only one engine can be specified in the `kind` key.
# Moreover, for each engine multiple options might be available,
# grouped under engine-specific configuration keys.
# Some of them deserve an in-depth description:
#
################### `buf_size_preset`
#
# 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.
#
################### `drop_failed_exit`
#
# Enabling this option in Falco allows it to drop failed system call exit events
# in the kernel drivers 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.
#
################### `cpus_for_each_buffer` (modern_ebpf only)
#
# The modern_ebpf driver in Falco utilizes the new BPF ring 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_ebpf 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
# `buf_size_preset` index. For instance, you can create a large shared
# syscall buffer of 512 MB (using 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 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_buffer`) can lower the memory footprint.
#
engine:
  # -- The kind of engine to use.
  kind: modern_ebpf
  # -- Engine-specific configuration for Kernel Module (kmod) engine.
  kmod:
    buf_size_preset: 4
    drop_failed_exit: false
  # -- Engine-specific configuration for Modern eBPF (modern_ebpf) engine.
  modern_ebpf:
    cpus_for_each_buffer: 2
    buf_size_preset: 4
    drop_failed_exit: false
  # -- Engine-specific configuration for replay engine which replays a capture file.
  replay:
    # -- Path to the capture file to replay (eg: /path/to/file.scap)
    capture_file: ""

##################
# Falco captures #
##################

# [Sandbox] `capture`
#
# -- Falco captures allow you to record events and their associated data for
# later analysis. This feature is particularly useful for debugging and
# forensics purposes.
#
# Captures operate in two modes:
#
# 1. `rules`: Captures events only when specific rules are triggered.
#    Enable capturing for individual rules by adding `capture: true` to the rule.
#
# 2. `all_rules`: Captures events when any enabled rule is triggered.
#
# When a capture starts, Falco records events from the moment the triggering rule
# fires until a stop condition is reached. Two stop conditions are available:
#
# - Time (per-rule, soft): determined by the rule's `capture_duration` if
#   specified, otherwise `default_duration` is used. If additional rules trigger
#   during an active capture, the deadline is extended accordingly (the longest
#   deadline wins). For this reason, the time limit has "at least" semantics:
#   the capture is guaranteed to last at least that long, but can last longer if
#   other rules keep matching.
#
# - File size (global, hard): `max_file_size_mb` applies to any capture,
#   regardless of which rule triggered it. Unlike the time limit, it cannot be
#   overridden or extended by rules: if a capture reaches this size, it stops.
#   N.B. The size check uses the dumper's compressed on-disk counter, which is
#   updated in chunks as zlib flushes its internal buffers. The effective file
#   size is therefore approximate and may overshoot the configured value by up
#   to one flush window. For this reason, avoid very small values (under a few
#   MB), which may be inaccurate, and consider tuning with a healthy margin.
#
# The first stop condition met wins (OR semantics). Once a stop condition is
# met, the capture stops and data is written to a file. Subsequent captures
# create new files with unique names. When a capture stops because of
# `max_file_size_mb`, Falco emits an internal INFO message so the truncation
# is visible in the configured outputs.
#
# Captured data is stored in files with a `.scap` extension, which can be
# analyzed later using:
#   falco -o engine.kind=replay -o replay.capture_file=/path/to/file.scap
#
# --- [Usage]
#
# Enable captures by setting `capture.enabled` to `true`.
#
# Configure `capture.path_prefix` to specify where capture files are stored.
# Falco generates unique filenames based on timestamp and event number for
# proper ordering. For example, with `path_prefix: /tmp/falco`, files are
# named like `/tmp/falco_00000001234567890_00000000000000042.scap`.
#
# Use `capture.mode` to choose between `rules` and `all_rules` modes.
#
# Set `capture.default_duration` to define the default capture duration
# in milliseconds. Optionally, set `capture.max_file_size_mb` to enforce a
# hard upper bound on the capture file size in MB (applies to any capture).
#
# --- [Suggestions]
#
# When using `mode: rules`, configure individual rules to enable capture by
# adding `capture: true` and optionally `capture_duration` to specific rules.
# For example:
#
# - rule: Suspicious File Access
#   desc: Detect suspicious file access patterns
#   condition: >
#     open_read and fd.name startswith "/etc/"
#   output: >
#     Suspicious file access (user=%user.name command=%proc.cmdline file=%fd.name)
#   priority: WARNING
#   capture: true
#   capture_duration: 10000  # Capture for 10 seconds when this rule triggers
#
# This configuration will capture events for 10 seconds whenever the
# "Suspicious File Access" rule is triggered, overriding the default duration.
capture:
  # -- Set to true to enable event capturing.
  enabled: false
  # -- Prefix for capture files. Falco appends a timestamp and event number to ensure unique filenames.
  path_prefix: /tmp/falco
  # -- Capture mode. Can be "rules" or "all_rules".
  mode: rules
  # -- Default capture duration in milliseconds if not specified in the rule.
  default_duration: 5000
  # -- Global hard cap on capture file size in MB (0 = unlimited).
  # This limit applies to any capture and cannot be overridden or extended by rules.
  # The check is approximate (see the section above): prefer values of at least a few MB.
  # max_file_size_mb: 100

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

# Plugins allow Falco to extend its functionality and leverage data sources such as
# Kubernetes audit logs or enable integration with other services in your ecosystem.
# This enables Falco to perform fast on-host detections beyond syscalls.
# Furthermore, plugins allow enriching existing data sources with additional metadata,
# and add other advanced capabilities to Falco.
#
# 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 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. This information is automatically extracted from
# the container runtime socket by the 'container' plugin.
# 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]

# [Stable] `load_plugins`
#
# -- List of plugins to load.
load_plugins: []

# [Stable] `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: container
    # For a summary of config option, see https://github.com/falcosecurity/plugins/tree/main/plugins/container#configuration
    library_path: libcontainer.so
    init_config:
      label_max_len: 100
      with_size: false
      # We use default config values for "engines" key.
# Configuration example for `k8saudit` plugin.
# - name: k8saudit
#   library_path: libk8saudit.so
#   init_config: ""
#   #   maxEventSize: 262144
#   #   webhookMaxBatchSize: 12582912
#   #   sslCertificate: /etc/falco/falco.pem
#   open_params: "http://:9765/k8s-audit"
# - name: json
#   library_path: libjson.so

# [Sandbox] `plugins_hostinfo`
#
# -- Control host info support for plugins.
# When `false`, it disables host info support for source plugins
# that DO NOT generate raw events from the libscap event table
# or for plugins that DO NOT parse raw events generated by drivers,
# effectively dropping the `proc-fs` hostPath volume requirement for them:
# https://github.com/falcosecurity/charts/blob/bd57711e7c8e00919ea288716e0d9d5fdad8867e/charts/falco/templates/pod-template.tpl#L302-L304
plugins_hostinfo: 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

# [Incubating] `buffer_format_base64`
#
# -- When enabled, Falco will output data buffer with base64 encoding. This is useful
# for encoding binary data that needs to be used over media designed to consume
# this format.
buffer_format_base64: 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

# [Incubating] `json_include_message_property`
#
# -- When using JSON output in Falco, you have the option to include the formatted
# rule output without timestamp or priority. For instance, if a rule specifies
# an "output" property like "Opened process %proc.name" the "message" field will
# only contain "Opened process bash" whereas the "output" field will contain more
# information.
json_include_message_property: false

# [Incubating] `json_include_output_fields_property`
#
# -- When using JSON output in Falco, you have the option to include the individual
# output fields for easier access. To reduce the logging volume, it is recommended
# to turn it off if it's not necessary for your use case.
json_include_output_fields_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`
#
# -- Global buffering option for output channels. When disabled, the output channel
# that supports buffering flushes the output buffer on every alert. This can lead to
# increased CPU usage but is useful when piping outputs to another process or script.
# Buffering is currently supported by `file_output`, `program_output`, and `stdout_output`.
# Some output channels may implement buffering strategies you cannot control.
# Additionally, this setting is separate from the `output_queue` option. The output queue
# sits between the rule engine and the output channels, while output buffering occurs
# afterward once the specific channel implementation outputs the formatted message.
buffered_outputs: false

# [Incubating] `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.
# -- Default value is `first`, which stops checking conditions of rules against upcoming event
# at the first matching rule.
rule_matching: first

# [Stable] `outputs_queue`
#
# -- Configure the output queue capacity.
#
# 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://uxlfoundation.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.
#
# In the case of an unbounded queue, if the available memory on the system is consumed,
# the Falco process would be OOM killed. When using this option and setting the capacity,
# the current event would be dropped, and the event loop would continue. This behavior mirrors
# kernel-side event drops when the buffer between kernel space and user space is full.
outputs_queue:
  # -- 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.
  capacity: 0

# [Sandbox] `append_output`
#
# -- Add information to the Falco output.
# With this setting you can add more information to the Falco output message, customizable by
# rule, tag or source.
# You can also add additional data that will appear in the output_fields property
# of JSON formatted messages but will not be part of the regular output message.
# This allows you to add custom fields that can help you filter your Falco events without
# polluting the message text.
#
# Each append_output entry has an optional `match` map which specifies which rules will be
# affected.
# `match`:
#   `rule`: append output only to a specific rule
#   `source`: append output only to a specific source
#   `tags`: append output only to rules that have all of the specified tags
# If none of the above are specified (or `match` is omitted)
# output is appended to all events.
# If more than one match condition is specified output will be appended to events
# that match all conditions.
# And several options to add output:
#   `extra_output`: add output to the Falco message
#   `extra_fields`: add new fields to the JSON output and structured output, which will not
#             affect the regular Falco message in any way. These can be specified as a
#             custom name with a custom format or as any supported field
#             (see: https://falco.org/docs/reference/rules/supported-fields/)
#   `suggested_output`: automatically append fields that are suggested to rules output
#
# Example:
#
# append_output:
#   - match:
#       source: syscall
#     extra_output: "on CPU %evt.cpu"
#     extra_fields:
#       - home_directory: "${HOME}"
#       - evt.hostname
#
# In the example above every event coming from the syscall source will get an extra message
# at the end telling the CPU number. In addition, if `json_output` is true, in the "output_fields"
# property you will find three new ones: "evt.cpu", "home_directory" which will contain the value of the
# environment variable $HOME, and "evt.hostname" which will contain the hostname.
#
# By default, we enable suggested_output for any source.
# This means that any extractor plugin that indicates some of its fields
# as suggested output formats, will see these fields in the output
# in the form "foo_bar=$foo.bar"
append_output:
  # -- Automatically append fields that are suggested to rules output.
  - suggested_output: true

# [Sandbox] `static_fields`
#
# Add statically defined fields to the Falco engine.
# Then, they can be used as normal rule conditions, by prepending `static.` prefix,
# eg: evt.type=open and static.foo=bar
# Also, if `append_output.suggested_output` is true,
# they'll be automatically appended to each rule output,
# in the form "static_foo=bar"
# static_fields:
#  foo: bar
#  foo2: ${env}

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

# Falco supports various output channels, such as syslog, stdout, file,
# 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`
#
# -- Send alerts to standard output.
stdout_output:
  # -- Enable sending alerts to standard output.
  enabled: true

# [Stable] `syslog_output`
#
# -- Send alerts to syslog.
syslog_output:
  # -- Enable sending alerts to syslog.
  enabled: true

# [Stable] `file_output`
#
# -- Send 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. Furthermore, the file will be closed and reopened if Falco receives
# the SIGUSR1 signal.
file_output:
  # -- Enable sending alerts to a file.
  enabled: false
  # -- If true, the file will be opened once and continuously written to.
  # If false, the file will be reopened for each output message.
  keep_alive: false
  # -- Path to the file where alerts will be appended.
  filename: ./events.txt

# [Stable] `http_output`
#
# -- Send alerts 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:
  # -- Enable sending alerts to an HTTP endpoint or webhook.
  enabled: false
  # -- URL of the remote server to send the alerts to.
  url: ""
  # -- User agent string to be used in the HTTP request.
  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 individual 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
  # -- Whether to compress the payload sent to the http server.
  compress_uploads: false
  # -- If true, the HTTP connection will be kept alive and reused.
  keep_alive: false
  # -- Maximum consecutive timeouts of libcurl to ignore.
  max_consecutive_timeouts: 5

# [Stable] `program_output`
#
# -- Send alerts 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
#
# The program will be re-spawned if Falco receives the SIGUSR1 signal.
program_output:
  # -- Enable sending alerts to another program or command.
  enabled: false
  # -- If true, the program will be started once and continuously written to,
  # with each output message on its own line.
  # If false, the program will be re-spawned for each output message.
  keep_alive: false
  # -- The program to execute.
  program: "jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX"

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

# [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.
#
webserver:
  # -- Enable the embedded 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
  # -- Port to listen on.
  listen_port: 8765
  # -- Address to listen on.
  # Can be an IPV4 or IPV6 address, defaults to IPV4.
  listen_address: 0.0.0.0
  # -- Endpoint to use for the health check.
  k8s_healthz_endpoint: /healthz
  # [Incubating] `webserver.prometheus_metrics_enabled`
  # -- Enable the metrics endpoint providing Prometheus values.
  # It is effective only if metrics.enabled is set to true.
  prometheus_metrics_enabled: false
  # -- Enable SSL.
  ssl_enabled: false
  # -- Path to the combined SSL certificate and key 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
  # ```
  ssl_certificate: /etc/falco/falco.pem

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

# [Stable] `log_stderr`
#
# 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.
#
# -- Send information logs to stderr.
# Note that these are just Falco lifecycle (and possibly error) logs.
# These are *not* alerts related to Falco outputs, so must not be considered
# as security notification logs!
log_stderr: true

# [Stable] `log_syslog`
#
# -- Send information logs to syslog.
# Note that these are just Falco lifecycle (and possibly error) logs.
# These are *not* alerts related to Falco outputs, so must not be considered
# as security notification logs!
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 to use "debug" and "trace" for production use.
libs_logger:
  # -- Enable logging from the underlying `libs` library.
  enabled: true
  # -- The minimum log level to include in the `libs` logs. Only logs of a certain
  # severity level or higher will be emitted. Supported levels: "fatal", "critical",
  # "error", "warning", "notice", "info", "debug", "trace".
  severity: info

#################################################################################
# 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:
  # -- The maximum number of consecutive timeouts without an event after which Falco will generate an alert.
  max_consecutives: 1000

# [Stable] `syscall_event_drops`
#
# Take actions when syscall events are dropped.
#
# -- 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).
#
# --- [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.
#
# --- [Notice]
#
# Automatic notifications will be simplified in future Falco versions!
# If you depend on the detailed drop counters payload, use 'metrics.output_rule'
# along with 'metrics.kernel_event_counters_enabled' instead.
syscall_event_drops:
  # -- The percentage of dropped syscall events with respect to the number of events in the last second
  # that will trigger the actions. A value in the range [0, 1]. If you want to be alerted on any drops,
  # set the threshold to 0.
  threshold: .1
  # -- The list of actions to take when the threshold is exceeded. Possible values are:
  # `ignore`, `log`, `alert`, `exit`. If the list is empty, no action is taken.
  actions:
    - log
    - alert
  # -- The rate at which log/alert messages are emitted is governed by a token bucket. The rate
  # corresponds to one message every `1/rate` seconds.
  # The default rate corresponds to one message every 30 seconds.
  rate: .03333
  # -- The maximum number of messages that can be emitted in a burst.
  max_burst: 1
  # -- For debugging/testing it is possible to simulate the drops. In this case the threshold does not apply.
  # This is useful to test the actions taken when drops are detected.
  simulate_drops: false

# [Stable] `metrics`
#
# Falco's `metrics` feature provides a comprehensive and flexible framework for
# capturing and exporting metrics.
#
# 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.
#
# If metrics are enabled, the web server can be configured to activate the
# corresponding Prometheus endpoint using `webserver.prometheus_metrics_enabled`.
# Prometheus output can be used in combination with the other output options.
#
# --- [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).
metrics:
  # -- Enable metrics collection and export.
  enabled: false
  # -- Interval at which stats are collected and emitted. This 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
  # 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.
  interval: 1h
  # Set `webserver.prometheus_metrics_enabled` for Prometheus output.
  # -- Emit stats as an output alert "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_rule: true
  # -- Append stats to a `jsonl` file. If empty, no file is written.
  # Use with caution in production as Falco does not automatically rotate the file.
  # It can be used in combination with `output_rule`, however enabling both is not typical.
  # e.g. output_file: /tmp/falco_stats.jsonl
  output_file: ""
  # -- Add counts for each rule to metrics output.
  rules_counters_enabled: true
  # -- Add CPU and memory usage metrics to metrics output.
  # 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 when
  # deployed as daemonset, 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. Finally, we emit the overall host
  # CPU and memory usages, along with the total number of processes and open file
  # descriptors (fds) on the host, obtained from the proc file system unrelated to
  # Falco's monitoring. These metrics help assess Falco's usage in relation to the
  # server's workload intensity.
  resource_utilization_enabled: true
  # -- Add Falco's internal state counters to metrics output.
  # Including added, removed threads or file descriptors (fds), and failed lookup,
  # store, or retrieve actions in relation to Falco's underlying process cache table
  # (a.k.a. the threadtable).
  state_counters_enabled: true
  # -- Add kernel side event and drop counters to metrics output.
  # This is 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.
  kernel_event_counters_enabled: true
  # -- Add kernel side event and drop counters per CPU to metrics output.
  # Enabling this option automatically enables `kernel_event_counters_enabled`.
  kernel_event_counters_per_cpu_enabled: false
  # -- Add statistics similar to `bpftool prog show` to metrics output.
  # This provides 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.
  libbpf_stats_enabled: true
  # -- Add custom plugins metrics to metrics output.
  # Please note that if the respective plugin has no metrics implemented,
  # there will be no metrics available.
  plugins_metrics_enabled: true
  # -- Add kernel side iterator event and drop counters to metrics output.
  # These counters reflect monotonic values since Falco's start and are exported at a
  # constant stats interval.
  kernel_iter_event_counters_enabled: true
  # -- Add jemalloc stats to metrics output.
  # This option requires that Falco is built with jemalloc support, otherwise
  # it will have no effect.
  jemalloc_stats_enabled: false
  # -- Convert memory metrics to megabytes.
  convert_memory_to_mb: true
  # -- Include fields with empty values in the metrics output.
  # Still, this option does not apply to high-level fields such as `n_evts` or `n_drops`;
  # they will always be included in the metrics output even if their value is empty.
  include_empty_values: false

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

# [Stable] `base_syscalls`, use with caution, read carefully
#
# -- 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.
#
# --- [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 of syscalls to trace in addition to the ones required by enabled rules.
  # This is useful in lowering CPU utilization and further tailoring Falco to
  # specific environments according to your threat model and budget constraints.
  # In the `base_syscalls.custom_set` list, it is possible either to use syscall names
  # (e.g. "mprotect") to be included or the negative notation ("!<syscall-name>")
  # for those to be excluded.
  # CAUTION: Misconfiguration of this setting may result in incomplete Falco event
  # logs, Falco being unable to trace events entirely, or Falco being unable to properly
  # garbage collect its internal process cache table.
  custom_set: []
  # -- When true, Falco will automatically add the minimal set of additional
  # syscalls needed to properly build up (e.g. "repair") its state engine and life-cycle
  # management. The repair mode can be enabled with an empty custom set.
  # This is an alternative to Falco's default state engine enforcement and is designed to be
  # the most system resource-friendly by activating the least number of additional syscalls
  # (outside of those enabled for enabled rules).
  repair: false
  # -- Enable monitoring for all events supported by Falco and used in rules and configs.
  # By default some events, such as `write`, are ignored (run `falco -i` to get
  # the full list) unless this option is true.
  # Enabling this option may negatively impact performance.
  all: false

##############
# Falco libs #
##############

# [Incubating] `falco_libs`
#
# -- Falco's performance and resource utilization can be fine-tuned by adjusting `falco_libs`
# parameters. For advanced users and specific use cases only.
#
falco_libs:
  # -- Maximum number of entries for Falco's internal threadtable (process cache).
  # The absolute maximum value can only be MAX UINT32.
  # Please note that Falco operates at a granular level, focusing on individual threads.
  # Falco rules reference the thread leader (i.e. the thread which spawned the thread)
  # as the process. The size of the threadtable should typically be much higher than the
  # number of currently alive processes. The default value should work well on modern
  # infrastructures and be sufficient to absorb bursts.
  # Reducing its size can help in better memory management, but as a consequence, your
  # process tree may be more frequently disrupted due to missing threads. You can explore
  # `metrics.state_counters_enabled` to measure how the internal state handling is performing,
  # and the fields called `n_drops_full_threadtable` or `n_store_evts_drops` will inform you
  # if you should increase this value for optimal performance.
  thread_table_size: 262144
  # -- Interval at which the automatic threads purging routine runs, in seconds.
  # Theautomatic threads purging is essential for Falco to remove stale inactive/dead threads
  # from its internal threadtable. The presence of this kind of threads could be the
  # results of multiple conditions, process exit events dropping or event re-ordering being
  # the most probable ones.
  # Reducing the interval can help in better memory management, but as a consequence, could
  # impact the CPU usage.
  thread_table_auto_purging_interval_s: 300
  # -- Amount of time after which a thread which has seen no events can be purged
  # through the automatic threads purging routine, in seconds.
  # As the purging happens only every `thread_table_auto_purging_interval_s`,
  # the max time a thread may linger is actually
  # `thread_table_auto_purging_interval_s` + `thread_table_auto_purging_thread_timeout_s`.
  # Reducing the interval can help in better memory management, but as a consequence, could
  # impact the CPU usage.
  thread_table_auto_purging_thread_timeout_s: 300
  # -- Set how many bytes are collected of each I/O buffer for 'syscall' events.
  # Use this option with caution since it can have a strong performance impact.
  snaplen: 80