new(userspace/falco): add capture.max_file_size_mb global hard limit

Co-authored-by: Alessandro Cannarella <cannarella.dev@gmail.com>
Co-authored-by: Gerald Combs <gerald@wireshark.org>
Co-authored-by: Iacopo Rozzo <iacopo@sysdig.com>
Co-authored-by: Leonardo Di Giovanna <leonardodigiovanna1@gmail.com>
Signed-off-by: Leonardo Grasso <me@leonardograsso.com>

Author: 5 people

falco.yaml

@@ -461,11 +461,29 @@ engine:
 # 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.
+# fires until a stop condition is reached. Two stop conditions are available:
+#
+# - Time (per-rule, soft): determined by the rule's `capture_duration` if
+#   specified, otherwise `default_duration` is used. If additional rules trigger
+#   during an active capture, the deadline is extended accordingly (the longest
+#   deadline wins). For this reason, the time limit has "at least" semantics:
+#   the capture is guaranteed to last at least that long, but can last longer if
+#   other rules keep matching.
+#
+# - File size (global, hard): `max_file_size_mb` applies to any capture,
+#   regardless of which rule triggered it. Unlike the time limit, it cannot be
+#   overridden or extended by rules: if a capture reaches this size, it stops.
+#   N.B. The size check uses the dumper's compressed on-disk counter, which is
+#   updated in chunks as zlib flushes its internal buffers. The effective file
+#   size is therefore approximate and may overshoot the configured value by up
+#   to one flush window. For this reason, avoid very small values (under a few
+#   MB), which may be inaccurate, and consider tuning with a healthy margin.
+#
+# The first stop condition met wins (OR semantics). Once a stop condition is
+# met, the capture stops and data is written to a file. Subsequent captures
+# create new files with unique names. When a capture stops because of
+# `max_file_size_mb`, Falco emits an internal INFO message so the truncation
+# is visible in the configured outputs.
 #
 # Captured data is stored in files with a `.scap` extension, which can be
 # analyzed later using:
@@ -483,7 +501,8 @@ engine:
 # Use `capture.mode` to choose between `rules` and `all_rules` modes.
 #
 # Set `capture.default_duration` to define the default capture duration
-# in milliseconds.
+# in milliseconds. Optionally, set `capture.max_file_size_mb` to enforce a
+# hard upper bound on the capture file size in MB (applies to any capture).
 #
 # --- [Suggestions]
 #
@@ -512,6 +531,10 @@ capture:
   mode: rules
   # -- Default capture duration in milliseconds if not specified in the rule.
   default_duration: 5000
+  # -- Global hard cap on capture file size in MB (0 = unlimited).
+  # This limit applies to any capture and cannot be overridden or extended by rules.
+  # The check is approximate (see the section above): prefer values of at least a few MB.
+  # max_file_size_mb: 100
 
 #################
 # Falco plugins #

userspace/falco/app/actions/helpers.h

@@ -35,6 +35,33 @@ void check_for_ignored_events(falco::app::state& s);
 void format_plugin_info(std::shared_ptr<sinsp_plugin> p, std::ostream& os);
 void format_described_rules_as_text(const nlohmann::json& v, std::ostream& os);
 
+enum class capture_stop_reason {
+	NONE,
+	TIME_DEADLINE,
+	SIZE_LIMIT,
+};
+
+// Returns the reason why an active capture should stop, given the current
+// event timestamp, the dump deadline, and the number of bytes written so far.
+// Stop conditions combine with OR semantics (first met wins); time is checked
+// before size, so when both trip on the same event, TIME_DEADLINE is reported.
+// `max_file_size_mb == 0` means "unlimited".
+// Note: `written_bytes` is the dumper's on-disk counter (compressed, buffered
+// by zlib), so the check is approximate — the effective file size may overshoot
+// by up to one flush window.
+inline capture_stop_reason check_capture_stop(uint64_t evt_ts,
+                                              uint64_t dump_deadline_ts,
+                                              uint64_t written_bytes,
+                                              uint64_t max_file_size_mb) {
+	if(evt_ts >= dump_deadline_ts) {
+		return capture_stop_reason::TIME_DEADLINE;
+	}
+	if(max_file_size_mb > 0 && written_bytes >= max_file_size_mb * 1024 * 1024) {
+		return capture_stop_reason::SIZE_LIMIT;
+	}
+	return capture_stop_reason::NONE;
+}
+
 inline std::string generate_scap_file_path(const std::string& prefix,
                                            uint64_t timestamp,
                                            uint64_t evt_num) {

userspace/falco/app/actions/process_events.cpp

@@ -149,6 +149,13 @@ static falco::app::run_result do_inspect(
 	auto dumper = std::make_unique<sinsp_dumper>();
 	uint64_t dump_started_ts = 0;
 	uint64_t dump_deadline_ts = 0;
+	// Global hard cap on capture file size (MB). 0 means unlimited.
+	const uint64_t dump_max_file_size_mb = s.config->m_capture_max_file_size_mb;
+	// Pre-built notification strings for the size-limit branch (constant per
+	// do_inspect call), hoisted to avoid per-event allocations in the hot path.
+	const std::string size_cap_rule = "Falco internal: capture size limit reached";
+	const std::string size_cap_msg =
+	        size_cap_rule + ". Configured limit: " + std::to_string(dump_max_file_size_mb) + " MB.";
 
 	//
 	// Start capture
@@ -347,14 +354,35 @@ static falco::app::run_result do_inspect(
 		}
 
 		// Save events when a dump is in progress.
-		// If the deadline is reached, close the dump.
+		// If any stop condition is reached, close the dump.
+		// Stop conditions (first one met wins):
+		//   - per-rule time deadline (soft, extended by matching rules)
+		//   - global size cap (hard, applies to any capture)
 		if(dump_started_ts != 0) {
 			dumper->dump(ev);
-			if(ev->get_ts() > dump_deadline_ts) {
+			auto reason = check_capture_stop(ev->get_ts(),
+			                                 dump_deadline_ts,
+			                                 dumper->written_bytes(),
+			                                 dump_max_file_size_mb);
+			if(reason != capture_stop_reason::NONE) {
 				dumper->flush();
+				uint64_t written = dumper->written_bytes();
 				dumper->close();
 				dump_started_ts = 0;
 				dump_deadline_ts = 0;
+				if(reason == capture_stop_reason::SIZE_LIMIT) {
+					nlohmann::json fields;
+					fields["max_file_size_mb"] = dump_max_file_size_mb;
+					fields["written_bytes"] = written;
+					auto now = std::chrono::duration_cast<std::chrono::nanoseconds>(
+					                   std::chrono::system_clock::now().time_since_epoch())
+					                   .count();
+					s.outputs->handle_msg(now,
+					                      falco_common::PRIORITY_INFORMATIONAL,
+					                      size_cap_msg,
+					                      size_cap_rule,
+					                      fields);
+				}
 			}
 		}
 

userspace/falco/config_json_schema.h

@@ -326,7 +326,13 @@ const char config_schema_string[] = LONG_STRING_CONST(
                     ]
                 },
                 "default_duration": {
-                    "type": "integer"
+                    "type": "integer",
+                    "minimum": 0
+                },
+                "max_file_size_mb": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 1048576
                 }
             },
             "title": "Capture"

userspace/falco/configuration.cpp

@@ -100,7 +100,8 @@ falco_configuration::falco_configuration():
         m_capture_enabled(false),
         m_capture_path_prefix("/tmp/falco"),
         m_capture_mode(capture_mode_t::RULES),
-        m_capture_default_duration_ns(5000 * 1000000LL) {
+        m_capture_default_duration_ns(5000 * 1000000LL),
+        m_capture_max_file_size_mb(0) {
 	m_config_schema = nlohmann::json::parse(config_schema_string);
 }
 
@@ -621,6 +622,7 @@ void falco_configuration::load_yaml(const std::string &config_name) {
 	// Convert to nanoseconds
 	m_capture_default_duration_ns =
 	        m_config.get_scalar<uint32_t>("capture.default_duration", 5000) * 1000000LL;
+	m_capture_max_file_size_mb = m_config.get_scalar<uint64_t>("capture.max_file_size_mb", 0);
 
 	m_plugins_hostinfo = m_config.get_scalar<bool>("plugins_hostinfo", true);
 

userspace/falco/configuration.h

@@ -199,6 +199,7 @@ class falco_configuration {
 	std::string m_capture_path_prefix;
 	capture_mode_t m_capture_mode = capture_mode_t::RULES;
 	uint64_t m_capture_default_duration_ns;
+	uint64_t m_capture_max_file_size_mb;
 
 	// Falco engine
 	engine_kind_t m_engine_mode = engine_kind_t::KMOD;