new: add config options and docs for capture feature

Signed-off-by: Leonardo Grasso <me@leonardograsso.com>
This commit is contained in:
Leonardo Grasso 2025-07-18 13:00:55 +02:00 committed by poiana
parent bff2f619df
commit 5ebfa1b05b
3 changed files with 161 additions and 70 deletions

View File

@ -83,7 +83,6 @@
#
# For more info, please take a look at the proposal: https://github.com/falcosecurity/falco/blob/master/proposals/20231220-features-adoption-and-deprecation.md.
################################
# Falco command-line arguments #
################################
@ -99,7 +98,6 @@
# Please note that command-line arguments take precedence over the options
# specified in this config file.
###############################
# Falco environment variables #
###############################
@ -129,7 +127,6 @@
# - FALCOCTL_ENABLED is useful when set to 'no' during the installation of Falco deb/rpm packages,
# disabling the automatic artifacts followed by falcoctl.
###############################
# Falco config files settings #
###############################
@ -168,7 +165,6 @@ config_files:
#- path: $HOME/falco_local_configs/
# strategy: add-only
# [Stable] `watch_config_files`
#
# Falco monitors configuration and rules files for changes and automatically
@ -452,6 +448,75 @@ engine:
# is the one usually passed to 'runsc --root' flag.
root: ""
##################
# Falco captures #
##################
# [Sandbox] `capture`
#
# --- [Description]
#
# Falco captures allow you to record events and their associated data for
# later analysis. This feature is particularly useful for debugging and
# forensics purposes.
#
# Captures operate in two modes:
#
# 1. `rules`: Captures events only when specific rules are triggered.
# Enable capturing for individual rules by adding `capture: true` to the rule.
#
# 2. `all_rules`: Captures events when any enabled rule is triggered.
#
# When a capture starts, Falco records events from the moment the triggering rule
# fires until the deadline is reached. The deadline is determined by the rule's
# `capture_duration` if specified, otherwise the `default_duration` is used.
# If additional rules trigger during an active capture, the deadline is extended
# accordingly. Once the deadline expires, the capture stops and data is written
# to a file. Subsequent captures create new files with unique names.
#
# Captured data is stored in files with a `.scap` extension, which can be
# analyzed later using:
# falco -o engine.kind=replay -o replay.capture_file=/path/to/file.scap
#
# --- [Usage]
#
# Enable captures by setting `capture.enabled` to `true`.
#
# Configure `capture.path_prefix` to specify where capture files are stored.
# Falco generates unique filenames based on timestamp and event number for
# proper ordering. For example, with `path_prefix: /tmp/falco`, files are
# named like `/tmp/falco_00000001234567890_00000000000000042.scap`.
#
# Use `capture.mode` to choose between `rules` and `all_rules` modes.
#
# Set `capture.default_duration` to define the default capture duration
# in milliseconds.
#
# --- [Suggestion]
#
# When using `mode: rules`, configure individual rules to enable capture by
# adding `capture: true` and optionally `capture_duration` to specific rules.
# For example:
#
# - rule: Suspicious File Access
# desc: Detect suspicious file access patterns
# condition: >
# open_read and fd.name startswith "/etc/"
# output: >
# Suspicious file access (user=%user.name command=%proc.cmdline file=%fd.name)
# priority: WARNING
# capture: true
# capture_duration: 10000 # Capture for 10 seconds when this rule triggers
#
# This configuration will capture events for 10 seconds whenever the
# "Suspicious File Access" rule is triggered, overriding the default duration.
capture:
enabled: false
path_prefix: /tmp/falco
mode: rules # or "all_rules"
default_duration: 5000 # in milliseconds
#################
# Falco plugins #
#################
@ -805,7 +870,6 @@ program_output:
grpc_output:
enabled: false
##########################
# Falco exposed services #
##########################
@ -895,7 +959,6 @@ webserver:
ssl_enabled: false
ssl_certificate: /etc/falco/falco.pem
##############################################################################
# Falco logging / alerting / metrics related to software functioning (basic) #
##############################################################################
@ -935,7 +998,6 @@ libs_logger:
enabled: true
severity: info
#################################################################################
# Falco logging / alerting / metrics related to software functioning (advanced) #
#################################################################################

View File

@ -74,6 +74,12 @@ const char rule_schema_string[] = LONG_STRING_CONST(
"priority": {
"$ref": "#/definitions/Priority"
},
"capture": {
"type": "boolean"
},
"capture_duration": {
"type": "integer"
},
"source": {
"type": "string"
},

View File

@ -1,6 +1,6 @@
// SPDX-License-Identifier: Apache-2.0
/*
Copyright (C) 2024 The Falco Authors.
Copyright (C) 2025 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.
@ -311,6 +311,29 @@ const char config_schema_string[] = LONG_STRING_CONST(
}
}
},
"Capture": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"path_prefix": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"rules",
"all_rules"
]
},
"default_duration": {
"type": "integer"
}
},
"title": "Capture"
},
"BaseSyscalls": {
"type": "object",
"additionalProperties": false,