Add documentation about vulnerability database persistence (#267)

* fix: avoid applying trivy Job if vulnerability scan is disabled

* fix: avoid applying trivy PVC if vulnerability scan is disabled

* update descriptions of some persistence variables

* add documentation about vulnerability database persistence

* update trivy page

* link trivy page

charts/zora/README.md

@@ -121,8 +121,8 @@ The following table lists the configurable parameters of the Zora chart and thei
 | scan.plugins.trivy.timeout | string | `"10m"` | Trivy timeout |
 | scan.plugins.trivy.insecure | bool | `false` | Allow insecure server connections for Trivy |
 | scan.plugins.trivy.persistence.enabled | bool | `true` | Specifies whether Trivy vulnerabilities database should be persisted between the scans, using PersistentVolumeClaim |
-| scan.plugins.trivy.persistence.accessMode | string | `"ReadWriteOnce"` | Persistence access mode |
-| scan.plugins.trivy.persistence.storageClass | string | `""` | Persistence storage class. Let it empty for default storage class |
+| scan.plugins.trivy.persistence.accessMode | string | `"ReadWriteOnce"` | [Persistence access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) |
+| scan.plugins.trivy.persistence.storageClass | string | `""` | [Persistence storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/). Set to empty for default storage class |
 | scan.plugins.trivy.persistence.storageRequest | string | `"1Gi"` | Persistence storage size |
 | scan.plugins.trivy.persistence.downloadJavaDB | bool | `false` | Specifies whether Java vulnerability database should be downloaded on helm install/upgrade |
 | scan.plugins.popeye.skipInternalResources | bool | `false` | Specifies whether the following resources should be skipped by `popeye` scans. 1. resources from `kube-system`, `kube-public` and `kube-node-lease` namespaces; 2. kubernetes system reserved RBAC (prefixed with `system:`); 3. `kube-root-ca.crt` configmaps; 4. `default` namespace; 5. `default` serviceaccounts; 6. Helm secrets (prefixed with `sh.helm.release`); 7. Zora components. See `popeye` configuration file that is used for this case: https://github.com/undistro/zora/blob/main/charts/zora/templates/plugins/popeye-config.yaml |

charts/zora/templates/plugins/trivy-job.yaml

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-{{- if .Values.scan.plugins.trivy.persistence.enabled }}
+{{- if and .Values.scan.plugins.trivy.persistence.enabled .Values.scan.vulnerability.enabled }}
 apiVersion: batch/v1
 kind: Job
 metadata:

charts/zora/templates/plugins/trivy-pvc.yaml

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-{{- if .Values.scan.plugins.trivy.persistence.enabled }}
+{{- if and .Values.scan.plugins.trivy.persistence.enabled .Values.scan.vulnerability.enabled }}
 apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:

charts/zora/values.yaml

@@ -232,9 +232,9 @@ scan:
       persistence:
         # -- Specifies whether Trivy vulnerabilities database should be persisted between the scans, using PersistentVolumeClaim
         enabled: true
-        # -- Persistence access mode
+        # -- [Persistence access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes)
         accessMode: ReadWriteOnce
-        # -- Persistence storage class. Let it empty for default storage class
+        # -- [Persistence storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/). Set to empty for default storage class
         storageClass: ""
         # -- Persistence storage size
         storageRequest: 1Gi

docs/configuration/vulnerability-database-persistence.md

@@ -0,0 +1,28 @@
+# Vulnerability Database Persistence
+
+[Trivy](../plugins/trivy.md) utilizes a database containing vulnerability information in its scan. 
+[This database is updated every **6 hours**](https://aquasecurity.github.io/trivy/v0.50/docs/scanner/vulnerability/#database).
+
+When scanning JAR files, Trivy downloads a specific database for Java every **3 days**.
+
+Both databases are distributed via [GitHub Container registry (GHCR)](https://ghcr.io/aquasecurity/trivy-db) and cached 
+by Trivy in local file system.
+
+Starting with version 0.8.4, Zora persists Trivy databases by default, caching them between the scheduled scans. 
+This means that scheduled scans may not need to download the databases, saving compute resources, time, and networking.
+
+It's done by applying a [PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) during 
+a Zora installation/upgrade through Helm. A Job is also applied, which just downloads the vulnerability database to be 
+ready for the first scheduled scan.
+
+This persistence can be disabled or configured with the following Helm parameters:
+
+| Key                                           | Type   | Default           | Description                                                                                                                       |
+|-----------------------------------------------|--------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| scan.plugins.trivy.persistence.enabled        | bool   | `true`            | Specifies whether Trivy vulnerabilities database should be persisted between the scans, using PersistentVolumeClaim               |
+| scan.plugins.trivy.persistence.accessMode     | string | `"ReadWriteOnce"` | [Persistence access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes)                           |
+| scan.plugins.trivy.persistence.storageClass   | string | `""`              | [Persistence storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/). Set to empty for default storage class |
+| scan.plugins.trivy.persistence.storageRequest | string | `"1Gi"`           | Persistence storage size                                                                                                          |
+| scan.plugins.trivy.persistence.downloadJavaDB | bool   | `false`           | Specifies whether Java vulnerability database should be downloaded on helm install/upgrade                                        |
+
+These parameters can be specified using the `--set key=value` argument in `helm upgrade --install` command.

docs/plugins/trivy.md

@@ -15,6 +15,14 @@ in different targets like containers, code repositories and **Kubernetes cluster
 
 :simple-github: **GitHub repository**: [https://github.com/aquasecurity/trivy](https://github.com/aquasecurity/trivy){:target="_blank"}
 
+## Vulnerability Database Persistence
+
+Trivy utilizes a database containing vulnerability information. 
+This database is updated every **6 hours** and persisted by default for caching purposes between the schedule scans.
+
+Please refer to [this page](../configuration/vulnerability-database-persistence.md) for further details and 
+configuration options regarding vulnerability database persistence.
+
 ## Large vulnerability reports
 
 Vulnerability reports can be large.
@@ -35,7 +43,7 @@ The `ClusterScan` will have a `Failed` status. You will see a log entry similar
 ## Scan timeout
 
 Trivy's scan duration may vary depending on the total images in your cluster 
-and the time to download the vulnerability database during each scan. 
+and the time to download the vulnerability database when needed. 
 
 By default, Zora sets a timeout of **10 minutes** for Trivy scan completion.
 

mkdocs.yml

@@ -90,6 +90,7 @@ nav:
           - Ignore unfixed vulnerabilities: plugins/trivy/#large-vulnerability-reports
           - Vulnerability scan timeout: plugins/trivy/#scan-timeout
           - Authenticated registries: configuration/authenticated-registries.md
+          - Vulnerability database persistence: configuration/vulnerability-database-persistence.md
           - Private registries:
               - AWS ECR: configuration/private-registries/ecr.md
               - Azure ACR: configuration/private-registries/acr.md