mirror of
https://github.com/falcosecurity/falco.git
synced 2025-06-29 08:07:24 +00:00
cleanup(config): re-arrange falco.yaml configs in logical categories
* add an index for logical categories * move configs around without changing description content, solely add a uniform header to each config * indicate "Stable" or "Experimental" for most configs to indicate current stability or maturity Signed-off-by: Melissa Kilby <melissa.kilby.oss@gmail.com>
This commit is contained in:
Melissa Kilby
poiana
parent
354c06567a
commit
b423754575
859
falco.yaml
859
falco.yaml
@ -1,5 +1,5 @@
|
||||
#
|
||||
# Copyright (C) 2022 The Falco Authors.
|
||||
# Copyright (C) 2023 The Falco Authors.
|
||||
#
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
@ -15,6 +15,72 @@
|
||||
# limitations under the License.
|
||||
#
|
||||
|
||||
################
|
||||
# Config index #
|
||||
################
|
||||
|
||||
# Here is an index of the configuration categories to help you navigate
|
||||
# the Falco configuration file:
|
||||
#
|
||||
# Falco rules + config files
|
||||
# rules_file
|
||||
# watch_config_files
|
||||
# Falco outputs (basic)
|
||||
# time_format_iso_8601
|
||||
# priority
|
||||
# json_output
|
||||
# json_include_output_property
|
||||
# json_include_tags_property
|
||||
# stdout_output
|
||||
# syslog_output
|
||||
# file_output
|
||||
# buffered_outputs
|
||||
# outputs (throttling)
|
||||
# Falco internal logging / alerting / metrics (basic)
|
||||
# log_stderr
|
||||
# log_syslog
|
||||
# log_level
|
||||
# libs_logger
|
||||
# Falco outputs (advanced)
|
||||
# grpc_output
|
||||
# grpc
|
||||
# http_output
|
||||
# program_output
|
||||
# webserver
|
||||
# Falco internal logging / alerting / metrics (advanced)
|
||||
# syscall_event_timeouts
|
||||
# syscall_event_drops
|
||||
# metrics
|
||||
# output_timeout
|
||||
# Falco cloud native relevant configs
|
||||
# metadata_download
|
||||
# load_plugins
|
||||
# plugins
|
||||
# Falco performance tuning
|
||||
# syscall_buf_size_preset
|
||||
# syscall_drop_failed_exit
|
||||
# base_syscalls
|
||||
# modern_bpf.cpus_for_each_syscall_buffer
|
||||
|
||||
################################
|
||||
# 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 `log_stderr`) are passed as
|
||||
# command-line arguments with their corresponding values :
|
||||
# `falco -o "json_output=true" -o "log_level=debug" -o "log_stderr=true"`. Please
|
||||
# note that command-line arguments take precedence over the options specified in
|
||||
# this config file.
|
||||
|
||||
|
||||
##############################
|
||||
# Falco rules + config files #
|
||||
##############################
|
||||
|
||||
# File(s) or Directories containing Falco rules, loaded at startup.
|
||||
# The name "rules_file" is only for backwards compatibility.
|
||||
# If the entry is a file, it will be read directly. If the entry is a directory,
|
||||
@ -32,47 +98,27 @@ rules_file:
|
||||
- /etc/falco/falco_rules.local.yaml
|
||||
- /etc/falco/rules.d
|
||||
|
||||
#
|
||||
# Plugins that are available for use. These plugins are not loaded by
|
||||
# default, as they require explicit configuration to point to
|
||||
# cloudtrail log files.
|
||||
#
|
||||
|
||||
# To learn more about the supported formats for
|
||||
# init_config/open_params for the cloudtrail plugin, see the README at
|
||||
# https://github.com/falcosecurity/plugins/blob/master/plugins/cloudtrail/README.md.
|
||||
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
|
||||
|
||||
# Setting this list to empty ensures that the above plugins are *not*
|
||||
# loaded and enabled by default. If you want to use the above plugins,
|
||||
# set a meaningful init_config/open_params for the cloudtrail plugin
|
||||
# and then change this to:
|
||||
# load_plugins: [cloudtrail, json]
|
||||
load_plugins: []
|
||||
|
||||
# Watch config file and rules files for modification.
|
||||
# When a file is modified, Falco will propagate new config,
|
||||
# by reloading itself.
|
||||
watch_config_files: true
|
||||
|
||||
|
||||
#########################
|
||||
# Falco outputs (basic) #
|
||||
#########################
|
||||
|
||||
# If true, 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.
|
||||
time_format_iso_8601: false
|
||||
|
||||
# Minimum rule priority level to load and run. All rules having a
|
||||
# priority more severe than this level will be loaded/run. Can be one
|
||||
# of "emergency", "alert", "critical", "error", "warning", "notice",
|
||||
# "informational", "debug".
|
||||
priority: debug
|
||||
|
||||
# If "true", print falco alert messages and rules file
|
||||
# loading/validation results as json, which allows for easier
|
||||
# consumption by downstream programs. Default is "false".
|
||||
@ -89,6 +135,53 @@ json_include_output_property: true
|
||||
# false, the "tags" field will not be included in the json output at all.
|
||||
json_include_tags_property: true
|
||||
|
||||
# Where security notifications should go.
|
||||
# Multiple outputs can be enabled.
|
||||
stdout_output:
|
||||
enabled: true
|
||||
|
||||
syslog_output:
|
||||
enabled: true
|
||||
|
||||
# If keep_alive is set to true, the file will be opened once and
|
||||
# continuously written to, with each output message on its own
|
||||
# line. If keep_alive is set to false, the file will be re-opened
|
||||
# for each output message.
|
||||
#
|
||||
# Also, the file will be closed and reopened if falco is signaled with
|
||||
# SIGUSR1.
|
||||
file_output:
|
||||
enabled: false
|
||||
keep_alive: false
|
||||
filename: ./events.txt
|
||||
|
||||
# Whether or not output to any of the output channels below is
|
||||
# buffered. Defaults to false
|
||||
buffered_outputs: false
|
||||
|
||||
# A throttling mechanism implemented as a token bucket limits the
|
||||
# rate of Falco notifications. One rate limiter is assigned to each event
|
||||
# source, so that alerts coming from one can't influence the throttling
|
||||
# mechanism of the others. This is controlled by the following options:
|
||||
# - 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.
|
||||
#
|
||||
# With these defaults, the throttling mechanism is disabled.
|
||||
# For example, by setting rate to 1 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.
|
||||
outputs:
|
||||
rate: 0
|
||||
max_burst: 1000
|
||||
|
||||
|
||||
#######################################################
|
||||
# Falco internal logging / alerting / metrics (basic) #
|
||||
#######################################################
|
||||
|
||||
# Send information logs to stderr and/or syslog Note these are *not* security
|
||||
# notification logs! These are just Falco lifecycle (and possibly error) logs.
|
||||
log_stderr: true
|
||||
@ -111,16 +204,140 @@ libs_logger:
|
||||
# "info", "debug", "trace".
|
||||
severity: debug
|
||||
|
||||
# Minimum rule priority level to load and run. All rules having a
|
||||
# priority more severe than this level will be loaded/run. Can be one
|
||||
# of "emergency", "alert", "critical", "error", "warning", "notice",
|
||||
# "informational", "debug".
|
||||
priority: debug
|
||||
|
||||
# Whether or not output to any of the output channels below is
|
||||
# buffered. Defaults to false
|
||||
buffered_outputs: false
|
||||
############################
|
||||
# Falco outputs (advanced) #
|
||||
############################
|
||||
|
||||
# [Stable] `grpc_output` and `grpc`
|
||||
#
|
||||
# gRPC output service.
|
||||
# By default it is off.
|
||||
# By enabling this all the output events will be kept in memory until you read them with a gRPC client.
|
||||
# Make sure to have a consumer for them or leave this disabled.
|
||||
grpc_output:
|
||||
enabled: false
|
||||
|
||||
# Falco supports running a gRPC server with two main binding types
|
||||
# 1. Over the network with mandatory mutual TLS authentication (mTLS)
|
||||
# 2. Over a local unix socket with no authentication
|
||||
# By default, the gRPC server is disabled, with no enabled services (see grpc_output)
|
||||
# please comment/uncomment and change accordingly the options below to configure it.
|
||||
# Important note: if Falco has any troubles creating the gRPC server
|
||||
# this information will be logged, however the main Falco daemon will not be stopped.
|
||||
# gRPC server over network with (mandatory) mutual TLS configuration.
|
||||
# This gRPC server is secure by default so you need to generate certificates and update their paths here.
|
||||
# By default the gRPC server is off.
|
||||
# You can configure the address to bind and expose it.
|
||||
# By modifying the threadiness configuration you can fine-tune the number of threads (and context) it will use.
|
||||
# grpc:
|
||||
# enabled: true
|
||||
# bind_address: "0.0.0.0:5060"
|
||||
# # when threadiness is 0, Falco sets it by automatically figuring out the number of online cores
|
||||
# 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 an unix socket
|
||||
grpc:
|
||||
enabled: false
|
||||
bind_address: "unix:///run/falco/falco.sock"
|
||||
# when threadiness is 0, Falco automatically guesses it depending on the number of online cores
|
||||
threadiness: 0
|
||||
|
||||
# [Stable] `http_output`
|
||||
#
|
||||
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`
|
||||
#
|
||||
# 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.
|
||||
#
|
||||
# Also, the program will be closed and reopened if falco is signaled with
|
||||
# SIGUSR1.
|
||||
program_output:
|
||||
enabled: false
|
||||
keep_alive: false
|
||||
program: "jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX"
|
||||
|
||||
# [Stable] `webserver`
|
||||
#
|
||||
# Falco supports an embedded webserver and exposes the following endpoints:
|
||||
# - /healthz: health endpoint useful for checking if Falco is up and running
|
||||
# (the endpoint name is configurable).
|
||||
# - /versions: responds with a JSON object containing version numbers of the
|
||||
# internal Falco components (similar output as `falco --version -o json_output=true`).
|
||||
#
|
||||
# # NOTE: the /versions endpoint is useful to other services (such as falcoctl)
|
||||
# to retrieve info about a running Falco instance. Make sure the webserver is
|
||||
# enabled if you're using falcoctl either locally or with Kubernetes.
|
||||
#
|
||||
# The following options control the behavior of that webserver (enabled by default).
|
||||
#
|
||||
# The ssl_certificate is a combination SSL Certificate and corresponding
|
||||
# key 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 threadiness is 0, Falco automatically guesses it depending on the number of online cores
|
||||
threadiness: 0
|
||||
listen_port: 8765
|
||||
k8s_healthz_endpoint: /healthz
|
||||
ssl_enabled: false
|
||||
ssl_certificate: /etc/falco/falco.pem
|
||||
|
||||
|
||||
##########################################################
|
||||
# Falco internal logging / alerting / metrics (advanced) #
|
||||
##########################################################
|
||||
|
||||
# [Stable] `syscall_event_timeouts`
|
||||
#
|
||||
# Falco uses a shared buffer between the kernel and userspace to receive
|
||||
# the events (eg., system call information) in userspace.
|
||||
#
|
||||
# Anyways, the underlying libraries can also timeout for various reasons.
|
||||
# For example, there could have been issues while reading an event.
|
||||
# Or the particular event needs to be skipped.
|
||||
# Normally, it's very unlikely that Falco does not receive events consecutively.
|
||||
#
|
||||
# Falco is able to detect such uncommon situation.
|
||||
#
|
||||
# Here you can configure the maximum number of consecutive timeouts without an event
|
||||
# after which you want Falco to alert.
|
||||
# By default this value is set to 1000 consecutive timeouts without an event at all.
|
||||
# How this value maps to a time interval depends on the CPU frequency.
|
||||
syscall_event_timeouts:
|
||||
max_consecutives: 1000
|
||||
|
||||
# [Stable] `syscall_event_drops`
|
||||
#
|
||||
# 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
|
||||
@ -142,7 +359,6 @@ buffered_outputs: false
|
||||
#
|
||||
# For debugging/testing it is possible to simulate the drops using
|
||||
# the `simulate_drops: true`. In this case the threshold does not apply.
|
||||
|
||||
syscall_event_drops:
|
||||
threshold: .1
|
||||
actions:
|
||||
@ -152,31 +368,184 @@ syscall_event_drops:
|
||||
max_burst: 1
|
||||
simulate_drops: false
|
||||
|
||||
# Falco uses a shared buffer between the kernel and userspace to receive
|
||||
# the events (eg., system call information) in userspace.
|
||||
# [Experimental] `metrics`
|
||||
#
|
||||
# Anyways, the underlying libraries can also timeout for various reasons.
|
||||
# For example, there could have been issues while reading an event.
|
||||
# Or the particular event needs to be skipped.
|
||||
# Normally, it's very unlikely that Falco does not receive events consecutively.
|
||||
# periodic metric snapshots (including stats and resource utilization)
|
||||
# captured at regular intervals
|
||||
#
|
||||
# Falco is able to detect such uncommon situation.
|
||||
# --- [Description]
|
||||
#
|
||||
# Here you can configure the maximum number of consecutive timeouts without an event
|
||||
# after which you want Falco to alert.
|
||||
# By default this value is set to 1000 consecutive timeouts without an event at all.
|
||||
# How this value maps to a time interval depends on the CPU frequency.
|
||||
# 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.
|
||||
#
|
||||
# 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 - milliseconds
|
||||
# s - seconds
|
||||
# m - minutes
|
||||
# h - hours
|
||||
# d - days - assuming a day has always 24h
|
||||
# w - weeks - assuming a week has always 7d
|
||||
# y - years - 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 `log_level` 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.
|
||||
#
|
||||
# `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.
|
||||
#
|
||||
# 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
|
||||
|
||||
syscall_event_timeouts:
|
||||
max_consecutives: 1000
|
||||
# [Stable] `output_timeout`
|
||||
#
|
||||
# Falco continuously monitors outputs performance. When an output channel does not allow
|
||||
# to deliver an alert within a given deadline, an error is reported indicating
|
||||
# which output is blocking notifications.
|
||||
# The timeout error will be reported to the log according to the above log_* settings.
|
||||
# Note that the notification will not be discarded from the output queue; thus,
|
||||
# output channels may indefinitely remain blocked.
|
||||
# An output timeout error indeed indicate a misconfiguration issue or I/O problems
|
||||
# that cannot be recovered by Falco and should be fixed by the user.
|
||||
#
|
||||
# The "output_timeout" value specifies the duration in milliseconds to wait before
|
||||
# considering the deadline exceed.
|
||||
#
|
||||
# With a 2000ms default, the notification consumer can block the Falco output
|
||||
# for up to 2 seconds without reaching the timeout.
|
||||
output_timeout: 2000
|
||||
|
||||
# Enabling this option allows Falco to drop failed syscalls exit events
|
||||
# in the kernel driver before the event is pushed onto the ring buffer.
|
||||
# This can enable some small optimization both in CPU usage and ring buffer usage,
|
||||
# possibly leading to lower number of event losses.
|
||||
# Be careful: enabling it also means losing a bit of visibility on the system.
|
||||
syscall_drop_failed_exit: false
|
||||
|
||||
#######################################
|
||||
# Falco cloud native relevant configs #
|
||||
#######################################
|
||||
|
||||
# [Stable] `metadata_download`
|
||||
#
|
||||
# Container orchestrator metadata fetching params
|
||||
metadata_download:
|
||||
max_mb: 100
|
||||
chunk_wait_us: 1000
|
||||
watch_freq_sec: 1
|
||||
|
||||
# [Experimental] `load_plugins` and `plugins`
|
||||
#
|
||||
# Setting this list to empty ensures that the above plugins are *not*
|
||||
# loaded and enabled by default. If you want to use the above plugins,
|
||||
# set a meaningful init_config/open_params for the cloudtrail plugin
|
||||
# and then change this to:
|
||||
# load_plugins: [cloudtrail, json]
|
||||
load_plugins: []
|
||||
|
||||
# Plugins that are available for use. These plugins are not loaded by
|
||||
# default, as they require explicit configuration to point to
|
||||
# cloudtrail log files.
|
||||
# To learn more about the supported formats for
|
||||
# init_config/open_params for the cloudtrail plugin, see the README at
|
||||
# https://github.com/falcosecurity/plugins/blob/master/plugins/cloudtrail/README.md.
|
||||
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 performance tuning #
|
||||
############################
|
||||
|
||||
# [Stable] `syscall_buf_size_preset`
|
||||
#
|
||||
# --- [Description]
|
||||
#
|
||||
# This is an index that controls the dimension of the syscall buffers.
|
||||
@ -232,234 +601,17 @@ syscall_drop_failed_exit: false
|
||||
|
||||
syscall_buf_size_preset: 4
|
||||
|
||||
############## Modern BPF probe specific ##############
|
||||
# Please note: these configs regard only the modern BPF probe.
|
||||
# [Experimental] `syscall_drop_failed_exit`
|
||||
#
|
||||
# `cpus_for_each_syscall_buffer`
|
||||
#
|
||||
# --- [Description]
|
||||
#
|
||||
# This is an index that controls how many CPUs you want to assign to a single
|
||||
# syscall buffer (ring buffer). By default, 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, 1:1 would mean a syscall buffer for each CPU.
|
||||
#
|
||||
# --- [Usage]
|
||||
#
|
||||
# You can choose between different indexes: from `0` to `MAX_NUMBER_ONLINE_CPUs`.
|
||||
# `0` is a special value and it means a single syscall buffer shared between all
|
||||
# your online CPUs. `0` has the same effect as `MAX_NUMBER_ONLINE_CPUs`, the rationale
|
||||
# is that `0` allows you to create a single buffer without knowing the number of online
|
||||
# CPUs on your system.
|
||||
# Let's consider an example to better understand it:
|
||||
#
|
||||
# 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 we need 4 buffers, 3 buffers are associated with CPU pairs, the last
|
||||
# one is mapped with just 1 CPU since 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 can combine this param with `syscall_buf_size_preset`
|
||||
# index, for example, you could create a huge single syscall buffer
|
||||
# shared between all your online CPUs of 512 MB (so `syscall_buf_size_preset=10`).
|
||||
#
|
||||
# --- [Suggestions]
|
||||
#
|
||||
# We chose index `2` (so one syscall buffer for each CPU pair) as default because the modern bpf probe
|
||||
# follows a different memory allocation strategy with respect to the other 2 drivers (bpf and kernel module).
|
||||
# By the way, you are free to find the preferred configuration for your system.
|
||||
# Considering a fixed `syscall_buf_size_preset` and so a fixed buffer dimension:
|
||||
# - a lower number of buffers can speed up your system (lower memory footprint)
|
||||
# - a too lower number of buffers could increase contention in the kernel causing an
|
||||
# overall slowdown of the system.
|
||||
# If you don't have huge events throughputs and you are not experimenting with tons of drops
|
||||
# you can try to reduce the number of buffers to have a lower memory footprint
|
||||
# Enabling this option allows Falco to drop failed syscalls exit events
|
||||
# in the kernel driver before the event is pushed onto the ring buffer.
|
||||
# This can enable some small optimization both in CPU usage and ring buffer usage,
|
||||
# possibly leading to lower number of event losses.
|
||||
# Be careful: enabling it also means losing a bit of visibility on the system.
|
||||
|
||||
modern_bpf:
|
||||
cpus_for_each_syscall_buffer: 2
|
||||
############## Modern BPF probe specific ##############
|
||||
syscall_drop_failed_exit: false
|
||||
|
||||
# Falco continuously monitors outputs performance. When an output channel does not allow
|
||||
# to deliver an alert within a given deadline, an error is reported indicating
|
||||
# which output is blocking notifications.
|
||||
# The timeout error will be reported to the log according to the above log_* settings.
|
||||
# Note that the notification will not be discarded from the output queue; thus,
|
||||
# output channels may indefinitely remain blocked.
|
||||
# An output timeout error indeed indicate a misconfiguration issue or I/O problems
|
||||
# that cannot be recovered by Falco and should be fixed by the user.
|
||||
#
|
||||
# The "output_timeout" value specifies the duration in milliseconds to wait before
|
||||
# considering the deadline exceed.
|
||||
#
|
||||
# With a 2000ms default, the notification consumer can block the Falco output
|
||||
# for up to 2 seconds without reaching the timeout.
|
||||
|
||||
output_timeout: 2000
|
||||
|
||||
# A throttling mechanism implemented as a token bucket limits the
|
||||
# rate of Falco notifications. One rate limiter is assigned to each event
|
||||
# source, so that alerts coming from one can't influence the throttling
|
||||
# mechanism of the others. This is controlled by the following options:
|
||||
# - 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.
|
||||
#
|
||||
# With these defaults, the throttling mechanism is disabled.
|
||||
# For example, by setting rate to 1 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.
|
||||
|
||||
outputs:
|
||||
rate: 0
|
||||
max_burst: 1000
|
||||
|
||||
# Where security notifications should go.
|
||||
# Multiple outputs can be enabled.
|
||||
|
||||
syslog_output:
|
||||
enabled: true
|
||||
|
||||
# If keep_alive is set to true, the file will be opened once and
|
||||
# continuously written to, with each output message on its own
|
||||
# line. If keep_alive is set to false, the file will be re-opened
|
||||
# for each output message.
|
||||
#
|
||||
# Also, the file will be closed and reopened if falco is signaled with
|
||||
# SIGUSR1.
|
||||
|
||||
file_output:
|
||||
enabled: false
|
||||
keep_alive: false
|
||||
filename: ./events.txt
|
||||
|
||||
stdout_output:
|
||||
enabled: true
|
||||
|
||||
# Falco supports an embedded webserver and exposes the following endpoints:
|
||||
# - /healthz: health endpoint useful for checking if Falco is up and running
|
||||
# (the endpoint name is configurable).
|
||||
# - /versions: responds with a JSON object containing version numbers of the
|
||||
# internal Falco components (similar output as `falco --version -o json_output=true`).
|
||||
#
|
||||
# # NOTE: the /versions endpoint is useful to other services (such as falcoctl)
|
||||
# to retrieve info about a running Falco instance. Make sure the webserver is
|
||||
# enabled if you're using falcoctl either locally or with Kubernetes.
|
||||
#
|
||||
# The following options control the behavior of that webserver (enabled by default).
|
||||
#
|
||||
# The ssl_certificate is a combination SSL Certificate and corresponding
|
||||
# key 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 threadiness is 0, Falco automatically guesses it depending on the number of online cores
|
||||
threadiness: 0
|
||||
listen_port: 8765
|
||||
k8s_healthz_endpoint: /healthz
|
||||
ssl_enabled: false
|
||||
ssl_certificate: /etc/falco/falco.pem
|
||||
|
||||
# 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.
|
||||
#
|
||||
# Also, the program will be closed and reopened if falco is signaled with
|
||||
# SIGUSR1.
|
||||
program_output:
|
||||
enabled: false
|
||||
keep_alive: false
|
||||
program: "jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX"
|
||||
|
||||
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"
|
||||
|
||||
# Falco supports running a gRPC server with two main binding types
|
||||
# 1. Over the network with mandatory mutual TLS authentication (mTLS)
|
||||
# 2. Over a local unix socket with no authentication
|
||||
# By default, the gRPC server is disabled, with no enabled services (see grpc_output)
|
||||
# please comment/uncomment and change accordingly the options below to configure it.
|
||||
# Important note: if Falco has any troubles creating the gRPC server
|
||||
# this information will be logged, however the main Falco daemon will not be stopped.
|
||||
# gRPC server over network with (mandatory) mutual TLS configuration.
|
||||
# This gRPC server is secure by default so you need to generate certificates and update their paths here.
|
||||
# By default the gRPC server is off.
|
||||
# You can configure the address to bind and expose it.
|
||||
# By modifying the threadiness configuration you can fine-tune the number of threads (and context) it will use.
|
||||
# grpc:
|
||||
# enabled: true
|
||||
# bind_address: "0.0.0.0:5060"
|
||||
# # when threadiness is 0, Falco sets it by automatically figuring out the number of online cores
|
||||
# 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 an unix socket
|
||||
grpc:
|
||||
enabled: false
|
||||
bind_address: "unix:///run/falco/falco.sock"
|
||||
# when threadiness is 0, Falco automatically guesses it depending on the number of online cores
|
||||
threadiness: 0
|
||||
|
||||
# gRPC output service.
|
||||
# By default it is off.
|
||||
# By enabling this all the output events will be kept in memory until you read them with a gRPC client.
|
||||
# Make sure to have a consumer for them or leave this disabled.
|
||||
grpc_output:
|
||||
enabled: false
|
||||
|
||||
# Container orchestrator metadata fetching params
|
||||
metadata_download:
|
||||
max_mb: 100
|
||||
chunk_wait_us: 1000
|
||||
watch_freq_sec: 1
|
||||
|
||||
|
||||
# base_syscalls ! [EXPERIMENTAL] Use with caution, read carefully !
|
||||
# [Experimental] `base_syscalls`, use with caution, read carefully
|
||||
#
|
||||
# --- [Description]
|
||||
#
|
||||
@ -561,116 +713,69 @@ metadata_download:
|
||||
# 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
|
||||
|
||||
# metrics: [EXPERIMENTAL] periodic metric snapshots
|
||||
# (including stats and resource utilization) captured at regular intervals
|
||||
# [Experimental] `modern_bpf.cpus_for_each_syscall_buffer`, modern_bpf only
|
||||
#
|
||||
# --- [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.
|
||||
#
|
||||
# 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.
|
||||
# This is an index that controls how many CPUs you want to assign to a single
|
||||
# syscall buffer (ring buffer). By default, 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, 1:1 would mean a syscall buffer for each CPU.
|
||||
#
|
||||
# --- [Usage]
|
||||
#
|
||||
# `enabled`:
|
||||
# Disabled by default.
|
||||
# You can choose between different indexes: from `0` to `MAX_NUMBER_ONLINE_CPUs`.
|
||||
# `0` is a special value and it means a single syscall buffer shared between all
|
||||
# your online CPUs. `0` has the same effect as `MAX_NUMBER_ONLINE_CPUs`, the rationale
|
||||
# is that `0` allows you to create a single buffer without knowing the number of online
|
||||
# CPUs on your system.
|
||||
# Let's consider an example to better understand it:
|
||||
#
|
||||
# `interval`:
|
||||
# The stats interval in Falco follows the time duration definitions used by Prometheus.
|
||||
# https://prometheus.io/docs/prometheus/latest/querying/basics/#time-durations
|
||||
# Consider a system with 7 online CPUs:
|
||||
#
|
||||
# Time durations are specified as a number, followed immediately by one of the following units:
|
||||
# ms - milliseconds
|
||||
# s - seconds
|
||||
# m - minutes
|
||||
# h - hours
|
||||
# d - days - assuming a day has always 24h
|
||||
# w - weeks - assuming a week has always 7d
|
||||
# y - years - assuming a year has always 365d
|
||||
# CPUs 0 X 2 3 X X 6 7 8 9 (X means offline CPU)
|
||||
#
|
||||
# Example of a valid time duration: 1h30m20s10ms
|
||||
# - `1` means a syscall buffer for each CPU so 7 buffers
|
||||
#
|
||||
# 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
|
||||
# CPUs 0 X 2 3 X X 6 7 8 9 (X means offline CPU)
|
||||
# | | | | | | |
|
||||
# BUFFERs 0 1 2 3 4 5 6
|
||||
#
|
||||
# `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 `log_level` must be set to `info` at a minimum.
|
||||
# - `2` (Default value) means a syscall buffer for each CPU pair, so 4 buffers
|
||||
#
|
||||
# `output_file`:
|
||||
# Append stats to a `jsonl` file. Use with caution in production as Falco does not automatically rotate the file.
|
||||
# CPUs 0 X 2 3 X X 6 7 8 9 (X means offline CPU)
|
||||
# | | | | | | |
|
||||
# BUFFERs 0 0 1 1 2 2 3
|
||||
#
|
||||
# `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.
|
||||
# Please note that we need 4 buffers, 3 buffers are associated with CPU pairs, the last
|
||||
# one is mapped with just 1 CPU since we have an odd number of CPUs.
|
||||
#
|
||||
# `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.
|
||||
# - `0` or `MAX_NUMBER_ONLINE_CPUs` mean a syscall buffer shared between all CPUs, so 1 buffer
|
||||
#
|
||||
# `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.
|
||||
# CPUs 0 X 2 3 X X 6 7 8 9 (X means offline CPU)
|
||||
# | | | | | | |
|
||||
# BUFFERs 0 0 0 0 0 0 0
|
||||
#
|
||||
# todo: prometheus export option
|
||||
# todo: syscall_counters_enabled option
|
||||
# Moreover you can combine this param with `syscall_buf_size_preset`
|
||||
# index, for example, you could create a huge single syscall buffer
|
||||
# shared between all your online CPUs of 512 MB (so `syscall_buf_size_preset=10`).
|
||||
#
|
||||
# --- [Suggestions]
|
||||
#
|
||||
# We chose index `2` (so one syscall buffer for each CPU pair) as default because the modern bpf probe
|
||||
# follows a different memory allocation strategy with respect to the other 2 drivers (bpf and kernel module).
|
||||
# By the way, you are free to find the preferred configuration for your system.
|
||||
# Considering a fixed `syscall_buf_size_preset` and so a fixed buffer dimension:
|
||||
# - a lower number of buffers can speed up your system (lower memory footprint)
|
||||
# - a too lower number of buffers could increase contention in the kernel causing an
|
||||
# overall slowdown of the system.
|
||||
# If you don't have huge events throughputs and you are not experimenting with tons of drops
|
||||
# you can try to reduce the number of buffers to have a lower memory footprint
|
||||
|
||||
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
|
||||
modern_bpf:
|
||||
cpus_for_each_syscall_buffer: 2
|
||||
|
||||
Loading…
Reference in New Issue
Block a user