[PATCH man v3 1/2] landlock.7: Copy introductory description of Landlock rules

[PATCH man v3 1/2] landlock.7: Copy introductory description of Landlock rules

[Günther Noack]

Copy over the existing wording from kernel documentation, as it was introduced
in Linux commit 51442e8d64bc ("landlock: Document network support").  Landlock
rules are not only about the filesystem any more and the new wording is more
appropriate.

Signed-off-by: Günther Noack <gnoack@google.com>
---
 man/man7/landlock.7 | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index c6b7272ea..7b7a797ad 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -39,13 +39,23 @@ the running kernel must support Landlock and
 it must be enabled at boot time.
 .\"
 .SS Landlock rules
-A Landlock rule describes an action on an object.
-An object is currently a file hierarchy,
-and the related filesystem actions are defined with access rights (see
-.BR landlock_add_rule (2)).
+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.
+.P
+The two existing types of rules are:
+.TP
+.B Filesystem rules
+For these rules, the object is a file hierarchy,
+and the related filesystem actions are defined with
+.IR "filesystem access rights" .
+.TP
+.BR "Network rules" " (since ABI v4)"
+For these rules, the object is a TCP port,
+and the related actions are defined with
+.IR "network access rights" .
 .\"
 .SS Filesystem actions
 These flags enable to restrict a sandboxed process to a
-- 
2.48.1.711.g2feabab25a-goog

[PATCH man v3 2/2] landlock.7: Add IPC scoping documentation in line with kernel side

[Günther Noack]

* Move over documentation for ABI version 6 (IPC scoping features)
* Clarify terminology
* Stop mixing the unix(7) and signal(7) aspects in the explanation.

With this ABI version, Landlock can restrict outgoing interactions with
higher-privileged Landlock domains through Abstract Unix Domain sockets and
signals.

Terminology:

* The *IPC Scope* of a Landlock domain is that Landlock domain and its
  nested domains.

* An *operation* (e.g., signaling, connecting to abstract UDS) is said to
  be *scoped within a domain* when the flag for that operation was set at
  ruleset creation time.  This means that for the purpose of this
  operation, only processes within the domain's IPC scope are reachable.

Link: https://lore.kernel.org/all/20250303194510.135506-4-gnoack@google.com/
Signed-off-by: Günther Noack <gnoack@google.com>
---
 man/man7/landlock.7 | 65 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 64 insertions(+), 1 deletion(-)

diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index 7b7a797ad..aa383860c 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -246,7 +246,8 @@ This access right is available since the fifth version of the Landlock ABI.
 .SS Network flags
 These flags enable to restrict a sandboxed process
 to a set of network actions.
-This is supported since the Landlock ABI version 4.
+.P
+This is supported since Landlock ABI version 4.
 .P
 The following access rights apply to TCP port numbers:
 .TP
@@ -256,6 +257,24 @@ Bind a TCP socket to a local port.
 .B LANDLOCK_ACCESS_NET_CONNECT_TCP
 Connect an active TCP socket to a remote port.
 .\"
+.SS Scope flags
+These flags enable isolating a sandboxed process from a set of IPC actions.
+Setting a flag for a ruleset will isolate the Landlock domain
+to forbid connections to resources outside the domain.
+.P
+This is supported since Landlock ABI version 6.
+.P
+The following scopes exist:
+.TP
+.B LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
+Restrict a sandboxed process from connecting to an abstract UNIX socket
+created by a process outside the related Landlock domain
+(e.g., a parent domain or a non-sandboxed process).
+.TP
+.B LANDLOCK_SCOPE_SIGNAL
+Restrict a sandboxed process from sending a signal
+to another process outside the domain.
+.\"
 .SS Layers of file path access rights
 Each time a thread enforces a ruleset on itself,
 it updates its Landlock domain with a new layer of policy.
@@ -332,6 +351,47 @@ and related syscalls on a target process,
 a sandboxed process should have a subset of the target process rules,
 which means the tracee must be in a sub-domain of the tracer.
 .\"
+.SS IPC scoping
+Similar to the implicit
+.BR "Ptrace restrictions" ,
+we may want to further restrict interactions between sandboxes.
+Therefore, at ruleset creation time,
+each Landlock domain can restrict the scope for certain operations,
+so that these operations can only reach out to processes
+within the same Landlock domain or in a nested Landlock domain (the "scope").
+.P
+The operations which can be scoped are:
+.TP
+.B LANDLOCK_SCOPE_SIGNAL
+This limits the sending of signals to target processes
+which run within the same or a nested Landlock domain.
+.TP
+.B LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
+This limits the set of abstract
+.BR unix (7)
+sockets to which we can
+.BR connect (2)
+to socket addresses which were created
+by a process in the same or a nested Landlock domain.
+.IP
+A
+.BR sendto (2)
+on a non-connected datagram socket is treated as if it were doing an implicit
+.BR connect (2)
+and will be blocked if the remote end does not stem
+from the same or a nested Landlock domain.
+.IP
+A
+.BR sendto (2)
+on a socket which was previously connected will not be restricted.
+This works for both datagram and stream sockets.
+.P
+IPC scoping does not support exceptions via
+.BR 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.
+.\"
 .SS Truncating files
 The operations covered by
 .B LANDLOCK_ACCESS_FS_WRITE_FILE
@@ -411,6 +471,9 @@ _	_	_
 \^	\^	LANDLOCK_ACCESS_NET_CONNECT_TCP
 _	_	_
 5	6.10	LANDLOCK_ACCESS_FS_IOCTL_DEV
+_	_	_
+6	6.12	LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET
+\^	\^	LANDLOCK_SCOPE_SIGNAL
 .TE
 .P
 Users should use the Landlock ABI version rather than the kernel version
-- 
2.48.1.711.g2feabab25a-goog

Re: [PATCH man v3 1/2] landlock.7: Copy introductory description of Landlock rules

[Alejandro Colomar]

Hi!

On Mon, Mar 03, 2025 at 08:50:29PM +0100, Günther Noack wrote:
> +.P
> +The two existing types of rules are:

BTW, I didn't want to send back the patch for another revision, so I
applied it as is, but this sentence is likely to get outdated at some
point.

I would have removed the "two" from it.  But we'll be able to remove it
when/if it changes.  I'm just mentioning this for future documentation.


Cheers,
Alex

> +.TP
> +.B Filesystem rules
> +For these rules, the object is a file hierarchy,
> +and the related filesystem actions are defined with
> +.IR "filesystem access rights" .
> +.TP
> +.BR "Network rules" " (since ABI v4)"
> +For these rules, the object is a TCP port,
> +and the related actions are defined with
> +.IR "network access rights" .
>  .\"
>  .SS Filesystem actions
>  These flags enable to restrict a sandboxed process to a
> -- 
> 2.48.1.711.g2feabab25a-goog
> 
> 

-- 
<https://www.alejandro-colomar.es/>