Trivy: Setup, Configuration, and Best Practices

Introduction to Trivy

Trivy (pronounced "trih-vee") is a comprehensive, open-source security scanner designed to find vulnerabilities, misconfigurations, secrets, and license issues in a wide array of targets. Developed by Aqua Security, Trivy has become a staple in the DevSecOps toolkit due to its speed, accuracy, and ease of use.

What is Trivy?

Trivy is a unified security scanning tool. Unlike traditional vulnerability scanners that focus solely on container images or operating system packages, Trivy can scan container images, file systems, Git repositories, Kubernetes clusters, and Infrastructure as Code (IaC) files like Terraform and CloudFormation. It detects known vulnerabilities (CVEs) in OS packages and language-specific dependencies, while also identifying hardcoded secrets (like API keys and passwords) and cloud misconfigurations.

Why Trivy Matters in Modern Development

In today's fast-paced software development lifecycle, security cannot be an afterthought. The rise of supply chain attacks has highlighted the need to secure every component of an application. Trivy matters because it allows developers to integrate security scanning directly into their workflows. By catching vulnerabilities and exposed secrets early—often before code is even committed—teams can remediate issues quickly, reduce risk, and maintain compliance without slowing down deployment pipelines.

Setting Up Trivy

Getting started with Trivy is straightforward. It is distributed as a single binary file, making installation simple across various operating systems.

Installation on macOS and Linux

For macOS users, the easiest way to install Trivy is via Homebrew. For Linux, you can use the official installation script or package managers depending on your distribution.

# macOS
brew install trivy

# Debian/Ubuntu
sudo apt-get install wget apt-transport-https gnupg lsb-release
wget -qO - https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sudo bash

Installation on Windows

Windows users can install Trivy using Chocolatey or Scoop, two popular package managers for Windows.

# Using Chocolatey
choco install trivy

# Using Scoop
scoop install trivy

Running Trivy via Docker

If you prefer not to install Trivy locally, you can run it as a Docker container. This is particularly useful for CI/CD pipelines where ephemeral runners are used.

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  -v $HOME/.cache:/root/.cache/ \
  aquasec/trivy:latest image your-image-name:latest

Basic Usage and Scanning

Trivy's command-line interface is designed to be intuitive. The first time you run a scan, Trivy will automatically download its vulnerability database. Subsequent scans will use this cached database, making them significantly faster.

Scanning Container Images

The most common use case for Trivy is scanning container images. It analyzes the image layers to find vulnerabilities in both the OS-level packages (like Alpine, Ubuntu, or CentOS packages) and application-level dependencies (like npm, pip, or gem packages).

trivy image node:18

You can also filter the output to only show high and critical vulnerabilities, which is useful for keeping your terminal output clean and focused on the most pressing issues.

trivy image --severity HIGH,CRITICAL node:18

Scanning File Systems and Repositories

Trivy can scan your local file system or a remote Git repository. This is excellent for catching vulnerabilities in your application dependencies before you even build a container image.

# Scan a local directory
trivy fs .

# Scan a remote Git repository
trivy repo https://github.com/aquasecurity/trivy

Scanning Kubernetes Clusters

Trivy can also scan your running Kubernetes cluster to find vulnerabilities in the deployed images and misconfigurations in your Kubernetes resources.

trivy k8s --report summary

Configuration and Customization

While Trivy works perfectly out of the box, it offers extensive configuration options to fit the specific needs of your project.

Using a Configuration File

To avoid passing long lists of flags every time you run a scan, you can use a YAML configuration file. By default, Trivy looks for a file named trivy.yaml in the current directory.

# trivy.yaml
scan:
  severity:
    - HIGH
    - CRITICAL
  ignore-unfixed: true
format: json
output: trivy-report.json

To use this configuration file, simply run Trivy with the --config flag (or let it pick up the default file automatically).

trivy image --config trivy.yaml my-app:latest

Ignoring Vulnerabilities

Sometimes, a vulnerability may not apply to your specific use case, or a fix may not yet be available. In these situations, you can instruct Trivy to ignore specific CVEs using a .trivyignore file.

# .trivyignore
CVE-2021-21311
CVE-2020-25638

Place this file in the directory where you run Trivy, and those specific vulnerabilities will be omitted from the scan results.

Best Practices

To get the most out of Trivy and ensure your security posture is as strong as possible, consider the following best practices:

Shift Left: Integrate Trivy into your IDE or pre-commit hooks. Catching a vulnerable dependency before it is committed is infinitely cheaper than finding it in production.
Automate in CI/CD: Add Trivy scans as a step in your CI/CD pipeline (e.g., GitHub Actions, GitLab CI). Fail the build if HIGH or CRITICAL vulnerabilities are found to prevent insecure code from being deployed.
Keep the Database Updated: Trivy updates its database automatically by default, but in air-gapped environments or CI runners, ensure you are periodically running trivy image --download-db-only to fetch the latest vulnerability data.
Scan Infrastructure as Code: Use trivy config to scan your Terraform, Dockerfile, and Kubernetes manifests. Misconfigurations in cloud infrastructure are a leading cause of data breaches.
Use Ignore Files Responsibly: While ignoring vulnerabilities is sometimes necessary, regularly review your .trivyignore file to ensure ignored CVEs are still irrelevant or if patches have become available.

Conclusion

Trivy is a powerful, versatile, and user-friendly tool that bridges the gap between development and security. By supporting a wide range of targets—from container images and file systems to Kubernetes clusters and IaC—it provides a unified solution for securing your software supply chain. By setting it up correctly, understanding its scanning capabilities, and adhering to best practices like shifting left and automating within CI/CD pipelines, development teams can proactively manage vulnerabilities and build more resilient applications. Integrating Trivy into your workflow is a significant step toward achieving a robust DevSecOps culture.