Configuration

Configuration for the Falco daemon

This is for the Falco daemon configuration options.

Please visit rules or alerts for those options.

Falco's configuration file is a YAML file containing a collection of key: value or key: [value list] pairs.

Any configuration option can be overridden on the command line via the -o/--option key=value flag. For key: [value list] options, you can specify individual list items using --option key.subkey=value.

Current configuration options

Config	Type	Description
`rules_file`	List	The location of the rules file(s). This can contain one or more paths to separate rules files. The following examples are equivalent: `rules_file: - path1 - path2 rules_file: [path1, path2]` You can also specify multiple rules files on the command line via one or more `-r` options.
`time_format_iso_8601`	Boolean	If `true` (default is `false`), the times displayed in log messages and output messages will be in ISO 8601. By default, times are displayed in the local time zone, as governed by /etc/localtime.
`json_output`	Boolean	Whether to use JSON output for alert messages.
`json_include_output_property`	Boolean	When using json output, whether or not to include the `output` property itself (e.g. `File below a known binary directory opened for writing (user=root ....`) in the JSON output.
`log_stderr`	Boolean	If `true`, log messages describing Falco's activity will be logged to stderr. Note these are not alert messages---these are log messages for Falco itself.
`log_syslog`	Boolean	If `true`, log messages describing Falco's activity will be logged to syslog.
`log_level`	Enum with the following possible values: `emergency`, `alert`, `critical`, `error`, `warning`, `notice`, `info`, `debug`	Minimum log level to include in logs. Note: these levels are separate from the priority field of rules. This refers only to the log level of Falco's internal logging.
`priority`	Enum with the following possible values: `emergency`, `alert`, `critical`, `error`, `warning`, `notice`, `info`, `debug`	Minimum rule priority level to load and run. All rules having a priority more severe than this level will be loaded/run.
`syscall_event_drops`	List containing the following sub-keys: `actions`: A list containing one or more of these boolean sub-keys: `ignore`: do nothing. If an empty list is provided, ignore is assumed. `log`: log a CRITICAL 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. `rate`: The steady-state rate at which actions can be taken. Units of actions/second. Default 0.03333 (one action per 30 seconds). `max_burst`: The maximum number of actions that can be taken before the steady-state rate is applied.	Controls Actions For Dropped System Call Events.
`buffered_outputs`	Boolean	Whether or not output to any of the output channels below is buffered. Defaults to false.
`outputs`	List containing the following sub-keys: `rate: <notifications/second>` `outputs: max_burst: <number of messages>`	A throttling mechanism implemented as a token bucket limits the rate of Falco notifications. This throttling is controlled by the `rate` and `max_burst` options. `rate` is the number of tokens (i.e. right to send a notification) gained per second, and defaults to 1. `max_burst` is the maximum number of tokens outstanding, and defaults to 1000. With these defaults, Falco could send up to 1000 notifications after an initial quiet period, and then up to 1 notification per second afterward. It would gain the full burst back after 1000 seconds of no activity.
`syslog_output`	List containing the following sub-keys: `enabled: [true\|false]`	If `true`, Falco alerts will be sent via syslog.
`file_output`	List containing the following sub-keys: `enabled: [true\|false]` `keep_alive: [true\|false]` `filename: <path>`	If `enabled` is set to `true`, Falco alerts will be sent to the filepath specified in `filename`. If `keep_alive` is set to `false` (the default), Falco will re-open the file for every alert. If `true`, Falco will open the file once and keep it open for all alerts. It may also be necessary to specify `--unbuffered` using the Falco CLI.
`stdout_output`	List containing the following sub-keys: `enabled: [true\|false]`	If `enabled` is set to `true`, Falco alerts will be sent to standard output (stdout).
`program_output`	List containing the following sub-keys: `enabled: [true\|false]` `keep_alive: [true\|false]`	If `enabled` is set to `true`, Falco alerts will be sent to a program. If `keep_alive` is set to `false` (the default), run the program for each alert. If `true`, Falco will spawn the program once and keep it open for all alerts. It may also be necessary to specify `--unbuffered` using the Falco CLI. The `program` setting specifies the program to be run for each alert. This is started via the shell, so you can specify a command pipeline to allow for additional formatting.
`http_output`	List containing the following sub-keys: `enabled: [true\|false]` `url: [http[s]://path/to/webhook/]`	As of `0.15.0`, if enabled is set to true, Falco alerts will be sent to the HTTP[s] URL defined by `url`. Currently this is a blocking operation and this output does not support `keep_alive`.
`webserver`	List containing the following sub-keys: `enabled: [true\|false]` `listen_port` `k8s_audit_endpoint` `ssl_enabled: [true\|false]` `ssl_certificate: <path>`	If `enabled` is set to `true`, Falco will start an embedded web server to accept Kubernetes audit events. `listen_port` specifies the port on which the web server will listen. The default is 8765. `k8s_audit_endpoint` specifies the URI on which to listen for Kubernetes audit events. The default is `/k8s-audit`. `ssl_enabled` enables SSL support for the webserver, using the certificate specified in `ssl_certificate`. The specified `ssl_certificate` file should contain the server's certificate as well as the key as documented by civitweb.
`grpc`	List containing the following sub-keys: `enabled: [true\|false]` `bind_address: [unix://<path>.sock\|address:port]` `threadiness: <integer>` `private_key: <path>` `cert_chain: <path>` `root_certs: <path>`	If `enabled` is set to `true`, Falco will embed a gRPC server to expose its gRPC API. The default is `false`. Falco supports running a gRPC server with two main binding types: Over a local unix socket with no authentication Over the network with mandatory mutual TLS authentication (mTLS) `bind_address` specifies either the unix socket path or the address and port on which the gRPC server will listen. The default is `unix:///var/run/falco.sock`. `threadiness` defines the number of threads to use to serve gRPC requests. When `threadiness` is `0`, Falco automatically guesses it depending on the number of online cores. The default is `0`. The gRPC server over the network can only be used with mutual authentication between the clients and the server using TLS certificates, and the following options should be provided: `private_key` path of the private key for server authentication. The default is `/etc/falco/certs/server.key`. `cert_chain` path of the public cert for server authentication. The default is `/etc/falco/certs/server.crt`. `root_certs` path of the CA certificate (or chain) common between the server and all the clients. The default is `/etc/falco/certs/ca.crt`. How to generate the certificates is documented here. Please always remember that the only common thing between server and clients is the root certificate. Every client will need to generate their own certificates signed by the same root CA as the server.
`grpc_output`	List containing the following sub-keys: `enabled: [true\|false]`	If `enabled` is set to `true`, Falco will start collecting outputs for the gRPC server. It's important to consume them with an output client. Example of output client here.
`plugins`	A list of objects. Each object has the following sub-keys: `name: <string>` `library_path: <path>` `init_config: <string>` `init_config_file: <path>` `open_params: <string>` `open_params_file: <path>`	Defines the set of plugins Falco can load. `name` provides the plugin name. This is only used for load_plugins, but by convention should be the same as the value returned by the plugin_get_name() api function. `library_path` is path to the shared library. The path can be relative, in which case it is relative to Falco's "share" directory under a "plugins" subdirectory e.g. /usr/share/falco/plugins. If `init_config` is present, it contains the exact configuration text that will be provided as an argument to the init() function. Alternatively, if `init_config_file` is present, the provided file will be read and the contents will be provided as an argument to the init() function. if `open_params`: is present, it contains the exact params text that will be provided as an argument to the open() function. Alternatively, if `open_params_file` is present, the provided file will be read and the contents will be provided as an argument to the open() function. For a given yaml object in the plugins list, only one of init_config/init_config_file and one of open_params/open_params_file can be provided at a time.
`load_plugins`	A list of plugin names, corresponding to the name sub-key from the plugins config item. Example: `load_plugins: [cloudtrail, json]`	Defines the set of plugins that will actually be loaded. This is optional--if the property is not present, all plugins named in the plugins list will be loaded.

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Last modified January 22, 2021: added DCO signoff (e9d58f5)