Message ID | 20250226212911.34502-3-gnoack@google.com (mailing list archive) |
---|---|
State | Handled Elsewhere |
Headers | show |
Series | landlock: Clarify IPC scoping documentation | expand |
Hi Günther! On Wed, Feb 26, 2025 at 10:29:11PM +0100, Günther Noack wrote: > With this ABI version, Landlock can restrict outgoing interactions with > higher-privileged Landlock domains through Abstract Unix Domain sockets and > signals. > > Signed-off-by: Günther Noack <gnoack@google.com> > --- > man/man7/landlock.7 | 69 ++++++++++++++++++++++++++++++++++++++++++++- > 1 file changed, 68 insertions(+), 1 deletion(-) > > diff --git a/man/man7/landlock.7 b/man/man7/landlock.7 > index 11f76b072..30dbac73d 100644 > --- a/man/man7/landlock.7 > +++ b/man/man7/landlock.7 > @@ -248,7 +248,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 > @@ -258,6 +259,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 to isolate a sandboxed process from a set of IPC actions. s/to isolate/isolating/ AFAIU, to be able to use an infinitive with enable/allow you need a direct object in the sentence. If there's no direct object, you need a gerund. > +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. I'm wondering if we should have this as a parenthetical next to the title, like we usually do with "(since Linux X.Y)". Don't do it for now, but please consider it for when you have some time. I'm not saying you should do it though, just that you consider it, and tell me if you agree or not. > +.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. > @@ -334,6 +353,51 @@ 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. > +Each Landlock domain can be explicitly scoped for a set of actions > +by specifying it on a ruleset. > +For example, if a sandboxed process should not be able to > +.BR connect (2) > +to a non-sandboxed process through abstract > +.BR unix (7) > +sockets, > +we can specify such a restriction with > +.BR LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET . > +Moreover, if a sandboxed process should not be able > +to send a signal to a non-sandboxed process, > +we can specify this restriction with > +.BR LANDLOCK_SCOPE_SIGNAL . > +.P > +A sandboxed process can connect to a non-sandboxed process > +when its domain is not scoped. Does "its" refer to the sandboxed one or to the non-snadboxed one? > +If a process's domain is scoped, > +it can only connect to sockets created by processes in the same scope. > +Moreover, > +If a process is scoped to send signal Is this a typo? s/signal/&s/ > to a non-scoped process, Should we use plural here? > +it can only send signals to processes in the same scope. > +.P > +A connected datagram socket behaves like a stream socket > +when its domain is scoped, > +meaning if the domain is scoped after the socket is connected, > +it can still > +.BR send (2) > +data just like a stream socket. > +However, in the same scenario, > +a non-connected datagram socket cannot send data (with > +.BR sendto (2)) > +outside its scope. > +.P > +A process with a scoped domain can inherit a socket > +created by a non-scoped process. > +The process cannot connect to this socket since it has a scoped domain. > +.P > +IPC scoping does not support exceptions, so if a domain is scoped, Please break after the first ',' too. > +no rules can be added to allow access to resources or processes Please break after the second 'to'. > +outside of the scope. > +.\" > .SS Truncating files > The operations covered by > .B LANDLOCK_ACCESS_FS_WRITE_FILE > @@ -413,6 +477,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 >
Hello Alejandro! For context, in this patch set, we have three commits: * 1/3 and 2/3 copy documentation from the kernel side unmodified. * 3/3 revises a section about Landlock's "scoped" restriction features. I thought it would be easier to discuss with the "copy" and "rewrite" parts separate, but actually, as you also noticed, 3/3 does rewrite large chunks of the 2/3 commit along the way, and it is probably not worth correcting much of that wording any more. Would you prefer if I squashed commits 2/3 and 3/3 into one? On Fri, Feb 28, 2025 at 10:23:47PM +0100, Alejandro Colomar wrote: > On Wed, Feb 26, 2025 at 10:29:11PM +0100, Günther Noack wrote: > > With this ABI version, Landlock can restrict outgoing interactions with > > higher-privileged Landlock domains through Abstract Unix Domain sockets and > > signals. > > > > Signed-off-by: Günther Noack <gnoack@google.com> > > --- > > man/man7/landlock.7 | 69 ++++++++++++++++++++++++++++++++++++++++++++- > > 1 file changed, 68 insertions(+), 1 deletion(-) > > > > diff --git a/man/man7/landlock.7 b/man/man7/landlock.7 > > index 11f76b072..30dbac73d 100644 > > --- a/man/man7/landlock.7 > > +++ b/man/man7/landlock.7 > > @@ -248,7 +248,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 > > @@ -258,6 +259,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 to isolate a sandboxed process from a set of IPC actions. > > s/to isolate/isolating/ > > AFAIU, to be able to use an infinitive with enable/allow you need a > direct object in the sentence. If there's no direct object, you need a > gerund. Thanks, this is useful. Changed it to infinitive for now. FWIW, the same phrases exist on the kernel side as well, unfortunately. > > +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. > > I'm wondering if we should have this as a parenthetical next to the > title, like we usually do with "(since Linux X.Y)". Don't do it for > now, but please consider it for when you have some time. I'm not saying > you should do it though, just that you consider it, and tell me if you > agree or not. I added it to my notes for further revisions, I think this would indeed be more appropriate in the man pages. Is it possible to set the paranthetical without bold as well, even in a .SS subsection header? > > +.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. > > @@ -334,6 +353,51 @@ 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. > > +Each Landlock domain can be explicitly scoped for a set of actions > > +by specifying it on a ruleset. > > +For example, if a sandboxed process should not be able to > > +.BR connect (2) > > +to a non-sandboxed process through abstract > > +.BR unix (7) > > +sockets, > > +we can specify such a restriction with > > +.BR LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET . > > +Moreover, if a sandboxed process should not be able > > +to send a signal to a non-sandboxed process, > > +we can specify this restriction with > > +.BR LANDLOCK_SCOPE_SIGNAL . > > +.P > > +A sandboxed process can connect to a non-sandboxed process > > +when its domain is not scoped. > > Does "its" refer to the sandboxed one or to the non-snadboxed one? It refers to the sandboxed process. This correction would be overwritten in the following commit. I don't think it's worth fixing any more. > > +If a process's domain is scoped, > > +it can only connect to sockets created by processes in the same scope. > > +Moreover, > > +If a process is scoped to send signal > > Is this a typo? s/signal/&s/ It is a typo, copied from kernel documentation. Oops. This correction is overwritten in the following commit. > > to a non-scoped process, > > Should we use plural here? This correction is overwritten in the following commit. > > +it can only send signals to processes in the same scope. > > +.P > > +A connected datagram socket behaves like a stream socket > > +when its domain is scoped, > > +meaning if the domain is scoped after the socket is connected, > > +it can still > > +.BR send (2) > > +data just like a stream socket. > > +However, in the same scenario, > > +a non-connected datagram socket cannot send data (with > > +.BR sendto (2)) > > +outside its scope. > > +.P > > +A process with a scoped domain can inherit a socket > > +created by a non-scoped process. > > +The process cannot connect to this socket since it has a scoped domain. > > +.P > > +IPC scoping does not support exceptions, so if a domain is scoped, > > Please break after the first ',' too. Done. > > +no rules can be added to allow access to resources or processes > > Please break after the second 'to'. Done. > > +outside of the scope. Thanks for the review, —Günther
On Mon, Mar 03, 2025 at 05:24:45PM +0100, Günther Noack wrote: > Hello Alejandro! Hello Günther! > For context, in this patch set, we have three commits: > > * 1/3 and 2/3 copy documentation from the kernel side unmodified. > * 3/3 revises a section about Landlock's "scoped" restriction features. > > I thought it would be easier to discuss with the "copy" and "rewrite" parts > separate, but actually, as you also noticed, 3/3 does rewrite large chunks of > the 2/3 commit along the way, and it is probably not worth correcting much of > that wording any more. > > Would you prefer if I squashed commits 2/3 and 3/3 into one? I think so. :-) > > > +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. > > > > I'm wondering if we should have this as a parenthetical next to the > > title, like we usually do with "(since Linux X.Y)". Don't do it for > > now, but please consider it for when you have some time. I'm not saying > > you should do it though, just that you consider it, and tell me if you > > agree or not. > > I added it to my notes for further revisions, > I think this would indeed be more appropriate in the man pages. > > Is it possible to set the paranthetical without bold as well, > even in a .SS subsection header? Yes. It requires you to use \f, but you can. We avoid \f as much as possible, but here it's not possible, and I think I've used it already in a few places. Here's an example of how to do it: alx@debian:~/tmp$ cat roman.man .TH a s d f .SH foo .SS bar \f[R]baz\f[] asdf \f[R] starts a roman (non-bold) text, and \f[] reverts to the previous thing, which in this case is bold. > > > +outside of the scope. > > Thanks for the review, > —Günther :-) Have a lovely night! Alex
diff --git a/man/man7/landlock.7 b/man/man7/landlock.7 index 11f76b072..30dbac73d 100644 --- a/man/man7/landlock.7 +++ b/man/man7/landlock.7 @@ -248,7 +248,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 @@ -258,6 +259,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 to isolate 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. @@ -334,6 +353,51 @@ 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. +Each Landlock domain can be explicitly scoped for a set of actions +by specifying it on a ruleset. +For example, if a sandboxed process should not be able to +.BR connect (2) +to a non-sandboxed process through abstract +.BR unix (7) +sockets, +we can specify such a restriction with +.BR LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET . +Moreover, if a sandboxed process should not be able +to send a signal to a non-sandboxed process, +we can specify this restriction with +.BR LANDLOCK_SCOPE_SIGNAL . +.P +A sandboxed process can connect to a non-sandboxed process +when its domain is not scoped. +If a process's domain is scoped, +it can only connect to sockets created by processes in the same scope. +Moreover, +If a process is scoped to send signal to a non-scoped process, +it can only send signals to processes in the same scope. +.P +A connected datagram socket behaves like a stream socket +when its domain is scoped, +meaning if the domain is scoped after the socket is connected, +it can still +.BR send (2) +data just like a stream socket. +However, in the same scenario, +a non-connected datagram socket cannot send data (with +.BR sendto (2)) +outside its scope. +.P +A process with a scoped domain can inherit a socket +created by a non-scoped process. +The process cannot connect to this socket since it has a scoped domain. +.P +IPC scoping does not support exceptions, so if a domain is scoped, +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 @@ -413,6 +477,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
With this ABI version, Landlock can restrict outgoing interactions with higher-privileged Landlock domains through Abstract Unix Domain sockets and signals. Signed-off-by: Günther Noack <gnoack@google.com> --- man/man7/landlock.7 | 69 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 68 insertions(+), 1 deletion(-)