new: add config options and docs for capture feature

Signed-off-by: Leonardo Grasso <me@leonardograsso.com>

falco.yaml

@@ -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) #
 #################################################################################

userspace/engine/rule_json_schema.h

@@ -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"
                 },

userspace/falco/config_json_schema.h

@@ -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,