Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

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
··· 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)