[AlonLiwsky]

Overview

This enforces the file section of SandboxPolicy with a new portable BPF LSM gadget, built the same way as the privilege and network gadgets: one node-wide instance, a cgroup → policy-slot bindings map, and the policy as frozen map data. Binding changes apply live (no pod restart); a policy change replaces the instance with overlap.

It is stacked on #1073 (network gadget, which contains #1067 and #1068). GitHub can't use a fork branch as the base, so please review only the commits that are not in #1073 (git log AlonLiwsky/feat/sandbox-policy-network-gadget..; the merge commits only bring #1073 up to date), and merge after #1073.

Production code is about 3,800 lines: 2,800 in the gadget (BPF program and header, compiler, runtime), 1,000 in node-agent. Tests are about 3,600 lines.

1. The gadget — pkg/ebpf/gadgets/enforce_file/ (portable, no node-agent or Kubernetes concepts)

• Hooks per access kind:

  • read / write: lsm/file_open (by f_mode; O_TRUNC is write), path_truncate
  • create: path_mknod (covers open(O_CREAT), openat2, io_uring), path_mkdir, path_symlink, path_link
  • delete: path_unlink, path_rmdir
  • rename: path_rename (both names)
  • chmod: path_chmod, path_chown, and inode_setxattr / inode_set_acl for file capabilities and POSIX ACLs (setcap, setfacl). These two hooks have no mount, so they are judged only on the task's root filesystem; elsewhere they fail closed.
  • A create is denied at path_mknod, not at file_open. A deny at file_open would leave an empty file.

• Paths: bpf_d_path where the kernel allows it. path_mknod uses a bounded dentry walk, because bpf_d_path is refused there and bpf_path_d_path does not exist on 6.8. No kfunc is needed, so 6.8 and 6.12 run the same program.

• Matching: a component-level shift-and NFA. There is one hash lookup per path component, against frozen per-slot bit masks. Globs: literal, * (one component), ** (any depth), and one * inside a component (cron*, *.sock, rc*.d). That covers every default path class in the CRD design. The hash is FNV-1a with a random seed per instance. A Go simulator runs the same step function, and a C harness checks that the real header agrees with it.

• Moves: a link or rename source (and both names of RENAME_EXCHANGE) is judged for rename, read and write with the full decision. A new name is judged as create and write (or write and delete when it replaces a file). Renaming a parent directory of a protected path is denied at both ends. So ln /root/.aws/credentials /tmp/x, mv /root/.aws /tmp and mv /tmp/dir /root/.aws don't get around a rule.

• fromImage: an overlay file with a lower-layer origin (ovl_entry has a lower stack). A copy-up by write, chmod, touch or setxattr does not change it. The runtime checks the private ovl_inode layout in the kernel BTF; if it differs, fromImage rules are reported as not enforced instead of reading a wrong field.

• Overlay: each overlay open calls file_open twice. The second call is the backing file on an internal mount. The gadget skips it, because a deny there breaks copy-up.

• Runtime work: the shared arming rule (common/arming.h) keeps runc init, kubectl exec setup and probes out until the workload's exec. Without it, a write default deny breaks docker exec and healthchecks (oom_score_adj).

• Fail closed: a path the gadget can't resolve (too long, walk too deep, a task whose root is not its mount root after a chroot) gets the most limiting verdict of its access kind (unresolved-path).

• Merge of several policies follows common/merge/CONTRACT.md per access kind and passes its shared vectors.

• Cost for unbound containers: file_open is a hot path on every container of the node. The gadget checks the internal mount first and reads the cgroup level with plain loads (BINDINGS_DIRECT_LEVEL, opt-in in common/bindings.h; network and privilege don't change). Program time per open (bpf_stats), measured in the lab on arm64:

  	unbound, cgroup depth 2	unbound, depth 4	bound, 51 rules
  6.12	80 ns	91 ns	362–366 ns
  6.8	81 ns	104 ns	440–446 ns

  On 6.8 the first program on file_open also adds about 250 ns of trampoline cost to every open on the node, when no other LSM program uses that hook.

2. The node-agent layer — pkg/sandboxpolicy/

• The section splitter routes file to a new backend on the generic node owner. compiler.go no longer rejects the file section; identity stays rejected (separate ticket).
• Translator (file.go): per-access defaults (defaultByAccess, or the old object form of default), their modes and origins, rules with access, path, pathClass, fromImage, and except on deny rules.
• Path classes: the default classes from the CRD design (credentialStore, sshKeys, cloudConfig, shellRc, agentConfig, persistence, packageStore, containerRuntimeSocket, hostDevices), plus SandboxPolicyClasses, plus the policy's own classes.
• Symlinked paths: the kernel sees resolved paths. So a /var/run/... pattern also gets /run/...; a pattern that ends in a file name also matches the kubelet atomic-writer form dir/..*/file (Secret, ConfigMap and projected volumes); and deny rules on /bin, /sbin, /lib, /lib64 also cover /usr/... (merged-usr images). Without this, the service-account token in credentialStore never matches.
• Unresolved classes degrade as the design says: a deny rule goes to audit; an allow rule moves the defaults of its access kinds to audit, with Ready=False / ClassUnresolved. As in network, an audit-degraded deny keeps no paths, so it can't weaken its own policy's enforce default. An allow rule the gadget can't enforce does the same, with Ready=False / RuleNotEnforceable.
• Built-in allows for runtime devices (/dev/null, /dev/zero, /dev/tty, /dev/pts/**, ...) and /dev/shm/**. Identical allow rules from several policies merge, so they don't count twice against the slot limit.
• Reported as not enforced, with a reason (condition FileNotEnforced): execMap, fsType, actor on file rules, patterns the gadget can't express (?, [...], two * in one component).
• The engine passes the runtime's mount namespace to the gadget (host-mntns-id), like privilege. Without it, runc init is judged on kind and kubectl exec fails.
• Config key sandboxPolicyFileImage (default empty: the section reports FileNotConfigured).
• Small refactor: the except splitting of the local mirror moved to a shared helper, used by network and file.

How to Test

• go test ./pkg/ebpf/gadgets/... ./pkg/sandboxpolicy/...
• Kernel test, as root on a Linux host with BPF LSM: go test -tags file_kernel ./pkg/ebpf/gadgets/enforce_file/runtime/ (see the README for the env vars). I ran it on 6.8 (Ubuntu 24.04) and 6.12 (Debian 13), arm64, at cgroup depth 2 and 4. It covers every access kind, the move guard at both ends, setfacl / setcap, fromImage after copy-up, chroot, audit, docker exec and healthchecks under a write default deny, and binding changes on a running task (bind after it opened files, moves to child cgroups and out, unbind, rebind).
• In kind (Kubernetes 1.36, 6.8), live on running pods: write default deny with a workspace allow, credentialStore read deny including the projected service-account token, the hard-link and rename guard, fromImage, audit wouldDeny, unbind restoring access in about 3 s, kubectl exec and exec probes, ClassUnresolved and FileNotEnforced, two policies merged, an except entry, a Secret-volume file matched by **/.docker/config.json, setfacl / setcap under a chmod default deny, and one object with both network and file sections.

Known limits

• The file section binds when the container starts (container binding). Writes in the first moments of a container, before the bind, are not judged. Pod-level binding before start exists only for the privilege section.
• A hard link or bind mount that exists before the policy binds is a second name for the file. A path rule sees only the name used.
• A bind mount made inside a new user + mount namespace renames paths. The privilege section's user-namespace deny closes this. A chroot into a mount root (for example a volume) is not detected either.
• Renaming a parent of a floating pattern (a directory that contains .claude/) is not guarded.
• In audit mode, an open(O_CREAT) of an existing file that is not in the dentry cache can log a false create wouldDeny. The kernel drops that error, so the open works and the enforce verdict is correct.
• setcap, setfacl and cp -a with ACLs on a volume file (not the root filesystem) fail when the policy has any chmod deny. Removing an ACL is not judged. io_uring with registered credentials on a volume file is not judged for these two hooks.
• Kernel issue, not caused by the gadget: on kernels without upstream fix 61df7b828204 (v6.11), the kernel skips cap_inode_setxattr whenever BPF LSM is active, so an unprivileged task can set security.* xattrs. I reproduced it on Ubuntu 6.8 with no BPF program loaded. Ubuntu 6.8 also refuses an LSM program that returns 1, so a program can't restore the check there. Where a load probe shows that the old convention works, the gadget returns the hook default when it allows.
• On images where /lib and /usr/lib are separate directories (for example Alpine), a deny rule on /lib/** also covers /usr/lib/**, because of the merged-usr alias.
• A Secret key with a subdirectory (items[].path: a/b/file) is not covered by the atomic-writer alias.
• With overlay metacopy=on (not the containerd default) a data-only lower file is not tested.

Open questions

1. Storage fields: resolved. Storage now has defaultByAccess, defaultModeByAccess, defaultOriginByAccess and except, and the translator reads them from the storage types (the local mirror is gone). Tested in kind with the unpatched CRDs.
2. execMap: not built (mmap_file / file_mprotect). The design marks it default-off because it breaks JITs. Is it needed in this ticket?
3. Path class defined in two SandboxPolicyClasses objects: since the base's per-class errors (bae9ee5), a duplicate or broken shared path class is treated as unresolved, so only the rules that use it degrade; other policies are not affected (TestFileDuplicateSharedClassDegrades).

Tracking: SUB-9583.