1.. SPDX-License-Identifier: GPL-2.0 2.. Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net> 3.. Copyright © 2019-2020 ANSSI 4.. Copyright © 2026 Cloudflare, Inc. 5 6================================== 7Landlock LSM: kernel documentation 8================================== 9 10:Author: Mickaël Salaün 11:Date: August 2026 12 13Landlock's goal is to create scoped access-control (i.e. sandboxing). To 14harden a whole system, this feature should be available to any process, 15including unprivileged ones. Because such a process may be compromised or 16backdoored (i.e. untrusted), Landlock's features must be safe to use from the 17kernel and other processes point of view. Landlock's interface must therefore 18expose a minimal attack surface. 19 20Landlock is designed to be usable by unprivileged processes while following the 21system security policy enforced by other access control mechanisms (e.g. DAC, 22LSM). A Landlock rule shall not interfere with other access-controls enforced 23on the system, only add more restrictions. 24 25Any user can enforce Landlock rulesets on their processes. They are merged and 26evaluated against inherited rulesets in a way that ensures that only more 27constraints can be added. 28 29User space documentation can be found here: 30Documentation/userspace-api/landlock.rst. 31 32Guiding principles for safe access controls 33=========================================== 34 35* A Landlock rule shall be focused on access control on kernel objects instead 36 of syscall filtering (i.e. syscall arguments), which is the purpose of 37 seccomp-bpf. 38* To avoid multiple kinds of side-channel attacks (e.g. leak of security 39 policies, CPU-based attacks), Landlock rules shall not be able to 40 programmatically communicate with user space. 41* Kernel access check shall not slow down access request from unsandboxed 42 processes. 43* Computation related to Landlock operations (e.g. enforcing a ruleset) shall 44 only impact the processes requesting them. 45* Resources (e.g. file descriptors) directly obtained from the kernel by a 46 sandboxed process shall retain their scoped accesses (at the time of resource 47 acquisition) whatever process uses them. 48 Cf. `File descriptor access rights`_. 49* Access denials shall be logged according to system and Landlock domain 50 configurations. Log entries must contain information about the cause of the 51 denial and the owner of the related security policy. Such log generation 52 should have a negligible performance and memory impact on allowed requests. 53 54Design choices 55============== 56 57Inode access rights 58------------------- 59 60All access rights are tied to an inode and what can be accessed through it. 61Reading the content of a directory does not imply to be allowed to read the 62content of a listed inode. Indeed, a file name is local to its parent 63directory, and an inode can be referenced by multiple file names thanks to 64(hard) links. Being able to unlink a file only has a direct impact on the 65directory, not the unlinked inode. This is the reason why 66``LANDLOCK_ACCESS_FS_REMOVE_FILE`` or ``LANDLOCK_ACCESS_FS_REFER`` are not 67allowed to be tied to files but only to directories. 68 69File descriptor access rights 70----------------------------- 71 72Access rights are checked and tied to file descriptors at open time. The 73underlying principle is that equivalent sequences of operations should lead to 74the same results, when they are executed under the same Landlock domain. 75 76Taking the ``LANDLOCK_ACCESS_FS_TRUNCATE`` right as an example, it may be 77allowed to open a file for writing without being allowed to 78:manpage:`ftruncate` the resulting file descriptor if the related file 79hierarchy doesn't grant that access right. The following sequences of 80operations have the same semantic and should then have the same result: 81 82* ``truncate(path);`` 83* ``int fd = open(path, O_WRONLY); ftruncate(fd); close(fd);`` 84 85Similarly to file access modes (e.g. ``O_RDWR``), Landlock access rights 86attached to file descriptors are retained even if they are passed between 87processes (e.g. through a Unix domain socket). Such access rights will then be 88enforced even if the receiving process is not sandboxed by Landlock. Indeed, 89this is required to keep access controls consistent over the whole system, and 90this avoids unattended bypasses through file descriptor passing (i.e. confused 91deputy attack). 92 93.. _scoped-flags-interaction: 94 95Interaction between scoped flags and other access rights 96-------------------------------------------------------- 97 98The ``scoped`` flags in &struct landlock_ruleset_attr restrict the 99use of *outgoing* IPC from the created Landlock domain, while they 100permit reaching out to IPC endpoints *within* the created Landlock 101domain. 102 103In the future, scoped flags *may* interact with other access rights, 104e.g. so that abstract UNIX sockets can be allow-listed by name, or so 105that signals can be allow-listed by signal number or target process. 106 107When introducing ``LANDLOCK_ACCESS_FS_RESOLVE_UNIX``, we defined it to 108implicitly have the same scoping semantics as a 109``LANDLOCK_SCOPE_PATHNAME_UNIX_SOCKET`` flag would have: connecting to 110UNIX sockets within the same domain (where 111``LANDLOCK_ACCESS_FS_RESOLVE_UNIX`` is used) is unconditionally 112allowed. 113 114The reasoning is: 115 116* Like other IPC mechanisms, connecting to named UNIX sockets in the 117 same domain should be expected and harmless. (If needed, users can 118 further refine their Landlock policies with nested domains or by 119 restricting ``LANDLOCK_ACCESS_FS_MAKE_SOCK``.) 120* We reserve the option to still introduce 121 ``LANDLOCK_SCOPE_PATHNAME_UNIX_SOCKET`` in the future. (This would 122 be useful if we wanted to have a Landlock rule to permit IPC access 123 to other Landlock domains.) 124* But we can postpone the point in time when users have to deal with 125 two interacting flags visible in the userspace API. (In particular, 126 it is possible that it won't be needed in practice, in which case we 127 can avoid the second flag altogether.) 128* If we *do* introduce ``LANDLOCK_SCOPE_PATHNAME_UNIX_SOCKET`` in the 129 future, setting this scoped flag in a ruleset does *not reduce* the 130 restrictions, because access within the same scope is already 131 allowed based on ``LANDLOCK_ACCESS_FS_RESOLVE_UNIX``. 132 133Tests 134===== 135 136Userspace tests for backward compatibility, ptrace restrictions and filesystem 137support can be found here: `tools/testing/selftests/landlock/`_. 138 139Kernel structures 140================= 141 142Object 143------ 144 145.. kernel-doc:: security/landlock/object.h 146 :identifiers: 147 148Filesystem 149---------- 150 151.. kernel-doc:: security/landlock/fs.h 152 :identifiers: 153 154Process credential 155------------------ 156 157.. kernel-doc:: security/landlock/cred.h 158 :identifiers: 159 160Ruleset and domain 161------------------ 162 163A domain is a read-only ruleset tied to a set of subjects (i.e. tasks' 164credentials). Each time a ruleset is enforced on a task, the current domain is 165duplicated and the ruleset is imported as a new layer of rules in the new 166domain. Indeed, once in a domain, each rule is tied to a layer level. To 167grant access to an object, at least one rule of each layer must allow the 168requested action on the object. A task can then only transit to a new domain 169that is the intersection of the constraints from the current domain and those 170of a ruleset provided by the task. 171 172The definition of a subject is implicit for a task sandboxing itself, which 173makes the reasoning much easier and helps avoid pitfalls. 174 175.. kernel-doc:: security/landlock/ruleset.h 176 :identifiers: 177 178.. kernel-doc:: security/landlock/domain.h 179 :identifiers: 180 181Denial logging 182============== 183 184Access denials are logged through two independent channels: audit 185records and tracepoints. Both are managed by the common denial 186framework in ``log.c``, compiled under ``CONFIG_SECURITY_LANDLOCK_LOG`` 187(automatically selected by ``CONFIG_AUDIT`` or ``CONFIG_TRACEPOINTS``). 188 189Audit records respect audit configuration, the domain's Landlock log 190flags, and ``LANDLOCK_LOG_DISABLED``. Tracepoints fire unconditionally, 191independent of these settings. The denial counter (``num_denials``) is 192always incremented regardless of logging configuration. 193 194Each denial tracepoint carries a ``logged`` field reporting the 195audit-logging verdict: whether the denial would be written to the audit 196log if audit were configured and active. This verdict is the same 197whether or not the kernel is built with audit support, so a 198tracepoints-only build reports the selection audit would make. A quiet 199rule (``LANDLOCK_ADD_RULE_QUIET`` with the access in the ``quiet_*`` 200fields of ``struct landlock_ruleset_attr``) suppresses logging by 201setting ``logged=0`` the same way. 202 203See Documentation/admin-guide/LSM/landlock.rst for audit record format, 204tracepoint usage, and filtering examples. 205 206.. kernel-doc:: security/landlock/log.h 207 :identifiers: 208 209Trace events 210------------ 211 212See Documentation/trace/events-landlock.rst for trace event usage and format 213details; the full event reference lives there and is not duplicated here. 214 215Additional documentation 216======================== 217 218* Documentation/userspace-api/landlock.rst 219* Documentation/admin-guide/LSM/landlock.rst 220* Documentation/trace/events-landlock.rst 221* https://landlock.io 222 223.. Links 224.. _tools/testing/selftests/landlock/: 225 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/landlock/ 226