How to Use Trivy: The Beginner's Guide to Scanning Container Images

CodexFuse Team · 2026-10-31T16:39:49.948Z · 11 min read min read

Install Trivy, run your first container image scan, filter by severity, read the report, and wire it into your CI pipeline as a security gate.

If you ship Docker images, you ship other people's code — base OS packages, language runtimes, and app dependencies — and any of them can carry a known vulnerability. Learning how to use Trivy is the fastest way to find those problems before your users do: it is a free, open-source scanner from Aqua Security that inspects a container image and lists every known CVE it finds, with one command and no server to run. This trivy tutorial walks you through it the way a beginner actually learns it: install, your first scan, reading the report, filtering by severity, fixing what matters, and wiring the whole thing into CI. It assumes you already know the basics of images from our Docker beginner guide, because Trivy scans the images Docker builds.

What is Trivy?

Trivy is a universal, open-source vulnerability scanner built by Aqua Security (Apache-2.0 license) that scans container images, filesystems, Git repositories, and Kubernetes clusters for known vulnerabilities, exposed secrets, and misconfigurations. Its CLI follows one pattern — targets (what to scan) and scanners (what to scan for) — and its default behavior needs no configuration: point it at an image and it builds a software inventory from the image's layers, then matches every package against vulnerability feeds like NVD, Alpine SecDB, and Debian's security tracker. At the time of writing, Trivy's GitHub project (aquasecurity/trivy) sits at roughly 38,900 stars with version v0.76.1 released on October 21, 2026 — the latest patch in a release cadence that moves fast, so always grab the newest release when you install.

How do I install Trivy?

Install Trivy through whatever channel fits your machine — the official docs keep the list current, and the three most common paths are below. This trivy for beginners arc assumes a Linux or macOS machine with Docker installed.

# macOS (official docs path)
brew install trivy

# Linux (official install script, works on most distros)
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin

# No install at all: run it as a container
docker run aquasec/trivy version

If you only need the fastest trivy install, the brew and install.sh commands above are the whole story.

The Docker-image route is handy on a fresh VPS where you don't want to touch the host: Trivy runs from the container and can scan your local images if you mount the Docker socket. There are also native packages for most distros in the official install docs, which keep Trivy updated through your normal package manager.

What is the fastest way to scan a Docker image with Trivy? (7-step first-scan arc)

This trivy scan docker image workflow is the core of the guide — seven steps from zero to a gated pipeline. Each step builds on the last.

1. Install Trivy. Pick one method from the previous section and confirm it with trivy version.
2. Pick a real image. Start with something you actually ship — your own app image, or a public one like nginx:1.25 for practice. Scan your own images in the lab, never production registries you don't own.
3. Run your first scan. trivy image nginx:1.25. On the first run Trivy downloads its vulnerability database (it caches it afterwards), pulls the image if it isn't local, walks its layers, and prints a report.
4. Read the report header. The top line names the detected OS of the image and the severity totals — for example, a sample scan of nginx:1.25 shows debian 12.4 with Total: 14 (UNKNOWN: 0, LOW: 3, MEDIUM: 6, HIGH: 4, CRITICAL: 1). The OS line matters: it tells you which distro feed Trivy matched against.
5. Filter for what matters. trivy image --ignore-unfixed --severity HIGH,CRITICAL nginx:1.25 hides vulnerabilities with no available fix and everything below HIGH — this is the working view most teams live in.
6. Fix and rescan. The report's Fixed Version column tells you the remedy; for OS packages this usually means rebuilding on a newer base image tag. Rebuild, then scan again to confirm the count drops.
7. Gate your CI. Add --exit-code 1 so the build fails when the filtered scan finds anything, then wire it into your pipeline (see the CI section below).

How do I read a Trivy report?

Read a Trivy report top-down: the OS line first, then the severity totals, then the per-package table rows. The table below maps every trivy severity to how a beginner should treat it, and each row names the library, the vulnerability ID, its severity, the installed version, the fixed version (if one exists), and a short title. The single most important rule for beginners — the severity rule — is: chase fixable HIGH and CRITICAL findings first, and treat everything else as backlog.

Two flags control the noise. --ignore-unfixed drops every finding with no available fix — these are problems you literally cannot act on yet. --severity HIGH,CRITICAL limits the report to the two levels that decide ship-or-not. Combine them and a 14-finding report shrinks to the handful that can actually block you.

How do I make Trivy's output machine-readable? (trivy json output)

Switch Trivy's output format when a human isn't the consumer: --format json --output results.json gives you the full report as structured data for dashboards and ticket automation. Trivy also supports table (the default you see in the terminal) and SARIF, which plugs straight into GitHub's code-scanning view.

# JSON report for automation
trivy image --format json --output results.json nginx:1.25

# SARIF for GitHub code scanning
trivy image --severity CRITICAL --format sarif --output trivy.sarif nginx:1.25

# Scan OS packages AND language packages together
trivy image --scanners vuln,secret,misconfig nginx:1.25

The --scanners flag is the modern control (it replaced the older per-target flags, so copy commands from old tutorials with care). By default Trivy runs the vulnerability scanner; adding secret and misconfig widens the same run to secrets and config problems.

Can Trivy find secrets in my image? (trivy secret scanning)

Yes — enable the secret scanner and Trivy flags API keys, private keys, and tokens baked into image layers. Run trivy fs --scanners vuln,secret,misconfig /path/to/myproject to check a project directory the same way you check an image. Treat any hit as an incident, not a finding: rotate the credential, then stop committing secrets into layers — a scanner finds leaks, it doesn't prevent them. Our secrets-management guide covers keeping credentials out of images in the first place.

How do I scan my Kubernetes cluster with Trivy? (trivy kubernetes)

Point Trivy at the cluster itself: trivy k8s --report summary cluster scans the workloads running in your cluster and shows a summary report, per the official docs. This is the natural next step after scanning individual images — it answers "what's actually deployed right now?" instead of "what did I build last week?" If you run a lightweight cluster, our K3s beginner guide is the matching starting point, and Trivy also ships a Kubernetes operator for continuous in-cluster scanning.

Trivy vs Grype vs Snyk: which scanner should a beginner pick? (trivy vs grype, trivy vs snyk)

Pick Trivy if you want the simplest path: one static binary, no daemon, no account, no registry credentials for local images, and output in table, JSON, or SARIF. That is why independent comparisons consistently recommend it as the starting point — the fresh AquilaX comparison (March 2026) calls it the recommended default, and the 17-day-old redlinesoft guide treats it as the industry's default image scanner.

Grype is the closest open-source rival and a fine choice if your workflow is SBOM-centric. Snyk makes sense when you want one paid platform covering code, dependencies, and containers together. For a beginner learning to scan images, Trivy's zero-friction setup wins — you can always layer a platform on later.

Where does Trivy fit next to Falco?

Trivy and Falco are siblings, not rivals: Trivy scans images before deployment to find known vulnerabilities, while Falco watches containers at runtime for suspicious behavior that no scanner can see. Our Falco beginner guide covers the runtime half — scan with Trivy, watch with Falco, and you cover both sides of the container's life.

How do I put Trivy in my CI pipeline? (trivy ci cd)

Fail the build on fixable CRITICALs with a two-command pattern: one full scan for visibility, one filtered scan as the hard gate. Trivy's exit code is 0 by default even when it finds vulnerabilities, so the --exit-code 1 flag is what turns a scan into a gate.

# Gate: fail the build only on fixable CRITICALs
trivy image --severity CRITICAL --ignore-unfixed --exit-code 1 myapp:latest

# GitHub Actions: official trivy-action (pin to a current release)
- name: Run Trivy vulnerability scanner
  uses: aquasecurity/[email protected]
  with:
    image-ref: myapp:latest
    format: sarif
    output: trivy-results.sarif
    severity: HIGH,CRITICAL

Two practices keep the gate sane. First, scan the exact artifact you would ship — the built image, not the Dockerfile — so the report matches production. Second, keep the visibility scan and the merge gate as separate steps with separate policies: developers read the full report, the gate only blocks on the severities you agreed on.

7 beginner mistakes with Trivy (and how to avoid them)

Most Trivy frustration comes from the same seven errors. Learn them here instead of in production.

Sources

• Trivy official documentation — "First steps" (install, CLI pattern, trivy image / trivy fs / trivy k8s examples, ecosystem integrations), fetched 2026-10-31: https://trivy.dev/docs/latest/getting-started/
• aquasecurity/trivy on GitHub — release history (v0.76.1 published 2026-10-21; v0.76.0 2026-10-14), ~38,900 stars, Apache-2.0, fetched via GitHub API 2026-10-31
• AquilaX — "How to Scan Docker Images for Vulnerabilities: Trivy, Grype, and Snyk Compared" (March 2026): https://aquilax.ai/blog/scan-docker-images-vulnerabilities
• redlinesoft — "CVE Scanning with Trivy: Finding Vulnerabilities in Container Images" (17 days ago): https://blog.redlinesoft.net/posts/docker-image-cve-scanning-trivy/
• dev.to — "Trivy in Java Development: Complete Guide to Container Security Scanning" (29 days ago): https://dev.to/said_olano/trivy-in-java-development-complete-guide-to-container-security-scanning-182m
• readmedium — "How To Check your Docker Images for Vulnerabilities": https://readmedium.com/how-to-check-your-docker-images-for-vulnerabilities-287bd61aacc6
• Chainguard education — Trivy tutorial (fresh independent guide): https://edu.chainguard.dev/chainguard/containers/security-and-compliance/working-with-scanners/trivy-tutorial/

Frequently Asked Questions

Does Trivy need the Docker daemon to scan images?

No. Trivy is a single static binary that pulls and inspects images on its own — no daemon, no server, no registry credentials for local images. You can even run Trivy itself as a container (docker run aquasec/trivy) on a machine where you don't want a native install.

Is Trivy free?

Yes. Trivy is open source under the Apache-2.0 license from Aqua Security — free to use commercially, with no account or paid tier required for scanning. Aqua sells a commercial platform built on top of it, but the scanner itself is fully free.

How is Trivy different from Falco?

Trivy is a pre-deployment scanner: it finds known vulnerabilities in image contents before you ship. Falco is a runtime detector: it watches running containers for suspicious behavior like unexpected shell spawns. They complement each other — scan with Trivy, watch with Falco. See our Falco beginner guide for the runtime half.

Why does my first scan show so many vulnerabilities?

Because a base image carries an entire OS userland, and the default report shows every severity including unfixable ones. Apply --severity HIGH,CRITICAL --ignore-unfixed to see the findings you can actually act on, then shrink them by rebuilding on a newer base image tag.

Can Trivy scan images in a private registry?

Yes — Trivy works with all major registries (Docker Hub, ECR, GCR, Artifactory and others) and authenticates with your normal registry credentials. For a first run, though, practice on public images or your own local builds.