Merge pull request #562 from viccuad/from-self-assessment

Expand security-hardening/ subsection, reorder howtos/ section

Author: viccuad

docs/howtos/airgap/01-requirements.md

@@ -1,7 +1,7 @@
 ---
 sidebar_label: Requirements
-title: Requirements for a Kubewarden air gap installation
-description: Requirements for a Kubewarden air gap installation.
+title: Requirements for installing Kubewarden in an air gapped environment
+description: Requirements for installing Kubewarden in an air gapped installation.
 keywords: [kubewarden, kubernetes, air gap installation]
 doc-persona: [kubewarden-operator, kubewarden-integrator]
 doc-type: [howto]

docs/howtos/airgap/02-install.md

@@ -12,8 +12,8 @@ doc-topic: [operator-manual, airgap, installation]
   <link rel="canonical" href="https://docs.kubewarden.io/howtos/airgap/install"/>
 </head>
 
-This guide shows you how to install Kubewarden in air-gapped environments.
-For an air-gapped installation of Kubewarden,
+This guide shows you how to install Kubewarden in air gapped environments.
+For an air gapped installation of Kubewarden,
 you need a private Open Container Initiative (OCI) registry accessible by your Kubernetes cluster.
 Kubewarden Policies are WebAssembly modules,
 therefore you can store them in an OCI-compliant registry as OCI artifacts.
@@ -142,7 +142,7 @@ helm install --wait -n kubewarden \
 :::caution
 To use the Policy Reported sub-chart available in the
 `kubewarden-controller` chart you need to define other values specific for the
-sub-chart in an air-gapped environment.
+sub-chart in an air gapped environment.
 See an example below:
 
 ```shell

docs/howtos/airgap/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "Airgap",
+  "label": "Air gap",
   "position": 100,
   "collapsed": true
 }

docs/howtos/application-collection/_category_.json

@@ -1,5 +1,5 @@
 {
   "label": "Rancher Application Collection",
-  "position": 120,
+  "position": 140,
   "collapsed": true
 }

docs/howtos/argocd-installation.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: ArgoCD Installation
-sidebar_position: 35
+sidebar_position: 90
 title: ArgoCD Installation
 description: How to install Kubewarden with ArgoCD
 keywords: [kubewarden, gitops, argocd]

docs/howtos/audit-scanner.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Audit Scanner
-sidebar_position: 70
+sidebar_position: 21
 title: Audit Scanner
 description: How-to install and use Audit Scanner.
 keywords: [kubewarden, kubernetes, audit scanner]

docs/howtos/pod-security-admission-with-kubewarden.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Pod Security Admission
-sidebar_position: 30
+sidebar_position: 42
 title: Using Pod Security Admission with Kubewarden
 description: Using Pod Security Admission with Kubewarden, since the Kubernetes 1.25 release.
 keywords: [kubewarden, pod security admission, pod security policy, kubernetes]

docs/howtos/policies.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Configuring policies
-sidebar_position: 90
+sidebar_position: 30
 title: Configuring policies
 description: Dependency matrix of Kubewarden.
 keywords: [policies, ClusterAdmissionPolicies, AdmissionPolicies, configuration, namespaces]

docs/howtos/policy-groups.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Policy Groups
-sidebar_position: 36
+sidebar_position: 33
 title: How to use policy groups
 description: How to use Kubewarden policy groups
 keywords: [kubewarden, policy groups, clusteradmissionpolicygroup, admissionpolicygroup]

docs/howtos/policy-servers/_category_.json

@@ -1,5 +1,5 @@
 {
   "label": "Configuring Policy Servers",
-  "position": 80,
+  "position": 32,
   "collapsed": true
 }

docs/howtos/production-deployments.md

@@ -2,6 +2,7 @@
 sidebar_label: Production deployments
 title: Configuring Kubewarden stack for production
 description: Configuring Kubewarden stack for production
+sidebar_position: 20
 keywords:
   [
     kubewarden,

docs/howtos/psp-migration.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: PSP migration
-sidebar_position: 20
+sidebar_position: 40
 title: PodSecurityPolicy migration
 description: Discusses PSP migration to Kubewarden policies after Kubernetes v1.25.
 keywords: [kubewarden, kubernetes, appvia, psp, pod security policy]

docs/howtos/security-hardening/_category_.json

@@ -1,5 +1,5 @@
 {
   "label": "Security",
-  "position": 100,
+  "position": 90,
   "collapsed": true
 }

docs/howtos/secure-supply-chain.md docs/howtos/security-hardening/secure-supply-chain.md

@@ -295,7 +295,7 @@ The following checks were performed on each of these signatures:
 ## Configuring the policy server to check policy signatures
 
 You can configure Kubewarden with a `ConfigMap` to only run trusted policies.
-The `ConfigMap` structure described in [Signature Config Reference](../reference/verification-config.md#signature-configuration-reference).
+The `ConfigMap` structure described in [Signature Config Reference](../../reference/verification-config.md#signature-configuration-reference).
 It's used to verify a policy using `kwctl`.
 The `ConfigMap` should define allowable configurations under the `verification-config` field.
 

docs/howtos/security-hardening/security-hardening.md

@@ -0,0 +1,81 @@
+---
+sidebar_label: Security hardening
+sidebar_position: 50
+title: Security hardening
+description: Harden the Kubewarden installation
+keywords: [kubewarden, kubernetes, security]
+doc-persona: [kubewarden-operator, kubewarden-integrator]
+doc-type: [howto]
+doc-topic: [operator-manual, security]
+---
+
+Kubewarden strives to be secure with little configuration.
+In this section and its subpages you can find hardening tips (with their
+trade-offs) to secure Kubewarden itself.
+
+Please refer to our [threat model](../reference/threat-model) for more information.
+
+### `kubewarden-defaults` Helm chart
+
+Operators can obtain a secure deployment by installing all the
+Kubewarden Helm charts. It's recommended to install the
+`kubewarden-defaults` Helm chart and enable its recommended policies with:
+
+```console
+helm install --wait -n kubewarden kubewarden-defaults kubewarden/kubewarden-defaults \
+  --set recommendedPolicies.enabled=True \
+  --set recommendedPolicies.defaultPolicyMode=protect
+```
+
+This provides a default PolicyServer and default policies, in protect mode, to
+ensure the Kubewarden stack is safe from other workloads.
+
+### Verifying Kubewarden artifacts
+
+See the [Verifying Kubewarden](../tutorials/verifying-kubewarden) tutorial.
+
+### RBAC
+
+Kubewarden describes RBAC configurations in different
+_Explanations_ sections. Users can fine-tune the needed permissions for the
+[Audit Scanner](../explanations/audit-scanner#permissions-and-serviceaccounts)
+feature, as well as [per Policy Server](../explanations/context-aware-policies)
+Service Account for the context-aware feature.
+
+The view all Roles:
+
+```console
+kubectl get clusterroles,roles -A | grep kubewarden
+```
+
+### Per-policy permissions
+
+For context-aware policies, operators specify fine-grained permissions per
+policy under its `spec.contectAwareResources`, and those work in conjuction
+with the Service Account configured for the Policy Server where the policy
+runs.
+
+### Workload coverage
+
+By default, Kubewarden excludes specific Namespaces from Kubewarden coverage. This is
+done to simplify first-time use and interoperability with other workloads.
+
+Security-conscious operators can tune these Namespaces list via the
+`.global.skipNamespaces` value for both the `kubewarden-controller` and
+`kubewarden-defaults` Helm charts.
+
+### SecurityContexts
+
+Starting from 1.23, Kubewarden's stack is able to run in a Namespace
+where the [restricted
+Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/#restricted)
+are enforced, with current Pod hardening best practices.
+
+The `kubewarden-controller` Helm chart configures the SecurityContexts and
+exposes them in its `values.yaml`.
+
+The `kubewarden-defaults` Helm chart allows for configuing the default Policy
+Server `.spec.securityContexts` under `.Values.policyServer.securityContexts`.
+
+For Policy Servers managed by operators, you can configure them via their
+[`spec.securityContexts`](https://docs.kubewarden.io/reference/CRDs#policyserversecurity).

docs/howtos/security-hardening/webhook-mtls.md

@@ -15,6 +15,9 @@ doc-topic: [operator-manual, security]
 This guide shows you how to enable mutual TLS (mTLS) for all the webhooks used by the Kubewarden
 stack when using [k3s](https://k3s.io/) as your Kubernetes distribution.
 
+For more information on how to harden the webhooks, see the [reference
+page](../../reference/security-hardening/webhooks-hardening).
+
 ## Prerequisites
 
 Before installing k3s, you need to create a certificate authority (CA) and a client certificate to use to secure the communication between the Kubewarden webhooks and the Kubernetes API server.

docs/howtos/ui-extension/01-install.md

@@ -26,7 +26,7 @@ however,
 the Kubewarden controller is installed through the Rancher UI as a cluster scoped resource.
 
 :::note
-For air-gapped installations, follow [these steps](../airgap/02-install.md).
+For air gapped installations, follow [these steps](../airgap/02-install.md).
 :::
 
 Within the Extensions page,
@@ -101,7 +101,7 @@ As Kubewarden is a Rancher Official Extension,
 the Rancher team provides a mechanism to automatically generate an Extension Catalog Image.
 This is added to the `rancher-images.txt` file when
 [installing Rancher Manager](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images#1-find-the-required-assets-for-your-rancher-version)
-for air-gapped instances.
+for air gapped instances.
 
 Once this image has been mirrored to a registry accessible to your air-gapped cluster,
 you can import the image within the Rancher UI.

docs/howtos/ui-extension/_category_.json

@@ -1,5 +1,5 @@
 {
   "label": "Rancher UI extension",
-  "position": 110,
+  "position": 130,
   "collapsed": true
 }

docs/howtos/vap-migration.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: ValidatingAdmissionPolicy migration
-sidebar_position: 35
+sidebar_position: 41
 title: ValidatingAdmissionPolicy migration
 description: Discusses how to migrate from Kubernetes VAP policies to Kubewarden.
 keywords: [kubewarden, kubernetes, cel, vap, validatingadmissionpolicy]

docs/howtos/workarounds/_category_.json

@@ -1,5 +1,5 @@
 {
   "label": "Workarounds",
-  "position": 15,
+  "position": 140,
   "collapsed": true
 }

docs/reference/spec/host-capabilities/02-signature-verifier-policies.md

@@ -26,7 +26,7 @@ This allows implementing a "Secure Supply Chain" for your cluster.
 Part of the function of the secure supply chain is to ensure that all container images running in the cluster are signed and verified.
 This proves that they come from their stated authors, with no tampering.
 For further reading, check the docs on
-[how we implement a Secure Supply Chain for the policies themselves](../../../howtos/secure-supply-chain.md).
+[how we implement a Secure Supply Chain for the policies themselves](../../../howtos/security-hardening/secure-supply-chain.md).
 
 Sigstore signatures are stored inside of container registries,
 next to the OCI object being signed.

docs/reference/threat-model.md

@@ -302,6 +302,6 @@ For example, by:
    The Kubernetes Administrator must verify the Kubewarden images, its dependencies' images, and charts
    out of the Kubernetes cluster, in a trusted environment.
    You can do this with `cosign`, for example.
-   Incidentally, this is part of the implementation needed for air-gapped installations.
+   Incidentally, this is part of the implementation needed for air gapped installations.
 2. Use signed Helm charts, and verified digests instead of tags for Kubewarden images in those Helm charts.
    This doesn't secure dependencies though.

docs/reference/verification-config.md

@@ -20,7 +20,7 @@ The verification-config format is used by:
 - `policy-server` to verify policy modules provenance
 - `verify-image-signatures` policy to verify cluster images provenance
 
-See [secure supply chain](../howtos/secure-supply-chain.md) for more info.
+See [secure supply chain](../howtos/security-hardening/secure-supply-chain.md) for more info.
 
 ## Format