Re: [RFC PATCH v1 11/11] landlock: Add documentation for capability and namespace restrictions

Justin Suess
2026-04-23T16:08:43Z

On Thu, Apr 23, 2026 at 12:01:08PM -0400, Justin Suess wrote:
> On Thu, Apr 23, 2026 at 03:51:32PM +0200, Mickaël Salaün wrote:
> > On Thu, Mar 12, 2026 at 10:48:42AM -0400, Justin Suess wrote:
> > > On Thu, Mar 12, 2026 at 11:04:44AM +0100, Mickaël Salaün wrote:
> > > > Document the two new Landlock permission categories in the userspace
> > > > API guide, admin guide, and kernel security documentation.
> > > >
> > > > The userspace API guide adds sections on capability restriction
> > > > (LANDLOCK_PERM_CAPABILITY_USE with LANDLOCK_RULE_CAPABILITY), namespace
> > > > restriction (LANDLOCK_PERM_NAMESPACE_ENTER with LANDLOCK_RULE_NAMESPACE
> > > > covering creation via unshare/clone and entry via setns), and the
> > > > backward-compatible degradation pattern for ABI < 9. A table documents
> > > > the per-namespace-type capability requirements for both creation and
> > > > entry.
> > > >
> > > > The admin guide adds the new perm.namespace_enter and
> > > > perm.capability_use audit blocker names with their object identification
> > > > fields (namespace_type, namespace_inum, capability).
> > > >
> > > > The kernel security documentation adds a "Ruleset restriction models"
> > > > section defining the three models (handled_access_*, handled_perm,
> > > > scoped), their coverage and compatibility properties, and the criteria
> > > > for choosing between them for future features. It also documents
> > > > composability with user namespaces and adds kernel-doc references for
> > > > the new capability and namespace headers.
> > > >
> > > > 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>
> > > > Signed-off-by: Mickaël Salaün <mic@digikod.net>
> > > > ---
> > > > Documentation/admin-guide/LSM/landlock.rst | 19 ++-
> > > > Documentation/security/landlock.rst | 80 ++++++++++-
> > > > Documentation/userspace-api/landlock.rst | 156 ++++++++++++++++++++-
> > > > 3 files changed, 245 insertions(+), 10 deletions(-)
> > > >
> > > > diff --git a/Documentation/admin-guide/LSM/landlock.rst b/Documentation/admin-guide/LSM/landlock.rst
> > > > index 9923874e2156..99c6a599ce9e 100644
> > > > --- a/Documentation/admin-guide/LSM/landlock.rst
> > > > +++ b/Documentation/admin-guide/LSM/landlock.rst
> > > > @@ -6,7 +6,7 @@ Landlock: system-wide management
> > > > ================================
> > > >
> > > > :Author: Mickaël Salaün
> > > > -:Date: January 2026
> > > > +:Date: March 2026
> > > >
> > > > Landlock can leverage the audit framework to log events.
> > > >
> > > > @@ -59,14 +59,25 @@ AUDIT_LANDLOCK_ACCESS
> > > > - scope.abstract_unix_socket - Abstract UNIX socket connection denied
> > > > - scope.signal - Signal sending denied
> > > >
> > > > + **perm.*** - Permission restrictions (ABI 9+):
> > > > + - perm.namespace_enter - Namespace entry was denied (creation via
> > > > + :manpage:`unshare(2)` / :manpage:`clone(2)` or joining via
> > > > + :manpage:`setns(2)`);
> > > > + ``namespace_type`` indicates the type (hex CLONE_NEW* bitmask),
> > > > + ``namespace_inum`` identifies the target namespace for
> > > > + :manpage:`setns(2)` operations
> > > > + - perm.capability_use - Capability use was denied;
> > > > + ``capability`` indicates the capability number
> > > > +
> > > > Multiple blockers can appear in a single event (comma-separated) when
> > > > multiple access rights are missing. For example, creating a regular file
> > > > in a directory that lacks both ``make_reg`` and ``refer`` rights would show
> > > > ``blockers=fs.make_reg,fs.refer``.
> > > >
> > > > - The object identification fields (path, dev, ino for filesystem; opid,
> > > > - ocomm for signals) depend on the type of access being blocked and provide
> > > > - context about what resource was involved in the denial.
> > > > + The object identification fields depend on the type of access being blocked:
> > > > + ``path``, ``dev``, ``ino`` for filesystem; ``opid``, ``ocomm`` for signals;
> > > > + ``namespace_type`` and ``namespace_inum`` for namespace operations;
> > > > + ``capability`` for capability use.
> > > >
> > > >
> > > > AUDIT_LANDLOCK_DOMAIN
> > > > diff --git a/Documentation/security/landlock.rst b/Documentation/security/landlock.rst
> > > > index 3e4d4d04cfae..cd3d640ca5c9 100644
> > > > --- a/Documentation/security/landlock.rst
> > > > +++ b/Documentation/security/landlock.rst
> > > > @@ -7,7 +7,7 @@ Landlock LSM: kernel documentation
> > > > ==================================
> > > >
> > > > :Author: Mickaël Salaün
> > > > -:Date: September 2025
> > > > +:Date: March 2026
> > > >
> > > > Landlock's goal is to create scoped access-control (i.e. sandboxing). To
> > > > harden a whole system, this feature should be available to any process,
> > > > @@ -89,6 +89,72 @@ this is required to keep access controls consistent over the whole system, and
> > > > this avoids unattended bypasses through file descriptor passing (i.e. confused
> > > > deputy attack).
> > > >
> > > > +Composability with user namespaces
> > > > +----------------------------------
> > > > +
> > > > +Landlock domain-based scoping and the kernel's user namespace-based capability
> > > > +scoping enforce isolation over independent hierarchies. Landlock checks domain
> > > > +ancestry; the kernel's ``ns_capable()`` checks user namespace ancestry. These
> > > > +hierarchies are orthogonal: Landlock enforcement is deterministic with respect
> > > > +to its own configuration, regardless of namespace or capability state, and vice
> > > > +versa. This orthogonality is a design invariant that must hold for all new
> > > > +scoped features.
> > > The last sentence on orthogonality may better belong under the restriction
> > > model section for scoped access rights. I assume that future scopes must
> > > also be deterministic with respect to landlock's configuration as well,
> > > not just user namespaces.
> >
> > Correct
> >
> > > > +
> > > > +Ruleset restriction models
> > > > +--------------------------
> > > +1
> > >
> > > This section is very helpful for aligning new features with a particular
> > > model.
> >
> > Thanks
> >
> > >
> > > > +
> > > > +Landlock provides three restriction models, each with different coverage
> > > > +and compatibility properties.
> > > Maybe add:
> > >
> > > Each restriction model below corresponds to one or more fields of
> > > ``struct landlock_ruleset_attr``.
> >
> > Ok
> >
> > >
> > > > +
> > > > +Access rights (``handled_access_*``)
> > > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > > > +
> > > > +Access rights control **enumerated operations on kernel objects**
> > > > +identified by a rule key (a file hierarchy or a network port). Each
> > > > +``handled_access_*`` field declares a set of access rights that the
> > > > +ruleset restricts. Multiple access rights share a single rule type.
> > > > +Operations for which no access right exists yet remain uncontrolled;
> > > > +new rights are added incrementally across ABI versions.
> > > > +
> > > > +Permissions (``handled_perm``)
> > > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > > > +
> > > > +Permissions control **broad operations enforced at single kernel
> > > > +chokepoints**, achieving complete deny-by-default coverage. Each
> > > > +``LANDLOCK_PERM_*`` flag maps to its own rule type. When a ruleset
> > > > +handles a permission, all instances of that operation are denied unless
> > > > +explicitly allowed by a rule. New kernel values (new ``CAP_*``
> > > > +capabilities, new ``CLONE_NEW*`` namespace types) are automatically
> > > > +denied without any Landlock update.
> > > > +
> > > > +Each permission flag names a single gateway operation whose control
> > > > +transitively covers an open-ended set of downstream operations: for
> > > > +example, exercising a capability enables privileged operations across
> > > > +many subsystems; entering a namespace enables gaining capabilities in a
> > > > +new context.
> > > > +
> > > > +Permission rules identify what to allow using constants defined by other
> > > > +kernel subsystems (``CAP_*``, ``CLONE_NEW*``). Unknown values are
> > > > +silently ignored because deny-by-default ensures they are denied anyway.
> > > > +In contrast, unknown ``LANDLOCK_PERM_*`` flags in ``handled_perm`` are
> > > > +rejected (``-EINVAL``), since Landlock owns that namespace.
> > > > +
> > > > +Scopes (``scoped``)
> > > > +~~~~~~~~~~~~~~~~~~~~
> > > > +
> > > > +Scopes restrict **cross-domain interactions** categorically, without
> > > > +rules. Setting a scope flag (e.g. ``LANDLOCK_SCOPE_SIGNAL``) denies the
> > > > +operation to targets outside the Landlock domain or its children. Like
> > > > +permissions, scopes provide complete coverage of the controlled
> > > > +operation.
> > > > +
> > > > +When adding new Landlock features, new operations on existing rule types
> > > > +extend the corresponding ``handled_access_*`` field (e.g. a new
> > > > +filesystem operation extends ``handled_access_fs``). A new object
> > > > +category with multiple fine-grained operations would use a new
> > > > +``handled_access_*`` field. New rule types that control a single
> > > > +chokepoint operation use ``handled_perm``.
> > > > +
> > > > Tests
> > > > =====
> > > >
> > > > @@ -110,6 +176,18 @@ Filesystem
> > > > .. kernel-doc:: security/landlock/fs.h
> > > > :identifiers:
> > > >
> > > > +Namespace
> > > > +---------
> > > > +
> > > > +.. kernel-doc:: security/landlock/ns.h
> > > > + :identifiers:
> > > > +
> > > > +Capability
> > > > +----------
> > > > +
> > > > +.. kernel-doc:: security/landlock/cap.h
> > > > + :identifiers:
> > > > +
> > > > Process credential
> > > > ------------------
> > > >
> > > > diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> > > > index 13134bccdd39..238d30a18162 100644
> > > > --- a/Documentation/userspace-api/landlock.rst
> > > > +++ b/Documentation/userspace-api/landlock.rst
> > > > @@ -8,7 +8,7 @@ Landlock: unprivileged access control
> > > > =====================================
> > > >
> > > > :Author: Mickaël Salaün
> > > > -:Date: January 2026
> > > > +:Date: March 2026
> > > >
> > > > The goal of Landlock is to enable restriction of ambient rights (e.g. global
> > > > filesystem or network access) for a set of processes. Because Landlock
> > > > @@ -33,7 +33,7 @@ A Landlock rule describes an action on an object which the process intends to
> > > > perform. A set of rules is aggregated in a ruleset, which can then restrict
> > > > the thread enforcing it, and its future children.
> > > >
> > > > -The two existing types of rules are:
> > > > +The existing types of rules are:
> > > >
> > > > Filesystem rules
> > > > For these rules, the object is a file hierarchy,
> > > > @@ -44,6 +44,14 @@ Network rules (since ABI v4)
> > > > For these rules, the object is a TCP port,
> > > > and the related actions are defined with `network access rights`.
> > > >
> > > > +Capability rules (since ABI v9)
> > > > + For these rules, the object is a set of Linux capabilities,
> > > > + and the related actions are defined with `permission flags`.
> > > > +
> > > > +Namespace rules (since ABI v9)
> > > > + For these rules, the object is a set of namespace types,
> > > > + and the related actions are defined with `permission flags`.
> > > > +
> > > > Defining and enforcing a security policy
> > > > ----------------------------------------
> > > >
> > > > @@ -84,6 +92,9 @@ to be explicit about the denied-by-default access rights.
> > > > .scoped =
> > > > LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET |
> > > > LANDLOCK_SCOPE_SIGNAL,
> > > > + .handled_perm =
> > > > + LANDLOCK_PERM_CAPABILITY_USE |
> > > > + LANDLOCK_PERM_NAMESPACE_ENTER,
> > > > };
> > > >
> > > > Because we may not know which kernel version an application will be executed
> > > > @@ -127,6 +138,12 @@ version, and only use the available subset of access rights:
> > > > /* Removes LANDLOCK_SCOPE_* for ABI < 6 */
> > > > ruleset_attr.scoped &= ~(LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET |
> > > > LANDLOCK_SCOPE_SIGNAL);
> > > > + __attribute__((fallthrough));
> > > > + case 6:
> > > > + case 7:
> > > > + case 8:
> > > > + /* Removes permission support for ABI < 9 */
> > > > + ruleset_attr.handled_perm = 0;
> > > > }
> > > >
> > > > This enables the creation of an inclusive ruleset that will contain our rules.
> > > > @@ -191,6 +208,42 @@ number for a specific action: HTTPS connections.
> > > > err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_NET_PORT,
> > > > &net_port, 0);
> > > >
> > > > +For capability access-control, we can add rules that allow specific
> > > > +capabilities. For instance, to allow ``CAP_SYS_CHROOT`` (so the sandboxed
> > > > +process can call :manpage:`chroot(2)` inside a user namespace):
> > > > +
> > > > +.. code-block:: c
> > > > +
> > > > + struct landlock_capability_attr cap_attr = {
> > > > + .allowed_perm = LANDLOCK_PERM_CAPABILITY_USE,
> > > > + .capabilities = (1ULL << CAP_SYS_CHROOT),
> > > > + };
> > > > +
> > > > + err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_CAPABILITY,
> > > > + &cap_attr, 0);
> > > > +
> > > > +For namespace access-control, we can add rules that allow entering specific
> > > > +namespace types (creating them via :manpage:`unshare(2)` / :manpage:`clone(2)`
> > > > +or joining them via :manpage:`setns(2)`). For instance, to allow creating user
> > > > +namespaces (which grants all capabilities inside the new namespace):
> > > > +
> > > > +.. code-block:: c
> > > > +
> > > > + struct landlock_namespace_attr ns_attr = {
> > > > + .allowed_perm = LANDLOCK_PERM_NAMESPACE_ENTER,
> > > > + .namespace_types = CLONE_NEWUSER,
> > > > + };
> > > > +
> > > > + err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_NAMESPACE,
> > > > + &ns_attr, 0);
> > > > +
> > > > +Together, these two rules allow an unprivileged process to create a user
> > > > +namespace and call :manpage:`chroot(2)` inside it, while denying all other
> > > > +capabilities and namespace types. User namespace creation is the one operation
> > > > +that does not require ``CAP_SYS_ADMIN``, so no capability rule is needed for it.
> > > > +See `Capability and namespace restrictions`_ for details on capability
> > > > +requirements.
> > > > +
> > > > When passing a non-zero ``flags`` argument to ``landlock_restrict_self()``, a
> > > > similar backwards compatibility check is needed for the restrict flags
> > > > (see sys_landlock_restrict_self() documentation for available flags):
> > > > @@ -354,10 +407,87 @@ The operations which can be scoped are:
> > > > A :manpage:`sendto(2)` on a socket which was previously connected will not
> > > > be restricted. This works for both datagram and stream sockets.
> > > >
> > > > -IPC scoping does not support exceptions via :manpage:`landlock_add_rule(2)`.
> > > > +Scoping does not support exceptions via :manpage:`landlock_add_rule(2)`.
> > > > If an operation is scoped within a domain, no rules can be added to allow access
> > > > to resources or processes outside of the scope.
> > > >
> > > > +Capability and namespace restrictions
> > > > +-------------------------------------
> > > > +
> > > > +See Documentation/security/landlock.rst for the design rationale behind
> > > > +the permission model (``handled_perm``) and how it differs from access
> > > > +rights (``handled_access_*``) and scopes (``scoped``).
> > > > +When a process creates a user namespace, the kernel grants all capabilities
> > > > +within that namespace. While these capabilities cannot directly bypass Landlock
> > > > +restrictions (Landlock enforces access controls independently of capability
> > > > +checks), they open kernel code paths that are normally unreachable to
> > > > +unprivileged users and may contain exploitable bugs.
> > > > +
> > > > +Landlock provides two complementary permissions to address this.
> > > > +``LANDLOCK_PERM_CAPABILITY_USE`` restricts which capabilities a process can use,
> > > > +even when it holds them. ``LANDLOCK_PERM_NAMESPACE_ENTER`` restricts which
> > > > +namespace types a process can create (via :manpage:`unshare(2)` or
> > > > +:manpage:`clone(2)`) or join (via :manpage:`setns(2)`). After creating a user
> > > > +namespace, the granted capabilities are scoped to namespaces owned by that user
> > > > +namespace or its descendants; to exercise a capability such as
> > > > +``CAP_NET_ADMIN``, the process must create a namespace of the corresponding type
> > > > +(e.g., a network namespace). Configuring both permissions together provides
> > > > +full coverage: ``LANDLOCK_PERM_CAPABILITY_USE`` restricts which capabilities are
> > > > +available, while ``LANDLOCK_PERM_NAMESPACE_ENTER`` restricts the namespaces in
> > > > +which they can be used.
> > > Maybe add a section on the what this does versus PR_SET_NO_NEW_PRIVS.
> >
> > Hmm, what do you mean? What would be the link with this part?
> PR_SET_NO_NEW_PRIVS prevents gaining of privileges through execution,
> including capabilities (i.e setcap command, not just setuid/gid).
> So they're adjacent at least.
>
> Some users might not want to set NNP because they want to execute
> a binary with w/ CAP_BPF file capabilities set for instance. But
> they don't need CAP_SYS_ADMIN or whatever for their usecase.
>
Bad example sorry. They need CAP_SYS_ADMIN to make the ruleset. But this
point still applies for other caps or if they drop CAP_SYS_ADMIN after
applying the ruleset.