Trivy Action

GitHub Action for Trivy

Table of Contents

• Usage
  • Scan CI Pipeline
  • Scan CI Pipeline (w/ Trivy Config)
  • Cache
  • Trivy Setup
  • Scanning a Tarball
  • Using Trivy with templates
  • Using Trivy with GitHub Code Scanning
  • Using Trivy to scan your Git repo
  • Using Trivy to scan your rootfs directories
  • Using Trivy to scan Infrastructure as Code
  • Using Trivy to generate SBOM
  • Using Trivy to scan your private registry
  • Using Trivy if you don't have code scanning enabled
• Customizing
  • inputs
  • Environment variables
  • Trivy config file

Usage

Scan CI Pipeline

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-20.04steps:
- name: Checkout codeuses: actions/checkout@v3
- name: Build an image from Dockerfilerun: docker build -t docker.io/my-organization/my-app:${{ github.sha }} .
- name: Run Trivy vulnerability scanneruses: aquasecurity/trivy-action@0.28.0with:
image-ref: 'docker.io/my-organization/my-app:${{ github.sha }}'format: 'table'exit-code: '1'ignore-unfixed: truevuln-type: 'os,library'severity: 'CRITICAL,HIGH'

Scan CI Pipeline (w/ Trivy Config)

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-20.04steps:
- name: Checkout codeuses: actions/checkout@v4
- name: Run Trivy vulnerability scanner in fs modeuses: aquasecurity/trivy-action@0.28.0with:
scan-type: 'fs'scan-ref: '.'trivy-config: trivy.yaml

In this case trivy.yaml is a YAML configuration that is checked in as part of the repo. Detailed information is available on the Trivy website but an example is as follows:

format: jsonexit-code: 1severity: CRITICALsecret:
config: config/trivy/secret.yaml

It is possible to define all options in the trivy.yaml file. Specifying individual options via the action are left for backward compatibility purposes. Defining the following is required as they cannot be defined with the config file:

• scan-ref: If using fs, repo scans.
• image-ref: If using image scan.
• scan-type: To define the scan type, e.g. image, fs, repo, etc.

Order of preference for options

Trivy uses Viper which has a defined precedence order for options. The order is as follows:

• GitHub Action flag
• Environment variable
• Config file
• Default

Cache

The action has a built-in functionality for caching and restoring the vulnerability DB, the Java DB and the checks bundle if they are downloaded during the scan. The cache is stored in the $GITHUB_WORKSPACE/.cache/trivy directory by default. The cache is restored before the scan starts and saved after the scan finishes.

It uses actions/cache under the hood but requires less configuration settings. The cache input is optional, and caching is turned on by default.

Disabling caching

If you want to disable caching, set the cache input to false, but we recommend keeping it enabled to avoid rate limiting issues.

 - name: Run Trivy scanner without cacheuses: aquasecurity/trivy-action@0.28.0with:
scan-type: 'fs'scan-ref: '.'cache: 'false'

Updating caches in the default branch

Please note that there are restrictions on cache access between branches in GitHub Actions. By default, a workflow can access and restore a cache created in either the current branch or the default branch (usually main or master). If you need to share caches across branches, you may need to create a cache in the default branch and restore it in the current branch.

To optimize your workflow, you can set up a cron job to regularly update the cache in the default branch. This allows subsequent scans to use the cached DB without downloading it again.

# Note: This workflow only updates the cache. You should create a separate workflow for your actual Trivy scans.# In your scan workflow, set TRIVY_SKIP_DB_UPDATE=true and TRIVY_SKIP_JAVA_DB_UPDATE=true.name: Update Trivy Cacheon:
schedule:
- cron: '0 0 * * *'# Run daily at midnight UTCworkflow_dispatch: # Allow manual triggeringjobs:
update-trivy-db:
runs-on: ubuntu-lateststeps:
- name: Setup orasuses: oras-project/setup-oras@v1
- name: Get current dateid: daterun: echo "date=$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
- name: Download and extract the vulnerability DBrun: | mkdir -p $GITHUB_WORKSPACE/.cache/trivy/db oras pull ghcr.io/aquasecurity/trivy-db:2 tar -xzf db.tar.gz -C $GITHUB_WORKSPACE/.cache/trivy/db rm db.tar.gz - name: Download and extract the Java DBrun: | mkdir -p $GITHUB_WORKSPACE/.cache/trivy/java-db oras pull ghcr.io/aquasecurity/trivy-java-db:1 tar -xzf javadb.tar.gz -C $GITHUB_WORKSPACE/.cache/trivy/java-db rm javadb.tar.gz - name: Cache DBsuses: actions/cache/save@v4with:
path: ${{ github.workspace }}/.cache/trivykey: cache-trivy-${{ steps.date.outputs.date }}

When running a scan, set the environment variables TRIVY_SKIP_DB_UPDATE and TRIVY_SKIP_JAVA_DB_UPDATE to skip the download process.

 - name: Run Trivy scanner without downloading DBsuses: aquasecurity/trivy-action@0.28.0with:
scan-type: 'image'scan-ref: 'myimage'env:
TRIVY_SKIP_DB_UPDATE: trueTRIVY_SKIP_JAVA_DB_UPDATE: true

Trivy Setup

By default the action calls aquasecurity/setup-trivy as the first step which installs the trivy version specified by the version input. If you have already installed trivy by other means, e.g. calling aquasecurity/setup-trivy directly, or are invoking this action multiple times then you can use the skip-setup-trivy input to disable this step.

Setting up Trivy Manually

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-20.04steps:
- name: Checkout codeuses: actions/checkout@v4
- name: Manual Trivy Setupuses: aquasecurity/setup-trivy@v0.2.0with:
cache: trueversion: v0.57.1
- name: Run Trivy vulnerability scanner in repo modeuses: aquasecurity/trivy-action@masterwith:
scan-type: 'fs'ignore-unfixed: trueformat: 'sarif'output: 'trivy-results.sarif'severity: 'CRITICAL'skip-setup-trivy: true

Skipping Setup when Calling Trivy Action multiple times

Another common use case is when a build calls this action multiple times, in this case we can set skip-setup-trivy to true on subsequent invocations e.g.

name: buildon:
push:
branches:
- mainpull_request:
jobs:
test:
runs-on: ubuntu-latestpermissions:
contents: readsteps:
- name: Check out Git repositoryuses: actions/checkout@v4# The first call to the action will invoke setup-trivy and install trivy
- name: Generate Trivy Vulnerability Reportuses: aquasecurity/trivy-action@masterwith:
scan-type: "fs"output: trivy-report.jsonformat: jsonscan-ref: .exit-code: 0
- name: Upload Vulnerability Scan Resultsuses: actions/upload-artifact@v4with:
name: trivy-reportpath: trivy-report.jsonretention-days: 30
- name: Fail build on High/Criticial Vulnerabilitiesuses: aquasecurity/trivy-action@masterwith:
scan-type: "fs"format: tablescan-ref: .severity: HIGH,CRITICALignore-unfixed: trueexit-code: 1# On a subsequent call to the action we know trivy is already installed so can skip thisskip-setup-trivy: true

Use non-default token to install Trivy

GitHub Enterprise Server (GHES) uses an invalid github.token for https://github.com server. Therefore, you can't install Trivy using the setup-trivy action.

To fix this problem, you need to overwrite the token for setup-trivy using token-setup-trivy input:

 - name: Run Trivy scanner without cacheuses: aquasecurity/trivy-action@0.28.0with:
scan-type: 'fs'scan-ref: '.'token-setup-trivy: ${{ secrets.GITHUB_PAT }}

GitHub even has create-github-app-token for similar cases.

Scanning a Tarball

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-20.04steps:
- name: Checkout codeuses: actions/checkout@v4
- name: Generate tarball from imagerun: | docker pull <your-docker-image> docker save -o vuln-image.tar <your-docker-image> - name: Run Trivy vulnerability scanner in tarball modeuses: aquasecurity/trivy-action@0.28.0with:
input: /github/workspace/vuln-image.tarseverity: 'CRITICAL,HIGH'

Using Trivy with templates

The action supports Trivy templates.

Use template input to specify path (remember to prefix the path with @) to template file.

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-24.04steps:
- name: Checkout codeuses: actions/checkout@v3
- name: Run Trivy vulnerability scanneruses: aquasecurity/trivy-action@0.28.0with:
scan-type: "fs"scan-ref: .format: 'template'template: "@path/to/my_template.tpl"

Default templates

Trivy has default templates.

By default, setup-trivy installs them into the $HOME/.local/bin/trivy-bin/contrib directory.

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-24.04steps:
- name: Checkout codeuses: actions/checkout@v3
- name: Run Trivy vulnerability scanneruses: aquasecurity/trivy-action@0.28.0with:
scan-type: "fs"scan-ref: .format: 'template'template: "@$HOME/.local/bin/trivy-bin/contrib/html.tpl"

Using Trivy with GitHub Code Scanning

If you have GitHub code scanning available you can use Trivy as a scanning tool as follows:

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-20.04steps:
- name: Checkout codeuses: actions/checkout@v4
- name: Build an image from Dockerfilerun: | docker build -t docker.io/my-organization/my-app:${{ github.sha }} . - name: Run Trivy vulnerability scanneruses: aquasecurity/trivy-action@0.28.0with:
image-ref: 'docker.io/my-organization/my-app:${{ github.sha }}'format: 'sarif'output: 'trivy-results.sarif'
- name: Upload Trivy scan results to GitHub Security tabuses: github/codeql-action/upload-sarif@v3with:
sarif_file: 'trivy-results.sarif'

You can find a more in-depth example here: https://github.com/aquasecurity/trivy-sarif-demo/blob/master/.github/workflows/scan.yml

If you would like to upload SARIF results to GitHub Code scanning even upon a non zero exit code from Trivy Scan, you can add the following to your upload step:

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-20.04steps:
- name: Checkout codeuses: actions/checkout@v4
- name: Build an image from Dockerfilerun: | docker build -t docker.io/my-organization/my-app:${{ github.sha }} . - name: Run Trivy vulnerability scanneruses: aquasecurity/trivy-action@0.28.0with:
image-ref: 'docker.io/my-organization/my-app:${{ github.sha }}'format: 'sarif'output: 'trivy-results.sarif'
- name: Upload Trivy scan results to GitHub Security tabuses: github/codeql-action/upload-sarif@v3if: always()with:
sarif_file: 'trivy-results.sarif'

See this for more details: https://docs.github.com/en/actions/learn-github-actions/expressions#always

Using Trivy to scan your Git repo

It's also possible to scan your git repos with Trivy's built-in repo scan. This can be handy if you want to run Trivy as a build time check on each PR that gets opened in your repo. This helps you identify potential vulnerablites that might get introduced with each PR.

If you have GitHub code scanning available you can use Trivy as a scanning tool as follows:

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-20.04steps:
- name: Checkout codeuses: actions/checkout@v4
- name: Run Trivy vulnerability scanner in repo modeuses: aquasecurity/trivy-action@0.28.0with:
scan-type: 'fs'ignore-unfixed: trueformat: 'sarif'output: 'trivy-results.sarif'severity: 'CRITICAL'
- name: Upload Trivy scan results to GitHub Security tabuses: github/codeql-action/upload-sarif@v3with:
sarif_file: 'trivy-results.sarif'

Using Trivy to scan your rootfs directories

It's also possible to scan your rootfs directories with Trivy's built-in rootfs scan. This can be handy if you want to run Trivy as a build time check on each PR that gets opened in your repo. This helps you identify potential vulnerablites that might get introduced with each PR.

If you have GitHub code scanning available you can use Trivy as a scanning tool as follows:

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-20.04steps:
- name: Checkout codeuses: actions/checkout@v4
- name: Run Trivy vulnerability scanner with rootfs commanduses: aquasecurity/trivy-action@0.28.0with:
scan-type: 'rootfs'scan-ref: 'rootfs-example-binary'ignore-unfixed: trueformat: 'sarif'output: 'trivy-results.sarif'severity: 'CRITICAL'
- name: Upload Trivy scan results to GitHub Security tabuses: github/codeql-action/upload-sarif@v3with:
sarif_file: 'trivy-results.sarif'

Using Trivy to scan Infrastructure as Code

It's also possible to scan your IaC repos with Trivy's built-in repo scan. This can be handy if you want to run Trivy as a build time check on each PR that gets opened in your repo. This helps you identify potential vulnerablites that might get introduced with each PR.

If you have GitHub code scanning available you can use Trivy as a scanning tool as follows:

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-20.04steps:
- name: Checkout codeuses: actions/checkout@v4
- name: Run Trivy vulnerability scanner in IaC modeuses: aquasecurity/trivy-action@0.28.0with:
scan-type: 'config'hide-progress: trueformat: 'sarif'output: 'trivy-results.sarif'exit-code: '1'severity: 'CRITICAL,HIGH'
- name: Upload Trivy scan results to GitHub Security tabuses: github/codeql-action/upload-sarif@v3with:
sarif_file: 'trivy-results.sarif'

Using Trivy to generate SBOM

It's possible for Trivy to generate an SBOM of your dependencies and submit them to a consumer like GitHub Dependency Graph.

The sending of an SBOM to GitHub feature is only available if you currently have GitHub Dependency Graph enabled in your repo.

In order to send results to GitHub Dependency Graph, you will need to create a GitHub PAT or use the GitHub installation access token (also known as GITHUB_TOKEN):

---
name: Pull Requeston:
push:
branches:
- main## GITHUB_TOKEN authentication, add only if you're not going to use a PATpermissions:
contents: writejobs:
build:
name: Checksruns-on: ubuntu-20.04steps:
- name: Checkout codeuses: actions/checkout@v4
- name: Run Trivy in GitHub SBOM mode and submit results to Dependency Graphuses: aquasecurity/trivy-action@0.28.0with:
scan-type: 'fs'format: 'github'output: 'dependency-results.sbom.json'image-ref: '.'github-pat: ${{ secrets.GITHUB_TOKEN }} # or ${{ secrets.github_pat_name }} if you're using a PAT

When scanning images you may want to parse the actual output JSON as Github Dependency doesn't show all details like the file path of each dependency for instance.

You can upload the report as an artifact and download it, for instance using the upload-artifact action:

---
name: Pull Requeston:
push:
branches:
- main## GITHUB_TOKEN authentication, add only if you're not going to use a PATpermissions:
contents: writejobs:
build:
name: Checksruns-on: ubuntu-20.04steps:
- name: Scan image in a private registryuses: aquasecurity/trivy-action@0.28.0with:
image-ref: "private_image_registry/image_name:image_tag"scan-type: imageformat: 'github'output: 'dependency-results.sbom.json'github-pat: ${{ secrets.GITHUB_TOKEN }} # or ${{ secrets.github_pat_name }} if you're using a PATseverity: "MEDIUM,HIGH,CRITICAL"scanners: "vuln"env:
TRIVY_USERNAME: "image_registry_admin_username"TRIVY_PASSWORD: "image_registry_admin_password"
- name: Upload trivy report as a Github artifactuses: actions/upload-artifact@v4with:
name: trivy-sbom-reportpath: '${{ github.workspace }}/dependency-results.sbom.json'retention-days: 20# 90 is the default

Using Trivy to scan your private registry

It's also possible to scan your private registry with Trivy's built-in image scan. All you have to do is set ENV vars.

Docker Hub registry

Docker Hub needs TRIVY_USERNAME and TRIVY_PASSWORD. You don't need to set ENV vars when downloading from a public repository.

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-20.04steps:
- name: Checkout codeuses: actions/checkout@v4
- name: Run Trivy vulnerability scanneruses: aquasecurity/trivy-action@0.28.0with:
image-ref: 'docker.io/my-organization/my-app:${{ github.sha }}'format: 'sarif'output: 'trivy-results.sarif'env:
TRIVY_USERNAME: UsernameTRIVY_PASSWORD: Password
- name: Upload Trivy scan results to GitHub Security tabuses: github/codeql-action/upload-sarif@v3with:
sarif_file: 'trivy-results.sarif'

AWS ECR (Elastic Container Registry)

Trivy uses AWS SDK. You don't need to install aws CLI tool. You can use AWS CLI's ENV Vars.

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-20.04steps:
- name: Checkout codeuses: actions/checkout@v4
- name: Run Trivy vulnerability scanneruses: aquasecurity/trivy-action@0.28.0with:
image-ref: 'aws_account_id.dkr.ecr.region.amazonaws.com/imageName:${{ github.sha }}'format: 'sarif'output: 'trivy-results.sarif'env:
AWS_ACCESS_KEY_ID: key_idAWS_SECRET_ACCESS_KEY: access_keyAWS_DEFAULT_REGION: us-west-2
- name: Upload Trivy scan results to GitHub Security tabuses: github/codeql-action/upload-sarif@v3with:
sarif_file: 'trivy-results.sarif'

GCR (Google Container Registry)

Trivy uses Google Cloud SDK. You don't need to install gcloud command.

If you want to use target project's repository, you can set it via GOOGLE_APPLICATION_CREDENTIAL.

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-20.04steps:
- name: Checkout codeuses: actions/checkout@v4
- name: Run Trivy vulnerability scanneruses: aquasecurity/trivy-action@0.28.0with:
image-ref: 'docker.io/my-organization/my-app:${{ github.sha }}'format: 'sarif'output: 'trivy-results.sarif'env:
GOOGLE_APPLICATION_CREDENTIAL: /path/to/credential.json
- name: Upload Trivy scan results to GitHub Security tabuses: github/codeql-action/upload-sarif@v3with:
sarif_file: 'trivy-results.sarif'

Self-Hosted

BasicAuth server needs TRIVY_USERNAME and TRIVY_PASSWORD. if you want to use 80 port, use NonSSL TRIVY_NON_SSL=true

name: buildon:
push:
branches:
- mainpull_request:
jobs:
build:
name: Buildruns-on: ubuntu-20.04steps:
- name: Checkout codeuses: actions/checkout@v4
- name: Run Trivy vulnerability scanneruses: aquasecurity/trivy-action@0.28.0with:
image-ref: 'docker.io/my-organization/my-app:${{ github.sha }}'format: 'sarif'output: 'trivy-results.sarif'env:
TRIVY_USERNAME: UsernameTRIVY_PASSWORD: Password
- name: Upload Trivy scan results to GitHub Security tabuses: github/codeql-action/upload-sarif@v3with:
sarif_file: 'trivy-results.sarif'

Using Trivy if you don't have code scanning enabled

It's also possible to browse a scan result in a workflow summary.

This step is especially useful for private repositories without GitHub Advanced Security license.

- name: Run Trivy scanneruses: aquasecurity/trivy-action@0.28.0with:
scan-type: confighide-progress: trueoutput: trivy.txt
- name: Publish Trivy Output to Summaryrun: | if [[ -s trivy.txt ]]; then { echo "### Security Output" echo "<details><summary>Click to expand</summary>" echo "" echo '```terraform' cat trivy.txt echo '```' echo "</details>" } >> $GITHUB_STEP_SUMMARY fi

Customizing

Configuration priority:

• Inputs
• Environment variables
• Trivy config file
• Default values

inputs

Following inputs can be used as step.with keys:

Name	Type	Default	Description
scan-type	String	image	Scan type, e.g. image or fs
input	String		Tar reference, e.g. alpine-latest.tar
image-ref	String		Image reference, e.g. alpine:3.10.2
scan-ref	String	/github/workspace/	Scan reference, e.g. /github/workspace/ or .
format	String	table	Output format (table, json, template, sarif, cyclonedx, spdx, spdx-json, github, cosign-vuln)
template	String		Output template (@$HOME/.local/bin/trivy-bin/contrib/gitlab.tpl, @$HOME/.local/bin/trivy-bin/contrib/junit.tpl)
tf-vars	String		path to Terraform variables file
output	String		Save results to a file
exit-code	String	0	Exit code when specified vulnerabilities are found
ignore-unfixed	Boolean	false	Ignore unpatched/unfixed vulnerabilities
vuln-type	String	os,library	Vulnerability types (os,library)
severity	String	UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL	Severities of vulnerabilities to scanned for and displayed
skip-dirs	String		Comma separated list of directories where traversal is skipped
skip-files	String		Comma separated list of files where traversal is skipped
cache-dir	String	$GITHUB_WORKSPACE/.cache/trivy	Cache directory. NOTE: This value cannot be configured by trivy.yaml.
timeout	String	5m0s	Scan timeout duration
ignore-policy	String		Filter vulnerabilities with OPA rego language
hide-progress	String	false	Suppress progress bar and log output
list-all-pkgs	String		Output all packages regardless of vulnerability
scanners	String	vuln,secret	comma-separated list of what security issues to detect (vuln,secret,misconfig,license)
trivyignores	String		comma-separated list of relative paths in repository to one or more .trivyignore files
trivy-config	String		Path to trivy.yaml config
github-pat	String		Authentication token to enable sending SBOM scan results to GitHub Dependency Graph. Can be either a GitHub Personal Access Token (PAT) or GITHUB_TOKEN
limit-severities-for-sarif	Boolean	false	By default SARIF format enforces output of all vulnerabilities regardless of configured severities. To override this behavior set this parameter to true
docker-host	String		By default it is set to unix://var/run/docker.sock, but can be updated to help with containerized infrastructure values
version	String	v0.57.1	Trivy version to use, e.g. latest or v0.57.1
skip-setup-trivy	Boolean	false	Skip calling the setup-trivy action to install trivy
token-setup-trivy	Boolean		Overwrite github.token used by setup-trivy to checkout the trivy repository

Environment variables

You can use Trivy environment variables to set the necessary options (including flags that are not supported by Inputs, such as --secret-config).

Trivy config file

When using the trivy-configInput, you can set options using the Trivy config file (including flags that are not supported by Inputs, such as --secret-config).