feat: audit scanner docs.

docs/explanations/audit-scanner/audit-scanner.md

@@ -0,0 +1,89 @@
+---
+sidebar_label: "What's it?"
+title: "Audit Scanner"
+---
+
+# Audit Scanner
+
+:::note
+The Audit Scanner feature is available starting from Kubewarden 1.7.0 release
+:::
+
+A component, called `audit-scanner`, constantly checks the
+resources declared in the cluster, flagging the ones that do not adhere with
+the deployed Kubewarden policies.
+
+Policies evolve over time: new ones are deployed and the existing ones can be
+updated, both in terms of version and configuration settings. This can lead to
+situations where resources already inside of the cluster are no longer
+compliant. The audit scanner feature provides Kubernetes administrators with a
+tool to consistently verify the compliance state of their clusters.
+
+To illustrate the usage of the audit scanner in Kubewarden, let's consider the
+following scenario.
+
+Assume Bob is deploying a Wordpress Pod inside of the cluster. He's new to
+Kubernetes, hence he makes a mistake and deploys this Pod running as a
+privileged container. Since there's no policy preventing that, the Pod is
+successfully created inside of the cluster.
+
+Some days later, Alice, the Kubernetes administrator, enforces a Kubewarden
+policy that prohibits the creation of privileged containers. The Pod deployed
+by Bob keeps running inside of the cluster.
+
+However, thanks to the report generated by the audit scanner, Alice can
+quickly identify all the workloads that are violating her policies; including
+the Wordpress Pod created by Bob.
+
+To make that happens, audit scanner get all resources that should be audited,
+build a fake admission request with the resource's data and send it to the
+policy server in a different endpoint exclusively used to audit requests.
+However, for the policy evaluating the request, there is no differences from a
+real or an audit request. The data received are the same. Furthermore, this
+policy server endpoint is instrumented to collect data of the evaluation as
+the one used to validate request from the control plane. Therefore, users can
+use their monitoring tools analyze this data as well.
+
+## Enable audit scanner
+
+As stated before, the audit scanner feature can be enabled starting from the
+Kubewarden 1.7.0 release.
+
+Detailed installation instructions can be found
+[here](../howtos/audit-scanner).
+
+## Policies
+
+By default, every policy is evaluated by the audit scanner. Operators that want
+to skip a policy evaluation in the Audit scanner should set the
+`spec.backgroundAudit` field to `false` inside of the policy definition.
+Furthermore, policies in Kubewarden now support two optional annotations:
+`io.kubewarden.policy.severity` and `io.kubewarden.policy.category`:
+
+- The `io.kubewarden.policy.severity` annotation allows you to specify the
+  severity level of the policy violation, such as `critical`, `high`, `medium`,
+  `low` or `info`.
+- The `io.kubewarden.policy.category` annotation allows you to categorize the
+  policy based on a specific domain or purpose, such as `PSP`, `compliance`, or
+  `performance`.
+
+See the policy authors [docs](../writing-policies/index.md) for more info.
+
+## Permissions and ServiceAccounts
+
+The audit scanner in Kubernetes requires specific RBAC configurations to be
+able to scan Kubernetes resources and save the results. A correct default Service
+Account with those permissions is created during the installation. But the user
+can provide their own ServiceAccount to fine tune access to resources.
+
+The default audit scanner `ServiceAccount` is bound to the `view` `ClusterRole`
+provided by Kubernetes. This `ClusterRole` allows read-only access to a wide
+range of Kubernetes resources within a namespace. You can find more details
+about this role in the [Kubernetes
+documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles).
+
+In addition, the audit scanner is also bound to a `ClusterRole` that grants
+read access to Kubewarden resource types and read-write access to the
+`PolicyReport` [CRDs](policy-reports.md). These permissions enable the scanner
+to fetch resources for conducting audit evaluations and create policy reports
+based on the evaluation results.

docs/explanations/audit-scanner/limitations.md

@@ -0,0 +1,42 @@
+---
+sidebar_label: "Limitations"
+title: "Audit Scanner - Limitations"
+---
+
+## Supported event types
+
+Policies can inspect `CREATE`, `UPDATE`, and `DELETE` events.
+
+The audit scanner cannot simulate `UPDATE` events, as it doesn't know exactly
+which part of the resource needs to be changed in a meaningful way.
+
+Because of that, policy interested only in `UPDATE` events will be ignored by
+the audit scanner.
+
+:::note
+The audit-scanner v1.7.0 release supports only `CREATE` events. `DELETE` ones
+will be handled in the near future.
+:::
+
+## Policies relying on user and user group information
+
+Each Kubernetes admission request object contains information about which user
+(or ServiceAccount) initiated the event, and to which group they belong.
+
+All the events simulated by the audit scanner are originated by the same hard
+coded user and group. Because of that, policies that rely on these values to
+make their decisions will not produce meaningful results.
+
+For these cases, the policy should be configured to be skipped from the audit
+checks.
+
+## Policies relying on external data
+
+Policies can request and use external data when performing an evaluation. These
+policies can be evaluated by the audit checks, but their outcome can change
+over time depending on the external data.
+
+## Policies targeting `*`
+
+Policies targeting any kind of Kubernetes resources are not being evaluated for
+now. Because of that they are going to be ignored by the audit scanner.

docs/explanations/audit-scanner/policy-reports.md

@@ -0,0 +1,157 @@
+---
+sidebar_label: "Policy Reports"
+title: "Audit Scanner - Policy Reports"
+---
+
+# Policy Reports
+
+When using the Kubewarden Audit Scanner, the results of the policy scans are
+stored using the
+[PolicyReport](https://htmlpreview.github.io/?https://github.com/kubernetes-sigs/wg-policy-prototypes/blob/master/policy-report/docs/index.html)
+Custom Resource.
+
+:::caution
+Note that the PolicyReport CRDs are under development in the `wg-policy`
+Kubernetes group. Therefore, this documentation can be out of date if a new
+version of the CRDs is released.
+
+Check the `wg-policy` group
+[repository](https://github.com/kubernetes-sigs/wg-policy-prototypes) for
+more information about the CRDs.
+:::
+
+These CRDs provide a structured way to store and manage the audit results.
+
+Each namespace scanned by the audit scanner will have a dedicated
+`PolicyReport` resource defined inside of it.
+
+The results of Cluster wide resources are going to be found inside of a
+`ClusterPolicyReport` object. There is going to be only one
+`ClusterPolicyReport` per cluster.
+
+The audit results generated by the scanner includes various information, such
+as the policy that was evaluated, the resource being scanned, the result of the
+evaluation (pass, fail, or skip), and a timestamp indicating when the
+evaluation took place. Additionally, you can optionally define severity and
+category annotations for your policies.
+
+You can also leverage the optional UI provided by the
+[policy-reporter](https://github.com/kyverno/policy-reporter) open source
+project for monitoring and observability of the PolicyReport CRDs.
+Furthermore, operators can access the reports via ordinary `kubectl` commands.
+
+Let's take a look at some example audit results generated by the audit scanner:
+
+## Cluster-Wide Audit Results example
+
+In the next example, the audit scanner has evaluated the
+`cap-testing-cap-policy` on multiple namespaces in the cluster. The results
+indicate that all the namespaces passed the policy validation. The `summary`
+section provides a summary of the audit results, showing there were no
+errors, failures, or warnings.
+
+```yaml
+apiVersion: wgpolicyk8s.io/v1beta1
+kind: ClusterPolicyReport
+metadata:
+  creationTimestamp: "2023-07-10T19:25:40Z"
+  generation: 1
+  labels:
+    app.kubernetes.io/managed-by: kubewarden
+  ...
+results:
+- policy: cap-testing-cap-policy
+  ...
+  resourceSelector: {}
+  resources:
+  - apiVersion: v1
+    kind: Namespace
+    name: kube-system
+    ...
+  result: pass
+  rule: testing-cap-policy
+  source: kubewarden
+  timestamp:
+    nanos: 0
+    seconds: 1689017140
+- policy: cap-testing-cap-policy
+  ...
+  resourceSelector: {}
+  resources:
+  - apiVersion: v1
+    kind: Namespace
+    name: default
+    ...
+  result: pass
+  rule: testing-cap-policy
+  source: kubewarden
+  timestamp:
+    nanos: 0
+    seconds: 1689017140
+...
+summary:
+  error: 0
+  fail: 0
+  pass: 6
+  skip: 0
+  warn: 0
+```
+
+## Namespace-Specific Audit Results example
+
+In this example, the audit scanner has evaluated multiple policies on resources
+within the `default` namespace. The results indicate that some of the resources
+failed the validation for the `cap-no-privilege-escalation` policy, while
+others passed the validation for the `cap-do-not-run-as-root` policy. The
+`summary` section shows a summary of the audit results, indicating the number
+of failures and passes.
+
+```yaml
+apiVersion: wgpolicyk8s.io/v1beta1
+kind: PolicyReport
+metadata:
+  creationTimestamp: "2023-07-10T19:28:05Z"
+  generation: 4
+  labels:
+    app.kubernetes.io/managed-by: kubewarden
+  ...
+results:
+- message: one of the containers has privilege escalation enabled
+  policy: cap-no-privilege-escalation
+  ...
+  resourceSelector: {}
+  resources:
+  - apiVersion: apps/v1
+    kind: Deployment
+    name: nginx-deployment
+    namespace: default
+    ...
+  result: fail
+  rule: no-privilege-escalation
+  source: kubewarden
+  timestamp:
+    nanos: 0
+    seconds: 1689017383
+- policy: cap-do-not-run-as-root
+  ...
+  resourceSelector: {}
+  resources:
+  - apiVersion: apps/v1
+    kind: Deployment
+    name: nginx-deployment
+    namespace: default
+    ...
+  result: pass
+  rule: do-not-run-as-root
+  source: kubewarden
+  timestamp:
+    nanos: 0
+    seconds: 1689017383
+...
+summary:
+  error: 0
+  fail: 8
+  pass: 10
+  skip: 0
+  warn: 0
+```

docs/howtos/audit-scanner.md

@@ -0,0 +1,66 @@
+---
+sidebar_label: "Audit Scanner Installation"
+title: "Audit Scanner Installation"
+---
+
+# Audit Scanner installation
+
+Beginning with version `v1.7.0`, Kubewarden has a new feature called "Audit Scanner".
+A new component, called "audit-scanner", constantly checks the resources declared in the
+cluster, flagging the ones that do not adhere with the deployed Kubewarden policies.
+
+Policies evolve over the time: new ones are deployed and the existing ones can be
+updated, both in terms of version and configuration settings.
+This can lead to situations where resources already inside of the cluster
+are no longer compliant.
+
+The audit scanner feature provides Kubernetes administrators
+with a tool to consistently verify the compliance state of their clusters.
+
+## Installation
+
+The audit scanner component is available since Kubewarden `v1.7.0`. Therefore,
+make sure you are installing the Helm chart with app version `v1.7.0` or
+higher.
+
+1. Install the `kubewarden-crds` Helm chart. The chart install the needed
+   `PolicyReport` CRDs by default.
+
+   ```console
+   helm install kubewarden-crds kubewarden/kubewarden-crds
+   ```
+
+   :::caution
+   To store the results of policy reports, you need to have the PolicyReport
+   Custom Resource Definitions (CRDs) available. If the necessary
+   PolicyReport CRDs are already in the cluster, you cannot install them
+   using the kubewarden-crds chart. In such case, you can disable the
+   installation of PolicyReport CRDs by setting `installPolicyReportCRDs` to
+   `false` in the chart. This means that the Kubewarden stack will not manage
+   those CRDs, and the responsibility will be with the administrator.
+
+   See more info about the CRDs at the [policy work group
+   repository](https://github.com/kubernetes-sigs/wg-policy-prototypes)
+   :::
+
+2. Install the `kubewarden-controller` Helm chart.
+
+   ```console
+   helm install kubewarden-controller kubewarden/kubewarden-controller
+   ```
+
+   :::note
+   The audit scanner is enabled by default. If you want to disable it, set the
+   `auditScanner.enable=false`.
+   :::
+
+   For more information about the installation of Kubewarden see the [Quick Start guide](../quick-start.md)
+
+By default, the Audit Scanner is implemented as a
+[Cronjob](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs)
+that will be triggered every 60 minutes. You can adjust this and other audit
+scanner settings by changing the kubewarden-controller chart
+[values.yaml](https://github.com/kubewarden/helm-charts/blob/main/charts/kubewarden-controller/values.yaml).
+
+See [here](../explanations/audit-scanner) more information about the Audit
+Scanner.

docs/quick-start.md

@@ -57,12 +57,19 @@ helm repo update kubewarden
 
 Install the following Helm charts inside the `kubewarden` namespace in your Kubernetes cluster:
 
-* `kubewarden-crds`, which will register the `ClusterAdmissionPolicy` and `PolicyServer` Custom Resource Definitions
+* `kubewarden-crds`, which will register the `ClusterAdmissionPolicy`,
+  `AdmissionPolicy` and `PolicyServer` Custom Resource Definitions.  As well as
+  the `PolicyReport` Custom Resource Definitions used by the audit scanner
 
-* `kubewarden-controller`, which will install the Kubewarden controller
+* `kubewarden-controller`, which will install the Kubewarden controller and the
+  audit scanner
+:::note
+If you want to disable the audit scanner component. Please check out the audit
+scanner installation [docs page](../howtos/audit-scanner).
+:::
 
 * `kubewarden-defaults`, which will create a `PolicyServer` resource named `default`. It can also install a set of
-recommended policies to secure your cluster by enforcing some best practices.
+recommended policies to secure your cluster by enforcing some well known best practices.
 
 ```console
 helm install --wait -n kubewarden --create-namespace kubewarden-crds kubewarden/kubewarden-crds