landlock: Add documentation for capability and namespace restrictions

Document the two new Landlock permission categories, introduced with ABI
12, in the userspace API guide, admin guide, trace-event guide, UAPI
comments, and kernel security documentation.

The kernel security documentation generalizes the existing per-object
access-rights framing into three restriction models (handled_access_*,
handled_permissions, scoped) and states criteria for choosing among
them, so future permission or scope additions have a documented place to
land.

Cc: Christian Brauner <brauner@kernel.org>
Cc: Günther Noack <gnoack@google.com>
Cc: Paul Moore <paul@paul-moore.com>
Cc: Serge E. Hallyn <serge@hallyn.com>
Link: https://patch.msgid.link/20261014082718.1435842-9-mic@digikod.net
Signed-off-by: Mickaël Salaün <mic@digikod.net>

2 files changed, 15 insertions, 13 deletions

diff --git a/include/trace/events/landlock.h b/include/trace/events/landlock.h
index 744ef55ec1de..4f19d1c04d74 100644
--- a/include/trace/events/landlock.h
+++ b/include/trace/events/landlock.h
@@ -278,11 +278,12 @@ static inline const char *__trace_landlock_print_layers(
  * Every denial event shares three fields.  domain is the ID of the
  * innermost domain that blocked the access.  same_exec tells whether the
  * current task is the same executable that entered that domain.  logged is
- * the domain's audit-logging decision for this denial (its log_status is
- * enabled and the per-execution flag selected by same_exec is set); a
- * stateless ftrace filter can select the denials the domain submits to
- * audit with logged==1, without reconstructing it from the per-execution
- * log flags.  Denial events order their shared fields as domain, same_exec,
+ * the complete audit-submission selection for this denial: the domain's
+ * log_status and per-execution flag, per-object or per-member quiet rules,
+ * and request-specific no-audit options.  This excludes global audit state
+ * and audit-side filters.  A stateless ftrace filter can select the denials
+ * the domain submits to audit with logged==1, without reconstructing those
+ * inputs.  Denial events order their shared fields as domain, same_exec,
  * and logged.  Access and permission denial events follow these with the
  * blockers verdict input, type-specific fields, and any variable-length field.
  *
diff --git a/include/uapi/linux/landlock.h b/include/uapi/linux/landlock.h
index 3128e58d4b78..24510e5d8479 100644
--- a/include/uapi/linux/landlock.h
+++ b/include/uapi/linux/landlock.h
@@ -33,14 +33,14 @@
  * (and that they have tested with a kernel that supported them all).
  *
  * @quiet_access_fs and @quiet_access_net are bitmasks of actions for which a
- * denial by this layer will not trigger a log if the corresponding object (or
- * its children, for filesystem rules) is marked with the "quiet" bit via
- * %LANDLOCK_ADD_RULE_QUIET, even if logging would normally take place per
+ * denial by this layer will not trigger an audit record if the corresponding
+ * object (or its children, for filesystem rules) is marked with the "quiet" bit
+ * via %LANDLOCK_ADD_RULE_QUIET, even if logging would normally take place per
  * landlock_restrict_self() flags.  @quiet_scoped is similar, except that it
  * does not require marking any objects as quiet - if the ruleset is created
  * with any bits set in @quiet_scoped, then denial of such scoped resources will
- * not trigger any log.  These 3 fields are available since Landlock ABI version
- * 10.
+ * not trigger an audit record.  These three fields are available since Landlock
+ * ABI version 10.
  *
  * @quiet_access_fs, @quiet_access_net and @quiet_scoped must be a subset of
  * @handled_access_fs, @handled_access_net and @scoped respectively.
@@ -66,16 +66,17 @@ struct landlock_ruleset_attr {
 	__u64 scoped;
 	/**
 	 * @quiet_access_fs: Bitmask of filesystem actions which should not be
-	 * logged if per-object quiet flag is set.
+	 * submitted to audit if the per-object quiet flag is set.
 	 */
 	__u64 quiet_access_fs;
 	/**
 	 * @quiet_access_net: Bitmask of network actions which should not be
-	 * logged if per-object quiet flag is set.
+	 * submitted to audit if the per-object quiet flag is set.
 	 */
 	__u64 quiet_access_net;
 	/**
-	 * @quiet_scoped: Bitmask of scoped actions which should not be logged.
+	 * @quiet_scoped: Bitmask of scoped actions which should not be
+	 * submitted to audit.
 	 */
 	__u64 quiet_scoped;
 	/**