1 .. SPDX-License-Identifier: GPL-2.0
2 .. Copyright © 2017-2020 Mickaël Salaün <mic
3 .. Copyright © 2019-2020 ANSSI
4 .. Copyright © 2021-2022 Microsoft Corporatio
5
6 =====================================
7 Landlock: unprivileged access control
8 =====================================
9
10 :Author: Mickaël Salaün
11 :Date: September 2024
12
13 The goal of Landlock is to enable to restrict
14 filesystem or network access) for a set of pro
15 is a stackable LSM, it makes possible to creat
16 security layers in addition to the existing sy
17 kind of sandbox is expected to help mitigate t
18 unexpected/malicious behaviors in user space a
19 any process, including unprivileged ones, to s
20
21 We can quickly make sure that Landlock is enab
22 looking for "landlock: Up and running" in kern
23 ``dmesg | grep landlock || journalctl -kb -g l
24 Developers can also easily check for Landlock
25 :ref:`related system call <landlock_abi_versio
26 If Landlock is not currently supported, we nee
27 :ref:`configure the kernel appropriately <kern
28
29 Landlock rules
30 ==============
31
32 A Landlock rule describes an action on an obje
33 perform. A set of rules is aggregated in a ru
34 the thread enforcing it, and its future childr
35
36 The two existing types of rules are:
37
38 Filesystem rules
39 For these rules, the object is a file hier
40 and the related filesystem actions are def
41 `filesystem access rights`.
42
43 Network rules (since ABI v4)
44 For these rules, the object is a TCP port,
45 and the related actions are defined with `
46
47 Defining and enforcing a security policy
48 ----------------------------------------
49
50 We first need to define the ruleset that will
51
52 For this example, the ruleset will contain rul
53 read actions and establish a specific TCP conn
54 actions and other TCP actions will be denied.
55
56 The ruleset then needs to handle both these ki
57 required for backward and forward compatibilit
58 space may not know each other's supported rest
59 to be explicit about the denied-by-default acc
60
61 .. code-block:: c
62
63 struct landlock_ruleset_attr ruleset_attr
64 .handled_access_fs =
65 LANDLOCK_ACCESS_FS_EXECUTE |
66 LANDLOCK_ACCESS_FS_WRITE_FILE |
67 LANDLOCK_ACCESS_FS_READ_FILE |
68 LANDLOCK_ACCESS_FS_READ_DIR |
69 LANDLOCK_ACCESS_FS_REMOVE_DIR |
70 LANDLOCK_ACCESS_FS_REMOVE_FILE |
71 LANDLOCK_ACCESS_FS_MAKE_CHAR |
72 LANDLOCK_ACCESS_FS_MAKE_DIR |
73 LANDLOCK_ACCESS_FS_MAKE_REG |
74 LANDLOCK_ACCESS_FS_MAKE_SOCK |
75 LANDLOCK_ACCESS_FS_MAKE_FIFO |
76 LANDLOCK_ACCESS_FS_MAKE_BLOCK |
77 LANDLOCK_ACCESS_FS_MAKE_SYM |
78 LANDLOCK_ACCESS_FS_REFER |
79 LANDLOCK_ACCESS_FS_TRUNCATE |
80 LANDLOCK_ACCESS_FS_IOCTL_DEV,
81 .handled_access_net =
82 LANDLOCK_ACCESS_NET_BIND_TCP |
83 LANDLOCK_ACCESS_NET_CONNECT_TCP,
84 .scoped =
85 LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKE
86 LANDLOCK_SCOPE_SIGNAL,
87 };
88
89 Because we may not know on which kernel versio
90 executed, it is safer to follow a best-effort
91 should try to protect users as much as possibl
92 using.
93
94 To be compatible with older Linux versions, we
95 version, and only use the available subset of
96
97 .. code-block:: c
98
99 int abi;
100
101 abi = landlock_create_ruleset(NULL, 0, LAN
102 if (abi < 0) {
103 /* Degrades gracefully if Landlock is
104 perror("The running kernel does not en
105 return 0;
106 }
107 switch (abi) {
108 case 1:
109 /* Removes LANDLOCK_ACCESS_FS_REFER fo
110 ruleset_attr.handled_access_fs &= ~LAN
111 __attribute__((fallthrough));
112 case 2:
113 /* Removes LANDLOCK_ACCESS_FS_TRUNCATE
114 ruleset_attr.handled_access_fs &= ~LAN
115 __attribute__((fallthrough));
116 case 3:
117 /* Removes network support for ABI < 4
118 ruleset_attr.handled_access_net &=
119 ~(LANDLOCK_ACCESS_NET_BIND_TCP |
120 LANDLOCK_ACCESS_NET_CONNECT_TCP)
121 __attribute__((fallthrough));
122 case 4:
123 /* Removes LANDLOCK_ACCESS_FS_IOCTL_DE
124 ruleset_attr.handled_access_fs &= ~LAN
125 __attribute__((fallthrough));
126 case 5:
127 /* Removes LANDLOCK_SCOPE_* for ABI <
128 ruleset_attr.scoped &= ~(LANDLOCK_SCOP
129 LANDLOCK_SCOP
130 }
131
132 This enables to create an inclusive ruleset th
133
134 .. code-block:: c
135
136 int ruleset_fd;
137
138 ruleset_fd = landlock_create_ruleset(&rule
139 if (ruleset_fd < 0) {
140 perror("Failed to create a ruleset");
141 return 1;
142 }
143
144 We can now add a new rule to this ruleset than
145 descriptor referring to this ruleset. The rul
146 file hierarchy ``/usr``. Without another rule
147 denied by the ruleset. To add ``/usr`` to the
148 ``O_PATH`` flag and fill the &struct landlock_
149 descriptor.
150
151 .. code-block:: c
152
153 int err;
154 struct landlock_path_beneath_attr path_ben
155 .allowed_access =
156 LANDLOCK_ACCESS_FS_EXECUTE |
157 LANDLOCK_ACCESS_FS_READ_FILE |
158 LANDLOCK_ACCESS_FS_READ_DIR,
159 };
160
161 path_beneath.parent_fd = open("/usr", O_PA
162 if (path_beneath.parent_fd < 0) {
163 perror("Failed to open file");
164 close(ruleset_fd);
165 return 1;
166 }
167 err = landlock_add_rule(ruleset_fd, LANDLO
168 &path_beneath, 0);
169 close(path_beneath.parent_fd);
170 if (err) {
171 perror("Failed to update ruleset");
172 close(ruleset_fd);
173 return 1;
174 }
175
176 It may also be required to create rules follow
177 for the ruleset creation, by filtering access
178 ABI version. In this example, this is not req
179 ``allowed_access`` rights are already availabl
180
181 For network access-control, we can add a set o
182 number for a specific action: HTTPS connection
183
184 .. code-block:: c
185
186 struct landlock_net_port_attr net_port = {
187 .allowed_access = LANDLOCK_ACCESS_NET_
188 .port = 443,
189 };
190
191 err = landlock_add_rule(ruleset_fd, LANDLO
192 &net_port, 0);
193
194 The next step is to restrict the current threa
195 (e.g. through a SUID binary). We now have a r
196 allowing read access to ``/usr`` while denying
197 the filesystem, and a second rule allowing HTT
198
199 .. code-block:: c
200
201 if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)
202 perror("Failed to restrict privileges"
203 close(ruleset_fd);
204 return 1;
205 }
206
207 The current thread is now ready to sandbox its
208
209 .. code-block:: c
210
211 if (landlock_restrict_self(ruleset_fd, 0))
212 perror("Failed to enforce ruleset");
213 close(ruleset_fd);
214 return 1;
215 }
216 close(ruleset_fd);
217
218 If the ``landlock_restrict_self`` system call
219 now restricted and this policy will be enforce
220 children as well. Once a thread is landlocked
221 security policy; only adding more restrictions
222 now in a new Landlock domain, merge of their p
223 ruleset.
224
225 Full working code can be found in `samples/lan
226
227 Good practices
228 --------------
229
230 It is recommended setting access rights to fil
231 possible. For instance, it is better to be ab
232 read-only hierarchy and ``~/tmp/`` as a read-w
233 ``~/`` as a read-only hierarchy and ``~/tmp/``
234 Following this good practice leads to self-suf
235 depend on their location (i.e. parent director
236 relevant when we want to allow linking or rena
237 access rights per directory enables to change
238 without relying on the destination directory a
239 are required for this operation, see ``LANDLOC
240 documentation).
241
242 Having self-sufficient hierarchies also helps
243 rights to the minimal set of data. This also
244 i.e. directories where data can be linked to
245 this depends on data organization, which might
246 In this case, granting read-write access to ``
247 access, would potentially allow to move ``~/tm
248 and still keep the ability to list the content
249
250 Layers of file path access rights
251 ---------------------------------
252
253 Each time a thread enforces a ruleset on itsel
254 with a new layer of policy. Indeed, this comp
255 the potentially other rulesets already restric
256 thread can then safely add more constraints to
257 ruleset.
258
259 One policy layer grants access to a file path
260 encountered on the path grants the access. A
261 a file path if all its enforced policy layers
262 the other system access controls (e.g. filesys
263 etc.).
264
265 Bind mounts and OverlayFS
266 -------------------------
267
268 Landlock enables to restrict access to file hi
269 access rights can be propagated with bind moun
270 Documentation/filesystems/sharedsubtree.rst) b
271 Documentation/filesystems/overlayfs.rst.
272
273 A bind mount mirrors a source file hierarchy t
274 hierarchy is then composed of the exact same f
275 be tied, either via the source or the destinat
276 access when they are encountered on a path, wh
277 access to multiple file hierarchies at the sam
278 are the result of bind mounts or not.
279
280 An OverlayFS mount point consists of upper and
281 combined in a merge directory, result of the m
282 may include files from the upper and lower lay
283 on the merge hierarchy only reflects on the up
284 policy point of view, each OverlayFS layers an
285 standalone and contains their own set of files
286 different from bind mounts. A policy restrict
287 restrict the resulted merged hierarchy, and vi
288 then only think about file hierarchies they wa
289 of the underlying filesystem.
290
291 Inheritance
292 -----------
293
294 Every new thread resulting from a :manpage:`cl
295 restrictions from its parent. This is similar
296 Documentation/userspace-api/seccomp_filter.rst
297 task's :manpage:`credentials(7)`. For instanc
298 Landlock rules to itself, but they will not be
299 sibling threads (unlike POSIX thread credentia
300 :manpage:`nptl(7)`).
301
302 When a thread sandboxes itself, we have the gu
303 policy will stay enforced on all this thread's
304 creating standalone and modular security polic
305 automatically be composed between themselves a
306 policies.
307
308 Ptrace restrictions
309 -------------------
310
311 A sandboxed process has less privileges than a
312 then be subject to additional restrictions whe
313 To be allowed to use :manpage:`ptrace(2)` and
314 process, a sandboxed process should have a sub
315 which means the tracee must be in a sub-domain
316
317 IPC scoping
318 -----------
319
320 Similar to the implicit `Ptrace restrictions`_
321 interactions between sandboxes. Each Landlock
322 for a set of actions by specifying it on a rul
323 sandboxed process should not be able to :manpa
324 non-sandboxed process through abstract :manpag
325 specify such restriction with ``LANDLOCK_SCOPE
326 Moreover, if a sandboxed process should not be
327 non-sandboxed process, we can specify this res
328 ``LANDLOCK_SCOPE_SIGNAL``.
329
330 A sandboxed process can connect to a non-sandb
331 not scoped. If a process's domain is scoped, i
332 created by processes in the same scope.
333 Moreover, If a process is scoped to send signa
334 only send signals to processes in the same sco
335
336 A connected datagram socket behaves like a str
337 scoped, meaning if the domain is scoped after
338 still :manpage:`send(2)` data just like a stre
339 scenario, a non-connected datagram socket cann
340 :manpage:`sendto(2)`) outside its scope.
341
342 A process with a scoped domain can inherit a s
343 process. The process cannot connect to this so
344 domain.
345
346 IPC scoping does not support exceptions, so if
347 be added to allow access to resources or proce
348
349 Truncating files
350 ----------------
351
352 The operations covered by ``LANDLOCK_ACCESS_FS
353 ``LANDLOCK_ACCESS_FS_TRUNCATE`` both change th
354 overlap in non-intuitive ways. It is recommen
355 these together.
356
357 A particularly surprising example is :manpage:
358 that this system call requires the rights to c
359 it also requires the truncate right if an exis
360 already present.
361
362 It should also be noted that truncating files
363 ``LANDLOCK_ACCESS_FS_WRITE_FILE`` right. Apar
364 system call, this can also be done through :ma
365 ``O_RDONLY | O_TRUNC``.
366
367 The truncate right is associated with the open
368
369 Rights associated with file descriptors
370 ---------------------------------------
371
372 When opening a file, the availability of the `
373 ``LANDLOCK_ACCESS_FS_IOCTL_DEV`` rights is ass
374 file descriptor and will be used for subsequen
375 using :manpage:`ftruncate(2)` and :manpage:`io
376 to opening a file for reading or writing, wher
377 :manpage:`open(2)`, but not during the subsequ
378 :manpage:`write(2)` calls.
379
380 As a consequence, it is possible that a proces
381 descriptors referring to the same file, but La
382 when operating with these file descriptors. T
383 ruleset gets enforced and the process keeps fi
384 both before and after the enforcement. It is
385 descriptors between processes, keeping their L
386 of the involved processes do not have an enfor
387
388 Compatibility
389 =============
390
391 Backward and forward compatibility
392 ----------------------------------
393
394 Landlock is designed to be compatible with pas
395 kernel. This is achieved thanks to the system
396 associated bitflags, particularly the ruleset'
397 handled access right explicit enables the kern
398 contract with each other. This is required to
399 get stricter with a system update, which could
400
401 Developers can subscribe to the `Landlock mail
402 <https://subspace.kernel.org/lists.linux.dev.h
403 test their applications with the latest availa
404 users, and because they may use different kern
405 encouraged to follow a best-effort security ap
406 ABI version at runtime and only enforcing the
407
408 .. _landlock_abi_versions:
409
410 Landlock ABI versions
411 ---------------------
412
413 The Landlock ABI version can be read with the
414 system call:
415
416 .. code-block:: c
417
418 int abi;
419
420 abi = landlock_create_ruleset(NULL, 0, LAN
421 if (abi < 0) {
422 switch (errno) {
423 case ENOSYS:
424 printf("Landlock is not supported
425 break;
426 case EOPNOTSUPP:
427 printf("Landlock is currently disa
428 break;
429 }
430 return 0;
431 }
432 if (abi >= 2) {
433 printf("Landlock supports LANDLOCK_ACC
434 }
435
436 The following kernel interfaces are implicitly
437 version. Features only supported from a speci
438 as such.
439
440 Kernel interface
441 ================
442
443 Access rights
444 -------------
445
446 .. kernel-doc:: include/uapi/linux/landlock.h
447 :identifiers: fs_access net_access scope
448
449 Creating a new ruleset
450 ----------------------
451
452 .. kernel-doc:: security/landlock/syscalls.c
453 :identifiers: sys_landlock_create_ruleset
454
455 .. kernel-doc:: include/uapi/linux/landlock.h
456 :identifiers: landlock_ruleset_attr
457
458 Extending a ruleset
459 -------------------
460
461 .. kernel-doc:: security/landlock/syscalls.c
462 :identifiers: sys_landlock_add_rule
463
464 .. kernel-doc:: include/uapi/linux/landlock.h
465 :identifiers: landlock_rule_type landlock_
466 landlock_net_port_attr
467
468 Enforcing a ruleset
469 -------------------
470
471 .. kernel-doc:: security/landlock/syscalls.c
472 :identifiers: sys_landlock_restrict_self
473
474 Current limitations
475 ===================
476
477 Filesystem topology modification
478 --------------------------------
479
480 Threads sandboxed with filesystem restrictions
481 topology, whether via :manpage:`mount(2)` or :
482 However, :manpage:`chroot(2)` calls are not de
483
484 Special filesystems
485 -------------------
486
487 Access to regular files and directories can be
488 according to the handled accesses of a ruleset
489 come from a user-visible filesystem (e.g. pipe
490 accessed through ``/proc/<pid>/fd/*``, cannot
491 restricted. Likewise, some special kernel fil
492 be accessed through ``/proc/<pid>/ns/*``, cann
493 restricted. However, thanks to the `ptrace re
494 sensitive ``/proc`` files are automatically re
495 hierarchies. Future Landlock evolutions could
496 restrict such paths with dedicated ruleset fla
497
498 Ruleset layers
499 --------------
500
501 There is a limit of 16 layers of stacked rules
502 task willing to enforce a new ruleset in compl
503 rulesets. Once this limit is reached, sys_lan
504 E2BIG. It is then strongly suggested to caref
505 life of a thread, especially for applications
506 that may also want to sandbox themselves (e.g.
507 etc.).
508
509 Memory usage
510 ------------
511
512 Kernel memory allocated to create rulesets is
513 by the Documentation/admin-guide/cgroup-v1/mem
514
515 IOCTL support
516 -------------
517
518 The ``LANDLOCK_ACCESS_FS_IOCTL_DEV`` right res
519 :manpage:`ioctl(2)`, but it only applies to *n
520 means specifically that pre-existing file desc
521 stderr are unaffected.
522
523 Users should be aware that TTY devices have tr
524 other processes on the same TTY through the ``
525 commands. Both of these require ``CAP_SYS_ADM
526 the behavior is configurable for ``TIOCSTI``.
527
528 On older systems, it is therefore recommended
529 descriptors, or to reopen them from ``/proc/se
530 ``LANDLOCK_ACCESS_FS_IOCTL_DEV`` right, if pos
531
532 Landlock's IOCTL support is coarse-grained at
533 fine-grained in the future. Until then, users
534 guarantees that they need through the file hie
535 ``LANDLOCK_ACCESS_FS_IOCTL_DEV`` right on file
536
537 Previous limitations
538 ====================
539
540 File renaming and linking (ABI < 2)
541 -----------------------------------
542
543 Because Landlock targets unprivileged access c
544 handle composition of rules. Such property al
545 Properly handling multiple layers of rulesets,
546 restrict access to files, also implies inherit
547 from a parent to its hierarchy. Because files
548 their hierarchy, moving or linking a file from
549 propagation of the hierarchy constraints, or r
550 according to the potentially lost constraints.
551 escalations through renaming or linking, and f
552 Landlock previously limited linking and renami
553 Starting with the Landlock ABI version 2, it i
554 control renaming and linking thanks to the new
555 access right.
556
557 File truncation (ABI < 3)
558 -------------------------
559
560 File truncation could not be denied before the
561 always allowed when using a kernel that only s
562
563 Starting with the Landlock ABI version 3, it i
564 truncation thanks to the new ``LANDLOCK_ACCESS
565
566 Network support (ABI < 4)
567 -------------------------
568
569 Starting with the Landlock ABI version 4, it i
570 bind and connect actions to only a set of allo
571 ``LANDLOCK_ACCESS_NET_BIND_TCP`` and ``LANDLOC
572 access rights.
573
574 IOCTL (ABI < 5)
575 ---------------
576
577 IOCTL operations could not be denied before th
578 :manpage:`ioctl(2)` is always allowed when usi
579 earlier ABI.
580
581 Starting with the Landlock ABI version 5, it i
582 :manpage:`ioctl(2)` using the new ``LANDLOCK_A
583
584 Abstract UNIX socket scoping (ABI < 6)
585 --------------------------------------
586
587 Starting with the Landlock ABI version 6, it i
588 connections to an abstract :manpage:`unix(7)`
589 ``LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET`` to the
590
591 Signal scoping (ABI < 6)
592 ------------------------
593
594 Starting with the Landlock ABI version 6, it i
595 :manpage:`signal(7)` sending by setting ``LAND
596 ``scoped`` ruleset attribute.
597
598 .. _kernel_support:
599
600 Kernel support
601 ==============
602
603 Build time configuration
604 ------------------------
605
606 Landlock was first introduced in Linux 5.13 bu
607 time with ``CONFIG_SECURITY_LANDLOCK=y``. Lan
608 time as the other security modules. The list
609 default is set with ``CONFIG_LSM``. The kerne
610 contains ``CONFIG_LSM=landlock,[...]`` with ``
611 potentially useful security modules for the ru
612 ``CONFIG_LSM`` help).
613
614 Boot time configuration
615 -----------------------
616
617 If the running kernel does not have ``landlock
618 enable Landlock by adding ``lsm=landlock,[...]
619 Documentation/admin-guide/kernel-parameters.rs
620 configuration.
621
622 For example, if the current built-in configura
623
624 .. code-block:: console
625
626 $ zgrep -h "^CONFIG_LSM=" "/boot/config-$(
627 CONFIG_LSM="lockdown,yama,integrity,apparm
628
629 ...and if the cmdline doesn't contain ``landlo
630
631 .. code-block:: console
632
633 $ sed -n 's/.*\(\<lsm=\S\+\).*/\1/p' /proc
634 lsm=lockdown,yama,integrity,apparmor
635
636 ...we should configure the boot loader to set
637 list with the ``landlock,`` prefix::
638
639 lsm=landlock,lockdown,yama,integrity,apparmo
640
641 After a reboot, we can check that Landlock is
642 kernel logs:
643
644 .. code-block:: console
645
646 # dmesg | grep landlock || journalctl -kb
647 [ 0.000000] Command line: [...] lsm=lan
648 [ 0.000000] Kernel command line: [...]
649 [ 0.000000] LSM: initializing lsm=lockd
650 [ 0.000000] landlock: Up and running.
651
652 The kernel may be configured at build time to
653 ``capability`` LSMs. In that case, these LSMs
654 the ``LSM: initializing`` log line as well, ev
655 the boot loader.
656
657 Network support
658 ---------------
659
660 To be able to explicitly allow TCP operations
661 ``LANDLOCK_ACCESS_NET_BIND_TCP``), the kernel
662 (``CONFIG_INET=y``). Otherwise, sys_landlock_
663 ``EAFNOSUPPORT`` error, which can safely be ig
664 operation is already not possible.
665
666 Questions and answers
667 =====================
668
669 What about user space sandbox managers?
670 ---------------------------------------
671
672 Using user space process to enforce restrictio
673 to race conditions or inconsistent evaluations
674 the OS code and state
675 <https://www.ndss-symposium.org/ndss2003/traps
676
677 What about namespaces and containers?
678 -------------------------------------
679
680 Namespaces can help create sandboxes but they
681 access-control and then miss useful features f
682 fine-grained restrictions). Moreover, their c
683 issues, especially when untrusted processes ca
684 `Controlling access to user namespaces <https:
685
686 Additional documentation
687 ========================
688
689 * Documentation/security/landlock.rst
690 * https://landlock.io
691
692 .. Links
693 .. _samples/landlock/sandboxer.c:
694 https://git.kernel.org/pub/scm/linux/kernel
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.