Skip to content

Commit 8e2dd47

Browse files
l0kodl0kod
committed
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>
1 parent a5c369e commit 8e2dd47

File tree

5 files changed

+189
-1
lines changed

5 files changed

+189
-1
lines changed

‎Documentation/admin-guide/LSM/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,3 +48,4 @@ subdirectories.
4848
Yama
4949
SafeSetID
5050
ipe
51+
landlock

‎Documentation/admin-guide/LSM/landlock.rst

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
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

‎Documentation/security/landlock.rst

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Landlock LSM: kernel documentation
77
==================================
88

99
:Author: Mickaël Salaün
10-
:Date: December 2022
10+
:Date: March 2025
1111

1212
Landlock's goal is to create scoped access-control (i.e. sandboxing). To
1313
harden a whole system, this feature should be available to any process,
@@ -45,6 +45,10 @@ Guiding principles for safe access controls
4545
sandboxed process shall retain their scoped accesses (at the time of resource
4646
acquisition) whatever process uses them.
4747
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.
4852

4953
Design choices
5054
==============
@@ -124,6 +128,13 @@ makes the reasoning much easier and helps avoid pitfalls.
124128
.. kernel-doc:: security/landlock/ruleset.h
125129
:identifiers:
126130

131+
Additional documentation
132+
========================
133+
134+
* Documentation/userspace-api/landlock.rst
135+
* Documentation/admin-guide/LSM/landlock.rst
136+
* https://landlock.io
137+
127138
.. Links
128139
.. _tools/testing/selftests/landlock/:
129140
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/landlock/

‎Documentation/userspace-api/landlock.rst

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -594,6 +594,16 @@ Starting with the Landlock ABI version 6, it is possible to restrict
594594
:manpage:`signal(7)` sending by setting ``LANDLOCK_SCOPE_SIGNAL`` to the
595595
``scoped`` ruleset attribute.
596596

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+
597607
.. _kernel_support:
598608

599609
Kernel support
@@ -682,9 +692,16 @@ fine-grained restrictions). Moreover, their complexity can lead to security
682692
issues, especially when untrusted processes can manipulate them (cf.
683693
`Controlling access to user namespaces <https://lwn.net/Articles/673597/>`_).
684694

695+
How to disable Landlock audit records?
696+
--------------------------------------
697+
698+
You might want to put in place filters as explained here:
699+
Documentation/admin-guide/LSM/landlock.rst
700+
685701
Additional documentation
686702
========================
687703

704+
* Documentation/admin-guide/LSM/landlock.rst
688705
* Documentation/security/landlock.rst
689706
* https://landlock.io
690707

‎MAINTAINERS

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13075,6 +13075,7 @@ L: linux-security-module@vger.kernel.org
1307513075
S: Supported
1307613076
W: https://landlock.io
1307713077
T: git https://git.kernel.org/pub/scm/linux/kernel/git/mic/linux.git
13078+
F: Documentation/admin-guide/LSM/landlock.rst
1307813079
F: Documentation/security/landlock.rst
1307913080
F: Documentation/userspace-api/landlock.rst
1308013081
F: fs/ioctl.c

0 commit comments

Comments
 (0)