Trivy

Last reviewed Aug 26, 2026 · 843 words

trivy image --severity HIGH,CRITICAL --ignore-unfixed ghcr.io/immich-app/immich-server:release

That one line, against any image you already run, is the whole reason to install Trivy. It downloads a vulnerability database, unpacks the image layers, lists the OS packages and language dependencies inside, and prints the CVEs that have a fix available and are rated High or Critical. Thirty seconds, no account, no agent. Trivy is Aqua Security's open-source scanner and, at 37,609 GitHub stars, the default answer to "is this container full of known holes." The job of this guide is to make its output useful rather than terrifying.

Noise is the first problem, and 2 flags fix most of it

Run trivy image with no flags on a typical Debian-based image and you get hundreds of results, most of them Low or Medium with no available fix, which is accurate and useless. The catalogue's "findings can be noisy" is polite. The 2 flags above, --severity HIGH,CRITICAL and --ignore-unfixed, typically cut the list by 90 percent and leave things a maintainer could act on. A .trivyignore file with one CVE ID per line silences accepted risks, and --exit-code 1 turns the scan into a pass or fail gate.

Then read what remains with judgement. A Critical in a library the application never calls is real but not urgent; a High in the reverse proxy facing the internet is the one to chase tonight. The container security piece is about exactly that prioritisation.

Install and the scan targets

Deployment is a static Go binary, a container image (aquasec/trivy) or a Helm chart for the Kubernetes operator. On a Docker host, the container form avoids installing anything:

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  -v trivy-cache:/root/.cache/ aquasec/trivy image nginx:latest

The named volume matters: the vulnerability database is a few hundred megabytes, and re-downloading it every run is slow and hammers the upstream registry. Beyond images, trivy fs . scans a project directory's lockfiles, trivy config . checks Dockerfiles, compose files, Terraform and Kubernetes manifests for misconfigurations, trivy repo scans a Git URL, trivy k8s walks a live cluster, and trivy image --format cyclonedx emits an SBOM. Same binary, same database, 256 MB of RAM.

Server mode for a fleet of hosts

If several machines scan regularly, run one Trivy in server mode so the database is downloaded once:

trivy server --listen 0.0.0.0:4954

Clients then scan with trivy image --server http://scanner.lan:4954 image:tag, sending only layer metadata across the network. This is also the pattern for air-gapped or metered networks: the server updates its database on a schedule, or you fetch it once with trivy image --download-db-only and copy the cache directory. The catalogue's note that database updates need connectivity is the one operational requirement; a scan against a stale database is worse than no scan, because it feels like assurance.

Where it fits in a homelab pipeline

Three places earn their keep. In CI, a step in Woodpecker or Gitea Actions that runs trivy image --exit-code 1 on the image you just built, so a new base-image CVE blocks a deploy instead of surprising you. In a registry: Harbor bundles Trivy as its scanner and shows results per tag in the UI, which is the most pleasant way to consume them. And on a schedule: a weekly cron on the Docker host that scans every running image and writes a report, because the images you pulled 8 months ago are the ones with the problems. Pair that report with an update habit; Watchtower or a manual pull is how findings actually get fixed, and Trivy without updates is a very accurate list of things you have not done.

Limits worth knowing before you trust it

Trivy knows about packages, not behaviour. A hand-compiled binary with a vulnerable statically linked library will not appear unless an SBOM says so, and a misconfiguration that only exists at runtime is outside its view. It also cannot tell you whether a vulnerable function is reachable, which is why the noise flags matter. On the dev-tools shelf it is the scanner, not the whole security programme, and it pairs with rather than replaces host hardening and a tool like CrowdSec at the edge.

What I'd do

Install the binary on the main Docker host, scan every running image once today with the 2 noise flags, and fix or accept what is left into .trivyignore with a comment explaining why. Add a weekly cron that repeats the scan and mails you the diff. If you build your own images, put --exit-code 1 in CI. If you run Harbor, turn on its Trivy scanning and stop running it by hand. Total cost is an evening, and after that you know what you are running instead of hoping.