The Complete Trivy Guide

This is part one of three. It covers everything you need to do real work with Trivy, not a teaser. By the end you can scan a container image, a project folder, a git repository, your infrastructure files and a Kubernetes cluster; you can read the report without panic; you can make a pipeline fail when something serious turns up; you can produce a software bill of materials; and you can suppress a finding the honest way, with a reason and an expiry date. Mid-level and Senior take the same topics further; nothing here is thrown away.

Each section ends with a Try it task. Do them as you go. They take a few minutes each, and scanners only start to make sense once you have watched one find something in an image you built yourself.

This guide is written against Trivy 0.74.0, released on 14 August 2026. Trivy is still a 0.x tool, which means minor releases can change flags and output, so every command here was checked against that version, and the habit of pinning an exact version (explained in the section on Trivy's own supply chain) matters more than it does for most tools.

What Trivy is, and the problem it solves

Every application you ship is mostly code you did not write. A typical container image contains an operating system's worth of packages (a C library, a TLS library, a shell, a package manager), plus a language runtime, plus dozens or hundreds of third-party libraries pulled in by your dependency file, and only then your own few thousand lines. Any of those pieces can contain a security flaw that somebody has already found, reported and given a public identifier. Those identifiers are called CVEs (Common Vulnerabilities and Exposures), and they look like CVE-2024-12345: the year it was published and a serial number.

The problem is not that flaws exist. The problem is that nobody can hold the list of everything they depend on, and the list of every known flaw, in their head at once. New CVEs are published every day. An image that was clean on Monday can have a critical finding on Friday without a single byte of it changing, because the world learned something new about a library inside it.

Trivy is a scanner that does that matching for you. You point it at something (an image, a folder, a repository, a cluster), it works out what software is inside, compares that inventory with a database of known vulnerabilities, and prints what matches. It is made by Aqua Security, is open source under the Apache 2.0 licence, is written in Go and ships as a single binary with no server to run. That last detail is why it became popular: you can try it in thirty seconds and you can also put it in a pipeline in five minutes.

The diagram is the whole idea, and the rest of this guide is detail on each arrow. Notice that Trivy does not run your software. It reads files. That is why a scan takes seconds rather than minutes, and it is also the source of its limits, which we return to at the end of the guide.

Trivy does more than look for CVEs. It has four kinds of scanner, and a beginner should know all four exist even if you only use one at first:

• Vulnerability scanning finds known flaws in operating-system packages and in language libraries (npm, pip, Maven, Go modules and many more).
• Misconfiguration scanning reads infrastructure-as-code (Dockerfiles, Kubernetes manifests, Terraform, CloudFormation, Helm charts) and flags risky settings, such as a container that runs as root or a storage bucket open to the public.
• Secret scanning looks for credentials that were committed by accident: cloud access keys, tokens, private keys.
• License scanning reports the licences of the packages you depend on, which matters to a company's lawyers more than to its security team, but is the same inventory put to a different use.

What people use it for in practice:

You need little to follow along: a terminal, Docker (or any container runtime) for the image examples, and a small project of your own. If your team is in the Gulf or Egypt and your employer has data-residency rules, one fact is worth holding on to early: a default scan sends nothing about your code or images anywhere. Trivy downloads a public vulnerability database and compares locally. Later sections cover the few network calls it does make, so you can answer a security reviewer precisely.

What came before, and why scanners became routine

For a long time, vulnerability management was a human process. A security team subscribed to mailing lists, somebody kept a spreadsheet of "what version of what is running where", and on a good day a patch cycle happened quarterly. That worked when a server was a long-lived machine that an administrator logged into, and the list of installed software was a thing you could ask the machine for.

Containers and package managers broke that model in two ways. First, the number of things to track exploded: a single service could have a thousand transitive dependencies, and a company could have hundreds of services. Second, artifacts became immutable and short-lived, so "log in and check" stopped being possible. The answer the industry settled on was to inspect the artifact itself, automatically, at build time and again later.

The first wave of tools did one thing each. Some scanned operating-system packages in images, some scanned language dependencies, some linted Terraform, some hunted for passwords in git history, and a team that wanted all four ran four tools with four output formats and four ways of failing a build. Trivy's design choice was to put all of those behind one command line, one report structure and one set of output formats. You can disagree about whether the all-in-one approach is the best at each individual task (more specialised tools exist, and a later section names them), but for someone starting out the single interface is a real advantage: learning trivy image, trivy fs and trivy config teaches you one tool, not three.

A second idea became standard at the same time, and you will meet it throughout this guide: the software bill of materials, or SBOM. It is simply the ingredient list of an artifact, in a standard file format. Once you have the ingredient list, matching it against the vulnerability database is a separate, repeatable step that you can run again tomorrow without touching the original image. Trivy can both produce these lists and scan them.

The mental model: targets, scanners, data and results

Trivy has a small vocabulary. Learn these nouns and every command in the documentation reads naturally.

A target is what you point Trivy at, and it is chosen by the subcommand you type. The ones a beginner needs:

A scanner is the kind of finding you are asking for, chosen with the --scanners flag: vuln, misconfig, secret and license. Different subcommands have different defaults. For an image or a folder the default is vuln,secret: vulnerabilities and secrets on, misconfiguration and licences off until you ask. trivy config runs only the misconfiguration scanner.

Data is what Trivy compares against. The main piece is the Trivy DB, an aggregate of vulnerability information from the National Vulnerability Database, from the security advisories each Linux distribution publishes, from the GitHub Advisory Database and other sources. It is rebuilt roughly every six hours and distributed as an OCI artifact, the same packaging format container images use, so it is fetched from a registry. A second database, the Java DB, helps identify Java archives that lack metadata, and is only downloaded when Trivy finds JAR files. A third piece, the checks bundle, holds the rules for misconfiguration scanning, written in a policy language called Rego.

The cache is a folder on your disk where all of this lives. On Linux it is ~/.cache/trivy, on macOS ~/Library/Caches/trivy, and you can move it with --cache-dir. The first scan downloads the database into it (a few hundred megabytes), and later scans reuse it, refreshing when the database is stale.

A result is the output. Internally, a scan produces a report, which contains one result for each target inside the artifact and each class of finding. An image with Debian packages and a Python application has a result for the OS packages and another for the Python libraries. Each result lists vulnerabilities with a severity: UNKNOWN, LOW, MEDIUM, HIGH or CRITICAL. Finally a reporter renders the report as a table, JSON, SARIF, an SBOM or a template, depending on --format.

Two more words appear in the output and deserve an early definition. A vulnerability's status says where it stands: fixed means a patched version exists, affected means it is vulnerable and no fix has been published, will_not_fix means the maintainer has decided not to patch, fix_deferred and end_of_life mean what they say. The installed version is what your artifact contains, and the fixed version is the first release that resolves the flaw. Those two columns are the ones you will read most.

Installing Trivy and checking your setup

Trivy is one static binary, so installation is mostly a question of which delivery mechanism suits your machine. The project officially supports container images, release binaries, an install script and several package managers. Pick one.

On macOS, Homebrew is the easiest:

brew install trivy

On Debian and Ubuntu, use the project's APT repository. Pay attention to the last line of the repository definition, because it changed recently and old tutorials are wrong:

sudo apt-get install wget gnupg
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] 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

On Fedora, RHEL and CentOS, create /etc/yum.repos.d/trivy.repo with the repository definition, then install:

[trivy]
name=Trivy repository
baseurl=https://aquasecurity.github.io/trivy-repo/rpm/releases/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://aquasecurity.github.io/trivy-repo/rpm/public.key

sudo yum -y update && sudo yum -y install trivy

On Windows, the officially supported route is manual: download the windows-64bit.zip from the GitHub releases page, unzip it, and put trivy.exe on your PATH. If you use Docker Desktop, the most reliable setup is WSL2 with the Linux instructions above, so Trivy and the Docker socket live in the same Linux environment.

For a CI machine or a quick server install, there is an install script. Always pass a version, never run it unpinned:

curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sudo sh -s -- -b /usr/local/bin v0.74.0

Finally, you can skip installation and run Trivy as a container. You give it the Docker socket so it can see your local images, and a cache volume so it does not re-download the database every run:

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $HOME/Library/Caches:/root/.cache/ \
  aquasec/trivy:0.74.0 image python:3.4-alpine

Two details. Since version 0.72.0 the project no longer publishes architecture-specific tags such as 0.71.0-amd64; use the plain multi-architecture tag shown above, or a digest. And mounting the Docker socket gives the container very broad power over your host, which is acceptable on your own laptop and something to avoid in shared CI (the Senior guide covers safer arrangements).

Now verify the installation:

trivy --version

Version: 0.74.0

Once the database has been downloaded, the same command also prints the database and checks-bundle metadata. To warm the cache without scanning anything, which is useful before a demo or on a slow connection:

trivy image --download-db-only

This fetches the vulnerability database into your cache directory. If it fails, the error message will mention a registry such as ghcr.io or mirror.gcr.io: Trivy fetches its database from there, so a corporate firewall or proxy that blocks those hosts is the usual culprit. The errors section below has the fixes.

Your first scan: a container image

The most common use of Trivy is scanning an image, so start there. Choose an image that is old enough to have findings, which makes the output worth reading:

trivy image python:3.4-alpine

The first time you run this, Trivy prints progress lines about downloading the vulnerability database, and on later runs it skips that. Then it inspects the image: it unpacks the layers, reads the operating system's release file to learn that this is Alpine Linux and which version, reads the package manager's database to list installed packages, and looks for language dependency files. A couple of seconds later you get a report.

Where does Trivy find the image? By default it looks in this order: your local Docker daemon, then containerd, then Podman, then the remote registry. If you have the image locally, it reads it from the daemon without pulling. If not, it pulls the layers it needs from the registry (it does not need a running container and it does not start one). You can force a source with --image-src:

trivy image --image-src remote python:3.4-alpine

That matters in CI environments where there is no Docker daemon at all: remote goes straight to the registry. A third way is to scan an image that was saved to a tar file, which is also how you scan in places with no registry access:

docker save -o myapp.tar myapp:1.0
trivy image --input myapp.tar

Some notes about naming. An image reference with no registry prefix, like python:3.4-alpine, means Docker Hub. A locally built image such as myapp:1.0 is found in the daemon. A fully qualified name like ghcr.io/example/app:2.3 goes to that registry and will need credentials if it is private; Trivy reuses the credentials in your Docker configuration file, so if docker pull works for you, trivy image generally does too.

Try a real example by building something tiny and scanning it, so you have a thing you own:

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "app.py"]

docker build -t myapp:1.0 .
trivy image myapp:1.0

If you followed the Docker guide you will recognise each step (/student-guides/docker covers writing a Dockerfile in depth). The point here is that Trivy sees two different layers of software inside your image: the Debian packages that came with the base image, and the Python packages your requirements.txt installed. Your own code, app.py, is not scanned for vulnerabilities, because Trivy matches packages and not logic, although it will look at it for secrets.

Reading the report

The default output is a table, and reading it well is the skill that separates "I ran a scanner" from "I can act on it". The table below is typical in shape. The exact packages, identifiers and counts will differ from what you see, because the database changes every few hours.

python:3.4-alpine (alpine 3.9.2)
================================
Total: 12 (HIGH: 10, CRITICAL: 2)

┌────────────┬────────────────┬──────────┬──────────┬───────────────────┬───────────────┬───────────────────────────────┐
│  Library   │ Vulnerability  │ Severity │  Status  │ Installed Version │ Fixed Version │             Title             │
├────────────┼────────────────┼──────────┼──────────┼───────────────────┼───────────────┼───────────────────────────────┤
│ libcrypto1 │ CVE-2019-1543  │ HIGH     │ fixed    │ 1.1.1a-r1         │ 1.1.1b-r1     │ openssl: ChaCha20-Poly1305    │
│            │                │          │          │                   │               │ with long nonces              │
└────────────┴────────────────┴──────────┴──────────┴───────────────────┴───────────────┴───────────────────────────────┘

Read it from the top.

The header line names the target and what Trivy decided it is: python:3.4-alpine (alpine 3.9.2) tells you Trivy identified the operating system as Alpine 3.9.2. This matters more than it looks. Vulnerability data for operating-system packages is specific to each distribution and release, and if Trivy cannot identify the operating system (an image built FROM scratch, or a stripped-down base) it cannot match OS packages at all, and you will see no OS results. An empty report can mean "clean" or it can mean "not understood", so always check that the header shows what you expect.

The summary line, Total: 12 (HIGH: 10, CRITICAL: 2), is per section, not per image. An image with both OS packages and Python libraries has one section and one summary line for each. The summary counts only what is displayed after filters, so if you filtered by severity, the total reflects that.

In the table itself, each row is one finding:

• Library is the package that contains the flaw. For OS packages this is the name the package manager knows (libcrypto1.1, openssl, zlib); for language dependencies it is the library (requests, lodash).
• Vulnerability is the identifier. Most are CVEs, and some are advisory IDs from a language ecosystem. In modern terminals these are clickable links to a page with the details.
• Severity is Trivy's assessment, from UNKNOWN through CRITICAL. It comes from the most appropriate source for that package (your distribution's own rating is preferred when it has one), so the same CVE can legitimately show different severities in a Debian image and an Alpine image.
• Status is the most useful column for deciding what to do. fixed means a patched version exists and upgrading resolves it. affected means you are vulnerable and no fix has been published yet. will_not_fix means the vendor has decided not to patch, which can be reasonable when the affected feature is not compiled in.
• Installed Version and Fixed Version tell you the gap. If the fixed version is blank, there is nothing to upgrade to.
• Title is a one-line summary of the flaw.

Findings are not all equally actionable, and learning to sort them is most of the job. A rough triage order that works in practice:

1. Start with CRITICAL and HIGH findings that have a fixed version. These are real and have a cheap remedy: update the package or the base image.
2. Next, see whether the vulnerable package is in the image because of your choices or because of your base image. A dozen findings that all disappear when you move from python:3.9 to python:3.9-slim are one decision, not twelve chores.
3. Findings with no fix are real but not something you can act on today. Note them, and see whether the vulnerable feature is one your software uses.
4. Low and unknown severities are usually last.

A few more controls make the table easier to read. --table-mode lets you choose which parts of the table to show (for example only the summary), and --dependency-tree adds a view of how a vulnerable library got into your project, which is invaluable for dependencies you never chose directly: a flaw in a library three levels down is fixed by upgrading the thing at the top, and the tree tells you which thing that is.

trivy image --dependency-tree myapp:1.0

For a language-library result you may see a dependency-tree section showing that, for example, your direct dependency web-framework pulls in http-helper, which pulls in the vulnerable parser. That is the path you need to upgrade along.

Filtering: severity, unfixed, and status

A raw report on an old image can have hundreds of rows, which is useless for a human and dangerous for a pipeline, because people learn to ignore alarms that always ring. Filtering is how you turn a report into a decision. There are three filters to know on day one.

Filter by severity with --severity, giving a comma-separated list:

trivy image --severity HIGH,CRITICAL alpine:3.15

Only the listed severities are shown, and the summary counts follow. HIGH,CRITICAL is the conventional threshold for a gate, because MEDIUM and below produce a large volume of findings that rarely justify blocking a release.

Filter out findings with no fix using --ignore-unfixed:

trivy image --ignore-unfixed alpine:3.15

This hides anything whose status means no patched version exists yet. The reasoning is practical: if you cannot do anything about a finding today, failing a build for it only teaches the team to bypass the check. Use it together with a severity filter for a gate that only reports what is both serious and fixable:

trivy image --severity HIGH,CRITICAL --ignore-unfixed myapp:1.0

Filter by status gives finer control than the shortcut, through --ignore-status, listing the statuses to hide:

trivy image --ignore-status fixed,will_not_fix,end_of_life myapp:1.0

That is rarely what a beginner wants, but it shows the model: --ignore-unfixed is a convenience for a particular combination of statuses.

There are other filters that are worth knowing exist. --pkg-types os,library restricts the report to operating-system packages or to language libraries (both by default). --include-dev-deps includes development-only dependencies such as test frameworks, which are left out by default because they are not shipped. --skip-dirs and --skip-files exclude paths you know are noise, such as a vendored test fixture folder.

Keep one idea in mind about all filters: they change what you see and what a pipeline fails on, not what is true. A filtered report is a view. Use filters to express a policy your team agreed, write that policy down, and avoid filtering until the output looks clean, because a report made to look clean is the most dangerous kind.

Scanning a project: filesystem and repository

Images are what you ship, but you can catch problems earlier, in the folder where the code lives. trivy fs points at a directory and looks for the files package managers leave behind: package-lock.json, yarn.lock, requirements.txt and poetry.lock, go.mod, pom.xml, Gemfile.lock, Cargo.lock and many more. It reads those lock files as the inventory and matches them against the database.

cd my-project
trivy fs .

Because a lock file records the exact resolved versions, it is the best input for a scan. A requirements.txt with loose version ranges tells Trivy less than a lock file that pins each version. If your project has only loose ranges, Trivy can still report but the results reflect what the file says, not necessarily what will be installed. The habit this teaches is one worth adopting for its own sake: commit your lock files.

A filesystem scan runs the same default scanners (vuln,secret). To add misconfiguration checks for any infrastructure files sitting in the project:

trivy fs --scanners vuln,secret,misconfig .

To scan a project you do not have on disk, use trivy repo with a git URL. Trivy clones it to a temporary folder and scans the clone:

trivy repo https://github.com/user/repo

You can pick a branch, tag or commit with --branch, --tag or --commit. This is handy for vetting a dependency before you adopt it, or for auditing a repository without checking it out yourself. One caution: a repository scan looks at the working tree at that commit, not the full history. A password that was committed and later deleted is invisible to Trivy, and lives on in history. Tools that specialise in history (the Mid guide names some) are the right complement.

If a scan complains about disk space with a message mentioning a path like /tmp/fanal-..., the temporary folder is full (Trivy unpacks artifacts there). Point TMPDIR at a larger disk:

TMPDIR=/mnt/big-disk trivy repo https://github.com/user/repo

A few useful flags for real projects: --skip-dirs node_modules if you only want your lock file scanned rather than an installed dependency tree, and --skip-files to exclude particular files. Everything else you learned for images (severity, unfixed, formats, exit codes) applies identically to fs and repo, which is the payoff of the single interface.

Finding secrets before they leak

Of everything Trivy does, the secret scanner has the best ratio of effort to value. People commit credentials constantly: a cloud key pasted into a config file to "just test it", a token in a script, a private key in a forgotten folder. Once pushed, a credential should be treated as public, and automated bots harvest public repositories for them within minutes.

The secret scanner is on by default for image, filesystem and repository scans, so you may already have seen it fire. It works by matching a large set of built-in rules, each a pattern plus keywords that make a match plausible (an AWS access key has a recognisable shape and prefix, a GitHub token has its own), and it reports the file, the line, the rule and a redacted excerpt.

Try it on a file you create deliberately. The example key below is the well-known dummy value from the cloud provider's own documentation, not a live credential:

mkdir secret-demo && cd secret-demo
echo 'AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE' > settings.env
trivy fs --scanners secret .

settings.env (secrets)
======================
Total: 1 (HIGH: 1)

HIGH: AWS (aws-access-key-id)
═══════════════════════════════
AWS Access Key ID
───────────────────────────────
 settings.env:1 (offset: 18 bytes)
───────────────────────────────
   1 [ AWS_ACCESS_KEY_ID=***************** ]
───────────────────────────────

Notice that Trivy redacts the matched value in its output, so the report itself does not become a second place a secret leaks. That said, treat reports as sensitive anyway, since file names and surrounding context can reveal a good deal.

The scanner also looks inside images, including their layers and build history, and it reads compiled Python .pyc files. A secret baked into one layer and deleted in a later one is still in the image, because layers are additive, and Trivy will find it. If you followed the Docker guide you know why.

If a secret is found, the response is the same whichever tool found it: rotate it first, then remove it. Deleting the line does not un-leak it. Rotate the credential at its source (revoke the key, issue a new one), then fix the code to read it from an environment variable or a secrets manager. The Vault guide at /student-guides/vault covers a place to keep them properly.

Sometimes a match is a false positive, for example an example key in documentation, or a test fixture. You can tune the scanner with a configuration file named trivy-secret.yaml in the working directory (or pointed to with --secret-config), where you can add your own rules, allow-list paths and patterns, and disable built-in rules you do not need. Leaving only the built-in rules you care about also makes scans faster on big repositories, because each rule is work Trivy has to do.

Checking infrastructure files: misconfiguration scanning

A vulnerability is a flaw someone else wrote into a library. A misconfiguration is a risky setting that you wrote yourself, and it is usually more dangerous because nobody else will patch it for you. Examples: a Dockerfile with no USER line (so the process runs as root), a Kubernetes pod that allows privilege escalation, a Terraform storage bucket that permits public reads, a security group open to the whole internet.

Trivy handles these with the misconfiguration scanner. It understands Dockerfiles, Kubernetes manifests, Terraform (including plan files), CloudFormation, Azure ARM templates and Helm charts. The simplest entry point is trivy config, which runs only this scanner against a folder:

trivy config ./infra

Here is a small Dockerfile with a flaw, and what Trivy says about it:

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl
COPY . /app
CMD ["/app/run.sh"]

trivy config .

Dockerfile (dockerfile)
=======================
Tests: 27 (SUCCESSES: 25, FAILURES: 2)
Failures: 2 (HIGH: 1, LOW: 1)

AVD-DS-0002 (HIGH): Specify at least 1 USER command in Dockerfile with non-root user as argument

Two things to learn from that output. First, the check ID, AVD-DS-0002: AVD stands for Aqua Vulnerability Database, DS is for Dockerfile, and the number is the rule. You will see older IDs in the style DS002 or KSV001 (Kubernetes) in some material; they refer to the same rules. Cloud checks look like AWS-0010. Every ID is searchable and has a documentation page explaining why the setting is risky and how to fix it.

Second, each result shows a pass/fail count: Tests: 27 (SUCCESSES: 25, FAILURES: 2). By default only failures are listed. Pass --include-non-failures if you want to see what passed as well, which is useful the first time you run it against a real project to see the coverage.

The checks themselves are Rego policies, in a bundle Trivy downloads and keeps in its cache (and embeds a copy of as a fallback). You do not need to write Rego as a beginner, but you should know it exists, because you can write your own checks for your company's rules later, and it explains why trivy config can check a Terraform plan or a Helm chart in the same way: it converts each format into a common structure and runs the same policies on it.

To run misconfiguration checks as part of a wider scan, add the scanner explicitly: trivy fs --scanners vuln,secret,misconfig . or trivy image --scanners vuln,misconfig myapp:1.0. For an image, misconfiguration checks look at the Dockerfile-equivalent information Trivy can reconstruct from the image configuration.

If a file is not being checked, the usual cause is that Trivy did not recognise it as infrastructure code. Use trivy config (which is explicit about what it is doing) or check that the file's extension and structure match what the scanner expects.

Licenses, in brief

The same inventory that finds vulnerabilities can report what licence each package is distributed under. This rarely concerns a student, but it concerns companies: using a library under a licence that forces you to publish your own code can be a legal problem, and procurement teams in regulated sectors ask for this list.

The licence scanner is off by default. Turn it on with --scanners license:

trivy fs --scanners license .
trivy image --scanners license --license-full myapp:1.0

By default, Trivy only reports licences from package metadata, and --license-full makes it also examine licence files in the tree, which is slower and more thorough. It classifies each licence into categories (forbidden, restricted, reciprocal, notice, permissive, unencumbered, unknown), so that you can see at a glance that one package is under a strong copyleft licence while most are permissive. The lists behind those categories are configurable, because what a company considers forbidden is a policy decision, not a fact of nature. Recent releases have also improved Java licence detection, reading it from embedded project metadata and mapping licence URLs to standard identifiers.

For now, remember that the scanner exists and how to switch it on; the Mid-level guide covers turning categories into policy.

Output formats: table, JSON, SARIF and more

A table is for humans. Anything that consumes the result automatically (a dashboard, a code-scanning tab, a ticket-creating script) needs a structured format. You select it with --format, and write to a file with --output:

trivy image --format json --output result.json alpine:3.15

The formats a beginner should know:

• table is the default, for reading in a terminal.
• json is the complete report, with every field. It is the right choice for scripts and the source of truth you can convert from later.
• sarif is a standard format for static-analysis results, and is what GitHub's code-scanning feature ingests, so findings appear in a repository's Security tab.
• cyclonedx, spdx and spdx-json produce an SBOM rather than a vulnerability report. The next section covers these.
• template renders through a Go template, for custom layouts such as an HTML report; Trivy ships templates for HTML, JUnit and other targets.
• github produces a dependency snapshot for GitHub's dependency graph, and cosign-vuln produces a predicate for attaching a scan result to an image with the cosign signing tool.

A very useful trick is that you do not need to re-scan to get a different format. If you saved a JSON result, trivy convert renders it again:

trivy convert --format sarif --output result.sarif result.json

Use jq, a command-line JSON tool, to answer quick questions from a JSON report, for example to list every critical CVE:

trivy image --format json --output result.json myapp:1.0
jq -r '.Results[].Vulnerabilities[]? | select(.Severity=="CRITICAL") | .VulnerabilityID' result.json

Take a moment to look at the structure of result.json once. A top-level Results array has one entry per target and class, and each has a Vulnerabilities array whose entries carry fields like VulnerabilityID, PkgName, InstalledVersion, FixedVersion and Severity. The question marks in the jq expression handle results that have no vulnerabilities. Knowing this shape lets you build anything on top of Trivy.

Software bills of materials

An SBOM is an inventory: every package inside an artifact, with versions and identifiers, in a standard machine-readable file. The two common standards are CycloneDX and SPDX, and Trivy writes both.

trivy image --format cyclonedx --output sbom.cdx.json alpine:3.15
trivy image --format spdx-json --output sbom.spdx.json alpine:3.15
trivy fs --format cyclonedx --output sbom.json .

Why bother? Two reasons that matter to beginners. First, customers and regulators increasingly ask for one. Second, it separates two jobs that a plain scan does together: working out what is inside, and deciding what is vulnerable. The inventory of a released image never changes, but the vulnerability database does, every few hours. If you save the SBOM when you build, you can rescan it next week without pulling the image again:

trivy sbom ./sbom.spdx.json

That is how teams answer "are we affected by the new vulnerability?" quickly: they rescan a store of SBOMs rather than every image.

One detail surprises people. A CycloneDX file produced the ordinary way lists components only, with no vulnerabilities in it. If you want vulnerability data embedded alongside the inventory, say so:

trivy image --format cyclonedx --scanners vuln --output sbom-with-vulns.json alpine:3.15

Trivy will also notice SBOM files that already exist inside an image or virtual machine, with extensions such as .cdx.json and .spdx.json, and use them.

Failing a build: exit codes

So far Trivy has only talked. To make it block something, you use its exit code. A program's exit code is the number it hands back to the shell when it finishes: zero means success, anything else means failure, and every CI system treats a non-zero step as a failed step.

Here is the detail that surprises nearly everyone: by default Trivy exits with zero even when it finds critical vulnerabilities. Finding problems is a successful scan, not a failed one. A pipeline that runs trivy image myapp:1.0 and nothing else will stay green forever, which gives a false sense of security that is worse than no scan at all.

To turn findings into a failure, pass --exit-code:

trivy image --exit-code 1 --severity CRITICAL myapp:1.0
echo $?

If any critical finding remains after filters, Trivy exits with 1 and echo $? prints 1. If none remain, it prints 0. The filters decide what counts: the severity list above means only critical findings trigger the failure, although everything you did not filter is still printed. A gate that matches the sensible policy from earlier looks like this:

trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed myapp:1.0

A common pattern is two scans in one job: a first, informational one that prints everything and always succeeds, and a second, strict one that fails the build, so developers see the full picture but only serious, fixable findings block them.

trivy image --severity LOW,MEDIUM,HIGH,CRITICAL myapp:1.0
trivy image --exit-code 1 --severity CRITICAL --ignore-unfixed myapp:1.0

There is a second, separate switch, --exit-on-eol, which fails the scan if the image's operating system has reached end of life. An unsupported base image stops receiving security fixes altogether, so this catches a risk that no individual CVE row shows:

trivy image --exit-on-eol 1 myapp:1.0

In a GitHub Actions workflow, the same idea is expressed through an action's inputs. Pin the action to a full commit hash, not to a tag or branch (the next section explains why):

name: scan
on: [pull_request]
jobs:
  trivy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build image
        run: docker build -t myapp:${{ github.sha }} .
      - name: Scan image
        # Replace <full-commit-sha> with the verified commit of a safe release
        uses: aquasecurity/trivy-action@<full-commit-sha>
        with:
          image-ref: myapp:${{ github.sha }}
          severity: HIGH,CRITICAL
          ignore-unfixed: true
          exit-code: "1"

The action's exit-code input defaults to 0, which is the same trap in another costume. The GitHub Actions guide (/student-guides/github-actions) covers workflows in depth, and the GitLab CI guide (/student-guides/gitlab-ci) shows the same gate in a different system.

Ignoring findings honestly

Sooner or later a finding appears that you cannot or should not fix right now: the vulnerable function is not reachable in your code, the fix needs a major upgrade you have scheduled for next month, or it is a false positive. You need a way to say "I have seen this; do not fail the build for it" that is recorded, reviewable and temporary. Trivy provides it through an ignore file.

The simplest form is a plain text file named .trivyignore in the directory you run Trivy from. Each line is an identifier; exp: adds an expiry date:

# Not reachable: we do not use the affected parser. Review with the Q1 upgrade.
CVE-2019-14697 exp:2026-12-31

# Dockerfile check: this build image needs root to install packages.
AVD-DS-0002

When the date passes, the ignore stops applying and the finding returns. Expiry is the single most valuable habit in suppression, because it converts "we decided once" into "we decide again on a schedule". An ignore without an expiry date becomes permanent by neglect.

For anything beyond a personal project, use the richer YAML format, which records a reason and can limit an ignore to particular paths or packages. You enable it with --ignorefile:

vulnerabilities:
  - id: CVE-2023-29491
    statement: Not reachable, terminal library unused. Reviewed by platform team.
    expired_at: 2026-12-31
  - id: CVE-2023-3817
    purls: ["pkg:deb/debian/libssl1.1"]
    statement: Fix scheduled with base image update.

misconfigurations:
  - id: AVD-DS-0002
    paths: ["docs/Dockerfile"]
    statement: Documentation example, never built.

secrets:
  - id: aws-access-key-id
    paths: ["tests/fixtures/fake-credentials.txt"]
    statement: Dummy key used in unit tests.

trivy image --ignorefile ./.trivyignore.yaml myapp:1.0

Notice how much more a statement and a path tell the reviewer than a bare ID. Six months later, AVD-DS-0002 on its own is a mystery, and with a path and a sentence it is a decision.

Suppressed findings are hidden, not deleted. To see what you are currently ignoring, which is a good periodic audit:

trivy image --show-suppressed --ignorefile ./.trivyignore.yaml myapp:1.0

There is a more formal tool for the same problem, used when a vendor or maintainer wants to publish "this vulnerability does not affect product X, and here is why": VEX, short for Vulnerability Exploitability eXchange. A VEX statement says a CVE is not_affected, affected, fixed or under_investigation for a product, and Trivy can read such statements (from a file, a repository or an attached attestation) to suppress findings. You will meet it at the Mid level; for a beginner, .trivyignore.yaml with a statement and an expiry date is the right tool.

The cache and the database

Trivy feels fast because it does its heavy lifting once and remembers it. Understanding where that memory lives solves most "why is it slow" and "why did it do that" questions.

Everything is stored in the cache directory (~/.cache/trivy on Linux, ~/Library/Caches/trivy on macOS). Inside you will find:

• db/ holds the vulnerability database (trivy.db) and a metadata.json saying when it was built.
• java-db/ holds the Java database, present only after a scan that found JAR files.
• policy/ holds the downloaded misconfiguration checks bundle.
• fanal/ holds the scan cache: results of analysing image layers, keyed by layer hash, so scanning an image whose layers you have seen before is nearly instant.

On each run, Trivy checks whether its local database is recent enough, and downloads a fresh one if not. The database is rebuilt about every six hours, so a scan on Monday morning and one on Monday evening can legitimately disagree. That is a feature, not a flaw: it is why an image that passed yesterday can fail today without any change to the image.

You control this behaviour with a few flags worth knowing:

trivy image --download-db-only              # fetch the DB and stop
trivy image --skip-db-update myapp:1.0      # use the cached DB, do not check for a newer one
trivy image --cache-dir /tmp/trivy-cache myapp:1.0
trivy clean --all                           # delete the caches and start fresh

--skip-db-update is what you use when you are offline or when a pipeline pre-seeds the cache, but it only works if a database is already present. The older spelling --skip-update was removed, so if a tutorial uses it, the tutorial is out of date.

Two warnings. First, do not run two Trivy processes against the same cache directory at the same time: the database file is locked, and the second process fails with a message that the database "may be in use by another process". Give each its own --cache-dir. Second, there is a flag called --offline-scan, and its name misleads: it only stops Trivy making some remote lookups (such as to Maven Central); it does not stop the database download. For a genuinely offline machine you need the database already in place and --skip-db-update. The senior guide covers running fully air-gapped.

If the cache ever seems corrupt, or after a major upgrade produces a confusing database-schema error, trivy clean --all is the reset button.

Configuration: flags, environment variables and a config file

Typing the same six flags on every command is error-prone, and it makes it too easy for a pipeline and a laptop to disagree. Trivy lets you set any option in three ways, and they stack.

The command line is for one-off use. Environment variables are named TRIVY_ plus the flag in upper snake case, which suits CI, where you set them once for the whole job:

export TRIVY_SEVERITY=HIGH,CRITICAL
export TRIVY_IGNORE_UNFIXED=true
export TRIVY_TIMEOUT=15m
trivy image myapp:1.0

A config file named trivy.yaml in the current directory is read automatically, and is the right place for team policy that you want in version control. Every flag has a matching key, nested by topic:

severity:
  - HIGH
  - CRITICAL
scan:
  scanners:
    - vuln
    - secret
    - misconfig
  skip-dirs:
    - node_modules
    - vendor
vulnerability:
  ignore-unfixed: true
timeout: 10m
exit-code: 1

With that file in place, a bare trivy fs . applies the whole policy. Precedence decides conflicts: a flag on the command line beats an environment variable, which beats the file, which beats the built-in default. To generate a file listing every option with its default, run trivy image --generate-default-config, then delete everything you do not need; a short file is easier to review. Recent versions also publish a JSON Schema for the file, so an editor can validate your keys as you type.

A few defaults worth memorising, because they explain behaviour that otherwise looks arbitrary: the scan timeout is five minutes, the default scanners are vuln,secret, and the config file is looked up as trivy.yaml and the ignore file as .trivyignore. The timeout matters for large images: a five-minute limit that is fine for a slim service can be too short for a fat machine-learning image, in which case you will see a context deadline exceeded error and raise it with --timeout.

There is also a choice between two detection modes. The default, precise, reports what Trivy is confident about and produces fewer false positives. comprehensive adds less certain matches and produces more findings. Stay with the default until you have a reason, and if a colleague's scan shows different results from yours, compare this setting first, along with the database date.

Scanning a Kubernetes cluster

Kubernetes adds a fourth target: the running cluster. trivy kubernetes (or trivy k8s) connects using your kubeconfig, the same credentials kubectl uses, and scans what it finds. The Kubernetes guide (/student-guides/kubernetes) explains the objects involved, so read it first if Pods and Deployments are new.

trivy k8s --report summary

The command scans three layers: the cluster infrastructure (the API server, the kubelet and add-ons), the cluster configuration (roles and bindings, which decide who can do what) and the application workloads, including the images they run. By default it prints a summary, and --report all prints every finding.

A few flags you will reach for:

trivy k8s --report all --severity CRITICAL --scanners vuln,misconfig,secret
trivy k8s --include-namespaces prod,staging --exclude-kinds node
trivy k8s --skip-images
trivy k8s my-context --kubeconfig ~/.kube/config2

--include-namespaces narrows the scan, --skip-images avoids downloading and scanning every workload image (much faster, and you get configuration findings only), and naming a context chooses which cluster to scan if your kubeconfig holds several. Note that the old trivy k8s cluster and trivy k8s all subcommands no longer exist; the current form is trivy k8s [flags] [CONTEXT].

Your account needs permission to list many object kinds, and for node-level checks Trivy creates a short-lived job in a temporary namespace named trivy-temp. On a shared or production cluster, confirm with whoever owns it before you run a first scan, and start with --disable-node-collector if you want to avoid creating anything.

It can also measure the cluster against a named compliance benchmark:

trivy k8s --compliance=k8s-cis-1.23 --report all

Built-in specifications include k8s-nsa-1.0, k8s-cis-1.23, eks-cis-1.4 and the Pod Security Standards profiles. This is one way to answer "how do we measure up against the CIS benchmark" with a command instead of a spreadsheet. Continuous in-cluster scanning is done by a separate component, the Trivy Operator, which installs with Helm; the Mid-level guide covers it, and the Helm guide at /student-guides/helm is the place to learn the packaging.

Common errors and how to read them

Most Trivy errors fall into a handful of causes: the network, the cache, the image name, or a resource limit. The messages below are the real ones, with the cause and the fix.

A few more, in brief:

For anything else, two flags give you more information. --debug prints what Trivy is doing at each step, including which source it chose for an image and which database it loaded. --trace-http prints the HTTP traffic, which is excellent for proxy problems but may print tokens and other sensitive data, so never paste its output into a public place. And trivy clean --all resets the cache when its state is the problem.

A final habit: read an error from the end of the output upward. The last line is usually the cause and the lines above are the path Trivy took to get there.

Trivy's own supply chain: the March 2026 incident

A security scanner is itself software you download and run, often with access to your pipeline's secrets, and in March 2026 that stopped being a theoretical concern. Read this section carefully, because it shapes how you should install and use Trivy.

In March 2026 a threat actor used a compromised credential to publish malicious artifacts under Trivy's name. The official incident notice (GitHub discussion 10425, advisory GHSA-69fq-xp46-6x23) describes these pieces:

• The trivy binary v0.69.4 was malicious. It was available for about three hours on 19 March 2026. Versions v0.69.3 and earlier, and v0.70 and later, are the safe ones.
• Most tags of the aquasecurity/trivy-action GitHub Action before 0.35.0 were compromised for about twelve hours. Version 0.35.0 and later are safe.
• All releases that then existed of aquasecurity/setup-trivy were compromised, for about four hours. Version v0.2.6 and later are safe.
• Distribution channels affected included Docker Hub, GHCR, ECR Public, the deb and rpm repositories and the install-script host.

The official guidance is blunt: if an affected version ran in a pipeline, treat every secret that pipeline could see as compromised and rotate it immediately. It also lists a network address and a look-alike domain (spelled aquasecurtiy, with the typo) to block and to search logs for; take the exact indicators from the official notice rather than from this guide.

What matters for you is the lesson, which applies to every tool you use and not only this one. The attack worked because people referred to software by names that can move: a tag like latest, a branch like main, an action pinned as @v1. A name that can be re-pointed can be re-pointed by an attacker. The defences are simple habits, and you can adopt all of them on day one:

1. Pin exact versions. Install v0.74.0, never "latest". Pass the version to the install script. Use aquasec/trivy:0.74.0, not aquasec/trivy:latest.
2. Pin by digest where you can. A digest (aquasec/trivy@sha256:...) identifies exact content, and cannot be silently replaced.
3. Pin GitHub Actions by full commit SHA. A commit hash is immutable; a tag is not. Let a tool such as Renovate propose updates as reviewable pull requests.
4. Verify what you download against the published checksums and signatures.
5. Limit what a scan job can see. A scanner rarely needs your deployment credentials; give the job only what it needs.
6. Do not run an installer from a moving reference without a pinned version argument.

Putting it all together

Here is one small end-to-end project that uses everything so far: a tiny Python service, scanned as files, as infrastructure and as an image, with a policy file, an ignore file, a saved report, an SBOM and a gate. Build it once and this page becomes reference material.

Create a folder with a few files:

flask==2.0.1
requests==2.25.0

from flask import Flask

app = Flask(__name__)


@app.route("/")
def index():
    return "hello"


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8080)

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
EXPOSE 8080
CMD ["python", "app.py"]

severity:
  - HIGH
  - CRITICAL
scan:
  scanners:
    - vuln
    - secret
    - misconfig
vulnerability:
  ignore-unfixed: true

Now run the stages in order.

# 1. Scan the project's dependencies, secrets and config before building
trivy fs .

# 2. Check only the infrastructure files, including passes
trivy config --include-non-failures .

# 3. Build and scan the image
docker build -t demo:1.0 .
trivy image demo:1.0

# 4. Save the full report and an SBOM as build artifacts
trivy image --format json --output report.json demo:1.0
trivy image --format cyclonedx --output sbom.cdx.json demo:1.0

# 5. Apply the gate that a pipeline would use
trivy image --exit-code 1 demo:1.0
echo "gate exit code: $?"

Expect the project scan to flag the old pinned versions of flask and requests (they are deliberately old), and the config scan to flag the missing USER instruction. Fix them properly: raise the versions in requirements.txt to ones the report lists as fixed, add a non-root user to the Dockerfile, and rebuild:

FROM python:3.9-slim
RUN useradd --create-home appuser
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
USER appuser
EXPOSE 8080
CMD ["python", "app.py"]

Scan again and confirm that the gate's exit code is now zero. If something remains that you cannot yet fix, add it to a .trivyignore.yaml with a statement and an expiry date, rather than loosening the gate. Finally, write a short README section for whoever inherits the project: which scan runs where, what fails the build, and where the ignore file lives.

What you can now do, and what comes next

You can explain what a vulnerability scanner does and does not know, choose the right Trivy target for an artifact, read a report including status and fixed versions, filter it into a policy, find committed secrets, catch risky infrastructure settings, produce and rescan an SBOM, make a pipeline fail on purpose, suppress a finding with a reason and an expiry, configure Trivy once for a whole repository, scan a cluster carefully, and install the tool defensively after the March 2026 incident. That is a working practitioner's toolkit.

Mid-level takes every one of those topics further: how the scan works under the hood, the exact rules for caching and the database, CI patterns with SARIF and code scanning, VEX in practice, custom secret and misconfiguration rules, scanning private registries, Trivy Operator for continuous in-cluster scanning, and rescanning SBOMs on a schedule.

Senior covers running Trivy as a platform for a team: client and server mode with a shared cache, mirroring the database for air-gapped environments, securing the scanner's own supply chain, governance for ignores and exceptions, cost and scaling, upgrades across a 0.x release line, and where Trivy stops and another tool should take over.

Natural neighbours in this catalogue: the Docker guide (/student-guides/docker) for the images you are scanning, the Kubernetes guide (/student-guides/kubernetes) for the clusters, the Terraform guide (/student-guides/terraform) for the infrastructure you check, the Helm guide (/student-guides/helm) for packaging the operator, and the Argo CD guide (/student-guides/argo-cd) for delivering it.

Sources

• Trivy documentation
• Installation
• trivy image command reference
• Configuration file reference
• Troubleshooting
• Standalone mode
• Kubernetes scanning
• Filtering results
• Misconfiguration scanning
• Secret scanning
• SBOM
• VEX
• Trivy releases
• v0.72.0 highlights
• v0.73.0 highlights
• v0.74.0 highlights
• Security incident notice, 2026-03-19
• trivy-action

This page is for the moment someone asks you about Trivy across a table or a screen share. It assumes you have read the Beginner guide, or used the tool for a few days, and it is organised the way an interview goes: a short answer first, then the model, the commands, the traps, and practice questions with model answers. Read it twice: once to learn, once out loud.

The thirty-second answer

Trivy is an open-source scanner from Aqua Security that inspects container images, project folders, git repositories, infrastructure-as-code files and Kubernetes clusters, and reports known vulnerabilities, risky misconfigurations, leaked secrets and licences. It works by building an inventory of what is inside the target, without running it, and matching that inventory against a vulnerability database it downloads and caches locally.

The sentence to add if you have a few seconds more: it is a single binary that is easy to drop into a pipeline, and its exit code is what turns it from a report into a gate. That shows you have used it in anger and not only read about it.

The model

An interviewer who asks "how does it work?" wants the pipeline in order, in your own words.

Say it like this. You choose a target with a subcommand. Trivy unpacks it and its analyzers work out the operating system, the installed packages and the language dependency files, which gives a package inventory. The scanners you enabled compare that inventory, or the infrastructure files, against data: the Trivy DB for vulnerabilities, the checks bundle (Rego policies) for misconfigurations, built-in rules for secrets. The findings are then filtered (severity, ignore files, status) and rendered by a reporter in the format you asked for.

Four facts to have ready, because they are the ones that separate a user from a reader:

• Default scanners are vuln,secret. Misconfiguration and licence are opt-in with --scanners; trivy config runs only misconfiguration.
• The vulnerability database is rebuilt about every six hours and fetched as an OCI artifact into a local cache. So results change over time with no change to the artifact.
• Trivy does not execute anything. It reads files, which is why it is fast and also why it cannot see what is only visible at runtime.
• The exit code is zero by default, even with critical findings. --exit-code 1 makes findings fail a build.

A severity vocabulary also comes up: UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL. And a status vocabulary: fixed, affected, will_not_fix, fix_deferred, end_of_life.

Targets and what each is for

Be able to match target to situation without hesitating.

A good follow-up answer: scan early and scan late. The folder scan catches a vulnerable dependency at the pull request, before an image exists. The image scan catches what the base image added, which the folder scan cannot see. Mentioning both shows you understand they are complementary and not redundant.

The commands to have ready

You should be able to write each of these without looking anything up.

trivy image python:3.4-alpine                              # scan an image
trivy image --severity HIGH,CRITICAL alpine:3.15           # filter by severity
trivy image --ignore-unfixed alpine:3.15                   # hide what has no fix
trivy image --format json --output result.json alpine:3.15 # machine-readable output
trivy image --input myapp.tar                              # scan a saved tar
trivy fs .                                                 # scan a project folder
trivy repo https://github.com/user/repo                    # scan a remote repository
trivy config ./infra                                       # misconfiguration only
trivy image --exit-code 1 --severity CRITICAL myapp:1.0    # fail the build
trivy image --format cyclonedx --output sbom.cdx.json myapp:1.0   # produce an SBOM
trivy sbom sbom.cdx.json                                   # scan an SBOM
trivy clean --all                                          # reset the cache

And the combination that most interviewers are really asking for when they say "how would you gate a pipeline":

trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed myapp:1.0

Be ready to explain each piece: why HIGH,CRITICAL (volume and signal), why --ignore-unfixed (you cannot act on it, so failing teaches people to bypass the gate), and why --exit-code 1 (because the default is zero).

Reading a finding

Interviewers love to put a table in front of you and ask what you would do. Walk the columns. Library is the affected package, Vulnerability is the identifier, Severity is the rating, Status says whether a fix exists, Installed Version versus Fixed Version is the gap.

The answer that scores well is a triage order, not a list of columns. First critical and high findings with a fixed version: they are real and cheaply fixed, usually by rebuilding on a newer base image or upgrading a library. Then ask whether many findings share one cause, such as an old base image. Findings with no fix are noted and assessed for reachability. Low and unknown are last.

One subtlety to mention unprompted: the header line shows what Trivy thought the operating system was. If it could not identify one, OS-package results are missing and an empty report means "not understood", not "clean".

Suppression, done properly

The standard question is "how do you deal with a false positive, or a vulnerability you cannot fix yet?" The answer has four parts. Use an ignore file, .trivyignore for simple cases or .trivyignore.yaml (passed with --ignorefile) when you need a statement and path scoping. Give every entry a reason and an expiry date (exp: in the plain file, expired_at in the YAML). Keep the file in version control and require a review on changes. And audit what is suppressed with --show-suppressed.

vulnerabilities:
  - id: CVE-2023-29491
    statement: Terminal library is not used by this service.
    expired_at: 2026-12-31

If they push further, mention VEX (Vulnerability Exploitability eXchange): a standard way to state that a vulnerability is not_affected, affected, fixed or under_investigation for a product, which Trivy can consume through --vex. The beginner-level answer is that an ignore file is a local decision and VEX is a shareable, structured one.

The cache and the database

Two questions are common here: "why did the result change?" and "why is it slow?". Both come from the same model. The database lives in a cache directory (~/.cache/trivy on Linux), is refreshed when stale, and is rebuilt about every six hours upstream. So an image that passed yesterday can fail today: the image did not change, the knowledge did. The remedies for slowness are to keep the cache between CI runs, to restrict scanners with --scanners vuln, and to skip directories that do not matter.

Mention the two flags people get wrong. --skip-db-update (the old --skip-update spelling was removed) uses the cached database without checking for a newer one and needs a database already present. --offline-scan does not stop the database download; it only limits certain remote lookups, so it is not the flag for an air-gapped machine.

The classic traps, and why they happen

Most traps share a cause: people read a tool's silence as approval. Keep that sentence and each trap below is an instance of it.

The March 2026 incident, in an interview

You are likely to be asked about it, since it was a widely reported event and it concerned the tool itself. Have a calm, factual two-minute answer.

In March 2026 an attacker used a compromised credential to publish malicious artifacts under the project's name. The trivy binary v0.69.4 was malicious for about three hours. Most tags of aquasecurity/trivy-action before 0.35.0 were compromised for about twelve hours, and all then-existing releases of aquasecurity/setup-trivy for about four hours. Safe versions are v0.69.3 and earlier, v0.70 and later, trivy-action 0.35.0 and later, and setup-trivy v0.2.6 and later. The official guidance for anyone who ran an affected version in a pipeline was to treat the pipeline's secrets as compromised and rotate them.

Then the part that shows judgement: what you do differently. Pin exact versions, pin images by digest, pin GitHub Actions by full commit SHA, verify checksums and signatures, give scan jobs minimal credentials, and do not pipe an install script from a moving branch without a version argument. Finish with a balanced sentence: it is not a reason to abandon the tool, it is a reason to apply supply-chain hygiene to every tool, including the ones that guard you.

Common interview questions

What is Trivy, and what does it scan? An open-source scanner for images, filesystems, repositories, IaC and Kubernetes clusters. It finds known vulnerabilities in OS and language packages, misconfigurations, hard-coded secrets and licence information, by matching an inventory of what is inside the target against local data.

Does Trivy run my container? No. It reads the image's layers and files statically. That is why scans are fast and need no privileges to execute anything, and why it cannot find runtime-only problems.

A scan passed last week and fails today with no code change. Why? The vulnerability database is rebuilt about every six hours, so new flaws are added continuously. The artifact is the same, but what is known about it changed. This is expected, and it is why teams rescan stored images or SBOMs on a schedule.

How do you make a CI job fail on serious findings? trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed <image>. The exit code is zero by default, so it must be set explicitly. I would print the full report before the gate so the reason is visible.

Why --ignore-unfixed? A finding with no available fix cannot be acted on by upgrading, and blocking builds on it trains people to bypass the gate. I would still track unfixed findings in a non-blocking report.

What is the difference between trivy fs and trivy image? fs scans a directory, mostly reading lock files; image scans the built artifact, including the operating system packages the base image added. They catch different things, so using both is sensible.

How do you scan an image on a CI runner with no Docker daemon? Use --image-src remote to pull straight from the registry, or scan a saved tarball with --input.

What are the default scanners, and how do you change them? vuln and secret. Use --scanners to choose, for example --scanners vuln,misconfig. trivy config runs only the misconfiguration scanner.

How would you handle a false positive? Add it to an ignore file with a statement and an expiry date, keep the file in version control with review, and use --show-suppressed to audit. If the claim is that a vulnerability does not affect our product, VEX is the structured way to say so.

What is an SBOM, and what does Trivy do with one? A standard inventory of the packages in an artifact, in CycloneDX or SPDX. Trivy can produce one with --format cyclonedx or spdx-json, and can scan one with trivy sbom. The value is that you can rescan the inventory later without the image.

Why does a CycloneDX file from Trivy list no vulnerabilities? By default it contains components only. Adding --scanners vuln embeds vulnerability data.

What is a misconfiguration, and how is it different from a vulnerability? A vulnerability is a known flaw in someone else's software; a misconfiguration is a risky setting in your own files, such as a container running as root or a public bucket. Trivy finds them with Rego-based checks over Dockerfiles, Kubernetes manifests, Terraform, CloudFormation and Helm.

What would you do if Trivy reports a leaked secret? Rotate the credential first, because it must be assumed exposed, then remove it from the code and use a secrets manager. Deleting the line alone is not a fix, and in an image a deleted file can still exist in an earlier layer.

What are the limits of Trivy? It only finds known vulnerabilities in packages it can detect. It cannot see flaws not yet published, copied-in code that no package manager installed, or runtime behaviour, and it scans the working tree rather than git history. It also cannot tell you whether the vulnerable code path is reachable.

How do you keep scans fast? Cache the database between runs, limit scanners to what you need, skip irrelevant directories, and raise --timeout for large images rather than retrying.

What does x509: certificate signed by unknown authority mean, and how do you fix it? Usually a proxy that inspects TLS traffic. Point Trivy at the corporate certificate with SSL_CERT_FILE; disabling verification is a last resort.

Sixty-second self-test

Cover the answers and say them out loud. If you hesitate on more than two, reread the matching section of the Beginner guide.

1. What does Trivy scan, and does it run anything? Images, folders, repos, IaC and clusters; no, it reads files.
2. Name the four scanners and the two on by default. vuln, misconfig, secret, license; vuln and secret.
3. Why can a scan change between Monday and Tuesday? The database is rebuilt about every six hours.
4. What is the default exit code with critical findings present? Zero; use --exit-code 1.
5. Write the command for a sensible gate. trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed myapp:1.0
6. What must every ignore entry have? A reason and an expiry date.
7. How do you scan without the image later? Save an SBOM and run trivy sbom.
8. What is wrong with aquasecurity/trivy-action@main? A moving reference; pin a full commit SHA of a safe release.
9. Which version of the binary was malicious? v0.69.4.
10. What does an empty report not prove? That the artifact is safe: only that nothing known was found in what was recognised.

If you answered all ten, you can handle the beginner round on Trivy. The next step is the Mid-level guide, which covers how the scan works under the hood, VEX, CI integration and continuous scanning in a cluster.

How to answer when you do not know

Some questions will reach past this page. A strong answer to an unfamiliar Trivy question is not a guess; it is a method. Say what you would check and where. "I would run trivy <command> --help to see the current flags, because Trivy is a 0.x tool and they change between minor versions", followed by "and I would check the release highlights for the version we pin", is a better answer than a confident wrong flag. Interviewers for security and platform roles are listening for exactly that calibration: you know the model, you know the main commands, you know which details move, and you know where the authoritative source lives.

Two closing habits help. First, tie every answer to a decision: not just what a flag does, but why a team would choose it. Second, when you mention a limit of the tool, pair it with the complementary control, such as a history-scanning tool for old secrets, or a runtime tool for behaviour Trivy cannot see. That shows you treat scanning as one layer in a defence, not as the whole defence.

This page collects what goes wrong in the first weeks with Trivy and the habits that prevent it. It is deliberately practical: each mistake has a symptom you will actually see, a cause, and a fix. Skim it once now and come back when a scan behaves strangely.

Common errors at this level

The pipeline is green but the image has critical flaws

Symptom: a CI job runs trivy image myapp:1.0, prints a long table with critical findings, and the job succeeds. Cause: Trivy exits with zero by default. Finding problems counts as a successful scan. The GitHub Action's exit-code input also defaults to 0. Fix: state the policy explicitly.

trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed myapp:1.0

Check it once by scanning a deliberately old image such as python:3.4-alpine and confirming the job goes red. A gate you have never seen fail is a gate you do not know works.

The report is empty, and that feels suspicious

Symptom: a scan of an image or folder prints nothing, or only some sections. Cause: either the target is clean, or Trivy did not understand it. A minimal image built from scratch has no operating-system package database, and an unusual file layout may hide a lock file. Fix: read the header line, which names the operating system Trivy detected, and confirm each section you expect is present. Run with --debug to see what was analysed. Compare with a known-vulnerable image to confirm the tool is working at all.

A scan result changed overnight

Symptom: the same image passed on Monday and fails on Tuesday. Cause: the vulnerability database is rebuilt about every six hours. Nothing is wrong; something new was learned. Fix: accept that "passed once" is not a permanent state. Rescan on a schedule, and keep an SBOM of each release so you can rescan the inventory without pulling the image.

The timeout

Symptom: analyze error: timeout: context deadline exceeded. Cause: the default timeout is five minutes, and a large image, many Java archives or a slow network can exceed it. Fix: raise it (--timeout 15m or TRIVY_TIMEOUT=15m), and also reduce the work: --scanners vuln, --skip-dirs for folders you do not need.

"Unable to initialize an image scanner"

Symptom: unable to initialize a scanner: unable to initialize an image scanner. Cause: Trivy could not obtain the image. The name has a typo, the Docker daemon is not running, a private registry needs credentials, or a proxy is in the way. A name with no registry prefix defaults to Docker Hub, which surprises people using a private registry. Fix: run docker pull on the same name first. If there is no daemon (common in CI containers), add --image-src remote or scan a tarball with --input.

Certificate errors behind a company proxy

Symptom: x509: certificate signed by unknown authority, often while downloading the database. Cause: a proxy that inspects TLS presents its own certificate, which Trivy does not trust. Fix: export the company CA certificate and point Trivy at it.

export SSL_CERT_FILE=/path/to/company-ca.pem
trivy image alpine:3.20

TRIVY_INSECURE=true also makes the error go away, but it turns off verification, which is the protection TLS provides. Keep it for a short experiment, never a pipeline.

The database will not download

Symptom: FATAL failed to download vulnerability DB, or DENIED: denied from ghcr.io. Cause: a firewall blocks ghcr.io or mirror.gcr.io, rate limits apply, or stale credentials for ghcr.io are being sent. Fix: allow those hosts or configure a proxy. For DENIED, run docker logout ghcr.io and unset GITHUB_TOKEN. On locked-down networks, ask your platform team about an internal mirror, which the Senior guide covers.

Two scans at once break each other

Symptom: cache may be in use by another process. Cause: the database is a locked file, and two Trivy processes are using one cache directory, for example parallel CI jobs on a shared runner. Fix: give each process its own --cache-dir, or run a Trivy server that holds the database for everyone.

The disk fills up

Symptom: write /tmp/fanal-...: no space left on device. Cause: Trivy unpacks artifacts into a temporary directory, and /tmp is small. Fix: TMPDIR=/path/with/space trivy ..., and reduce work with --skip-dirs.

The package that never upgrades

Symptom: apt upgrade never installs anything newer than 0.71.2. Cause: the repository line still contains a release codename. Since v0.72.0, new versions are published only to the generic distribution. Fix:

echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main" | sudo tee /etc/apt/sources.list.d/trivy.list
sudo apt-get update && sudo apt-get install trivy

The same release stopped publishing architecture-specific image tags such as 0.71.0-amd64. A pull of one of those fails; use the plain tag or a digest.

The flag that does not exist

Symptom: unknown flag: --security-checks or --skip-update from a tutorial. Cause: the tutorial is out of date. --security-checks became --scanners, and --skip-update became --skip-db-update. Fix: run trivy image --help and use what it lists. Prefer the official documentation over old blog posts, because Trivy is a 0.x tool whose flags do change.

The habits that pay off most

These are ordered by how much trouble they prevent for the effort they cost.

1. Pin the version of Trivy everywhere. Exact version, never latest, never a moving branch. After the March 2026 incident this is the most valuable habit, and it also makes scan results reproducible.
2. Make the gate explicit and test it. Write the policy as flags in a config file, and prove it can fail.
3. Put an expiry and a reason on every ignore. Review the ignore file like code.
4. Scan twice: the folder, then the image. One catches a dependency at the pull request; the other catches what the base image brought.
5. Prefer small, current base images. Most findings in a typical image come from the base, and a slim or recent one removes many at once.
6. Commit lock files. They give Trivy exact versions to match, and they make builds reproducible anyway.
7. Save the JSON report and an SBOM as build artifacts. You can convert or rescan them later.
8. Treat reports as sensitive. They list what you run and where it is weak.
9. Rotate a secret the moment Trivy finds one. Then remove it.
10. Read the release notes when you upgrade. Trivy is 0.x, and minor versions can change flags and output.

Practice cards

Do one card at a time. Each takes about ten minutes.

Reading a scan in five minutes

When you inherit a report or run one on an unfamiliar project, a fixed routine saves time and prevents the two common mistakes: drowning in rows, and trusting an empty page.

First, read the header for each section. Does the detected operating system match what you expect? Are the sections you expect present, such as both OS packages and a language ecosystem? Second, read the summary line for each section and note the count by severity. Third, filter to what matters, with --severity HIGH,CRITICAL --ignore-unfixed, and read those rows. For each, note the library and ask whether it came from the base image or from your dependency file. Fourth, fix in bulk where you can: a new base image tag can clear dozens of rows at once. Fifth, deal with what remains one at a time: upgrade, ignore with a reason and an expiry, or record as a risk with an owner.

A useful side habit is to look at the fixed version more than the severity. Severity tells you how worried to be; the fixed version tells you what to do. A row with a fixed version is a task. A row without one is a note.

trivy image --severity HIGH,CRITICAL --ignore-unfixed myapp:1.0
trivy image --dependency-tree myapp:1.0

Keeping scans fast

Slow scans are the main reason teams drop a scanner from the pipeline, so they are worth a little effort.

The cache is the biggest lever. The first scan on a clean machine downloads the database, a few hundred megabytes, and every scan after that reuses it. In CI, keep the cache directory between runs, using your CI system's cache feature, or every job pays the download again. The GitHub Action caches by default.

Next, scan only what you need. --scanners vuln skips secret detection, which is worthwhile on very large images when secrets are checked in the source repository. --skip-dirs and --skip-files remove folders that add no information, such as an installed node_modules when the lock file is scanned already.

Then, do not scan the same thing twice. If a release image is built once and promoted through environments, scan it once at build time and save the report. If you only changed documentation, a path filter on the pipeline can skip the job.

Finally, respect the timeout. A scan that regularly hits five minutes should have its timeout raised deliberately, and its image examined: a very large image is usually a sign that a smaller base would serve better, which also shrinks the attack surface.

Scanning locally before you push

The cheapest place to catch a problem is on your own machine, in seconds, before anyone else sees it. Keep a tiny script in the repository so running the same checks is one command:

#!/usr/bin/env bash
set -euo pipefail

echo "== dependencies, secrets and IaC =="
trivy fs --scanners vuln,secret,misconfig --severity HIGH,CRITICAL --ignore-unfixed .

echo "== image =="
docker build -t local-scan:latest .
trivy image --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 local-scan:latest

Because the script applies the same flags as your pipeline, "it passed on my machine" and "it passed in CI" mean the same thing, which removes a whole class of arguments. If you use a pre-commit hook, the secret scan alone (trivy fs --scanners secret .) is quick enough to run on every commit and is the most valuable single check to run that early.

Platform gotchas

• macOS with Docker Desktop or Colima: Trivy reads images from whichever Docker socket your environment exposes. If it cannot find your local image, check that docker images shows it from the same shell, or use --image-src docker.
• Windows: the officially supported install is the release zip. Docker Desktop with WSL2 and the Linux instructions is the most reliable combination.
• Apple silicon and ARM machines: an image scanned may be for a different architecture from your machine. Use --platform linux/amd64 or linux/arm64 to choose the one you ship.
• Running Trivy in a container: mounting the Docker socket gives that container broad power over the host. Fine on a laptop; in shared CI prefer --image-src remote or a tarball.
• Corporate networks: a TLS-inspecting proxy, a firewall blocking ghcr.io, or rate limits are the usual causes of download failures. Your platform team may provide an internal mirror.
• Data residency: a default scan uploads nothing about your code or images; it downloads a public database. That is useful to know when a security reviewer at a bank or a government-adjacent employer in the Gulf or Egypt asks where your data goes.

Small things to do from day one

• Run trivy --version in your CI log so every scan records the version used.
• Add .trivyignore.yaml to your repository template with an example entry containing a statement and an expiry.
• Add the cache directory to the CI cache.
• Keep scan reports out of public artifacts.
• Put a line in your README: what is scanned, what blocks a merge, where exceptions live.
• Subscribe to the release announcements, and read the highlights when a new minor version arrives.
• Learn the two neighbouring guides: Docker (/student-guides/docker) for the images, and Kubernetes (/student-guides/kubernetes) for the clusters.

A starter setup to copy

Here is a small set of files to drop into a new repository. It pins the tool, sets the policy once and keeps exceptions reviewable.

severity:
  - HIGH
  - CRITICAL
scan:
  scanners:
    - vuln
    - secret
    - misconfig
  skip-dirs:
    - node_modules
vulnerability:
  ignore-unfixed: true
exit-code: 1
ignorefile: .trivyignore.yaml
timeout: 10m

vulnerabilities: []
misconfigurations: []
secrets: []

name: scan
on:
  pull_request:
  schedule:
    - cron: "0 5 * * 1"
jobs:
  trivy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Scan the repository
        # Replace <full-commit-sha> with the verified commit of a safe release
        uses: aquasecurity/trivy-action@<full-commit-sha>
        with:
          scan-type: fs
          scan-ref: .

The weekly schedule matters: it rescans unchanged code against the newest database, which catches findings that appear without any commit. The placeholder in the workflow is deliberate. Look up the commit of a release at or above the safe version in the official repository, verify it, and paste the full hash, so the reference cannot be silently moved. See the GitHub Actions guide (/student-guides/github-actions) for workflow basics.

The beginner's checklist

Before you call your Trivy setup "done", check each line.

• Trivy is installed at a version I chose, and it is not v0.69.4.
• I can say what each of my scan commands targets and which scanners it runs.
• My pipeline step fails on purpose for the policy I wrote, and I have seen it fail.
• The policy lives in trivy.yaml, not in someone's memory.
• Every ignore has a reason and an expiry date, and the file is reviewed.
• The database cache is kept between CI runs.
• A scheduled job rescans unchanged code.
• Reports and SBOMs are saved, and treated as sensitive.
• The tool, its image and any GitHub Action are pinned (digest or full commit SHA).
• Secrets found by a scan are rotated before they are removed.
• I know what an empty report does not prove.

If every box is ticked you have a setup that most teams do not have, and you are ready for the Mid-level guide.

When a finding does not make sense

Occasionally a row looks wrong: a library you do not recognise, a version you did not install, or a vulnerability in something you already upgraded. Work through a short list before raising it with anyone.

You did not install that library. It is almost certainly a transitive dependency, pulled in by something you did choose. Re-run with --dependency-tree to see the chain, and upgrade the top of the chain. If the library comes from the operating system instead, it belongs to the base image, and the remedy is a newer base tag.

You upgraded, but the finding is still there. The scan may be reading a stale image. Confirm that you rebuilt, that the tag you scan is the tag you built, and that an old copy in the local daemon is not shadowing a newer one in the registry. Scanning by digest removes the ambiguity. Also check that the old version is not still present in an earlier layer or a second lock file in a subfolder.

The finding says it is fixed, but upgrading does not remove it. The fixed version listed is for a particular release line. On a distribution image, the fix arrives in the distribution's own package version, so the answer is often to rebuild from an updated base image and not to install a newer upstream version by hand.

The severity differs from a website you checked. Trivy picks the most appropriate source for each package, and distributions sometimes rate the same CVE differently from the general database, because they know whether the vulnerable code is compiled in or exposed. This is expected. Judge by the row Trivy shows you, and use the linked advisory for the reasoning.

Your colleague sees different results. Compare three things: the Trivy version, the age of the database (the metadata file in the cache), and the detection mode. Different versions or a stale cache explain most disagreements. Running both machines with trivy --version and a fresh trivy image --download-db-only usually settles it.

trivy --version
cat ~/.cache/trivy/db/metadata.json

Keep notes on findings you investigated and their outcome. The notes become the statement text in your ignore file, and the pattern of what you investigated tells you where the real weak spots in your build are.

This is part two of three. It picks up where Beginner ended, and its aim is that a scan result stops being a wall of CVE numbers and becomes something you can predict, explain and defend. You already run Trivy. By the end of this level you will know why an image that passed on Monday fails on Tuesday with no change to the code, how to keep a pipeline gate strict without drowning the team in noise, how to suppress a finding so that the suppression is reviewed and expires, and how to run the tool so that the tool itself is not the weakest link in your supply chain. This version of the guide is written against Trivy v0.74.0, released on 14 August 2026.

Where this picks up

Each section starts with the problem it solves and ends with a Try it you can run on a real project in a few minutes. Commands assume a recent 0.7x release. Trivy is still a 0.x project, so minor releases may change flags or output, and whenever a flag matters to you, trivy <command> --help is the authority for the version you have installed.

How a scan actually works

The problem this section solves is unpredictability. If you treat Trivy as a box that prints CVEs, every surprising result is a mystery: why was that library missed, why did the scan take nine minutes, why does the same image give different answers on two machines. The pipeline underneath is short enough to hold in your head, and once you can, most of those questions answer themselves.

A scan has five stages. First, Trivy obtains the artifact: it pulls or reads the image, walks the directory, or clones the repository. For an image it unpacks every layer in turn. Second, analyzers run over the files it finds. An analyzer is a small piece of code that recognises one kind of file: the operating system release file, the dpkg or apk or rpm package database, a package-lock.json, a go.mod, a poetry.lock, a JAR, a Dockerfile, a Kubernetes manifest. Third, the analyzers' output is merged into a package inventory, which is the list of everything Trivy believes is installed, with names, versions and where each was found. Fourth, scanners take that inventory and match it against data: the vulnerability scanner against the Trivy DB, the license scanner against a license classification, the misconfiguration scanner against Rego checks, the secret scanner against regular expressions. Fifth, the findings go through filters (severity, ignore files, VEX statements) and are rendered by a reporter in the format you asked for.

The single most useful consequence of this design is this: Trivy can only report on what an analyzer recognised. It does not execute your code, it does not guess, and it does not read your mind about what you vendored. A library copied into your source tree as files, a binary downloaded by a curl in a Dockerfile, a Python package installed by hand without metadata: none of these appear in any package database or lock file, so none of them are in the inventory, so none can be matched. A clean scan means "no known vulnerabilities in the packages Trivy could identify", which is a weaker statement than "this image is safe". Keep the difference in mind when you read a green pipeline.

The second consequence concerns where Trivy looks. In an image scan, operating system packages (the os-pkgs class in the results) come from the package manager database inside the image, and language packages (lang-pkgs) come from lock files and installed-package metadata. For source directories with trivy fs, language packages come from lock files in the tree. That means a package.json without a lock file yields a weak result, because a manifest lists ranges rather than the exact versions that would be installed, and the scanner needs exact versions to match against advisories. If a Node or Python project has no lock file checked in, fix that before you tune anything else.

The third consequence is about layers. Trivy analyses each layer and caches the result keyed by the layer's hash, in the fanal directory of its cache. A second scan of an image that shares its base layers with one you scanned earlier skips the unpacking work for those layers. This is the same idea as the Docker build cache, and it is why the second scan of anything is much faster than the first, and why putting a fresh cache in front of every CI job (an empty runner) makes every scan pay the full cost.

There is also a choice of how Trivy reads an image. By default --image-src tries docker,containerd,podman,remote in that order: if a local daemon has the image, it is read from there, and otherwise Trivy fetches it from the registry. Two things follow. A locally built myapp:dev is scanned from your daemon, never from a registry, which is exactly what you want before a push. And on a CI runner with no Docker socket, the daemon sources all fail and the lookup falls to the registry, which fails for an image that only exists locally. You then either save the image with docker save and scan with --input image.tar, or push first and scan the pushed reference with --image-src remote.

trivy image --image-src docker myapp:dev          # force the local daemon, fail loudly if absent
trivy image --image-src remote ghcr.io/org/app:1.4.2   # registry only, no daemon needed
docker save myapp:dev -o myapp.tar && trivy image --input myapp.tar
trivy image --platform linux/arm64 ghcr.io/org/app:1.4.2   # a specific architecture from a multi-arch index

The database, and why yesterday's green image turns red

The problem: a team ships an image on Monday with a clean scan, and on Wednesday the same image, byte for byte, fails the gate. Nobody changed anything. This is not a bug, and it is not flakiness. It is the defining property of vulnerability scanning: the software did not change, the knowledge about it did.

The Trivy DB is an aggregation of advisory sources: the National Vulnerability Database, distribution security trackers (Debian, Ubuntu, Alpine, Red Hat and others), the GitHub Advisory Database and more. It is rebuilt about every six hours and published as an OCI artifact in a registry. By default Trivy tries mirror.gcr.io/aquasec/trivy-db:2 and then ghcr.io/aquasecurity/trivy-db:2; the 2 is the schema version, so a Trivy release that expects schema 2 will not read a database with a different schema. On your machine the DB is a BoltDB file, db/trivy.db plus a small metadata.json, in the cache directory (~/.cache/trivy on Linux, ~/Library/Caches/trivy on macOS). Each scan checks whether the cached copy is stale and downloads a new one if so. This is the moment that dominates the runtime of small scans in CI.

Alongside the main DB there are supporting data sets, each with its own download. The Java DB maps JAR checksums to Maven coordinates, so Trivy can identify JARs that carry no POM metadata; it is fetched only when a scan actually finds JAR files. The checks bundle holds the Rego misconfiguration checks and is published as trivy-checks; a copy is also embedded in the binary as a fallback. VEX Hub provides community VEX statements. Every one of these is a network dependency, and each has a flag to skip its update and a flag to point it at a mirror.

trivy image --download-db-only                   # warm the vulnerability DB and exit
trivy image --download-java-db-only              # same for the Java DB
trivy image --skip-db-update myapp:1.0           # use what is cached, do not check for a newer DB
trivy --version                                  # prints Trivy, DB, Java DB and checks bundle versions once cached
trivy clean --vuln-db                            # remove just the DB; `trivy clean --all` removes every cache

The practical rule that follows: a pass is a statement about a point in time. Design for that. A build-time gate answers "is this artifact acceptable to ship now", and a scheduled rescan answers "is what we already shipped still acceptable". They are different jobs and you need both. For the second job you do not want to re-pull every image in the fleet. Generate an SBOM once at build time and rescan the SBOM as often as you like with trivy sbom, which only needs the fresh DB and not the image. The SBOM section later in this guide builds that pipeline.

When a scan result confuses you, check the versions before anything else. trivy --version shows the DB build date, and the --debug output prints which repository the DB came from. Two engineers comparing results across laptops are very often comparing two different DB snapshots, and the fix is to compare the metadata.json timestamps, not to argue about the CVE.

Reading results precisely

The problem: a table with four hundred rows is not a decision. To turn it into one you need to know what each column means and, more importantly, which filters are changing the list before you ever see it.

Every finding carries a severity and a status. Severity is one of UNKNOWN, LOW, MEDIUM, HIGH or CRITICAL. It is not one universal number. Different sources rate the same CVE differently: NVD may say CRITICAL while a distribution that has examined how its own build is exposed says MEDIUM. Trivy picks which vendor's rating to show through vulnerability.severity-source, which defaults to auto, meaning it prefers the distribution's rating for OS packages and falls back to others. If two tools disagree about severity, the first question is whose rating each is using.

Status is the part beginners skip and mid-level engineers should not. It tells you what the vendor says about a fix. fixed means a patched version exists and is listed in the Fixed Version column. affected means the vulnerability applies and no fix has been published. will_not_fix means the distribution has decided not to patch it, typically because the impact is minor for their packaging. fix_deferred means a fix is planned but postponed. end_of_life means the package or the whole release has left support, so no fix will ever come. These statuses are what --ignore-status filters on, and they let you write a precise policy rather than a blanket one:

# Fail only on things a developer can actually act on
trivy image --severity HIGH,CRITICAL --ignore-status will_not_fix,fix_deferred,end_of_life \
  --exit-code 1 myapp:1.4.2

# The common shortcut: hide anything without a fix (fixed-only view)
trivy image --ignore-unfixed --severity HIGH,CRITICAL myapp:1.4.2

Read the second command carefully, because it teaches the core trade-off of gating. --ignore-unfixed hides every finding that has no available fix. That makes the gate actionable, since the team can only be asked to fix what is fixable, and it removes most noise from large base images. It also means a critical vulnerability with no patch is invisible in the gate output. The standard answer is to run the strict, actionable gate on every pull request and a separate scheduled report with no --ignore-unfixed, reviewed by a person weekly. The gate keeps velocity, the report keeps honesty.

Two more dials change what counts as a finding. Detection priority is precise by default, which reports only findings where Trivy is confident the vulnerable version is present. --detection-priority comprehensive also reports less certain matches, which is useful for an audit and painful in a gate. Package filters narrow the inventory before matching. --pkg-types os,library selects operating system packages, language libraries, or both (both by default). --pkg-relationships accepts unknown, root, workspace, direct and indirect, which lets you ask only about direct dependencies, the ones your team chose. Development dependencies are skipped by default in language scans, and --include-dev-deps adds them back.

The result also has structure worth reading. Each Result block is one target and one class: for an image that is typically the operating system (alpine 3.20.3 (alpine), class os-pkgs) followed by one block per language file found (Node.js (node-pkg), Python (python-pkg)), each with a summary such as Total: 12 (HIGH: 10, CRITICAL: 2). A vulnerability in a transitive library can be hard to fix unless you know who pulled it in, and --dependency-tree renders the path from your direct dependency down to the vulnerable one. Since v0.67, --list-all-pkgs is on by default, so JSON output includes the full package list and not only the vulnerable ones, which is what makes SBOM-like downstream use possible but also makes JSON files larger than they used to be.

trivy image --format json --output result.json myapp:1.4.2
# Who is affected, and which fix would close the most findings?
jq -r '.Results[] | select(.Vulnerabilities) | .Vulnerabilities[]
  | select(.FixedVersion != null) | "\(.PkgName)\t\(.InstalledVersion) -> \(.FixedVersion)\t\(.VulnerabilityID)"' result.json \
  | sort | uniq -c | sort -rn | head

Grouping by package, as that jq does, is usually the fastest route to a manageable plan. Four hundred findings are often thirty packages, and a dozen of those come from one base image. Upgrading the base image is one change that closes dozens of rows. The table is arranged by CVE, but your remediation is arranged by package and by layer.

Choosing scanners, and making scans fast

The problem: out of the box a scan does more than you need for one job and less than you need for another. The default scanners are vuln and secret. Misconfiguration and license scanning are opt-in, and trivy config runs only the misconfiguration scanner. Knowing this avoids two opposite mistakes: paying for secret scanning on a job that only needs CVEs, and assuming your Dockerfile was checked when nobody enabled misconfig.

trivy image --scanners vuln myapp:1.4.2                       # fastest, CVEs only
trivy fs --scanners vuln,secret,misconfig,license .           # everything, for a scheduled audit
trivy image --image-config-scanners misconfig,secret myapp:1.4.2   # check image config and history too

Speed matters because slow gates get bypassed. Most of the wall-clock time of a scan comes from five places, and the levers for each are direct. Database download is the first, solved by caching the cache directory between jobs or by server mode, both covered later. Layer unpacking is the second, solved by the layer cache for repeat scans and by --skip-dirs and --skip-files for the parts you know are irrelevant. File walking is the third: trivy fs . in a repository with a checked-out node_modules or a vendor directory will crawl every file, so skip them explicitly and scan the lock file instead. Secret scanning is the fourth, because it reads the content of many files against many regular expressions; turn it off with --scanners vuln when you do not need it, or narrow the rule set. Java is the fifth: image scans that contain many JARs pull the Java DB and then identify each archive.

trivy fs --skip-dirs node_modules,vendor,.git --scanners vuln,secret .
trivy fs --skip-files "**/*.min.js" --scanners secret .
trivy image --parallel 2 --max-image-size 2GB bigimage:latest   # bound memory and work on small runners
trivy image --timeout 15m hugeimage:latest                        # the default is 5m
TMPDIR=/mnt/bigdisk trivy repo https://github.com/org/monorepo    # temp files can be large for clones

The default --parallel is 5. On a CI runner with two CPUs and a large image, more parallelism can cause memory pressure rather than speed; on a large runner, raising it helps. The error that signals you hit the ceiling is analyze error: timeout: context deadline exceeded: your scan exceeded the five-minute default. Raise --timeout as a conscious choice, after deciding that the scan should take that long, not as a reflex. A scan that takes twenty minutes is usually a scan that is walking something it should skip.

Suppression that stays honest

The problem: some findings you will not, or cannot, fix today. The library has no patch. The vulnerable code path is never reached. The finding is in a test fixture. If the only tool you have is "turn the gate off", the gate eventually gets turned off. Trivy gives you several ways to record a decision, and they differ in how well they keep the decision honest over time.

The simplest is .trivyignore, a plain list of IDs read from the working directory by default. It is fast and it has one important feature, the expiry marker:

# Accepted until the vendor ships 2.4.1 (ticket SEC-1432)
CVE-2019-14697 exp:2026-12-31
# Dockerfile runs as root in this build-tool image on purpose
AVD-DS-0002

A comment above each entry and an exp: date make this tolerable for a small repository. It has two limits: it cannot say where the ignore applies, so the ID is suppressed everywhere, and it cannot hold a structured reason. The YAML form, selected with --ignorefile ./.trivyignore.yaml, fixes both:

vulnerabilities:
  - id: CVE-2022-40897
    paths:
      - "usr/local/lib/python3.9/site-packages/setuptools-58.1.0.dist-info/METADATA"
    statement: "Build-time only, removed in the runtime stage. Owner: platform team"
    expired_at: 2026-12-31
  - id: CVE-2023-3817
    purls:
      - "pkg:deb/debian/libssl1.1"
misconfigurations:
  - id: AVD-DS-0002
    paths: ["docs/Dockerfile"]
    statement: "Tooling image, never deployed"
secrets:
  - id: aws-access-key-id
    paths: ["tests/fixtures/fake-credentials.txt"]
licenses:
  - id: GPL-3.0

The paths and purls fields scope the suppression to a file or a package, statement records the reason, and expired_at makes the suppression lapse on its own. When it lapses, the finding returns and someone has to look again, which is the entire point. Add --show-suppressed to list what is currently being ignored; in a review this is how you find a graveyard of forgotten ignores. A healthy policy, which you can enforce in code review, is that every entry has a statement, a scope and an expiry.

The third mechanism is VEX, the Vulnerability Exploitability eXchange. Where an ignore file says "hide this", a VEX document makes a structured, shareable claim: for this product, this vulnerability has the status not_affected (with a justification such as the vulnerable function not being present or not reachable), affected, fixed or under_investigation. Trivy can read VEX from four sources and apply them in the order you list them:

trivy image --vex repo myapp:1.4.2               # VEX repositories, including VEX Hub
trivy image --vex ./openvex.json myapp:1.4.2     # a file you maintain (OpenVEX, CSAF or CycloneDX VEX)
trivy image --vex oci myapp:1.4.2                # attestations attached to the image in the registry
trivy sbom --vex sbom-ref app.cdx.json           # a VEX reference recorded in the SBOM

Since v0.73, VEX attestations attached to an image are discovered both as OCI 1.1 referrers and as bare in-toto statements, and artifacts that are not VEX are skipped gracefully. VEX-suppressed findings are hidden by default and appear with --show-suppressed. The reason to prefer VEX for claims that customers or other teams will see is portability: the statement travels with the artifact and is machine-readable, whereas an ignore file lives in one repository and is meaningful only to Trivy.

The most flexible mechanism is a Rego ignore policy, selected with --ignore-policy. It is for rules that cannot be expressed as a list, such as "ignore any finding whose CWE is in this set" or "ignore everything in packages under this path":

package trivy

default ignore = false

ignore {
    input.PkgName == "libxml2"
    input.Severity == "LOW"
}

The input is the finding. Because Rego can express arbitrary logic, it is also the easiest mechanism to misuse: a broad rule is invisible to reviewers who only look at the scan output. Keep a Rego policy small, commented and tested. The Rego syntax accepted can change with the engine bundled in a Trivy release, so re-test policies after every upgrade.

Misconfiguration scanning in depth

The problem: a vulnerable library is one kind of risk, and a Terraform file that opens a storage bucket to the world is another. Trivy's misconfiguration scanner reads infrastructure-as-code and checks it against rules. Since it is the same binary and the same pipeline, you can put it in the same job as the vulnerability scan, but it behaves quite differently and deserves its own mental model.

The rules are called checks. Each one is a policy written in Rego, the policy language from Open Policy Agent, and each has an ID such as AVD-DS-0002 (a Dockerfile check that flags running as root) or AVD-AWS-0107 (an AWS security group rule). The IDs come from the Aqua Vulnerability Database naming, and you will still meet older forms like DS002 and KSV001 in documentation and old ignore files. The checks ship as the checks bundle, an OCI artifact that Trivy downloads alongside the vulnerability DB, with an embedded copy in the binary as a fallback. One consequence is that check results can change between two runs of the same Trivy binary, because the bundle updated. --skip-check-update pins you to what is cached or embedded.

What gets scanned is controlled by --misconfig-scanners, whose default covers Azure ARM, CloudFormation, Dockerfile, Helm, Kubernetes, Terraform, Terraform plan JSON and Terraform plan snapshots. Trivy decides which scanner applies to a file by looking at it, so a Dockerfile or a manifest with apiVersion and kind is recognised. When a file is not recognised, say a Dockerfile.build or a template with an unusual name, you tell Trivy explicitly with --file-patterns:

trivy config ./infra                                          # only the misconfig scanner
trivy fs --scanners vuln,misconfig,secret .                   # alongside the others
trivy config --file-patterns "dockerfile:Dockerfile.build" .  # recognise a custom file name
trivy config --include-non-failures ./infra                   # also show the checks that passed
trivy config --severity HIGH,CRITICAL --exit-code 1 ./infra   # gate on it

Input that needs rendering deserves care. Helm charts are rendered with your values before checking, so a finding can exist under one values.yaml and not another. Pass the values you actually deploy with --helm-values prod-values.yaml or --helm-set, and if the chart uses .Capabilities checks, set --helm-kube-version. Terraform takes variables through --tf-vars terraform.tfvars, and Trivy also evaluates modules, including remote ones it downloads; --exclude-downloaded-modules stops findings inside third-party modules you cannot change from polluting your report. The most accurate input of all is a Terraform plan, because it contains the resolved values: terraform show -json tfplan > plan.json and then trivy config plan.json checks what Terraform is actually about to do, including values that came from variables and data sources that static files cannot know.

terraform plan -out=tfplan && terraform show -json tfplan > plan.json
trivy config --severity HIGH,CRITICAL plan.json
trivy config --helm-values values-prod.yaml ./charts/myapp
trivy config --tf-vars prod.tfvars --exclude-downloaded-modules ./terraform

To understand a failure, read its structure. Each finding names the check ID, the resource and the lines involved, and --render-cause adds a rendering of how the value was computed, which is valuable when a finding comes through a variable or a module. The finding also links to a documentation page describing the rule and how to remediate it. When the rule is correct but your situation is an exception, the inline ignore keeps the exception next to the code it applies to. In Terraform that is a comment directly above the resource:

#trivy:ignore:AVD-AWS-0107
resource "aws_security_group_rule" "office_ssh" {
  type        = "ingress"
  from_port   = 22
  to_port     = 22
  protocol    = "tcp"
  cidr_blocks = ["203.0.113.0/24"]
  security_group_id = aws_security_group.bastion.id
}

If your organisation has rules the built-in bundle does not, such as "every bucket must carry a data-classification tag" or "no workload in a Gulf-region cluster may pull from a registry outside an approved list", you write a custom check in Rego and load it with --config-check. Your checks live in a namespace that you must opt in to with --check-namespaces, and static lookup data goes in with --config-data. The same three settings exist as config-file keys (rego.check, rego.namespaces and rego.data), which is what you will actually use in a shared pipeline. A custom check is also a code artifact: keep it in a repository, test it with sample inputs, and version it like any other library.

trivy config --config-check ./policies --check-namespaces user --config-data ./data ./infra

Secrets and licenses

Two scanners round out a full audit, and both reward a little configuration. The secret scanner looks for credentials committed in files or baked into images. It is on by default, and it works by matching regular expressions, each paired with keywords that make the match cheap to pre-filter. That design explains its behaviour: it finds well-structured tokens such as cloud access keys, GitHub tokens and private key headers with low false positives, and it finds arbitrary passwords in arbitrary formats poorly. It reads compiled Python .pyc files too, which surprises people who assume bytecode is opaque. In an image scan it also examines the image configuration when you ask for it with --image-config-scanners secret, which is where ENV variables and build arguments that leaked into the image history show up.

Configuration lives in trivy-secret.yaml, found in the working directory by default, or supplied with --secret-config. You can add your own rules (an ID, a category, a title, a severity, a regex and keywords), allow-list paths or patterns that hold deliberate fake credentials, and disable built-in rules that do not apply. The file's precise field names are documented on the secret scanner page linked in Sources; check it there, since the schema is richer than the example below.

rules:
  - id: acme-internal-token
    category: Acme
    title: Acme internal API token
    severity: HIGH
    regex: 'acme_[a-f0-9]{32}'
    keywords:
      - acme_
allow-rules:
  - id: test-fixtures
    description: Fake credentials in test data
    path: 'tests/fixtures/.*'

Two practical points. First, every finding is a leaked credential until proven otherwise, and the fix is rotation, not deletion: a secret that reached an image layer or a commit must be treated as public. Second, the secret scanner reads file content, which makes it one of the heavier stages; if a job only needs CVEs, --scanners vuln removes that cost.

The license scanner answers a legal question instead of a security one: which licenses do our dependencies carry, and are any forbidden for our distribution model. It is opt-in: --scanners license. Trivy classifies licenses into categories (forbidden, restricted, reciprocal, notice, permissive, unencumbered, unknown) using lists in its configuration, and you can move a license between categories to fit your own policy. Without --license-full, it reports licenses declared in package metadata; with it, Trivy also scans source files for license headers and LICENSE files, reported under the license-file class, at the price of reading more files. Recent releases improved Java: v0.72 reads licenses from JAR-embedded POMs, v0.73 handles the Jenkins Plugin-License-Name field, and v0.74 resolves license URLs in POMs and OSGi Bundle-License headers to SPDX identifiers.

trivy fs --scanners license .
trivy fs --scanners license --license-full --severity HIGH,CRITICAL .
trivy image --scanners license --ignorefile .trivyignore.yaml myapp:1.4.2

Outputs, SBOMs and scanning what you already stored

The problem: a human reads a table, but a pipeline has other consumers. Code-scanning dashboards want SARIF. Compliance wants a bill of materials. A warehouse wants JSON. You do not want to re-scan for each one. Trivy separates finding from rendering, so the right habit is to scan once, keep the JSON, and convert.

The --format values are table, json, template, sarif, cyclonedx, spdx, spdx-json, github and cosign-vuln. SARIF is the format GitHub code scanning understands. The github format is a dependency snapshot for GitHub's dependency graph. cosign-vuln produces a predicate you can attach to an image as a signed attestation. template renders through Go templates, with several bundled ones such as @contrib/html.tpl and @contrib/junit.tpl, and is how you feed a test-report panel in CI. trivy convert turns a saved JSON result into another format without scanning again, so you can keep one canonical file and emit many views:

trivy image --format json --output result.json myapp:1.4.2
trivy convert --format sarif --output result.sarif result.json
trivy convert --format template --template "@contrib/html.tpl" --output report.html result.json

An SBOM (software bill of materials) is the inventory stage of the pipeline, written to a file: every package, version and relationship, without findings unless you ask for them. The two standard formats are CycloneDX and SPDX. A CycloneDX SBOM contains no vulnerabilities by default; adding --scanners vuln embeds them. The reason to generate SBOMs at build time is the rescan pattern described earlier: the inventory of a released artifact never changes, but the advisory data does, so you store the inventory once and ask "what is vulnerable now" repeatedly.

# At build time: produce and keep the inventory
trivy image --format cyclonedx --output sbom.cdx.json ghcr.io/org/app:1.4.2
trivy fs --format spdx-json --output sbom.spdx.json .

# Nightly: rescan the stored inventory, no image pull required
trivy sbom --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 sbom.cdx.json

Two related features reduce repeated work. --sbom-sources oci,rekor lets Trivy look for an SBOM already attested for an image, either attached to it in the registry or published in the Rekor transparency log, instead of unpacking the image itself. And Trivy auto-detects SBOM files found inside images and VMs (files ending .spdx, .spdx.json, .cdx and .cdx.json), which is how SBOMs embedded by some build tools are honoured. Store SBOMs next to the artifact, keyed by its digest, so the question "what was in release 1.4.2" is always answerable, including after the image has been garbage collected.

Trivy in CI, and protecting the pipeline from Trivy

The problem: a scanner that runs in every pipeline with access to the registry, the source and often the deployment credentials is itself a high-value target. In March 2026 that stopped being theoretical for this very tool, so this section covers the pipeline design first and the defensive practice that the incident made mandatory second.

A CI gate has four design decisions. What to scan is the built artifact, the exact image that will be deployed, not a rebuild of it; scan after build and before push, or after push by digest. What fails the build is a threshold you choose deliberately: a typical starting policy is --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1, with the strict part being that --exit-code defaults to 0, so without it Trivy reports findings and still exits successfully. This is the most common reason "we run Trivy in CI" turns out to gate nothing. What to keep is the JSON or SARIF file as a pipeline artifact, which gives you evidence for audits and a record to diff. What to cache is the Trivy cache directory between runs, which avoids re-downloading the databases every time.

name: image-scan
on:
  pull_request:
  schedule:
    - cron: "0 3 * * *"        # nightly rescan: the DB changes even when the code does not

permissions:
  contents: read
  security-events: write       # only needed to upload SARIF

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<full-commit-sha>
      - name: Build
        run: docker build -t app:${{ github.sha }} .
      - name: Scan (gate)
        uses: aquasecurity/trivy-action@<full-commit-sha>   # pinned by SHA, not by tag or branch
        with:
          scan-type: image
          image-ref: app:${{ github.sha }}
          format: sarif
          output: trivy.sarif
          severity: HIGH,CRITICAL
          ignore-unfixed: true
          exit-code: "1"
      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@<full-commit-sha>
        with:
          sarif_file: trivy.sarif

The action has a cache that is on by default and stores .cache/trivy inside the workspace. Its README at the time of writing recommends version 0.36.0 of the action; whichever version you take, the rule below governs how you refer to it. If you would rather not depend on an action at all, the same job in any CI system is a pinned container image plus a command:

docker run --rm \
  -v "$PWD":/work -w /work \
  -v trivy-cache:/root/.cache \
  aquasec/trivy:0.74.0 \
  image --input app.tar --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1

This example scans a tarball produced by docker save, so the Trivy container needs no access to the Docker socket. That matters: mounting /var/run/docker.sock into a scanner container hands it root-equivalent power over the host, which is a large privilege to give to a tool whose only task is reading files. Tarballs, --image-src remote, or a rootless socket are all safer.

The March 2026 incident and what it teaches. On 19 March 2026 an attacker who had obtained a compromised credential published malicious artifacts under Trivy's own names. The malicious Trivy binary was version 0.69.4, available for about three hours; most tags of aquasecurity/trivy-action before 0.35.0 were altered for roughly twelve hours; and every then-existing release of aquasecurity/setup-trivy was affected for about four hours. Distribution channels including Docker Hub, GHCR, ECR Public, the deb and rpm repositories and get.trivy.dev were involved. The project's guidance is that if an affected version ran in a pipeline, all secrets available to that pipeline should be treated as compromised and rotated. Safe versions are 0.69.3 and earlier, and 0.70 onwards, for the binary; 0.35.0 and later for the action; and 0.2.6 and later for setup-trivy. The project's published advisory (GHSA-69fq-xp46-6x23) and its discussion thread carry the full indicators, and you should read them rather than rely on a summary.

The lessons are general, and they apply to every tool in your pipeline, not only this one:

1. Pin GitHub Actions by full commit SHA. A tag is a movable pointer; a SHA is content. Tags are exactly what the attacker rewrote.
2. Pin the binary or image by exact version, and ideally by digest. aquasec/trivy:0.74.0 is good and aquasec/trivy@sha256:<digest> is better. Never use latest.
3. Do not pipe an installer from a moving branch. If you use the install script, pass an explicit version as its argument, and better still download a release tarball and check its checksum and signature.
4. Mirror what you depend on. Keep the Trivy binary and its databases in an internal registry so a compromised public channel does not reach you on the next run.
5. Limit what a scan job can reach. It needs to read the artifact and write a report. It rarely needs deployment credentials, so give it a separate, low-privilege job, and restrict its network egress.
6. Let a bot update the pins. Renovate or a similar tool can raise pull requests that bump a pinned SHA or digest, so that pinning does not mean freezing.

Two version changes from v0.72 bite pipelines that install Trivy in the obvious ways. The APT repository now publishes new releases only to the generic distribution, so a source line using a codename such as jammy or $(lsb_release -sc) silently stays on v0.71.2 and never upgrades. And container image tags with an architecture suffix, like 0.71.0-amd64, are no longer published; use the plain multi-architecture tag or a digest.

# The apt source line that keeps receiving releases
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main" \
  | sudo tee /etc/apt/sources.list.d/trivy.list

Client/server mode, registries and air-gapped scanning

The problem: fifty pipelines each downloading a few hundred megabytes of database on every run is slow, expensive, and sensitive to rate limits at the registry that hosts the DB. There are three separate remedies, in rising order of effort: a shared cache, a central server, and a private mirror or full offline copy. Pick the smallest one that solves your problem.

Standalone mode is the default: each Trivy process holds its own database and cache. Client/server mode moves the heavy, shared part to one place. You run trivy server, and clients call it with --server:

# On the shared host (put TLS in front of it with a reverse proxy)
trivy server --listen 0.0.0.0:8080 --token "$TRIVY_TOKEN"

# On runners
trivy image --server https://trivy.internal.example.com --token "$TRIVY_TOKEN" myapp:1.4.2
trivy fs --server https://trivy.internal.example.com --token "$TRIVY_TOKEN" .

Understand the split, because it affects what leaves the client. The client unpacks the artifact and does the analysis, and it runs the misconfiguration and secret scanners locally, so your source files and any secrets in them are not sent over the network. The server holds the vulnerability database and performs the vulnerability and license matching against the package inventory the client submits. Always write the full http:// or https:// scheme in the client's --server value. The server exposes /healthz for liveness and /version for version and DB information, which is what a Kubernetes probe or load balancer should use. Authentication is a shared token sent in the Trivy-Token header, with no user management, so the server should sit behind TLS and inside a network you control.

If you run more than one server replica behind a load balancer, the replicas need a shared cache. Without it, a client may upload layer information to one replica and ask a different one to scan, which produces the error layer cache missing. The remedy is a shared backend such as Redis, set with --cache-backend redis://.... Separately, the cache on one machine is protected by a file lock: two Trivy processes using the same cache directory collide with cache may be in use by another process. The remedies are one process per cache directory (--cache-dir), or using server mode, which serialises access for you.

Private registries. Trivy reads the standard Docker configuration (~/.docker/config.json) and credential helpers, so if docker pull works on the runner, trivy image typically works too. For explicit credentials there are the TRIVY_USERNAME, TRIVY_PASSWORD and TRIVY_REGISTRY_TOKEN environment variables and a --password-stdin option, and the cloud registries (ECR, Google Artifact Registry, Azure Container Registry) can be authenticated through the provider's own credentials. Prefer credential helpers and standard input over a password on the command line, where it shows up in process listings and logs. A registry with a self-signed certificate is handled with --insecure for that one host, which should be a last resort; the right fix is to trust the certificate authority.

The TLS-inspection problem. Many employers in the region and beyond route outbound traffic through a proxy that re-signs TLS. Trivy, as a Go program, then fails to download the DB with x509: certificate signed by unknown authority. The correct fix is to give Trivy the corporate CA, with SSL_CERT_FILE=/path/to/corp-ca.pem (one file) or SSL_CERT_DIR=/path/to/certs (a directory). TRIVY_INSECURE=true makes the error disappear and turns off all certificate checking for the run, which is not a fix. Do not set it in a pipeline that holds credentials.

Mirroring and air-gap. If a runner cannot reach ghcr.io or mirror.gcr.io, or you want to stop depending on them, copy the databases into a registry you control and point Trivy at them. This is explicitly supported through --db-repository, --java-db-repository and --checks-bundle-repository:

db:
  repository:
    - registry.example.com/mirror/trivy-db:2
  java-repository:
    - registry.example.com/mirror/trivy-java-db:1
misconfiguration:
  checks-bundle-repository: registry.example.com/mirror/trivy-checks:1

A fully disconnected host needs the data moved by hand. On a connected machine you pull the DB artifacts (the docs use oras) and extract them into the cache layout, then transfer the files. On the isolated host you run Trivy with every update and every outbound lookup switched off:

trivy image --skip-db-update --skip-java-db-update --offline-scan \
  --skip-check-update --skip-version-check --disable-telemetry \
  --input myapp.tar

Note what --offline-scan does and does not do. It stops Trivy making remote lookups such as those to Maven Central; it does not stop the database download, which is why --skip-db-update appears as well. Count the external dependencies when you plan an air-gap: the vulnerability DB, the Java DB, the checks bundle (which has an embedded fallback), VEX Hub, Maven Central lookups and the version and telemetry check. Refresh the mirror on a schedule shorter than your patching SLA, because the DB is rebuilt about every six hours and an air-gapped copy is always stale by the length of your transfer process. Mention that age in every report you produce from it.

Scanning Kubernetes: the CLI and the Operator

The problem: image scans tell you what is in your images, but not what is actually running, nor whether the cluster's own configuration is sound. Kubernetes scanning answers three separate questions, and Trivy offers two tools for them, which you should treat as complements rather than alternatives.

The CLI command trivy k8s takes a snapshot of a live cluster, using the kubeconfig context you select. It examines three layers: the cluster infrastructure (API server, kubelet and add-ons), the cluster configuration (roles, bindings and other resources), and your application workloads, including the images they run. The old trivy k8s cluster and trivy k8s all subcommands are gone; the current form is trivy k8s [flags] [CONTEXT], with --report summary (the default) or --report all.

trivy k8s --report summary
trivy k8s --report all --severity HIGH,CRITICAL --scanners vuln,misconfig,secret
trivy k8s --include-namespaces prod,staging --exclude-kinds node
trivy k8s --skip-images                        # configuration only, no image pulls
trivy k8s --disable-node-collector             # skip the per-node check jobs
trivy k8s my-context --kubeconfig ~/.kube/config2
trivy k8s --compliance=k8s-cis-1.23 --report all

Start with --skip-images on a large cluster: scanning every workload image means pulling each one, which is the expensive part. The node collector is the component that inspects nodes, and it runs as jobs in a temporary namespace, so the identity you scan with needs rights beyond read-only listing: to create jobs, read pod logs, use the node proxy and manage that temporary namespace. Give the scan a dedicated service account and review those rights rather than using cluster-admin out of convenience. In managed services where you cannot reach node internals, disable the collector instead of granting more. The client-side rate settings kubernetes.qps and kubernetes.burst (defaults 5 and 10) limit how hard Trivy hits the API server.

Compliance reports use built-in specifications: k8s-nsa-1.0, k8s-cis-1.23, rke2-cis-1.24, eks-cis-1.4, k8s-pss-baseline-0.1 and k8s-pss-restricted-0.1. The CIS ones are useful in audits and the Pod Security Standards ones tell you how close a namespace is to enforcing baseline or restricted, which is a practical migration guide. Another output, the KBOM (Kubernetes bill of materials), is a CycloneDX inventory of the cluster's components, and it can be scanned like any SBOM:

trivy k8s --format cyclonedx --output mykbom.cdx.json
trivy sbom mykbom.cdx.json

The Trivy Operator is the always-on counterpart. Installed with Helm into its own namespace, it watches the cluster and, when workloads appear or change, launches scan jobs and stores the results as Kubernetes custom resources next to the workloads they describe:

helm install trivy-operator oci://ghcr.io/aquasecurity/helm-charts/trivy-operator \
  --namespace trivy-system --create-namespace
kubectl get vulnerabilityreports -A -o wide
kubectl get configauditreports -A
kubectl get exposedsecretreports -A

Reports are namespaced resources (vulnerability, configuration audit, exposed secret, RBAC assessment, infrastructure assessment, compliance and SBOM reports, with VulnerabilityReport and ConfigAuditReport being the ones you meet first), which means ordinary Kubernetes RBAC controls who may read them, and other tools can consume them: a Grafana dashboard through the Operator's Prometheus metrics, or an admission policy engine that reads reports to block workloads. The Operator's version numbers are decoupled from Trivy's, and its Helm chart is versioned separately from the application, so when you pin, pin the chart version and check both numbers in its release notes. The costs to plan for are real: each report is an object in etcd, so on a cluster with thousands of workloads you should watch API server and etcd load, limit scanning to the namespaces that matter, and set concurrency and timeouts in its configuration. A sensible division of labour is the Operator for continuous visibility, the trivy k8s CLI for ad hoc compliance snapshots and KBOMs, and the CI gate for preventing new problems from reaching the cluster at all.

Configuration management with trivy.yaml

The problem: by the time a team has a gate, a scheduled audit, a mirror and an ignore policy, the command line has forty flags and three pipelines have three slightly different copies of it. Drift between them is how "it passes in CI but fails locally" starts. Trivy lets every flag live in a configuration file, and the discipline is to keep the policy in the file and leave only the job-specific parts on the command line.

Every flag has three spellings. The flag --ignore-unfixed has the environment variable TRIVY_IGNORE_UNFIXED and a key in trivy.yaml (under vulnerability). The file is read from trivy.yaml in the working directory by default, or from the path given with --config (-c). When the same setting appears in several places the order is: command-line flag first, then environment variable, then configuration file, then the built-in default. Keys are grouped by area (scan, vulnerability, db, cache, misconfiguration, license, rego, registry, server and so on), and since v0.69 a JSON Schema for the file is published, so an editor can validate it and autocomplete the keys. To start from the complete, current set, let Trivy write it for you with --generate-default-config, then delete everything you do not change.

# Team policy: lives in the repository, reviewed like code
severity:
  - HIGH
  - CRITICAL
scan:
  scanners: [vuln, secret, misconfig]
  skip-dirs: [node_modules, vendor, .git]
vulnerability:
  ignore-unfixed: true
  ignore-status: [will_not_fix, end_of_life]
  vex: [repo]
ignorefile: .trivyignore.yaml
exit-code: 1
db:
  repository:
    - registry.example.com/mirror/trivy-db:2
  java-repository:
    - registry.example.com/mirror/trivy-java-db:1

The pattern that works in practice is a layered one. A trivy.yaml in each repository carries the team policy: severity, ignore file, skipped directories. The pipeline supplies job-specific values through environment variables: TRIVY_CACHE_DIR for where the cache lives, TRIVY_TIMEOUT for the big monorepo job, and registry credentials from the CI secret store. A central platform team can publish a base configuration, and each repository can extend its decisions by flags. Because the file is code, changes to the gate's strictness appear in pull requests, with an author and a reviewer, instead of disappearing into a pipeline UI.

Watch for a few specifics. The default --scanners is vuln,secret, so a configuration that lists misconfig is changing behaviour, not restating it. The key scan.disable-telemetry and scan.skip-version-check are the settings to add in locked-down environments, to avoid calls to the telemetry and version-check endpoints. Newer releases add keys (v0.73 brought Maven repository mirrors into the file), and a key that your installed version does not know about is a reason to consult the schema for that release rather than copy an example from a blog post.

Debugging beyond the basics

The problem: Trivy fails in a small number of recurring ways, and each has an exact message. Learning to recognise them turns a half-hour of guessing into a two-minute fix. The habit underneath all of them is the same: reproduce with --debug, read what was actually done, and change one thing.

--debug (or -d) prints the decisions Trivy makes: which image source succeeded, which DB repository it tried, which analyzers ran and which files they claimed, and where time went. For failures that look like network problems, --trace-http shows the HTTP traffic, with one warning that matters: it can print tokens and other sensitive values, so never paste its output into a ticket without reading it first.

A few deserve a longer explanation. The DENIED error is surprising because it happens during an anonymous pull: the registry rejects an expired credential instead of ignoring it, so the fix is to remove the credential. The failed analysis of a JAR such as usr/lib/jvm/.../tools.jar points to the Java DB not being available in time, and running trivy image --download-java-db-only first, as a separate step, removes the race. And odd behaviour that no flag explains, after an upgrade or an interrupted download, is often a corrupted cache: trivy clean --all removes it, at the cost of a fresh download.

The tricky class of problem is the scan that succeeds and is wrong. There are four causes worth checking. First, the package was not in the inventory, so look for vendored or manually installed software. Second, the scanner was not enabled, which you see in the list of scanners in the debug output. Third, a filter removed the finding: --ignore-unfixed, --ignore-status, a severity threshold, a VEX document or an ignore file. Fourth, the data differs from what you expected, because the DB version is older than the advisory. Work through them in that order, and use --show-suppressed early, because it converts the third cause from a guess into a list.

Upgrades, pinning and keeping the tool current

The problem: Trivy is a 0.x project. It has no 1.0, releases arrive every few weeks, and minor releases may carry breaking changes. The two bad responses are never upgrading, which leaves you on a release without fixes, and always taking the newest, which leaves your gate's behaviour at the mercy of someone else's release schedule. The good response is to pin exactly and upgrade on purpose.

Every upgrade should start with the release highlights for each minor version you are skipping. For the versions covered in this guide: v0.72 changed where APT packages are published and dropped architecture-specific image tags; v0.73 added VEX discovery through OCI referrers and Maven mirror settings; v0.74 improved Java license resolution and added matching for RapidFort images. None of these was a change to the core gate flags, but the APT and tag changes broke installs that looked correct. Earlier, v0.67 made --list-all-pkgs default to true, which made JSON output bigger, and the old --security-checks, --skip-update and --light flags had been removed in favour of --scanners, --skip-db-update and nothing. If you inherit a pipeline that uses a removed flag, the fix is the current name and not a version pin to an old release.

A safe upgrade sequence is short. Bump the pinned version in one pull request. Run the new version against a few representative images and repositories beside the old one, and diff the JSON. Expect differences caused by the data, which move independently of the binary, and investigate only differences that are caused by the binary: new findings in a package type, different severities, a changed exit behaviour. If the DB or checks bundle complains after the change, trivy clean --all resolves most cases. Keep the old pinned version available until the new one has run for a week.

Automate the boring part. A dependency bot can open pull requests that bump the Trivy image digest, the action SHA and the Operator chart, each with release notes attached, so the human effort goes into reading a diff and not into finding that a release exists. Given what happened in March 2026, you should also decide in advance who can approve a bump, and require that the new SHA or digest comes from the official project rather than a fork or a look-alike name.

Putting it all together

Here is the whole mid-level practice on one fictional service, orders-api, a containerised service with Terraform and a Helm chart, deployed on a Kubernetes cluster in a Gulf region, where the employer's policy requires that vulnerability data and reports stay inside a private network.

1. Commit the policy.A trivy.yaml sets severities, scanners, skipped directories and the ignore file, and a .trivyignore.yaml holds decisions with statements and expiry dates. Both are code-reviewed.
2. Pin the tool.The pipeline runs aquasec/trivy:0.74.0 by digest, from an internal mirror, in a job with no deployment secrets. A bot proposes updates.
3. Mirror the data.The DB, Java DB and checks bundle are copied into the internal registry on a schedule, and trivy.yaml points at them. Runners no longer depend on public registries.
4. Gate the pull request.The job builds the image, runs trivy image --exit-code 1 for HIGH and CRITICAL findings with fixes, and runs trivy config on the Terraform plan and the Helm chart rendered with production values.
5. Record the inventory.The release job writes a CycloneDX SBOM next to the image digest and stores it as an artifact.
6. Rescan every night.A scheduled job runs trivy sbom against every stored SBOM and opens a ticket for new HIGH or CRITICAL findings, so problems disclosed after release are found within a day.
7. Watch the cluster.The Trivy Operator runs in trivy-system for continuous reports, and a monthly trivy k8s --compliance=k8s-pss-restricted-0.1 --report all drives the work of tightening namespaces.

# The same gate on GitLab CI, with the cache and pinned image
trivy-gate:
  image:
    name: registry.example.com/mirror/aquasec/trivy:0.74.0
    entrypoint: [""]
  variables:
    TRIVY_CACHE_DIR: .trivycache
    TRIVY_NO_PROGRESS: "true"
  cache:
    paths: [.trivycache/]
  script:
    - trivy image --input app.tar --format json --output trivy-report.json --exit-code 1
    - trivy sbom --exit-code 0 sbom.cdx.json
  artifacts:
    when: always
    paths: [trivy-report.json]

Each piece connects to a neighbour in this catalogue. The Terraform checks belong next to your Terraform workflow, the Kubernetes and Operator parts to Kubernetes and Helm, the Helm-rendering step to the chart you already keep, and pipeline wiring to GitHub Actions or GitLab CI. The images you scan come from Docker, and the dashboards for Operator metrics from Prometheus and Grafana. Keep the secrets that the pipeline needs in Vault, not in CI variables that every job can read.

Where you are now

You understand that Trivy is a pipeline from artifact to inventory to findings to report, and that every surprising result can be traced to one of its stages. You can explain why an unchanged image fails a week later, read status and severity as separate signals, and choose filters as explicit policy. You can suppress findings with scope, reasons and expiry, use VEX for claims that should travel with an artifact, and scan infrastructure code in the form it will actually be deployed. You can design a CI gate that really fails, cache and mirror the data it needs, run a shared server, scan a cluster, and keep the whole setup pinned and updated so the scanner does not become the weak link.

The third part of the series takes the next step up: Trivy as a platform for other teams, with its architecture and failure modes, scaling limits, multi-tenancy, governance, incident playbooks and the point where another tool is the better answer.

Sources

• Trivy documentation
• Installation
• trivy image reference
• Configuration file reference
• Troubleshooting
• Client/server mode
• Standalone mode
• Kubernetes scanning
• Filtering
• Air-gapped environments
• Misconfiguration scanning
• Secret scanning
• SBOM
• VEX
• Plugins
• Trivy releases
• Trivy changelog
• v0.72.0 highlights
• v0.73.0 highlights
• v0.74.0 highlights
• Security incident of 2026-03-19
• trivy-action
• Trivy Operator documentation
• Trivy Operator releases

Part two of three. A review of Beginner and Mid-level Trivy material, organised around the questions an interviewer asks someone who already runs the tool at work, in about thirty-five minutes. The fast review comes first, then scenarios, trade-offs, and what separates a strong answer from a weak one. The interviews are written for Trivy v0.74.0; where a flag may differ in your version, say so and name trivy <command> --help as your source. That is itself a strong answer.

Where this picks up

Foundations, in one screen

Trivy is an open-source scanner from Aqua Security, a single Go binary, that finds known vulnerabilities, misconfigurations, secrets and license issues in images, filesystems, repositories, Kubernetes clusters and SBOMs. It builds an inventory of what it can identify, then matches that inventory against downloaded data, so it reports what is known about what it recognised.

Say this early: it does not execute anything, it does not find unknown vulnerabilities, and it does not see vendored code or software installed without package metadata. Interviewers listen for whether you understand the limits of your own tool.

Default scanners are vuln and secret. Misconfiguration and license scanning are opt-in, and trivy config runs only misconfiguration. The default exit code is 0 whatever it finds; you must ask for --exit-code 1 to gate anything.

The data is separate from the binary. The vulnerability DB is rebuilt about every six hours and is an OCI artifact with a schema version. The Java DB, the checks bundle and VEX data are separate downloads. A result is always "this binary plus this data at this moment".

Commands and flags to have ready

trivy image --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 myapp:1.4.2
trivy image --scanners vuln myapp:1.4.2                       # CVEs only, faster
trivy image --input app.tar                                   # from a tarball, no daemon
trivy image --image-src remote ghcr.io/org/app:1.4.2          # registry only
trivy fs --scanners vuln,secret,misconfig --skip-dirs node_modules .
trivy config --severity HIGH,CRITICAL plan.json               # a rendered Terraform plan
trivy image --format cyclonedx --output sbom.cdx.json myapp:1.4.2
trivy sbom --exit-code 1 sbom.cdx.json                        # rescan a stored inventory
trivy convert --format sarif --output r.sarif result.json
trivy k8s --report summary --skip-images
trivy clean --all                                             # reset caches when state looks corrupt

Scenario questions

"The pipeline is slow. What do you check first?"

A strong answer starts by measuring instead of guessing: run one scan with --debug and read the timestamps to see which stage dominates. Then it walks the usual suspects in order of how often they are the cause. An empty cache means the DB (hundreds of megabytes) is downloaded on every run: cache the Trivy cache directory between jobs, or use a shared server, or a mirror inside the network. A source scan walking node_modules, vendor or .git should skip them and scan the lock file. Secret scanning reads file content, so a CVE-only job should use --scanners vuln. A Java-heavy image pulls the Java DB, so prewarm it with --download-java-db-only. Only after those does it touch --parallel and --timeout, and it says why: raising the timeout hides a slow scan without fixing it.

A weak answer says "increase the timeout" or "use a bigger runner" first, and never looks at what the scan is doing.

"An image passed yesterday and fails today with no code change. Explain."

The code did not change, the knowledge did. The DB is rebuilt about every six hours, so a vulnerability disclosed overnight, or a severity or status updated by a distribution, appears in a fresh DB. A strong answer proves it instead of asserting it: compare trivy --version from the two runs (DB build dates), confirm the image digest is identical, and read the new finding's published date. Then it answers the process question: a build-time gate cannot catch this, so you need a scheduled rescan, cheaply done by storing an SBOM at release and running trivy sbom nightly. It also notes that the checks bundle can change misconfiguration results the same way.

A weak answer blames "flaky scanning" or re-runs until it passes.

"We have 600 findings and the team is ignoring the report."

The answer is to change the shape of the problem. Group by package and by layer, because 600 CVEs are typically dozens of packages and one base image, and upgrading the base image is one change. Gate on what is actionable: --severity HIGH,CRITICAL --ignore-unfixed, perhaps with --ignore-status will_not_fix,end_of_life. Keep a separate weekly report without --ignore-unfixed so unpatched critical issues are visible to a person. Then reduce the source of the noise: a slimmer or distroless base, a multi-stage build so build tools never ship. Introduce ownership for the remainder: every accepted finding gets a scoped, expiring entry in .trivyignore.yaml. Strong answers treat noise as a process problem and use the tool's filters as explicit policy.

"A scan reports nothing for a service we know has an old library. Why?"

Four causes, checked in order. The library was not in the inventory: it is vendored, copied in, or installed without package metadata, or the project has no lock file so exact versions are unknown. The relevant scanner was not enabled, which is visible in the debug output. A filter removed it: --ignore-unfixed, a status filter, a severity threshold, a VEX document or an ignore file, and --show-suppressed lists what is hidden. Or the data is stale: the DB is old, or an air-gapped mirror was not refreshed. Naming all four and the order you check them is what interviewers want to hear.

"Security wants you to ignore a CVE in a library we cannot upgrade."

The answer is a governed exception, not a switch. Write a YAML ignore entry scoped by path or package URL, with a statement explaining the decision and who owns it, and an expired_at date so it resurfaces. Submit it as a pull request reviewed by security. If the reason is that the vulnerable code is not reachable, consider a VEX statement with status not_affected and a justification, because it travels with the artifact and can be shown to customers and other teams. Mention --show-suppressed as the audit tool: it lists what is being ignored so the list can be reviewed. Weak answers add the ID to .trivyignore globally with no comment and no date.

"Our Trivy job started failing with a certificate error on the DB download."

x509: certificate signed by unknown authority almost always means a TLS-inspecting proxy or a private CA that the Go runtime inside Trivy does not trust. The fix is to give Trivy the corporate CA through SSL_CERT_FILE or SSL_CERT_DIR. Say clearly why TRIVY_INSECURE=true is wrong: it disables verification for the whole run, in a job that usually holds registry credentials. Then mention the broader fix, which is mirroring the DB into an internal registry with --db-repository so runners do not cross the inspecting proxy for it at all. If the error is DENIED from ghcr.io instead, say you would suspect stale GitHub credentials sent on an anonymous pull, and remove them with docker logout ghcr.io or by unsetting GITHUB_TOKEN.

"A new release of Trivy broke our pipeline. How do you prevent a repeat?"

Trivy is a 0.x project, so minor releases may break things. The answer is pinning and controlled upgrades: exact version or digest in every place, updates through a bot-created pull request, and a side-by-side run of old and new on representative targets with the JSON diffed. Give a real example: from v0.72 the APT repository publishes only to the generic distribution, so sources using a distribution codename silently stay on v0.71.2, and architecture-suffixed image tags like 0.71.0-amd64 are no longer published. These are the kind of changes release highlights announce and "latest" hides.

"What would you do if you found Trivy v0.69.4 had run in your pipelines?"

This refers to the March 2026 supply-chain incident. The malicious v0.69.4 binary was available for a few hours on 19 March, and most trivy-action tags before 0.35.0 and all then-existing setup-trivy releases were also affected. The official guidance is to treat every secret the pipeline could reach as compromised and rotate it, and to move to the safe releases (0.69.3 and earlier, or 0.70 onwards; action 0.35.0 or later; setup-trivy 0.2.6 or later). A strong answer adds the structural fix: pin actions by commit SHA and binaries by version or digest, mirror internally, limit what the scan job can reach, and block the indicators in the published advisory at the egress layer.

Trade-off questions

"Gate on every pull request, or scan on a schedule?"

Both, because they answer different questions. A pull-request gate prevents new problems from merging and needs to be fast and actionable: HIGH and CRITICAL, fixed-only, scoped scanners. A scheduled job answers "is what we already run still acceptable", and it is where unfixed findings, new disclosures and license checks belong. Running only the gate misses everything disclosed after merge. Running only the schedule lets new problems in and finds them a day late. The scheduled job is cheap if it rescans stored SBOMs.

"--ignore-unfixed: helpful filter or dangerous shortcut?"

It is both, and a strong answer says which one depends on where you use it. In a gate it keeps the failure list to things a developer can change, which is what makes a gate survivable. But it makes unpatched critical vulnerabilities invisible in that output, and a long-lived unfixed finding never reaches a human. So you use it on the gate and leave it off in a scheduled report that someone reads, and you track affected findings with no fix as a risk register rather than a failing build.

"Client/server mode versus a shared cache versus a mirror?"

Start from the problem. If the pain is repeated DB downloads on runners that persist, a cache directory between jobs is enough and needs no new service. If runners are ephemeral and numerous, or registry rate limits hurt, a mirror of the DB in your own registry, selected with --db-repository, removes the external dependency with little operational overhead. Server mode centralises the DB and the cache and serialises access to it, which also avoids the BoltDB lock problem, at the cost of running, securing (TLS in front, token auth) and scaling a service, and needing Redis if you run more than one replica. The server does vulnerability and license matching, while secret and misconfiguration scanning stay on the client, so sensitive files do not travel. Pick the lightest option that solves your actual bottleneck.

"Trivy Operator or scanning in CI?"

They cover different failure modes. CI scans artifacts before they are deployed, and the Operator scans what is running, which catches images deployed outside the pipeline, drift, and vulnerabilities disclosed later. The Operator also assesses configuration, RBAC and infrastructure, and exposes results as Kubernetes resources and Prometheus metrics. Its costs are the scan jobs it launches and the report objects stored in etcd, which matter on big clusters. A mature setup uses both, plus trivy k8s for compliance snapshots.

"Ignore file, VEX, or Rego policy?"

An ignore file is the simplest and is meaningful only to Trivy in that repository, so it suits local, scoped, time-boxed exceptions. VEX is a standard, machine-readable statement about exploitability that travels with the artifact and suits claims other parties will rely on, such as "not affected". A Rego ignore policy suits rules that cannot be listed, such as ignoring a class of weakness, but its logic is hidden from anyone reading only the scan output, so keep it small and tested. Strong answers choose per situation and mention review.

"Scan the image or the SBOM?"

Scan the image at build time, because that is the moment to catch what is in it, including secrets and image configuration. Rescan the SBOM afterwards, because the inventory of a released artifact never changes and the advisories do; it is faster, needs no registry pull, and keeps working after the image is garbage collected. The SBOM must be stored by digest. Its limits: it does not include secrets and it is only as complete as the inventory that produced it.

What a strong answer covers that a weak one misses

• The data's age. Strong answers always mention the DB version and date when discussing a result. Weak ones talk about "the image" as if the verdict were a property of the image alone.
• The scope of "clean". Strong answers say what the inventory cannot see. Weak ones say "we scan everything".
• Exit codes. Strong answers know --exit-code defaults to zero and that a gate must be tested with a known-bad image.
• Expiry on exceptions. Strong answers attach an owner, a reason and a date. Weak ones add an ID and move on.
• Pinning. Strong answers pin the tool by digest or SHA and can cite the March 2026 incident. Weak ones use latest.
• Rendered inputs. Strong answers scan Helm with production values and Terraform plans. Weak ones scan templates with defaults.
• Trade-off language. Strong answers name what a choice costs. Weak ones present one option as obviously right.
• Escalation. Strong answers know when to send a problem elsewhere: secrets in history to a history scanner, runtime threats to a runtime tool, admission control to a policy engine.

Common interview questions

What is the difference between trivy image and trivy fs? image analyses a built container artifact, including OS packages from the package database and language packages found in the layers. fs analyses a directory, mainly language lock files and IaC, and is what you run on source before building. Running both is normal, because they see different things.

What does --ignore-unfixed do, and what does it risk? It hides findings with no available fix, which makes gates actionable and hides unpatched issues. Use it on gates and keep a separate report without it.

What is VEX? The Vulnerability Exploitability eXchange: a statement that a product is not_affected, affected, fixed or under_investigation for a vulnerability. Trivy can consume it from a repository, a local file, an OCI attestation or an SBOM reference, and hide the matching findings unless --show-suppressed is set.

How do you scan a private registry image? Through the Docker configuration and credential helpers, or TRIVY_USERNAME and TRIVY_PASSWORD, or cloud provider credentials for the big three registries. Prefer helpers and standard input over a password on the command line.

How do you run Trivy where there is no internet? Mirror or copy the vulnerability DB, Java DB and checks bundle, run with --skip-db-update, --skip-java-db-update, --skip-check-update and --offline-scan, and scan tarballs. Explain that --offline-scan does not stop the DB download by itself, and that the mirror's age must be stated in reports.

Why scan a Terraform plan and not only the .tf files? The plan has the resolved values, including variables and data sources, so the checks see what will actually be applied.

What is the Java DB for? It maps JAR checksums to Maven coordinates, so Trivy can identify JARs lacking POM metadata. It is only downloaded when JARs are found.

How do you keep scan results consistent between developers and CI? The same pinned version and a committed trivy.yaml, with the same DB source. Differences that remain are DB dates.

What does Trivy not do? It does not find unknown (zero-day) flaws, see vendored code, scan git history, watch runtime behaviour or enforce admission. It pairs with other tools for those.

How would you roll out Trivy to twenty teams? Start in report-only mode to learn the baseline, then gate on CRITICAL, fixed-only, then widen. Publish one shared base trivy.yaml and pipeline template, require statements and expiry on ignores, run a central mirror, and review the ignore lists regularly.

Sixty-second self-test

Answer aloud without looking.

1. Name the five stages of a scan and what each decides.
2. Why can the same image pass on Monday and fail on Wednesday, and how do you prove it?
3. Which scanners run by default, and what is the default exit code?
4. What does --ignore-unfixed hide, and where would you deliberately not use it?
5. What is wrong with a .trivyignore entry that has no date or comment?
6. Give three things Trivy cannot see.
7. How do you fix x509: certificate signed by unknown authority, and why is TRIVY_INSECURE not the fix?
8. What is the difference between --skip-db-update and --offline-scan?
9. Which Trivy references should be pinned, and to what?
10. How do you rescan a released artifact without pulling the image again?

Senior interviews go further: architecture and failure modes of client/server deployments, which component breaks first at scale, multi-tenancy, governance of exceptions across an organisation, incident playbooks, and arguing the cost and risk trade-offs of a scanning programme to leadership.

Part two of three. Beginner tips covered first-contact mistakes. This file covers what goes wrong once Trivy is part of a real pipeline, the habits that pay back most, practice cards you can work through in an afternoon, and recipes to keep in a runbook. Everything here is written for Trivy v0.74.0.

Where this picks up

Errors at this level

Each entry gives the symptom, the cause and the fix. The causes are rarely about Trivy being broken. Mostly they are about what the tool was told or what it was allowed to see.

The gate is green but the image has critical findings

Symptom. A pipeline that "runs Trivy" passes while a manual scan shows CRITICAL rows. Cause. --exit-code defaults to 0. Findings are reported and the exit status is still success. A second common cause is a filter stack such as --ignore-unfixed plus a long ignore file that hides everything. Fix. Add --exit-code 1 with an explicit --severity, then test the gate once against an image you know is bad, such as an old python:3.8. Run the same scan with --show-suppressed to see what the ignore file hides.

Yesterday's passing build fails today

Symptom. Same commit, same image digest, new failure. Cause. The vulnerability DB is rebuilt about every six hours, and the checks bundle updates too. New advisories or re-rated severities appear without any change to your code. Fix. Do not "fix the flake". Compare trivy --version from both runs, which shows DB build dates, then read the new finding. Decide whether to patch, suppress with an expiry, or accept. Add the DB date to your job log so the answer is on the screen next time.

x509: certificate signed by unknown authority

Symptom. The DB download or a registry pull fails on a corporate laptop or runner. Cause. A TLS-inspecting proxy re-signs traffic with a corporate CA that Trivy's Go runtime does not trust. Fix. Point Trivy at the CA: SSL_CERT_FILE=/etc/ssl/corp-ca.pem for one file, or SSL_CERT_DIR=/etc/ssl/corp-certs for a directory. TRIVY_INSECURE=true silences the error by disabling verification for the run, so keep it out of any job that holds credentials.

cache may be in use by another process

Symptom. Parallel jobs on one runner fail intermittently with a lock message. Cause. The vulnerability DB is a BoltDB file that one process locks. Two scans sharing a cache directory collide. Fix. Give each process its own --cache-dir (or TRIVY_CACHE_DIR), serialise them, or move to server mode so access to the DB is centralised.

context deadline exceeded

Symptom. analyze error: timeout: context deadline exceeded on a large image or monorepo. Cause. The scan hit the five-minute default. The reason is almost always work Trivy should not be doing: a cold cache, node_modules walked file by file, secret scanning over large trees, or hundreds of JARs. Fix. Run once with --debug to see which stage is slow, skip what is irrelevant (--skip-dirs, --skip-files, --scanners vuln), warm the caches, and raise --timeout last.

The apt install never gets past 0.71.2

Symptom. apt-get upgrade reports nothing new months after new releases. Cause. From v0.72 the repository publishes only to the generic distribution. A source line naming jammy, noble or $(lsb_release -sc) keeps reading the old one. Fix. Rewrite the line to deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main, run apt-get update, and confirm with trivy --version. Better still, pin the exact version in your image or runner build.

A pull of aquasec/trivy:X.Y.Z-amd64 fails

Symptom. A Dockerfile or pipeline that worked on v0.71 cannot pull its Trivy image. Cause. Architecture-suffixed tags are no longer published from v0.72. Fix. Use the plain multi-architecture tag, for example aquasec/trivy:0.74.0, or pin a digest.

No findings on a Terraform or Helm directory that obviously has problems

Symptom. trivy fs . prints nothing for infrastructure code. Cause. The misconfiguration scanner is not on by default for fs, or the file name was not recognised, or the chart was rendered with default values that happen to pass. Fix. Use trivy config ./infra or --scanners misconfig; give unusual names with --file-patterns "dockerfile:Dockerfile.build"; pass production values with --helm-values; scan a rendered Terraform plan.

A finding keeps reappearing after you "ignored" it

Symptom. You added an ID to an ignore file and the finding is back. Cause. Usually one of: the expired_at or exp: date passed; the ignore file is not the one Trivy reads (the default is .trivyignore in the working directory, and a YAML file needs --ignorefile); the paths or purls scope does not match the finding; or the job runs from a different directory. Fix. Run with --debug to see which ignore file loaded, then --show-suppressed to see what is being hidden, and check the path spelling against the finding exactly, because paths inside an image are relative (usr/local/lib/..., no leading slash).

Everything breaks after an interrupted download or an upgrade

Symptom. Odd schema errors, partial DB messages, a scan that worked yesterday. Cause. A corrupted or incompatible cache, such as a DB with an old schema. Fix. trivy clean --all (or --vuln-db to be narrower) and scan again to download fresh data.

The practices that pay off most, in order of leverage

The ordering matters. The first items change whether the programme works at all, and the last ones are polish.

1. Make the gate real and keep it honest. --exit-code 1, an explicit --severity, a documented list of filters, and a test image that proves the gate can fail. Nothing else matters if the gate cannot stop a build.

2. Rescan what you already shipped. Store an SBOM for every release, keyed by image digest, and run trivy sbom nightly. This turns the DB's six-hour refresh from a surprise into a feature, and it is cheap because no image is pulled. It is the highest-leverage habit after the gate itself.

3. Pin the scanner and the pipeline around it. Exact version or digest for the binary and image, full commit SHA for GitHub Actions, explicit version argument for the install script. The March 2026 incident, in which a malicious v0.69.4 binary and altered trivy-action and setup-trivy tags were published, is the concrete reason. Let a bot propose bumps so pinning does not mean neglect.

4. Attach an owner, a reason and an expiry to every exception. Use .trivyignore.yaml with statement, paths or purls, and expired_at. Review --show-suppressed output monthly.

5. Fix the source of noise, not the report. Upgrade or slim the base image, use multi-stage builds, prune dev dependencies. One base-image bump often removes dozens of findings, which beats any amount of suppression.

6. Scan the thing you deploy. Render Helm with production values, scan Terraform plans not just .tf files, scan the final image not the intermediate one.

7. Cache and mirror the data. Persist the cache directory between jobs, or run a server, or mirror the DB, Java DB and checks bundle in an internal registry. This is what makes scans fast and keeps them running when ghcr.io has a bad day.

8. Put policy in trivy.yaml and code-review it. Severity, scanners, skipped paths and ignore-file location belong in the repository, and job-specific values go in environment variables.

9. Keep reports as sensitive data. Scan output lists inventories, internal paths and sometimes secret fragments. Restrict who can read CI artifacts and never paste raw JSON into public tickets.

10. Keep the scanner's privileges small. No Docker socket mount if a tarball will do, no deploy credentials in the scan job, a dedicated low-privilege service account for trivy k8s and the Operator.

Practice cards

Each card is a self-contained exercise. Work through them in any order.

Operational recipes

Short, copy-ready procedures for the situations that come up repeatedly.

Recipe: a CI gate with a cache and a test

export TRIVY_CACHE_DIR="${CI_PROJECT_DIR:-$PWD}/.trivycache"
export TRIVY_NO_PROGRESS=true
trivy image --input app.tar \
  --severity HIGH,CRITICAL --ignore-unfixed --ignorefile .trivyignore.yaml \
  --format json --output trivy-report.json --exit-code 1
echo "trivy exit: $?"
trivy --version    # DB date in the log explains tomorrow's surprises

Persist .trivycache between jobs with your CI's cache mechanism. Keep a separate scheduled job without --ignore-unfixed for the human-reviewed report.

Recipe: a nightly SBOM rescan

# At release: store the inventory next to the image digest
trivy image --format cyclonedx --output "sbom-${IMAGE_DIGEST#sha256:}.cdx.json" "$IMAGE@$IMAGE_DIGEST"

# Nightly: scan every stored SBOM with fresh data
for f in sboms/*.cdx.json; do
  trivy sbom --severity HIGH,CRITICAL --ignore-unfixed --format json --output "reports/$(basename "$f").json" "$f" || echo "FINDINGS: $f"
done

Open a ticket per SBOM with new findings, and link it to the release that owns it.

Recipe: audit the ignore list

trivy image --show-suppressed --format json --output all.json myapp:1.4.2
jq '.Results | length' all.json      # how many result blocks the scan produced
grep -nE 'exp:|expired_at' .trivyignore .trivyignore.yaml

Look for entries with no expiry, expiry dates far in the future, and statements that say only "accepted". Field names in the JSON for suppressed findings can differ between releases, so look at the file before scripting against it.

Recipe: a shared server for the team

# server host
trivy server --listen 0.0.0.0:8080 --token "$TRIVY_TOKEN" --cache-backend redis://redis:6379

# probes and checks
curl -fsS http://trivy.internal:8080/healthz
curl -fsS http://trivy.internal:8080/version

# runners
trivy image --server http://trivy.internal:8080 --token "$TRIVY_TOKEN" myapp:1.4.2

Put TLS in front with a reverse proxy, restrict network access, and use Redis when you run more than one replica, otherwise clients will meet layer cache missing. Secret and misconfiguration scanning still run on the client.

Recipe: point Trivy at an internal mirror

db:
  repository:
    - registry.example.com/mirror/trivy-db:2
  java-repository:
    - registry.example.com/mirror/trivy-java-db:1
misconfiguration:
  checks-bundle-repository: registry.example.com/mirror/trivy-checks:1
scan:
  skip-version-check: true
  disable-telemetry: true

Refresh the mirror on a schedule shorter than your patching target, because the source DB is rebuilt about every six hours. Record the mirror's last-sync time in your reports.

Recipe: scan a cluster safely

trivy k8s --skip-images --report summary                      # configuration first, cheap
trivy k8s --include-namespaces prod --report all --severity HIGH,CRITICAL
trivy k8s --compliance=k8s-pss-restricted-0.1 --report all    # Pod Security readiness
trivy k8s --format cyclonedx --output mykbom.cdx.json         # cluster bill of materials

Use a dedicated service account, disable the node collector on managed services where you cannot grant its rights (--disable-node-collector), and keep the reports in a restricted location.

Recipe: recover from a suspected bad Trivy release

1. Find every place Trivy runs: workflow files, Dockerfiles, runner images, laptops.
2. Compare the versions against the project's security advisory for the incident (v0.69.4 was the malicious binary; v0.69.3 and earlier, and v0.70 onwards, are safe).
3. If an affected version ran where secrets were available, rotate those secrets first and investigate second.
4. Move every reference to a pinned safe version, with actions by full commit SHA.
5. Add egress restrictions and an internal mirror so the next incident has a smaller blast radius.

Reading a scan like a reviewer

Most of the value in mid-level practice is in review, not in configuration. When a colleague opens a pull request that touches a scan job, an ignore file or a Dockerfile, there are a handful of questions that catch nearly every problem, and they are worth internalising until they are automatic.

Start with the ignore file, because that is where risk accumulates quietly. For every new entry ask who owns it, why it is acceptable, and when it will be looked at again. An entry with no statement cannot be reviewed, and an entry with no expiry will still be there in three years, protecting a vulnerability that has long since been fixed upstream or, worse, one that has become exploitable. Ask whether the scope is as narrow as it can be: a path or a package URL is almost always available, and a global ID suppresses the same CVE in every other service that inherits the file. Then ask whether the finding is better expressed as a VEX statement, which travels with the artifact and can be shown to a customer, than as a private note inside one repository.

Next read the scan job itself. Is --exit-code set, and does the threshold match what the team believes it is? Is --ignore-unfixed present, and if so, is there a second job where unfixed findings are visible to a human? Are there --skip-dirs entries that are wider than needed, such as skipping an entire src directory because one fixture caused noise? A skip is a blind spot with a reason attached, and the reason should be in a comment. Check which scanners are enabled, because a job that lists only vuln is not scanning for secrets, and a team that thinks it is will learn otherwise at the worst time.

Look at how the tool is installed and referenced. A floating tag, a branch name, an unpinned install script or a latest image are all review failures, and since the March 2026 incident they are not a matter of taste. Check that the scan job holds only the permissions it needs, that it does not mount the Docker socket without a reason, and that its reports are stored somewhere with sensible access control.

Finally, read a result, not just a configuration. Open the JSON from the last run and look at three things: the DB version and date, the number of result blocks and what class each belongs to, and the top few packages by finding count. If the result contains no lang-pkgs blocks for a service you know has dependencies, the lock file is missing or ignored, and the scan is telling you less than you think. If it contains only operating-system findings for an image built on a slim base, that may be perfectly healthy, but it is worth confirming that the application layer was recognised at all. This habit of reading the evidence behind a green tick is what separates a team that uses Trivy from a team that merely runs it.

Habits for the first week of a new service

When a new service is added to the platform, there is a short sequence that gets Trivy working properly from day one, and it is far cheaper than retrofitting later. On day one, commit a trivy.yaml that states the severity threshold and scanners, plus an empty .trivyignore.yaml with a comment describing the required fields. Add the pull-request gate with --exit-code 1 and prove that it fails. On day two, add the release step that writes a CycloneDX SBOM and stores it by digest, and add the service to the nightly rescan list. On day three, scan the Helm chart with production values and the Terraform plan, and record the baseline findings as a report rather than as a wall of ignores. On day four, run the first scan under --debug to record how long each stage takes and set a realistic --timeout. On day five, walk the team through reading a result: status, fixed version, path, and which base-image upgrade would remove the most rows. A service that follows this sequence rarely needs a scramble later, and the team has learned to read the output, which is the skill that scales.

Habits worth adopting now

Write down your filters. One paragraph in the repository README listing the severity threshold, the statuses ignored, and the location of the ignore file. It stops debates and makes reviews faster.

Read release highlights before upgrading. Trivy is pre-1.0, so every minor release deserves five minutes, especially for install and image-tag changes.

Keep one canonical JSON. Scan once, store the JSON, and use trivy convert for SARIF, HTML and other views.

Treat an unknown license or an unmatched file as a question. Findings labelled unknown are work for a person, not noise to suppress.

Note the region. If your employer or regulator requires data residency in the Gulf or Egypt, decide where the mirror, the reports and the SBOM store live, and confirm that no report leaves that boundary.

A checklist before you call the setup done

• The gate uses --exit-code 1 and has been seen to fail on a known-bad image.
• Filters are written down and deliberate.
• Every ignore has a scope, a statement and an expiry.
• Trivy, its image, and any action are pinned by version, digest or SHA.
• A nightly job rescans stored SBOMs.
• Helm and Terraform are scanned with the inputs you deploy.
• Caches persist, or a mirror or server removes the DB download.
• Reports are stored with restricted access.
• The scan job holds no deployment credentials.

Senior tips go further: production traps that only appear at scale, such as ghcr.io rate limits on shared egress and report volume in etcd, platform habits for running Trivy for other teams, governance of exceptions across an organisation, and review checklists for pull requests and design documents.

This is part three of three. The first two levels taught you to run Trivy and to run it well inside a pipeline. This one is about what changes when other people's pipelines depend on your Trivy setup: when a bad configuration blocks forty teams at once, when the scanner itself is part of the attack surface, and when somebody in a security review asks you to prove what your "zero critical findings" number actually means.

A scanner looks like the simplest thing in the toolchain. It is one static Go binary, it reads an artifact, and it prints a table. That simplicity is exactly why platform owners underestimate it. Trivy has four external dependencies (the vulnerability database, the Java database, the checks bundle and optionally the VEX repository), a local cache with a single-writer lock, a client/server mode with no user model, and, since March 2026, a public record of having been compromised twice. None of that is visible on a developer laptop. All of it is visible the day you become the owner.

The version this guide is checked against is Trivy v0.74.0, released on 14 August 2026. Trivy is still a 0.x project, which means a minor release may change flags, defaults or output, and that fact shapes several sections below.

Where this picks up

I am starting with how the pieces fit together, because every failure in the later sections is a failure of one of these pieces.

Architecture and failure modes

Hold one picture of Trivy in your head and most platform decisions follow from it. A scan is a pipeline with four inputs and one output, and each input can fail on its own.

What each failure looks like from the outside

The useful skill is translating a symptom into the input that failed. Most of the incidents a platform owner sees fall into five shapes.

A cold-cache stampede is the most common. A hundred CI jobs start at 09:00, each on a fresh runner with an empty cache, and each downloads the vulnerability database from mirror.gcr.io or ghcr.io. Bandwidth costs are small; the real damage is registry rate limits and, if your runners share one NAT address, the registry seeing all hundred as a single abusive client. The symptom is FATAL failed to download vulnerability DB in a random subset of jobs, which is exactly what makes it hard to diagnose: it is intermittent and it heals itself.

A lock collision happens when two Trivy processes share one cache directory. The database file is BoltDB, which takes a file lock, and the second process fails with a message saying the cache or the vulnerability database may be in use by another process. On a laptop you never see this. On a long-lived CI runner that executes parallel jobs with a shared home directory, you see it weekly.

A silent staleness failure is the worst, because nothing errors. A pipeline passes because the database it used is three weeks old: someone set --skip-db-update to make scans faster and forgot that the cache then never refreshes. You will meet this again in the database section, because the defence is to make staleness a measured thing rather than a thing you hope about.

A partial scan happens when one of the lazily fetched inputs fails and Trivy continues. The classic case is the Java DB: if it is unreachable, JAR analysis emits an error like failed to analyze file: failed to analyze usr/lib/jvm/...tools.jar, and depending on how your wrapper treats errors the pipeline may still go green. A scan that did not look at half the image is worse than a scan that failed.

A scanner-side compromise is the new entry on the list, and it is in its own section below because it changes how you decide what is allowed to run.

Standalone versus client/server, as an architecture choice

In standalone mode everything happens in the process you started: it downloads the database to its own cache, analyses the artifact, matches, and reports. In client/server mode a long-running trivy server holds the database and does the vulnerability and licence matching, while the client analyses the artifact and ships the package inventory. The split matters for security and I will return to it: misconfiguration and secret scanning stay on the client, so your source files and any credentials inside them never travel to the server.

The choice is not "which is better". It is where you want the failure to live. Standalone distributes the database download across every job, so a registry outage or rate limit hits everyone independently and unpredictably. Client/server concentrates it in one service you can monitor, but it makes that service a dependency of every pipeline, and a dependency that is down blocks everyone at once. The right answer depends on how many scans you run and how much a central outage costs, and the scaling section gives numbers to reason with.

The database as a dependency you operate

The junior view is that Trivy "checks CVEs". The platform view is that Trivy downloads a data product from a registry you do not control, and the quality of every result depends on it. You own that dependency the moment other teams rely on your gate.

What is actually downloaded

The vulnerability database is distributed as an OCI artifact, not as a file from a web server. By default Trivy tries mirror.gcr.io/aquasec/trivy-db:2 first and ghcr.io/aquasecurity/trivy-db:2 second; the 2 is the schema version, not a release number. The Java database follows the same pattern with trivy-java-db:1, and the checks bundle comes from mirror.gcr.io/aquasec/trivy-checks:1. All of these are configurable, in trivy.yaml under db.repository, db.java-repository and misconfiguration.checks-bundle-repository, or by the --db-repository, --java-db-repository and --checks-bundle-repository flags.

On disk, inside the cache directory, you get db/trivy.db plus a metadata.json, a java-db/ directory, a policy/ directory holding the checks, a fanal/ directory (the scan cache keyed by layer hash) and a vex/ directory. The default cache location is ~/.cache/trivy on Linux and ~/Library/Caches/trivy on macOS; --cache-dir or TRIVY_CACHE_DIR overrides it. That metadata.json is worth knowing by name, because it carries the build timestamps you will use to measure freshness.

Mirroring internally

There are three reasons to host your own copy, and they stack. The first is rate limits: a few hundred scans an hour from one egress address will eventually be throttled by a public registry. The second is reliability: your gate should not fail because a third-party registry had a bad hour. The third is control: you decide when a new database becomes visible to teams, and you can see exactly which one ran.

The mechanism is ordinary OCI mirroring. You copy the three artifacts into a registry you run, then point Trivy at them.

db:
  repository:
    - registry.example.com/mirror/trivy-db:2
  java-repository:
    - registry.example.com/mirror/trivy-java-db:1
misconfiguration:
  checks-bundle-repository: registry.example.com/mirror/trivy-checks:1
scan:
  skip-version-check: true
  disable-telemetry: true

A mirror job then runs on a schedule shorter than the upstream build interval. The mechanics are plain registry tooling; here is one way with oras, which is what the air-gap documentation itself uses.

#!/usr/bin/env bash
# mirror-trivy-db.sh: run every 3 hours from a host with outbound access.
set -euo pipefail

for ref in trivy-db:2 trivy-java-db:1; do
  oras copy "ghcr.io/aquasecurity/${ref}" "registry.example.com/mirror/${ref}"
done
oras copy ghcr.io/aquasecurity/trivy-checks:1 registry.example.com/mirror/trivy-checks:1

I am deliberately not showing more flags than that. Registry tooling has its own authentication conventions, and oras copy preserves the artifact as-is, which is what you want. What matters for the platform is the schedule and the alert: the job must run more often than the upstream rebuild, and a failed mirror must page someone, because otherwise your freshness silently decays exactly the way --skip-db-update does.

Air-gapped environments

If your scan hosts cannot reach the internet at all, which is common for banks and government workloads in the Gulf, the requirement shifts from "mirror" to "transfer". You download the artifacts on a connected host, move them across your boundary by whatever approved mechanism you have, and seed the cache on the isolated side. The documented shape is:

# Connected host: fetch the artifacts.
oras pull ghcr.io/aquasecurity/trivy-db:2
oras pull ghcr.io/aquasecurity/trivy-java-db:1

# Isolated host: scan with every outbound call switched off.
trivy image --skip-db-update --skip-java-db-update --offline-scan \
  --skip-check-update --skip-version-check --disable-telemetry \
  --input myimg.tar

Each of those flags closes a specific door, and reading the list as a checklist of external dependencies is the useful part. The vulnerability database and the Java database you seeded. The checks bundle falls back to the copy embedded in the binary. Trivy otherwise contacts check.trivy.dev for version checks, VEX Hub for community VEX statements, and Maven Central for some Java metadata. --offline-scan turns off the Maven-style remote lookups; it does not stop the database download, which is a frequent misunderstanding. Only --skip-db-update with a pre-seeded cache does that.

The operational burden in an air gap is freshness. A database you copied in six weeks ago is not "a bit stale", it is missing every vulnerability disclosed since. Write the transfer cadence down, automate what you can, and expose the database age in whatever report the isolated side produces, so a reader can see it.

Making freshness a number

You cannot manage what you cannot see. The database records when it was built in its metadata, and trivy --version prints the DB and Java DB details once they are cached. A cheap, robust pattern is to have your scan wrapper read that timestamp, and to fail the gate or attach a warning when the age passes a threshold, typically 48 to 72 hours for online environments. The alternative is learning about a stale database from an incident review.

#!/usr/bin/env bash
# db-age-check.sh: fail if the cached vulnerability DB is older than 72 hours.
set -euo pipefail
CACHE="${TRIVY_CACHE_DIR:-$HOME/.cache/trivy}"
META="$CACHE/db/metadata.json"

[ -f "$META" ] || { echo "no vulnerability DB in $CACHE" >&2; exit 2; }

# DownloadedAt is an RFC 3339 timestamp written into metadata.json.
downloaded=$(jq -r '.DownloadedAt' "$META")
age_hours=$(( ( $(date -u +%s) - $(date -u -d "$downloaded" +%s) ) / 3600 ))

echo "vulnerability DB age: ${age_hours}h"
[ "$age_hours" -le 72 ] || { echo "DB older than 72h" >&2; exit 3; }

I should flag honestly that the metadata.json field names are what I have seen in practice, not something I re-verified against documentation for this version. Run cat on the file in your own cache and adjust the jq path to match; Version, NextUpdate, UpdatedAt and DownloadedAt are the fields I would expect. The pattern matters more than the key name.

Scaling: which component breaks first

"Does Trivy scale?" is the wrong question, because it has no single answer. The useful version is which component hits its limit first, at what load, and what do you do about it. In roughly the order you will meet them:

The last row is the one that most often really limits you, and the last section of this guide comes back to it.

Per-scan resource behaviour

CPU and memory scale with the size of the image and the number of files in it, not with the number of vulnerabilities. A monorepo checkout with a node_modules tree of a few hundred thousand files behaves very differently from a distroless Go image, even when the second has the same number of findings. The knobs are all in the flag reference:

• --timeout defaults to five minutes. Large images, many JARs and slow registries exceed that. Raise it deliberately (--timeout 15m) for the workloads that need it instead of globally, so a genuinely hung scan still fails in reasonable time.
• --parallel defaults to 5 and sets how many files are analysed concurrently (0 means automatic). On a small runner with a huge tree, lowering it to 1 reduces peak memory and temp-disk pressure; on a large runner it is wasted headroom.
• --skip-dirs and --skip-files remove whole trees from analysis. node_modules in a trivy fs scan of a repo that also has a lock file is the classic example, since the lock file already describes the dependencies. Skipping things also removes findings, so make it a reviewed decision.
• --max-image-size exists so a surprise 40 GB image fails fast rather than consuming the runner.
• --scanners vuln turns off secret scanning, which is on by default and reads a great many files. Scoping scanners per job is the cheapest speed-up available.
• TMPDIR controls where Trivy unpacks layers. The default /tmp is often a small tmpfs on hardened runners; point it at real disk.

The mistake to avoid is tuning for the average scan. Your platform will be judged by the worst image a team ships, and a timeout on the one Java monolith with two thousand JARs is what produces the support ticket.

The server under load

A single trivy server is a modest workload: it loads the database, receives package inventories from clients, matches them, and returns results. The matching is cheap; the thing that hurts is memory for the database and the cache behind it. With one replica the default filesystem cache is fine. The moment you place several replicas behind a load balancer, a client can upload a layer's analysis to replica A and then ask replica B to scan it, and B answers layer cache missing. The fix is a shared cache: --cache-backend redis://... on every replica, so the analysis cache is common.

trivy server \
  --listen 0.0.0.0:8080 \
  --token "$TRIVY_TOKEN" \
  --cache-backend redis://redis.internal:6379

Redis in this role is a cache, not a store of record: losing it means re-analysis, not data loss. That is the right mental model for sizing and for deciding how much availability it needs. Its configuration keys sit under cache in trivy.yaml, including a ttl, and TLS options for the Redis connection; set a time-to-live so the cache does not grow without bound.

The health endpoints are simple and worth wiring into your probes from day one: GET /healthz for liveness and GET /version for version and database information. The second is the useful one, because it lets a monitor check the database age the server is serving, which is the freshness metric from the previous section measured at the place that matters.

Throughput versus latency

Server mode reduces per-job startup cost, since there is no database download and often no cold cache, but it adds a network hop and moves the package inventory across it. For small images the client-side analysis dominates and the gain is in avoiding the DB pull. For very large images the upload can be noticeable. Measure on your own workloads, not on a blog post's.

The trust model, and the March 2026 compromise

A scanner has an unusual position in your pipeline. It runs with read access to everything you build, often with registry credentials, frequently with network egress, and always in a job that teams have been told to trust. That makes it an excellent place for an attacker to sit. In March 2026 that stopped being theoretical for Trivy, and every platform owner should be able to tell the story accurately.

What happened

The following is taken from the project's own incident disclosure (GitHub discussion #10425 and advisory GHSA-69fq-xp46-6x23). An earlier incident on 1 March 2026 had been answered incompletely. On 19 March a threat actor used a compromised credential to publish malicious artifacts:

• The trivy binary v0.69.4 was published and exposed for roughly three hours (about 18:22 to 21:42 UTC on 19 March). Version 0.69.3 and earlier are safe, and so are the later releases, v0.70 onwards.
• The aquasecurity/trivy-action repository had most of its tags before 0.35.0 compromised, for about twelve hours across 19 and 20 March. Safe: 0.35.0 and later.
• The aquasecurity/setup-trivy action had every release that existed at the time compromised, for about four hours. Safe: v0.2.6 and later.
• The affected distribution channels included Docker Hub, GHCR, ECR Public, the deb and rpm repositories, and get.trivy.dev.

The project's guidance for anyone whose pipeline ran an affected version was blunt: treat all secrets available to that pipeline as compromised and rotate them immediately, pin to verified safe releases, and block the command-and-control domain scan[.]aquasecurtiy[.]org (note the deliberate typo-squat spelling) and the IP address 45.148.10.212. That is the published indicator list at the time of writing; always read the current version of the advisory rather than trusting a copy in a course.

The lessons, stated as policy

It is tempting to treat this as "Trivy had a bad month". The more useful reading is that every scanner, linter and build helper in your pipeline is exposed to the same failure, and the incident shows which habits turned a three-hour window into a breach.

The habits that made it worse were the floating references. A workflow that said uses: aquasecurity/trivy-action@master, or pulled aquasec/trivy:latest, or piped the install script from a moving main ref without a version argument, picked up malicious code automatically, with no human decision in between. The habits that contained it were pinning and review.

That gives a pinning policy for any third-party component you run in CI:

1. Pin GitHub Actions by full commit SHA, not by tag. Tags are mutable; the March incident involved existing tags being repointed. A SHA is content-addressed. Keep the human-readable version in a trailing comment so reviewers can tell what it is.
2. Pin the Trivy binary or image by exact version, and preferably by digest. aquasec/trivy:0.74.0 is a version pin; aquasec/trivy@sha256:... is an immutable one.
3. Verify what you download. Release binaries ship with checksums and cosign signatures. Verify them in the step that installs, or, better, verify once and mirror the verified artifact internally.
4. Mirror the binary and the image into a registry you control, and let pipelines pull only from there. Then a compromised public channel cannot reach your runners directly, and you choose when to promote a new version.
5. Automate the bump, do not skip it. Pinning without updating leaves you on a version with its own known vulnerabilities. Let Renovate or an equivalent tool open the pull request with the new SHA or digest, so a human reviews each change.

# Pinned by commit SHA; the comment records what the SHA means.
- name: Scan image
  uses: aquasecurity/trivy-action@<full-40-character-commit-sha>  # 0.36.0
  with:
    scan-type: image
    image-ref: registry.example.com/team/app:${{ github.sha }}
    severity: HIGH,CRITICAL
    ignore-unfixed: true
    exit-code: "1"
    version: v0.74.0

I have left the SHA as a placeholder because the right value is the one you resolve and review on the day; copying a hash from a course would defeat the purpose. The trivy-action README recommends v0.36.0 at the time of writing, and it also exposes version to choose the Trivy binary it installs.

Where a scanner's privileges should stop

Design the scan job as if the tool inside it might one day be hostile. That sounds paranoid until you list what the job typically holds: a registry pull credential, a source checkout, perhaps a token that can write SARIF results to a repository, and sometimes the Docker socket.

The principle is least privilege per job, with the scan isolated from the publish. The job that scans should be able to read the artifact and write a report; it should not hold the credential that pushes to production or deploys. Structure the pipeline so that scanning happens in a job with only read credentials, and so that the gate's verdict is communicated by exit status and an artifact rather than by handing the scanner a write token.

The Docker socket deserves its own warning. Mounting /var/run/docker.sock into a container, which the standard docker run aquasec/trivy example does, gives that container the ability to start privileged containers on the host: it is root-equivalent. In an environment where the scanner's integrity is something you worry about, prefer scanning from a registry with --image-src remote, scanning an exported tarball with --input, or using a rootless socket.

# No daemon access needed: pull the layers straight from the registry.
trivy image --image-src remote registry.example.com/team/app:1.4.2

# Or hand Trivy a tarball produced earlier in the pipeline.
docker save registry.example.com/team/app:1.4.2 -o app.tar
trivy image --input app.tar

Plugins and modules are code you chose to run

trivy plugin install fetches an executable and runs it, with the same privileges as Trivy. The documentation is candid that public plugins are not audited by the project. Treat each plugin as a third-party program and apply your normal review: who maintains it, how is it pinned, what does it do with the report. Modules, which are WebAssembly programs loaded from a module directory, run in a sandbox, but they can still alter what Trivy reports, which for a gate is itself a security-relevant power. On a platform, consider disabling ad-hoc plugin installation in CI entirely and shipping an approved set inside your pinned image.

Secrets, credentials and what the report contains

Two kinds of secret pass through a Trivy platform: the credentials Trivy uses, and the secrets Trivy finds. They need different handling, and most incidents involve forgetting that the second kind exists.

Credentials Trivy uses

Trivy reads registry credentials from the Docker config file (~/.docker/config.json) and its credential helpers, exactly as the docker CLI does. It also accepts the environment variables TRIVY_USERNAME, TRIVY_PASSWORD and TRIVY_REGISTRY_TOKEN, a --password-stdin form, and it can authenticate to the major cloud registries (ECR, Google Artifact Registry, ACR) using the provider's own credential chain. The ordering of preference, for a platform, follows from how leaky each channel is:

• Workload identity or short-lived tokens from the cloud credential chain are best: nothing long-lived exists to steal.
• A credential helper or a Docker config written to a job-scoped location is next.
• --password-stdin avoids putting the password in the process listing.
• --password on the command line is the worst. It shows in ps, in shell history, and in CI logs that echo the command.

Whichever you use, give scan credentials pull-only scope on only the repositories being scanned. A scanner never needs push.

Two error modes are worth memorising because they waste hours. DENIED: denied when pulling the database from ghcr.io usually means stale or expired credentials for GHCR are being sent for what should be an anonymous pull; docker logout ghcr.io or unsetting GITHUB_TOKEN fixes it. The opposite, API rate limit exceeded, means unauthenticated GitHub API calls, cured by supplying a GITHUB_TOKEN. Same registry family, opposite cause.

Debug output leaks

--debug is safe to attach to a ticket. --trace-http is not: the documentation warns that it may print tokens and other sensitive data. Put a rule in your platform runbook that nobody pastes --trace-http output into a chat or an issue, and make the support template ask for --debug output instead.

What Trivy finds: the report as a sensitive artifact

The secret scanner exists to find hard-coded credentials, and when it does, the report contains them (or fragments of them, depending on the output format). A JSON report uploaded as a CI artifact, a SARIF file published to a code-scanning dashboard readable by the whole organisation, a table pasted into a chat: each of those is a disclosure of a secret to a wider audience than the secret was meant for.

Three rules follow. First, the moment a real secret is found, rotate it; the finding itself proves the secret has been in a place it should not have been, and deleting the file does not help if it has already been pushed. Second, restrict who can read scan artifacts to the same audience as the code. Third, in client/server mode, remember the design works in your favour here: secret and misconfiguration scanning run on the client, so a file containing a credential is never sent to the shared server. Do not undo that by pointing a separate secrets pipeline at the server's logs.

Reports also reveal something less dramatic but still useful to an attacker: a precise inventory of every package and version in an image, which tells them which exploits to try. For internal services this is acceptable; for anything whose reports leave your organisation, decide what you are willing to share.

# Keep secret scanning fast and quiet: only the rules you actually need.
enable-builtin-rules:
  - aws-access-key-id
  - aws-secret-access-key
  - github-pat
  - private-key
allow-rules:
  - id: test-fixtures
    description: Dummy credentials in test fixtures
    path: ^tests/fixtures/

The exact rule IDs in the built-in set are listed in the secret-scanning documentation; check the list for the version you run before copying names, since new rules arrive in most minor releases (v0.71 and v0.72 added several, including OpenAI key formats and stateless GitHub App tokens). Enabling only the rules you need is the documented way to speed the scan up, and an allow-rule with a narrow path is far safer than disabling a rule globally.

Client/server as a shared service

If the scaling analysis pushes you toward a central server, you are now operating a service, and a service needs the things a CLI never did: an authentication story, transport security, capacity planning, and an on-call owner.

What the server does and does not provide

Start the server and point a client at it:

trivy server --listen 0.0.0.0:8080 --token "$TRIVY_TOKEN"
trivy image --server https://trivy.internal.example.com --token "$TRIVY_TOKEN" myapp:1.0

The client must include the scheme, http:// or https://; omitting it is a common first-day error. The token is sent in the Trivy-Token header (the header name is configurable through token-header), and custom-headers can add others, which is how you would carry a gateway credential.

Be clear-eyed about what that token is. It is a single static shared secret. There are no users, no per-team credentials, no audit trail of who scanned what, no rate limiting, no revocation other than rotating the secret for everyone. For an internal service behind a network boundary that is often adequate; for anything else, it is the first thing a security reviewer will challenge. The honest posture is:

• Always terminate TLS in front of it. The server itself listens in plain HTTP; put a reverse proxy or service mesh in front and use https:// in clients. A static token over plain HTTP is a token on the wire.
• Do not expose it beyond the network that needs it. An unauthenticated or weakly authenticated scanning endpoint is an oracle that discloses how your packages map to vulnerabilities, and it consumes CPU on demand.
• If you need per-team identity, add it at the gateway. Put an API gateway or an authenticating proxy in front, issue each team its own credential there, and have the gateway inject the single Trivy token upstream. The server stays simple, and you gain revocation and logs where they belong.

What stays on the client

The split of work is deliberate and worth stating to anyone who asks whether the server "sees our code". The server performs vulnerability and licence matching; it receives package inventories (names and versions), not file contents. The client performs misconfiguration and secret scanning locally, so Dockerfiles, Terraform and any strings that look like credentials never leave the job. This is also why the client still needs a checks bundle, and why --skip-check-update or an internal bundle mirror still matters in server mode.

Operating it

A server deployment should have, at minimum:

1. A readiness and liveness probe on /healthz.
2. A freshness check using /version, alerting when the database it serves is older than your threshold.
3. Redis as a shared cache once you run more than one replica.
4. Resource limits sized from measurement: memory is dominated by the loaded database, so watch it during a database refresh, when old and new copies may briefly coexist.
5. A rolling upgrade path: replicas should be replaced one at a time so the pool never drops to zero, and clients should retry on connection errors.
6. An explicit failure policy in the clients: if the server is unreachable, does the job fail (safe, blocks teams) or fall back to standalone (available, slower, rate-limit-exposed)? Pick one per environment and write it in the pipeline template, not in each team's repo.

Trivy Operator at cluster scale

CI scanning answers "is this image acceptable to ship?". It cannot answer "what is running in production right now, given what we have learned since it shipped?". An image that passed in March has a different vulnerability profile in June, and nothing in the pipeline will notice. The Trivy Operator closes that gap by running inside the cluster, watching workloads, and creating scan jobs whose results land as Kubernetes objects.

What it creates

Install it with Helm, from either the Aqua chart repository or the OCI registry:

helm install trivy-operator aqua/trivy-operator \
  --namespace trivy-system --create-namespace

# or, from the OCI registry:
helm install trivy-operator oci://ghcr.io/aquasecurity/helm-charts/trivy-operator \
  --namespace trivy-system --create-namespace

The operator produces one custom resource per kind of finding. The kinds I expect are VulnerabilityReport, ConfigAuditReport, ExposedSecretReport, RbacAssessmentReport, InfraAssessmentReport, ClusterComplianceReport and SbomReport; check kubectl get crd | grep aquasecurity on your cluster to see the exact set for the version you deploy, because I have not re-verified those names against the current chart. Two version numbers will confuse you: the chart version and the operator application version are decoupled from each other, and both are decoupled from the Trivy version. Always quote which one you mean.

These reports are namespaced objects owned by the workload they describe, so they appear next to the pod or deployment, are garbage-collected with it, and are readable with ordinary Kubernetes RBAC. That last property is what makes the operator the natural multi-tenant answer inside a cluster, and I use it in the multi-tenancy section.

What it costs

Every report is an object in etcd, served through the API server. A large cluster with thousands of workloads, each with vulnerability, configuration, secret and SBOM reports, each containing hundreds of findings, can add a substantial amount of data, and vulnerability reports for big images are large. Symptoms of an operator that has outgrown its cluster include rising API server latency, slow kubectl get on the report kinds, and etcd database size alarms.

The levers, in the order I would reach for them:

1. Scope the scanners. Do you need SBOM reports and RBAC assessment and infrastructure assessment on every cluster? Each disabled scanner removes a whole class of object.
2. Scope the namespaces. The operator can be told to target or exclude namespaces, which matters for system namespaces and for clusters shared with workloads you do not own. Consult the operator configuration for the exact option names for your version.
3. Limit concurrency. The operator launches scan jobs as pods; an unbounded concurrent scan limit on a cold cluster starts hundreds of pods at once, all downloading the database. The configuration exposes a concurrent-scan limit and timeouts; set them from measurement.
4. Use ClientServer mode so scan jobs talk to a Trivy server rather than each downloading the database; that is the same stampede defence as in CI.
5. Mind the TTLs. Report retention and scan-job cleanup settings decide how long objects accumulate.

Consuming reports without building a fragile dashboard

The operator exposes Prometheus metrics, which is how you turn a pile of custom resources into something an on-call engineer can see: counts of findings by severity, by namespace and by image. Wire those into Grafana and alert on trend and on new criticals in production namespaces, not on absolute totals, which will never be zero and will teach people to ignore the alert. See the Prometheus and Grafana guides for the monitoring side.

The reports also make excellent inputs to admission and policy tooling. A policy engine such as Kyverno or Gatekeeper can read report objects and refuse to schedule a workload whose image has a fresh critical, which moves the gate from "CI said yes once" to "the cluster says yes now". Do this carefully. A gate that evaluates continuously will one day block a rollout that is fixing a production incident because a database refresh added a new CVE to the very image you are rolling back to. Give incident responders a documented, audited bypass, or your policy will be disabled by the first person it inconveniences.

One-off checks with the CLI

The operator is for continuous state; trivy k8s is for the question you ask once. It scans three layers: cluster infrastructure (API server, kubelet, add-ons), cluster configuration (Roles and ClusterRoles) and application workloads.

# A compliance snapshot against the CIS benchmark, full detail.
trivy k8s --compliance k8s-cis-1.23 --report all

# A workload scan limited to two namespaces, without pulling every image.
trivy k8s --include-namespaces prod,staging --skip-images --report summary

# A Kubernetes bill of materials, then scan it like any other SBOM.
trivy k8s --format cyclonedx --output mykbom.cdx.json
trivy sbom mykbom.cdx.json

It needs permission to list across core, apps, batch, networking and RBAC API groups, and the node collector needs more: it creates jobs, reads pod logs and uses the node proxy, and it runs in a temporary namespace named trivy-temp. A review of "what can the audit identity do" is therefore part of adopting it; do not grant cluster-admin because it was easier. On managed clusters where you cannot run jobs on nodes, --disable-node-collector skips that part, at the cost of the node-level checks.

Multi-tenancy, policy and governance

Trivy has no concept of a tenant. There are no teams, no projects, no per-team policy, and no central database of findings. Everything that looks like multi-tenancy is something you build around it from three ingredients: isolation of execution, policy in version control, and ownership of exceptions.

Isolating execution

The simplest safe model is one job per team and per scan, each with its own cache directory so the BoltDB lock cannot collide and one team's poisoned or oversized scan cannot affect another's. On a shared runner, give every job a unique --cache-dir (a path derived from the job ID) and delete it at the end; on ephemeral runners this happens for free.

If you run shared servers, the honest answer to "per-team isolation" is a separate server per trust domain, not a clever token scheme. The server is cheap, the isolation is easy to reason about, and a noisy team's load does not touch anyone else. Reserve the shared server for teams that have accepted the same trust boundary.

Inside a cluster, the operator's namespaced reports are the isolation primitive: a team with RBAC to read objects in its own namespaces sees its own findings and nobody else's.

Policy in version control

The configuration a platform team wants to control is small and stable: the severities that block, the statuses that are ignored, which scanners run, which directories are skipped, and where the data comes from. The tidy way to deliver it is a shared trivy.yaml in a platform repository, consumed by every pipeline through a template or a reusable workflow, with the team-specific part limited to an ignore file.

# Platform baseline. Teams may add to ignore files, not change this.
severity: [HIGH, CRITICAL]
exit-code: 1
scan:
  scanners: [vuln, secret, misconfig]
  skip-dirs: [node_modules, vendor]
  disable-telemetry: true
  skip-version-check: true
vulnerability:
  ignore-unfixed: true
  vex: [repo]
db:
  repository: [registry.example.com/mirror/trivy-db:2]
  java-repository: [registry.example.com/mirror/trivy-java-db:1]
misconfiguration:
  checks-bundle-repository: registry.example.com/mirror/trivy-checks:1

trivy --generate-default-config writes a complete file with every key, and since v0.69 a JSON Schema is published for trivy.yaml, so you can validate the file in your platform repository's own CI and catch a typo before it reaches forty pipelines. Precedence is worth stating once: a command-line flag beats an environment variable, which beats the config file, which beats the default. That means a team can override your baseline with a flag or a TRIVY_SEVERITY environment variable, which is a governance hole if you care about it. Closing it means running Trivy from a wrapper or reusable workflow that teams cannot alter, not relying on the config file alone.

Ownership of exceptions

Every scanner eventually produces findings a team cannot or will not fix: a base-image vulnerability with no patch, a false positive, a component that is unreachable in practice. The exception mechanism decides whether your programme stays honest.

The plain .trivyignore file lists IDs, one per line, with an optional exp: expiry. It is convenient and it is too weak for a platform: no reason, no owner, no path scoping. The YAML form, passed with --ignorefile ./.trivyignore.yaml, carries what a reviewer needs:

vulnerabilities:
  - id: CVE-2025-00000
    paths:
      - "usr/local/lib/python3.12/site-packages/example-1.0.dist-info/METADATA"
    statement: "Not reachable: the vulnerable parser is never imported. Owner: payments-team. Ticket PLAT-1234."
    expired_at: 2026-12-01
misconfigurations:
  - id: AVD-DS-0002
    paths: ["tools/debug/Dockerfile"]
    statement: "Debug image runs as root by design; never deployed."
    expired_at: 2026-12-01

The identifiers above are illustrative placeholders. The policy you build around the file is the substance:

• Every entry has a statement and an expired_at date. An exception with no expiry is a permanent decision made by whoever was in a hurry.
• Entries are scoped with paths or purls wherever possible, so suppressing a CVE in one test image does not suppress it across a repository.
• The file is code-reviewed by the platform or security team, enforced with code owners, not just by the application team.
• Suppressed findings remain visible to auditors: --show-suppressed lists them, and reviewing that list on a schedule is how you notice an exception that should have expired.
• An expired entry fails the pipeline again, which is the feature. Expiry dates are worthless if nobody has to act when they arrive, so send a warning a couple of weeks before.

For exceptions that follow a rule rather than a single ID, there is the Rego ignore policy, passed with --ignore-policy. It is a short program evaluated against each finding:

package trivy

import rego.v1

default ignore := false

# Accept a whole class only with a documented reason: here, findings in
# packages we vendor for a build tool that is never shipped.
ignore if {
	input.PkgName == "build-only-tool"
	input.Severity != "CRITICAL"
}

The sheet I worked from shows the older syntax (ignore { ... }); import rego.v1 with if is the modern OPA form, and you should confirm which your Trivy version's embedded OPA accepts by running the policy against a test finding before rolling it out. Treat a Rego ignore policy with the suspicion you would give any code that makes the gate pass: keep it small, test it, review it like a security control, and never let it silently cover CRITICAL.

Custom checks

The misconfiguration engine runs Rego checks from the bundle, and you can add your own to encode organisation-specific rules: "every Kubernetes Deployment in the payments namespace must set a data-classification label", or "no Terraform resource may create a public bucket in our Gulf region accounts". Point Trivy at a directory with --config-check ./my-checks, enable your package namespace with --check-namespaces user, and supply static data with --config-data ./data; in trivy.yaml these live under rego.check, rego.namespaces and rego.data. Custom checks are code: put them in their own repository with tests, version them, and publish them as an OCI artifact if you distribute them widely, using the checks-bundle-repository mechanism.

Older flag names (--policy, --namespaces) were renamed in earlier releases. If you inherit a pipeline that still uses them, treat that as a sign the pipeline has not been maintained, and update it while you are there.

SBOMs, VEX and attestation: making results portable

Scanning a running image over and over is wasteful and, worse, wobbly: the answer depends on when you ask. The supply-chain answer is to produce an inventory once at build time and then ask questions of that inventory as often as you need.

The SBOM as the system of record

A software bill of materials lists the packages inside an artifact. Trivy produces CycloneDX and SPDX (--format cyclonedx, spdx, spdx-json) and consumes them with trivy sbom.

# At build time: produce and store the inventory.
trivy image --format cyclonedx --output sbom.cdx.json registry.example.com/team/app:1.4.2

# Later, as often as you like, with no image pull: match against today's DB.
trivy sbom --severity HIGH,CRITICAL --exit-code 1 sbom.cdx.json

There is one trap that catches every team once. A CycloneDX SBOM generated by default contains no vulnerabilities: it is an inventory. If you want findings embedded, add --scanners vuln when generating. Decide which you want: a clean inventory is better for long-term storage and for feeding tools such as Dependency-Track, which do their own matching.

The pattern this enables is the rescan loop. Because the database updates roughly every six hours, an image that passed yesterday can fail today without a single byte changing. Instead of re-pulling every image in every registry nightly, store the SBOMs you generated at build time, and rescan those. It is cheaper (no image layers), faster, and it covers artifacts whose images have been deleted or are in a registry you can no longer reach.

Trivy can also reuse SBOMs that are already attached to an image: --sbom-sources oci,rekor looks for one in the registry or in the Rekor transparency log before falling back to analysing the image, and it detects SBOM files inside images when they have extensions such as .cdx.json or .spdx.json. Reusing the producer's SBOM is faster, but it means you are trusting the producer's inventory; decide which attestations you accept from whom.

VEX: turning noise into statements

The majority of findings in a scan of a typical base image are technically present but not exploitable in your usage. A vulnerable function in a library you include but never call; a flaw in a feature compiled out. Teams handle this by editing ignore files, which works but does not travel: the suppression lives in one repository, in one tool's format.

VEX, the Vulnerability Exploitability eXchange, is the portable form. A VEX document is a set of statements about a specific product and vulnerability, with a status: not_affected, affected, fixed or under_investigation. Trivy reads OpenVEX, CSAF and CycloneDX VEX, from four kinds of source: a VEX repository (including the community VEX Hub), a local file, an OCI attestation, or a reference inside an SBOM.

trivy image --vex repo registry.example.com/team/app:1.4.2
trivy image --vex ./openvex.json registry.example.com/team/app:1.4.2
trivy image --vex oci registry.example.com/team/app:1.4.2
trivy sbom --vex sbom-ref app.cdx.json

You may pass several --vex flags, and their order sets their priority. Findings suppressed by VEX are hidden from the report unless you add --show-suppressed, which is what an auditor should run. Two recent changes matter. Version 0.73 added discovery of VEX attestations attached as OCI 1.1 referrers and as bare in-toto statements during image scans, skipping non-VEX artefacts gracefully; if you publish VEX alongside images, this lets consumers pick them up with no extra configuration. Version 0.71.1 fixed VEX document loading problems, which is a reminder to pin and test rather than assume.

The governance rule for VEX is the same as for ignore files, only stronger: a not_affected statement is a security claim made on behalf of the product. It needs a justification, an author, and review. A VEX file anybody can edit to make red builds green is a laundering mechanism. Treat it as a signed artifact of the team that owns the product, not as a convenience of the team that owns the pipeline.

Attestation, to prove it

An SBOM or VEX statement is only as good as the claim that it belongs to this image and was produced by your pipeline. Trivy can emit a cosign-vuln format that is a predicate suitable for cosign, which then signs it and attaches it to the image as an attestation.

trivy image --format cosign-vuln --output vuln.json registry.example.com/team/app@sha256:<digest>
cosign attest --predicate vuln.json --type vuln registry.example.com/team/app@sha256:<digest>

Attest against the digest, never a tag; a tag can move after the attestation is made and the two then describe different content. The downstream consumer, which might be an admission controller, verifies the attestation with cosign before trusting the claim. I have not re-verified cosign's flags against its current release, so check cosign attest --help for your version. See the Kubernetes guide for the admission side of this loop.

Upgrades and migrations

Trivy is 0.x software on a fast release cadence. Between January and August 2026 the project shipped v0.69 through v0.74, in intervals of roughly two to eight weeks, with patch releases in between. In a 0.x project a minor version is allowed to break things, and several of those did. The platform owner's job is to make upgrades boring, and the first step is to treat them as planned changes rather than background noise.

What changed recently, and who it bit

It is worth reading this list as a catalogue of the kinds of break that happen, not as a history lesson.

• Distribution changes (v0.72.0, 30 June 2026). The APT repository now publishes new releases only to the generic distribution. A machine whose source line still uses a release codename (jammy, noble, or $(lsb_release -sc)) silently stays frozen at v0.71.2: no error, no upgrade. The correct line is deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main. In the same release, architecture-specific image tags such as 0.71.0-amd64 stopped being published; use the plain multi-arch tag (aquasec/trivy:0.74.0) or, better, a digest. Anything still pulling an -amd64 tag breaks outright.
• Default changes. From v0.67, --list-all-pkgs defaults to true, which makes JSON output bigger; anything parsing the output or storing it feels that in size.
• Flag and key renames over time. --security-checks became --scanners; --skip-update became --skip-db-update; --light is gone; the misconfiguration flags --policy and --namespaces became --config-check and --check-namespaces; and the old trivy k8s cluster and trivy k8s all subcommands became trivy k8s with --report summary|all. v0.69 also changed the misconfiguration provider mapping to use ID rather than AVDID, which can affect anything that filters on those fields.
• New detection. Releases routinely add ecosystems and rules: Julia in v0.69, pylock.toml in v0.70, Bottlerocket advisories and .NET self-contained runtime detection in v0.72, Jenkins plugin licence reading in v0.73, RapidFort image support in v0.74. New detection means new findings. A gate that was green can turn red on an upgrade with no change in the application, which is correct behaviour and needs a communication plan.

An upgrade procedure

Pin exact versions everywhere (binary, image, action, operator chart) and change them through reviewed pull requests. For each bump:

1. Read the release highlights for every minor you are skipping, not only the destination. The project publishes them as GitHub discussions for each minor.
2. Run old and new side by side on a fixed corpus of images and repositories, and diff the JSON. Expect additions from new detection; investigate any disappearances, which are either fixed false positives or regressions.
3. Check the gate's blast radius. Count how many pipelines would newly fail. If it is large, stage the rollout with an advisory period before enforcement.
4. Roll out in rings: the platform team's own repositories, then a few volunteer teams, then everyone.
5. Clear state if a schema complains. After an upgrade, trivy clean --all resets caches; trivy clean --vuln-db removes only the vulnerability database, which is the fix when an old cached database schema conflicts with the new binary.
6. Keep the previous version available for a fast rollback, mirrored in your registry.

# Side-by-side comparison on a fixed corpus.
for img in $(cat corpus.txt); do
  name=$(echo "$img" | tr '/:' '__')
  docker run --rm -v trivy-cache:/root/.cache aquasec/trivy:0.73.0 image -q -f json "$img" > "old-$name.json"
  docker run --rm -v trivy-cache:/root/.cache aquasec/trivy:0.74.0 image -q -f json "$img" > "new-$name.json"
done

That sketch deliberately shares one cache volume for the database so the comparison isolates the binary change; use separate volumes if you want to compare data as well. Note the cache lock: running old and new concurrently against the same volume would collide, so run them sequentially as above.

The operator and the data, separately

The operator chart, the operator application, the Trivy scanner it launches, and the databases are four versioned things. Upgrade the data path first where you can (a mirror update is invisible and reversible), then the scanner, then the operator. For the operator, read its own release notes, because CRD changes in Helm need care: Helm does not upgrade CRDs in the crds/ directory automatically, so check the chart's upgrade notes before assuming a helm upgrade is enough.

Cost and observability

Trivy is open source under Apache-2.0 with no licence fee, so "cost" means the resources around it. Knowing where they go keeps the conversation with finance short and the conversation with engineers honest.

Where the money goes

The spending is in five places, in rough order of size for a typical organisation: CI minutes (every scan takes runner time, multiplied by every pipeline run), bandwidth for database and image pulls (small per scan, large in aggregate and on cross-region egress), storage for caches, reports and SBOMs, the in-cluster footprint of the operator (scan jobs, API server and etcd load), and human time spent triaging, which dwarfs the rest and is the subject of the final section.

The reductions follow directly from earlier sections. Cache the Trivy directory between jobs. Move to a server or a mirror so the database is fetched once, not per job. Scope scanners: --scanners vuln on an image job and misconfiguration only on the infrastructure job. Skip directories that are not shipped. Rescan stored SBOMs rather than pulling images again. Each is a few lines of configuration and together they commonly cut scan time substantially, though I would not quote a percentage without measuring your own workload.

If you operate in the Middle East, one further cost is data residency and egress location. Teams with workloads in Gulf cloud regions, or bound by national data rules, should check where their mirror and server live: pulling the database across a continent for every job is slow, and some regulated environments cannot reach public registries at all, which returns you to the air-gap pattern. Reports that include package inventories and file paths are also data; decide whether they may leave the region before wiring a SaaS dashboard to them. Aqua's commercial platform and the Trivy Cloud integration introduced in v0.68 are options if you want a managed layer; evaluate them against the same residency questions.

Measuring the platform itself

A platform needs service-level indicators. For a scanning platform the useful ones are few:

The first row contains a detail worth dwelling on. The same exit code 1 can mean "findings exceeded the threshold" (what you want to count as a gate) or, in some failure paths, a tool error. Choosing a distinct gate exit code with --exit-code 10 or similar lets your wrapper tell the two apart without parsing text. Do that once, in the template, and your success-rate metric becomes trustworthy.

#!/usr/bin/env bash
# scan-wrapper.sh: distinguish "gate failed" from "the scanner broke".
set -uo pipefail
start=$(date +%s)

trivy image --exit-code 10 --severity HIGH,CRITICAL --ignore-unfixed \
  --format json --output result.json "$IMAGE"
rc=$?

echo "scan_duration_seconds $(( $(date +%s) - start ))" >> metrics.txt
case "$rc" in
  0)  echo "gate: pass" ;;
  10) echo "gate: findings above threshold"; exit 1 ;;
  *)  echo "scanner error (exit $rc): failing closed" >&2; exit 2 ;;
esac

Logs and debugging on a platform

For each support case, ask for three things in this order: the exact Trivy version, the --debug output, and the command line or config used. Nine in ten tickets resolve at the second. Keep a short internal page that maps the common error messages to causes: timeout means raise --timeout or fix the scope; x509: certificate signed by unknown authority means a TLS-inspecting proxy, cured with SSL_CERT_FILE or SSL_CERT_DIR rather than TRIVY_INSECURE; no space left on device under /tmp/fanal-... means TMPDIR or --parallel 1. Teams on networks with Cloudflare Gateway or similar inspection will meet the certificate error constantly; the right fix is to trust the inspection CA in the runner image, never to disable verification.

Incident playbooks

Platform ownership is mostly not the steady state; it is what you do when the steady state breaks. Five incidents recur. Each has a recognisable first signal, a first action that stops the bleeding, and a follow-up that stops it happening again.

The investigation order

When the cause is unclear, resist the urge to guess. The order that finds most problems fastest is:

1. Version. trivy --version. Is it the version you think it is, and did it change recently?
2. Data. Database and Java DB age and source. Did the mirror update? Did a refresh happen just before the failures started?
3. Scope. What was scanned? A changed skip-dirs, a new base image or a newly added directory explains many sudden differences.
4. Configuration precedence. Is an environment variable or flag overriding the config file? --debug prints what was actually used.
5. Environment. Network, proxy, TLS inspection, disk, memory, cache contention.

Where Trivy stops

A guide that only praises a tool is marketing. Trivy is excellent at what it does, and what it does has edges. Knowing them is how you avoid promising teams protection they do not have.

It finds known vulnerabilities in packages it can detect. That is three qualifications. Known: a vulnerability with no database entry is invisible, and the lag between disclosure and entry is real. In packages: code you wrote, code copied into your tree without a manifest, statically linked libraries with stripped metadata, and vendored dependencies are not seen as packages. It can detect: ecosystems without analyzers, unusual installation methods and unrecognised lock files produce no findings, which looks identical to "clean".

It does not tell you whether a finding is exploitable. A reachable function, an exposed port and a network path are all outside its view. That is what VEX, reachability tools and runtime context are for. Reporting a raw count as "risk" is the commonest misuse of scanner output.

It does not look at runtime. Trivy analyses statically and never executes the image. A container that is compromised after deployment, or whose behaviour differs from its contents, is invisible to it. Runtime detection (Falco and similar) and admission control (Kyverno, Gatekeeper) cover what a scanner cannot.

It scans the working tree, not history. A secret removed in a later commit is not found by trivy fs; Gitleaks and TruffleHog search history.

It is single-tenant with no central findings store. There is no built-in place to see "all findings across all teams over time", no assignment of findings to owners, no workflow. At scale you add DefectDojo, Dependency-Track or a commercial platform, or build a pipeline into your warehouse.

Its misconfiguration coverage is broad, not exhaustive. It overlaps Checkov for IaC (Trivy absorbed tfsec's engine), and Kubescape and kube-bench for cluster compliance. Teams with deep policy requirements often run a dedicated policy engine, and compare coverage on their own code before dropping either.

Its release model is fast and 0.x. If your change-control process cannot absorb a minor release every few weeks, you need a slower, vetted internal release channel, or you need to accept the drift.

Note the pattern: most "alternatives" are actually complements. The mature position is that scanners are one layer, used with a findings manager, a policy engine and runtime detection, and that two scanners disagreeing is information, not a bug. Differences in severity source, in database coverage, and in precise versus comprehensive detection priority all produce legitimately different answers. Trivy's default --detection-priority precise favours fewer false positives; comprehensive finds more, including less certain matches. Pick consciously and say which you use.

Running Trivy as a platform for other teams

Everything so far has been technical. A platform succeeds or fails on whether teams choose to use it, and they choose based on how much it costs them. A scanner that adds four minutes to every pull request, fails mysteriously, and demands a ticket for every exception will be routed around within a quarter.

Design the product, not just the pipeline

Give teams a paved road: one reusable workflow or template they include with two lines, which installs the pinned, mirrored Trivy, applies the baseline configuration, runs the scan with the platform's gate, uploads SARIF and an SBOM, and reports a clear summary. What they get for using it should be visible: findings in their pull request, in the tool they already use, with the fix version.

Make failure messages actionable. "Gate failed: 1 CRITICAL" is useless; "CVE-XXXX in openssl 3.0.x, fixed in 3.0.y, your base image python:3.12-slim needs a rebuild; here is the Renovate config that automates it" is a support ticket that never gets filed. The Fixed Version column exists for this. --ignore-unfixed is the single most important adoption lever, because a gate that blocks on findings nobody can fix teaches teams that the gate is arbitrary.

Roll out in phases

1. Observe. Run in advisory mode: exit code 0, reports collected, nothing blocks. You learn the baseline, find the scanner's rough edges on your real workloads, and find which teams are ahead.
2. Block on new, critical, fixable. Enforce only for CRITICAL, unfixed ignored, on changes that introduce the finding. Early wins, low friction.
3. Widen. Add HIGH, then secrets, then misconfiguration, one at a time, each with a notice and a date.
4. Enforce expiry. Exceptions now expire and fail again, with advance warnings.
5. Measure outcomes, not activity: time to remediate, findings trend, exceptions in force.

The discipline is to make each step reversible and announced. Surprise enforcement is what turns a platform into an adversary.

Ownership and support

Decide and publish the following: who owns the template, who approves exceptions and how fast, what the support channel and its response times are, the upgrade calendar, and how teams request a change to the baseline. The Docker guide covers the image side that most teams will be fixing; the Terraform guide covers the IaC that trivy config scans; for the delivery side, see Argo CD. When the template references a neighbouring tool, link the guide so a team can self-serve.

Reporting upward

Leadership wants one number and will pick the wrong one if you do not offer a better. "Total CVEs" rises with every database refresh and punishes thoroughness. Offer instead: percentage of production images scanned in the last 24 hours, critical findings older than the agreed remediation window, number of exceptions in force and past expiry, and time to remediate. These measure whether the programme works, and each has an owner who can act on it.

The review checklist

Use this for a design document introducing Trivy to a new environment, or for reviewing an existing platform. Each line is a question with a clear wrong answer.

Supply chain of the scanner

• Is the Trivy version pinned exactly, and by digest or SHA where possible?
• Are GitHub Actions pinned by full commit SHA?
• Is the binary or image mirrored internally and verified against published checksums or signatures?
• Does any pipeline use latest, a floating branch, or an unpinned install script?
• Did any pipeline run v0.69.4, or a pre-0.35.0 trivy-action or pre-v0.2.6 setup-trivy, during the March 2026 window, and were secrets rotated if so?
• Are the plugins in use reviewed and pinned, or disabled?

Data

• Where does each of the vulnerability DB, Java DB and checks bundle come from, and is there a mirror?
• Is database age measured, and does a stale database fail or warn?
• Is the mirror job monitored and alerting on failure?
• In an air gap, what is the transfer cadence, and is the age visible in reports?

Gate design

• What happens when the scanner itself errors: fail closed or open?
• Can a team weaken the gate through a flag, environment variable or edited config?
• Does the gate use a distinct exit code so tool errors are distinguishable from findings?
• Is there an audited break-glass path for emergencies?

Exceptions

• Does every exception have a statement, an owner and an expiry?
• Are they scoped by path or package URL?
• Are they code-reviewed by someone outside the requesting team?
• Is --show-suppressed reviewed on a schedule?
• Is every not_affected VEX statement justified and signed off?

Scale and runtime

• One cache directory per concurrent process, or a server?
• Redis behind multiple server replicas?
• Timeouts, parallelism and temp directory sized from measurement?
• Is the operator scoped, rate-limited and watched for API server load?

Security of the job

• Does the scan job hold only read credentials, with no deploy or push rights?
• Is the Docker socket avoided?
• Is egress restricted?
• Are reports access-controlled like the code, and are real secret findings rotated?

Operations

• Is the Trivy version emitted from every job and monitored?
• Are scan success rate, duration and database age tracked?
• Is there a tested runbook for each incident in the playbook section?
• Is there an upgrade procedure with a fixed corpus, rings and rollback?

Outcome

• Do you report remediation time and exceptions, not raw CVE counts?
• Is there a findings store above Trivy, or a plan for one?

The complete picture

Put the whole platform on one page and it is a short chain, in which each link has one job and one owner.

Read left to right it tells the story of one image. The scanner and its data arrive through your mirror, so a public outage or compromise cannot reach you unannounced. At build time a pinned template scans the image, emits an inventory and signs the result against the digest. The gate is a policy owned by the platform, with exceptions that expire. The records are stored by digest, so you can answer questions about a release long after the image is gone. Every night the stored inventories are matched against the newest data, because a clean result has a shelf life. In the cluster the operator reports what is actually running, and metrics feed the dashboards that tell you whether the whole loop is working.

Notice what is not on the page: heroics. Nothing in it depends on someone remembering to update a database, on someone guessing the right flag, or on trust in a tag. The defining quality of a well-run platform is that its failure modes are loud, measured and rehearsed.

Where the series leaves you

Across three levels you have gone from pointing Trivy at an image, to gating a pipeline on its output with the database and cache understood, to owning it as infrastructure that other teams depend on and that attackers have already targeted once. The habits that carry over are not specific to this tool.

Treat every dependency as something you operate. The databases, the binary, the actions and the registries are all supply chain, and the question is always who can change them without your knowing. Make staleness and drift measurable: database age, tool version, exception age. Prefer policy in version control over policy in people's heads, with reviewed changes and expiry dates. Separate the scan from the privileges, so the day a tool misbehaves is a bad day and not a breach. And measure outcomes, because a scanner's activity is not the same thing as your security improving.

Where to go next depends on what you found weakest in the review checklist. If the weak area is what to do with the findings, read the Docker guide's hardening sections and the Kubernetes guide on admission and policy. If it is the infrastructure being scanned, the Terraform guide. If it is how the results reach production safely, the Argo CD and Helm guides. If it is how the platform is watched, Prometheus and Grafana. And if it is how Trivy's secrets and credentials are handled in practice, Vault.

The best next step is concrete: take the review checklist, run it against what you operate this week, and pick the three answers that made you wince. Fix those first.

Sources

• Trivy documentation
• Installation
• trivy image reference
• Config file reference
• Troubleshooting
• Client/server mode
• Standalone mode
• Kubernetes scanning
• Filtering
• Air-gapped environments
• Misconfiguration scanning
• Secret scanning
• SBOM
• VEX
• Plugins
• Trivy releases
• Trivy changelog
• v0.72.0 release highlights
• v0.73.0 release highlights
• v0.74.0 release highlights
• Security incident 2026-03-19
• trivy-action
• Trivy Operator documentation
• Trivy Operator releases

Part three of three. A senior interview on Trivy is rarely about flags. The interviewer wants to know whether you can design a scanning platform, run it through an incident, and defend its trade-offs to someone who controls the budget. This file is organised around those three things, with the model of a strong answer after each prompt, and then a set of common questions and a self-test. About fifty minutes.

The version assumed throughout is Trivy v0.74.0 (14 August 2026). If you are asked about anything newer, say so and say how you would check the release notes.

How to answer at this level

Three habits separate a senior answer from a mid-level one, and interviewers listen for them.

State the failure mode before the feature. A mid-level answer describes what the tool does. A senior answer says what breaks, for whom and how you would notice. "Trivy downloads its vulnerability database on every cold start" is a fact; "a hundred simultaneous cold runners behind one NAT get rate-limited and fail intermittently, which is why I would mirror the database" is an answer.

Name the trust boundary. Whenever you introduce a component, say what it is trusted to do and what happens if it lies. The March 2026 compromise of Trivy's own release channels is the best example you can give, and you should be able to tell it in thirty seconds.

Quantify, or say how you would. You will not know the numbers for their environment. Say what you would measure: scan duration at the 95th percentile, database age, exception count, time to remediate. An answer that ends in a metric beats one that ends in a tool name.

The thirty-second version, to have ready

Trivy is an open-source scanner from Aqua Security that finds known vulnerabilities, misconfigurations, hard-coded secrets and licence problems in container images, filesystems, repositories, IaC and Kubernetes clusters. It is a single Go binary that works from a local cache of a vulnerability database, rebuilt about every six hours. On a platform, the work is not running it; it is operating its data dependencies, its gate policy and its own supply chain.

Keep the last sentence. It signals immediately that you think as an owner.

Part one: system-design prompts

Design a scanning platform for forty teams

The prompt. "We have forty product teams on Kubernetes, builds in a central CI system, images in a private registry. Design the vulnerability scanning platform."

A strong answer builds in layers and says why at each step.

At build time, a centrally owned reusable pipeline template runs Trivy on each image before it is promoted. The template pins Trivy by exact version and digest, pulls it from an internal mirror, and applies a baseline trivy.yaml that the application team cannot weaken: HIGH and CRITICAL block, unfixed findings are ignored so the gate only asks for things a team can act on, and secret and misconfiguration scanning are on. It emits three artifacts keyed to the image digest: a JSON or SARIF report for the pull request, a CycloneDX SBOM, and a signed attestation.

For the data, I would mirror the vulnerability database, the Java database and the checks bundle into an internal registry on a schedule shorter than the upstream rebuild, alert when the mirror job fails, and measure the database age in every scan. The mirror removes rate limits, removes a public dependency from the critical path, and lets me control when a new database reaches teams.

For scale, cold-cache stampedes are the first thing that breaks, so a shared Trivy server with a Redis cache, or simply a good mirror plus CI cache, removes per-job database downloads. I would measure before choosing: if the mirror and cache already keep scan p95 acceptable, a server is extra infrastructure with its own on-call.

After deployment, images age. A nightly job rescans the stored SBOMs against the newest database, which is cheaper than pulling images and works for artifacts no longer in the registry. In the cluster, the Trivy Operator reports what is actually running, with metrics feeding alerting on new criticals in production, not absolute totals.

For governance, exceptions live in .trivyignore.yaml files with a statement, an owner and an expiry, code-reviewed by a party outside the requesting team. --show-suppressed is reviewed on a schedule.

Rollout is phased: advisory first, then block on critical and fixable, then widen, each step announced with a date.

What makes it strong: it names the failure mode that motivates each component, it keeps the gate's configuration out of the hands of the team being gated, and it ends with how the rollout avoids making the platform an adversary.

What a weak answer does: "We run trivy image in each pipeline and fail on critical." That is correct for one team and says nothing about forty.

Follow-ups to expect.

• "Why not just let each team run it?" Because the gate's strictness, the data source and the version then vary per team; you cannot state what the organisation's policy is, you cannot rotate a compromised version, and the exceptions are unreviewed.
• "Why ignore unfixed findings?" A gate that blocks on issues nobody can remediate teaches teams the gate is arbitrary. The unfixed ones still appear in the weekly report; they do not block a merge.
• "What about the images already running?" The operator and the nightly SBOM rescan.

Design the platform for an air-gapped environment

The prompt. "A regulated client in the Gulf forbids internet access from the build network. How do you run Trivy?"

A strong answer starts by enumerating the external dependencies, because that is the whole problem: the vulnerability database, the Java database, the checks bundle (which falls back to a copy embedded in the binary), VEX Hub, Maven Central for some Java lookups, and the version-check endpoint. Each needs either a transferred copy or to be switched off.

The approach: on a connected staging host, pull the database artifacts with an OCI tool such as oras, verify them, and move them across the boundary by the client's approved transfer process into an internal registry or directly into cache directories. On the isolated side, scan with --skip-db-update, --skip-java-db-update, --skip-check-update, --skip-version-check, --disable-telemetry and --offline-scan, from a tarball with --input if there is no registry.

Then the part that separates seniors: freshness is the real risk. A database six weeks old is silently missing six weeks of disclosures. So I would set and document a transfer cadence, automate it, make the database age part of every report, and fail the gate beyond a threshold. I would also point out that --offline-scan does not stop the database download; it only disables remote lookups, so a pre-seeded cache with --skip-db-update is what makes it truly offline. I would also raise where reports are stored, since they contain package inventories, which may be regulated data.

Follow-up: "How do you get the Trivy binary in?" The same way: download, verify the checksum and signature on the connected side, transfer, and store in an internal artifact repository. Never install from the internet on the isolated side.

Design continuous scanning of a production cluster

The prompt. "Tell me how you would keep a 400-node cluster continuously scanned."

A strong answer picks the Trivy Operator and immediately discusses its cost. It creates report custom resources (vulnerability, configuration audit, exposed secret, RBAC, infrastructure, compliance, SBOM) for each workload, all stored in etcd through the API server. On a large cluster that is significant load, so I would scope the scanners I actually use, target or exclude namespaces, limit concurrent scan jobs so a cold start does not launch hundreds of pods each downloading the database, use ClientServer mode to share the database, and set report retention. I would watch API server latency and etcd size after the rollout.

Reports are namespaced, so ordinary RBAC governs which team sees which findings, which gives cheap multi-tenancy inside the cluster. Prometheus metrics feed Grafana, and I would alert on new criticals in production, not totals.

The judgement point: do not make the cluster gate a hard admission block on day one. A continuous policy will one day block a rollback because a database refresh added a finding to the image you are rolling back to, so any admission control built on report data needs an audited bypass for incidents.

If the interviewer pushes on alternatives: trivy k8s from a scheduled job is lighter and adequate for compliance snapshots and KBOMs, at the cost of no continuous view.

Design the exception and governance model

The prompt. "Teams will want to suppress findings. How do you stop that becoming a loophole?"

A strong answer treats exceptions as debt with a due date. Every entry carries a statement, an owner and an expired_at; entries are scoped by path or package URL rather than by ID alone; the file is protected by code owners so the requesting team cannot approve its own exception; expired entries make the pipeline fail again; and suppressed findings remain reportable through --show-suppressed. For claims of non-exploitability I would use VEX statements (not_affected with a justification) signed by the product owner, because unlike an ignore file they are portable and auditable. For class-based rules I would accept a short Rego ignore policy, tested and reviewed like a security control, and I would never let it cover CRITICAL silently.

The weak answer is "we use .trivyignore".

Part two: incident-response questions

Incident questions test whether you panic, guess, or investigate. State the first action, the reasoning order, and the follow-up.

"Every pipeline turned red this morning and nothing changed."

The instinct to say "nothing changed" is the trap: something always changed, and in a scanner the usual suspect is the data. The vulnerability database is rebuilt about every six hours, so an image that passed yesterday can fail today without any change of your own. The second suspect is a scanner upgrade with new detection.

My order: confirm the Trivy version; check the database source and age and whether a refresh preceded the failures; scan one failing image with the previous version or the previous database to see which variable matters; look at what the failing findings have in common (one package across many base images is typical). The first action is not to relax the global threshold. I would publish the affected package list, let teams with a patched base rebuild, and use a time-boxed, approved exception for images with no fix. The follow-up is a canary: a fixed corpus scanned against each new database before the mirror promotes it.

"Scans are failing with failed to download vulnerability DB, but only for some jobs."

Intermittent plus download plus registry suggests rate limiting on shared egress: many jobs on one NAT address look like one abusive client. Other causes are a registry outage, a proxy change, or expired credentials (DENIED: denied from ghcr.io when stale credentials are sent for an anonymous pull; docker logout ghcr.io fixes that). The immediate fix is to point db.repository at an internal mirror, or at the alternate public registry if no mirror exists. The lasting fix is a mirror and a freshness alert.

"We think a compromised version of Trivy ran in our pipelines."

This is the question to be ready for, because it happened. In March 2026 a threat actor used a compromised credential to publish malicious artifacts: the trivy binary v0.69.4 (exposed about three hours), most trivy-action tags before 0.35.0, and every then-existing setup-trivy release. Safe versions are 0.69.3 and earlier plus the later releases, trivy-action 0.35.0 or later, and setup-trivy v0.2.6 or later.

The answer has four parts. Determine exposure: from version telemetry and pipeline logs, which jobs ran an affected version or an unpinned reference in the window. Assume compromise: the project's own guidance is to treat every secret the pipeline could reach as compromised and rotate immediately; do not negotiate with that. Contain: block the published indicators at the egress layer and move to verified versions pinned by digest or commit SHA. Prevent: pin Actions by SHA, pin the binary by digest, verify signatures, mirror internally, restrict runner egress, and reduce the credentials each scan job can see so the next rotation list is short.

The sentence that impresses: "The incident did not require a vulnerability in Trivy's code. It exploited the fact that pipelines pulled whatever a tag pointed at."

"A scan found a live AWS key in an image we already published."

Rotate first, investigate second. The finding proves the key has been somewhere it should not; deleting the layer does not un-publish copies. Then determine who pulled the image, and check the key's CloudTrail or equivalent activity. Then restrict the report, which itself contains the secret fragment. Then find the origin: Trivy scans the working tree, not full history, so use a history-aware tool (Gitleaks or TruffleHog) to look for earlier copies. The preventive controls are BuildKit secret mounts and a secret scan in the pipeline before the image is pushed.

"The gate blocked an urgent production fix."

Do not tell the responder to disable the scanner. Use the documented break-glass path with an approver and a record, and set it to expire. Afterwards, ask whether the gate should apply to rollbacks and hotfixes at all, and whether the finding that blocked it was fixable.

"Trivy is passing on everything, and then we had an incident."

The honest list of what Trivy cannot see: vulnerabilities not yet in the database; code you wrote; vendored or statically linked code without package metadata; ecosystems it cannot detect, where "no findings" looks identical to "clean"; runtime behaviour; and anything about exploitability. The senior move is to say "I would first check whether the scan actually analysed the affected component" (look for analyzer errors, a failed Java DB load, a skipped directory) before blaming the tool.

"Two scanners disagree."

Disagreement is information. Causes include different severity sources (vulnerability.severity-source, default auto), different data coverage, Trivy's precise versus comprehensive detection priority, and VEX or status filtering applied by one and not the other. I would compare the raw JSON for one disputed finding, find which input differs, and then decide which behaviour I want. Not which tool is "right".

Part three: arguing a trade-off to leadership

Leadership does not want flags. It wants a recommendation, a cost, a risk and a number. Each of these prompts is a conversation with a director or a CISO. A good answer is short, plain, and names what you are not recommending.

"Why do we need a mirror? It is free to pull from the internet."

The public registries are free but they are a dependency on the critical path of every pipeline, and they are rate limited per address. A mirror costs a small registry and a scheduled job. It buys three things: builds do not fail because a third party had a bad hour, we decide when a new database reaches teams, and a compromised public channel cannot reach our runners directly. Put it in terms of blocked engineer-hours per outage and they will usually agree.

"Why not block on every critical finding?"

Because findings with no available fix are not something a team can act on, and a gate that blocks on them teaches engineers to bypass it. I recommend blocking on fixable HIGH and CRITICAL findings, reporting the unfixable ones weekly with an owner, and using VEX for ones we have assessed as not exploitable. The measurable outcome is time to remediate fixable criticals, not a count that hits zero.

"Can we go faster by skipping the database update to speed up scans?"

No, and I would show the failure mode rather than argue it. --skip-db-update makes scans faster by making them less current, and without a refresh job the cache never updates, so a gate can pass indefinitely on a stale database. If speed is the problem the real levers are caching, a mirror or server, scoped scanners and skipped directories. Staleness must be measured, not accepted quietly.

"Do we need to buy a commercial platform?"

It depends on what problem is actually unsolved. Trivy itself has no licence fee. What it lacks is a central findings store with ownership and workflow, multi-team reporting and, at scale, support. Before buying, list the capabilities you need and check them against open options (DefectDojo, Dependency-Track) and the commercial platform, with attention to data residency: where do reports containing our package inventories go? The decision is about engineering time saved versus licence and lock-in, and I would pilot with two teams before committing.

"What does this programme cost, and what does it buy?"

Costs: CI minutes, bandwidth, storage for caches and SBOMs, in-cluster footprint, and platform team time. The biggest is human triage time, which is why the design focuses on gating only what is actionable. What it buys: a defined policy, an inventory of what is shipped, the ability to answer "are we affected by this new CVE" in minutes from stored SBOMs, and evidence for audits. I would present it with three measures: percentage of production images scanned in the last 24 hours, critical findings past the agreed remediation window, and exceptions in force.

"How fast should we upgrade Trivy?"

It is 0.x software with a release every few weeks, and minor releases can break things; v0.72 changed the APT repository and container tag scheme, for example. So I would not track the latest release automatically, and I would not freeze either. The recommendation is a scheduled cadence, for example monthly: Renovate opens the pull request with the new digest, we run old and new over a fixed corpus of images and diff the output, stage through rings, and keep the previous version mirrored for rollback. The risk of freezing is running old detection code, and the risk of floating is the March 2026 scenario.

Common interview questions

What is the difference between trivy image, trivy fs, trivy rootfs, trivy repo and trivy config? They differ in the target. image scans a container image from a daemon, registry or tarball; fs scans a local project directory (lock files, secrets, optionally misconfiguration); rootfs scans an unpacked root filesystem and is the one that analyses OS packages; repo scans a local or remote git repository (it clones first); config runs only the misconfiguration scanner on IaC. trivy k8s scans a live cluster and trivy sbom scans an existing SBOM.

What scanners run by default? vuln and secret. Misconfiguration and licence are opt-in with --scanners. trivy config runs misconfiguration only.

Does Trivy fail the build on findings by default? No. The exit code is 0 regardless of findings; you opt in with --exit-code 1. Tool errors exit non-zero, but wrappers often swallow that.

What is the vulnerability database and how is it distributed? An aggregation of NVD, distribution advisories, the GitHub Advisory Database and others, rebuilt about every six hours, distributed as an OCI artifact (schema version 2) from mirror.gcr.io and ghcr.io by default, and stored locally as a BoltDB file in the cache directory.

What does the Java DB do? It maps JAR file hashes and artifact data to Maven coordinates for JARs without usable pom metadata. It is only downloaded when JARs are present, which is why a Java-heavy scan can fail on a different database than a Go-only one.

What is the difference between --skip-db-update and --offline-scan? --skip-db-update stops the database download and requires a pre-seeded cache. --offline-scan only disables remote lookups such as Maven Central; it does not stop the database download.

Why do two processes fail on one cache? The database is a BoltDB file with a file lock. The fix is one cache directory per process, or client/server mode.

How does client/server mode split the work? The server does vulnerability and licence matching and holds the database and cache; the client analyses the artifact, and runs misconfiguration and secret scanning locally so sensitive files do not travel. Multiple server replicas need a shared Redis cache or clients get layer cache missing.

How secure is the server token? It is a single static shared secret in a header. No users, no audit, no rate limiting. Put TLS and, if you need per-team identity, an authenticating gateway in front.

What is VEX and how does Trivy use it? A Vulnerability Exploitability eXchange statement says whether a product is affected by a vulnerability (not_affected, affected, fixed, under_investigation). Trivy reads OpenVEX, CSAF and CycloneDX VEX from a repository, a file, an OCI attestation or an SBOM reference, with --vex; order sets priority, and suppressed findings show with --show-suppressed.

Why is my CycloneDX SBOM missing vulnerabilities? By default it is only an inventory. Add --scanners vuln when generating, or scan the SBOM later with trivy sbom.

How would you scan a Kubernetes cluster? trivy k8s for a point-in-time scan of infrastructure, configuration and workloads, with --report summary|all, --compliance for benchmarks such as k8s-cis-1.23, and --format cyclonedx for a KBOM. The Trivy Operator for continuous reports as custom resources.

What changed in v0.72 that can silently break an install? The APT repository publishes only to the generic distribution, so a source line using a codename stays frozen at v0.71.2; and architecture-specific image tags such as 0.71.0-amd64 are no longer published, so use the plain multi-arch tag or a digest.

Which flags were renamed or removed? --security-checks became --scanners, --skip-update became --skip-db-update, --light was removed, --policy became --config-check, --namespaces became --check-namespaces, and trivy k8s cluster and trivy k8s all became trivy k8s.

What is the safest way to run Trivy in a container? Avoid mounting the Docker socket, since it is root-equivalent on the host. Use --image-src remote or a tarball with --input, pin the image by digest, and restrict egress.

How do you reduce a slow scan? Cache the directory, scope scanners (--scanners vuln), skip directories that are not shipped, tune --parallel, raise --timeout only for the workloads that need it, and set TMPDIR to real disk. Also check whether the scope is wrong before buying time.

What does Trivy not do? Find unknown vulnerabilities, exploitability analysis, runtime detection, search of git history for secrets, or provide a multi-team findings store. See the detailed guide for the full list and the tools that complement it.

Sixty-second self-test

Answer aloud, then check against the section above.

1. Name the four inputs to a scan and the failure mode of each.
2. Why does a green image turn red overnight, and what is the first thing you check?
3. What is the exit code of trivy image when it finds critical vulnerabilities and you passed no flags?
4. Give two reasons to run a database mirror and one reason you would not fall back to the public registry.
5. What does client/server mode keep on the client, and why?
6. Name the three compromised components in March 2026, and the safe version of each.
7. What fields does a good exception entry carry, and who should approve it?
8. Why attest against a digest and not a tag?
9. Which two v0.72 changes break installs silently or loudly?
10. What single sentence describes what your gate guarantees, honestly?

If you hesitated on more than three, re-read the incident playbooks and the trust-model section of the detailed guide, then try the questions on a colleague. The fastest way to find gaps in a platform answer is to have someone ask "and what if that fails?" after every sentence.

Part three of three. This file collects the production traps that only show up at scale, the habits that keep a scanning platform healthy once other teams depend on it, and the checklists to run before a pull request or a design document is approved. Everything is checked against Trivy v0.74.0 (14 August 2026).

The mistakes here are different from the ones in the earlier levels. They are rarely a wrong flag. They are a reasonable decision that was correct for one team and wrong for forty, or a default nobody questioned because it had never hurt anyone yet.

Common errors at this level

Each entry has the symptom you will see, the cause underneath it, and the fix. Read the cause column first; it is the part that transfers to problems not listed here.

The three causes behind most of the table

Nearly every row reduces to three root causes, and recognising them is faster than memorising rows.

Shared state without a plan. The cache directory, the registry, the NAT address and the server's cache are all shared resources. Problems appear when concurrency crosses a threshold nobody tested. If you can name the shared thing, you can name the fix: give each process its own, or put a shared, correctly sized one in front.

A missing signal. Staleness, version drift, partial scans and silent non-upgrades all fail without an error. The fix is never "be more careful"; it is a metric and a threshold: database age, Trivy version in use, scanner error rate.

Trust by default. Floating tags, latest, public plugins, curl | sh from a moving branch, broad scan credentials and open reports are all instances of trusting something without a record of deciding to. The March 2026 incident exploited exactly this.

The practices that pay off most

In order of leverage, which is to say the order in which I would spend a platform team's first quarter.

1. Pin everything, and automate the bumps. The single highest-value change. Pin the Trivy binary or image by exact version and digest, pin GitHub Actions by full commit SHA, pin operator chart versions, and let Renovate or an equivalent open reviewed pull requests. Pinning without bumping is a slow failure; bumping without pinning is the March 2026 scenario.
2. Mirror the data and the binary. The three databases and the release artefacts come from your registry, refreshed on a schedule shorter than upstream's, with an alert on job failure. This removes rate limits, removes a public dependency from your critical path, and gives you control over promotion.
3. Make the gate central and failure-aware. One reusable workflow, owned by the platform team and protected by code owners. A distinct --exit-code for "findings" so scanner errors are distinguishable. Fail closed on scanner errors.
4. Measure freshness and version from every scan. Emit database age and trivy --version as build metadata. Alert on databases older than 48 to 72 hours and on versions more than two minors behind.
5. Give exceptions owners and expiry dates. .trivyignore.yaml with statement, paths or purls, and expired_at, reviewed by someone outside the requesting team.
6. Gate on fixable findings. --ignore-unfixed with --severity HIGH,CRITICAL is the default adoption posture. Report the unfixable ones separately.
7. Keep the SBOM and rescan it. Generate at build time, store by digest, rescan nightly. This answers "are we affected by today's CVE" in minutes.
8. Reduce the credentials and egress of scan jobs. Read-only pull credentials, no deploy rights, no Docker socket, restricted outbound network.
9. Rehearse the incidents. A game day for the compromised-scanner case costs an afternoon and shortens a real response by hours.

Practice cards

1. Reproduce the lock collisionRun two scans of a large image against one --cache-dir at the same time and read the error. Fix it with a directory per process. Write down how a shared CI runner would hit this.
2. Measure your cold startTime a scan with an empty cache and with a warm one. The difference, multiplied by your daily scan count, is the case for a mirror or server.
3. Let the database go stale on purposeSeed a cache, then scan with --skip-db-update for a few days. Watch nothing fail. Then add the age check and watch it fail.
4. Expire an exceptionWrite a .trivyignore.yaml entry with an expired_at in the past and confirm the finding returns. Then use --show-suppressed with a valid one and read what it shows.
5. Verify a releaseDownload a Trivy release archive and its checksums, and verify them. Then look at which signing artefacts the release publishes and plan where your pipeline would verify them.
6. Swap a tag for a digestFind one workflow with a tag reference, resolve the digest or commit SHA, and pin it with a version comment. Notice how many reviewers would have noticed a tag moving.
7. Diff two versionsScan five images with two adjacent Trivy releases and classify every difference in the JSON as new detection, data change or regression.
8. Distinguish the exitsWrap a scan with a distinct gate exit code and force three outcomes: clean, findings above threshold, and a nonexistent image. Confirm your wrapper reports each differently.

Production traps that appear only at scale

The shared cache that becomes a shared failure

On a laptop the cache is a convenience. On a CI fleet it is a shared mutable resource. Two cases recur. On persistent runners with a home-directory cache, parallel jobs collide on the BoltDB lock, and the collision is load-dependent, so it passes review and appears in production. On ephemeral runners with a remote cache restore, a corrupted cache archive can be restored into every job, and the symptom is odd failures everywhere that trivy clean --all fixes locally but not in the pipeline that keeps restoring the bad cache.

The habit: key the CI cache by Trivy version and date, not just a static name, so a corrupt entry ages out and an upgrade does not reuse an incompatible layout. Give each concurrent job its own directory. And when a cache is suspected, the fastest diagnostic is to run once with --cache-dir $(mktemp -d); if that works, the shared cache is the problem.

The fallback that hides an outage

Wrappers that try the internal server and fall back to standalone scanning make a server outage invisible, then recreate the cold-cache stampede you built the server to prevent, at the worst possible moment. If you keep a fallback, it must log loudly and emit a metric, and the fallback path should use a database mirror, not the public registry. Otherwise the fallback is a second way to be rate limited.

Stale-by-design air gaps

Air-gapped scanning works, and then the transfer that copies the database in becomes a quarterly chore, then a yearly one. Since a database disclosed-vulnerability gap grows linearly with time, a six-month-old database makes every scan result misleading while every scan looks normal. The trap is treating the initial seeding as the end of the project. Put the transfer on a calendar, automate what the boundary allows, and print the database age at the top of every report produced inside the gap.

The gate that drifts

A baseline that teams can override by flag or environment variable drifts. Flag precedence is command line over environment variable over config file over default, which means anything a team puts on the command line defeats your trivy.yaml. Gates that live in the application repository are edited by the people they gate. The fix is structural: the scan step is part of a template teams include, the template is code-owned, and the parameters it exposes are a deliberately short list.

New detection turns the world red

Every minor release may add detection (new ecosystems, new advisory sources, new secret rules, new misconfiguration checks), and more detection means findings appear on code that did not change. Teams read that as "the platform broke our build". The trap is upgrading in one motion across the whole organisation. Stage through rings, run an advisory period for changes that add findings, and publish what is new before the gate changes.

Reports as a leak channel

Secret findings and package inventories are sensitive. Reports uploaded as open CI artefacts, pasted into chat, posted to a public code-scanning dashboard or pasted into an issue with --trace-http output (which can print tokens) all leak. The trap is that the scanning tool itself is considered safe, so nobody reviews where its output goes. Treat a scan report like a build log that might contain credentials.

The operator that loads the control plane

The Trivy Operator writes report objects for every workload into etcd. On a large cluster, with all scanners enabled and no concurrency limit, it can raise API server latency and etcd size noticeably, and its scan pods can all pull the database at once after a restart. The habit is to roll it out with only the scanners you will act on, namespace scoping, a concurrency limit and a report retention policy, and then watch API server latency for a week. If the operator's own reports are not being consumed by anything, it is an expensive way to fill etcd.

Scan credentials with push rights

It is common for one "registry service account" to be used for scanning, building and publishing. A compromised scanner then has push rights to your production registry. Give scan jobs a pull-only credential scoped to the repositories being scanned. It costs an hour and removes an entire category of incident.

Exit code overloading

If the gate and the tool error both exit 1, your success-rate metric mixes "teams have findings" with "the platform is broken", and on-call cannot tell which it is. Choose a distinct gate exit code once, in the template.

The unpinned plugin

trivy plugin install runs a program with the privileges of the scan job. Public plugins are not audited by the project. Unpinned plugin installs in CI are a supply-chain opening, and so is a plugin that fetches other things at run time. Ship an approved set in your pinned image, and disable ad hoc installation in pipelines.

Platform-ownership habits

Write down what the gate guarantees

Every platform should have one sentence, agreed with security, that says what passing means. A defensible one: "No fixable HIGH or CRITICAL vulnerability known to our vulnerability database at the time of the scan, in packages Trivy detects, and no secret matching the enabled rules." Anything stronger is a promise you cannot keep. Anyone who asks "so we are secure?" gets the sentence, not a yes.

Treat each release as a change, with a corpus

Keep a fixed corpus of a dozen representative images and repositories (a distroless Go image, an old Python image, a Java monolith with many JARs, a Node project with a lock file, a Terraform directory). Run each candidate Trivy version over it and diff the output. The corpus is the cheapest regression suite a scanning platform can have, and it doubles as the performance benchmark for timeouts.

Keep a version ledger

Record, per pipeline, the Trivy version, the database build and the configuration hash that produced each result. When an advisory says a version is affected, this is the difference between a same-day answer and a week of archaeology. Emitting trivy --version into build metadata costs nothing.

Own the exception queue like a service

Exceptions need a turnaround time. If approval takes a week, teams will work around the gate; if it takes five minutes with no review, it is not a control. Publish the target time, staff it, and report on the queue: requests, time to decision, entries expiring this month.

Publish the error catalogue

The common failures are few. A short internal page mapping each message to its cause and fix (timeout, certificate, lock, layer cache, disk, rate limit, DB download, codename APT source) removes most support load. Ask every ticket to include version, --debug output and command line, in that order.

Communicate changes as changes

Announce baseline changes with a date, say what will newly fail, and offer a way to see the effect in advisory mode first. Announce Trivy upgrades with the release highlights that matter to your users. Teams forgive strictness they saw coming.

Decide the failure policy, and write it in the template

What happens when the database cannot be downloaded, when the Java DB is missing, when the server is down, when the scan times out? Fail closed or fail open is a decision per environment and per finding class. Silent defaults make the decision for you.

Review the platform's own supply chain quarterly

List every third-party component in the scan path: the binary, the action, the image, the plugins, the mirror job's tools, the Helm chart. For each, record the pin, the verification and the owner. The March 2026 compromise affected the distribution channels, the GitHub Actions and the install script; a quarterly look costs an hour.

Hardening recipes

A pinned, mirrored install step

The install step is where supply-chain discipline is won or lost. Whatever your CI system, the shape is the same: a fixed version, a checksum you verify, and an internal source.

#!/usr/bin/env bash
# Install a pinned Trivy from an internal mirror and verify its checksum.
set -euo pipefail

VERSION="0.74.0"
BASE="https://artifacts.example.com/mirror/trivy/v${VERSION}"
ARCHIVE="trivy_${VERSION}_Linux-64bit.tar.gz"

curl -sfL "${BASE}/${ARCHIVE}" -o "/tmp/${ARCHIVE}"
curl -sfL "${BASE}/trivy_${VERSION}_checksums.txt" -o /tmp/checksums.txt

( cd /tmp && grep " ${ARCHIVE}\$" checksums.txt | sha256sum -c - )
tar -xzf "/tmp/${ARCHIVE}" -C /usr/local/bin trivy
trivy --version

The archive and checksum file names follow the naming convention of the release assets; confirm them against the release page for the version you pin, since I have not re-verified every name. The principle is that the checksum is published alongside the archive in your mirror and was itself verified against the upstream signatures when you mirrored it. A checksum fetched from the same compromised channel as the archive proves nothing.

A scan job with minimal privileges

scan-image:
  stage: scan
  image: registry.example.com/platform/trivy@sha256:<digest>   # mirrored, pinned by digest
  variables:
    TRIVY_CACHE_DIR: "$CI_PROJECT_DIR/.trivy-cache"
    TRIVY_DB_REPOSITORY: "registry.example.com/mirror/trivy-db:2"
    TRIVY_JAVA_DB_REPOSITORY: "registry.example.com/mirror/trivy-java-db:1"
    TRIVY_SKIP_VERSION_CHECK: "true"
    TRIVY_DISABLE_TELEMETRY: "true"
  cache:
    key: "trivy-0.74.0-$CI_COMMIT_REF_SLUG"
    paths: [.trivy-cache/]
  script:
    - trivy image --image-src remote --exit-code 10 --severity HIGH,CRITICAL
        --ignore-unfixed --format json --output result.json "$IMAGE"
  artifacts:
    when: always
    paths: [result.json]
    expire_in: 7 days
    access: developer

Every flag has an environment-variable form of TRIVY_<FLAG_NAME_UPPER_SNAKE>, which is what makes the variables block possible. Check the exact variable names for the database repository flags with trivy image --help for your version before copying; the pattern holds but I have not confirmed each one. Notice the choices that matter: a digest-pinned image from your mirror, --image-src remote so there is no Docker socket, a cache key containing the Trivy version, a distinct gate exit code, and an artefact with a short expiry and restricted access. See the GitLab CI guide for how job artefact access and caching work in detail.

A nightly rescan from stored SBOMs

#!/usr/bin/env bash
# nightly-rescan.sh: match last night's database against stored build-time SBOMs.
set -uo pipefail
failures=0

for sbom in sboms/*.cdx.json; do
  if ! trivy sbom --severity HIGH,CRITICAL --ignore-unfixed \
        --exit-code 10 -q --format json --output "reports/$(basename "$sbom" .cdx.json).json" "$sbom"; then
    echo "attention: $sbom"
    failures=$((failures + 1))
  fi
done
echo "images with new blocking findings: $failures"

This simple form treats any non-zero exit as "attention", which includes scanner errors; in a real version use the distinct exit code to separate the two as in the wrapper shown in the detailed guide. The point of the script is the pattern: the nightly job scans inventories, not images, so it is fast, cheap and does not depend on the registry.

Verifying which version ran

# Record the version and data sources into the build metadata.
trivy --version | tee build-metadata/trivy-version.txt

The output includes the Trivy version and, once databases are cached, the database and Java DB metadata. Collect these files centrally, and you have the ledger.

Review checklists

For a pull request that changes the scanning configuration

• Does the change weaken the gate (lower severity, add ignore-unfixed or status filters, skip directories, disable a scanner), and is that stated in the description with a reason?
• Is every new skipped directory or file pattern shipped in any image? Skipping removes findings.
• Does any new exception carry a statement, an owner and an expiry, and is it scoped by path or package URL?
• Are new flags current? No --security-checks, --skip-update, --light, --policy or --namespaces.
• Is the version or digest pinned, and does the bump come from the automated tool?
• Does any step add a network destination, a plugin or an install script?
• Is a new Rego ignore policy tested against a known finding, and does it avoid covering CRITICAL?
• Are secrets passed as files or standard input, not command-line arguments?

For a pull request that adds a new service to the platform

• Is the image scanned by digest, not tag?
• Does the pipeline use the central template, with no local overrides?
• Are SBOM and attestation emitted, and stored by digest?
• Does the scan job hold only pull credentials?
• Is the owner of exceptions for this service named?

For a design document proposing a scanning platform

• Data. Where does each database come from? Is there a mirror, a freshness metric and an alert? What is the air-gap transfer plan, if any?
• Supply chain. Pins, verification, mirrored artefacts, plugin policy, and what the plan is if a release channel is compromised.
• Scale. Expected scans per hour, cold-start behaviour, cache model, server need, Redis, timeouts and temp disk.
• Gate. Thresholds, unfixed policy, exit codes, failure policy, break-glass.
• Governance. Exceptions, VEX, review path, expiry, reporting.
• Tenancy. Cache and credential isolation per team; report visibility.
• Operations. Version ledger, SLIs, upgrade cadence, runbooks, on-call owner.
• Rollout. Advisory phase, dates, communication, reversibility.
• Limits. What this does not catch, and which complementary tools cover it.
• Data residency. Where mirrors, servers and reports live, and whether reports may leave the region.

Before you ship the platform

1. PinsBinary or image by version and digest, Actions by SHA, chart versions fixed.
2. DataMirror in place, job monitored, freshness alert live, fallback policy decided.
3. GateCentral template, distinct exit code, fail closed on errors, break-glass documented.
4. ExceptionsSchema enforced, owners named, expiry checked, review path staffed.
5. PrivilegesPull-only credentials, no Docker socket, restricted egress, restricted reports.
6. RecordsSBOM and attestation by digest, version ledger, nightly rescan running.
7. RehearsalAt least one incident game day completed, with the compromised-scanner case covered.
8. RolloutAdvisory phase scheduled, dates announced, support channel staffed.

Where to go from here

If this level taught you one thing, it is that a scanner's correctness matters less than its operability: whether you can see when it is stale, whether you know which version ran, whether its failures are loud, and whether you can replace it in an afternoon when a release channel is compromised. The neighbouring guides go deeper on the pieces you will lean on next: Docker for the images being scanned, Kubernetes for the operator and admission, Vault for the credentials your scan jobs use, and Prometheus for the metrics that keep the platform honest.