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 © 2021-2022 Microsoft Corporation
5
6=====================================
7Landlock: unprivileged access control
8=====================================
9
10:Author: Mickaël Salaün
11:Date: May 2022
12
13The goal of Landlock is to enable to restrict ambient rights (e.g. global
14filesystem access) for a set of processes.  Because Landlock is a stackable
15LSM, it makes possible to create safe security sandboxes as new security layers
16in addition to the existing system-wide access-controls. This kind of sandbox
17is expected to help mitigate the security impact of bugs or
18unexpected/malicious behaviors in user space applications.  Landlock empowers
19any process, including unprivileged ones, to securely restrict themselves.
20
21We can quickly make sure that Landlock is enabled in the running system by
22looking for "landlock: Up and running" in kernel logs (as root): ``dmesg | grep
23landlock || journalctl -kg landlock`` .  Developers can also easily check for
24Landlock support with a :ref:`related system call <landlock_abi_versions>`.  If
25Landlock is not currently supported, we need to :ref:`configure the kernel
26appropriately <kernel_support>`.
27
28Landlock rules
29==============
30
31A Landlock rule describes an action on an object.  An object is currently a
32file hierarchy, and the related filesystem actions are defined with `access
33rights`_.  A set of rules is aggregated in a ruleset, which can then restrict
34the thread enforcing it, and its future children.
35
36Defining and enforcing a security policy
37----------------------------------------
38
39We first need to define the ruleset that will contain our rules.  For this
40example, the ruleset will contain rules that only allow read actions, but write
41actions will be denied.  The ruleset then needs to handle both of these kind of
42actions.  This is required for backward and forward compatibility (i.e. the
43kernel and user space may not know each other's supported restrictions), hence
44the need to be explicit about the denied-by-default access rights.
45
46.. code-block:: c
47
48    struct landlock_ruleset_attr ruleset_attr = {
49        .handled_access_fs =
50            LANDLOCK_ACCESS_FS_EXECUTE |
51            LANDLOCK_ACCESS_FS_WRITE_FILE |
52            LANDLOCK_ACCESS_FS_READ_FILE |
53            LANDLOCK_ACCESS_FS_READ_DIR |
54            LANDLOCK_ACCESS_FS_REMOVE_DIR |
55            LANDLOCK_ACCESS_FS_REMOVE_FILE |
56            LANDLOCK_ACCESS_FS_MAKE_CHAR |
57            LANDLOCK_ACCESS_FS_MAKE_DIR |
58            LANDLOCK_ACCESS_FS_MAKE_REG |
59            LANDLOCK_ACCESS_FS_MAKE_SOCK |
60            LANDLOCK_ACCESS_FS_MAKE_FIFO |
61            LANDLOCK_ACCESS_FS_MAKE_BLOCK |
62            LANDLOCK_ACCESS_FS_MAKE_SYM |
63            LANDLOCK_ACCESS_FS_REFER,
64    };
65
66Because we may not know on which kernel version an application will be
67executed, it is safer to follow a best-effort security approach.  Indeed, we
68should try to protect users as much as possible whatever the kernel they are
69using.  To avoid binary enforcement (i.e. either all security features or
70none), we can leverage a dedicated Landlock command to get the current version
71of the Landlock ABI and adapt the handled accesses.  Let's check if we should
72remove the `LANDLOCK_ACCESS_FS_REFER` access right which is only supported
73starting with the second version of the ABI.
74
75.. code-block:: c
76
77    int abi;
78
79    abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION);
80    if (abi < 2) {
81        ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_REFER;
82    }
83
84This enables to create an inclusive ruleset that will contain our rules.
85
86.. code-block:: c
87
88    int ruleset_fd;
89
90    ruleset_fd = landlock_create_ruleset(&ruleset_attr, sizeof(ruleset_attr), 0);
91    if (ruleset_fd < 0) {
92        perror("Failed to create a ruleset");
93        return 1;
94    }
95
96We can now add a new rule to this ruleset thanks to the returned file
97descriptor referring to this ruleset.  The rule will only allow reading the
98file hierarchy ``/usr``.  Without another rule, write actions would then be
99denied by the ruleset.  To add ``/usr`` to the ruleset, we open it with the
100``O_PATH`` flag and fill the &struct landlock_path_beneath_attr with this file
101descriptor.
102
103.. code-block:: c
104
105    int err;
106    struct landlock_path_beneath_attr path_beneath = {
107        .allowed_access =
108            LANDLOCK_ACCESS_FS_EXECUTE |
109            LANDLOCK_ACCESS_FS_READ_FILE |
110            LANDLOCK_ACCESS_FS_READ_DIR,
111    };
112
113    path_beneath.parent_fd = open("/usr", O_PATH | O_CLOEXEC);
114    if (path_beneath.parent_fd < 0) {
115        perror("Failed to open file");
116        close(ruleset_fd);
117        return 1;
118    }
119    err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_PATH_BENEATH,
120                            &path_beneath, 0);
121    close(path_beneath.parent_fd);
122    if (err) {
123        perror("Failed to update ruleset");
124        close(ruleset_fd);
125        return 1;
126    }
127
128It may also be required to create rules following the same logic as explained
129for the ruleset creation, by filtering access rights according to the Landlock
130ABI version.  In this example, this is not required because
131`LANDLOCK_ACCESS_FS_REFER` is not allowed by any rule.
132
133We now have a ruleset with one rule allowing read access to ``/usr`` while
134denying all other handled accesses for the filesystem.  The next step is to
135restrict the current thread from gaining more privileges (e.g. thanks to a SUID
136binary).
137
138.. code-block:: c
139
140    if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) {
141        perror("Failed to restrict privileges");
142        close(ruleset_fd);
143        return 1;
144    }
145
146The current thread is now ready to sandbox itself with the ruleset.
147
148.. code-block:: c
149
150    if (landlock_restrict_self(ruleset_fd, 0)) {
151        perror("Failed to enforce ruleset");
152        close(ruleset_fd);
153        return 1;
154    }
155    close(ruleset_fd);
156
157If the `landlock_restrict_self` system call succeeds, the current thread is now
158restricted and this policy will be enforced on all its subsequently created
159children as well.  Once a thread is landlocked, there is no way to remove its
160security policy; only adding more restrictions is allowed.  These threads are
161now in a new Landlock domain, merge of their parent one (if any) with the new
162ruleset.
163
164Full working code can be found in `samples/landlock/sandboxer.c`_.
165
166Good practices
167--------------
168
169It is recommended setting access rights to file hierarchy leaves as much as
170possible.  For instance, it is better to be able to have ``~/doc/`` as a
171read-only hierarchy and ``~/tmp/`` as a read-write hierarchy, compared to
172``~/`` as a read-only hierarchy and ``~/tmp/`` as a read-write hierarchy.
173Following this good practice leads to self-sufficient hierarchies that don't
174depend on their location (i.e. parent directories).  This is particularly
175relevant when we want to allow linking or renaming.  Indeed, having consistent
176access rights per directory enables to change the location of such directory
177without relying on the destination directory access rights (except those that
178are required for this operation, see `LANDLOCK_ACCESS_FS_REFER` documentation).
179Having self-sufficient hierarchies also helps to tighten the required access
180rights to the minimal set of data.  This also helps avoid sinkhole directories,
181i.e.  directories where data can be linked to but not linked from.  However,
182this depends on data organization, which might not be controlled by developers.
183In this case, granting read-write access to ``~/tmp/``, instead of write-only
184access, would potentially allow to move ``~/tmp/`` to a non-readable directory
185and still keep the ability to list the content of ``~/tmp/``.
186
187Layers of file path access rights
188---------------------------------
189
190Each time a thread enforces a ruleset on itself, it updates its Landlock domain
191with a new layer of policy.  Indeed, this complementary policy is stacked with
192the potentially other rulesets already restricting this thread.  A sandboxed
193thread can then safely add more constraints to itself with a new enforced
194ruleset.
195
196One policy layer grants access to a file path if at least one of its rules
197encountered on the path grants the access.  A sandboxed thread can only access
198a file path if all its enforced policy layers grant the access as well as all
199the other system access controls (e.g. filesystem DAC, other LSM policies,
200etc.).
201
202Bind mounts and OverlayFS
203-------------------------
204
205Landlock enables to restrict access to file hierarchies, which means that these
206access rights can be propagated with bind mounts (cf.
207Documentation/filesystems/sharedsubtree.rst) but not with
208Documentation/filesystems/overlayfs.rst.
209
210A bind mount mirrors a source file hierarchy to a destination.  The destination
211hierarchy is then composed of the exact same files, on which Landlock rules can
212be tied, either via the source or the destination path.  These rules restrict
213access when they are encountered on a path, which means that they can restrict
214access to multiple file hierarchies at the same time, whether these hierarchies
215are the result of bind mounts or not.
216
217An OverlayFS mount point consists of upper and lower layers.  These layers are
218combined in a merge directory, result of the mount point.  This merge hierarchy
219may include files from the upper and lower layers, but modifications performed
220on the merge hierarchy only reflects on the upper layer.  From a Landlock
221policy point of view, each OverlayFS layers and merge hierarchies are
222standalone and contains their own set of files and directories, which is
223different from bind mounts.  A policy restricting an OverlayFS layer will not
224restrict the resulted merged hierarchy, and vice versa.  Landlock users should
225then only think about file hierarchies they want to allow access to, regardless
226of the underlying filesystem.
227
228Inheritance
229-----------
230
231Every new thread resulting from a :manpage:`clone(2)` inherits Landlock domain
232restrictions from its parent.  This is similar to the seccomp inheritance (cf.
233Documentation/userspace-api/seccomp_filter.rst) or any other LSM dealing with
234task's :manpage:`credentials(7)`.  For instance, one process's thread may apply
235Landlock rules to itself, but they will not be automatically applied to other
236sibling threads (unlike POSIX thread credential changes, cf.
237:manpage:`nptl(7)`).
238
239When a thread sandboxes itself, we have the guarantee that the related security
240policy will stay enforced on all this thread's descendants.  This allows
241creating standalone and modular security policies per application, which will
242automatically be composed between themselves according to their runtime parent
243policies.
244
245Ptrace restrictions
246-------------------
247
248A sandboxed process has less privileges than a non-sandboxed process and must
249then be subject to additional restrictions when manipulating another process.
250To be allowed to use :manpage:`ptrace(2)` and related syscalls on a target
251process, a sandboxed process should have a subset of the target process rules,
252which means the tracee must be in a sub-domain of the tracer.
253
254Compatibility
255=============
256
257Backward and forward compatibility
258----------------------------------
259
260Landlock is designed to be compatible with past and future versions of the
261kernel.  This is achieved thanks to the system call attributes and the
262associated bitflags, particularly the ruleset's `handled_access_fs`.  Making
263handled access right explicit enables the kernel and user space to have a clear
264contract with each other.  This is required to make sure sandboxing will not
265get stricter with a system update, which could break applications.
266
267Developers can subscribe to the `Landlock mailing list
268<https://subspace.kernel.org/lists.linux.dev.html>`_ to knowingly update and
269test their applications with the latest available features.  In the interest of
270users, and because they may use different kernel versions, it is strongly
271encouraged to follow a best-effort security approach by checking the Landlock
272ABI version at runtime and only enforcing the supported features.
273
274.. _landlock_abi_versions:
275
276Landlock ABI versions
277---------------------
278
279The Landlock ABI version can be read with the sys_landlock_create_ruleset()
280system call:
281
282.. code-block:: c
283
284    int abi;
285
286    abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION);
287    if (abi < 0) {
288        switch (errno) {
289        case ENOSYS:
290            printf("Landlock is not supported by the current kernel.\n");
291            break;
292        case EOPNOTSUPP:
293            printf("Landlock is currently disabled.\n");
294            break;
295        }
296        return 0;
297    }
298    if (abi >= 2) {
299        printf("Landlock supports LANDLOCK_ACCESS_FS_REFER.\n");
300    }
301
302The following kernel interfaces are implicitly supported by the first ABI
303version.  Features only supported from a specific version are explicitly marked
304as such.
305
306Kernel interface
307================
308
309Access rights
310-------------
311
312.. kernel-doc:: include/uapi/linux/landlock.h
313    :identifiers: fs_access
314
315Creating a new ruleset
316----------------------
317
318.. kernel-doc:: security/landlock/syscalls.c
319    :identifiers: sys_landlock_create_ruleset
320
321.. kernel-doc:: include/uapi/linux/landlock.h
322    :identifiers: landlock_ruleset_attr
323
324Extending a ruleset
325-------------------
326
327.. kernel-doc:: security/landlock/syscalls.c
328    :identifiers: sys_landlock_add_rule
329
330.. kernel-doc:: include/uapi/linux/landlock.h
331    :identifiers: landlock_rule_type landlock_path_beneath_attr
332
333Enforcing a ruleset
334-------------------
335
336.. kernel-doc:: security/landlock/syscalls.c
337    :identifiers: sys_landlock_restrict_self
338
339Current limitations
340===================
341
342Filesystem topology modification
343--------------------------------
344
345As for file renaming and linking, a sandboxed thread cannot modify its
346filesystem topology, whether via :manpage:`mount(2)` or
347:manpage:`pivot_root(2)`.  However, :manpage:`chroot(2)` calls are not denied.
348
349Special filesystems
350-------------------
351
352Access to regular files and directories can be restricted by Landlock,
353according to the handled accesses of a ruleset.  However, files that do not
354come from a user-visible filesystem (e.g. pipe, socket), but can still be
355accessed through ``/proc/<pid>/fd/*``, cannot currently be explicitly
356restricted.  Likewise, some special kernel filesystems such as nsfs, which can
357be accessed through ``/proc/<pid>/ns/*``, cannot currently be explicitly
358restricted.  However, thanks to the `ptrace restrictions`_, access to such
359sensitive ``/proc`` files are automatically restricted according to domain
360hierarchies.  Future Landlock evolutions could still enable to explicitly
361restrict such paths with dedicated ruleset flags.
362
363Ruleset layers
364--------------
365
366There is a limit of 16 layers of stacked rulesets.  This can be an issue for a
367task willing to enforce a new ruleset in complement to its 16 inherited
368rulesets.  Once this limit is reached, sys_landlock_restrict_self() returns
369E2BIG.  It is then strongly suggested to carefully build rulesets once in the
370life of a thread, especially for applications able to launch other applications
371that may also want to sandbox themselves (e.g. shells, container managers,
372etc.).
373
374Memory usage
375------------
376
377Kernel memory allocated to create rulesets is accounted and can be restricted
378by the Documentation/admin-guide/cgroup-v1/memory.rst.
379
380Previous limitations
381====================
382
383File renaming and linking (ABI 1)
384---------------------------------
385
386Because Landlock targets unprivileged access controls, it needs to properly
387handle composition of rules.  Such property also implies rules nesting.
388Properly handling multiple layers of rulesets, each one of them able to
389restrict access to files, also implies inheritance of the ruleset restrictions
390from a parent to its hierarchy.  Because files are identified and restricted by
391their hierarchy, moving or linking a file from one directory to another implies
392propagation of the hierarchy constraints, or restriction of these actions
393according to the potentially lost constraints.  To protect against privilege
394escalations through renaming or linking, and for the sake of simplicity,
395Landlock previously limited linking and renaming to the same directory.
396Starting with the Landlock ABI version 2, it is now possible to securely
397control renaming and linking thanks to the new `LANDLOCK_ACCESS_FS_REFER`
398access right.
399
400.. _kernel_support:
401
402Kernel support
403==============
404
405Landlock was first introduced in Linux 5.13 but it must be configured at build
406time with `CONFIG_SECURITY_LANDLOCK=y`.  Landlock must also be enabled at boot
407time as the other security modules.  The list of security modules enabled by
408default is set with `CONFIG_LSM`.  The kernel configuration should then
409contains `CONFIG_LSM=landlock,[...]` with `[...]`  as the list of other
410potentially useful security modules for the running system (see the
411`CONFIG_LSM` help).
412
413If the running kernel doesn't have `landlock` in `CONFIG_LSM`, then we can
414still enable it by adding ``lsm=landlock,[...]`` to
415Documentation/admin-guide/kernel-parameters.rst thanks to the bootloader
416configuration.
417
418Questions and answers
419=====================
420
421What about user space sandbox managers?
422---------------------------------------
423
424Using user space process to enforce restrictions on kernel resources can lead
425to race conditions or inconsistent evaluations (i.e. `Incorrect mirroring of
426the OS code and state
427<https://www.ndss-symposium.org/ndss2003/traps-and-pitfalls-practical-problems-system-call-interposition-based-security-tools/>`_).
428
429What about namespaces and containers?
430-------------------------------------
431
432Namespaces can help create sandboxes but they are not designed for
433access-control and then miss useful features for such use case (e.g. no
434fine-grained restrictions).  Moreover, their complexity can lead to security
435issues, especially when untrusted processes can manipulate them (cf.
436`Controlling access to user namespaces <https://lwn.net/Articles/673597/>`_).
437
438Additional documentation
439========================
440
441* Documentation/security/landlock.rst
442* https://landlock.io
443
444.. Links
445.. _samples/landlock/sandboxer.c:
446   https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/samples/landlock/sandboxer.c
447