landlock.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2.. Copyright © 2025 Microsoft Corporation
  3
  4================================
  5Landlock: system-wide management
  6================================
  7
  8:Author: Mickaël Salaün
  9:Date: March 2025
 10
 11Landlock can leverage the audit framework to log events.
 12
 13User space documentation can be found here:
 14Documentation/userspace-api/landlock.rst.
 15
 16Audit
 17=====
 18
 19Denied access requests are logged by default for a sandboxed program if `audit`
 20is enabled.  This default behavior can be changed with the
 21sys_landlock_restrict_self() flags (cf.
 22Documentation/userspace-api/landlock.rst).  Landlock logs can also be masked
 23thanks to audit rules.  Landlock can generate 2 audit record types.
 24
 25Record types
 26------------
 27
 28AUDIT_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
 41AUDIT_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
 74Event samples
 75--------------
 76
 77Here are two examples of log events (see serial numbers).
 78
 79In this example a sandboxed program (``kill``) tries to send a signal to the
 80init 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
 85This command generates two events, each identified with a unique serial
 86number following a timestamp (``msg=audit(1729738800.268:30)``).  The first
 87event (serial ``30``) contains 4 records.  The first record
 88(``type=LANDLOCK_ACCESS``) shows an access denied by the domain `1a6fdc66f`.
 89The cause of this denial is signal scopping restriction
 90(``blockers=scope.signal``).  The process that would have receive this signal
 91is the init process (``opid=1 ocomm="systemd"``).
 92
 93The second record (``type=LANDLOCK_DOMAIN``) describes (``status=allocated``)
 94domain `1a6fdc66f`.  This domain was created by process ``286`` executing the
 95``/root/sandboxer`` program launched by the root user.
 96
 97The third record (``type=SYSCALL``) describes the syscall, its provided
 98arguments, its result (``success=no exit=-1``), and the process that called it.
 99
100The fourth record (``type=PROCTITLE``) shows the command's name as an
101hexadecimal value.  This can be translated with ``python -c
102'print(bytes.fromhex("6B696C6C0031"))'``.
103
104Finally, the last record (``type=LANDLOCK_DOMAIN``) is also the only one from
105the second event (serial ``31``).  It is not tied to a direct user space action
106but an asynchronous one to free resources tied to a Landlock domain
107(``status=deallocated``).  This can be useful to know that the following logs
108will not concern the domain ``1a6fdc66f`` anymore.  This record also summarize
109the number of requests this domain denied (``denials=1``), whether they were
110logged 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
120Here 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
124The related audit logs contains 8 records from 3 different events (serials 33,
12534 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
137Event filtering
138---------------
139
140If you get spammed with audit logs related to Landlock, this is either an
141attack attempt or a bug in the security policy.  We can put in place some
142filters 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
148Additional 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