docs: add kbom documentation

aquasecurity · Oct 11, 2023 · 86ac011 · 86ac011
1 parent 20ab703
commit 86ac011
Show file tree

Hide file tree

Showing 6 changed files with 190 additions and 119 deletions.
diff --git 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)
+- [IaC files](iac/index.md)
+- [Kubernetes clusters](./kubernetes.md)
diff --git a/docs/docs/coverage/kubernetes.md b/docs/docs/coverage/kubernetes.md
@@ -0,0 +1,21 @@
+# 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).
+
+When scanning any of the above, Trivy differentiates between the Kubernetes Resource definition (i.e the YAML that defines it), and the container image if relevant.
+
+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
@@ -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
@@ -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, Trivy differentiates between the Kubernetes Resource definition (i.e the YAML that defines it), and the container image if relevant.
+
+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
 ```
 
 <details>
@@ -239,62 +270,10 @@ $ trivy k8s --format json -o results.json cluster
 
 </details>
 
-
-
-### 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=<compliance_id> --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=<compliance_id> --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=<compliance_id> --report summary --format json
+trivy k8s cluster --compliance=k8s-cis --report summary --format json
 ```
 
+Get detailed report in JSON format:
+
 ```
-trivy k8s cluster --compliance=<compliance_id> --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).
 
-<figure>
-  <figcaption>Workload reconcilers discover K8s controllers, manage scan jobs, and create VulnerabilityReport and ConfigAuditReport objects.</figcaption>
-</figure>
+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
+<details>
+<summary>Result</summary>
 
-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
-```
+</details>
+
+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.