diff --git a/content/rancher/v2.x/en/cis-scans/v2.5/_index.md b/content/rancher/v2.x/en/cis-scans/v2.5/_index.md index d878f359f5b..2381182116c 100644 --- a/content/rancher/v2.x/en/cis-scans/v2.5/_index.md +++ b/content/rancher/v2.x/en/cis-scans/v2.5/_index.md @@ -28,25 +28,31 @@ We now support running CIS scans on any Kubernetes cluster, including hosted Kub In Rancher v2.4, the CIS scan tool was available from the **cluster manager** in the Rancher UI. Now it is available in the **Cluster Explorer** and it can be enabled and deployed using a Helm chart. It can be installed from the Rancher UI, but it can also be installed independently of Rancher. It deploys a CIS scan operator for the cluster, and deploys Kubernetes custom resources for cluster scans. The custom resources can be managed directly from the **Cluster Explorer.** -In v1 of the CIS scan tool, which was available in Rancher v2.4 through the cluster manager, recurring scans could be scheduled. The ability to schedule recurring scans is not yet available in Rancher v2.5. +In v1 of the CIS scan tool, which was available in Rancher v2.4 through the cluster manager, recurring scans could be scheduled. The ability to schedule recurring scans is now also available for CIS v2 from Rancher v2.5.4. -Support for alerting for the cluster scan results is not available for Rancher v2.5 yet. +Support for alerting for the cluster scan results is now also available from Rancher v2.5.4. -More test profiles were added. In Rancher v2.4, permissive and hardened profiles were included. In Rancher v2.5, the following profiles are available: +More test profiles were added. In Rancher v2.4, permissive and hardened profiles were included. From Rancher v2.5.4 onwards, the following profiles are available: - Generic CIS 1.5 -- RKE permissive -- RKE hardened +- Generic CIS 1.6 +- RKE permissive 1.5 +- RKE hardened 1.5 +- RKE permissive 1.6 +- RKE hardened 1.6 - EKS - GKE +- RKE2 permissive 1.5 +- RKE2 permissive 1.5 The default profile depends on the type of cluster that will be scanned: -- For RKE Kubernetes clusters, the RKE permissive profile is the default. +- For RKE Kubernetes clusters, the RKE Permissive 1.6 profile is the default. - EKS and GKE have their own CIS Benchmarks published by `kube-bench`. The corresponding test profiles are used by default for those clusters. -- For cluster types other than RKE, EKS and GKE, the Generic CIS 1.5 profile will be used by default. +- For RKE2 Kubernetes clusters, the RKE2 Permissive 1.5 profile is the default. +- For cluster types other than RKE, RKE2, EKS and GKE, the Generic CIS 1.5 profile will be used by default. -The `rancher-cis-benchmark` currently supports the CIS 1.5 Benchmark version. +The `rancher-cis-benchmark` now supports the CIS 1.6 Benchmark version since the release 2.5.4 > **Note:** CIS v1 cannot run on a cluster when CIS v2 is deployed. In other words, after `rancher-cis-benchmark` is installed, you can't run scans by going to the Cluster Manager view in the Rancher UI and clicking **Tools > CIS Scans.** @@ -200,3 +206,132 @@ For information about permissions, refer to }}/rancher/v2.x/en/cis-scans/configuration" target="_blank">this page. + +# Running a Scan periodically on a schedule + +Since Rancher v2.5.4, it is possible to run a ClusterScan on a schedule. + +To run a scan on a schedule, + +1. Go to the **Cluster Explorer** in the Rancher UI. In the top left dropdown menu, click **Cluster Explorer > CIS Benchmark.** +1. In the **Scans** section, click **Create.** +1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on. +1. Choose the option "Run scan on a schedule" +1. Enter a valid cron schedule expression in the field "Schedule" +1. Choose a "Retention" count which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged. +1. Click **Create.** + +**Result:** The scan runs and reschedules to run according to the cron schedule provided. The "Next Scan" value indicates the next time this scan will run again. +A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears. +You can also see the previous reports by choosing the report from the "Reports" dropdown on the scan detail page. + +# Enabling Alerting for rancher-cis-benchmark + +Alerts can be configured to be sent out for a scan that runs on a schedule. + +To configure alerts, + +1. While installing or upgrading the `rancher-cis-benchmark` application, set the following flag to `true` in `Values YAML` + + ```yaml + alerts: + enabled: true + ``` +1. Before enabling alerts for `rancher-cis-benchmark`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. + Please check [this section.]({{}}/rancher/v2.x/en/monitoring-alerting/v2.5/configuration/#alertmanager-config) +1. While configuring the routes for `rancher-cis-benchmark` alerts, you can specify the matching using the (key: value) pair (job: rancher-cis-scan) + +# Configuring Alerts for a periodic Scan on a schedule + +From Rancher v2.5.4, it is possible to run a ClusterScan on a schedule and also specify if you should receive alerts when the scan completes. +Alerts are supported only for a scan that runs on a schedule. + +The `rancher-cis-benchmark` application supports two types of alerts: +1. Alert on scan completion - this alert is sent out when the scan run finishes. The alert includes details including the ClusterScan's name, ClusterScanProfile name. +1. Alert on scan failure - this alert is sent out if there are some test failures in the scan run or if the scan is in a `Fail` state. + +To configure alerts for a scan that runs on a schedule, + +1. Please enable alerts on the `rancher-cis-benchmark` application (#enabling-alerting-for-rancher-cis-benchmark) +1. Go to the **Cluster Explorer** in the Rancher UI. In the top left dropdown menu, click **Cluster Explorer > CIS Benchmark.** +1. In the **Scans** section, click **Create.** +1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on. +1. Choose the option "Run scan on a schedule" +1. Enter a valid cron schedule expression in the field "Schedule" +1. Check the boxes next to the Alert types under `Alerting` +1. Please ensure that Rancher's Monitoring and Alerting app is installed and the Receivers and Routes are configured to send out alerts. +1. Optionally Choose a "Retention" count which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged. +1. Click **Create.** + +**Result:** The scan runs and reschedules to run according to the cron schedule provided. Alerts are sent out when the scan finishes if routes and receiver are configured under `rancher-monitoring` application. +A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears. + +# Creating a custom Benchmark Version for running a cluster scan + +When a cluster scan is run, you need to select a Profile which points to a specific Benchmark Version. +Each Benchmark Version defines a set of test configuration files that define the CIS tests to be run by the kube-bench tool. +The `rancher-cis-benchmark` application installs a few default Benchmark Versions which are listed under CIS Benchmark application menu. + +But there could be some kubernetes cluster setups that require custom configurations of the Benchmark tests. +For example, path to the kubernetes config files or certs might be different than the standard location where the upstream +CIS benchmarks look for. + +With Rancher v2.5.4 it is now possible to create a custom Benchmark Version for running a cluster scan using the `rancher-cis-benchmark` application. + +Follow all the steps below to add a custom Benchmark Version and run a scan using it. + +## Preparing the custom Benchmark Version ConfigMap +To create a custom Benchmark Version first you need to create a ConfigMap containing the benchmark version's config files and upload it to your kubernetes cluster where you want to run the scan. + +To prepare a custom Benchmark Version ConfigMap, +1. Suppose we want to add a custom Benchmark Version named `foo` +1. Create a directory named `foo` and place all the config yaml files that kube-bench tool looks for, inside this directory. +1. For example, here are the config yaml files for a Generic CIS 1.5 Benchmark Version https://github.com/aquasecurity/kube-bench/tree/master/cfg/cis-1.5 +1. Place the complete config.yaml file which includes all the components that should be tested. +1. To the config.yaml file add the Benchmark version name to the `target_mapping` section. + ```yaml + target_mapping: + "foo": + - "master" + - "node" + - "controlplane" + - "etcd" + - "policies" + ``` +1. Now upload this directory to your Kubernetes Cluster by creating a Configmap: + ```yaml + kubectl create configmap -n foo --from-file= + ``` +## Adding the custom Benchmark Version to your Cluster + +1. Once the configmap has been created in your cluster, navigate to the **Cluster Explorer** in the Rancher UI. +1. In the top left dropdown menu, click **Cluster Explorer > CIS Benchmark.** +1. In the **Benchmark Versions** section, click **Create.** +1. Enter the Name as `foo` and a description for your custom Benchmark. +1. Choose the cluster provider that your Benchmark Version applies to. +1. Choose the ConfigMap you have uploaded from the dropdown. +1. Add the minimum and maximum Kubernetes version limits applicable if any. +1. Click **Create.** + +## Create a new Profile for your custom Benchmark Version +To run a scan using your custom Benchmark Version, you need to add a new Profile pointing to this Benchmark Version. + +1. Once the custom Benchmark Version has been created in your cluster, navigate to the **Cluster Explorer** in the Rancher UI. +1. In the top left dropdown menu, click **Cluster Explorer > CIS Benchmark.** +1. In the **Profiles** section, click **Create.** +1. Provide a name say `foo-profile` and description +1. Choose the Benchmark Version `foo` from the dropdown +1. Click **Create.** + +## Running a scan using your custom Benchmark Version + +Once the Profile pointing to your custom Benchmark Version `foo` has been created, you can create a new Scan to run the custom test configs in the Benchmark Version. +To run a scan, + +1. Go to the **Cluster Explorer** in the Rancher UI. In the top left dropdown menu, click **Cluster Explorer > CIS Benchmark.** +1. In the **Scans** section, click **Create.** +1. Choose the new cluster scan profile `foo-profile`. +1. Click **Create.** + +**Result:** A report is generated with the scan results. To see the results, click the name of the scan that appears. +