From d87f5fac4c98e68c24b3fb1b19d4ccd41e39c1dd Mon Sep 17 00:00:00 2001 From: John Krug Date: Tue, 10 Oct 2023 14:07:57 +0200 Subject: [PATCH 1/6] Review and refresh of audit scanner overview document. Signed-off-by: John Krug --- .../audit-scanner/audit-scanner.md | 127 ++++++++---------- 1 file changed, 57 insertions(+), 70 deletions(-) diff --git a/docs/explanations/audit-scanner/audit-scanner.md b/docs/explanations/audit-scanner/audit-scanner.md index ec0b082e31..bbe6fba408 100644 --- a/docs/explanations/audit-scanner/audit-scanner.md +++ b/docs/explanations/audit-scanner/audit-scanner.md @@ -1,89 +1,76 @@ --- -sidebar_label: "What's it?" -title: "Audit Scanner" +sidebar_label: "What is the Audit Scanner?" +title: "What is the 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. +The `audit-scanner` component constantly checks resources in the cluster. +It flags the ones that don't adhere with the Kubewarden policies deployed in the cluster. + +Policies evolve over time. +New ones are deployed, existing ones are updated. +Versions and configuration settings change. +This can lead to situations where resources already inside the cluster are no longer compliant. +The audit scanning feature provides Kubernetes administrators with a tool that constantly verifies the compliance state of their clusters. + +To explain the use of the audit scanner in Kubewarden, consider the following scenario. + +Assume Bob is deploying a WordPress Pod in the cluster. +Bob is new to Kubernetes, makes a mistake and deploys the Pod running as a privileged container. +At this point there's no policy preventing that so the Pod is +successfully created in 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 in the cluster as it already exists. + +A report generated by the audit scanner lets Alice identify all the workloads that are violating creation policies. +This includes the WordPress Pod created by Bob. + +The audit scanner operates by: + +- identifying all the resources to audit +- for each it builds a fake admission request with the resource's data +- it sends each admission request to a policy server endpoint which is only for audit requests + +For the policy evaluating the request, +there are no differences between real or audit requests. +The data received is the same. +This auditing policy server endpoint has instrumentation to collect data of the evaluation. +So, users can use their monitoring tools analyze audit scanner data. ## Enable audit scanner -As stated before, the audit scanner feature can be enabled starting from the -Kubewarden 1.7.0 release. +You can enable the audit scanner starting from the Kubewarden 1.7.0 release. -Detailed installation instructions can be found -[here](../howtos/audit-scanner). +Detailed installation instructions are in the +[audit scanner How-to](../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`: +By default, the audit scanner evaluates every policy. +Operators that want to skip a policy evaluation in the audit scanner must set the `spec.backgroundAudit` field to `false` in the policy definition. -- 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`. +Also, policies in Kubewarden now support two optional annotations: -See the policy authors [docs](../../writing-policies/index.md) for more info. +- The `io.kubewarden.policy.severity` annotation lets you specify the severity level of the policy violation, such as `critical`, `high`, `medium`, `low` or `info`. +- The `io.kubewarden.policy.category` annotation lets you categorize the policy based on a specific domain or purpose, such as `PSP`, `compliance`, or `performance`. + +See the policy authors [documentation](../../writing-policies/index.md) for more information. ## 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. +The audit scanner in Kubernetes requires specific Role Based Access Control (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. +The user can create and configure 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). + +Also, the audit scanner is 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 let the scanner fetch resources for conducting audit evaluations and creating policy reports based on the evaluation results. From 10b2444dbf0df7544d38a26ba558f5aad7e4617f Mon Sep 17 00:00:00 2001 From: John Krug Date: Tue, 10 Oct 2023 14:40:26 +0200 Subject: [PATCH 2/6] Added a refresh of limitations and policy reports for audit scanner. Signed-off-by: John Krug --- .../audit-scanner/audit-scanner.md | 2 + .../explanations/audit-scanner/limitations.md | 42 +++++---- .../audit-scanner/policy-reports.md | 93 +++++++++---------- 3 files changed, 70 insertions(+), 67 deletions(-) diff --git a/docs/explanations/audit-scanner/audit-scanner.md b/docs/explanations/audit-scanner/audit-scanner.md index bbe6fba408..887be8b0e7 100644 --- a/docs/explanations/audit-scanner/audit-scanner.md +++ b/docs/explanations/audit-scanner/audit-scanner.md @@ -1,6 +1,8 @@ --- sidebar_label: "What is the Audit Scanner?" title: "What is the Audit Scanner?" +description: An overview of the Kubewarden Audit Scanner. +keywords: [kubewarden, audit scanner, kubernetes] --- :::note diff --git a/docs/explanations/audit-scanner/limitations.md b/docs/explanations/audit-scanner/limitations.md index 1e00fb63c5..e8618ad24a 100644 --- a/docs/explanations/audit-scanner/limitations.md +++ b/docs/explanations/audit-scanner/limitations.md @@ -1,40 +1,41 @@ --- sidebar_label: "Limitations" title: "Audit Scanner - Limitations" +description: The limitation of the audit scanner +keywords: [kubewarden, kubernetes, audit scanner] --- ## 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. +The audit scanner can not simulate `UPDATE` events, +as it doesn't know which part of the resource need to be changed. -Because of that, policy interested only in `UPDATE` events will be ignored by -the audit scanner. +So, a policy concerned only with `UPDATE` events is 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. + +The audit-scanner v1.7.0 release supports only `CREATE` events. +`DELETE` events 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. +Each Kubernetes admission request object has 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. +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. +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 can request and use external data when performing an evaluation. +These policies can be evaluated by the audit checks, +but their outcomes can change depending on the external data. ## Usage of `*` by policies @@ -51,7 +52,10 @@ spec: - UPDATE ``` -The `apiGroups`, `apiVersions` and `resources` attributes can use the special `*` inside of them. This is a wildcard -symbol that causes the policy to match all the values used inside of the field. + + +The `apiGroups`, `apiVersions` and `resources` attributes can use the wildcard `*`. +This wildcard symbol causes the policy to match all the values used in the field. -Policies that make use of the `*` symbol are going to be ignored by the audit scanner. +The audit scanner ignores policies that make use of the `*` symbol. diff --git a/docs/explanations/audit-scanner/policy-reports.md b/docs/explanations/audit-scanner/policy-reports.md index 21365a95ee..72a694c8fb 100644 --- a/docs/explanations/audit-scanner/policy-reports.md +++ b/docs/explanations/audit-scanner/policy-reports.md @@ -1,75 +1,74 @@ --- sidebar_label: "Policy Reports" title: "Audit Scanner - Policy Reports" +description: The policy reports that the Audit Scanner produces. +keywords: [kubewarden, kubernetes, audit scanner] --- -# Policy Reports - -When using the Kubewarden Audit Scanner, the results of the policy scans are -stored using the +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/045372e558b896695b2daae92e8c7a04d4d40282/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. + +The PolicyReport CRDs are under development in the `wg-policy` Kubernetes group. +Therefore, this documentation will become 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. +[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. +These CRDs offer a structured way to store and manage the audit results. + +Each namespace scanned by the audit scanner has a dedicated `PolicyReport` resource defined in it. + +The results of Cluster wide resources are found in a `ClusterPolicyReport` object. +There will be only one `ClusterPolicyReport` per cluster. -Each namespace scanned by the audit scanner will have a dedicated -`PolicyReport` resource defined inside of it. +The audit results generated by the scanner include: -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 policy that was evaluated +- the resource being scanned +- the result of the evaluation (pass, fail, or skip) +- a timestamp indicating when the evaluation took place. -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 define severity and category annotations for your policies. -Operators can access the reports via ordinary `kubectl` commands. They can also -leverage the optional UI provided by the -[policy-reporter](https://kyverno.github.io/policy-reporter) open source -project for monitoring and observability of the PolicyReport CRDs. +Operators can access the reports via ordinary `kubectl` commands. +They can also use the optional UI provided by the +[policy-reporter](https://kyverno.github.io/policy-reporter) +open source project for monitoring and observability of the PolicyReport CRDs. ## Policy Reporter UI -The Policy Reporter is shipped as a subchart of `kubewarden-controller`, refer -to the [Audit Scanner Installation](../../howtos/audit-scanner) page for more -info. +The Policy Reporter is shipped as a subchart of `kubewarden-controller`. +Se the [Audit Scanner Installation](../../howtos/audit-scanner) +page for more information. -The Policy Reporter UI provides a dashboard showcasing all violations from -`PolicyReports` and the `ClusterPolicyReport`. See the following example: +The Policy Reporter UI provides a dashboard showcasing all violations +from `PolicyReports` and the `ClusterPolicyReport`. +This is shown below. ![Policy Reporter dashboard example](/img/policy-reporter_dashboard.png) -In addition, it provides a tab for PolicyReports, and a tab for -ClusterPolicyReports, with expanded info. See the following example of the -PolicyReport results: +As shown below, +it also provides a tab for PolicyReports, and a tab for ClusterPolicyReports, with expanded information. ![Policy Reporter PolicyReports example](/img/policy-reporter_policyreports.png) -Additional features of Policy Reporter include forwarding of results to -different clients (like Grafana Loki, Elasticsearch, chat applications), -metrics endpoint, etc. Please refer to the -[policy-reporter's community docs](https://kyverno.github.io/policy-reporter) -for more info. +Other features of Policy Reporter include forwarding of results to different clients +(like Grafana Loki, Elasticsearch, chat applications), +metrics endpoints, and so on. +See the [policy-reporter's community docs](https://kyverno.github.io/policy-reporter) +for more information. ## 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. +In the next example, the audit scanner has evaluated the `cap-testing-cap-policy` on many 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 @@ -120,12 +119,10 @@ summary: ## 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. +In this example, the audit scanner evaluated many policies on resources within the `default` namespace. +The results indicate that certain resources failed the validation for the `cap-no-privilege-escalation` policy. +Others passed the validation for the `cap-do-not-run-as-root` policy. +The `summary` section shows the number of failures and passes. ```yaml apiVersion: wgpolicyk8s.io/v1beta1 From b6772c697819223a5b6340d07b43b064b6b40415 Mon Sep 17 00:00:00 2001 From: John Krug Date: Tue, 10 Oct 2023 14:43:01 +0200 Subject: [PATCH 3/6] Another tweak. Signed-off-by: John Krug --- docs/explanations/audit-scanner/policy-reports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanations/audit-scanner/policy-reports.md b/docs/explanations/audit-scanner/policy-reports.md index 72a694c8fb..c17871b9fb 100644 --- a/docs/explanations/audit-scanner/policy-reports.md +++ b/docs/explanations/audit-scanner/policy-reports.md @@ -68,7 +68,7 @@ for more information. In the next example, the audit scanner has evaluated the `cap-testing-cap-policy` on many 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. +The `summary` section summarizes the audit results, showing there were no errors, failures, or warnings. ```yaml apiVersion: wgpolicyk8s.io/v1beta1 From 6c46c6a5f481c5c1d287342cbe0918f7b9ccfebf Mon Sep 17 00:00:00 2001 From: John Krug Date: Tue, 10 Oct 2023 15:04:09 +0200 Subject: [PATCH 4/6] Update docs/explanations/audit-scanner/audit-scanner.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Víctor Cuadrado Juan <2196685+viccuad@users.noreply.github.com> Signed-off-by: John Krug --- docs/explanations/audit-scanner/audit-scanner.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanations/audit-scanner/audit-scanner.md b/docs/explanations/audit-scanner/audit-scanner.md index 887be8b0e7..bd17819a12 100644 --- a/docs/explanations/audit-scanner/audit-scanner.md +++ b/docs/explanations/audit-scanner/audit-scanner.md @@ -36,7 +36,7 @@ This includes the WordPress Pod created by Bob. The audit scanner operates by: - identifying all the resources to audit -- for each it builds a fake admission request with the resource's data +- for each it builds a synthetic admission request with the resource's data - it sends each admission request to a policy server endpoint which is only for audit requests For the policy evaluating the request, From 87246f2918aa5a8b5024115de150d8fd24c95a4c Mon Sep 17 00:00:00 2001 From: John Krug Date: Wed, 11 Oct 2023 15:45:09 +0200 Subject: [PATCH 5/6] Update docs/explanations/audit-scanner/policy-reports.md Thanks! Co-authored-by: Flavio Castelli Signed-off-by: John Krug --- docs/explanations/audit-scanner/policy-reports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanations/audit-scanner/policy-reports.md b/docs/explanations/audit-scanner/policy-reports.md index c17871b9fb..58f251fe4a 100644 --- a/docs/explanations/audit-scanner/policy-reports.md +++ b/docs/explanations/audit-scanner/policy-reports.md @@ -44,7 +44,7 @@ open source project for monitoring and observability of the PolicyReport CRDs. ## Policy Reporter UI The Policy Reporter is shipped as a subchart of `kubewarden-controller`. -Se the [Audit Scanner Installation](../../howtos/audit-scanner) +To the [Audit Scanner Installation](../../howtos/audit-scanner) page for more information. The Policy Reporter UI provides a dashboard showcasing all violations From 887be5c035142045f766623287af0b85554ec186 Mon Sep 17 00:00:00 2001 From: John Krug Date: Wed, 11 Oct 2023 16:37:13 +0200 Subject: [PATCH 6/6] Final fixes incorporating suggestions. Signed-off-by: John Krug --- docs/explanations/audit-scanner/limitations.md | 4 ---- docs/explanations/audit-scanner/policy-reports.md | 2 +- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/explanations/audit-scanner/limitations.md b/docs/explanations/audit-scanner/limitations.md index e8618ad24a..42672a1c3d 100644 --- a/docs/explanations/audit-scanner/limitations.md +++ b/docs/explanations/audit-scanner/limitations.md @@ -52,10 +52,6 @@ spec: - UPDATE ``` - - The `apiGroups`, `apiVersions` and `resources` attributes can use the wildcard `*`. This wildcard symbol causes the policy to match all the values used in the field. - The audit scanner ignores policies that make use of the `*` symbol. diff --git a/docs/explanations/audit-scanner/policy-reports.md b/docs/explanations/audit-scanner/policy-reports.md index 58f251fe4a..c1454b0230 100644 --- a/docs/explanations/audit-scanner/policy-reports.md +++ b/docs/explanations/audit-scanner/policy-reports.md @@ -44,7 +44,7 @@ open source project for monitoring and observability of the PolicyReport CRDs. ## Policy Reporter UI The Policy Reporter is shipped as a subchart of `kubewarden-controller`. -To the [Audit Scanner Installation](../../howtos/audit-scanner) +Refer to the [Audit Scanner Installation](../../howtos/audit-scanner) page for more information. The Policy Reporter UI provides a dashboard showcasing all violations