1.. SPDX-License-Identifier: GPL-2.0 2.. Copyright © 2025 Microsoft Corporation 3.. Copyright © 2026 Cloudflare, Inc. 4 5================================ 6Landlock: system-wide management 7================================ 8 9:Author: Mickaël Salaün 10:Date: October 2026 11 12Landlock can leverage the audit framework to log events. 13 14User space documentation can be found here: 15Documentation/userspace-api/landlock.rst. 16 17Audit 18===== 19 20Denied access requests are logged by default for a sandboxed program if `audit` 21is enabled. This default behavior can be changed with the 22sys_landlock_restrict_self() flags (cf. 23Documentation/userspace-api/landlock.rst), suppressed on a per-object 24basis by using ``LANDLOCK_ADD_RULE_QUIET`` (ABI 10+), or suppressed for 25specific capability or namespace members with the corresponding permission 26rule's ``quiet_*`` field (ABI 12+). Quiet rules only suppress audit submission; 27they do not suppress denial trace events. Landlock logs can also be masked 28thanks to audit rules. Landlock can generate two audit record types. 29 30Record types 31------------ 32 33AUDIT_LANDLOCK_ACCESS 34 This record type identifies a denied access request to a kernel resource. 35 The ``domain`` field indicates the ID of the domain that blocked the 36 request. The ``blockers`` field indicates the cause(s) of this denial 37 (separated by a comma), and the following fields identify the kernel object 38 (similar to SELinux). There may be more than one of this record type per 39 audit event. 40 41 Example with a file link request generating two records in the same event:: 42 43 domain=195ba459b blockers=fs.refer path="/usr/bin" dev="vda2" ino=351 44 domain=195ba459b blockers=fs.make_reg,fs.refer path="/usr/local" dev="vda2" ino=365 45 46 47 The ``blockers`` field uses dot-separated prefixes to indicate the type of 48 restriction that caused the denial: 49 50 **fs.*** - Filesystem access rights (ABI 1+): 51 - fs.execute, fs.write_file, fs.read_file, fs.read_dir 52 - fs.remove_dir, fs.remove_file 53 - fs.make_char, fs.make_dir, fs.make_reg, fs.make_sock 54 - fs.make_fifo, fs.make_block, fs.make_sym 55 - fs.refer (ABI 2+) 56 - fs.truncate (ABI 3+) 57 - fs.ioctl_dev (ABI 5+) 58 - fs.resolve_unix (ABI 9+) 59 60 **net.*** - Network access rights (ABI 4+): 61 - net.bind_tcp - TCP port binding was denied 62 - net.connect_tcp - TCP connection was denied 63 - net.bind_udp - UDP port binding was denied 64 - net.connect_send_udp - UDP connection and send was denied 65 66 **scope.*** - IPC scoping restrictions (ABI 6+): 67 - scope.abstract_unix_socket - Abstract UNIX socket connection denied 68 - scope.signal - Signal sending denied 69 70 **namespace.*** - Namespace restrictions (ABI 12+): 71 - namespace.use - Namespace use was denied (creation via 72 :manpage:`unshare(2)`, :manpage:`clone(2)`, :manpage:`clone3(2)`, 73 :manpage:`open_tree(2)`, or :manpage:`fsmount(2)`, or joining via 74 :manpage:`setns(2)`); 75 ``namespace_type`` indicates the type (hex ``CLONE_NEW*`` bitmask), 76 and ``namespace_id`` identifies the target namespace for 77 :manpage:`setns(2)` operations (zero for creation) 78 79 **capability.*** - Capability restrictions (ABI 12+): 80 - capability.use - Capability use was denied; 81 ``capability`` indicates the capability number 82 83 Multiple blockers can appear in a single event (comma-separated) when 84 multiple access rights are missing. For example, creating a regular file 85 in a directory that lacks both ``make_reg`` and ``refer`` rights would show 86 ``blockers=fs.make_reg,fs.refer``. 87 88 The object identification fields depend on the type of access being blocked: 89 ``path``, ``dev``, ``ino`` for filesystem; ``opid``, ``ocomm`` for signals; 90 ``namespace_type`` and ``namespace_id`` for namespace operations; 91 ``capability`` for capability use. 92 93 94AUDIT_LANDLOCK_DOMAIN 95 This record type describes the status of a Landlock domain. The ``status`` 96 field can be either ``allocated`` or ``deallocated``. 97 98 The ``allocated`` status is part of the same audit event and follows 99 the first logged ``AUDIT_LANDLOCK_ACCESS`` record of a domain. It identifies 100 Landlock domain information at the time of the sys_landlock_restrict_self() 101 call with the following fields: 102 103 - the ``domain`` ID 104 - the enforcement ``mode`` 105 - the domain creator's ``pid`` 106 - the domain creator's ``uid`` 107 - the domain creator's executable path (``exe``) 108 - the domain creator's command line (``comm``) 109 110 Example:: 111 112 domain=195ba459b status=allocated mode=enforcing pid=300 uid=0 exe="/root/sandboxer" comm="sandboxer" 113 114 The ``deallocated`` status is an event on its own and it identifies a 115 Landlock domain release. After such event, it is guarantee that the 116 related domain ID will never be reused during the lifetime of the system. 117 The ``domain`` field indicates the ID of the domain which is released, and 118 the ``denials`` field indicates the total number of denied access request, 119 which might not have been logged according to the audit rules and 120 sys_landlock_restrict_self()'s flags. 121 122 Example:: 123 124 domain=195ba459b status=deallocated denials=3 125 126 127Event samples 128-------------- 129 130Here are two examples of log events (see serial numbers). 131 132In this example a sandboxed program (``kill``) tries to send a signal to the 133init process, which is denied because of the signal scoping restriction 134(``LL_SCOPED=s``):: 135 136 $ LL_FS_RO=/ LL_FS_RW=/ LL_SCOPED=s LL_FORCE_LOG=1 ./sandboxer kill 1 137 138This command generates two events, each identified with a unique serial 139number following a timestamp (``msg=audit(1729738800.268:30)``). The first 140event (serial ``30``) contains 4 records. The first record 141(``type=LANDLOCK_ACCESS``) shows an access denied by the domain `1a6fdc66f`. 142The cause of this denial is signal scoping restriction 143(``blockers=scope.signal``). The process that would have receive this signal 144is the init process (``opid=1 ocomm="systemd"``). 145 146The second record (``type=LANDLOCK_DOMAIN``) describes (``status=allocated``) 147domain `1a6fdc66f`. This domain was created by process ``286`` executing the 148``/root/sandboxer`` program launched by the root user. 149 150The third record (``type=SYSCALL``) describes the syscall, its provided 151arguments, its result (``success=no exit=-1``), and the process that called it. 152 153The fourth record (``type=PROCTITLE``) shows the command's name as an 154hexadecimal value. This can be translated with ``python -c 155'print(bytes.fromhex("6B696C6C0031"))'``. 156 157Finally, the last record (``type=LANDLOCK_DOMAIN``) is also the only one from 158the second event (serial ``31``). It is not tied to a direct user space action 159but an asynchronous one to free resources tied to a Landlock domain 160(``status=deallocated``). This can be useful to know that the following logs 161will not concern the domain ``1a6fdc66f`` anymore. This record also summarize 162the number of requests this domain denied (``denials=1``), whether they were 163logged or not. 164 165.. code-block:: 166 167 type=LANDLOCK_ACCESS msg=audit(1729738800.268:30): domain=1a6fdc66f blockers=scope.signal opid=1 ocomm="systemd" 168 type=LANDLOCK_DOMAIN msg=audit(1729738800.268:30): domain=1a6fdc66f status=allocated mode=enforcing pid=286 uid=0 exe="/root/sandboxer" comm="sandboxer" 169 type=SYSCALL msg=audit(1729738800.268:30): arch=c000003e syscall=62 success=no exit=-1 [..] ppid=272 pid=286 auid=0 uid=0 gid=0 [...] comm="kill" [...] 170 type=PROCTITLE msg=audit(1729738800.268:30): proctitle=6B696C6C0031 171 type=LANDLOCK_DOMAIN msg=audit(1729738800.324:31): domain=1a6fdc66f status=deallocated denials=1 172 173Here is another example showcasing filesystem access control:: 174 175 $ LL_FS_RO=/ LL_FS_RW=/tmp LL_FORCE_LOG=1 ./sandboxer sh -c "echo > /etc/passwd" 176 177The related audit logs contains 8 records from 3 different events (serials 33, 17834 and 35) created by the same domain `1a6fdc679`:: 179 180 type=LANDLOCK_ACCESS msg=audit(1729738800.221:33): domain=1a6fdc679 blockers=fs.write_file path="/dev/tty" dev="devtmpfs" ino=9 181 type=LANDLOCK_DOMAIN msg=audit(1729738800.221:33): domain=1a6fdc679 status=allocated mode=enforcing pid=289 uid=0 exe="/root/sandboxer" comm="sandboxer" 182 type=SYSCALL msg=audit(1729738800.221:33): arch=c000003e syscall=257 success=no exit=-13 [...] ppid=272 pid=289 auid=0 uid=0 gid=0 [...] comm="sh" [...] 183 type=PROCTITLE msg=audit(1729738800.221:33): proctitle=7368002D63006563686F203E202F6574632F706173737764 184 type=LANDLOCK_ACCESS msg=audit(1729738800.221:34): domain=1a6fdc679 blockers=fs.write_file path="/etc/passwd" dev="vda2" ino=143821 185 type=SYSCALL msg=audit(1729738800.221:34): arch=c000003e syscall=257 success=no exit=-13 [...] ppid=272 pid=289 auid=0 uid=0 gid=0 [...] comm="sh" [...] 186 type=PROCTITLE msg=audit(1729738800.221:34): proctitle=7368002D63006563686F203E202F6574632F706173737764 187 type=LANDLOCK_DOMAIN msg=audit(1729738800.261:35): domain=1a6fdc679 status=deallocated denials=2 188 189 190Event filtering 191--------------- 192 193If you get spammed with audit logs related to Landlock, this is either an 194attack attempt or a bug in the security policy. We can put in place some 195filters to limit noise with two complementary ways: 196 197- with sys_landlock_restrict_self()'s flags, 198 ``LANDLOCK_ADD_RULE_QUIET`` (ABI 10+), or the permission rules' 199 per-member ``quiet_*`` fields (ABI 12+) if we can fix the sandboxed 200 programs, 201- or with audit rules (see :manpage:`auditctl(8)`). 202 203Tracepoints 204=========== 205 206Landlock also provides tracepoints as an alternative to audit for 207debugging and observability. Tracepoints fire unconditionally, 208independent of audit configuration, ``audit_enabled``, and domain log 209flags. This makes them suitable for always-on monitoring with eBPF or 210for ad-hoc debugging with ``trace-pipe``. 211 212See Documentation/trace/events-landlock.rst for the complete event 213reference: the full event list, how to enable events and read their 214output, the field formats, the ``check_rule`` interpretation guide, 215worked event samples, ftrace filtering, and eBPF access. 216 217.. _landlock_observability: 218 219When to use tracing vs audit 220----------------------------- 221 222Audit and tracing both help diagnose Landlock policy issues: 223 224**Audit** records denied accesses with the blockers, domain, and object 225identification (path, port). Audit is the standard Linux mechanism for 226security events, with a stable record format that is well established 227and already supported by log management systems, SIEM platforms, and EDR 228solutions. Audit is always active when the kernel is built with audit 229support, filtered by the Landlock log flags to reduce noise in 230production, and designed for long-term security monitoring and 231compliance. 232 233**Tracing** provides deeper introspection for policy debugging. In 234addition to denied accesses, trace events cover the complete lifecycle 235of Landlock objects (rulesets, domains) and intermediate rule matching 236during access checks. Trace events are disabled by default (zero 237overhead) and fire unconditionally. eBPF 238programs attached to trace events can access the full kernel context 239(ruleset rules, domain hierarchy, process credentials) via BTF, enabling 240richer analysis than the flat fields in audit records. For example, an 241eBPF-based live monitoring tool can correlate creation, rule-addition, 242and denial events to build a real-time view of all active Landlock 243domains and their policies. However, BTF-based access depends on 244internal kernel struct layouts which have no stability guarantee. CO-RE 245(Compile Once, Run Everywhere) provides best-effort field relocation. 246The ftrace printk format is also not a stable ABI, but is 247self-describing via the per-event ``format`` file, allowing tools to 248adapt dynamically. 249 250Observability guarantees and limitations 251----------------------------------------- 252 253Both audit records and trace events are emitted for every denied access, 254with these exceptions: 255 256- **Landlock log flags** (audit only): ``LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF``, 257 ``LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON``, and 258 ``LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF`` control which denials 259 generate audit records. Trace events fire regardless of these flags. 260 261- **NOAUDIT hooks**: Some LSM hooks suppress logging for speculative 262 permission probes (e.g., reading ``/proc/<pid>/status`` uses 263 ``PTRACE_MODE_NOAUDIT``, and :manpage:`listxattr(2)` probes 264 ``CAP_SYS_ADMIN`` with ``CAP_OPT_NOAUDIT`` to decide whether to list 265 ``trusted.*`` extended attributes). When NOAUDIT is set, neither audit 266 records nor trace events are emitted, and the denial is not counted in 267 ``denials``. The denial is still enforced. This avoids performance 268 overhead and noise from speculative probes that test permissions 269 without performing an actual access. 270 271- **Audit rate limiting**: The audit subsystem may silently drop records 272 when the audit queue is full. Trace events are not rate-limited. 273 274- **Tracepoint disabled**: When a trace event is disabled (the default 275 state), the tracepoint is a no-op with zero overhead. 276 277When both audit and tracing are active, every denial emits a trace event, 278and a denial that the domain's log policy selects additionally produces an 279audit record (subject to the Landlock log flags). The ``denials`` count in 280``free_domain`` events is incremented for every denial regardless of the 281log flags, so it can exceed the number of audit records (which the log 282flags and audit-side rate-limiting or exclude rules may suppress). 283 284.. _landlock_observability_security: 285 286Observability security considerations 287--------------------------------------- 288 289Both audit records and trace events expose information about all 290Landlock-sandboxed processes on the system, including filesystem paths 291being accessed, network ports, capability numbers, namespace types and IDs, 292and process identities. System 293administrators must ensure that access to audit logs (controlled by the 294audit subsystem configuration) and to trace events (requiring 295``CAP_SYS_ADMIN`` or ``CAP_BPF`` + ``CAP_PERFMON``) is restricted to 296trusted users. 297 298eBPF programs attached to Landlock trace events have access to the full 299kernel context of each event (ruleset rules, domain hierarchy, process 300credentials) via BTF, exposing sensitive state about every sandboxed 301process. Restrict this access to trusted users, as for the audit logs. 302 303Audit logs and kernel trace events require elevated privileges and are 304system-wide; they are not designed for per-sandbox unprivileged 305monitoring. 306 307Additional documentation 308======================== 309 310* `Linux Audit Documentation`_ 311* Documentation/userspace-api/landlock.rst 312* Documentation/trace/events-landlock.rst 313* Documentation/security/landlock.rst 314* https://landlock.io 315 316.. Links 317.. _Linux Audit Documentation: 318 https://github.com/linux-audit/audit-documentation/wiki 319