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

["Günther Noack" <gnoack3000@gmail.com>]

* 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 <mic@digikod.net>
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
 man/man2/landlock_restrict_self.2 | 67 ++++++++++++++++++++++++++++++-
 man/man7/landlock.7               |  6 ++-
 2 files changed, 70 insertions(+), 3 deletions(-)

diff --git a/man/man2/landlock_restrict_self.2 b/man/man2/landlock_restrict_self.2
index 530ef9a4cd25..9e80a40ee4a4 100644
--- a/man/man2/landlock_restrict_self.2
+++ b/man/man2/landlock_restrict_self.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.
+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 ()
diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index 05664b3d7cba..bcf06ea30ad4 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -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
-- 
2.53.0