add more information on SCC->PSa level mapping

Author: stlaz

enhancements/authentication/pod-security-admission-autolabeling.md

@@ -193,6 +193,81 @@ Given the need for human interaction with PSa check functions when creating the
 SCC-\>PSa mapping, and the complexity of this task, each OpenShift version should
 always ever consider the "latest" PSa checks.
 
+#### Deriving PSa Level from SCC fields
+
+The SCC fields perform different tasks for fields of a security context:
+
+1. restrict the values to a certain value domain
+2. modify the field value in case the field is unset
+3. combination of the above
+4. restrict the values of an already allowed set (e.g. `AllowedFlexVolumes` only
+   further restricts flex volumes allowed by `Volumes` but upstream makes no
+   difference there)
+
+For the conversion between SCC and PSa levels, we are only interested in fields
+that do 1. and 3. The conversion itself needs to make sure that the values allowed
+by SCCs are a subset of the values allowed by the given PSa level in order for the
+SCC to match the PSa level.
+
+**Caveats and Gotchas Found During SCC Mapping Investigation**
+
+1. Currently, there exists no default SCC supplied with the platform that would
+match any PSa level more restricted than `baseline`
+    - the `restricted` (and any dependent) SCC needs to be modified to match the
+      pod security standards of today:
+        - `RequiredDropCapabilities` should now contain just one value - `ALL`
+        - `AllowPrivilegeEscalation` should now be `false`
+        - `AllowedCapabilities` should include `NET_BIND_SERVICE` which allows
+          the application to use domain privileged ports (numbers lower than 1024)
+2. The SCC to PSa conversion depends on a namespace for the conversion
+    - the `MustRunAs` strategy of `RunAsUser` allows setting an empty range and
+      its evaluation for a given pod retrieves the range from the pod's namespace
+      annotations
+3. The upstream checks can be updated at any time and there is nothing that would
+   allow a simple machine conversion between SCC and PSa levels, this is all human driven
+4. PSa is designed in a way that allows improving security with time if such a need
+   arises
+    - this could mean that our SCCs might slip to less restrictive PSa levels in
+      time
+    - we will need to have a process to tighten SCC permissions that would match
+      the PSa capabilities in this regard
+
+From the above points, we can safely skip 2. as that is just an interesting observation.
+We are evaluating the PSa levels on namespace level anyway when we are checking the
+SCC-related permissions for each of the SA, which are namespaced by nature.
+
+The above changes required **to make 1. work** might cause workloads to break
+if applied directly to the `restricted` SCC. It is impossible to tell which
+workload would break by this step because most of the platform users very likely just
+went with the platform defaults and did not perform further steps in order to
+tighten their workloads to their actual needs. To solve this issue, new
+`*-v2` (e.g. `restricted-v2`, `nonroot-v2`) SCCs with tighter security policies
+should be introduced for the `restricted` SCC and SCCs derived from it. The `restricted`
+SCC will also drop `system:authenticated` from its `Groups` field in favour of adding
+it to the `restricted-v2` SCC.  This effectively causes older clusters to keep the looser
+permissions of `restricted` SCC for their workloads but tighten up the policies
+for workloads of newly created clusters.
+
+In case the changes above still break any of user workloads in upgraded clusters
+(`restricted-v2` has better restrictive score during evaluation and so it's chosen
+first for field defaulting), the users will need to fix their workloads' `securityContext`
+accordingly but they should still be able to since they would still have access to
+the `restricted` SCC. The **documentation should include information** how
+to fix such a workload, and how to remove broad user audience access to the legacy
+`restricted` SCC.
+
+**For 3**, a process needs to be introduce that allows to simply check the changes to
+the `k8s.io/pod-security-admission/policy` folder during k8s.io rebases. The
+repository containing the SCC conversion should include the commit hash of the
+latest checked version of the `k8s.io/pod-security-admission/policy` folder that
+the current mapping corresponds to and developers will need to manually check that
+no significant changes happened to the folder in between the two rebases that would
+cause updates to checks. If there were, the conversion needs to be updated. In both
+cases, the commit hash should be updated to match the latest checked version of the
+folder.
+
+The **process for 4.** should be drawn in a follow-up enhancement.
+
 ### API Extensions
 
 A new `Namespace` label is being introduced - `security.openshift.io/scc.podSecurityLabelSync`.
@@ -203,6 +278,7 @@ section.
 
 ### Risks and Mitigations
 
+#### PSa Label Synchronization Risks
 Turning on the PSa to restricted level enforcing even with the namespace label
 synchronization described in this enforcement brings the risk of breaking direct
 pod application for pods that don't rely on SA permissions, i.e. pods created
@@ -218,6 +294,19 @@ the labels are properly synchronized on their namespace. There is no way to
 mitigate that, the pods will eventually succeed to be created if the given
 service account running them has the correct permissions.
 
+#### Restricted SCC Change Risks
+
+The `restricted` SCC and its variations (e.g. `nonroot`) will need a duplicit `<name>-v2`
+variant that should match the updated pod security standards (see
+[Deriving PSa Level from SCC fields](#deriving-psa-level-from-scc-fields) for
+details of the proposed changes).
+
+The `restricted` SCC changes may cause some workloads to break. Such failures
+should be rather rare as modern restricted workloads should not be susceptible to
+the *setuid* bits and should tolerate dropped capabilities. Nevertheless, the
+documentation should state how to fix such workloads by modifying the `dropCapabilities`
+to match the previous `restricted` SCC.
+
 ## Design Details
 
 ### Open Questions