Commit | Line | Data |
---|---|---|
5526b450 MS |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | .. Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net> | |
3 | .. Copyright © 2019-2020 ANSSI | |
5e469829 | 4 | .. Copyright © 2021-2022 Microsoft Corporation |
5526b450 MS |
5 | |
6 | ===================================== | |
7 | Landlock: unprivileged access control | |
8 | ===================================== | |
9 | ||
10 | :Author: Mickaël Salaün | |
dba40c77 | 11 | :Date: September 2024 |
5526b450 MS |
12 | |
13 | The goal of Landlock is to enable to restrict ambient rights (e.g. global | |
51442e8d KM |
14 | filesystem or network access) for a set of processes. Because Landlock |
15 | is a stackable LSM, it makes possible to create safe security sandboxes as new | |
16 | security layers in addition to the existing system-wide access-controls. This | |
17 | kind of sandbox is expected to help mitigate the security impact of bugs or | |
5526b450 MS |
18 | unexpected/malicious behaviors in user space applications. Landlock empowers |
19 | any process, including unprivileged ones, to securely restrict themselves. | |
20 | ||
5e469829 | 21 | We can quickly make sure that Landlock is enabled in the running system by |
0e89ef6f MS |
22 | looking for "landlock: Up and running" in kernel logs (as root): |
23 | ``dmesg | grep landlock || journalctl -kb -g landlock`` . | |
24 | Developers can also easily check for Landlock support with a | |
25 | :ref:`related system call <landlock_abi_versions>`. | |
26 | If Landlock is not currently supported, we need to | |
27 | :ref:`configure the kernel appropriately <kernel_support>`. | |
5e469829 | 28 | |
5526b450 MS |
29 | Landlock rules |
30 | ============== | |
31 | ||
51442e8d KM |
32 | A Landlock rule describes an action on an object which the process intends to |
33 | perform. A set of rules is aggregated in a ruleset, which can then restrict | |
5526b450 MS |
34 | the thread enforcing it, and its future children. |
35 | ||
51442e8d KM |
36 | The two existing types of rules are: |
37 | ||
38 | Filesystem rules | |
39 | For these rules, the object is a file hierarchy, | |
40 | and the related filesystem actions are defined with | |
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 `network access rights`. | |
46 | ||
5526b450 MS |
47 | Defining and enforcing a security policy |
48 | ---------------------------------------- | |
49 | ||
51442e8d KM |
50 | We first need to define the ruleset that will contain our rules. |
51 | ||
52 | For this example, the ruleset will contain rules that only allow filesystem | |
53 | read actions and establish a specific TCP connection. Filesystem write | |
54 | actions and other TCP actions will be denied. | |
55 | ||
56 | The ruleset then needs to handle both these kinds of actions. This is | |
57 | required for backward and forward compatibility (i.e. the kernel and user | |
58 | space may not know each other's supported restrictions), hence the need | |
59 | to be explicit about the denied-by-default access rights. | |
5526b450 MS |
60 | |
61 | .. code-block:: c | |
62 | ||
5526b450 MS |
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 | | |
6f59abfa | 77 | LANDLOCK_ACCESS_FS_MAKE_SYM | |
ede2a343 | 78 | LANDLOCK_ACCESS_FS_REFER | |
a3746da8 GN |
79 | LANDLOCK_ACCESS_FS_TRUNCATE | |
80 | LANDLOCK_ACCESS_FS_IOCTL_DEV, | |
51442e8d KM |
81 | .handled_access_net = |
82 | LANDLOCK_ACCESS_NET_BIND_TCP | | |
83 | LANDLOCK_ACCESS_NET_CONNECT_TCP, | |
dba40c77 | 84 | .scoped = |
1ca98081 TF |
85 | LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET | |
86 | LANDLOCK_SCOPE_SIGNAL, | |
5526b450 MS |
87 | }; |
88 | ||
6f59abfa MS |
89 | Because we may not know on which kernel version an application will be |
90 | executed, it is safer to follow a best-effort security approach. Indeed, we | |
91 | should try to protect users as much as possible whatever the kernel they are | |
a3746da8 GN |
92 | using. |
93 | ||
94 | To be compatible with older Linux versions, we detect the available Landlock ABI | |
95 | version, and only use the available subset of access rights: | |
6f59abfa MS |
96 | |
97 | .. code-block:: c | |
98 | ||
99 | int abi; | |
100 | ||
101 | abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION); | |
ede2a343 GN |
102 | if (abi < 0) { |
103 | /* Degrades gracefully if Landlock is not handled. */ | |
104 | perror("The running kernel does not enable to use Landlock"); | |
105 | return 0; | |
106 | } | |
107 | switch (abi) { | |
108 | case 1: | |
109 | /* Removes LANDLOCK_ACCESS_FS_REFER for ABI < 2 */ | |
6f59abfa | 110 | ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_REFER; |
ede2a343 GN |
111 | __attribute__((fallthrough)); |
112 | case 2: | |
113 | /* Removes LANDLOCK_ACCESS_FS_TRUNCATE for ABI < 3 */ | |
114 | ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_TRUNCATE; | |
51442e8d KM |
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); | |
a3746da8 GN |
121 | __attribute__((fallthrough)); |
122 | case 4: | |
123 | /* Removes LANDLOCK_ACCESS_FS_IOCTL_DEV for ABI < 5 */ | |
124 | ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_IOCTL_DEV; | |
dba40c77 TF |
125 | __attribute__((fallthrough)); |
126 | case 5: | |
1ca98081 TF |
127 | /* Removes LANDLOCK_SCOPE_* for ABI < 6 */ |
128 | ruleset_attr.scoped &= ~(LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET | | |
129 | LANDLOCK_SCOPE_SIGNAL); | |
6f59abfa MS |
130 | } |
131 | ||
132 | This enables to create an inclusive ruleset that will contain our rules. | |
133 | ||
134 | .. code-block:: c | |
135 | ||
136 | int ruleset_fd; | |
137 | ||
5526b450 MS |
138 | ruleset_fd = landlock_create_ruleset(&ruleset_attr, sizeof(ruleset_attr), 0); |
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 thanks to the returned file | |
145 | descriptor referring to this ruleset. The rule will only allow reading the | |
146 | file hierarchy ``/usr``. Without another rule, write actions would then be | |
147 | denied by the ruleset. To add ``/usr`` to the ruleset, we open it with the | |
148 | ``O_PATH`` flag and fill the &struct landlock_path_beneath_attr with this file | |
149 | descriptor. | |
150 | ||
151 | .. code-block:: c | |
152 | ||
153 | int err; | |
154 | struct landlock_path_beneath_attr path_beneath = { | |
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_PATH | O_CLOEXEC); | |
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, LANDLOCK_RULE_PATH_BENEATH, | |
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 | ||
6f59abfa MS |
176 | It may also be required to create rules following the same logic as explained |
177 | for the ruleset creation, by filtering access rights according to the Landlock | |
ede2a343 GN |
178 | ABI version. In this example, this is not required because all of the requested |
179 | ``allowed_access`` rights are already available in ABI 1. | |
6f59abfa | 180 | |
51442e8d KM |
181 | For network access-control, we can add a set of rules that allow to use a port |
182 | number for a specific action: HTTPS connections. | |
183 | ||
184 | .. code-block:: c | |
185 | ||
186 | struct landlock_net_port_attr net_port = { | |
187 | .allowed_access = LANDLOCK_ACCESS_NET_CONNECT_TCP, | |
188 | .port = 443, | |
189 | }; | |
190 | ||
191 | err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_NET_PORT, | |
192 | &net_port, 0); | |
193 | ||
194 | The next step is to restrict the current thread from gaining more privileges | |
195 | (e.g. through a SUID binary). We now have a ruleset with the first rule | |
196 | allowing read access to ``/usr`` while denying all other handled accesses for | |
197 | the filesystem, and a second rule allowing HTTPS connections. | |
5526b450 MS |
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 itself with the ruleset. | |
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 | ||
2fff00c8 MS |
218 | If the ``landlock_restrict_self`` system call succeeds, the current thread is |
219 | now restricted and this policy will be enforced on all its subsequently created | |
5526b450 MS |
220 | children as well. Once a thread is landlocked, there is no way to remove its |
221 | security policy; only adding more restrictions is allowed. These threads are | |
222 | now in a new Landlock domain, merge of their parent one (if any) with the new | |
223 | ruleset. | |
224 | ||
225 | Full working code can be found in `samples/landlock/sandboxer.c`_. | |
226 | ||
09340cf4 MS |
227 | Good practices |
228 | -------------- | |
229 | ||
230 | It is recommended setting access rights to file hierarchy leaves as much as | |
231 | possible. For instance, it is better to be able to have ``~/doc/`` as a | |
232 | read-only hierarchy and ``~/tmp/`` as a read-write hierarchy, compared to | |
233 | ``~/`` as a read-only hierarchy and ``~/tmp/`` as a read-write hierarchy. | |
16023b05 | 234 | Following this good practice leads to self-sufficient hierarchies that do not |
09340cf4 MS |
235 | depend on their location (i.e. parent directories). This is particularly |
236 | relevant when we want to allow linking or renaming. Indeed, having consistent | |
237 | access rights per directory enables to change the location of such directory | |
238 | without relying on the destination directory access rights (except those that | |
2fff00c8 MS |
239 | are required for this operation, see ``LANDLOCK_ACCESS_FS_REFER`` |
240 | documentation). | |
a3746da8 | 241 | |
09340cf4 MS |
242 | Having self-sufficient hierarchies also helps to tighten the required access |
243 | rights to the minimal set of data. This also helps avoid sinkhole directories, | |
244 | i.e. directories where data can be linked to but not linked from. However, | |
245 | this depends on data organization, which might not be controlled by developers. | |
246 | In this case, granting read-write access to ``~/tmp/``, instead of write-only | |
247 | access, would potentially allow to move ``~/tmp/`` to a non-readable directory | |
248 | and still keep the ability to list the content of ``~/tmp/``. | |
249 | ||
5526b450 MS |
250 | Layers of file path access rights |
251 | --------------------------------- | |
252 | ||
253 | Each time a thread enforces a ruleset on itself, it updates its Landlock domain | |
254 | with a new layer of policy. Indeed, this complementary policy is stacked with | |
255 | the potentially other rulesets already restricting this thread. A sandboxed | |
256 | thread can then safely add more constraints to itself with a new enforced | |
257 | ruleset. | |
258 | ||
259 | One policy layer grants access to a file path if at least one of its rules | |
260 | encountered on the path grants the access. A sandboxed thread can only access | |
261 | a file path if all its enforced policy layers grant the access as well as all | |
262 | the other system access controls (e.g. filesystem DAC, other LSM policies, | |
263 | etc.). | |
264 | ||
265 | Bind mounts and OverlayFS | |
266 | ------------------------- | |
267 | ||
268 | Landlock enables to restrict access to file hierarchies, which means that these | |
269 | access rights can be propagated with bind mounts (cf. | |
69fe5540 MCC |
270 | Documentation/filesystems/sharedsubtree.rst) but not with |
271 | Documentation/filesystems/overlayfs.rst. | |
5526b450 MS |
272 | |
273 | A bind mount mirrors a source file hierarchy to a destination. The destination | |
274 | hierarchy is then composed of the exact same files, on which Landlock rules can | |
275 | be tied, either via the source or the destination path. These rules restrict | |
276 | access when they are encountered on a path, which means that they can restrict | |
277 | access to multiple file hierarchies at the same time, whether these hierarchies | |
278 | are the result of bind mounts or not. | |
279 | ||
280 | An OverlayFS mount point consists of upper and lower layers. These layers are | |
281 | combined in a merge directory, result of the mount point. This merge hierarchy | |
282 | may include files from the upper and lower layers, but modifications performed | |
283 | on the merge hierarchy only reflects on the upper layer. From a Landlock | |
284 | policy point of view, each OverlayFS layers and merge hierarchies are | |
285 | standalone and contains their own set of files and directories, which is | |
286 | different from bind mounts. A policy restricting an OverlayFS layer will not | |
287 | restrict the resulted merged hierarchy, and vice versa. Landlock users should | |
288 | then only think about file hierarchies they want to allow access to, regardless | |
289 | of the underlying filesystem. | |
290 | ||
291 | Inheritance | |
292 | ----------- | |
293 | ||
294 | Every new thread resulting from a :manpage:`clone(2)` inherits Landlock domain | |
295 | restrictions from its parent. This is similar to the seccomp inheritance (cf. | |
69fe5540 MCC |
296 | Documentation/userspace-api/seccomp_filter.rst) or any other LSM dealing with |
297 | task's :manpage:`credentials(7)`. For instance, one process's thread may apply | |
5526b450 MS |
298 | Landlock rules to itself, but they will not be automatically applied to other |
299 | sibling threads (unlike POSIX thread credential changes, cf. | |
300 | :manpage:`nptl(7)`). | |
301 | ||
302 | When a thread sandboxes itself, we have the guarantee that the related security | |
303 | policy will stay enforced on all this thread's descendants. This allows | |
304 | creating standalone and modular security policies per application, which will | |
305 | automatically be composed between themselves according to their runtime parent | |
306 | policies. | |
307 | ||
308 | Ptrace restrictions | |
309 | ------------------- | |
310 | ||
311 | A sandboxed process has less privileges than a non-sandboxed process and must | |
312 | then be subject to additional restrictions when manipulating another process. | |
313 | To be allowed to use :manpage:`ptrace(2)` and related syscalls on a target | |
314 | process, a sandboxed process should have a subset of the target process rules, | |
315 | which means the tracee must be in a sub-domain of the tracer. | |
316 | ||
dba40c77 TF |
317 | IPC scoping |
318 | ----------- | |
319 | ||
320 | Similar to the implicit `Ptrace restrictions`_, we may want to further restrict | |
321 | interactions between sandboxes. Each Landlock domain can be explicitly scoped | |
322 | for a set of actions by specifying it on a ruleset. For example, if a | |
323 | sandboxed process should not be able to :manpage:`connect(2)` to a | |
324 | non-sandboxed process through abstract :manpage:`unix(7)` sockets, we can | |
325 | specify such restriction with ``LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET``. | |
1ca98081 TF |
326 | Moreover, if a sandboxed process should not be able to send a signal to a |
327 | non-sandboxed process, we can specify this restriction with | |
328 | ``LANDLOCK_SCOPE_SIGNAL``. | |
dba40c77 TF |
329 | |
330 | A sandboxed process can connect to a non-sandboxed process when its domain is | |
331 | not scoped. If a process's domain is scoped, it can only connect to sockets | |
332 | created by processes in the same scope. | |
1ca98081 TF |
333 | Moreover, If a process is scoped to send signal to a non-scoped process, it can |
334 | only send signals to processes in the same scope. | |
dba40c77 TF |
335 | |
336 | A connected datagram socket behaves like a stream socket when its domain is | |
337 | scoped, meaning if the domain is scoped after the socket is connected , it can | |
338 | still :manpage:`send(2)` data just like a stream socket. However, in the same | |
339 | scenario, a non-connected datagram socket cannot send data (with | |
340 | :manpage:`sendto(2)`) outside its scope. | |
341 | ||
342 | A process with a scoped domain can inherit a socket created by a non-scoped | |
343 | process. The process cannot connect to this socket since it has a scoped | |
344 | domain. | |
345 | ||
346 | IPC scoping does not support exceptions, so if a domain is scoped, no rules can | |
347 | be added to allow access to resources or processes outside of the scope. | |
348 | ||
ede2a343 GN |
349 | Truncating files |
350 | ---------------- | |
351 | ||
352 | The operations covered by ``LANDLOCK_ACCESS_FS_WRITE_FILE`` and | |
353 | ``LANDLOCK_ACCESS_FS_TRUNCATE`` both change the contents of a file and sometimes | |
354 | overlap in non-intuitive ways. It is recommended to always specify both of | |
355 | these together. | |
356 | ||
357 | A particularly surprising example is :manpage:`creat(2)`. The name suggests | |
358 | that this system call requires the rights to create and write files. However, | |
359 | it also requires the truncate right if an existing file under the same name is | |
360 | already present. | |
361 | ||
362 | It should also be noted that truncating files does not require the | |
363 | ``LANDLOCK_ACCESS_FS_WRITE_FILE`` right. Apart from the :manpage:`truncate(2)` | |
364 | system call, this can also be done through :manpage:`open(2)` with the flags | |
365 | ``O_RDONLY | O_TRUNC``. | |
366 | ||
a3746da8 GN |
367 | The truncate right is associated with the opened file (see below). |
368 | ||
369 | Rights associated with file descriptors | |
370 | --------------------------------------- | |
371 | ||
372 | When opening a file, the availability of the ``LANDLOCK_ACCESS_FS_TRUNCATE`` and | |
373 | ``LANDLOCK_ACCESS_FS_IOCTL_DEV`` rights is associated with the newly created | |
374 | file descriptor and will be used for subsequent truncation and ioctl attempts | |
375 | using :manpage:`ftruncate(2)` and :manpage:`ioctl(2)`. The behavior is similar | |
376 | to opening a file for reading or writing, where permissions are checked during | |
377 | :manpage:`open(2)`, but not during the subsequent :manpage:`read(2)` and | |
ede2a343 GN |
378 | :manpage:`write(2)` calls. |
379 | ||
a3746da8 GN |
380 | As a consequence, it is possible that a process has multiple open file |
381 | descriptors referring to the same file, but Landlock enforces different things | |
382 | when operating with these file descriptors. This can happen when a Landlock | |
383 | ruleset gets enforced and the process keeps file descriptors which were opened | |
384 | both before and after the enforcement. It is also possible to pass such file | |
385 | descriptors between processes, keeping their Landlock properties, even when some | |
386 | of the involved processes do not have an enforced Landlock ruleset. | |
ede2a343 | 387 | |
6f59abfa MS |
388 | Compatibility |
389 | ============= | |
390 | ||
391 | Backward and forward compatibility | |
392 | ---------------------------------- | |
393 | ||
394 | Landlock is designed to be compatible with past and future versions of the | |
395 | kernel. This is achieved thanks to the system call attributes and the | |
2fff00c8 | 396 | associated bitflags, particularly the ruleset's ``handled_access_fs``. Making |
6f59abfa MS |
397 | handled access right explicit enables the kernel and user space to have a clear |
398 | contract with each other. This is required to make sure sandboxing will not | |
399 | get stricter with a system update, which could break applications. | |
400 | ||
401 | Developers can subscribe to the `Landlock mailing list | |
402 | <https://subspace.kernel.org/lists.linux.dev.html>`_ to knowingly update and | |
403 | test their applications with the latest available features. In the interest of | |
404 | users, and because they may use different kernel versions, it is strongly | |
405 | encouraged to follow a best-effort security approach by checking the Landlock | |
406 | ABI version at runtime and only enforcing the supported features. | |
407 | ||
5e469829 MS |
408 | .. _landlock_abi_versions: |
409 | ||
6f59abfa MS |
410 | Landlock ABI versions |
411 | --------------------- | |
412 | ||
413 | The Landlock ABI version can be read with the sys_landlock_create_ruleset() | |
414 | system call: | |
415 | ||
416 | .. code-block:: c | |
417 | ||
418 | int abi; | |
419 | ||
420 | abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION); | |
421 | if (abi < 0) { | |
422 | switch (errno) { | |
423 | case ENOSYS: | |
424 | printf("Landlock is not supported by the current kernel.\n"); | |
425 | break; | |
426 | case EOPNOTSUPP: | |
427 | printf("Landlock is currently disabled.\n"); | |
428 | break; | |
429 | } | |
430 | return 0; | |
431 | } | |
432 | if (abi >= 2) { | |
433 | printf("Landlock supports LANDLOCK_ACCESS_FS_REFER.\n"); | |
434 | } | |
435 | ||
436 | The following kernel interfaces are implicitly supported by the first ABI | |
437 | version. Features only supported from a specific version are explicitly marked | |
438 | as such. | |
439 | ||
5526b450 MS |
440 | Kernel interface |
441 | ================ | |
442 | ||
443 | Access rights | |
444 | ------------- | |
445 | ||
446 | .. kernel-doc:: include/uapi/linux/landlock.h | |
dba40c77 | 447 | :identifiers: fs_access net_access scope |
5526b450 MS |
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_path_beneath_attr | |
51442e8d | 466 | landlock_net_port_attr |
5526b450 MS |
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 | ||
5526b450 MS |
477 | Filesystem topology modification |
478 | -------------------------------- | |
479 | ||
d7220364 MS |
480 | Threads sandboxed with filesystem restrictions cannot modify filesystem |
481 | topology, whether via :manpage:`mount(2)` or :manpage:`pivot_root(2)`. | |
482 | However, :manpage:`chroot(2)` calls are not denied. | |
5526b450 MS |
483 | |
484 | Special filesystems | |
485 | ------------------- | |
486 | ||
487 | Access to regular files and directories can be restricted by Landlock, | |
488 | according to the handled accesses of a ruleset. However, files that do not | |
489 | come from a user-visible filesystem (e.g. pipe, socket), but can still be | |
490 | accessed through ``/proc/<pid>/fd/*``, cannot currently be explicitly | |
491 | restricted. Likewise, some special kernel filesystems such as nsfs, which can | |
492 | be accessed through ``/proc/<pid>/ns/*``, cannot currently be explicitly | |
493 | restricted. However, thanks to the `ptrace restrictions`_, access to such | |
494 | sensitive ``/proc`` files are automatically restricted according to domain | |
495 | hierarchies. Future Landlock evolutions could still enable to explicitly | |
496 | restrict such paths with dedicated ruleset flags. | |
497 | ||
498 | Ruleset layers | |
499 | -------------- | |
500 | ||
75c542d6 MS |
501 | There is a limit of 16 layers of stacked rulesets. This can be an issue for a |
502 | task willing to enforce a new ruleset in complement to its 16 inherited | |
5526b450 MS |
503 | rulesets. Once this limit is reached, sys_landlock_restrict_self() returns |
504 | E2BIG. It is then strongly suggested to carefully build rulesets once in the | |
505 | life of a thread, especially for applications able to launch other applications | |
506 | that may also want to sandbox themselves (e.g. shells, container managers, | |
507 | etc.). | |
508 | ||
509 | Memory usage | |
510 | ------------ | |
511 | ||
512 | Kernel memory allocated to create rulesets is accounted and can be restricted | |
69fe5540 | 513 | by the Documentation/admin-guide/cgroup-v1/memory.rst. |
5526b450 | 514 | |
a3746da8 GN |
515 | IOCTL support |
516 | ------------- | |
517 | ||
518 | The ``LANDLOCK_ACCESS_FS_IOCTL_DEV`` right restricts the use of | |
519 | :manpage:`ioctl(2)`, but it only applies to *newly opened* device files. This | |
520 | means specifically that pre-existing file descriptors like stdin, stdout and | |
521 | stderr are unaffected. | |
522 | ||
523 | Users should be aware that TTY devices have traditionally permitted to control | |
524 | other processes on the same TTY through the ``TIOCSTI`` and ``TIOCLINUX`` IOCTL | |
525 | commands. Both of these require ``CAP_SYS_ADMIN`` on modern Linux systems, but | |
526 | the behavior is configurable for ``TIOCSTI``. | |
527 | ||
528 | On older systems, it is therefore recommended to close inherited TTY file | |
529 | descriptors, or to reopen them from ``/proc/self/fd/*`` without the | |
530 | ``LANDLOCK_ACCESS_FS_IOCTL_DEV`` right, if possible. | |
531 | ||
532 | Landlock's IOCTL support is coarse-grained at the moment, but may become more | |
533 | fine-grained in the future. Until then, users are advised to establish the | |
534 | guarantees that they need through the file hierarchy, by only allowing the | |
535 | ``LANDLOCK_ACCESS_FS_IOCTL_DEV`` right on files where it is really required. | |
536 | ||
6f59abfa MS |
537 | Previous limitations |
538 | ==================== | |
539 | ||
16023b05 MS |
540 | File renaming and linking (ABI < 2) |
541 | ----------------------------------- | |
6f59abfa MS |
542 | |
543 | Because Landlock targets unprivileged access controls, it needs to properly | |
544 | handle composition of rules. Such property also implies rules nesting. | |
545 | Properly handling multiple layers of rulesets, each one of them able to | |
546 | restrict access to files, also implies inheritance of the ruleset restrictions | |
547 | from a parent to its hierarchy. Because files are identified and restricted by | |
548 | their hierarchy, moving or linking a file from one directory to another implies | |
549 | propagation of the hierarchy constraints, or restriction of these actions | |
550 | according to the potentially lost constraints. To protect against privilege | |
551 | escalations through renaming or linking, and for the sake of simplicity, | |
552 | Landlock previously limited linking and renaming to the same directory. | |
553 | Starting with the Landlock ABI version 2, it is now possible to securely | |
2fff00c8 | 554 | control renaming and linking thanks to the new ``LANDLOCK_ACCESS_FS_REFER`` |
6f59abfa MS |
555 | access right. |
556 | ||
ede2a343 GN |
557 | File truncation (ABI < 3) |
558 | ------------------------- | |
559 | ||
560 | File truncation could not be denied before the third Landlock ABI, so it is | |
561 | always allowed when using a kernel that only supports the first or second ABI. | |
562 | ||
563 | Starting with the Landlock ABI version 3, it is now possible to securely control | |
564 | truncation thanks to the new ``LANDLOCK_ACCESS_FS_TRUNCATE`` access right. | |
565 | ||
51442e8d KM |
566 | Network support (ABI < 4) |
567 | ------------------------- | |
568 | ||
569 | Starting with the Landlock ABI version 4, it is now possible to restrict TCP | |
570 | bind and connect actions to only a set of allowed ports thanks to the new | |
571 | ``LANDLOCK_ACCESS_NET_BIND_TCP`` and ``LANDLOCK_ACCESS_NET_CONNECT_TCP`` | |
572 | access rights. | |
573 | ||
a3746da8 GN |
574 | IOCTL (ABI < 5) |
575 | --------------- | |
576 | ||
577 | IOCTL operations could not be denied before the fifth Landlock ABI, so | |
578 | :manpage:`ioctl(2)` is always allowed when using a kernel that only supports an | |
579 | earlier ABI. | |
580 | ||
581 | Starting with the Landlock ABI version 5, it is possible to restrict the use of | |
582 | :manpage:`ioctl(2)` using the new ``LANDLOCK_ACCESS_FS_IOCTL_DEV`` right. | |
583 | ||
dba40c77 TF |
584 | Abstract UNIX socket scoping (ABI < 6) |
585 | -------------------------------------- | |
586 | ||
587 | Starting with the Landlock ABI version 6, it is possible to restrict | |
588 | connections to an abstract :manpage:`unix(7)` socket by setting | |
589 | ``LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET`` to the ``scoped`` ruleset attribute. | |
590 | ||
1ca98081 TF |
591 | Signal scoping (ABI < 6) |
592 | ------------------------ | |
593 | ||
594 | Starting with the Landlock ABI version 6, it is possible to restrict | |
595 | :manpage:`signal(7)` sending by setting ``LANDLOCK_SCOPE_SIGNAL`` to the | |
596 | ``scoped`` ruleset attribute. | |
597 | ||
5e469829 MS |
598 | .. _kernel_support: |
599 | ||
600 | Kernel support | |
601 | ============== | |
602 | ||
0e89ef6f MS |
603 | Build time configuration |
604 | ------------------------ | |
605 | ||
5e469829 | 606 | Landlock was first introduced in Linux 5.13 but it must be configured at build |
2fff00c8 | 607 | time with ``CONFIG_SECURITY_LANDLOCK=y``. Landlock must also be enabled at boot |
5e469829 | 608 | time as the other security modules. The list of security modules enabled by |
2fff00c8 MS |
609 | default is set with ``CONFIG_LSM``. The kernel configuration should then |
610 | contains ``CONFIG_LSM=landlock,[...]`` with ``[...]`` as the list of other | |
5e469829 | 611 | potentially useful security modules for the running system (see the |
2fff00c8 | 612 | ``CONFIG_LSM`` help). |
5e469829 | 613 | |
0e89ef6f MS |
614 | Boot time configuration |
615 | ----------------------- | |
616 | ||
2fff00c8 | 617 | If the running kernel does not have ``landlock`` in ``CONFIG_LSM``, then we can |
0e89ef6f MS |
618 | enable Landlock by adding ``lsm=landlock,[...]`` to |
619 | Documentation/admin-guide/kernel-parameters.rst in the boot loader | |
5e469829 MS |
620 | configuration. |
621 | ||
0e89ef6f MS |
622 | For example, if the current built-in configuration is: |
623 | ||
624 | .. code-block:: console | |
625 | ||
626 | $ zgrep -h "^CONFIG_LSM=" "/boot/config-$(uname -r)" /proc/config.gz 2>/dev/null | |
627 | CONFIG_LSM="lockdown,yama,integrity,apparmor" | |
628 | ||
629 | ...and if the cmdline doesn't contain ``landlock`` either: | |
630 | ||
631 | .. code-block:: console | |
632 | ||
633 | $ sed -n 's/.*\(\<lsm=\S\+\).*/\1/p' /proc/cmdline | |
634 | lsm=lockdown,yama,integrity,apparmor | |
635 | ||
636 | ...we should configure the boot loader to set a cmdline extending the ``lsm`` | |
637 | list with the ``landlock,`` prefix:: | |
638 | ||
639 | lsm=landlock,lockdown,yama,integrity,apparmor | |
640 | ||
641 | After a reboot, we can check that Landlock is up and running by looking at | |
642 | kernel logs: | |
643 | ||
644 | .. code-block:: console | |
645 | ||
646 | # dmesg | grep landlock || journalctl -kb -g landlock | |
647 | [ 0.000000] Command line: [...] lsm=landlock,lockdown,yama,integrity,apparmor | |
648 | [ 0.000000] Kernel command line: [...] lsm=landlock,lockdown,yama,integrity,apparmor | |
649 | [ 0.000000] LSM: initializing lsm=lockdown,capability,landlock,yama,integrity,apparmor | |
650 | [ 0.000000] landlock: Up and running. | |
651 | ||
652 | The kernel may be configured at build time to always load the ``lockdown`` and | |
653 | ``capability`` LSMs. In that case, these LSMs will appear at the beginning of | |
654 | the ``LSM: initializing`` log line as well, even if they are not configured in | |
655 | the boot loader. | |
656 | ||
657 | Network support | |
658 | --------------- | |
659 | ||
51442e8d KM |
660 | To be able to explicitly allow TCP operations (e.g., adding a network rule with |
661 | ``LANDLOCK_ACCESS_NET_BIND_TCP``), the kernel must support TCP | |
662 | (``CONFIG_INET=y``). Otherwise, sys_landlock_add_rule() returns an | |
663 | ``EAFNOSUPPORT`` error, which can safely be ignored because this kind of TCP | |
664 | operation is already not possible. | |
665 | ||
5526b450 MS |
666 | Questions and answers |
667 | ===================== | |
668 | ||
669 | What about user space sandbox managers? | |
670 | --------------------------------------- | |
671 | ||
672 | Using user space process to enforce restrictions on kernel resources can lead | |
673 | to race conditions or inconsistent evaluations (i.e. `Incorrect mirroring of | |
674 | the OS code and state | |
675 | <https://www.ndss-symposium.org/ndss2003/traps-and-pitfalls-practical-problems-system-call-interposition-based-security-tools/>`_). | |
676 | ||
677 | What about namespaces and containers? | |
678 | ------------------------------------- | |
679 | ||
680 | Namespaces can help create sandboxes but they are not designed for | |
681 | access-control and then miss useful features for such use case (e.g. no | |
682 | fine-grained restrictions). Moreover, their complexity can lead to security | |
683 | issues, especially when untrusted processes can manipulate them (cf. | |
684 | `Controlling access to user namespaces <https://lwn.net/Articles/673597/>`_). | |
685 | ||
686 | Additional documentation | |
687 | ======================== | |
688 | ||
69fe5540 | 689 | * Documentation/security/landlock.rst |
5526b450 MS |
690 | * https://landlock.io |
691 | ||
692 | .. Links | |
693 | .. _samples/landlock/sandboxer.c: | |
694 | https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/samples/landlock/sandboxer.c |