diff --git a/docs/docs/coverage/index.md b/docs/docs/coverage/index.md index dbb06339c654..41637ef5a60b 100644 --- a/docs/docs/coverage/index.md +++ b/docs/docs/coverage/index.md @@ -5,4 +5,5 @@ For more detailed information about the specific platforms and languages, check - [OS Packages](os/index.md) - [Language-specific Packages](language/index.md) -- [IaC files](iac/index.md) \ No newline at end of file +- [IaC files](iac/index.md) +- [Kubernetes clusters](./kubernetes.md) \ No newline at end of file diff --git a/docs/docs/coverage/kubernetes.md b/docs/docs/coverage/kubernetes.md new file mode 100644 index 000000000000..66a144190bc7 --- /dev/null +++ b/docs/docs/coverage/kubernetes.md @@ -0,0 +1,22 @@ +# Kubernetes + +When scanning a Kubernetes cluster, Trivy differentiates between the following: + +1. Cluster infrastructure (e.g api-server, kubelet, addons) +1. Cluster configuration (e.g Roles, ClusterRoles). +1. Application workloads (e.g nginx, postgresql). + +Whenever Trivy scans either of these Kubernetes resources, the container image is scanned separately to the Kubernetes resource definition (the YAML manifest) that defines the resource. +When scanning any of the above, the container image is scanned separately to the Kubernetes resource definition (the YAML manifest) that defines the resource. + +Container image is scanned for: +- Vulnerabilities +- Misconfigurations +- Exposed secrets + +Kubernetes resource definition is scanned for: +- Vulnerabilities - partially supported through [KBOM scanning](#KBOM) +- Misconfigurations +- Exposed secrets + +To learn more, please see the [documentation for Kubernetes scanning](../target/kubernetes.md) diff --git a/docs/docs/scanner/vulnerability.md b/docs/docs/scanner/vulnerability.md index b6f200ec6b45..017d57510b65 100644 --- a/docs/docs/scanner/vulnerability.md +++ b/docs/docs/scanner/vulnerability.md @@ -6,6 +6,8 @@ The following packages are supported. - [OS packages](#os-packages) - [Language-specific packages](#language-specific-packages) +Trivy also detects known vulnerabilities in Kubernetes components using KBOM (Kubernetes bill of Material) scanning. To learn more, see the [documentation for Kubernetes scanning](../target/kubernetes.md#KBOM). + ## OS Packages Trivy is capable of automatically detecting installed OS packages when scanning container images, VM images and running hosts. @@ -98,6 +100,18 @@ See [here](../coverage/language/index.md#supported-languages) for the supported [^1]: Intentional delay between vulnerability disclosure and registration in the DB +## Kubernetes + +Trivy can detect vulnerabilities in Kubernetes clusters and components. + +### Data Sources + +| Vendor | Source | +| ------------- | ------------------------------------------------------------ | +| Kubernetes | [Kubernetes Official CVE feed][^1] | + +[^1]: Some manual triage and correction has been made. + ## Database Trivy downloads [the vulnerability database](https://github.com/aquasecurity/trivy-db) every 6 hours. Trivy uses two types of databases for vulnerability detection: @@ -180,3 +194,5 @@ Currently, specifying a username and password is not supported. [rust-osv]: https://osv.dev/list?q=&ecosystem=crates.io [nvd]: https://nvd.nist.gov/vuln + +[Kubernetes Official CVE feed]: https://kubernetes.io/docs/reference/issues-security/official-cve-feed/ diff --git a/docs/docs/target/kubernetes.md b/docs/docs/target/kubernetes.md index 894e9943e70d..c10546ed53f3 100644 --- a/docs/docs/target/kubernetes.md +++ b/docs/docs/target/kubernetes.md @@ -3,84 +3,115 @@ !!! warning "EXPERIMENTAL" This feature might change without preserving backwards compatibility. -## CLI -The Trivy K8s CLI allows you to scan your Kubernetes cluster for +Trivy can connect to your Kubernetes cluster and scan it for security issues using the `trivy k8s` command. This page covers the technical capabilities of Trivy Kubernetes scanning. +Trivy can also be installed *inside* your cluster as a Kubernetes Operator, and continuously scan it. For more about this, please see the [Trivy Operator][https://aquasecurity.github.io/trivy-operator/] project. +When scanning a Kubernetes cluster, Trivy differentiates between the following: + +1. Cluster infrastructure (e.g api-server, kubelet, addons) +1. Cluster configuration (e.g Roles, ClusterRoles). +1. Application workloads (e.g nginx, postgresql). + +When scanning any of the above, the container image is scanned separately to the Kubernetes resource definition (the YAML manifest) that defines the resource. + +Container image is scanned for: - Vulnerabilities - Misconfigurations -- Secrets - -You can either run the CLI locally or integrate it into your CI/CD pipeline. -The difference to the Trivy CLI is that the Trivy K8s CLI allows you to scan running workloads directly within your cluster. +- Exposed secrets -If you are looking for continuous cluster audit scanning, have a look at the Trivy K8s operator below. +Kubernetes resource definition is scanned for: +- Vulnerabilities - partially supported through [KBOM scanning](#KBOM) +- Misconfigurations +- Exposed secrets -Trivy uses your local kubectl configuration to access the API server to list artifacts. +## Kubernetes target configurations -### Commands +Trivy follows the behavior of the `kubectl` tool as much as possible. -Scan a full cluster and generate a simple summary report: +### Scope + +The command expects an argument that selects the scope of the scan (similarly to how `kubectl` expects an argument after `kubectl get`). This argument can be: +1. A Kubernetes Kind. e.g `pod`, `deployment`, etc. +2. A Kubernetes Resource. e.g `pods/mypod`, etc. +3. `all`. Scan common workload kinds, as listed [here](https://github.com/aquasecurity/trivy-kubernetes/blob/bf8cc2a00d9772e0aa271f06d375b936152b54b1/pkg/k8s/k8s.go#L296:L314) +4. `cluster` scan the entire cluster including all namespaced resources and cluster level resources. + +Examples: ``` -$ trivy k8s --report=summary cluster +trivy k8s all +trivy k8s pods +trivy k8s deploy myapp +trivy k8s pod/mypod +trivy k8s pods,deploy +trivy k8s cluster ``` -![k8s Summary Report](../../imgs/trivy-k8s.png) +Note that the scope argument must appear last in the command line, after any other flag. -The summary report is the default. To get all of the detail the output contains, use `--report all`. +### Cluster -Filter by severity: +By default Trivy will look for a [`kubeconfig` configuration file in the default location](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/), and use the default cluster that is specified. +You can also specify a `kubeconfig` using the `--kubeconfig` flag: ``` -$ trivy k8s --severity=CRITICAL --report=all cluster +trivy k8s --kubeconfig ~/.kube/config2 ``` -Filter by scanners (Vulnerabilities, Secrets or Misconfigurations): +### Namespace + +By default Trivy will scan all namespaces (following `kubectl` behavior). To specify a namespace use the `--namespace` flag: ``` -$ trivy k8s --scanners=secret --report=summary cluster -# or -$ trivy k8s --scanners=config --report=summary cluster +trivy k8s --kubeconfig ~/.kube/config2 --namespace default ``` +### Node -Scan a specific namespace: +You can exclude specific nodes from the scan using the `--exclude-nodes` flag, which takes a label in the format `label-name:label-value` and excludes all matching nodes: ``` -$ trivy k8s -n kube-system --report=summary all +trivy k8s cluster --report summary --exclude-nodes kubernetes.io/arch:arm6 ``` -Use a specific kubeconfig file: +### Components types -``` -$ trivy k8s --kubeconfig ~/.kube/config2 -n kube-system --report=summary all -``` +You can control what kinds of components are discovered using the `--components` flag: +- `--components infra` will discover only cluster infrastructure components. +- `--components workloads` will discover only application workloads. +- If the flag is omitted: infra, workloads, and RBAC are discovered. + +## Reporting and filtering + +Since scanning an entire cluster for any security issue can be overwhelming, By default Trivy summarizes the results in a simple "summary" view. +By scoping the scan on a specific resource, you can see the detailed report. +You can always choose the report granularity using the `--report summary`/`--report all` flag. -Scan a specific resource and get all the output: +Scan a full cluster and generate a simple summary report: ``` -$ trivy k8s deployment appname +$ trivy k8s --report=summary cluster ``` -Scan all deploys, or deploys and configmaps: +![k8s Summary Report](../../imgs/trivy-k8s.png) + +Filter by severity: ``` -$ trivy k8s --report=summary deployment -$ trivy k8s --report=summary deployment,configmaps +trivy k8s --severity=CRITICAL --report=all cluster ``` -If you want to pass in flags before scanning specific workloads, you will have to do it before the resource name. -For example, scanning a deployment in the app namespace of your Kubernetes cluster for critical vulnerabilities would be done through the following command: +Filter by scanners (Vulnerabilities, Secrets or Misconfigurations): ``` -$ trivy k8s -n app --severity=CRITICAL deployment/appname +trivy k8s --scanners=secret --report=summary cluster +# or +trivy k8s --scanners=config --report=summary cluster ``` -This is specific to all Trivy CLI commands. -The supported formats are `table`, which is the default, and `json`. -To get a JSON output on a full cluster scan: +The supported output formats are `table`, which is the default, and `json`. ``` -$ trivy k8s --format json -o results.json cluster +trivy k8s --format json -o results.json cluster ```
@@ -239,62 +270,10 @@ $ trivy k8s --format json -o results.json cluster
- - -### Infra checks - -Trivy by default scans kubernetes infra components (apiserver, controller-manager, scheduler and etcd) -if they exist under the `kube-system` namespace. For example, if you run a full cluster scan, or scan all -components under `kube-system` with commands: - -``` -$ trivy k8s cluster --report summary # full cluster scan -$ trivy k8s all -n kube-system --report summary # scan all components under kube-system -``` - -A table will be printed about misconfigurations found on kubernetes core components: - -``` -Summary Report for minikube -┌─────────────┬──────────────────────────────────────┬─────────────────────────────┐ -│ Namespace │ Resource │ Kubernetes Infra Assessment │ -│ │ ├────┬────┬────┬─────┬────────┤ -│ │ │ C │ H │ M │ L │ U │ -├─────────────┼──────────────────────────────────────┼────┼────┼────┼─────┼────────┤ -│ kube-system │ Pod/kube-apiserver-minikube │ │ │ 1 │ 10 │ │ -│ kube-system │ Pod/kube-controller-manager-minikube │ │ │ │ 3 │ │ -│ kube-system │ Pod/kube-scheduler-minikube │ │ │ │ 1 │ │ -└─────────────┴──────────────────────────────────────┴────┴────┴────┴─────┴────────┘ -Severities: C=CRITICAL H=HIGH M=MEDIUM L=LOW U=UNKNOWN -``` - -The infra checks are based on CIS Benchmarks recommendations for kubernetes. - - -If you want filter only for the infra checks, you can use the flag `--components` along with the `--scanners=config` - -``` -$ trivy k8s cluster --report summary --components=infra --scanners=config # scan only infra -``` - -Or, to filter for all other checks besides the infra checks, you can: - -``` -$ trivy k8s cluster --report summary --components=workload --scanners=config # scan all components besides infra -``` - -If you wish to exclude nodes from being scanned, you can use the flag `--exclude-nodes` with the node labels - -``` -trivy k8s cluster --report summary --exclude-nodes kubernetes.io/arch:arm6 -``` - -### Compliance +## Compliance This section describes Kubernetes specific compliance reports. For an overview of Trivy's Compliance feature, including working with custom compliance, check out the [Compliance documentation](../compliance/compliance.md). -#### Built in reports - The following reports are available out of the box: | Compliance | Name for command | More info | @@ -304,55 +283,77 @@ The following reports are available out of the box: | Pod Security Standards, Baseline | `k8s-pss-baseline` | [Link](https://kubernetes.io/docs/concepts/security/pod-security-standards/#baseline) | | Pod Security Standards, Restricted | `k8s-pss-restricted` | [Link](https://kubernetes.io/docs/concepts/security/pod-security-standards/#restricted) | -#### Examples +Examples: -Scan a full cluster and generate a compliance summary report: +Scan the cluster for Kubernetes Pod Security Standards Baseline compliance: ``` -$ trivy k8s cluster --compliance= --report summary +trivy k8s cluster --compliance=k8s-pss-baseline --report summary ``` -***Note*** : The `Issues` column represent the total number of failed checks for this control. - - -Get all of the detailed output for checks: +Get the detailed report for checks: ``` -trivy k8s cluster --compliance= --report all +trivy k8s cluster --compliance=k8s-cis --report all ``` -Report result in JSON format: +Get summary report in JSON format: ``` -trivy k8s cluster --compliance= --report summary --format json +trivy k8s cluster --compliance=k8s-cis --report summary --format json ``` +Get detailed report in JSON format: + ``` -trivy k8s cluster --compliance= --report all --format json +trivy k8s cluster --compliance=k8s-cis --report all --format json ``` -## Operator -Trivy has a native [Kubernetes Operator][operator] which continuously scans your Kubernetes cluster for security issues, and generates security reports as Kubernetes [Custom Resources][crd]. It does it by watching Kubernetes for state changes and automatically triggering scans in response to changes, for example initiating a vulnerability scan when a new Pod is created. +## KBOM -> Kubernetes-native security toolkit. ([Documentation][trivy-operator]). +KBOM, Kubernetes Bill of Materials, is a manifest of all the important components that make up your Kubernetes cluster – Control plane components, Node Components, and Addons, including their versions and images. Which “api-server” version are you currently running? Which flavor of "kubelet" is running on each node? What kind of etcd or storage are you currently using? And most importantly – are there any vulnerabilities known to affect these components? These are all questions that KBOM can help you answer. +For more background on KBOM, see [here](https://blog.aquasec.com/introducing-kbom-kubernetes-bill-of-materials). -
-
Workload reconcilers discover K8s controllers, manage scan jobs, and create VulnerabilityReport and ConfigAuditReport objects.
-
+Trivy can generate KBOM in CycloneDX format: -[operator]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/ -[crd]: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/ -[trivy-operator]: https://aquasecurity.github.io/trivy-operator/latest +```sh +trivy k8s cluster --format cyclonedx --output mykbom.cdx.json +``` -## SBOM +Trivy can also scan that generated KBOM (or any SBOM) for vulnerabilities: -Trivy supports the generation of Kubernetes Bill of Materials (KBOM) for kubernetes cluster control plane components, node components and addons. +```sh +trivy sbom mykbom.cdx.json +``` -## KBOM +
+Result -KBOM, Kubernetes Bill of Materials, is a manifest of all the important components that make up your Kubernetes cluster – Control plane components, Node Components, and Addons, including their versions and images. Which “api-server” version are you currently running? Which flavor of “kubelet” is running on each node? What kind of etcd or storage are you currently using? And most importantly – are there any vulnerabilities known to affect these components? These are all questions that KBOM can help you answer. -Trivy can generate KBOM in CycloneDX format: +``` +2023-09-28T22:52:25.707+0300 INFO Vulnerability scanning is enabled + 2023-09-28T22:52:25.707+0300 INFO Detected SBOM format: cyclonedx-json + 2023-09-28T22:52:25.717+0300 WARN No OS package is detected. Make sure you haven't deleted any files that contain information about the installed packages. + 2023-09-28T22:52:25.717+0300 WARN e.g. files under "/lib/apk/db/", "/var/lib/dpkg/" and "/var/lib/rpm" + 2023-09-28T22:52:25.717+0300 INFO Detected OS: debian gnu/linux + 2023-09-28T22:52:25.717+0300 WARN unsupported os : debian gnu/linux + 2023-09-28T22:52:25.717+0300 INFO Number of language-specific files: 3 + 2023-09-28T22:52:25.717+0300 INFO Detecting kubernetes vulnerabilities... + 2023-09-28T22:52:25.718+0300 INFO Detecting gobinary vulnerabilities... + Kubernetes (kubernetes) + Total: 2 (UNKNOWN: 0, LOW: 1, MEDIUM: 0, HIGH: 1, CRITICAL: 0) + ┌────────────────┬────────────────┬──────────┬────────┬───────────────────┬─────────────────────────────────┬──────────────────────────────────────────────────┐ + │ Library │ Vulnerability │ Severity │ Status │ Installed Version │ Fixed Version │ Title │ + ├────────────────┼────────────────┼──────────┼────────┼───────────────────┼─────────────────────────────────┼──────────────────────────────────────────────────┤ + │ k8s.io/kubelet │ CVE-2021-25749 │ HIGH │ fixed │ 1.24.0 │ 1.22.14, 1.23.11, 1.24.5 │ runAsNonRoot logic bypass for Windows containers │ + │ │ │ │ │ │ │ https://avd.aquasec.com/nvd/cve-2021-25749 │ + │ ├────────────────┼──────────┤ │ ├─────────────────────────────────┼──────────────────────────────────────────────────┤ + │ │ CVE-2023-2431 │ LOW │ │ │ 1.24.14, 1.25.9, 1.26.4, 1.27.1 │ Bypass of seccomp profile enforcement │ + │ │ │ │ │ │ │ https://avd.aquasec.com/nvd/cve-2023-2431 │ + └────────────────┴────────────────┴──────────┴────────┴───────────────────┴─────────────────────────────────┴──────────────────────────────────────────────────┘ +``` -```sh -trivy k8s cluster --format cyclonedx -``` \ No newline at end of file +
+ +Find more in the [documentation for SBOM scanning](./sbom.md). + +Currently KBOM vulnerability matching works for plain Kubernetes distributions and does not work well for vendor variants, including some cloud managed distributions. diff --git a/docs/docs/target/sbom.md b/docs/docs/target/sbom.md index 69a2ba4db88b..21670f2d3d85 100644 --- a/docs/docs/target/sbom.md +++ b/docs/docs/target/sbom.md @@ -5,6 +5,7 @@ Trivy can take the following SBOM formats as an input and scan for vulnerabiliti - SPDX - SPDX JSON - CycloneDX-type attestation +- [KBOM](./kubernetes.md#KBOM) in CycloneDX format To scan SBOM, you can use the `sbom` subcommand and pass the path to the SBOM. The input format is automatically detected. @@ -107,3 +108,33 @@ Total: 2 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 2) │ │ │ │ │ │ │ └────────────┴────────────────┴──────────┴───────────────────┴───────────────┴──────────────────────────────────────────────────────────┘ ``` + +## KBOM + +To read more about KBOM, see the [documentation for Kubernetes scanning](./kubernetes.md#KBOM). + +```shell + $ trivy k8s --format cyclonedx cluster -o kbom.json + $ trivy sbom kbom.json + 2023-09-28T22:52:25.707+0300 INFO Vulnerability scanning is enabled + 2023-09-28T22:52:25.707+0300 INFO Detected SBOM format: cyclonedx-json + 2023-09-28T22:52:25.717+0300 WARN No OS package is detected. Make sure you haven't deleted any files that contain information about the installed packages. + 2023-09-28T22:52:25.717+0300 WARN e.g. files under "/lib/apk/db/", "/var/lib/dpkg/" and "/var/lib/rpm" + 2023-09-28T22:52:25.717+0300 INFO Detected OS: debian gnu/linux + 2023-09-28T22:52:25.717+0300 WARN unsupported os : debian gnu/linux + 2023-09-28T22:52:25.717+0300 INFO Number of language-specific files: 3 + 2023-09-28T22:52:25.717+0300 INFO Detecting kubernetes vulnerabilities... + 2023-09-28T22:52:25.718+0300 INFO Detecting gobinary vulnerabilities... + Kubernetes (kubernetes) + Total: 2 (UNKNOWN: 0, LOW: 1, MEDIUM: 0, HIGH: 1, CRITICAL: 0) + ┌────────────────┬────────────────┬──────────┬────────┬───────────────────┬─────────────────────────────────┬──────────────────────────────────────────────────┐ + │ Library │ Vulnerability │ Severity │ Status │ Installed Version │ Fixed Version │ Title │ + ├────────────────┼────────────────┼──────────┼────────┼───────────────────┼─────────────────────────────────┼──────────────────────────────────────────────────┤ + │ k8s.io/kubelet │ CVE-2021-25749 │ HIGH │ fixed │ 1.24.0 │ 1.22.14, 1.23.11, 1.24.5 │ runAsNonRoot logic bypass for Windows containers │ + │ │ │ │ │ │ │ https://avd.aquasec.com/nvd/cve-2021-25749 │ + │ ├────────────────┼──────────┤ │ ├─────────────────────────────────┼──────────────────────────────────────────────────┤ + │ │ CVE-2023-2431 │ LOW │ │ │ 1.24.14, 1.25.9, 1.26.4, 1.27.1 │ Bypass of seccomp profile enforcement │ + │ │ │ │ │ │ │ https://avd.aquasec.com/nvd/cve-2023-2431 │ + └────────────────┴────────────────┴──────────┴────────┴───────────────────┴─────────────────────────────────┴──────────────────────────────────────────────────┘ + ``` + \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index c3e84f5f9162..59ad99752b37 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -108,6 +108,7 @@ nav: - Helm: docs/coverage/iac/helm.md - Kubernetes: docs/coverage/iac/kubernetes.md - Terraform: docs/coverage/iac/terraform.md + - Kubernetes: docs/coverage/kubernetes.md - Configuration: - Overview: docs/configuration/index.md - Filtering: docs/configuration/filtering.md