# # 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) # 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. 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` # # 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 ########################## # 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" # [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: "emergency", # "alert", "critical", "error", "warning", "notice", "info", "debug". 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 # [Experimental] `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 # # --- [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 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 # [Experimental] `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 (), negative ("!") # notation supported. # # Example: base_syscalls.custom_set: [, , # "!"] base_syscalls.repair: # # 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.