From e64bd1ccdf3978eed0571b20131ab39e8612a835 Mon Sep 17 00:00:00 2001 From: John Johansen Date: Sat, 8 Mar 2025 23:05:59 -0800 Subject: [PATCH] binutils: aa-exec: add basic documentation on stacking and namespaces The aa-exec man page makes reference to aa-stack(8) and aa-namespace(8) manpages that don't exist. For now just remove those references and add a short blurb on using aa-exec with stacking and namespaces. Proper full manpages for stacking and namespaces need to be added but that is beyound the scope of this fix. Bug: https://gitlab.com/apparmor/apparmor/-/issues/496 Signed-off-by: John Johansen --- binutils/aa-exec.pod | 105 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 104 insertions(+), 1 deletion(-) diff --git a/binutils/aa-exec.pod b/binutils/aa-exec.pod index d432c7851..ff59c632c 100644 --- a/binutils/aa-exec.pod +++ b/binutils/aa-exec.pod @@ -80,6 +80,109 @@ aa-exec. =back +=head1 RESTRICTIONS + +aa-exec uses I to change application confinement. +The use of I may be restricted by policy in ways +that will cause failure or results different than expected. + +Even when using I from unconfined restrictions in policy can +causes failure or the confinement entered to be different than requested + +See the unpriviled unconfined restriction documentation for more detail. +https://gitlab.com/apparmor/apparmor/-/wikis/unprivileged_unconfined_restriction + +=head1 STACKING + +aa-exec can be used to setup a stack of profiles as confinement. When an +application is confined by a stack, all profiles in the stack are checked +as if they were the profile confining the application. The resulting +mediation is the intersection of what is allowed by each profile in the +stack. + +The profiles in a stack are treated independently. Each profile can have +its own flags and profile transitions. During an exec each profile gets +to specify its transition and the results brought together to form a +new canonicalized stack. + +The profile separator indicating a stack is the character sequence I. +Thus a stack can be expressed using + +=over 4 + + $ aa-exec -p "unconfined//&firefox" -- bash + $ ps -Z + LABEL PID TTY TIME CMD + unconfined 30714 pts/12 00:00:00 bash + firefox//&unconfined (unconfined) 31160 pts/12 00:00:00 bash + firefox//&unconfined (unconfined) 31171 pts/12 00:00:00 ps + +=back + +=head1 NAMESPACES + +aa-exec can be used to enter confinement in another policy namespace +if the policy namespaces exists, is visible, and the profile exists in +the namespace. Note applications launched within the namespace will +not be able to exit the namespace, and may be restricted by additional +confinement around namespacing. Files and resources visible to the +parent that launches the application may not be visible in the policy +namespace resultinging access denials. + +To enter a policy namespace the profile is prefixed with the namespace's +name, using a I<:> prefix and suffix. + +Eg. + +=over 4 + + $ aa-exec -p :ex1:unconfined -- bash + $ ps -Z + LABEL PID TTY TIME CMD + - 30714 pts/12 00:00:00 bash + unconfined 34372 pts/12 00:00:00 bash + unconfined 34379 pts/12 00:00:00 ps + +=back + +Confinement of processes outside of the namespace may not be visible +in which case the confinement will be represented with a -. If policy +is stacked only part of the confinement might be visible. However +confinement is usually fully visible from the parent policy namespace. + +Eg. the confinement of the child can be queried in the parent to see + +=over 4 + + $ ps -Z 34372 + LABEL PID TTY STAT TIME COMMAND + :ex1:unconfined 34372 pts/12 S+ 0:00 bash + +=back + +And in the case of stacking with namespaces + +=over 4 + + $ aa-exec -p "unconfined//&:ex1:unconfined" -- bash + $ ps -Z + LABEL PID TTY TIME CMD + - 30714 pts/12 00:00:00 bash + unconfined 36298 pts/12 00:00:00 bash + unconfined 36305 pts/12 00:00:00 ps + +=back + +while from the parent namespace the full confinement can be seen + +=over 4 + + $ ps -Z 36298 + LABEL PID TTY STAT TIME COMMAND + unconfined//&:ex1:unconfined 36298 pts/12 S+ 0:00 bash + +=back + =head1 BUGS If you find any bugs, please report them at @@ -87,7 +190,7 @@ L =head1 SEE ALSO -aa-stack(8), aa-namespace(8), apparmor(7), apparmor.d(5), aa_change_profile(3), +apparmor(7), apparmor.d(5), aa_change_profile(3), aa_change_onexec(3) and L. =cut