Falco Configuration

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.

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.

webserver List containing the following sub-keys:

  • enabled: [true|false]
  • listen_port
  • k8s_audit_endpoint

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.