[PATCH v2 17/17] landlock: Document tracepoints

Mickaël Salaün
2026-04-06T14:37:48Z

Add tracepoint documentation to the kernel security documentation.
Describe the complete lifecycle of trace events (create, deny, free),
the enriched denial fields (same_exec, log_same_exec, log_new_exec), and
the design for both stateful (eBPF) and stateless (ftrace) consumers.

Cc: Günther Noack <gnoack@google.com>
Cc: Tingmao Wang <m@maowtm.org>
Signed-off-by: Mickaël Salaün <mic@digikod.net>
---

Changes since v1:
- New patch.
---
Documentation/admin-guide/LSM/landlock.rst | 210 ++++++++++++++++++++-
Documentation/security/landlock.rst | 35 +++-
Documentation/trace/events-landlock.rst | 160 ++++++++++++++++
Documentation/trace/index.rst | 1 +
Documentation/userspace-api/landlock.rst | 11 +-
5 files changed, 412 insertions(+), 5 deletions(-)
create mode 100644 Documentation/trace/events-landlock.rst

diff --git a/Documentation/admin-guide/LSM/landlock.rst b/Documentation/admin-guide/LSM/landlock.rst
index 9923874e2156..cad5845b6ec7 100644
--- a/Documentation/admin-guide/LSM/landlock.rst
+++ b/Documentation/admin-guide/LSM/landlock.rst
@@ -1,12 +1,13 @@
.. SPDX-License-Identifier: GPL-2.0
.. Copyright © 2025 Microsoft Corporation
+.. Copyright © 2026 Cloudflare

================================
Landlock: system-wide management
================================

:Author: Mickaël Salaün
-:Date: January 2026
+:Date: April 2026

Landlock can leverage the audit framework to log events.

@@ -176,11 +177,218 @@ filters to limit noise with two complementary ways:
programs,
- or with audit rules (see :manpage:`auditctl(8)`).

+Tracepoints
+===========
+
+Landlock also provides tracepoints as an alternative to audit for
+debugging and observability. Tracepoints fire unconditionally,
+independent of audit configuration, ``audit_enabled``, and domain log
+flags. This makes them suitable for always-on monitoring with eBPF or
+for ad-hoc debugging with ``trace-pipe``. See
+:doc:`/trace/events-landlock` for the complete event reference.
+
+Enabling tracepoints
+--------------------
+
+Enable individual Landlock tracepoints via tracefs::
+
+ # Enable filesystem denial tracing:
+ echo 1 > /sys/kernel/tracing/events/landlock/landlock_deny_access_fs/enable
+
+ # Enable all Landlock events:
+ echo 1 > /sys/kernel/tracing/events/landlock/enable
+
+ # Read the trace output:
+ cat /sys/kernel/tracing/trace_pipe
+
+Available events
+----------------
+
+**Policy setup events:**
+
+- ``landlock_create_ruleset`` -- emitted when a ruleset is created.
+ Fields: ``ruleset`` (ID and version), ``handled_fs``, ``handled_net``,
+ ``scoped``.
+
+- ``landlock_add_rule_fs``, ``landlock_add_rule_net`` -- emitted when a
+ rule is added. Fields: ``ruleset`` (ID and version),
+ ``access_rights`` (access mask),
+ target identifier (``dev:ino`` and ``path`` for FS, ``port`` for net).
+
+- ``landlock_restrict_self`` -- emitted when a task restricts itself.
+ Fields: ``ruleset`` (ID and version), ``domain`` (new domain ID),
+ ``parent`` (parent domain ID or 0).
+
+**Access check events (hot path):**
+
+- ``landlock_check_rule_fs``, ``landlock_check_rule_net`` -- emitted
+ when a rule matches during an access check. Fires for every matching
+ rule in the pathwalk, regardless of the final outcome (allowed or
+ denied).
+
+**Denial events:**
+
+- ``landlock_deny_access_fs``, ``landlock_deny_access_net`` -- emitted
+ when a filesystem or network access is denied.
+- ``landlock_deny_ptrace``, ``landlock_deny_scope_signal``,
+ ``landlock_deny_scope_abstract_unix_socket`` -- emitted when a scope
+ check denies access.
+
+ Common fields include:
+
+ - ``domain`` -- the denying domain's ID
+ - ``blockers`` -- the denied access rights (bitmask,
+ ``deny_access_fs`` and ``deny_access_net`` only)
+ - ``same_exec`` -- whether the task is the same executable that
+ called ``landlock_restrict_self()`` for the denying domain
+ - ``log_same_exec``, ``log_new_exec`` -- the domain's configured log
+ flags (useful for filtering expected denials)
+ - Type-specific fields: ``path`` (FS), ``sport``/``dport`` (net),
+ ``tracee_pid``/``comm`` (ptrace), ``target_pid``/``comm`` (signal),
+ ``peer_pid``/``sun_path`` (abstract unix socket)
+
+**Lifecycle events:**
+
+- ``landlock_free_domain`` -- emitted when a domain is deallocated.
+ Fields: ``domain`` (ID), ``denials`` (total denial count).
+- ``landlock_free_ruleset`` -- emitted when a ruleset is freed.
+ Fields: ``ruleset`` (ID and version).
+
+Event samples
+-------------
+
+A sandboxed program tries to read ``/etc/passwd`` with only ``/tmp``
+writable::
+
+ $ echo 1 > /sys/kernel/tracing/events/landlock/enable
+ $ LL_FS_RO=/ LL_FS_RW=/tmp ./sandboxer cat /etc/passwd &
+ $ cat /sys/kernel/tracing/trace_pipe
+ sandboxer-286 landlock_create_ruleset: ruleset=10b556c58.0 handled_fs=0xdfff handled_net=0x0 scoped=0x0
+ sandboxer-286 landlock_restrict_self: ruleset=10b556c58.3 domain=10b556c61 parent=0
+ cat-287 landlock_deny_access_fs: domain=10b556c61 same_exec=0 log_same_exec=1 log_new_exec=0 blockers=0x4 dev=254:2 ino=143821 path=/etc/passwd
+ kworker/0:1-12 landlock_free_domain: domain=10b556c61 denials=1
+
+Unlike audit, tracepoints fire for all denials regardless of the
+domain's log flags. This means ``deny_access_*`` events appear even
+when ``LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF`` would suppress the
+corresponding audit record.
+
+Filtering with ftrace
+---------------------
+
+Use ftrace filter expressions to select specific events::
+
+ # Only show denials that audit would also log:
+ echo 'same_exec == 1 && log_same_exec == 1 || same_exec == 0 && log_new_exec == 1' > \
+ /sys/kernel/tracing/events/landlock/landlock_deny_access_fs/filter
+
+Using eBPF
+----------
+
+eBPF programs can attach to Landlock tracepoints to build custom
+monitoring. A stateful eBPF program observes the full event stream and
+maintains per-domain state in BPF maps:
+
+1. On ``landlock_restrict_self``: record the domain ID, parent, flags.
+2. On ``landlock_deny_access_*``: look up the domain, decide whether
+ to count, alert, or ignore the denial based on custom policy.
+3. On ``landlock_free_domain``: clean up the per-domain state, log
+ final statistics.
+
+This approach requires no kernel modification and no Landlock-specific
+BPF helpers. The Landlock IDs serve as correlation keys across events.
+
+.. _landlock_observability:
+
+When to use tracing vs audit
+-----------------------------
+
+Audit and tracing both help diagnose Landlock policy issues:
+
+**Audit** records denied accesses with the blockers, domain, and object
+identification (path, port). Audit is the standard Linux mechanism for
+security events, with a stable record format that is well established
+and already supported by log management systems, SIEM platforms, and EDR
+solutions. Audit is always active (when ``CONFIG_AUDIT`` is set),
+filtered by log flags to reduce noise in production, and designed for
+long-term security monitoring and compliance.
+
+**Tracing** provides deeper introspection for policy debugging. In
+addition to denied accesses, trace events cover the complete lifecycle
+of Landlock objects (rulesets, domains) and intermediate rule matching
+during access checks. Trace events are disabled by default (zero
+overhead) and fire unconditionally, regardless of log flags. eBPF
+programs attached to trace events can access the full kernel context
+(ruleset rules, domain hierarchy, process credentials) via BTF, enabling
+richer analysis than the flat fields in audit records. For example, an
+eBPF-based live monitoring tool can correlate creation, rule-addition,
+and denial events to build a real-time view of all active Landlock
+domains and their policies. However, BTF-based access depends on
+internal kernel struct layouts which have no stability guarantee. CO-RE
+(Compile Once, Run Everywhere) provides best-effort field relocation.
+The ftrace printk format is also not a stable ABI, but is
+self-describing via the per-event ``format`` file, allowing tools to
+adapt dynamically.
+
+Observability guarantees and limitations
+-----------------------------------------
+
+Both audit records and trace events are emitted for every denied access,
+with these exceptions:
+
+- **Log flags** (audit only): ``LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF``,
+ ``LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON``, and
+ ``LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF`` control which denials
+ generate audit records. Trace events fire regardless of these flags.
+
+- **NOAUDIT hooks**: Some LSM hooks suppress logging for speculative
+ permission probes (e.g., reading ``/proc/<pid>/status`` uses
+ ``PTRACE_MODE_NOAUDIT``). When NOAUDIT is set, neither audit records
+ nor trace events are emitted, and the denial is not counted in
+ ``denials``. The denial is still enforced. This avoids performance
+ overhead and noise from speculative probes that test permissions
+ without performing an actual access.
+
+- **Audit rate limiting**: The audit subsystem may silently drop records
+ when the audit queue is full. Trace events are not rate-limited.
+
+- **Tracepoint disabled**: When a trace event is disabled (the default
+ state), the tracepoint is a no-op with zero overhead.
+
+When both audit and tracing are active, every logged denial produces both
+an audit record (subject to log flags) and a trace event. The
+``denials`` count in ``free_domain`` events reflects the total number of
+logged denials, which may be lower than the actual number of enforced
+denials due to NOAUDIT hooks.
+
+.. _landlock_observability_security:
+
+Observability security considerations
+---------------------------------------
+
+Both audit records and trace events expose information about all
+Landlock-sandboxed processes on the system, including filesystem paths
+being accessed, network ports, and process identities. System
+administrators must ensure that access to audit logs (controlled by the
+audit subsystem configuration) and to trace events (requiring
+``CAP_SYS_ADMIN`` or ``CAP_BPF`` + ``CAP_PERFMON``) is restricted to
+trusted users.
+
+eBPF programs attached to Landlock trace events have access to the full
+kernel context of each event (ruleset rules, domain hierarchy, process
+credentials) via BTF. This level of access is comparable to
+``CAP_SYS_ADMIN`` and must be treated accordingly.
+
+Audit logs and kernel trace events require elevated privileges and are
+system-wide; they are not designed for per-sandbox unprivileged
+monitoring.
+
Additional documentation
========================

* `Linux Audit Documentation`_
* Documentation/userspace-api/landlock.rst
+* Documentation/trace/events-landlock.rst
* Documentation/security/landlock.rst
* https://landlock.io

diff --git a/Documentation/security/landlock.rst b/Documentation/security/landlock.rst
index c5186526e76f..5ef0164fbafb 100644
--- a/Documentation/security/landlock.rst
+++ b/Documentation/security/landlock.rst
@@ -1,13 +1,14 @@
.. SPDX-License-Identifier: GPL-2.0
.. Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net>
.. Copyright © 2019-2020 ANSSI
+.. Copyright © 2026 Cloudflare

==================================
Landlock LSM: kernel documentation
==================================

:Author: Mickaël Salaün
-:Date: March 2026
+:Date: April 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,
@@ -177,11 +178,43 @@ makes the reasoning much easier and helps avoid pitfalls.
.. kernel-doc:: security/landlock/domain.h
:identifiers:

+Denial logging
+==============
+
+Access denials are logged through two independent channels: audit
+records and tracepoints. Both are managed by the common denial
+framework in ``log.c``, compiled under ``CONFIG_SECURITY_LANDLOCK_LOG``
+(automatically selected by ``CONFIG_AUDIT`` or ``CONFIG_TRACEPOINTS``).
+
+Audit records respect audit configuration, domain log flags, and
+``LANDLOCK_LOG_DISABLED``. Tracepoints fire unconditionally,
+independent of audit configuration and domain log flags. The denial
+counter (``num_denials``) is always incremented regardless of logging
+configuration.
+
+See Documentation/admin-guide/LSM/landlock.rst for audit record format,
+tracepoint usage, and filtering examples.
+
+.. kernel-doc:: security/landlock/log.h
+ :identifiers:
+
+Trace events
+------------
+
+See :doc:`/trace/events-landlock` for trace event usage and format details.
+
+.. kernel-doc:: include/trace/events/landlock.h
+ :doc: Landlock trace events
+
+.. kernel-doc:: include/trace/events/landlock.h
+ :internal:
+
Additional documentation
========================

* Documentation/userspace-api/landlock.rst
* Documentation/admin-guide/LSM/landlock.rst
+* Documentation/trace/events-landlock.rst
* https://landlock.io

.. Links
diff --git a/Documentation/trace/events-landlock.rst b/Documentation/trace/events-landlock.rst
new file mode 100644
index 000000000000..802df09259ce
--- /dev/null
+++ b/Documentation/trace/events-landlock.rst
@@ -0,0 +1,160 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. Copyright © 2026 Cloudflare
+
+=====================
+Landlock Trace Events
+=====================
+
+:Date: April 2026
+
+Landlock emits trace events for sandbox lifecycle operations and access
+denials. These events can be consumed by ftrace (for human-readable
+trace output and filtering) and by eBPF programs (for programmatic
+introspection via BTF).
+
+See Documentation/security/landlock.rst for Landlock kernel internals and
+Documentation/admin-guide/LSM/landlock.rst for system administration.
+
+.. warning::
+
+ Landlock trace events, like audit records, expose sensitive
+ information about all sandboxed processes on the system. See
+ :ref:`landlock_observability_security` for security considerations
+ and privilege requirements.
+
+See Documentation/userspace-api/landlock.rst for the userspace API.
+
+Event overview
+==============
+
+Landlock trace events are organized in four categories:
+
+**Syscall events** are emitted during Landlock system calls:
+
+- ``landlock_create_ruleset``: a new ruleset is created
+- ``landlock_add_rule_fs``: a filesystem rule is added to a ruleset
+- ``landlock_add_rule_net``: a network port rule is added to a ruleset
+- ``landlock_restrict_self``: a new domain is created from a ruleset
+
+**Denial events** are emitted when an access is denied:
+
+- ``landlock_deny_access_fs``: filesystem access denied
+- ``landlock_deny_access_net``: network access denied
+- ``landlock_deny_ptrace``: ptrace access denied
+- ``landlock_deny_scope_signal``: signal delivery denied
+- ``landlock_deny_scope_abstract_unix_socket``: abstract unix socket
+ access denied
+
+**Rule evaluation events** are emitted during rule matching:
+
+- ``landlock_check_rule_fs``: a filesystem rule is evaluated
+- ``landlock_check_rule_net``: a network port rule is evaluated
+
+**Lifecycle events**:
+
+- ``landlock_free_domain``: a domain is freed
+- ``landlock_free_ruleset``: a ruleset is freed
+
+Enabling events
+===============
+
+Enable all Landlock events::
+
+ echo 1 > /sys/kernel/tracing/events/landlock/enable
+
+Enable a specific event::
+
+ echo 1 > /sys/kernel/tracing/events/landlock/landlock_deny_access_fs/enable
+
+Read the trace output::
+
+ cat /sys/kernel/tracing/trace_pipe
+
+Differences from audit records
+==============================
+
+Tracepoints and audit records both log Landlock denials, but differ
+in some field formats:
+
+- **Paths**: Tracepoints use ``d_absolute_path()`` (namespace-independent
+ absolute paths). Audit uses ``d_path()`` (relative to the process's
+ chroot). Tracepoint paths are deterministic regardless of the tracer's
+ mount namespace.
+
+- **Device names**: Tracepoints use numeric ``dev=<major>:<minor>``.
+ Audit uses string ``dev="<s_id>"``. Numeric format is more precise
+ for machine parsing.
+
+- **Denied access field**: The ``deny_access_fs`` and ``deny_access_net``
+ tracepoints use the ``blockers=`` field name (same as audit).
+ Audit uses human-readable access right names (e.g.,
+ ``blockers=fs.read_file``), while tracepoints use a hex bitmask
+ (e.g., ``blockers=0x4``). Scope and ptrace tracepoints omit
+ ``blockers`` because the event name identifies the denial type.
+
+- **Scope target names**: Tracepoints use role-specific field names
+ (``tracee_pid``, ``target_pid``, ``peer_pid``) that reflect the
+ semantic of each event. Audit uses generic names (``opid``, ``ocomm``)
+ because the audit log format is not event-type-specific.
+
+- **Process name**: Scope tracepoints include ``comm=`` in the printk
+ output for stateless consumers. eBPF consumers can read ``comm``
+ directly from the task_struct via BTF. The ``comm`` value is treated
+ as untrusted input (escaped via ``__print_untrusted_str``).
+
+Ruleset versioning
+==================
+
+Syscall events include a ruleset version (``ruleset=<hex_id>.<version>``)
+that tracks the number of rules added to the ruleset. The version is
+incremented on each ``landlock_add_rule()`` call and frozen at
+``landlock_restrict_self()`` time. This enables trace consumers to
+correlate a domain with the exact set of rules it was created from.
+
+eBPF access
+===========
+
+eBPF programs attached via ``BPF_RAW_TRACEPOINT`` can access the
+tracepoint arguments directly through BTF. The arguments include both
+standard kernel objects and Landlock-internal objects:
+
+- Standard kernel objects (``struct task_struct``, ``struct sock``,
+ ``struct path``, ``struct dentry``) can be used with existing BPF
+ helpers.
+- Landlock-internal objects (``struct landlock_domain``,
+ ``struct landlock_ruleset``, ``struct landlock_rule``,
+ ``struct landlock_hierarchy``) can be read via ``BPF_CORE_READ``.
+ Internal struct layouts may change between kernel versions; use CO-RE
+ for field relocation.
+
+All pointer arguments in the tracepoint prototypes are guaranteed
+non-NULL.
+
+Audit filtering equivalence
+============================
+
+Denial events include ``same_exec``, ``log_same_exec``, and
+``log_new_exec`` fields. These allow both stateless (ftrace filter)
+and stateful (eBPF) consumers to replicate the audit subsystem's
+filtering logic::
+
+ # Show only denials that audit would also log:
+ echo 'same_exec==1 && log_same_exec==1 || same_exec==0 && log_new_exec==1' > \
+ /sys/kernel/tracing/events/landlock/landlock_deny_access_fs/filter
+
+Event reference
+===============
+
+.. kernel-doc:: include/trace/events/landlock.h
+ :doc: Landlock trace events
+
+.. kernel-doc:: include/trace/events/landlock.h
+ :internal:
+
+Additional documentation
+========================
+
+* Documentation/userspace-api/landlock.rst
+* Documentation/admin-guide/LSM/landlock.rst
+* Documentation/security/landlock.rst
+* https://landlock.io
diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 338bc4d7cfab..d60e010e042b 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -54,6 +54,7 @@ applications.
events-power
events-nmi
events-msr
+ events-landlock
events-pci
boottime-trace
histogram
diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
index fd8b78c31f2f..e65370212aa1 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: March 2026
+:Date: April 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
@@ -698,8 +698,12 @@ Starting with the Landlock ABI version 7, it is possible to control logging of
Landlock audit events with the ``LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF``,
``LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON``, and
``LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF`` flags passed to
-sys_landlock_restrict_self(). See Documentation/admin-guide/LSM/landlock.rst
-for more details on audit.
+sys_landlock_restrict_self(). These flags control audit record generation.
+Landlock tracepoints are not affected by these flags and always fire when
+enabled, providing an alternative observability channel for debugging and
+monitoring. See :doc:`/admin-guide/LSM/landlock` for more details
+on audit and tracepoints, and :doc:`/trace/events-landlock` for the
+complete trace event reference.

Thread synchronization (ABI < 8)
--------------------------------
@@ -814,6 +818,7 @@ Additional documentation
========================

* Documentation/admin-guide/LSM/landlock.rst
+* Documentation/trace/events-landlock.rst
* Documentation/security/landlock.rst
* https://landlock.io

--
2.53.0