LSM Hooks Reference

BPF LSM (Linux Security Module) hooks run at kernel security decision points before the kernel completes an operation. They are the correct place for Override actions that need to deny an operation before the process can execute it, as opposed to kprobe-based Signal actions that kill a process after the hook point has been crossed.

Requires: Linux kernel 5.8 or later with CONFIG_BPF_LSM=y and lsm=...,bpf in the kernel configuration or boot parameters. Without this, LSM hooks load but Override actions are unavailable. See Requirements for how to verify kernel support.

---

Always-on LSM hooks (baseline policy)

The sensor writes and loads telovix-lsm-baseline.yaml at startup. This policy is active in all enforcement states on all supported kernels. The following four hooks are always active when BPF LSM is available:

Hook name	Event kind	Default severity	What it monitors
file_open	lsm_file_open	info	File open at the security decision point for sensitive credential, configuration, and persistence paths
bprm_check_security	lsm_exec	info (or critical when masquerade indicators are present)	Executable launch at the execve security check
task_fix_setuid	lsm_setuid	high (or info for known container runtimes)	UID change via SUID binary execution at the kernel security decision point
kernel_read_file	lsm_kernel_read	warning (or kmod_file_read when id=3)	Kernel file read operations; id=3 maps to kernel module loading

Why security_socket_connect is not in the baseline

The security_socket_connect LSM hook (socket_connect in TracingPolicy YAML) is intentionally not included in the always-on baseline policy. On ARM64 and some x86 kernels, loading this hook causes the entire policy to fail. Losing all LSM observation (bprm_check_security, file_open, task_fix_setuid) to gain lsm_net_connect events is not acceptable. This hook can be added in custom rules where the target kernel is known to support it.

---

Hook reference

file_open

Event kind: lsm_file_openSeverity: infoArg type: file (index 0)

Fires at the security_file_open kernel hook when a process opens a file. The baseline policy monitors reads of credential files, shell startup scripts, PAM libraries, SSH keys, cron directories, systemd units, udev rules, kernel module paths, and /proc/1/ns/.

Key monitored paths in the baseline (Prefix match):

• /etc/shadow, /etc/sudoers, /etc/sudoers.d/, /etc/pam.d/
• /root/.ssh, /.ssh/id_*, /authorized_keys*
• /etc/crontab, /etc/cron.d/, /var/spool/cron/
• /etc/profile, /etc/profile.d/, /etc/bash.bashrc, /etc/environment
• /etc/init.d/, /etc/rc.local, /etc/systemd/system/ (indirectly via other policies)
• /lib/security/, /usr/lib/security/ (PAM module directories)
• /lib/modules/, /etc/modprobe.d/
• /proc/sysrq-trigger, /proc/1/root, /proc/1/ns/
• Per-user shell config files (Postfix match on /.bashrc, /.zshrc, etc.)
• SSH private key files (Postfix match on /.ssh/id_rsa, /.ssh/id_ed25519, etc.)
• Kerberos and SSSD credential files

YAML template:

lsmhooks:
  - hook: file_open
    args:
      - index: 0
        type: file
    selectors:
      - matchArgs:
          - index: 0
            operator: Prefix
            values:
              - /etc/shadow
              - /etc/sudoers
        matchActions:
          - action: Post

---

bprm_check_security

Event kind: lsm_execSeverity: info (elevated to critical when masquerade indicators are detected) Arg type: linux_binprm (index 0)

Fires at the bprm_check_security kernel security hook when a process is about to be executed via execve. This hook fires before the new executable image is loaded into memory, making it the correct place for blocking execution from untrusted paths.

The baseline policy monitors execution from /tmp/, /dev/, and /var/tmp/ with a Post action.

::: note The arg type for bprm_check_security is linux_binprm, not bprm. Using bprm will cause the policy to load but matchArgs will silently never fire. :::

YAML template:

lsmhooks:
  - hook: bprm_check_security
    args:
      - index: 0
        type: linux_binprm
    selectors:
      - matchArgs:
          - index: 0
            operator: Prefix
            values:
              - /tmp/
              - /dev/shm/
        matchActions:
          - action: Override
            argError: -1

Override with argError: -1 is valid on this hook and blocks the execution before the new process image loads.

---

task_fix_setuid

Event kind: lsm_setuidSeverity: high (or info for known container runtimes: runc, crun, containerd, podman, buildah, and related) Args: none required in the baseline

Fires at the task_fix_setuid kernel hook when the kernel changes a process's UID via a SUID binary execution. This hook fires more reliably than sys_setuid kprobes for SUID transitions because it runs at the security decision point where the kernel applies the UID change, not at the syscall boundary.

The baseline policy monitors all SUID transitions without filtering, using Post action.

YAML template:

lsmhooks:
  - hook: task_fix_setuid
    selectors:
      - matchActions:
          - action: Post

No args: block is needed for a catch-all observer. Add args: only when using matchArgs to filter on specific UIDs.

---

kernel_read_file

Event kind: lsm_kernel_read (or kmod_file_read when the read type is 3, i.e. kernel module loading) Severity: warningArgs: file (index 0), int (index 1, the kernel_read_type enum value)

Fires at the kernel_read_file LSM hook when the kernel reads a file during security-sensitive operations. The most important value is index 1 = 3, which corresponds to READING_MODULE (kernel module loading). The baseline policy monitors only this case.

YAML template (kernel module load monitoring):

lsmhooks:
  - hook: kernel_read_file
    args:
      - index: 0
        type: file
      - index: 1
        type: int
    selectors:
      - matchArgs:
          - index: 1
            operator: Equal
            values:
              - "3"
        matchActions:
          - action: Post

To block kernel module loading with Override:

matchActions:
  - action: Override
    argError: -1

---

socket_connect (security_socket_connect)

Event kind: lsm_net_connectSeverity: infoKernel requirement: Available on kernel 5.8+ with BPF LSM, but excluded from the always-on baseline due to load failures on some kernels. Use only in custom rules where the target kernel is verified to support it.

Fires at the security_socket_connect hook when a process attempts a socket connect. Provides network connection monitoring at the LSM layer rather than via tcp_connect kprobes.

YAML template:

lsmhooks:
  - hook: socket_connect
    selectors:
      - matchActions:
          - action: Post

---

sb_mount

Event kind: lsm_mountSeverity: warning

Fires at the sb_mount LSM hook when a filesystem is mounted. Available for custom rules.

---

userns_create

Event kind: lsm_eventUsed by: enforcement template block-user-namespace

Fires when a new user namespace is created (CLONE_NEWUSER). User namespace creation is a common initial step in container escape and privilege escalation attacks.

---

ptrace_access_check

Event kind: enforcement_kill (when enforcement action fires) Used by: enforcement template kill-ptrace-attach

Fires at ptrace access security check. Used in the kill-ptrace-attach enforcement template to kill processes that attempt to attach a debugger.

---

kernel_module_request

Event kind: lsm_kmod_requestSeverity: critical

Fires when the kernel calls request_module() to autoload a kernel module. This is distinct from kernel_read_file which fires when the module file is actually read. Emitted as lsm_kmod_request.

---

Hook-to-event-kind mapping

TracingPolicy hook name	Event kind	Notes
file_open	lsm_file_open
bprm_check_security	lsm_exec
socket_connect	lsm_net_connect	Not in baseline; use in custom rules only
task_fix_setuid	lsm_setuid
sb_mount	lsm_mount
kernel_read_file	lsm_kernel_read or kmod_file_read	kmod_file_read when read type arg = 3
kernel_module_request	lsm_kmod_request
userns_create	lsm_event
ptrace_access_check	lsm_event or enforcement_kill
(any other)	lsm_event

---

Supported arg types for lsmhooks

Type string	Used for
file	File object arguments (file_open, kernel_read_file arg 0)
linux_binprm	Binary program argument (bprm_check_security arg 0)
int	Integer enum values (kernel_read_file arg 1)

---

Common authoring mistakes

Missing args on a hook that uses matchArgs

If an lsmhooks entry uses matchArgs selectors but has no args array, Tetragon cannot resolve the argument types. The policy loads and appears active, but the selector never fires. The Console validation catches this and returns a lsmhook_missing_args error.

Wrong type for bprm_check_security

The first argument type is linux_binprm, not bprm. Using bprm loads without error but matchArgs on that argument silently fails.

Mixing kprobes and lsmhooks in one policy

Do not combine both sections in a single TracingPolicy. Create two separate rules to allow independent validation and rollback.

Loading socket_connect on unsupported kernels

On ARM64 and some x86 kernels, security_socket_connect causes the entire policy load to fail. Verify kernel support before adding this hook to a policy that contains other hooks.

---

Further reading

• Custom Detection Rules
• Kprobes Reference
• Enforcement Mode
• Requirements
• Linux kernel documentation - BPF LSM
• Linux Security Module (LSM) framework - kernel.org