Skip to contentSkip to conversation

landlock: Document audit logging

PATCH Applied Günther Noack 3 participants 8 messages Mar 29 – Apr 8 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

Günther Noack

author
#0 lore raw

cover landlock: Document audit logging

Hello!

This brings the Landlock man pages up to speed with Landlock's audit logging support (introduced in March last year, about a year ago).

–Günther

Günther Noack (3):
man/man2/landlock*.2: Reorder errors alphabetically man/man2/landlock_create_ruleset.2: Document scoped field in struct
landlock_ruleset_attr (ABI v6)
man/man2/landlock_restrict_self.2, man/man7/landlock.7: Document audit
logging (ABI v7)

 man/man2/landlock_add_rule.2       | 38 ++++++-------
 man/man2/landlock_create_ruleset.2 | 26 +++++----
 man/man2/landlock_restrict_self.2  | 87 +++++++++++++++++++++++++-----
 man/man7/landlock.7                |  6 ++-
 4 files changed, 116 insertions(+), 41 deletions(-)
Signature · 1 line
2.53.0
author
#1 lore raw

PATCH 1/3 man/man2/landlock*.2: Reorder errors alphabetically

Reorder lists of error codes alphabetically, in line with man-pages(7).

Cc Mickaël Salaün <[email protected]>
Signed-off-by Günther Noack <[email protected]>
---
 man/man2/landlock_add_rule.2       | 38 +++++++++++++++---------------
 man/man2/landlock_create_ruleset.2 | 18 +++++++-------
 man/man2/landlock_restrict_self.2  | 20 ++++++++--------
 3 files changed, 38 insertions(+), 38 deletions(-)
man/man2/landlock_add_rule.2 +19 -19
index 108364528830..48d7d3b25c9e 100644
@@ -139,8 +139,23 @@ is
 .BR LANDLOCK_RULE_NET_PORT ,
 but TCP is not supported by the running kernel.
 .TP
-.B EOPNOTSUPP
-Landlock is supported by the kernel but disabled at boot time.
+.B EBADF
+.I ruleset_fd
+is not a file descriptor for the current thread,
+or a member of
+.I rule_attr
+is not a file descriptor as expected.
+.TP
+.B EBADFD
+.I ruleset_fd
+is not a ruleset file descriptor,
+or a member of
+.I rule_attr
+is not the expected file descriptor type.
+.TP
+.B EFAULT
+.I rule_attr
+was not a valid address.
 .TP
 .B EINVAL
 .I flags

@@ -171,27 +186,12 @@ Empty accesses (i.e.,
 .I rule_attr\->allowed_access
 is 0).
 .TP
-.B EBADF
-.I ruleset_fd
-is not a file descriptor for the current thread,
-or a member of
-.I rule_attr
-is not a file descriptor as expected.
-.TP
-.B EBADFD
-.I ruleset_fd
-is not a ruleset file descriptor,
-or a member of
-.I rule_attr
-is not the expected file descriptor type.
+.B EOPNOTSUPP
+Landlock is supported by the kernel but disabled at boot time.
 .TP
 .B EPERM
 .I ruleset_fd
 has no write access to the underlying ruleset.
-.TP
-.B EFAULT
-.I rule_attr
-was not a valid address.
 .SH STANDARDS
 Linux.
 .SH HISTORY
man/man2/landlock_create_ruleset.2 +9 -9
index ae5c89f5354f..8cffd8c770fa 100644
@@ -134,15 +134,6 @@ is set to indicate the error.
 .BR landlock_create_ruleset ()
 can fail for the following reasons:
 .TP
-.B EOPNOTSUPP
-Landlock is supported by the kernel but disabled at boot time.
-.TP
-.B EINVAL
-Unknown
-.IR flags ,
-or unknown access, or too small
-.IR size .
-.TP
 .B E2BIG
 .I size
 is too big.

@@ -151,10 +142,19 @@ is too big.
 .I attr
 was not a valid address.
 .TP
+.B EINVAL
+Unknown
+.IR flags ,
+or unknown access, or too small
+.IR size .
+.TP
 .B ENOMSG
 Empty accesses (i.e.,
 .I attr
 did not specify any access rights to restrict).
+.TP
+.B EOPNOTSUPP
+Landlock is supported by the kernel but disabled at boot time.
 .SH STANDARDS
 Linux.
 .SH HISTORY
man/man2/landlock_restrict_self.2 +10 -10
index 43fc8c6efcc7..530ef9a4cd25 100644
@@ -82,12 +82,9 @@ is set to indicate the error.
 .BR landlock_restrict_self ()
 can fail for the following reasons:
 .TP
-.B EOPNOTSUPP
-Landlock is supported by the kernel but disabled at boot time.
-.TP
-.B EINVAL
-.I flags
-is not 0.
+.B E2BIG
+The maximum number of composed rulesets is reached for the calling thread.
+This limit is currently 64.
 .TP
 .B EBADF
 .I ruleset_fd

@@ -97,6 +94,13 @@ is not a file descriptor for the current thread.
 .I ruleset_fd
 is not a ruleset file descriptor.
 .TP
+.B EINVAL
+Invalid value in
+.IR flags .
+.TP
+.B EOPNOTSUPP
+Landlock is supported by the kernel but disabled at boot time.
+.TP
 .B EPERM
 .I ruleset_fd
 has no read access to the underlying ruleset,

@@ -105,10 +109,6 @@ or the calling thread is not running with
 or it doesn't have the
 .B CAP_SYS_ADMIN
 in its user namespace.
-.TP
-.B E2BIG
-The maximum number of composed rulesets is reached for the calling thread.
-This limit is currently 64.
 .SH STANDARDS
 Linux.
 .SH HISTORY
Signature · 1 line
2.53.0
author
#2 lore raw

PATCH 2/3 man/man2/landlock_create_ruleset.2: Document scoped field in struct landlock_ruleset_attr (ABI v6)

In reply to Günther Noack

Add the missing scoped field to the struct landlock_ruleset_attr definition, and document it as a bitmask of scope flags.

Available since Linux 6.12 (Landlock ABI version 6).

Cc Tahera Fahimi <[email protected]>
Cc Mickaël Salaün <[email protected]>
Fixes 5a89b5bd (2025-03-06; "man/man7/landlock.7: Document IPC scoping (Landlock ABI v6)")
Signed-off-by Günther Noack <[email protected]>
---
 man/man2/landlock_create_ruleset.2 | 8 ++++++++
 1 file changed, 8 insertions(+)
man/man2/landlock_create_ruleset.2 +8 -0
index 8cffd8c770fa..5425ed59878b 100644
@@ -44,6 +44,7 @@ It points to the following structure:
 struct landlock_ruleset_attr {
     __u64 handled_access_fs;
     __u64 handled_access_net;
+    __u64 scoped;
 };
 .EE
 .in

@@ -62,6 +63,13 @@ is a bitmask of handled network actions
 in
 .BR landlock (7)).
 .IP
+.I scoped
+is a bitmask of scope flags
+(see
+.B Scope flags
+in
+.BR landlock (7)).
+.IP
 This structure defines a set of
 .IR "handled access rights" ,
 a set of actions on different object types,
Signature · 1 line
2.53.0
author
#3 lore raw

PATCH 3/3 man/man2/landlock_restrict_self.2, man/man7/landlock.7: Document audit logging (ABI v7)

In reply to Günther Noack

* Document the flags LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF, LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF and LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON.
* List these flags in the compatibility table in landlock.7

The documentation text is copied from the kernel documentation, originally authored by Mickaël Salaün in [1] and [2].

Link[1]: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/include/uapi/linux/landlock.h?id=ead9079f75696a028aea8860787770c80eddb8f9>
Link[2]: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/include/uapi/linux/landlock.h?id=12bfcda73ac2cf3083c9d6d05724af92da3a4b4b>

Cc Mickaël Salaün <[email protected]>
Signed-off-by Günther Noack <[email protected]>
---
 man/man2/landlock_restrict_self.2 | 67 ++++++++++++++++++++++++++++++-
 man/man7/landlock.7               |  6 ++-
 2 files changed, 70 insertions(+), 3 deletions(-)
man/man2/landlock_restrict_self.2 +65 -2
index 530ef9a4cd25..9e80a40ee4a4 100644
@@ -68,8 +68,71 @@ is a Landlock ruleset file descriptor obtained with
 and fully populated with a set of calls to
 .BR landlock_add_rule (2).
 .P
-.I flags
-must be 0.
+By default,
+denied accesses originating from programs that sandbox themselves
+are logged via the audit subsystem.
+Such events typically indicate unexpected behavior,
+such as bugs or exploitation attempts.
+However, to avoid excessive logging,
+access requests denied by a domain not created by the originating program
+are not logged by default.
+The rationale is that programs should know their own behavior,
+but not necessarily the behavior of other programs.
+This default configuration is suitable for most programs
+that sandbox themselves.
+For specific use cases,
+the following flags allow programs to modify this default logging behavior.
+.P
+The
+.B LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+and
+.B LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+flags apply to the newly created Landlock domain.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+Disables logging of denied accesses
+originating from the thread creating the Landlock domain,
+as well as its children,
+as long as they continue running the same executable code
+(i.e., without an intervening
+.BR execve (2)
+call).
+This is intended for programs that execute unknown code
+without invoking
+.BR execve (2),
+such as script interpreters.
+Programs that only sandbox themselves should not set this flag,
+so users can be notified of unauthorized access attempts
+via system logs.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+Enables logging of denied accesses after an
+.BR execve (2)
+call,
+providing visibility into unauthorized access attempts
+by newly executed programs within the created Landlock domain.
+This flag is recommended only when all potential executables
+in the domain are expected to comply with the access restrictions,
+as excessive audit log entries could make it more difficult
+to identify critical events.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
+Disables logging of denied accesses
+originating from nested Landlock domains created by the caller
+or its descendants.
+This flag should be set according to runtime configuration,
+not hardcoded, to avoid suppressing important security events.
+It is useful for container runtimes or sandboxing tools
+that may launch programs which themselves create Landlock domains
+and could otherwise generate excessive logs.
+Unlike
+.BR LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF ,
+this flag only affects future nested domains,
+not the one being created.
+It can also be used with a
+.I ruleset_fd
+value of \-1 to mute subdomain logs
+without creating a domain.
 .SH RETURN VALUE
 On success,
 .BR landlock_restrict_self ()
man/man7/landlock.7 +5 -1
index 05664b3d7cba..bcf06ea30ad4 100644
@@ -445,7 +445,7 @@ users should query the Landlock ABI version:
 box;
 ntb| ntb| lbx
 nt| nt| lbx.
-ABI	Kernel	Newly introduced access rights
+ABI	Kernel	Newly introduced constants
 _	_	_
 1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
 \^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE

@@ -472,6 +472,10 @@ _	_	_
 _	_	_
 6	6.12	LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
 \^	\^	LANDLOCK_SCOPE_SIGNAL
+_	_	_
+7	6.15	LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+\^	\^	LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+\^	\^	LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
Signature · 1 line
2.53.0
maintainer
#4 lore raw

Re: [PATCH 3/3] man/man2/landlock_restrict_self.2, man/man7/landlock.7: Document audit logging (ABI v7)

Hi Günther,

I've applied patches 1/3 and 2/3. However, I've tried reading this a few times and still don't understand it well.

Quoted 27 lines · Günther Noack

* Document the flags LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF, LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF and LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON.
* List these flags in the compatibility table in landlock.7

The documentation text is copied from the kernel documentation, originally authored by Mickaël Salaün in [1] and [2].

Link[1]: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/include/uapi/linux/landlock.h?id=ead9079f75696a028aea8860787770c80eddb8f9>
Link[2]: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/include/uapi/linux/landlock.h?id=12bfcda73ac2cf3083c9d6d05724af92da3a4b4b>

Cc Mickaël Salaün <[email protected]>
Signed-off-by Günther Noack <[email protected]>
---
 man/man2/landlock_restrict_self.2 | 67 ++++++++++++++++++++++++++++++-
 man/man7/landlock.7               |  6 ++-
 2 files changed, 70 insertions(+), 3 deletions(-)
man/man2/landlock_restrict_self.2 +0 -2
index 530ef9a4cd25..9e80a40ee4a4 100644
@@ -68,8 +68,71 @@ is a Landlock ruleset file descriptor obtained with
 and fully populated with a set of calls to
 .BR landlock_add_rule (2).
 .P
-.I flags
-must be 0.

man/man2/landlock_restrict_self.2 is a Landlock ruleset file descriptor obtained with · line 80

Quoted 10 lines
man/man2/landlock_restrict_self.2 +10 -0
+By default,
+denied accesses originating from programs that sandbox themselves
+are logged via the audit subsystem.
+Such events typically indicate unexpected behavior,
+such as bugs or exploitation attempts.
+However, to avoid excessive logging,
+access requests denied by a domain not created by the originating program
+are not logged by default.
+The rationale is that programs should know their own behavior,
+but not necessarily the behavior of other programs.

If I understand this correctly, the default is to log after fork(2) or execve(2), but not before. Is that correct?

Quoted 9 lines
man/man2/landlock_restrict_self.2 +9 -0
+This default configuration is suitable for most programs
+that sandbox themselves.
+For specific use cases,
+the following flags allow programs to modify this default logging behavior.
+.P
+The
+.B LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+and
+.B LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON

man/man2/landlock_restrict_self.2 is a Landlock ruleset file descriptor obtained with · line 99

Quoted 10 lines
man/man2/landlock_restrict_self.2 +10 -0
+flags apply to the newly created Landlock domain.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+Disables logging of denied accesses
+originating from the thread creating the Landlock domain,
+as well as its children,
+as long as they continue running the same executable code
+(i.e., without an intervening
+.BR execve (2)
+call).

And if I understood this well, this changes the behavior so that fork(2) is ignored, so that logging will only be enabled at execve(2) but not at fork(2).

man/man2/landlock_restrict_self.2 is a Landlock ruleset file descriptor obtained with · line 111

Quoted 12 lines
man/man2/landlock_restrict_self.2 +12 -0
+This is intended for programs that execute unknown code
+without invoking
+.BR execve (2),
+such as script interpreters.
+Programs that only sandbox themselves should not set this flag,
+so users can be notified of unauthorized access attempts
+via system logs.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+Enables logging of denied accesses after an
+.BR execve (2)
+call,

But this is the part that makes me think my previous understanding was wrong. I had understood that execve(3) already triggered logging. So what does this enable that wasn't enabled already?

Have a lovely night!
Alex

Quoted 54 lines
man/man2/landlock_restrict_self.2 +24 -0
+providing visibility into unauthorized access attempts
+by newly executed programs within the created Landlock domain.
+This flag is recommended only when all potential executables
+in the domain are expected to comply with the access restrictions,
+as excessive audit log entries could make it more difficult
+to identify critical events.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
+Disables logging of denied accesses
+originating from nested Landlock domains created by the caller
+or its descendants.
+This flag should be set according to runtime configuration,
+not hardcoded, to avoid suppressing important security events.
+It is useful for container runtimes or sandboxing tools
+that may launch programs which themselves create Landlock domains
+and could otherwise generate excessive logs.
+Unlike
+.BR LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF ,
+this flag only affects future nested domains,
+not the one being created.
+It can also be used with a
+.I ruleset_fd
+value of \-1 to mute subdomain logs
+without creating a domain.
 .SH RETURN VALUE
 On success,
 .BR landlock_restrict_self ()
man/man7/landlock.7 +5 -1
index 05664b3d7cba..bcf06ea30ad4 100644
@@ -445,7 +445,7 @@ users should query the Landlock ABI version:
 box;
 ntb| ntb| lbx
 nt| nt| lbx.
-ABI	Kernel	Newly introduced access rights
+ABI	Kernel	Newly introduced constants
 _	_	_
 1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
 \^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE

@@ -472,6 +472,10 @@ _	_	_
 _	_	_
 6	6.12	LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
 \^	\^	LANDLOCK_SCOPE_SIGNAL
+_	_	_
+7	6.15	LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+\^	\^	LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+\^	\^	LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
Signature · 1 line
2.53.0
Signature · 2 lines
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).
#5 lore raw

Re: [PATCH 3/3] man/man2/landlock_restrict_self.2, man/man7/landlock.7: Document audit logging (ABI v7)

Hi!

Quoted 38 lines · Alejandro Colomar

Hi Günther,

I've applied patches 1/3 and 2/3. However, I've tried reading this a few times and still don't understand it well.

Quoted 32 lines · Günther Noack

* Document the flags LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF, LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF and LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON.
* List these flags in the compatibility table in landlock.7

The documentation text is copied from the kernel documentation, originally authored by Mickaël Salaün in [1] and [2].

Link[1]: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/include/uapi/linux/landlock.h?id=ead9079f75696a028aea8860787770c80eddb8f9>
Link[2]: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/include/uapi/linux/landlock.h?id=12bfcda73ac2cf3083c9d6d05724af92da3a4b4b>

Cc Mickaël Salaün <[email protected]>
Signed-off-by Günther Noack <[email protected]>
---
 man/man2/landlock_restrict_self.2 | 67 ++++++++++++++++++++++++++++++-
 man/man7/landlock.7               |  6 ++-
 2 files changed, 70 insertions(+), 3 deletions(-)
man/man2/landlock_restrict_self.2 +5 -2
index 530ef9a4cd25..9e80a40ee4a4 100644
@@ -68,8 +68,71 @@ is a Landlock ruleset file descriptor obtained with
 and fully populated with a set of calls to
 .BR landlock_add_rule (2).
 .P
-.I flags
-must be 0.
+By default,
+denied accesses originating from programs that sandbox themselves
+are logged via the audit subsystem.
+Such events typically indicate unexpected behavior,
+such as bugs or exploitation attempts.
Quoted 8 lines

man/man2/landlock_restrict_self.2 is a Landlock ruleset file descriptor obtained with · line 80

Quoted 5 lines
man/man2/landlock_restrict_self.2 +5 -0
+However, to avoid excessive logging,
+access requests denied by a domain not created by the originating program
+are not logged by default.
+The rationale is that programs should know their own behavior,
+but not necessarily the behavior of other programs.

If I understand this correctly, the default is to log after fork(2) or execve(2), but not before. Is that correct?

There is a distinctions before and after the first execve: once a process sandboxes itself, by default, every denied operations are logged, until it calls execve(2). At this point, in most cases, it is not the same executable code, which means that this new program may not be aware of the restrictions and may try to repeatedly do some denied operations, which will not be logged by default

Quoted 16 lines
Quoted 16 lines
man/man2/landlock_restrict_self.2 +15 -0
+This default configuration is suitable for most programs
+that sandbox themselves.
+For specific use cases,
+the following flags allow programs to modify this default logging behavior.
+.P
+The
+.B LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+and
+.B LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+flags apply to the newly created Landlock domain.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+Disables logging of denied accesses
+originating from the thread creating the Landlock domain,
+as well as its children,
Quoted 8 lines

man/man2/landlock_restrict_self.2 is a Landlock ruleset file descriptor obtained with · line 99

Quoted 4 lines
man/man2/landlock_restrict_self.2 +4 -0
+as long as they continue running the same executable code
+(i.e., without an intervening
+.BR execve (2)
+call).

And if I understood this well, this changes the behavior so that fork(2) is ignored, so that logging will only be enabled at execve(2) but not at fork(2).

fork(2) and clone(2) are ignored, only execve(2) flips a bit and may change the default behavior.

Quoted 17 lines

man/man2/landlock_restrict_self.2 is a Landlock ruleset file descriptor obtained with · line 111

Quoted 13 lines
man/man2/landlock_restrict_self.2 +12 -0
+This is intended for programs that execute unknown code
+without invoking
+.BR execve (2),
+such as script interpreters.
+Programs that only sandbox themselves should not set this flag,
+so users can be notified of unauthorized access attempts
+via system logs.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+Enables logging of denied accesses after an
+.BR execve (2)
+call,

But this is the part that makes me think my previous understanding was wrong. I had understood that execve(3) already triggered logging. So what does this enable that wasn't enabled already?

LOG_NEW_EXEC_ON means that logging will not be disabled after execve(2).

Quoted 63 lines

Have a lovely night!
Alex

Quoted 54 lines
man/man2/landlock_restrict_self.2 +24 -0
+providing visibility into unauthorized access attempts
+by newly executed programs within the created Landlock domain.
+This flag is recommended only when all potential executables
+in the domain are expected to comply with the access restrictions,
+as excessive audit log entries could make it more difficult
+to identify critical events.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
+Disables logging of denied accesses
+originating from nested Landlock domains created by the caller
+or its descendants.
+This flag should be set according to runtime configuration,
+not hardcoded, to avoid suppressing important security events.
+It is useful for container runtimes or sandboxing tools
+that may launch programs which themselves create Landlock domains
+and could otherwise generate excessive logs.
+Unlike
+.BR LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF ,
+this flag only affects future nested domains,
+not the one being created.
+It can also be used with a
+.I ruleset_fd
+value of \-1 to mute subdomain logs
+without creating a domain.
 .SH RETURN VALUE
 On success,
 .BR landlock_restrict_self ()
man/man7/landlock.7 +5 -1
index 05664b3d7cba..bcf06ea30ad4 100644
@@ -445,7 +445,7 @@ users should query the Landlock ABI version:
 box;
 ntb| ntb| lbx
 nt| nt| lbx.
-ABI	Kernel	Newly introduced access rights
+ABI	Kernel	Newly introduced constants
 _	_	_
 1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
 \^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE

@@ -472,6 +472,10 @@ _	_	_
 _	_	_
 6	6.12	LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
 \^	\^	LANDLOCK_SCOPE_SIGNAL
+_	_	_
+7	6.15	LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+\^	\^	LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+\^	\^	LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
Signature · 1 line
2.53.0
Signature · 2 lines
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).
maintainer
#6 lore raw

Re: [PATCH 3/3] man/man2/landlock_restrict_self.2, man/man7/landlock.7: Document audit logging (ABI v7)

Hi Mickaël!

Quoted 20 lines · Mickaël Salaün
Quoted 11 lines
Quoted 11 lines
man/man2/landlock_restrict_self.2 +5 -2
@@ -68,8 +68,71 @@ is a Landlock ruleset file descriptor obtained with
 and fully populated with a set of calls to
 .BR landlock_add_rule (2).
 .P
-.I flags
-must be 0.
+By default,
+denied accesses originating from programs that sandbox themselves
+are logged via the audit subsystem.
+Such events typically indicate unexpected behavior,
+such as bugs or exploitation attempts.
Quoted 8 lines

man/man2/landlock_restrict_self.2 is a Landlock ruleset file descriptor obtained with · line 80

Quoted 5 lines
man/man2/landlock_restrict_self.2 +5 -0
+However, to avoid excessive logging,
+access requests denied by a domain not created by the originating program
+are not logged by default.
+The rationale is that programs should know their own behavior,
+but not necessarily the behavior of other programs.

If I understand this correctly, the default is to log after fork(2) or execve(2), but not before. Is that correct?

Quoted 6 lines

There is a distinctions before and after the first execve: once a process sandboxes itself, by default, every denied operations are logged, until it calls execve(2). At this point, in most cases, it is not the same executable code, which means that this new program may not be aware of the restrictions and may try to repeatedly do some denied operations, which will not be logged by default

Oh, true, I got it reversed! That's probably the source of my misunderstanding. :)

So, by default, before execve(2) we log, and after it we don't.

Quoted 24 lines
Quoted 15 lines
Quoted 15 lines
man/man2/landlock_restrict_self.2 +15 -0
+This default configuration is suitable for most programs
+that sandbox themselves.
+For specific use cases,
+the following flags allow programs to modify this default logging behavior.
+.P
+The
+.B LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+and
+.B LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+flags apply to the newly created Landlock domain.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+Disables logging of denied accesses
+originating from the thread creating the Landlock domain,
+as well as its children,
Quoted 8 lines

man/man2/landlock_restrict_self.2 is a Landlock ruleset file descriptor obtained with · line 99

Quoted 4 lines
man/man2/landlock_restrict_self.2 +4 -0
+as long as they continue running the same executable code
+(i.e., without an intervening
+.BR execve (2)
+call).

And if I understood this well, this changes the behavior so that fork(2) is ignored, so that logging will only be enabled at execve(2) but not at fork(2).

Quoted 2 lines

fork(2) and clone(2) are ignored, only execve(2) flips a bit and may change the default behavior.

So, this is the reverse of the above. Before execve(2), _EXEC_OFF doesn't log, and it logs after it.

Quoted 17 lines
Quoted 8 lines
Quoted 8 lines
man/man2/landlock_restrict_self.2 +8 -0
+This is intended for programs that execute unknown code
+without invoking
+.BR execve (2),
+such as script interpreters.
+Programs that only sandbox themselves should not set this flag,
+so users can be notified of unauthorized access attempts
+via system logs.
+.TP
Quoted 8 lines

man/man2/landlock_restrict_self.2 is a Landlock ruleset file descriptor obtained with · line 111

Quoted 4 lines
man/man2/landlock_restrict_self.2 +4 -0
+.B LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+Enables logging of denied accesses after an
+.BR execve (2)
+call,

But this is the part that makes me think my previous understanding was wrong. I had understood that execve(3) already triggered logging. So what does this enable that wasn't enabled already?

Quoted 1 line

LOG_NEW_EXEC_ON means that logging will not be disabled after execve(2).

Okay, and _EXEC_ON means log before and after. Sounds good now in my head.

Cheers,
Alex

Signature · 1 line
<https://www.alejandro-colomar.es>
maintainer Applied
#7 lore raw

Re: [PATCH 3/3] man/man2/landlock_restrict_self.2, man/man7/landlock.7: Document audit logging (ABI v7)

In reply to Günther Noack

Hi!

Quoted 5 lines · Günther Noack

* Document the flags LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF, LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF and LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON.
* List these flags in the compatibility table in landlock.7

Quoted 7 lines

The documentation text is copied from the kernel documentation, originally authored by Mickaël Salaün in [1] and [2].

Link[1]: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/include/uapi/linux/landlock.h?id=ead9079f75696a028aea8860787770c80eddb8f9>
Link[2]: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/include/uapi/linux/landlock.h?id=12bfcda73ac2cf3083c9d6d05724af92da3a4b4b>

Cc Mickaël Salaün <[email protected]>
Signed-off-by Günther Noack <[email protected]>

I've applied the patch. Thanks!

Have a lovely day!
Alex

Quoted 110 lines
---
 man/man2/landlock_restrict_self.2 | 67 ++++++++++++++++++++++++++++++-
 man/man7/landlock.7               |  6 ++-
 2 files changed, 70 insertions(+), 3 deletions(-)
man/man2/landlock_restrict_self.2 +65 -2
index 530ef9a4cd25..9e80a40ee4a4 100644
@@ -68,8 +68,71 @@ is a Landlock ruleset file descriptor obtained with
 and fully populated with a set of calls to
 .BR landlock_add_rule (2).
 .P
-.I flags
-must be 0.
+By default,
+denied accesses originating from programs that sandbox themselves
+are logged via the audit subsystem.
+Such events typically indicate unexpected behavior,
+such as bugs or exploitation attempts.
+However, to avoid excessive logging,
+access requests denied by a domain not created by the originating program
+are not logged by default.
+The rationale is that programs should know their own behavior,
+but not necessarily the behavior of other programs.
+This default configuration is suitable for most programs
+that sandbox themselves.
+For specific use cases,
+the following flags allow programs to modify this default logging behavior.
+.P
+The
+.B LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+and
+.B LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+flags apply to the newly created Landlock domain.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+Disables logging of denied accesses
+originating from the thread creating the Landlock domain,
+as well as its children,
+as long as they continue running the same executable code
+(i.e., without an intervening
+.BR execve (2)
+call).
+This is intended for programs that execute unknown code
+without invoking
+.BR execve (2),
+such as script interpreters.
+Programs that only sandbox themselves should not set this flag,
+so users can be notified of unauthorized access attempts
+via system logs.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+Enables logging of denied accesses after an
+.BR execve (2)
+call,
+providing visibility into unauthorized access attempts
+by newly executed programs within the created Landlock domain.
+This flag is recommended only when all potential executables
+in the domain are expected to comply with the access restrictions,
+as excessive audit log entries could make it more difficult
+to identify critical events.
+.TP
+.B LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
+Disables logging of denied accesses
+originating from nested Landlock domains created by the caller
+or its descendants.
+This flag should be set according to runtime configuration,
+not hardcoded, to avoid suppressing important security events.
+It is useful for container runtimes or sandboxing tools
+that may launch programs which themselves create Landlock domains
+and could otherwise generate excessive logs.
+Unlike
+.BR LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF ,
+this flag only affects future nested domains,
+not the one being created.
+It can also be used with a
+.I ruleset_fd
+value of \-1 to mute subdomain logs
+without creating a domain.
 .SH RETURN VALUE
 On success,
 .BR landlock_restrict_self ()
man/man7/landlock.7 +5 -1
index 05664b3d7cba..bcf06ea30ad4 100644
@@ -445,7 +445,7 @@ users should query the Landlock ABI version:
 box;
 ntb| ntb| lbx
 nt| nt| lbx.
-ABI	Kernel	Newly introduced access rights
+ABI	Kernel	Newly introduced constants
 _	_	_
 1	5.13	LANDLOCK_ACCESS_FS_EXECUTE
 \^	\^	LANDLOCK_ACCESS_FS_WRITE_FILE

@@ -472,6 +472,10 @@ _	_	_
 _	_	_
 6	6.12	LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
 \^	\^	LANDLOCK_SCOPE_SIGNAL
+_	_	_
+7	6.15	LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
+\^	\^	LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
+\^	\^	LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
Signature · 1 line
2.53.0
Signature · 1 line
<https://www.alejandro-colomar.es>