Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
landlock: Update log documentation
Fix and improve documentation related to landlock_restrict_self(2)'s
flags. Update the LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
documentation according to the current semantic.
Cc: Günther Noack <gnoack@google.com>
Cc: Paul Moore <paul@paul-moore.com>
Link: https://lore.kernel.org/r/20250416154716.1799902-3-mic@digikod.net
Signed-off-by: Mickaël Salaün <mic@digikod.net>
+38
-26
+38
-26
include/uapi/linux/landlock.h
+38
-26
include/uapi/linux/landlock.h
···
74
74
*
75
75
* **Flags**
76
76
*
77
+
* By default, denied accesses originating from programs that sandbox themselves
78
+
* are logged via the audit subsystem. Such events typically indicate unexpected
79
+
* behavior, such as bugs or exploitation attempts. However, to avoid excessive
80
+
* logging, access requests denied by a domain not created by the originating
81
+
* program are not logged by default. The rationale is that programs should know
82
+
* their own behavior, but not necessarily the behavior of other programs. This
83
+
* default configuration is suitable for most programs that sandbox themselves.
84
+
* For specific use cases, the following flags allow programs to modify this
85
+
* default logging behavior.
86
+
*
87
+
* The %LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF and
88
+
* %LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON flags apply to the newly created
89
+
* Landlock domain.
90
+
*
77
91
* %LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF
78
-
* Do not create any log related to the enforced restrictions. This should
79
-
* only be set by tools launching unknown or untrusted programs (e.g. a
80
-
* sandbox tool, container runtime, system service manager). Because
81
-
* programs sandboxing themselves should fix any denied access, they should
82
-
* not set this flag to be aware of potential issues reported by system's
83
-
* logs (i.e. audit).
92
+
* Disables logging of denied accesses originating from the thread creating
93
+
* the Landlock domain, as well as its children, as long as they continue
94
+
* running the same executable code (i.e., without an intervening
95
+
* :manpage:`execve(2)` call). This is intended for programs that execute
96
+
* unknown code without invoking :manpage:`execve(2)`, such as script
97
+
* interpreters. Programs that only sandbox themselves should not set this
98
+
* flag, so users can be notified of unauthorized access attempts via system
99
+
* logs.
84
100
*
85
101
* %LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON
86
-
* Explicitly ask to continue logging denied access requests even after an
87
-
* :manpage:`execve(2)` call. This flag should only be set if all the
88
-
* programs than can legitimately be executed will not try to request a
89
-
* denied access (which could spam audit logs).
102
+
* Enables logging of denied accesses after an :manpage:`execve(2)` call,
103
+
* providing visibility into unauthorized access attempts by newly executed
104
+
* programs within the created Landlock domain. This flag is recommended
105
+
* only when all potential executables in the domain are expected to comply
106
+
* with the access restrictions, as excessive audit log entries could make
107
+
* it more difficult to identify critical events.
90
108
*
91
109
* %LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF
92
-
* Do not create any log related to the enforced restrictions coming from
93
-
* future nested domains created by the caller or its descendants. This
94
-
* should only be set according to a runtime configuration (i.e. not
95
-
* hardcoded) by programs launching other unknown or untrusted programs that
96
-
* may create their own Landlock domains and spam logs. The main use case
97
-
* is for container runtimes to enable users to mute buggy sandboxed
98
-
* programs for a specific container image. Other use cases include
99
-
* sandboxer tools and init systems. Unlike
100
-
* ``LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF``,
101
-
* ``LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF`` does not impact the
102
-
* requested restriction (if any) but only the future nested domains.
103
-
*
104
-
* It is allowed to only pass the
105
-
* ``LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF`` flag with a @ruleset_fd
106
-
* value of -1.
107
-
*
110
+
* Disables logging of denied accesses originating from nested Landlock
111
+
* domains created by the caller or its descendants. This flag should be set
112
+
* according to runtime configuration, not hardcoded, to avoid suppressing
113
+
* important security events. It is useful for container runtimes or
114
+
* sandboxing tools that may launch programs which themselves create
115
+
* Landlock domains and could otherwise generate excessive logs. Unlike
116
+
* ``LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF``, this flag only affects
117
+
* future nested domains, not the one being created. It can also be used
118
+
* with a @ruleset_fd value of -1 to mute subdomain logs without creating a
119
+
* domain.
108
120
*/
109
121
/* clang-format off */
110
122
#define LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF (1U << 0)