public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-05-16 10:03:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

Edit CIS scan docs for v2.5.4

Browse Source
This commit is contained in:
Catherine Luse
2020-12-18 18:50:31 -07:00
committed by cluse
parent 6657a4ee34
commit a719692617
3 changed files with 272 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/rancher/v2.x/en/cis-scans/v2.5/_index.md
+189 -182
View File
@@ -4,25 +4,29 @@ shortTitle: Rancher v2.5
weight: 1
---
Rancher can run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS Kubernetes Benchmark.
The `rancher-cis-benchmark` app leverages <a href="https://github.com/aquasecurity/kube-bench" target="_blank">kube-bench,</a> an open-source tool from Aqua Security, to check clusters for CIS Kubernetes Benchmark compliance. Also, to generate a cluster-wide report, the application utilizes <a href="https://github.com/vmware-tanzu/sonobuoy" target="_blank">Sonobuoy</a> for report aggregation.
- [Changes in Rancher v2.5](#changes-in-rancher-v2-5)
- [About the CIS Benchmark](#about-the-cis-benchmark)
- [Installing rancher-cis-benchmark](#installing-rancher-cis-benchmark)
- [Uninstalling rancher-cis-benchmark](#uninstalling-rancher-cis-benchmark)
- [Running a Scan](#running-a-scan)
- [Skipping Tests](#skipping-tests)
- [Viewing Reports](#viewing-reports)
- [About the generated report](#about-the-generated-report)
- [About the Generated Report](#about-the-generated-report)
- [Test Profiles](#test-profiles)
- [About Skipped and Not Applicable Tests](#about-skipped-and-not-applicable-tests)
- [Roles-based access control](./rbac)
- [Roles-based Access Control](./rbac)
- [Configuration](./configuration)
- [How-to Guides](#how-to-guides)
- [Installing rancher-cis-benchmark](#installing-rancher-cis-benchmark)
- [Uninstalling rancher-cis-benchmark](#uninstalling-rancher-cis-benchmark)
- [Running a Scan](#running-a-scan)
- [Running a Scan Periodically on a Schedule](#running-a-scan-periodically-on-a-schedule)
- [Skipping Tests](#skipping-tests)
- [Viewing Reports](#viewing-reports)
- [Enabling Alerting for rancher-cis-benchmark](#enabling-alerting-for-rancher-cis-benchmark)
- [Configuring Alerts for a Periodic Scan on a Schedule](#configuring-alerts-for-a-periodic-scan-on-a-schedule)
- [Creating a Custom Benchmark Version for Running a Cluster Scan](#creating-a-custom-benchmark-version-for-running-a-cluster-scan)
### Changes in Rancher v2.5
# Changes in Rancher v2.5
We now support running CIS scans on any Kubernetes cluster, including hosted Kubernetes providers such as EKS, AKS, and GKE. Previously it was only supported to run CIS scans on RKE Kubernetes clusters.
@@ -32,8 +36,10 @@ In v1 of the CIS scan tool, which was available in Rancher v2.4 through the clus
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. From Rancher v2.5.4 onwards, the following profiles are available:
In Rancher v2.4, permissive and hardened profiles were included. In Rancher v2.5.0 and in v2.5.4, more profiles were included.
{{% tabs %}}
{{% tab "Profiles in v2.5.4" %}}
- Generic CIS 1.5
- Generic CIS 1.6
- RKE permissive 1.5
@@ -44,17 +50,39 @@ More test profiles were added. In Rancher v2.4, permissive and hardened profiles
- GKE
- RKE2 permissive 1.5
- RKE2 permissive 1.5
{{% /tab %}}
{{% tab "Profiles in v2.5.0" %}}
- Generic CIS 1.5
- RKE permissive
- RKE hardened
- EKS
- GKE
{{% /tab %}}
{{% /tabs %}}
<br/>
The default profile depends on the type of cluster that will be scanned:
The default profile and the supported CIS benchmark version depends on the type of cluster that will be scanned and the Rancher version:
{{% tabs %}}
{{% tab "v2.5.4" %}}
- 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 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` now supports the CIS 1.6 Benchmark version since the release 2.5.4
The `rancher-cis-benchmark` supports the CIS 1.6 Benchmark version.
{{% /tab %}}
{{% tab "v2.5.0" %}}
- For RKE Kubernetes clusters, the RKE permissive 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.
> **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.**
The `rancher-cis-benchmark` supports the CIS 1.5 Benchmark version.
{{% /tab %}}
{{% /tabs %}}
> **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 <b>Tools > CIS Scans.</b>
# About the CIS Benchmark
@@ -65,80 +93,6 @@ CIS Benchmarks are best practices for the secure configuration of a target syste
The official Benchmark documents are available through the CIS website. The sign-up form to access the documents is
<a href="https://learn.cisecurity.org/benchmarks" target="_blank">here.</a>
# Installing rancher-cis-benchmark
1. In the Rancher UI, go to the **Cluster Explorer.**
1. Click **Apps.**
1. Click `rancher-cis-benchmark`.
1. Click **Install.**
**Result:** The CIS scan application is deployed on the Kubernetes cluster.
# Uninstalling rancher-cis-benchmark
1. From the **Cluster Explorer,** go to the top left dropdown menu and click **Apps & Marketplace.**
1. Click **Installed Apps.**
1. Go to the `cis-operator-system` namespace and check the boxes next to `rancher-cis-benchmark-crd` and `rancher-cis-benchmark`.
1. Click **Delete** and confirm **Delete.**
**Result:** The `rancher-cis-benchmark` application is uninstalled.
# Running a Scan
When a ClusterScan custom resource is created, it launches a new CIS scan on the cluster for the chosen ClusterScanProfile.
Note: There is currently a limitation of running only one CIS scan at a time for a cluster. If you create multiple ClusterScan custom resources, they will be run one after the other by the operator, and until one scan finishes, the rest of the ClusterScan custom resources will be in the "Pending" state.
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 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. Click **Create.**
**Result:** A report is generated with the scan results. To see the results, click the name of the scan that appears.
# Skipping Tests
CIS scans can be run using test profiles with user-defined skips.
To skip tests, you will create a custom CIS scan profile. A profile contains the configuration for the CIS scan, which includes the benchmark versions to use and any specific tests to skip in that benchmark.
1. In the **Cluster Explorer,** go to the top-left dropdown menu and click **CIS Benchmark.**
1. Click **Profiles.**
1. From here, you can create a profile in multiple ways. To make a new profile, click **Create** and fill out the form in the UI. To make a new profile based on an existing profile, go to the existing profile, click the three vertical dots, and click **Clone as YAML.** If you are filling out the form, add the tests to skip using the test IDs, using the relevant CIS Benchmark as a reference. If you are creating the new test profile as YAML, you will add the IDs of the tests to skip in the `skipTests` directive. You will also give the profile a name:
```yaml
apiVersion: cis.cattle.io/v1
kind: ClusterScanProfile
metadata:
annotations:
meta.helm.sh/release-name: clusterscan-operator
meta.helm.sh/release-namespace: cis-operator-system
labels:
app.kubernetes.io/managed-by: Helm
name: "<example-profile>"
spec:
benchmarkVersion: cis-1.5
skipTests:
- "1.1.20"
- "1.1.21"
```
1. Click **Create.**
**Result:** A new CIS scan profile is created.
When you [run a scan](#running-a-scan) that uses this profile, the defined tests will be skipped during the scan. The skipped tests will be marked in the generated report as `Skip`.
# Viewing Reports
To view the generated CIS scan reports,
1. In the **Cluster Explorer,** go to the top left dropdown menu and click **Cluster Explorer > CIS Benchmark.**
1. The **Scans** page will show the generated reports. To see a detailed report, go to a scan report and click the name.
One can download the report from the Scans list or from the scan detail page.
# About the Generated Report
Each scan generates a report can be viewed in the Rancher UI and can be downloaded in CSV format.
@@ -172,11 +126,27 @@ Refer to <a href="{{<baseurl>}}/rancher/v2.x/en/security/" target="_blank">the t
The following profiles are available:
- Generic CIS 1.5 (default)
{{% tabs %}}
{{% tab "Profiles in v2.5.4" %}}
- Generic CIS 1.5
- 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
{{% /tab %}}
{{% tab "Profiles in v2.5.0" %}}
- Generic CIS 1.5
- RKE permissive
- RKE hardened
- EKS
- GKE
{{% /tab %}}
{{% /tabs %}}
You also have the ability to customize a profile by saving a set of tests to skip.
@@ -207,48 +177,146 @@ For information about permissions, refer to <a href="{{<baseurl>}}/rancher/v2.x/
For more information about configuring the custom resources for the scans, profiles, and benchmark versions, refer to <a href="{{<baseurl>}}/rancher/v2.x/en/cis-scans/configuration" target="_blank">this page.</a>
# Running a Scan periodically on a schedule
# How-to Guides
Since Rancher v2.5.4, it is possible to run a ClusterScan on a schedule.
- [Installing rancher-cis-benchmark](#installing-rancher-cis-benchmark)
- [Uninstalling rancher-cis-benchmark](#uninstalling-rancher-cis-benchmark)
- [Running a Scan](#running-a-scan)
- [Running a Scan Periodically on a Schedule](#running-a-scan-periodically-on-a-schedule)
- [Skipping Tests](#skipping-tests)
- [Viewing Reports](#viewing-reports)
- [Enabling Alerting for rancher-cis-benchmark](#enabling-alerting-for-rancher-cis-benchmark)
- [Configuring Alerts for a Periodic Scan on a Schedule](#configuring-alerts-for-a-periodic-scan-on-a-schedule)
- [Creating a Custom Benchmark Version for Running a Cluster Scan](#creating-a-custom-benchmark-version-for-running-a-cluster-scan)
### Installing rancher-cis-benchmark
To run a scan on a schedule,
1. In the Rancher UI, go to the **Cluster Explorer.**
1. Click **Apps.**
1. Click `rancher-cis-benchmark`.
1. Click **Install.**
**Result:** The CIS scan application is deployed on the Kubernetes cluster.
### Uninstalling rancher-cis-benchmark
1. From the **Cluster Explorer,** go to the top left dropdown menu and click **Apps & Marketplace.**
1. Click **Installed Apps.**
1. Go to the `cis-operator-system` namespace and check the boxes next to `rancher-cis-benchmark-crd` and `rancher-cis-benchmark`.
1. Click **Delete** and confirm **Delete.**
**Result:** The `rancher-cis-benchmark` application is uninstalled.
### Running a Scan
When a ClusterScan custom resource is created, it launches a new CIS scan on the cluster for the chosen ClusterScanProfile.
Note: There is currently a limitation of running only one CIS scan at a time for a cluster. If you create multiple ClusterScan custom resources, they will be run one after the other by the operator, and until one scan finishes, the rest of the ClusterScan custom resources will be in the "Pending" state.
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 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.
**Result:** A report is generated with the scan results. To see the results, click the name of the scan that appears.
### Running a Scan Periodically on a Schedule
_Available as of v2.5.4_
# Enabling Alerting for rancher-cis-benchmark
To run a ClusterScan 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](https://en.wikipedia.org/wiki/Cron#CRON_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.
### Skipping Tests
CIS scans can be run using test profiles with user-defined skips.
To skip tests, you will create a custom CIS scan profile. A profile contains the configuration for the CIS scan, which includes the benchmark versions to use and any specific tests to skip in that benchmark.
1. In the **Cluster Explorer,** go to the top-left dropdown menu and click **CIS Benchmark.**
1. Click **Profiles.**
1. From here, you can create a profile in multiple ways. To make a new profile, click **Create** and fill out the form in the UI. To make a new profile based on an existing profile, go to the existing profile, click the three vertical dots, and click **Clone as YAML.** If you are filling out the form, add the tests to skip using the test IDs, using the relevant CIS Benchmark as a reference. If you are creating the new test profile as YAML, you will add the IDs of the tests to skip in the `skipTests` directive. You will also give the profile a name:
```yaml
apiVersion: cis.cattle.io/v1
kind: ClusterScanProfile
metadata:
annotations:
meta.helm.sh/release-name: clusterscan-operator
meta.helm.sh/release-namespace: cis-operator-system
labels:
app.kubernetes.io/managed-by: Helm
name: "<example-profile>"
spec:
benchmarkVersion: cis-1.5
skipTests:
- "1.1.20"
- "1.1.21"
```
1. Click **Create.**
**Result:** A new CIS scan profile is created.
When you [run a scan](#running-a-scan) that uses this profile, the defined tests will be skipped during the scan. The skipped tests will be marked in the generated report as `Skip`.
### Viewing Reports
To view the generated CIS scan reports,
1. In the **Cluster Explorer,** go to the top left dropdown menu and click **Cluster Explorer > CIS Benchmark.**
1. The **Scans** page will show the generated reports. To see a detailed report, go to a scan report and click the name.
One can download the report from the Scans list or from the scan detail page.
### Enabling Alerting for rancher-cis-benchmark
_Available as of v2.5.4_
Alerts can be configured to be sent out for a scan that runs on a schedule.
To configure alerts,
> **Prerequisite:**
>
> 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.]({{<baseurl>}}/rancher/v2.x/en/monitoring-alerting/v2.5/configuration/alertmanager/)
>
> While configuring the routes for `rancher-cis-benchmark` alerts, you can specify the matching using the key-value pair `job: rancher-cis-scan`.
1. While installing or upgrading the `rancher-cis-benchmark` application, set the following flag to `true` in `Values YAML`
While installing or upgrading the `rancher-cis-benchmark` application, set the following flag to `true` in the `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.]({{<baseurl>}}/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)
```yaml
alerts:
enabled: true
```
# Configuring Alerts for a periodic Scan on a schedule
### Configuring Alerts for a Periodic Scan on a Schedule
_Available as of v2.5.4_
From Rancher v2.5.4, it is possible to run a ClusterScan on a schedule.
A scheduled scan can also specify if you should receive alerts when the scan completes.
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.
- Alert on scan completion: This alert is sent out when the scan run finishes. The alert includes details including the ClusterScan's name and the ClusterScanProfile name.
- 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.
> **Prerequisites:**
>
> Please ensure that Rancher's Monitoring and Alerting app is installed and the Receivers and Routes are configured to send out alerts. Please check [this section.]({{<baseurl>}}/rancher/v2.x/en/monitoring-alerting/v2.5/configuration/alertmanager/)
>
> While configuring the routes for `rancher-cis-benchmark` alerts, you can specify the matching using the key-value pair `job: rancher-cis-scan`.
To configure alerts for a scan that runs on a schedule,
@@ -256,82 +324,21 @@ To configure alerts for a scan that runs 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. 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. Choose the option **Run scan on a schedule.**
1. Enter a valid [cron schedule expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) in the field **Schedule.**
1. Check the boxes next to the Alert types under **Alerting.**
1. Optional: 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 <a href="https://github.com/aquasecurity/kube-bench" target="_blank">kube-bench</a> tool.
The `rancher-cis-benchmark` application installs a few default Benchmark Versions which are listed under CIS Benchmark application menu.
### Creating a Custom Benchmark Version for Running a Cluster Scan
_Available as of v2.5.4_
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.
There could be some Kubernetes cluster setups that require custom configurations of the Benchmark tests. For example, the path to the Kubernetes config files or certs might be different than the standard location where the upstream CIS Benchmarks look for them.
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.
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 <a href="https://github.com/aquasecurity/kube-bench" target="_blank">kube-bench</a> 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 <namespace> foo --from-file=<path to directory foo>
```
## 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.
For details, see [this page.](./custom-benchmark)
content/rancher/v2.x/en/cis-scans/v2.5/custom-benchmark/_index.md
+82
View File
@@ -0,0 +1,82 @@
---
title: Creating a Custom Benchmark Version for Running a Cluster Scan
weight: 4
---
_Available as of v2.5.4_
Each Benchmark Version defines a set of test configuration files that define the CIS tests to be run by the <a href="https://github.com/aquasecurity/kube-bench" target="_blank">kube-bench</a> 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, the path to the Kubernetes config files or certs might be different than the standard location where the upstream CIS Benchmarks look for them.
It is now possible to create a custom Benchmark Version for running a cluster scan using the `rancher-cis-benchmark` application.
When a cluster scan is run, you need to select a Profile which points to a specific Benchmark Version.
Follow all the steps below to add a custom Benchmark Version and run a scan using it.
1. [Prepare the Custom Benchmark Version ConfigMap](#1-prepare-the-custom-benchmark-version-configmap)
2. [Add a Custom Benchmark Version to a Cluster](#2-add-a-custom-benchmark-version-to-a-cluster)
3. [Create a New Profile for the Custom Benchmark Version](#3-create-a-new-profile-for-the-custom-benchmark-version)
4. [Run a Scan Using the Custom Benchmark Version](#4-run-a-scan-using-the-custom-benchmark-version)
### 1. Prepare 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, suppose we want to add a custom Benchmark Version named `foo`.
1. Create a directory named `foo` and inside this directory, place all the config YAML files that the <a href="https://github.com/aquasecurity/kube-bench" target="_blank">kube-bench</a> tool looks for. 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. Add the Benchmark version name to the `target_mapping` section of the `config.yaml`:
```yaml
target_mapping:
"foo":
- "master"
- "node"
- "controlplane"
- "etcd"
- "policies"
```
1. Upload this directory to your Kubernetes Cluster by creating a ConfigMap:
```yaml
kubectl create configmap -n <namespace> foo --from-file=<path to directory foo>
```
### 2. Add a Custom Benchmark Version to a 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** and a description for your custom benchmark version.
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.**
### 3. Create a New Profile for the 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** and description. In this example, we name it `foo-profile`.
1. Choose the Benchmark Version `foo` from the dropdown.
1. Click **Create.**
### 4. Run a Scan Using the 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.
content/rancher/v2.x/en/cis-scans/v2.5/rbac/_index.md
+1
View File
@@ -11,6 +11,7 @@ This section describes the permissions required to use the rancher-cis-benchmark
The rancher-cis-benchmark is a cluster-admin only feature by default.
However, the `rancher-cis-benchmark` chart installs these two default `ClusterRoles`:
- cis-admin
- cis-view