Update unprivileged_userns_restriction

unprivileged_userns_restriction.md

@@ -1,6 +1,6 @@
 # Introduction
 
-Unprivileged user namespaces are a feature of the kernel that can be used to replace many of the uses of setuid and setguid programs, and also allow for applications to create more secure sandboxes. 
+Unprivileged user namespaces are a feature of the kernel that can be used to replace many of the uses of setuid and setguid programs, and also allow for applications to create more secure sandboxes.
 
 However while unprivileged user namespaces have been beneficial by reducing the need for setuid and setguid processes they expose kernel interfaces that are normally restricted to processes with privileged capabilities (root) to use by unprivileged users. Exposing more kernel interfaces than necessary to a process introduces additional security risks, and unfortunately unprivileged user namespaces are now broadly used as a step in several privilege escalation exploit chains. Basically even if unprivileged user namespaces are bug free, as long as any privileged kernel interface or combination of interfaces has a bug an unprivileged user can try to exploit that bug.
 
@@ -17,11 +17,9 @@ Because of this several distro kernels carry a patch that allows for a [sysctl t
 
 With introduction of restricted unprivileged user namespaces AppArmor can be used to selectively allow and disallow unprivileged user namespaces. AppArmor policy is used to selectively control access to unprivileged user namespaces on a per applications basis.
 
-
-
 # Discovering if your kernel supports restrictions on unprivileged user namespaces
 
-There are two ways to determine if your Kernel has support for restricting unprivileged user namespaces 
+There are two ways to determine if your Kernel has support for restricting unprivileged user namespaces
 
 ## Examine /proc
 
@@ -42,8 +40,7 @@ The presence of AppArmor's ability to control user namespaces can also be found
     userns_create
 ```
 
-If the value ```userns_create``` is present AppArmor can control the creation of namespaces in policy and the use of unprivileged user namespaces by unconfined.
-
+If the value `userns_create` is present AppArmor can control the creation of namespaces in policy and the use of unprivileged user namespaces by unconfined.
 
 # Audit message
 
@@ -62,13 +59,22 @@ The /proc file that can be introspected to determine if AppArmor restrictions on
     0
 ```
 
-If the returned value is ```0``` then restrictions on unprivileged user namespace are disabled, if a value of ```1``` is reported the restriction is enabled.
-
+If the returned value is `0` then restrictions on unprivileged user namespace are disabled, if a value of `1` is reported the restriction is enabled.
 
 # Controlling unprivileged user namespace restrictions via sysctl
 
 Restrictions on unprivileged user namespaces can be controlled using the sysctl command. The changes made by the sysctl command will remain even after booting
 
+AppArmor offers three sysctls for controlling userns behavior.
+
+* kernel.apparmor_restrict_unprivileged_userns
+* kernel.apparmor_restrict_unprivileged_userns_force     (6.2+)
+* kernel.apparmor_restrict_unprivileged_userns_complain   (6.2+)
+
+## kernel.apparmor_restrict_unprivileged_userns
+
+This sysctl allows enabling or disabling all apparmor mediation/restrictions around unprivileged user namespaces. If set to off the other sysctls are ignored, rules in policy are ignored etc.
+
 To disable
 
 ```
@@ -81,16 +87,28 @@ To enabled
     sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=1
 ```
 
+## kernel.apparmor_restrict_unprivileged_userns_force
+
+This sysctl is used to control policy abi compatibility which is an AppArmor feature where older policy is supported at its declared ABI/feature set level. This is used to prevent confined applications from breaking when a new kernel is used without the policy being updated. However this also means confined applications can by-pass the user namespace restriction if they are using policy that has not been updated to the new ABI.
+
+This sysctl allows forcing the userns restrictions on regardless of the policies declared ABI. When enabled all confined applications will have the user namespace mediation enforced; old policy missing the appropriate rule will deny access to use namespace creation.
+
+## kernel.apparmor_restrict_unprivileged_userns_complain
+
+This sysctl is used to control complain mode of user namespace mediation for unconfined processes. It allows for the restriction to be globally enabled, but only log uses, instead of denying them.
+
 ## Controlling the restrictions temporarily
 
 Changing the restrictions on unprivileged user namespaces can be done temporarily by writing, with administrative privileges, to the /proc control file
 
 To Disable
+
 ```
     $ echo 0 > /proc/sys/kernel/apparmor_restrict_unprivileged_userns
 ```
 
 To Enable
+
 ```
     $ echo 1 > /proc/sys/kernel/apparmor_restrict_unprivileged_userns
 ```
@@ -110,13 +128,14 @@ Confined processes whether privileged or unprivileged are by default also not al
 The user namespace control respects policy ABIs. This means confined applications with ABIs that did not support control of user namespaces will function unchanged on kernels that support restrictions on user namespaces. The net effect is these profiles can be used to by-pass user namespace controls. This behavior can be overriden by using ABI pinning.
 
 ### AppArmor 2.x
-To pin the ABI of AppArmor 2.x policy add the following rule to the ```/etc/apparmor/parser.conf``` file.
+
+To pin the ABI of AppArmor 2.x policy add the following rule to the `/etc/apparmor/parser.conf` file.
 
 ```
 policy-features=kernel
 ```
 
-this will force AppArmor 2.x policy to use the current kernel's ABI. Note that this may cause failures beyond controlling user namespace. The ```kernel``` keyword can be replaced by a path to any appropriate ABI file, resulting in forcing that particular ABI to be used.
+this will force AppArmor 2.x policy to use the current kernel's ABI. Note that this may cause failures beyond controlling user namespace. The `kernel` keyword can be replaced by a path to any appropriate ABI file, resulting in forcing that particular ABI to be used.
 
 ### AppArmor 3.x
 
@@ -140,14 +159,13 @@ can be changed to (assuming the file is available)
 
 #### Pin an override ABI
 
-ABI rules can be overridden using a special override pin similar to the pin used with AppArmor 2.x policy. To do this the following rule is added to the ```/etc/apparmor/parser.conf``` file.
+ABI rules can be overridden using a special override pin similar to the pin used with AppArmor 2.x policy. To do this the following rule is added to the `/etc/apparmor/parser.conf` file.
 
 ```
 override-policy-abi=kernel
 ```
 
-this will force AppArmor 2.x and AppArmor 3.x policy to use the current kernel's ABI. Note that this may cause failures beyond controlling user namespace. The ```kernel``` keyword can be replaced by a path to any appropriate ABI file, resulting in forcing that particular ABI to be used.
-
+this will force AppArmor 2.x and AppArmor 3.x policy to use the current kernel's ABI. Note that this may cause failures beyond controlling user namespace. The `kernel` keyword can be replaced by a path to any appropriate ABI file, resulting in forcing that particular ABI to be used.
 
 #### Update/Replace the ABI file
 
@@ -155,14 +173,13 @@ This method is NOT recommended, as policy references to such a modified ABI file
 
 # Disabling unprivileged user namespaces
 
-Several distro kernels (but not all) have the ability to disable unprivileged user namespaces for the entire system via the ```unprivileged_userns_clone``` sysctl. If a kernel has this ability the file ```/proc/sys/kernel/unprivileged_userns_clone``` will be present. The current state of whether unprivileged user namespaces are allowed can be found by doing
+Several distro kernels (but not all) have the ability to disable unprivileged user namespaces for the entire system via the `unprivileged_userns_clone` sysctl. If a kernel has this ability the file `/proc/sys/kernel/unprivileged_userns_clone` will be present. The current state of whether unprivileged user namespaces are allowed can be found by doing
 
 ```
    $ cat /proc/sys/kernel/unprivileged_userns_clone
 ```
 
-Where a value of ```0``` means disabled and a value of ```1``` means enabled.
-
+Where a value of `0` means disabled and a value of `1` means enabled.
 
 Unprivileged user namespaces can be disabled by using the command
 
@@ -170,10 +187,8 @@ Unprivileged user namespaces can be disabled by using the command
     sudo sysctl -w kernel.unprivileged_userns_clone=0
 ```
 
-
 # Kernel Build kconfig options
 
-User namespaces can be configured via the ```CONFIG_USER_NS``` config symbol.
+User namespaces can be configured via the `CONFIG_USER_NS` config symbol.
 
-
-If user namespaces are enabled then the config symbol ```SECURITY_APPARMOR_RESTRICT_USERNS``` allows controlling if AppArmor enforces restrictions on unprivileged user namespaces by default. If ```N``` apparmor's unprivileged user namespace restrictions will be disabled by default, where```Y``` will enable restrictions by default. The default value can be overriden by setting sysctl at runtime.
+If user namespaces are enabled then the config symbol `SECURITY_APPARMOR_RESTRICT_USERNS` allows controlling if AppArmor enforces restrictions on unprivileged user namespaces by default. If `N` apparmor's unprivileged user namespace restrictions will be disabled by default, where`Y` will enable restrictions by default. The default value can be overriden by setting sysctl at runtime.