feat(bpf/file): Tier-3 signal-fallback enforcement for the file class (#212)

Closes the file-class arm of Tier-3 signal-fallback, the symmetric twin
of the already-shipped network arm (handle_tp_connect). On kernels
without BPF-LSM, lsm/file_open cannot attach and open() cannot be denied
with -EPERM; previously the sys_enter_openat tracepoint was pure audit.

It now mirrors handle_tp_connect exactly: when --enforce-fallback=signal
is set (agent_cfg.signal_fallback_enforce) AND the agent is in enforce
mode, an open of a denied path is met with bpf_send_signal() (default
SIGKILL, with the same "default to SIGKILL when no escalation configured"
rule since a tracepoint cannot return -EPERM). Inert by default, so
LSM-capable hosts behave exactly as before (audit-only).

Honesty: this tier is detection+signal, not synchronous denial, and is
PATH-based (the inode is not resolvable at syscall entry) — so it does
NOT carry the inode-alias guarantee proved for lsm/file_open in
proofs/inode_alias_resistance.py. GUARANTEES.md is updated to state the
mechanism now covers both connect() and open(), and to keep the gate
promotion (accepting signal-fallback as PRIMARY enforcement on genuinely
no-LSM hosts) honestly flagged as the remaining follow-up — that step
relaxes the No-Pretend gate and must be validated on a no-LSM kernel.

Reuses the existing --enforce-fallback=signal flag (no new wiring). No
new program/section, so the bpfcompat + kernel-compat manifests are
unchanged; object builds and loads clean on 6.17. Cross-kernel
verifier-safety is gated by the bpfcompat matrix on this PR.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: ErenAri

bpf/aegis_file.bpf.h

@@ -289,6 +289,23 @@ int BPF_PROG(handle_inode_permission, struct inode *inode, int mask)
     return ret;
 }
 
+/* ============================================================================
+ * File open tracepoint.
+ *
+ * Always-on AUDIT for the path-based deny list. Additionally provides the
+ * file-class arm of Tier-3 signal-fallback enforcement (the symmetric twin of
+ * handle_tp_connect in aegis_net.bpf.h): on kernels without BPF-LSM, where
+ * lsm/file_open cannot attach and open() cannot be denied with -EPERM, an open
+ * of a denied path is met with bpf_send_signal() when signal-fallback is enabled
+ * AND the agent is in enforce mode.
+ *
+ * This is detection + signal, NOT synchronous denial, and it is PATH-based (the
+ * inode is not resolvable at syscall entry), so it is strictly weaker than the
+ * inode-based lsm/file_open deny — in particular it does NOT carry the
+ * inode-alias guarantee proved in proofs/inode_alias_resistance.py. Inert unless
+ * agent_cfg.signal_fallback_enforce is set (default off), so on LSM-capable
+ * hosts running normally it behaves exactly as before (audit-only).
+ * ============================================================================ */
 SEC("tracepoint/syscalls/sys_enter_openat")
 int handle_openat(struct trace_event_raw_sys_enter *ctx)
 {
@@ -323,7 +340,26 @@ int handle_openat(struct trace_event_raw_sys_enter *ctx)
     increment_cgroup_stat(cgid);
     increment_path_stat(&key);
 
-    /* Send block event (audit only - tracepoints can't block) */
+    /* Tier-3 signal-fallback enforcement (see header comment). A tracepoint
+     * cannot return -EPERM, so when no SIGKILL escalation is configured we
+     * default the fallback to SIGKILL to make the tier meaningful — mirroring
+     * handle_tp_connect. */
+    __u8 audit = get_effective_audit_mode();
+    __u8 enforce_signal = 0;
+    if (agent_cfg.signal_fallback_enforce && !audit) {
+        __u64 start_time = task ? BPF_CORE_READ(task, start_time) : 0;
+        __u8 configured_signal = get_effective_enforce_signal();
+        if (configured_signal == SIGKILL) {
+            enforce_signal = runtime_enforce_signal(configured_signal, pid, start_time,
+                                                    get_sigkill_escalation_threshold(),
+                                                    get_sigkill_escalation_window_ns());
+        } else {
+            enforce_signal = configured_signal ? configured_signal : SIGKILL;
+        }
+        maybe_send_enforce_signal(enforce_signal);
+    }
+
+    /* Send block event */
     if (!should_emit_event(sample_rate))
         return 0;
     struct event *e = bpf_ringbuf_reserve(&events, sizeof(*e), 0);
@@ -335,7 +371,7 @@ int handle_openat(struct trace_event_raw_sys_enter *ctx)
         e->block.ino = 0;
         e->block.dev = 0;
         __builtin_memcpy(e->block.path, key.path, sizeof(e->block.path));
-        __builtin_memcpy(e->block.action, "AUDIT", sizeof("AUDIT"));
+        set_action_string(e->block.action, audit ? 1 : 0, enforce_signal);
         bpf_ringbuf_submit(e, 0);
     } else {
         increment_ringbuf_drops();

docs/GUARANTEES.md

@@ -132,19 +132,28 @@ see `docs/THREAT_MODEL.md`.
 
 ### Signal-fallback enforcement is opt-in and signal-based
 
-- On kernels without BPF-LSM, `connect()` cannot be denied with `-EPERM`. The
-  opt-in `--enforce-fallback=signal` flag attaches a `sys_enter_connect`
-  tracepoint that, in enforce mode, terminates a process connecting to a denied
-  endpoint via `bpf_send_signal()` (default `SIGKILL`).
-- This is signal-based termination, not synchronous denial: the `connect()` may
-  partially proceed before the signal is delivered on syscall return. Protocol is
-  not resolvable at syscall entry, so only protocol-agnostic rules are evaluated.
-- Verified to fire (`SIGKILL`, `net_connect_block` action=`KILL`) on a connect to
-  a denied IP. NOTE: when BPF-LSM is genuinely absent the enforce-gate currently
-  treats the missing LSM hook as a degradation (fail-closed exit or audit
-  fallback); teaching the gate to accept signal-fallback as primary connect
-  enforcement on no-LSM hosts is a follow-up. Today the tier is verified as
-  defense-in-depth alongside LSM enforcement.
+- On kernels without BPF-LSM, `connect()` and `open()` cannot be denied with
+  `-EPERM`. The opt-in `--enforce-fallback=signal` flag arms two symmetric
+  syscall tracepoints — `sys_enter_connect` (network) and `sys_enter_openat`
+  (file) — that, in enforce mode, terminate a process reaching a denied endpoint
+  or opening a denied path via `bpf_send_signal()` (default `SIGKILL`).
+- This is signal-based termination, not synchronous denial: the syscall may
+  partially proceed before the signal is delivered on syscall return. It is also
+  evaluated on the *syscall-entry* view — protocol is not resolvable for
+  `connect()` (protocol-agnostic rules only), and the file path is matched
+  by-path rather than by-inode, so the file arm does **not** carry the
+  inode-alias guarantee that the `lsm/file_open` deny does (proved in
+  `proofs/inode_alias_resistance.py`). Signal-fallback is a strictly weaker tier.
+- The network arm is verified to fire (`SIGKILL`, `net_connect_block`
+  action=`KILL`) on a connect to a denied IP; the file arm mirrors it on an open
+  of a denied path.
+- **Gate status (honest):** when BPF-LSM is genuinely absent the enforce-gate
+  still treats the missing LSM hook as a degradation (fail-closed exit or audit
+  fallback) — it does not yet *promote* signal-fallback to primary enforcement on
+  no-LSM hosts, because doing so safely requires validating the relaxed
+  No-Pretend gate on a no-LSM kernel. Today both arms are verified as
+  defense-in-depth alongside LSM enforcement; gate promotion is the remaining
+  follow-up.
 
 ## Known bypass classes