Trivy

Trivy is Aqua Security's open-source, all-in-one scanner, and its whole reason for existing is coverage rather than any single deep specialty: one static Go binary that scans a container image, a filesystem, or a git repository for known vulnerabilities; checks Terraform, CloudFormation, and Kubernetes manifests for misconfigurations; scans for accidentally committed secrets; flags dependencies under risky licenses; and generates a software bill of materials — all from the same install, the same cache, and the same --severity/--exit-code conventions. Most pipelines used to need three or four separate tools to cover that ground: one for image vulnerabilities, one for Terraform, one for secrets, one for the SBOM. Trivy's pitch, and the reason it shows up as a default in so many CI configs, is that a platform team can pin one binary version instead of four and get most of what those four tools covered. By the end of this page you should know Trivy's internal architecture, how its two vulnerability-matching paths differ, how its misconfiguration scanner absorbed the standalone tfsec engine, the commands you'll actually run day to day, and where it still loses to a narrower, deeper tool in each of its four categories.

What Trivy is, and the problem it solves

☺ Like you're 10: It started as one narrow tool and grew into four tools' worth of checks, all still living inside the same single binary.

Trivy started narrowly. It was created in 2019 by Teppei Fukuda (known in the project as knqyf263) as a container image vulnerability scanner, and Aqua Security — a cloud-native security vendor — took over as its primary steward not long after, continuing to develop it as free, open-source software under the Apache-2.0 license. What happened next is the part worth understanding: release by release, Aqua broadened Trivy's scope rather than shipping a second tool. Filesystem and git-repository scanning arrived. Misconfiguration scanning for infrastructure-as-code arrived. Secret scanning arrived. License scanning arrived. SBOM generation arrived. A Kubernetes-native mode (trivy k8s, and a separate in-cluster Trivy Operator) arrived for scanning a live cluster continuously rather than a single build artifact once. Each addition kept the same binary, the same cache directory, the same output-format family, and the same severity/exit-code conventions — which is the detail that actually matters here. Aqua didn't just add features; it kept every feature behind one consistent CLI surface.

The problem that consistency solves is an operational one, not a detection one. A pipeline that wants to know "is this image running a vulnerable OpenSSL," "does this Terraform module open a security group to the whole internet," "did someone bake an AWS key into a Docker layer," and "what's actually inside this artifact, for the audit trail" used to mean installing and maintaining three or four separate tools — each with its own install method, its own config file format, its own output schema, its own release cadence to track for CVEs in the scanner itself. Trivy answers all four questions from one static binary with no runtime dependency: drop it into a CI image with a single curl or a package-manager line, and every scan type is available immediately. That operational simplicity, more than raw detection depth in any one category, is why platform teams reach for it by default — see CNAPP & the unified cloud security stack for how this same "fewer tools, one correlated view" argument plays out one layer up, at the commercial-platform level.

Architecture: one binary, four scanners, one shared database

☺ Like you're 10: Trivy looks at what you point it at, decides which of its four checks apply, downloads the answer key it needs, and prints one combined report card.

Trivy has no server component by default and installs no agent — it's a single static binary you run against a target: a container image (local or in a registry), a directory on disk, a git repository URL, a running Kubernetes cluster, a virtual-machine image, or an already-generated SBOM file. Given a target, Trivy walks its filesystem, classifies what it finds — OS package manager databases, language-specific lockfiles, Terraform/CloudFormation/Kubernetes/Dockerfile/Helm source, anything that looks secret-shaped — and routes each category to the scanner built to handle it. Which scanners actually run is controlled by the --scanners flag (vuln, misconfig, secret, license), with sensible defaults per target type so most invocations don't need to specify it at all.

Vulnerability matching depends on data Trivy doesn't ship inside the binary itself. On first run — and periodically after, roughly every twelve hours unless told otherwise — Trivy pulls a vulnerability database published as an OCI artifact from ghcr.io/aquasecurity/trivy-db (plus a separate Java-specific index for jar-in-jar detection), aggregated from NVD, GitHub's Security Advisory database, and distro-specific trackers (Alpine's secdb, the Debian Security Tracker, Red Hat's OVAL feeds, Amazon Linux's ALAS), and caches it locally under ~/.cache/trivy. Misconfiguration checks, by contrast, ship bundled inside the binary itself as compiled Rego policies, so no network call is needed for that scanner to work offline. Secret and license scanning use their own bundled rulesets — a regex-and-entropy detector list for secrets, a package-license classifier for license scanning. One cache directory, one binary, four independent data sources feeding four independent checks that all report through the same output pipeline.

Vulnerability scanning: OS packages and language dependencies, matched two different ways

☺ Like you're 10: Checking your operating system's own software list works differently from checking the list of libraries your app imports — Trivy does both, and each one is matched against a different kind of answer key.

When Trivy scans an image or filesystem for known vulnerabilities, it's actually running two distinct matching processes, and knowing which one applies to a given finding matters when you're deciding how much to trust it. The first is OS package matching: Trivy identifies the base distribution (Alpine, Debian/Ubuntu, RHEL/CentOS/Fedora, Amazon Linux, and others) from distro-identifying files inside the image, then reads that distro's own package manager database directly — apk's installed-package list, dpkg's status file, rpm's database — without needing the apk, dpkg, or rpm binaries present in the image at all. Each installed package and version is matched against that specific distro's own security-advisory feed, not a generic CPE lookup against NVD. That distinction is why OS-level results tend to carry fewer false positives than a naive NVD/CPE matcher would produce: a distro's own advisory already states precisely which package version shipped the fix, instead of Trivy having to infer it from a loosely-matched product name.

The second path is language-dependency matching, and it runs independently of the OS layer entirely. Trivy parses lockfiles directly — no build execution required — and matches the parsed package-and-version pairs against the GitHub Advisory Database and OSV-sourced data bundled into the same trivy-db.

Because these two paths are independent, a scan can (and routinely does) return findings from both at once against a single image: a stale libssl reported through the OS-package path, and a vulnerable lodash reported through the npm-lockfile path, in the same run, in the same report. This is also the language-dependency job software composition analysis in depth covers generally — Trivy is simply one implementation of it, running for free, offline, inside the same binary as everything else on this page.

# scan a built image for OS + language vulnerabilities, fail the build on HIGH/CRITICAL
$ trivy image --severity HIGH,CRITICAL --exit-code 1 \
    --ignore-unfixed \
    registry.acme.io/checkout:1.8.2

# --ignore-unfixed matters in practice: without it, a build can fail on a CVE
# with no available patch yet, which nobody on the team can actually act on today.

Misconfiguration scanning: Terraform, CloudFormation, Kubernetes — and the tfsec absorption

☺ Like you're 10: tfsec used to be its own separate inspector for Terraform specifically; Aqua moved that inspector's whole rulebook inside Trivy instead of keeping two rulebooks that could drift apart.

Trivy's misconfiguration scanner walks infrastructure-as-code source and checks it against a bundled ruleset before anything is ever applied: Terraform (.tf/.tf.json, plus a rendered terraform plan converted with terraform show -json), CloudFormation templates, raw Kubernetes manifests (or a live cluster, via trivy k8s), Dockerfiles, rendered Helm charts, and Azure Resource Manager and Google Deployment Manager templates. Each provider gets its own parser, producing an internal representation that's checked against rules written in Rego — Open Policy Agent's policy language, the same language covered generally in IaC security & policy as code — organized by provider namespace, with each rule carrying an ID like AVD-AWS-0107 (an Aqua Vulnerability Database ID), a severity, a human-readable message, and remediation guidance.

The detail worth knowing precisely: this misconfiguration engine isn't something Aqua built from scratch for Trivy. tfsec was an independent, well-regarded open-source tool purpose-built for Terraform-specific static analysis. Aqua absorbed the tfsec project and its rule engine, and over subsequent releases folded that engine directly into trivy config's Terraform scanner rather than maintaining two separate parsers and two separate rulesets that could quietly drift out of sync with each other. Aqua has publicly signaled that the standalone tfsec binary is on a path toward being superseded by trivy config as the actively developed home for that logic — check the tfsec repository's own README for the current state of that timeline, since deprecation schedules for open-source projects tend to slip and shift. What matters for a team migrating is more concrete than the timeline: most tfsec-authored rule IDs and the familiar #tfsec:ignore:<ID> inline-suppression comment still work when the same Terraform runs through Trivy, because the engine underneath the two front ends is now the same code, not two reimplementations of the same idea. Swapping the CLI you invoke in CI is mostly a binary-name change, not a rewrite of every suppression comment in the repository. See the tfsec tool page for the standalone tool on its own terms.

# infra/security_group.tf — an open ingress rule, the kind a misconfig scan exists to catch
resource "aws_security_group" "web" {
  name = "web-sg"
  ingress {
    from_port   = 22
    to_port     = 22
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]   # AVD-AWS-0107 flags exactly this shape
  }
}

$ trivy config --severity HIGH,CRITICAL infra/
# infra/security_group.tf (terraform)
# ===================================
# Tests: 24 (SUCCESSES: 23, FAILURES: 1)
# AVD-AWS-0107 (HIGH): Security group rule allows ingress from 0.0.0.0/0.

# suppress one specific finding with a reason on record, same convention tfsec used
$ cat .trivyignore
# accepted risk — bastion host, restricted further by a security-group-referencing rule below
AVD-AWS-0107

SBOM generation and secret scanning: the other two scanners in the same binary

☺ Like you're 10: One more command from the same binary writes down everything inside the box; another checks nobody left a key taped to the outside of it.

Trivy generates a software bill of materials directly from a scanned artifact — the same command that finds vulnerabilities can emit the inventory those vulnerabilities were matched against, in either of the two dominant SBOM formats:

$ trivy image --format cyclonedx --output sbom.cdx.json registry.acme.io/checkout:1.8.2
$ trivy image --format spdx-json --output sbom.spdx.json registry.acme.io/checkout:1.8.2

# scan an SBOM someone else already generated — e.g. with Syft — for known vulnerabilities.
# this decouples "who produced the inventory" from "who checks it against a vuln feed."
$ trivy sbom sbom.cdx.json

That last command is worth pausing on: it means a pipeline can standardize on one SBOM generator — Trivy itself, or Syft, which many teams prefer specifically for SBOM generation — while still using Trivy purely as the vulnerability-matching engine against whatever inventory arrives. See software bills of materials for the fuller treatment of SPDX versus CycloneDX and why a real SBOM has to be generated from the built artifact rather than a source manifest.

Secret scanning runs as part of the same invocation by default, using a bundled set of regex-and-entropy detectors — AWS access keys, GCP service-account JSON, Slack tokens, private-key PEM headers, generic high-entropy strings — customizable through a trivy-secret.yaml config for org-specific patterns or exclusions. Keep the scope precise, though: Trivy's secret scanner inspects whatever filesystem or image layers it's given — the working tree, or a shallow checkout for trivy repo — not the full commit history a dedicated tool walks. gitleaks and TruffleHog exist specifically to crawl git history and, in TruffleHog's case, live-verify a hit against the issuing provider; Trivy's built-in detector is a useful last line of defense on the artifact you're about to ship, not a replacement for that discipline running earlier, on every commit.

# select exactly which scanners run in one invocation — vuln is the default alone if omitted
$ trivy fs --scanners vuln,secret,license .
$ trivy image --scanners misconfig registry.acme.io/checkout:1.8.2   # config-only, skip vuln DB entirely

Day-to-day commands

☺ Like you're 10: One target type per command, one severity/exit-code pair to actually gate a build, and a server mode so a whole CI fleet shares one warm cache instead of downloading the database a hundred times.

# the four target types you'll reach for most often
$ trivy image registry.acme.io/checkout:1.8.2        # a built container image
$ trivy fs .                                          # a local directory / checked-out repo
$ trivy repo https://github.com/acme/checkout          # clone-and-scan a remote git repo
$ trivy k8s --report summary cluster                    # scan every workload in the current kube-context

# gating flags — the ones that actually turn a scan into a pass/fail pipeline check
$ trivy image --severity CRITICAL,HIGH --exit-code 1 --ignore-unfixed registry.acme.io/checkout:1.8.2
# default exit code is 0 regardless of findings — forgetting --exit-code is the #1 reason
# a team thinks their pipeline is gating on Trivy when it has never actually failed a build

# machine-readable output for a dashboard, DefectDojo, or GitHub code scanning
$ trivy image --format sarif --output results.sarif registry.acme.io/checkout:1.8.2
$ trivy image --format json --output results.json registry.acme.io/checkout:1.8.2

# database lifecycle — matters for air-gapped and offline environments
$ trivy image --download-db-only                       # pre-warm the DB cache, no scan
$ trivy image --skip-db-update registry.acme.io/checkout:1.8.2   # don't touch the network at all
$ trivy image --offline-scan registry.acme.io/checkout:1.8.2      # scan using only what's already cached

# server mode — one shared cache for a whole CI fleet instead of every runner downloading its own
$ trivy server --listen 0.0.0.0:4954 &
$ trivy image --server http://trivy-server:4954 registry.acme.io/checkout:1.8.2

Exact subcommand and flag names have moved around more than once across Trivy's major versions — trivy config in particular has been reorganized as the project unified its CLI surface. If a tutorial's flags don't match what's installed, trivy --help and trivy <subcommand> --help are on the machine and current for the exact version running, which is the more reliable source than a blog post pinned to whichever release existed when it was written.

Gotchas and failure modes

☺ Like you're 10: Most of the surprises trace back to one of two things — the database has to come from somewhere over the network, or the thing you're scanning doesn't have the file Trivy needs to look at.

• Unauthenticated GHCR pulls have been rate-limited before. Because trivy-db ships as an OCI artifact from ghcr.io, a burst of CI runners all pulling anonymously at once has, in the past, tripped GitHub Container Registry's rate limits and broken builds with no code change involved — a real, widely reported operational incident, not a hypothetical. Authenticate the pull, run a shared trivy server so one warm cache serves a whole fleet instead of each runner downloading independently, or pre-bake the DB into your CI base image and pass --skip-db-update.
• Distroless and scratch images blind the OS-package path. Trivy's OS scanning depends on reading a real package manager's own database inside the image; an image with no apk/dpkg/rpm database at all — Google's distroless images, a scratch-based build — simply has no OS-level packages to enumerate that way. Language-dependency scanning is unaffected, since it reads lockfiles and binary metadata regardless of the base image, but don't read "clean OS scan" as proof the image has no OS-level exposure; it may mean there was nothing for that scanner to find in the first place.
• Default exit code is 0. Findings alone don't fail anything — --exit-code 1 combined with a --severity threshold is what turns a report into a gate. A pipeline that "runs Trivy" but never checks the exit code is running an expensive no-op.
• A lockfile has to survive into the layer being scanned. A multi-stage Dockerfile that installs dependencies in an earlier stage and copies only the compiled output or node_modules into the final image, without also copying package-lock.json, can leave Trivy with less to match against in that final stage than the build actually depends on. Scan the build context or an earlier stage directly if the final image is deliberately minimal.
• Misconfiguration IDs shift between the tfsec and Trivy eras. Since the engine merge, some checks carry an AVD-* ID where a team's older suppression comments still reference a tfsec-era ID. Most legacy IDs still resolve, but a fresh trivy config run against unfamiliar Terraform is worth cross-checking against current IDs before assuming an old .tfsec.yaml ignore list still covers everything it used to.

Where Trivy sits against Grype, Snyk, and standalone Checkov/tfsec

☺ Like you're 10: Every alternative trades Trivy's "does four jobs from one binary" for "does one job better" — which is the right trade depends entirely on which job matters most right now.

The real comparison is rarely "which tool is best" in the abstract — it's whether breadth from one binary or depth in one category is what a given pipeline stage actually needs.

A pipeline built around depth in one category and breadth everywhere else is a reasonable, common shape: Trivy as the universal, always-on gate covering four jobs adequately at every commit, with a narrower, deeper tool layered on top of exactly the one category where a team has decided the extra depth is worth paying for — Snyk's Fix PRs on the repositories where developers actually act on them, or Checkov's larger IaC policy set once Terraform coverage specifically becomes the priority. See vulnerability management & triage for how findings from more than one of these tools get deduplicated into a single backlog once a pipeline is running more than one at once.