1054 lines
44 KiB
YAML
1054 lines
44 KiB
YAML
#
|
|
# 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 (<syscall-name>), negative ("!<syscall-name>")
|
|
# notation supported.
|
|
#
|
|
# Example: base_syscalls.custom_set: [<syscall-name>, <syscall-name>,
|
|
# "!<syscall-name>"] base_syscalls.repair: <bool>
|
|
#
|
|
# We recommend to only exclude syscalls, e.g. "!mprotect" if you need a fast
|
|
# deployment update (overriding rules), else remove unwanted syscalls from the
|
|
# Falco rules.
|
|
#
|
|
# Passing `-o "log_level=debug" -o "log_stderr=true" --dry-run` to Falco's cmd
|
|
# args will print the final set of syscalls to STDOUT.
|
|
#
|
|
# --- [Suggestions]
|
|
#
|
|
# NOTE: setting `base_syscalls.repair: true` automates the following suggestions
|
|
# for you.
|
|
#
|
|
# These suggestions are subject to change as Falco and its state engine evolve.
|
|
#
|
|
# For execve* events: Some Falco fields for an execve* syscall are retrieved
|
|
# from the associated `clone`, `clone3`, `fork`, `vfork` syscalls when spawning
|
|
# a new process. The `close` syscall is used to purge file descriptors from
|
|
# Falco's internal thread / process cache table and is necessary for rules
|
|
# relating to file descriptors (e.g. open, openat, openat2, socket, connect,
|
|
# accept, accept4 ... and many more)
|
|
#
|
|
# Consider enabling the following syscalls in `base_syscalls.custom_set` for
|
|
# process rules: [clone, clone3, fork, vfork, execve, execveat, close]
|
|
#
|
|
# For networking related events: While you can log `connect` or `accept*`
|
|
# syscalls without the socket syscall, the log will not contain the ip tuples.
|
|
# Additionally, for `listen` and `accept*` syscalls, the `bind` syscall is also
|
|
# necessary.
|
|
#
|
|
# We recommend the following as the minimum set for networking-related rules:
|
|
# [clone, clone3, fork, vfork, execve, execveat, close, socket, bind,
|
|
# getsockopt]
|
|
#
|
|
# Lastly, for tracking the correct `uid`, `gid` or `sid`, `pgid` of a process
|
|
# when the running process opens a file or makes a network connection, consider
|
|
# adding the following to the above recommended syscall sets: ... setresuid,
|
|
# setsid, setuid, setgid, setpgid, setresgid, setsid, capset, chdir, chroot,
|
|
# fchdir ...
|
|
base_syscalls:
|
|
custom_set: []
|
|
repair: false
|
|
|
|
# [Stable] `modern_bpf.cpus_for_each_syscall_buffer`, modern_bpf only
|
|
#
|
|
# --- [Description]
|
|
#
|
|
# The modern_bpf driver in Falco utilizes the new BPF ring buffer, which has a
|
|
# different memory footprint compared to the current BPF driver that uses the
|
|
# perf buffer. The Falco core maintainers have discussed the differences and
|
|
# their implications, particularly in Kubernetes environments where limits need
|
|
# to be carefully set to avoid interference with the Falco daemonset deployment
|
|
# from the OOM killer. Based on guidance received from the kernel mailing list,
|
|
# it is recommended to assign multiple CPUs to one buffer instead of allocating
|
|
# a buffer for each CPU individually. This helps optimize resource allocation
|
|
# and prevent potential issues related to memory usage.
|
|
#
|
|
# This is an index that controls how many CPUs you want to assign to a single
|
|
# syscall buffer (ring buffer). By default, for modern_bpf every syscall buffer
|
|
# is associated to 2 CPUs, so the mapping is 1:2. The modern BPF probe allows
|
|
# you to choose different mappings, for example, changing the value to `1`
|
|
# results in a 1:1 mapping and would mean one syscall buffer for each CPU (this
|
|
# is the default for the `bpf` driver).
|
|
#
|
|
# --- [Usage]
|
|
#
|
|
# You can choose an index from 0 to MAX_NUMBER_ONLINE_CPUs to set the dimension
|
|
# of the syscall buffers. The value 0 represents a single buffer shared among
|
|
# all online CPUs. It serves as a flexible option when the exact number of
|
|
# online CPUs is unknown. Here's an example to illustrate this:
|
|
#
|
|
# Consider a system with 7 online CPUs:
|
|
#
|
|
# CPUs 0 X 2 3 X X 6 7 8 9 (X means offline CPU)
|
|
#
|
|
# - `1` means a syscall buffer for each CPU so 7 buffers
|
|
#
|
|
# CPUs 0 X 2 3 X X 6 7 8 9 (X means offline CPU)
|
|
# | | | | | | |
|
|
# BUFFERs 0 1 2 3 4 5 6
|
|
#
|
|
# - `2` (Default value) means a syscall buffer for each CPU pair, so 4 buffers
|
|
#
|
|
# CPUs 0 X 2 3 X X 6 7 8 9 (X means offline CPU)
|
|
# | | | | | | |
|
|
# BUFFERs 0 0 1 1 2 2 3
|
|
#
|
|
# Please note that in this example, there are 4 buffers in total. Three of the
|
|
# buffers are associated with pairs of CPUs, while the last buffer is mapped to
|
|
# a single CPU. This arrangement is necessary because we have an odd number of
|
|
# CPUs.
|
|
#
|
|
# - `0` or `MAX_NUMBER_ONLINE_CPUs` mean a syscall buffer shared between all
|
|
# CPUs, so 1 buffer
|
|
#
|
|
# CPUs 0 X 2 3 X X 6 7 8 9 (X means offline CPU)
|
|
# | | | | | | |
|
|
# BUFFERs 0 0 0 0 0 0 0
|
|
#
|
|
# Moreover, you have the option to combine this parameter with
|
|
# `syscall_buf_size_preset` index. For instance, you can create a large shared
|
|
# syscall buffer of 512 MB (using syscall_buf_size_preset=10) that is
|
|
# allocated among all the online CPUs.
|
|
#
|
|
# --- [Suggestions]
|
|
#
|
|
# The default choice of index 2 (one syscall buffer for each CPU pair) was made
|
|
# because the modern bpf probe utilizes a different memory allocation strategy
|
|
# compared to the other two drivers (bpf and kernel module). However, you have
|
|
# the flexibility to experiment and find the optimal configuration for your
|
|
# system.
|
|
#
|
|
# When considering a fixed syscall_buf_size_preset and a fixed buffer dimension:
|
|
# - Increasing this configs value results in lower number of buffers and you can
|
|
# speed up your system and reduce memory usage
|
|
# - However, using too few buffers may increase contention in the kernel,
|
|
# leading to a slowdown.
|
|
#
|
|
# If you have low event throughputs and minimal drops, reducing the number of
|
|
# buffers (higher `cpus_for_each_syscall_buffer`) can lower the memory footprint.
|
|
modern_bpf:
|
|
cpus_for_each_syscall_buffer: 2
|
|
|
|
|
|
#################################################
|
|
# Falco cloud orchestration systems integration #
|
|
#################################################
|
|
|
|
# [Stable] `metadata_download`
|
|
#
|
|
# When connected to an orchestrator like Kubernetes, Falco has the capability to
|
|
# collect metadata and enrich system call events with contextual data. The
|
|
# parameters mentioned here control the downloading process of this metadata.
|
|
#
|
|
# Please note that support for Mesos is deprecated, so these parameters
|
|
# currently apply only to Kubernetes. When using Falco with Kubernetes, you can
|
|
# enable this functionality by using the `-k` or `-K` command-line flag.
|
|
#
|
|
# However, it's worth mentioning that for important Kubernetes metadata fields
|
|
# such as namespace or pod name, these fields are automatically extracted from
|
|
# the container runtime, providing the necessary enrichment for common use cases
|
|
# of syscall-based threat detection.
|
|
#
|
|
# In summary, the `-k` flag is typically not required for most scenarios involving
|
|
# Kubernetes workload owner enrichment. The `-k` flag is primarily used when
|
|
# additional metadata is required beyond the standard fields, catering to more
|
|
# specific use cases, see https://falco.org/docs/reference/rules/supported-fields/#field-class-k8s.
|
|
metadata_download:
|
|
max_mb: 100
|
|
chunk_wait_us: 1000
|
|
watch_freq_sec: 1
|
|
|
|
# [Stable] Guidance for Kubernetes container engine command-line args settings
|
|
#
|
|
# Modern cloud environments, particularly Kubernetes, heavily rely on
|
|
# containerized workload deployments. When capturing events with Falco, it
|
|
# becomes essential to identify the owner of the workload for which events are
|
|
# being captured, such as syscall events. Falco integrates with the container
|
|
# runtime to enrich its events with container information, including fields like
|
|
# `container.image.repository`, `container.image.tag`, ... , `k8s.ns.name`,
|
|
# `k8s.pod.name`, `k8s.pod.*` in the Falco output (Falco retrieves Kubernetes
|
|
# namespace and pod name directly from the container runtime, see
|
|
# https://falco.org/docs/reference/rules/supported-fields/#field-class-container).
|
|
#
|
|
# Furthermore, Falco exposes container events themselves as a data source for
|
|
# alerting. To achieve this integration with the container runtime, Falco
|
|
# requires access to the runtime socket. By default, for Kubernetes, Falco
|
|
# attempts to connect to the following sockets:
|
|
# "/run/containerd/containerd.sock", "/run/crio/crio.sock",
|
|
# "/run/k3s/containerd/containerd.sock". If you have a custom path, you can use
|
|
# the `--cri` option to specify the correct location.
|
|
#
|
|
# In some cases, you may encounter empty fields for container metadata. To
|
|
# address this, you can explore the `--disable-cri-async` option, which disables
|
|
# asynchronous fetching if the fetch operation is not completing quickly enough.
|
|
#
|
|
# To get more information on these command-line arguments, you can run `falco
|
|
# --help` in your terminal to view their current descriptions.
|
|
#
|
|
# !!! The options mentioned here are not available in the falco.yaml
|
|
# configuration file. Instead, they can can be used as a command-line argument
|
|
# when running the Falco command.
|