From c06554a0df0a87dd4bc4e926800421d5265e45b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Guilherme=20Vanz?= Date: Tue, 11 Jul 2023 09:55:02 -0300 Subject: [PATCH 1/7] feat: audit scanner docs. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds documentation about the new Kubewarden component, the Audit Scanner. The docs explain what is it, how to use it and why it is useful. Signed-off-by: José Guilherme Vanz --- docs/explanations/audit-scanner.md | 278 +++++++++++++++++++++++++++++ docs/howtos/audit-scanner.md | 67 +++++++ docs/quick-start.md | 11 +- sidebars.js | 3 + 4 files changed, 357 insertions(+), 2 deletions(-) create mode 100644 docs/explanations/audit-scanner.md create mode 100644 docs/howtos/audit-scanner.md diff --git a/docs/explanations/audit-scanner.md b/docs/explanations/audit-scanner.md new file mode 100644 index 0000000000..42f529f0f2 --- /dev/null +++ b/docs/explanations/audit-scanner.md @@ -0,0 +1,278 @@ +--- +sidebar_label: "Audit Scanner" +title: "Audit Scanner" +--- + +# Audit Scanner + +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. + +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 instrumentalized 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). + +## 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. + + +## 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 +``` + +--- + +## 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 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 sane 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. These permissions enable the scanner to fetch resources +for conducting audit evaluations and create policy reports based on the +evaluation results. diff --git a/docs/howtos/audit-scanner.md b/docs/howtos/audit-scanner.md new file mode 100644 index 0000000000..d105403ede --- /dev/null +++ b/docs/howtos/audit-scanner.md @@ -0,0 +1,67 @@ +--- +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. Remember to enable the audit + scanner component. + + ```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. diff --git a/docs/quick-start.md b/docs/quick-start.md index 7da0af5af3..594483758d 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -57,9 +57,16 @@ 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. diff --git a/sidebars.js b/sidebars.js index 957882df9c..7413706f96 100644 --- a/sidebars.js +++ b/sidebars.js @@ -115,6 +115,8 @@ module.exports = { { Comparisons: ["explanations/opa-comparison"], }, + "explanations/context-aware-policies", + "explanations/audit-scanner" ], collapsed: true, }, @@ -145,6 +147,7 @@ module.exports = { }, ], }, + "howtos/audit-scanner" ], collapsed: true, }, From a4309a15127fccb5bef771700a1352b4ead6d29e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Guilherme=20Vanz?= Date: Wed, 12 Jul 2023 12:05:58 -0300 Subject: [PATCH 2/7] Policy metadata documentation. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit adds documentation explaining the purpose and usage of the Kubewarden metadata file. It covers the enablement of background audit checks, defining Kubernetes resources for policies, specifying policy types (mutating or non-mutating), and the rules for targeting resource types. Signed-off-by: José Guilherme Vanz --- docs/explanations/audit-scanner.md | 2 +- docs/writing-policies/metadata.md | 108 +++++++++++++++++++++++++++++ sidebars.js | 11 +-- 3 files changed, 115 insertions(+), 6 deletions(-) create mode 100644 docs/writing-policies/metadata.md diff --git a/docs/explanations/audit-scanner.md b/docs/explanations/audit-scanner.md index 42f529f0f2..ada966812d 100644 --- a/docs/explanations/audit-scanner.md +++ b/docs/explanations/audit-scanner.md @@ -9,7 +9,7 @@ Beginning with version `v1.7.0`, Kubewarden has a new feature called "Audit Scan 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 +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 diff --git a/docs/writing-policies/metadata.md b/docs/writing-policies/metadata.md new file mode 100644 index 0000000000..7ae7898e68 --- /dev/null +++ b/docs/writing-policies/metadata.md @@ -0,0 +1,108 @@ +--- +sidebar_label: "Policy metadata" +title: "Policy metadata" +--- + +# Policy metadata + +The Kubewarden metadata file, `metadata.yaml`, serves as a vital configuration +file that contains important information and settings related to the policies +used within Kubewarden. This documentation aims to provide an overview of the +purpose and usage of the metadata file. + +The policy `metadata.yaml` file contains defaults for the policy, in addition +to metadata such as author and description, set by the policy author. The file +is used by the `kwctl annonate` command to, as the name suggests, annotates the +`.wasm` file containing the policy. Therefore, all the relevant information required to run +the policy will be available. More information about how to annotate the policy +can be found in the [Distributing Policies](../distributing-policies.md) guide. + +When policy users want to use a policy, they generate a YAML manifest using +`kwctl scaffold`. This command reads the policy metadata embedded in the +shipped Wasm module, performs sanity checks, and returns a YAML manifest that +the author can use as-is or adapt to their needs. + +As a policy author, you can adapt the `metadata.yaml` file provided during the +scaffolding of your policy. + +See the following example of a `metadata.yaml`: + + +```yaml +rules: +- apiGroups: [""] + apiVersions: ["v1"] + resources: ["pods"] + operations: ["CREATE"] +mutating: false +contextAwareResources: [] +executionMode: kubewarden-wapc +backgroundAudit: true +annotations: + # artifacthub specific: + io.artifacthub.displayName: Policy Name + io.artifacthub.resources: Pod + io.artifacthub.keywords: pod, cool policy, kubewarden + io.kubewarden.policy.ociUrl: ghcr.io/myorg/my-policy + # kubewarden specific: + io.kubewarden.policy.title: My policy + io.kubewarden.policy.description: Short description + io.kubewarden.policy.author: myself + io.kubewarden.policy.url: https://github.com/yourorg/my-policy + io.kubewarden.policy.source: https://github.com/yourorg/my-policy + io.kubewarden.policy.license: Apache-2.0 + # The next two annotations are used in the policy report generated by the + # Audit scanner. Severity indicates policy check result criticality and + # Category indicates policy category. See more here at docs.kubewarden.io + io.kubewarden.policy.severity: medium + io.kubewarden.policy.category: Resource validation +``` + + +**1. Enabling Background Audit Checks:** + +The metadata file includes a flag, `backgroundAudit`, that enables the +background audit checks for a specific policy. By default, this flag is set to +`true`. + +There are some policies that, due to the way they work or to the type +of events they are interested about, should have this field set to `false`. +More information can be found inside of the +[audit scanner documentation](../explanations/audit-scanner#limitations), +respectively under the limitations section. + +**2. Defining Kubernetes Resources policies can access:** + +Within the metadata file, using the `contextAwareResources` field, users can +define which Kubernetes resources the policy is allowed to access. For example, +if the policy need access to `Namespace` resource. The policy author can define +the `contextAwareResources` as: + +```yaml +[...] +contextAwareResources: + - apiVersion: v1 kind: Namespace +[...] +``` + +**3. Specifying Policy Type: Mutating or Non-Mutating:** + +The metadata file contains a flag, `mutating`, that allows users to designate +a policy as either mutating or non-mutating. A mutating +policy modifies the incoming requests or the resources being managed. A +non-mutating one observes and enforces restrictions without making any +changes. This distinction is crucial in determining how policies interact with +the Kubernetes resources and their impact on the cluster. + +**4. Defining Resource Type Targets:** + +The metadata file provides users with the ability to define the rules within +the `rules` field, which determine the resource types to which the policy +applies. This feature empowers users to exercise precise control over policy +enforcement, guaranteeing that policies are exclusively applied to the intended +resource types. With this fine-grained control, users can ensure that policies +are targeted accurately, aligning with their specific requirements and avoiding +any unintended application to unrelated resource types. + +--- + diff --git a/sidebars.js b/sidebars.js index 7413706f96..2d447e6eeb 100644 --- a/sidebars.js +++ b/sidebars.js @@ -87,12 +87,13 @@ module.exports = { items: [], }, { - type: "category", - label: "WASI", - link: { type: "doc", id: "writing-policies/wasi" }, - items: [], + type: 'category', + label: 'WASI', + link: {type: 'doc', id: 'writing-policies/wasi'}, + items: [] }, - ], + "writing-policies/metadata", + ] }, { type: "category", From d4de928a6c06047eca95bb239b33cfeee7880820 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADctor=20Cuadrado=20Juan?= <2196685+viccuad@users.noreply.github.com> Date: Tue, 25 Jul 2023 16:57:04 +0200 Subject: [PATCH 3/7] Update docs/writing-policies/metadata.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: John Krug Signed-off-by: Víctor Cuadrado Juan <2196685+viccuad@users.noreply.github.com> --- docs/writing-policies/metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing-policies/metadata.md b/docs/writing-policies/metadata.md index 7ae7898e68..c1e225402d 100644 --- a/docs/writing-policies/metadata.md +++ b/docs/writing-policies/metadata.md @@ -7,7 +7,7 @@ title: "Policy metadata" The Kubewarden metadata file, `metadata.yaml`, serves as a vital configuration file that contains important information and settings related to the policies -used within Kubewarden. This documentation aims to provide an overview of the +used within Kubewarden. This documentation provides an overview of the purpose and usage of the metadata file. The policy `metadata.yaml` file contains defaults for the policy, in addition From c5db02a914a1eef107f409a0e6acd70fb5b6e851 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADctor=20Cuadrado=20Juan?= <2196685+viccuad@users.noreply.github.com> Date: Tue, 25 Jul 2023 16:57:21 +0200 Subject: [PATCH 4/7] Update docs/quick-start.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: John Krug Signed-off-by: Víctor Cuadrado Juan <2196685+viccuad@users.noreply.github.com> --- docs/quick-start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quick-start.md b/docs/quick-start.md index 594483758d..826e2c489a 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -69,7 +69,7 @@ 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 From 8f37ab6a07a6f2360d661571be94935d35f69fda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADctor=20Cuadrado=20Juan?= Date: Fri, 8 Sep 2023 12:19:06 +0200 Subject: [PATCH 5/7] fix: Audit-scanner is now enabled by default MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Víctor Cuadrado Juan --- docs/howtos/audit-scanner.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/howtos/audit-scanner.md b/docs/howtos/audit-scanner.md index d105403ede..13810d6c24 100644 --- a/docs/howtos/audit-scanner.md +++ b/docs/howtos/audit-scanner.md @@ -29,21 +29,21 @@ higher. ```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) + 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. Remember to enable the audit - scanner component. +2. Install the `kubewarden-controller` Helm chart. ```console helm install kubewarden-controller kubewarden/kubewarden-controller @@ -56,7 +56,6 @@ higher. 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 From 9bd944f5de23096f178f3d2f247d72335677808c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Guilherme=20Vanz?= Date: Fri, 8 Sep 2023 11:27:37 -0300 Subject: [PATCH 6/7] Split audit scanner explanation docs. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Splits the audit scanner docs into smaller pages and organize them inside the subtopic of the explanation docs. Signed-off-by: José Guilherme Vanz --- docs/explanations/audit-scanner.md | 278 ------------------ .../audit-scanner/audit-scanner.md | 86 ++++++ .../explanations/audit-scanner/limitations.md | 43 +++ .../audit-scanner/policy-reports.md | 161 ++++++++++ sidebars.js | 4 +- 5 files changed, 293 insertions(+), 279 deletions(-) delete mode 100644 docs/explanations/audit-scanner.md create mode 100644 docs/explanations/audit-scanner/audit-scanner.md create mode 100644 docs/explanations/audit-scanner/limitations.md create mode 100644 docs/explanations/audit-scanner/policy-reports.md diff --git a/docs/explanations/audit-scanner.md b/docs/explanations/audit-scanner.md deleted file mode 100644 index ada966812d..0000000000 --- a/docs/explanations/audit-scanner.md +++ /dev/null @@ -1,278 +0,0 @@ ---- -sidebar_label: "Audit Scanner" -title: "Audit Scanner" ---- - -# Audit Scanner - -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 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 instrumentalized 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). - -## 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. - - -## 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 -``` - ---- - -## 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 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 sane 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. These permissions enable the scanner to fetch resources -for conducting audit evaluations and create policy reports based on the -evaluation results. diff --git a/docs/explanations/audit-scanner/audit-scanner.md b/docs/explanations/audit-scanner/audit-scanner.md new file mode 100644 index 0000000000..29662d6036 --- /dev/null +++ b/docs/explanations/audit-scanner/audit-scanner.md @@ -0,0 +1,86 @@ +--- +sidebar_label: "What's it?" +title: "Audit Scanner" +--- + +# Audit Scanner + +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 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 instrumentalized 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 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 sane 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. diff --git a/docs/explanations/audit-scanner/limitations.md b/docs/explanations/audit-scanner/limitations.md new file mode 100644 index 0000000000..88a95a8ab0 --- /dev/null +++ b/docs/explanations/audit-scanner/limitations.md @@ -0,0 +1,43 @@ +--- +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. + diff --git a/docs/explanations/audit-scanner/policy-reports.md b/docs/explanations/audit-scanner/policy-reports.md new file mode 100644 index 0000000000..b0a15ad5d4 --- /dev/null +++ b/docs/explanations/audit-scanner/policy-reports.md @@ -0,0 +1,161 @@ +--- +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 +``` + +--- diff --git a/sidebars.js b/sidebars.js index 2d447e6eeb..380376d899 100644 --- a/sidebars.js +++ b/sidebars.js @@ -117,7 +117,9 @@ module.exports = { Comparisons: ["explanations/opa-comparison"], }, "explanations/context-aware-policies", - "explanations/audit-scanner" + { + "Audit Scanner": [ "explanations/audit-scanner/audit-scanner", "explanations/audit-scanner/limitations", "explanations/audit-scanner/policy-reports"], + }, ], collapsed: true, }, From 75967573789d1cbc07f32c9faf626c2c2a8ecc91 Mon Sep 17 00:00:00 2001 From: Flavio Castelli Date: Mon, 11 Sep 2023 15:06:59 +0200 Subject: [PATCH 7/7] Minor fixes to the audit-scanner docs * sidebar: open immediately the intro page when clicking on "explanations/audit scanner" * minor grammar fixes Signed-off-by: Flavio Castelli --- .../audit-scanner/audit-scanner.md | 33 ++++++++++--------- .../explanations/audit-scanner/limitations.md | 11 +++---- .../audit-scanner/policy-reports.md | 4 --- sidebars.js | 24 +++++++++----- 4 files changed, 38 insertions(+), 34 deletions(-) diff --git a/docs/explanations/audit-scanner/audit-scanner.md b/docs/explanations/audit-scanner/audit-scanner.md index 29662d6036..7422385f8e 100644 --- a/docs/explanations/audit-scanner/audit-scanner.md +++ b/docs/explanations/audit-scanner/audit-scanner.md @@ -5,8 +5,11 @@ title: "Audit Scanner" # Audit Scanner -Beginning with version `v1.7.0`, Kubewarden has a new feature called "Audit -Scanner". A new component, called "audit-scanner", constantly checks the +:::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. @@ -28,18 +31,18 @@ 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. +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 instrumentalized to collect data of the evaluation as +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. +use their monitoring tools analyze this data as well. ## Enable audit scanner @@ -52,30 +55,30 @@ Detailed installation instructions can be found ## 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 the +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: +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". + 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". + 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 sane default Service +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 +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). diff --git a/docs/explanations/audit-scanner/limitations.md b/docs/explanations/audit-scanner/limitations.md index 88a95a8ab0..50e195df86 100644 --- a/docs/explanations/audit-scanner/limitations.md +++ b/docs/explanations/audit-scanner/limitations.md @@ -3,9 +3,9 @@ sidebar_label: "Limitations" title: "Audit Scanner - Limitations" --- -# Supported event types +## Supported event types -Policies can inspect `CREATE`, `UPDATE`, and `DELETE` events. +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. @@ -18,7 +18,7 @@ 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 +## 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. @@ -30,14 +30,13 @@ 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 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 `*` 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. - diff --git a/docs/explanations/audit-scanner/policy-reports.md b/docs/explanations/audit-scanner/policy-reports.md index b0a15ad5d4..271d446ac8 100644 --- a/docs/explanations/audit-scanner/policy-reports.md +++ b/docs/explanations/audit-scanner/policy-reports.md @@ -40,7 +40,6 @@ You can also leverage the optional UI provided by the 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 @@ -98,7 +97,6 @@ summary: warn: 0 ``` - ## Namespace-Specific Audit Results example In this example, the audit scanner has evaluated multiple policies on resources @@ -157,5 +155,3 @@ summary: skip: 0 warn: 0 ``` - ---- diff --git a/sidebars.js b/sidebars.js index 380376d899..07b8ad0e78 100644 --- a/sidebars.js +++ b/sidebars.js @@ -87,13 +87,13 @@ module.exports = { items: [], }, { - type: 'category', - label: 'WASI', - link: {type: 'doc', id: 'writing-policies/wasi'}, - items: [] + type: "category", + label: "WASI", + link: { type: "doc", id: "writing-policies/wasi" }, + items: [], }, "writing-policies/metadata", - ] + ], }, { type: "category", @@ -116,10 +116,16 @@ module.exports = { { Comparisons: ["explanations/opa-comparison"], }, - "explanations/context-aware-policies", + "explanations/context-aware-policies", { - "Audit Scanner": [ "explanations/audit-scanner/audit-scanner", "explanations/audit-scanner/limitations", "explanations/audit-scanner/policy-reports"], - }, + type: "category", + label: "Audit Scanner", + link: { type: "doc", id: "explanations/audit-scanner/audit-scanner" }, + items: [ + "explanations/audit-scanner/limitations", + "explanations/audit-scanner/policy-reports", + ], + }, ], collapsed: true, }, @@ -150,7 +156,7 @@ module.exports = { }, ], }, - "howtos/audit-scanner" + "howtos/audit-scanner", ], collapsed: true, },