feat!: isolate modern probe TOCTOU mitigation logic

Current TOCTOU mitigation implementation leverages the enter events
generated by eBPF programs which are tail-called by the `sys_enter`
dispatcher. As the architecture is moving towards dropping enter
event generation and collection, the `sys_enter` dispatcher will
be ultimately removed. This requires to isolate TOCTOU mitigation
handling logic in order to make it independent from `sys_enter`
dispatcher removal.

This patch moves TOCTOU mitigation handling logic into separate
ad-hoc eBPF tracepoint programs attached on corresponding
`syscalls/sys_enter_*` hooks.

For each system call `<syscall>` that already supports TOCTOU
mitigation, two eBPF tracepoint programs are defined:
- `ttm_<syscall>_e` - this program is responsible for tail calling
  the `<syscall>_e` program after having performed syscall ID
  normalization and applied any required sampling/filtering logic
- `<syscall>_e` - this program is responsible for collecting the
  information needed to generate the proper enter event and sending
  the generated event to userspace

Tail-called TOCTOU mitigation programs are inserted into a separate
tail call map, called `syscall_enter_toctou_mitigation_tail_table`.

As the tracepoint attachment procedure generates an `openat` exit
event on `/sys/kernel/tracing/events/.../id` that would pollute the
stream of events read by the probe, the implementation takes care
of attaching them before attaching the `sys_exit` dispatcher.

Notice that the new logic make the TOCTOU mitigation programs
attachment dependent on the presence of the `sys_exit` dispatcher.

BREAKING CHANGE: change prerequisites for attaching some enter progs

Signed-off-by: Leonardo Di Giovanna <[email protected]>

Author: ekoops

driver/modern_bpf/helpers/interfaces/syscalls_dispatcher.h

@@ -13,14 +13,42 @@
 #include <helpers/base/read_from_task.h>
 #include <helpers/extract/extract_from_kernel.h>
 
+// We don't want to send DROP_E/DROP_X events from the enter tracepoint because it would requires us
+// to create a dedicated tail table for the enter. It is enough to send DROP_E/DROP_X events from
+// the exit tracepoint.
+static __always_inline bool syscalls_dispatcher__sampling_logic_enter(uint32_t syscall_id) {
+	/* If dropping mode is not enabled we don't perform any sampling
+	 * false: means don't drop the syscall
+	 * true: means drop the syscall
+	 */
+	if(!maps__get_dropping_mode()) {
+		return false;
+	}
+
+	uint8_t sampling_flag = maps__64bit_sampling_syscall_table(syscall_id);
+
+	if(sampling_flag == UF_NEVER_DROP) {
+		return false;
+	}
+
+	if(sampling_flag == UF_ALWAYS_DROP) {
+		return true;
+	}
+
+	// If we are in the sampling period we drop the event
+	if((bpf_ktime_get_boot_ns() % SECOND_TO_NS) >= (SECOND_TO_NS / maps__get_sampling_ratio())) {
+		return true;
+	}
+
+	return false;
+}
+
 static __always_inline bool syscalls_dispatcher__64bit_interesting_syscall(uint32_t syscall_id) {
 	return maps__interesting_syscall_64bit(syscall_id);
 }
 
-static __always_inline long convert_network_syscalls(struct pt_regs *regs) {
-	int socketcall_id = (int)extract__syscall_argument(regs, 0);
-
-	switch(socketcall_id) {
+static __always_inline long convert_socketcall_call_to_syscall_id(int socketcall_call) {
+	switch(socketcall_call) {
 #ifdef __NR_socket
 	case SYS_SOCKET:
 		return __NR_socket;

driver/modern_bpf/helpers/interfaces/toctou_mitigation.h

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: GPL-2.0-only OR MIT
+/*
+ * Copyright (C) 2025 The Falco Authors.
+ *
+ * This file is dual licensed under either the MIT or GPL 2. See MIT.txt
+ * or GPL2.txt for full copies of the license.
+ */
+
+#pragma once
+
+#include <helpers/interfaces/syscalls_dispatcher.h>
+#include <helpers/interfaces/variable_size_event.h>
+
+/**
+ * @brief Tail call the TOCTOU mitigation program corresponding to the specified program code.
+ *
+ * @param ctx is the original program context
+ * @param syscall_id is the original system call id that triggered the program
+ * @param socketcall_call (socketcall-only) is the call argument provided to the socketcall system
+ call  (e.g.: SYS_CONNECT)
+ * @param prog_code is the program code identifying the TOCTOU mitigation program to be called
+
+ * @return never returns in case of success; otherwise, returns 0
+ */
+static __always_inline int toctou_mitigation__call_prog(
+        void *ctx,
+        uint32_t syscall_id,
+        int socketcall_call,
+        enum sys_enter_toctou_mitigation_prog_code prog_code) {
+	int socketcall_syscall_id = -1;
+
+	if(bpf_in_ia32_syscall()) {
+#if defined(__TARGET_ARCH_x86)
+		if(syscall_id == __NR_ia32_socketcall) {
+			socketcall_syscall_id = __NR_ia32_socketcall;
+		} else {
+			syscall_id = maps__ia32_to_64(syscall_id);
+			// Syscalls defined only on 32 bits are dropped here.
+			if(syscall_id == (uint32_t)-1) {
+				return 0;
+			}
+		}
+#else
+		return 0;
+#endif
+	} else {
+#ifdef __NR_socketcall
+		socketcall_syscall_id = __NR_socketcall;
+#endif
+	}
+
+	// Convert the socketcall id into the network syscall id.
+	// In this way the syscall will be treated exactly as the original one.
+	if(syscall_id == socketcall_syscall_id) {
+		syscall_id = convert_socketcall_call_to_syscall_id(socketcall_call);
+		if(syscall_id == -1) {
+			// We can't do anything since modern bpf filler jump table is syscall indexed.
+			return 0;
+		}
+	}
+
+	if(!syscalls_dispatcher__64bit_interesting_syscall(syscall_id)) {
+		return 0;
+	}
+
+	if(syscalls_dispatcher__sampling_logic_enter(syscall_id)) {
+		return 0;
+	}
+
+	bpf_tail_call(ctx, &syscall_enter_toctou_mitigation_tail_table, prog_code);
+	bpf_printk("unable to tail call into TTM prog (prog_code: %d)", prog_code);
+	return 0;
+}
+
+static __always_inline void toctou_mitigation__push_connect_enter_event(
+        struct auxiliary_map *auxmap,
+        int64_t socket_fd,
+        unsigned long usrsockaddr,
+        uint16_t usrsockaddr_len) {
+	auxmap__preload_event_header(auxmap, PPME_SOCKET_CONNECT_E);
+
+	/*=============================== COLLECT PARAMETERS  ===========================*/
+
+	/* Parameter 1: fd (type: PT_FD) */
+	auxmap__store_s64_param(auxmap, socket_fd);
+
+	/* Parameter 2: addr (type: PT_SOCKADDR) */
+	auxmap__store_sockaddr_param(auxmap, usrsockaddr, usrsockaddr_len);
+
+	/*=============================== COLLECT PARAMETERS  ===========================*/
+
+	auxmap__finalize_event_header(auxmap);
+
+	auxmap__submit_event(auxmap);
+}

driver/modern_bpf/maps/maps.h

@@ -104,6 +104,18 @@ struct {
 	__type(value, uint32_t);
 } syscall_exit_tail_table __weak SEC(".maps");
 
+/**
+ * @brief This tail table is used by the TOCTOU mitigation sys_enter_* programs.
+ * Given a predefined tail-code (`sys_enter_toctou_mitigation_prog_code`), they call
+ * the right bpf program to generate the proper TOCTOU mitigation event.
+ */
+struct {
+	__uint(type, BPF_MAP_TYPE_PROG_ARRAY);
+	__uint(max_entries, SYS_ENTER_TOCTOU_MITIGATION_PROG_CODE_MAX);
+	__type(key, uint32_t);
+	__type(value, uint32_t);
+} syscall_enter_toctou_mitigation_tail_table __weak SEC(".maps");
+
 /**
  * @brief This tail table is used when a sys exit bpf program needs another program
  * to complete its execution flow.

driver/modern_bpf/programs/attached/dispatchers/syscall_enter.bpf.c

@@ -8,36 +8,6 @@
 
 #include <helpers/interfaces/syscalls_dispatcher.h>
 
-// We don't want to send DROP_E/DROP_X events from the enter tracepoint because it would requires us
-// to create a dedicated tail table for the enter. It is enough to send DROP_E/DROP_X events from
-// the exit tracepoint.
-static __always_inline bool sampling_logic_enter(void* ctx, uint32_t id) {
-	/* If dropping mode is not enabled we don't perform any sampling
-	 * false: means don't drop the syscall
-	 * true: means drop the syscall
-	 */
-	if(!maps__get_dropping_mode()) {
-		return false;
-	}
-
-	uint8_t sampling_flag = maps__64bit_sampling_syscall_table(id);
-
-	if(sampling_flag == UF_NEVER_DROP) {
-		return false;
-	}
-
-	if(sampling_flag == UF_ALWAYS_DROP) {
-		return true;
-	}
-
-	// If we are in the sampling period we drop the event
-	if((bpf_ktime_get_boot_ns() % SECOND_TO_NS) >= (SECOND_TO_NS / maps__get_sampling_ratio())) {
-		return true;
-	}
-
-	return false;
-}
-
 /* From linux tree: /include/trace/events/syscall.h
  * TP_PROTO(struct pt_regs *regs, long id),
  */
@@ -65,20 +35,44 @@ int BPF_PROG(sys_enter, struct pt_regs* regs, long syscall_id) {
 #endif
 	}
 
-	/* we convert it here in this way the syscall will be treated exactly as the original one */
+	/* We convert it here in this way the syscall will be treated exactly as the original one. */
 	if(syscall_id == socketcall_syscall_id) {
-		syscall_id = convert_network_syscalls(regs);
+		int socketcall_call = (int)extract__syscall_argument(regs, 0);
+		syscall_id = convert_socketcall_call_to_syscall_id(socketcall_call);
 		if(syscall_id == -1) {
 			// We can't do anything since modern bpf filler jump table is syscall indexed
 			return 0;
 		}
 	}
 
+	// The following system calls are already handled by TOCTOU mitigation programs and will not
+	// have an entry in the syscall enter tail table, so simply return early, avoiding wasting
+	// resources on any additional filtering logic.
+	switch(syscall_id) {
+#if defined(__NR_connect) || defined(__NR_creat) || defined(__NR_open) || defined(__NR_openat)
+#ifdef __NR_connect
+	case __NR_connect:
+#endif  // __NR_connect
+#ifdef __NR_creat
+	case __NR_creat:
+#endif  // __NR_creat
+#ifdef __NR_open
+	case __NR_open:
+#endif  // __NR_open
+#ifdef __NR_openat
+	case __NR_openat:
+#endif  // __NR_openat
+		return 0;
+#endif  // __NR_connect ||__NR_creat || __NR_open || __NR_openat
+	default:
+		break;
+	}
+
 	if(!syscalls_dispatcher__64bit_interesting_syscall(syscall_id)) {
 		return 0;
 	}
 
-	if(sampling_logic_enter(ctx, syscall_id)) {
+	if(syscalls_dispatcher__sampling_logic_enter(syscall_id)) {
 		return 0;
 	}
 

driver/modern_bpf/programs/attached/dispatchers/syscall_exit.bpf.c

@@ -207,9 +207,10 @@ int BPF_PROG(sys_exit, struct pt_regs *regs, long ret) {
 #endif
 	}
 
-	/* we convert it here in this way the syscall will be treated exactly as the original one */
+	/* We convert it here in this way the syscall will be treated exactly as the original one. */
 	if(syscall_id == socketcall_syscall_id) {
-		syscall_id = convert_network_syscalls(regs);
+		int socketcall_call = (int)extract__syscall_argument(regs, 0);
+		syscall_id = convert_socketcall_call_to_syscall_id(socketcall_call);
 		if(syscall_id == -1) {
 			// We can't do anything since modern bpf filler jump table is syscall indexed
 			return 0;

driver/modern_bpf/programs/attached/events/toctou_mitigation/README.md

@@ -0,0 +1,11 @@
+# TOCTOU mitigation programs
+
+eBPF programs in this folder generates enter events providing support to exit events data for TOCTOU mitigation.
+
+All programs are attached to specific `tracepoint/syscalls/sys_enter_*` hooks.
+
+For each system call `<syscall>`, two eBPF tracepoint programs are defined:
+- `ttm_<syscall>_e` - this program is responsible for tail calling the `<syscall>_e` program after having performed
+  syscall ID normalization and applied any required sampling/filtering logic
+- `<syscall>_e` - this program is responsible for collecting the information needed to generate the proper enter event
+  and sending the generated event to userspace

driver/modern_bpf/programs/attached/events/toctou_mitigation/sys_enter_connect.bpf.c

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: GPL-2.0-only OR MIT
+/*
+ * Copyright (C) 2025 The Falco Authors.
+ *
+ * This file is dual licensed under either the MIT or GPL 2. See MIT.txt
+ * or GPL2.txt for full copies of the license.
+ */
+
+#include <helpers/interfaces/toctou_mitigation.h>
+
+// This struct is defined according to the following format file:
+// /sys/kernel/tracing/events/syscalls/sys_enter_connect/format
+struct sys_enter_connect_args {
+	uint64_t pad1;
+
+	uint32_t __syscall_nr;
+	uint32_t pad2;
+	uint64_t fd;
+	uint64_t uservaddr;
+	uint64_t addrlen;
+};
+
+/*=============================== ENTER DISPATCHER ===========================*/
+
+SEC("tracepoint/syscalls/sys_enter_connect")
+int connect_e(struct sys_enter_connect_args* ctx) {
+	return toctou_mitigation__call_prog(ctx, ctx->__syscall_nr, -1, TTM_CONNECT_E);
+}
+
+/*=============================== ENTER DISPATCHER ===========================*/
+
+/*=============================== ENTER EVENT ===========================*/
+
+SEC("tracepoint/syscalls/sys_enter_connect")
+int ttm_connect_e(struct sys_enter_connect_args* ctx) {
+	struct auxiliary_map* auxmap = auxmap__get();
+	if(!auxmap) {
+		return 0;
+	}
+
+	/* Extract syscall arguments from context. */
+	int64_t socket_fd = (int64_t)(int32_t)ctx->fd;
+	unsigned long usrsockaddr = (unsigned long)ctx->uservaddr;
+	uint16_t usrsockaddr_len = (uint16_t)ctx->addrlen;
+
+	toctou_mitigation__push_connect_enter_event(auxmap, socket_fd, usrsockaddr, usrsockaddr_len);
+	return 0;
+}
+
+/*=============================== ENTER EVENT ===========================*/

driver/modern_bpf/programs/attached/events/toctou_mitigation/sys_enter_creat.bpf.c

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: GPL-2.0-only OR MIT
+/*
+ * Copyright (C) 2025 The Falco Authors.
+ *
+ * This file is dual licensed under either the MIT or GPL 2. See MIT.txt
+ * or GPL2.txt for full copies of the license.
+ */
+
+#include <helpers/interfaces/toctou_mitigation.h>
+#include <helpers/interfaces/variable_size_event.h>
+
+// This struct is defined according to the following format file:
+// /sys/kernel/tracing/events/syscalls/sys_enter_creat/format
+struct sys_enter_creat_args {
+	uint64_t pad;
+
+	uint32_t __syscall_nr;
+	uint64_t filename;
+	uint64_t mode;
+};
+
+/*=============================== ENTER DISPATCHER ===========================*/
+
+SEC("tracepoint/syscalls/sys_enter_creat")
+int creat_e(struct sys_enter_creat_args* ctx) {
+	return toctou_mitigation__call_prog(ctx, ctx->__syscall_nr, -1, TTM_CREAT_E);
+}
+
+/*=============================== ENTER DISPATCHER ===========================*/
+
+/*=============================== ENTER EVENT ===========================*/
+
+SEC("tracepoint/syscalls/sys_enter_creat")
+int ttm_creat_e(struct sys_enter_creat_args* ctx) {
+	struct auxiliary_map* auxmap = auxmap__get();
+	if(!auxmap) {
+		return 0;
+	}
+
+	auxmap__preload_event_header(auxmap, PPME_SYSCALL_CREAT_E);
+
+	/*=============================== COLLECT PARAMETERS  ===========================*/
+
+	/* Parameter 1: name (type: PT_FSPATH) */
+	unsigned long name_pointer = (unsigned long)ctx->filename;
+	auxmap__store_charbuf_param(auxmap, name_pointer, MAX_PATH, USER);
+
+	/* Parameter 2: mode (type: PT_UINT32) */
+	unsigned long mode = (unsigned long)ctx->mode;
+	auxmap__store_u32_param(auxmap, open_modes_to_scap(O_CREAT, mode));
+
+	/*=============================== COLLECT PARAMETERS  ===========================*/
+
+	auxmap__finalize_event_header(auxmap);
+
+	auxmap__submit_event(auxmap);
+
+	return 0;
+}
+
+/*=============================== ENTER EVENT ===========================*/