Document Trivy functionality; #136

README.md

@@ -68,6 +68,7 @@ Jenkins Pipeline Shared library, that contains additional features for Git, Mave
 - [Markdown](#markdown)
     - [DockerLint (Deprecated)](#dockerlint-deprecated)
     - [ShellCheck](#shellcheck)
+- [Trivy](#trivy)
 - [Steps](#steps)
   - [mailIfStatusChanged](#mailifstatuschanged)
   - [isPullRequest](#ispullrequest)
@@ -1240,6 +1241,124 @@ shellCheck(fileList) // fileList="a.sh b.sh" execute shellcheck on a custom list
 
 See [shellCheck](vars/shellCheck.groovy)
 
+# Trivy
+
+Scan images for vulnerabilities with Trivy.
+
+## Create a Trivy object
+
+```groovy
+Trivy trivy = new Trivy(this)
+// With specific Trivy version
+Trivy trivy = new Trivy(this, "0.57.1")
+// With explicit Docker registry
+Docker docker = new Docker(this)
+docker.withRegistry("https://my.registry.invalid", myRegistryCredentialsID)
+Trivy trivy = new Trivy(this, "0.57.1", docker)
+```
+
+## Scan image with Trivy
+
+Scan an image with Trivy by calling the `scanImage` function.
+
+```groovy
+Trivy trivy = new Trivy(this)
+boolean imageIsSafe = trivy.scanImage("ubuntu:24.04")
+if (!imageIsSafe){
+    echo "This image has vulnerabilities!"
+}
+```
+
+### Set the severity level for the scan
+
+You can set the severity levels of the vulnerabilities Trivy should scan for as a parameter of the scan method:
+
+```groovy
+Trivy trivy = new Trivy(this)
+trivy.scanImage("ubuntu:24.04", TrivySeverityLevel.ALL)
+trivy.scanImage("ubuntu:24.04", "CRITICAL,LOW")
+```
+
+For the available pre-defined severity levels see [TrivySeverityLevel.groovy](src/com/cloudogu/ces/cesbuildlib/TrivySeverityLevel.groovy)
+
+### Set the pipeline strategy
+
+To define how the Jenkins pipeline should behave if vulnerabilities are found, you can set certain strategies:
+- TrivyScanStrategy.IGNORE: Ignore the vulnerabilities and continue
+- TrivyScanStrategy.UNSTABLE: Mark the job as "unstable" and continue
+- TrivyScanStrategy.FAIL: Mark the job as failed
+
+```groovy
+Trivy trivy = new Trivy(this)
+trivy.scanImage("ubuntu:24.04", TrivySeverityLevel.ALL, TrivyScanStrategy.UNSTABLE)
+```
+
+### Set additional Trivy flags
+
+To set additional Trivy command flags, use the `additionalFlags` parameter:
+
+```groovy
+Trivy trivy = new Trivy(this)
+trivy.scanImage("ubuntu:24.04", TrivySeverityLevel.ALL, TrivyScanStrategy.UNSTABLE, "--db-repository public.ecr.aws/aquasecurity/trivy-db")
+```
+
+Note that the flags "--db-repository public.ecr.aws/aquasecurity/trivy-db --java-db-repository public.ecr.aws/aquasecurity/trivy-java-db"
+are set by default to avoid rate limiting of Trivy database downloads.
+
+### Set the Trivy report file name
+
+If you want to run multiple image scans in one pipeline, you can set distinct file names for the report files:
+
+```groovy
+Trivy trivy = new Trivy(this)
+trivy.scanImage("ubuntu:20.04", TrivySeverityLevel.ALL, TrivyScanStrategy.UNSTABLE, "", "trivy/ubuntu20.json")
+trivy.scanImage("ubuntu:24.04", TrivySeverityLevel.ALL, TrivyScanStrategy.UNSTABLE, "", "trivy/ubuntu24.json")
+// Save report by using the same file name (last parameter)
+trivy.saveFormattedTrivyReport(TrivyScanFormat.HTML, "ubuntu20.04report", "trivy/ubuntu20.json")
+```
+
+## Save Trivy report in another file format
+
+After calling the `scanImage` function you can save the scan report as JSON, HTML or table files.
+
+```groovy
+Trivy trivy = new Trivy(this)
+trivy.scanImage("ubuntu:24.04")
+trivy.saveFormattedTrivyReport(TrivyScanFormat.TABLE)
+trivy.saveFormattedTrivyReport(TrivyScanFormat.JSON)
+trivy.saveFormattedTrivyReport(TrivyScanFormat.HTML)
+```
+
+## Ignore / allowlist
+
+If you want to ignore / allow certain vulnerabilities, please use a .trivyignore file
+Provide the file in your repo `/` directory where you run your job
+e.g.:
+```shell
+.gitignore
+Jenkinsfile
+.trivyignore
+```
+
+[Offical documentation](https://trivy.dev/v0.57/docs/configuration/filtering/#by-finding-ids)
+```ignorelang
+# Accept the risk
+CVE-2018-14618
+
+# Accept the risk until 2023-01-01
+CVE-2019-14697 exp:2023-01-01
+
+# No impact in our settings
+CVE-2019-1543
+
+# Ignore misconfigurations
+AVD-DS-0002
+
+# Ignore secrets
+generic-unwanted-rule
+aws-account-id
+```
+
 # Steps
 
 ## mailIfStatusChanged
@@ -1293,7 +1412,9 @@ For example, if running on `http(s)://server:port/jenkins`, `server` is returned
 
 Returns true if the build is successful, i.e. not failed or unstable (yet).
 
-## findVulnerabilitiesWithTrivy
+## findVulnerabilitiesWithTrivy (Deprecated)
+
+This function is deprecated. Use [Trivy](#trivy) functionality instead.
 
 Returns a list of vulnerabilities or an empty list if there are no vulnerabilities for the given severity.
 
@@ -1330,36 +1451,7 @@ node {
 }
 ```
 
-### Ignore / allowlist
-
-If you want to ignore / allow certain vulnerabilities please use a .trivyignore file
-Provide the file in your repo / directory where you run your job
-e.g.:
-```shell
-.gitignore
-Jenkinsfile
-.trivyignore
-```
-
-[Offical documentation](https://aquasecurity.github.io/trivy/v0.41/docs/configuration/filtering/#by-finding-ids)
-```ignorelang
-# Accept the risk
-CVE-2018-14618
-
-# Accept the risk until 2023-01-01
-CVE-2019-14697 exp:2023-01-01
 
-# No impact in our settings
-CVE-2019-1543
-
-# Ignore misconfigurations
-AVD-DS-0002
-
-# Ignore secrets
-generic-unwanted-rule
-aws-account-id
-
-```
 
 If there are vulnerabilities the output looks as follows.
 

src/com/cloudogu/ces/cesbuildlib/Trivy.groovy

@@ -7,10 +7,10 @@ class Trivy implements Serializable {
     private String trivyVersion
     private String trivyDirectory = "trivy"
 
-    Trivy(script, Docker docker = new Docker(script), String trivyVersion = "0.57.1") {
+    Trivy(script, String trivyVersion = "0.57.1", Docker docker = new Docker(script)) {
         this.script = script
-        this.docker = docker
         this.trivyVersion = trivyVersion
+        this.docker = docker
     }
 
     /**