tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
landlock: Add audit documentation
Because audit is dedicated to the system administrator, create a new
entry in Documentation/admin-guide/LSM . Extend other Landlock
documentation's pages with this new one.
Extend UAPI with the new log flags.
Extend the guiding principles with logs.
Cc: Günther Noack <gnoack@google.com>
Cc: Paul Moore <paul@paul-moore.com>
Link: https://lore.kernel.org/r/20250320190717.2287696-29-mic@digikod.net
Signed-off-by: Mickaël Salaün <mic@digikod.net>
+189
-1
+158
Documentation/admin-guide/LSM/landlock.rst
+158
Documentation/admin-guide/LSM/landlock.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
.. Copyright © 2025 Microsoft Corporation
3
+
4
+
================================
5
+
Landlock: system-wide management
6
+
================================
7
+
8
+
:Author: Mickaël Salaün
9
+
:Date: March 2025
10
+
11
+
Landlock can leverage the audit framework to log events.
12
+
13
+
User space documentation can be found here:
14
+
Documentation/userspace-api/landlock.rst.
15
+
16
+
Audit
17
+
=====
18
+
19
+
Denied access requests are logged by default for a sandboxed program if `audit`
20
+
is enabled. This default behavior can be changed with the
21
+
sys_landlock_restrict_self() flags (cf.
22
+
Documentation/userspace-api/landlock.rst). Landlock logs can also be masked
23
+
thanks to audit rules. Landlock can generate 2 audit record types.
24
+
25
+
Record types
26
+
------------
27
+
28
+
AUDIT_LANDLOCK_ACCESS
29
+
This record type identifies a denied access request to a kernel resource.
30
+
The ``domain`` field indicates the ID of the domain that blocked the
31
+
request. The ``blockers`` field indicates the cause(s) of this denial
32
+
(separated by a comma), and the following fields identify the kernel object
33
+
(similar to SELinux). There may be more than one of this record type per
34
+
audit event.
35
+
36
+
Example with a file link request generating two records in the same event::
37
+
38
+
domain=195ba459b blockers=fs.refer path="/usr/bin" dev="vda2" ino=351
39
+
domain=195ba459b blockers=fs.make_reg,fs.refer path="/usr/local" dev="vda2" ino=365
40
+
41
+
AUDIT_LANDLOCK_DOMAIN
42
+
This record type describes the status of a Landlock domain. The ``status``
43
+
field can be either ``allocated`` or ``deallocated``.
44
+
45
+
The ``allocated`` status is part of the same audit event and follows
46
+
the first logged ``AUDIT_LANDLOCK_ACCESS`` record of a domain. It identifies
47
+
Landlock domain information at the time of the sys_landlock_restrict_self()
48
+
call with the following fields:
49
+
50
+
- the ``domain`` ID
51
+
- the enforcement ``mode``
52
+
- the domain creator's ``pid``
53
+
- the domain creator's ``uid``
54
+
- the domain creator's executable path (``exe``)
55
+
- the domain creator's command line (``comm``)
56
+
57
+
Example::
58
+
59
+
domain=195ba459b status=allocated mode=enforcing pid=300 uid=0 exe="/root/sandboxer" comm="sandboxer"
60
+
61
+
The ``deallocated`` status is an event on its own and it identifies a
62
+
Landlock domain release. After such event, it is guarantee that the
63
+
related domain ID will never be reused during the lifetime of the system.
64
+
The ``domain`` field indicates the ID of the domain which is released, and
65
+
the ``denials`` field indicates the total number of denied access request,
66
+
which might not have been logged according to the audit rules and
67
+
sys_landlock_restrict_self()'s flags.
68
+
69
+
Example::
70
+
71
+
domain=195ba459b status=deallocated denials=3
72
+
73
+
74
+
Event samples
75
+
--------------
76
+
77
+
Here are two examples of log events (see serial numbers).
78
+
79
+
In this example a sandboxed program (``kill``) tries to send a signal to the
80
+
init process, which is denied because of the signal scoping restriction
81
+
(``LL_SCOPED=s``)::
82
+
83
+
$ LL_FS_RO=/ LL_FS_RW=/ LL_SCOPED=s LL_FORCE_LOG=1 ./sandboxer kill 1
84
+
85
+
This command generates two events, each identified with a unique serial
86
+
number following a timestamp (``msg=audit(1729738800.268:30)``). The first
87
+
event (serial ``30``) contains 4 records. The first record
88
+
(``type=LANDLOCK_ACCESS``) shows an access denied by the domain `1a6fdc66f`.
89
+
The cause of this denial is signal scopping restriction
90
+
(``blockers=scope.signal``). The process that would have receive this signal
91
+
is the init process (``opid=1 ocomm="systemd"``).
92
+
93
+
The second record (``type=LANDLOCK_DOMAIN``) describes (``status=allocated``)
94
+
domain `1a6fdc66f`. This domain was created by process ``286`` executing the
95
+
``/root/sandboxer`` program launched by the root user.
96
+
97
+
The third record (``type=SYSCALL``) describes the syscall, its provided
98
+
arguments, its result (``success=no exit=-1``), and the process that called it.
99
+
100
+
The fourth record (``type=PROCTITLE``) shows the command's name as an
101
+
hexadecimal value. This can be translated with ``python -c
102
+
'print(bytes.fromhex("6B696C6C0031"))'``.
103
+
104
+
Finally, the last record (``type=LANDLOCK_DOMAIN``) is also the only one from
105
+
the second event (serial ``31``). It is not tied to a direct user space action
106
+
but an asynchronous one to free resources tied to a Landlock domain
107
+
(``status=deallocated``). This can be useful to know that the following logs
108
+
will not concern the domain ``1a6fdc66f`` anymore. This record also summarize
109
+
the number of requests this domain denied (``denials=1``), whether they were
110
+
logged or not.
111
+
112
+
.. code-block::
113
+
114
+
type=LANDLOCK_ACCESS msg=audit(1729738800.268:30): domain=1a6fdc66f blockers=scope.signal opid=1 ocomm="systemd"
115
+
type=LANDLOCK_DOMAIN msg=audit(1729738800.268:30): domain=1a6fdc66f status=allocated mode=enforcing pid=286 uid=0 exe="/root/sandboxer" comm="sandboxer"
116
+
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" [...]
117
+
type=PROCTITLE msg=audit(1729738800.268:30): proctitle=6B696C6C0031
118
+
type=LANDLOCK_DOMAIN msg=audit(1729738800.324:31): domain=1a6fdc66f status=deallocated denials=1
119
+
120
+
Here is another example showcasing filesystem access control::
121
+
122
+
$ LL_FS_RO=/ LL_FS_RW=/tmp LL_FORCE_LOG=1 ./sandboxer sh -c "echo > /etc/passwd"
123
+
124
+
The related audit logs contains 8 records from 3 different events (serials 33,
125
+
34 and 35) created by the same domain `1a6fdc679`::
126
+
127
+
type=LANDLOCK_ACCESS msg=audit(1729738800.221:33): domain=1a6fdc679 blockers=fs.write_file path="/dev/tty" dev="devtmpfs" ino=9
128
+
type=LANDLOCK_DOMAIN msg=audit(1729738800.221:33): domain=1a6fdc679 status=allocated mode=enforcing pid=289 uid=0 exe="/root/sandboxer" comm="sandboxer"
129
+
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" [...]
130
+
type=PROCTITLE msg=audit(1729738800.221:33): proctitle=7368002D63006563686F203E202F6574632F706173737764
131
+
type=LANDLOCK_ACCESS msg=audit(1729738800.221:34): domain=1a6fdc679 blockers=fs.write_file path="/etc/passwd" dev="vda2" ino=143821
132
+
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" [...]
133
+
type=PROCTITLE msg=audit(1729738800.221:34): proctitle=7368002D63006563686F203E202F6574632F706173737764
134
+
type=LANDLOCK_DOMAIN msg=audit(1729738800.261:35): domain=1a6fdc679 status=deallocated denials=2
135
+
136
+
137
+
Event filtering
138
+
---------------
139
+
140
+
If you get spammed with audit logs related to Landlock, this is either an
141
+
attack attempt or a bug in the security policy. We can put in place some
142
+
filters to limit noise with two complementary ways:
143
+
144
+
- with sys_landlock_restrict_self()'s flags if we can fix the sandboxed
145
+
programs,
146
+
- or with audit rules (see :manpage:`auditctl(8)`).
147
+
148
+
Additional documentation
149
+
========================
150
+
151
+
* `Linux Audit Documentation`_
152
+
* Documentation/userspace-api/landlock.rst
153
+
* Documentation/security/landlock.rst
154
+
* https://landlock.io
155
+
156
+
.. Links
157
+
.. _Linux Audit Documentation:
158
+
https://github.com/linux-audit/audit-documentation/wiki
+12
-1
Documentation/security/landlock.rst
+12
-1
Documentation/security/landlock.rst
···
7
7
==================================
8
8
9
9
:Author: Mickaël Salaün
10
-
:Date: December 2022
10
+
:Date: March 2025
11
11
12
12
Landlock's goal is to create scoped access-control (i.e. sandboxing). To
13
13
harden a whole system, this feature should be available to any process,
···
45
45
sandboxed process shall retain their scoped accesses (at the time of resource
46
46
acquisition) whatever process uses them.
47
47
Cf. `File descriptor access rights`_.
48
+
* Access denials shall be logged according to system and Landlock domain
49
+
configurations. Log entries must contain information about the cause of the
50
+
denial and the owner of the related security policy. Such log generation
51
+
should have a negligible performance and memory impact on allowed requests.
48
52
49
53
Design choices
50
54
==============
···
127
123
128
124
.. kernel-doc:: security/landlock/ruleset.h
129
125
:identifiers:
126
+
127
+
Additional documentation
128
+
========================
129
+
130
+
* Documentation/userspace-api/landlock.rst
131
+
* Documentation/admin-guide/LSM/landlock.rst
132
+
* https://landlock.io
130
133
131
134
.. Links
132
135
.. _tools/testing/selftests/landlock/:
+17
Documentation/userspace-api/landlock.rst
+17
Documentation/userspace-api/landlock.rst
···
594
594
:manpage:`signal(7)` sending by setting ``LANDLOCK_SCOPE_SIGNAL`` to the
595
595
``scoped`` ruleset attribute.
596
596
597
+
Logging (ABI < 7)
598
+
-----------------
599
+
600
+
Starting with the Landlock ABI version 7, it is possible to control logging of
601
+
Landlock audit events with the ``LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF``,
602
+
``LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON``, and
603
+
``LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF`` flags passed to
604
+
sys_landlock_restrict_self(). See Documentation/admin-guide/LSM/landlock.rst
605
+
for more details on audit.
606
+
597
607
.. _kernel_support:
598
608
599
609
Kernel support
···
692
682
issues, especially when untrusted processes can manipulate them (cf.
693
683
`Controlling access to user namespaces <https://lwn.net/Articles/673597/>`_).
694
684
685
+
How to disable Landlock audit records?
686
+
--------------------------------------
687
+
688
+
You might want to put in place filters as explained here:
689
+
Documentation/admin-guide/LSM/landlock.rst
690
+
695
691
Additional documentation
696
692
========================
697
693
694
+
* Documentation/admin-guide/LSM/landlock.rst
698
695
* Documentation/security/landlock.rst
699
696
* https://landlock.io
700
697
+1
MAINTAINERS
+1
MAINTAINERS
···
13075
13075
S: Supported
13076
13076
W: https://landlock.io
13077
13077
T: git https://git.kernel.org/pub/scm/linux/kernel/git/mic/linux.git
13078
+
F: Documentation/admin-guide/LSM/landlock.rst
13078
13079
F: Documentation/security/landlock.rst
13079
13080
F: Documentation/userspace-api/landlock.rst
13080
13081
F: fs/ioctl.c