Trivy (pronounced /ˈtraɪvi/) is an open-source comprehensive security scanner developed by Aqua Security. It has over 35,000 stars on GitHub and is one of the most popular open-source security scanning tools available.

Trivy's core advantage lies in its comprehensiveness—it can scan multiple targets (container images, file systems, Git repositories, VM images, Kubernetes clusters) and detect various security issues (known CVE vulnerabilities, IaC misconfigurations, sensitive information leaks, software licenses, SBOM generation). For modern DevSecOps teams, Trivy can cover almost the entire security scanning chain from code commit to production deployment.

This article starts with installation and gradually introduces Trivy's core features, practical usage, and how to integrate Trivy into CI/CD pipelines. It helps developers and security engineers quickly get started with this powerful security tool.

Why Choose Trivy?

Before Trivy emerged, the security scanning landscape was typically fragmented: you needed different tools to scan container images, check IaC configurations, and find secret leaks in code. Trivy consolidates these capabilities into a unified CLI tool with the following outstanding features:

1. Multi-Target Scanning Support

Trivy can scan the following targets:

  • Container Images: Docker, OCI-compatible images (local or remote registries)
  • File Systems: Local directories, project source code
  • Git Repositories: Remote Git repositories (no cloning required)
  • VM Images: AWS EC2 AMIs, Azure VMs, etc.
  • Kubernetes Clusters: Running cluster resource configurations

2. Multi-Dimensional Security Detection

Trivy can discover the following types of security issues:

  • Known Vulnerabilities (CVE): Based on OS package and software dependency vulnerability databases
  • IaC Misconfigurations: Best practice violations for Terraform, CloudFormation, Kubernetes YAML, etc.
  • Sensitive Information Leaks: Hard-coded API keys, passwords, tokens
  • Software License Compliance: Identify open-source license types used in projects
  • SBOM Generation: Generate Software Bill of Materials

3. Easy Integration

Trivy provides rich integration options:

4. Fast and Low Resource Usage

Trivy is written in Go, starts quickly, and has low memory footprint—perfect for frequent runs in CI/CD pipelines.

Installing Trivy

Trivy supports multiple installation methods. Here are the most commonly used:

Method 1: Using Homebrew (macOS/Linux)

brew install trivy

Method 2: Using Docker

docker run aquasec/trivy --version

Method 3: Download Binary

Download the binary for your platform from GitHub Releases:

# Linux x86_64
wget https://github.com/aquasecurity/trivy/releases/download/v0.50.0/trivy_0.50.0_Linux-64bit.tar.gz
tar -xzf trivy_0.50.0_Linux-64bit.tar.gz
sudo mv trivy /usr/local/bin/

Method 4: Using apt/yum (Linux Distributions)

# Ubuntu/Debian
sudo apt-get install wget gnupg
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | sudo apt-key add -
echo "deb https://aquasecurity.github.io/trivy-repo/deb generic main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
sudo apt-get update
sudo apt-get install trivy

# CentOS/RHEL
sudo yum install trivy

Verify Installation

trivy --version
# Example output: Version: 0.50.0

Quick Start: Scan Your First Container Image

Let's start with a simple example—scanning a public Docker image to see what Trivy can find.

Scan the Official Python Image

trivy image python:3.9-slim

Trivy will output results similar to:

python:3.9-slim (debian 11.7)
=====================================
Total: 123 (UNKNOWN: 0, LOW: 45, MEDIUM: 52, HIGH: 24, CRITICAL: 2)

+------------------+---------------------+----------+-------------------+---------------+---------------------------------------+
|     LIBRARY      |   VULNERABILITY ID  | SEVERITY | INSTALLED VERSION | FIXED VERSION |               TITLE                   |
+------------------+---------------------+----------+-------------------+---------------+---------------------------------------+
| libssl1.1        | CVE-2023-5678       | CRITICAL | 1.1.1w-0+deb11u1  | 1.1.1w-0+deb11u2 | OpenSSL: X.509 Email Address ...     |
| openssl          | CVE-2023-6129       | HIGH     | 1.1.1w-0+deb11u1  | 1.1.1w-0+deb11u2 | OpenSSL: POLY1305 MAC implementation... |
+------------------+---------------------+----------+-------------------+---------------+---------------------------------------+

The output contains the following key information:

  • Total Vulnerabilities: Categorized by severity (UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL)
  • Vulnerability Details Table: Library name, CVE ID, severity, current version, fixed version, and vulnerability description for each vulnerability

Only Output High and Critical Vulnerabilities

In practice, we usually focus more on high and critical vulnerabilities. Use the --severity parameter to filter:

trivy image --severity HIGH,CRITICAL python:3.9-slim

Output in JSON Format (for Automation)

trivy image --format json python:3.9-slim > results.json

Core Features Explained

1. Scanning File Systems

In addition to container images, Trivy can scan local file systems to find vulnerabilities in project dependencies. This is very useful for discovering security issues early in the development phase.

# Scan current directory
trivy fs .

# Scan specified directory
trivy fs /path/to/project

# Only scan dependencies for specific languages
trivy fs --scanners vuln --language python /path/to/project

Trivy supports: Python, Node.js, Java, Go, Ruby, PHP, .NET, Rust, and other mainstream programming languages.

2. Scanning Git Repositories

Trivy can directly scan remote Git repositories without cloning them locally first:

# Scan public GitHub repository
trivy repo https://github.com/aquasecurity/trivy

# Scan specific branch
trivy repo https://github.com/aquasecurity/trivy@main

This is very convenient for auditing the security of third-party open-source projects.

3. Scanning Kubernetes Configurations

Kubernetes configuration errors are one of the main causes of security incidents. Trivy can check if Kubernetes YAML files comply with security best practices:

# Scan single YAML file
trivy config deployment.yaml

# Scan all config files in a directory
trivy config ./k8s-manifests/

Trivy detects the following issues:

  • Containers running as root user
  • Resource limits (CPU/memory) not set
  • Using latest tag
  • Privileged mode enabled
  • Sensitive information hard-coded via environment variables

Example output:

k8s-manifests/deployment.yaml
=============================
Tests: 15 (SUCCESSES: 12, FAILURES: 3, EXCEPTIONS: 0)
Failures: 3 (UNKNOWN: 0, LOW: 1, MEDIUM: 1, HIGH: 1, CRITICAL: 0)

+-----------+------------+-----------------+----------+---------------------------------------+
| TYPE      | MISCONF ID |    CHECK        | SEVERITY |              MESSAGE                  |
+-----------+------------+-----------------+----------+---------------------------------------+
| Kubernetes| KSV012     | Image Tag       | MEDIUM   | Container 'app' uses 'latest' tag     |
| Kubernetes| KSV001     | Privileged      | HIGH     | Container 'app' runs in privileged mode|
+-----------+------------+-----------------+----------+---------------------------------------+

4. Generate SBOM (Software Bill of Materials)

SBOM is an important component of software supply chain security. Trivy can generate SBOMs in standard formats:

# Generate SPDX format SBOM
trivy image --format spdx-json python:3.9-slim > sbom.spdx.json

# Generate CycloneDX format SBOM
trivy image --format cyclonedx python:3.9-slim > sbom.cyclonedx.xml

The generated SBOM can be used for compliance audits, vulnerability impact analysis, and other scenarios.

5. Detect Sensitive Information Leaks

Trivy can scan code for hard-coded sensitive information (API keys, passwords, tokens, etc.):

trivy fs --scanners secret ./my-project

Trivy has built-in detection rules for various sensitive information, including:

  • AWS Access Key
  • GitHub Token
  • Slack Webhook URL
  • Private Key
  • Database Connection String

CI/CD Integration in Practice

Integrating Trivy into CI/CD pipelines is a key step in achieving "shift-left security." Here are integration examples for several common platforms.

GitHub Actions

Create .github/workflows/trivy.yml in your project root:

name: Trivy Security Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  trivy-scan:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: 'python:3.9-slim'
          format: 'table'
          severity: 'CRITICAL,HIGH'
          exit-code: '1'  # Fail when high/critical vulnerabilities found

This workflow automatically scans the specified container image on every push or PR. If high or critical vulnerabilities are found, the CI fails.

GitLab CI

Add to .gitlab-ci.yml:

trivy-scan:
  image:
    name: aquasec/trivy:latest
    entrypoint: [""]
  script:
    - trivy fs --exit-code 1 --severity HIGH,CRITICAL .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Jenkins Pipeline

pipeline {
    agent any

    stages {
        stage('Security Scan') {
            steps {
                sh '''
                    docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
                        aquasec/trivy image --exit-code 1 --severity HIGH,CRITICAL \
                        my-app:latest
                '''
            }
        }
    }
}

Advanced Usage

1. Ignore Specific Vulnerabilities

Sometimes certain vulnerabilities are not exploitable in your scenario. You can create a .trivyignore file to ignore them:

# .trivyignore
CVE-2023-1234
CVE-2023-5678

Or use the --ignorefile parameter to specify a custom ignore file:

trivy image --ignorefile .trivyignore python:3.9-slim

2. Cache Vulnerability Database

By default, Trivy updates the vulnerability database on every scan, which causes additional network overhead in CI/CD environments. You can use caching to speed things up:

# Download database on first scan
trivy image --download-db-only

# Subsequent scans use local cache
trivy image --skip-db-update python:3.9-slim

In GitHub Actions, you can use actions/cache to persist the database:

- name: Cache Trivy DB
  uses: actions/cache@v3
  with:
    path: ~/.cache/trivy
    key: trivy-db-${{ hashFiles('~/.cache/trivy/db/trivy.db') }}
    restore-keys: trivy-db-

3. Custom Report Templates

Trivy supports using Go templates to customize output formats:

trivy image --format template --template "@contrib/html.tpl" python:3.9-slim > report.html

Trivy includes several built-in templates:

  • @contrib/html.tpl: HTML report
  • @contrib/junit.tpl: JUnit XML format (suitable for CI/CD)
  • @contrib/sarif.tpl: SARIF format (suitable for GitHub Code Scanning)

4. Integration with Trivy Operator (Kubernetes)

For running Kubernetes clusters, you can deploy Trivy Operator to continuously monitor cluster security:

helm repo add aqua https://aquasecurity.github.io/helm-charts/
helm install trivy-operator aqua/trivy-operator --namespace trivy-system --create-namespace

Trivy Operator automatically scans workloads in the cluster and stores results as Kubernetes CRDs. You can view them in the Dashboard or query via API.

Troubleshooting Common Issues

Issue 1: Slow Scanning Speed

Cause: First scan requires downloading the vulnerability database (approx. 100-200MB).

Solution: Use --skip-db-update to skip database updates, or pre-download the database:

trivy image --download-db-only
trivy image --skip-db-update python:3.9-slim

Issue 2: Too Many False Positives

Cause: Trivy's vulnerability database may contain vulnerabilities that are not exploitable in your scenario.

Solution: Use .trivyignore file to ignore known false positives, or adjust --severity parameter to focus only on high-severity vulnerabilities.

Issue 3: Private Image Scanning Fails

Cause: Trivy cannot access private image registries that require authentication.

Solution: Set environment variables or use --registry-token parameter:

export TRIVY_USERNAME=myuser
export TRIVY_PASSWORD=mypassword
trivy image registry.example.com/my-private-image:latest

Issue 4: Out of Memory

Cause: Scanning large images or file systems may consume significant memory.

Solution: Increase container memory limits, or use --light mode to reduce memory usage:

trivy image --light python:3.9-slim

Summary

Trivy is a powerful and easy-to-use open-source security scanning tool. Its core value lies in:

  1. Comprehensiveness: Supports multiple scanning targets and detection types, covering full-chain security needs from code to production
  2. Ease of Use: Simple CLI interface, rich documentation, and community support
  3. Integration-Friendly: Native support for mainstream CI/CD platforms and Kubernetes
  4. Excellent Performance: Go implementation, fast startup, low resource usage

For any development team that values security, incorporating Trivy into daily development workflows is a wise choice. It helps you discover and fix security issues early, reducing security risks in production environments.

Recommended Next Steps:

  1. Install Trivy in your local development environment and try scanning a few commonly used container images
  2. Integrate Trivy into your CI/CD pipeline with appropriate security thresholds
  3. Regularly review scan results and establish a vulnerability remediation workflow
  4. Explore Trivy Operator to add continuous security monitoring for your Kubernetes cluster

Trivy's official documentation is at https://trivy.dev, and the GitHub repository is at https://github.com/aquasecurity/trivy. When you encounter issues, you can find detailed documentation and community support at these two locations.

Related Reading: