Vulnerability scanning

Active contributors: knqyf263, DmitriyLewen, afdesk

Purpose

Vulnerability scanning is Trivy's flagship feature. It detects known CVEs in:

• OS packages (Alpine, Debian, Ubuntu, RHEL, Rocky, Alma, Oracle, Amazon Linux, SUSE, Photon, Bottlerocket, CBL-Mariner, Wolfi, Chainguard).
• Language dependencies (Maven/Gradle, npm/yarn/pnpm/bun, pip/pipenv/poetry/uv, Go modules and binaries, Bundler, Cargo, NuGet, Composer, Conan, CocoaPods/Swift, Dart, Mix, Julia).
• Standalone binaries when they embed dependency metadata (Go binaries, Rust binaries, JARs).

Vulnerability data comes from the Trivy DB, which aggregates NVD, GitHub Security Advisories, distro-specific feeds (Red Hat, Debian, Ubuntu USN, Alpine secdb, etc.), and language-ecosystem feeds (npm, RubyGems, PyPI). The DB itself is built by the separate trivy-db project.

How it works

graph TD
    Walker[fanal walker] --> Analyzers[OS + language analyzers]
    Analyzers --> Blob[BlobInfo<br/>OS family + packages + applications]
    Blob --> Cache[(cache)]
    Cache --> Applier[applier.ApplyLayers]
    Applier --> Detail[ArtifactDetail]
    Detail --> OSScan[ospkg.Scanner]
    Detail --> LangScan[langpkg.Scanner]
    OSScan --> OSDetect[ospkg detectors<br/>pkg/detector/ospkg]
    LangScan --> LibDetect[library detectors<br/>pkg/detector/library]
    OSDetect --> DB[(Trivy DB)]
    LibDetect --> DB
    OSDetect --> Vulns[DetectedVulnerability]
    LibDetect --> Vulns
    Vulns --> VulnClient[vulnerability.Client<br/>fill metadata]
    VulnClient --> Result[types.Result Vulnerabilities]

The pipeline is split into discovery and detection:

1. Discovery (fanal). The walker runs OS and language analyzers, producing a list of installed packages per layer/snapshot.
2. Application (applier). Per-layer blobs are merged into a single ArtifactDetail that resolves overlays.
3. Detection (scan service). ospkg.Scanner and langpkg.Scanner consult the Trivy DB for each package, emitting DetectedVulnerability records.
4. Enrichment. vulnerability.Client fills in CVSS scores, references, and other metadata from the DB.
5. Filtering. Severity, fixed/unfixed status, and ignore lists filter the results.

Configuration

Flag	Purpose
--scanners vuln	Select vulnerability scanning (default; can be combined with others).
--severity	Filter by severity (UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL).
--ignore-unfixed	Drop vulnerabilities with no upstream fix.
--ignorefile	Path to .trivyignore.
--vuln-type	Restrict to os or library.
--detection-priority	precise (default) or comprehensive.
--pkg-types	Restrict to os/library.
--pkg-relationships	Filter by relationship (direct, indirect).

The .trivyignore file is a plain list of CVE IDs to suppress. For more nuanced suppression, use VEX.

OS detection

pkg/fanal/analyzer/os/ registers analyzers for each distro that produce a types.OS record (Family, Name, Eosl). The applier picks the highest-priority OS detected on the artifact. If none is found, the scanner logs a debug line and skips OS package scanning. EOSL (End of Service Life) is signaled when the distribution no longer ships security updates; Trivy logs a Warn when that happens (see pkg/scan/service.go).

Language detection

Each language has its own analyzer and detector pair:

Language	Analyzer	Detector
Go	gomod, gobinary	pkg/detector/library/golang/
Java	jar, pom, gradle-lockfile, sbt-lockfile	pkg/detector/library/maven/
Node.js	npm, yarn, pnpm, bun, node-pkg	pkg/detector/library/npm/
Python	pip, pipenv, poetry, uv, pylock, python-pkg	pkg/detector/library/python/
Ruby	bundler, gemspec	pkg/detector/library/bundler/
Rust	cargo, rustbinary	pkg/detector/library/cargo/
.NET	nuget, dotnet-core, packages-props	pkg/detector/library/nuget/
PHP	composer, composer-vendor	pkg/detector/library/composer/
Swift	swift, cocoapods	pkg/detector/library/swift/, cocoapods/
Dart	pubspec-lock	pkg/detector/library/pub/
Elixir	mix-lock	pkg/detector/library/hex/
Conda	conda-pkg, conda-environment	pkg/detector/library/conan/
Conan (C/C++)	conan-lock	pkg/detector/library/conan/
Julia	julia	pkg/detector/library/julia/

JAR archives that don't carry a manifest are matched against the Java DB by SHA-1 hash.

Output

Findings end up in types.Result.Vulnerabilities with fields like VulnerabilityID, PkgName, InstalledVersion, FixedVersion, Severity, Layer, and References. Renderers in pkg/report/ (table, JSON, SARIF, CycloneDX, SPDX, HTML, GitHub) all know how to format vulnerabilities.

Integration points

• fanal — OS and language analyzers.
• Scan service — runs the detectors.
• Database — vulnerability data source.
• VEX — post-scan filter.
• SBOM — vulnerabilities can be carried along with an SBOM.

Entry points for modification

• Add a language — implement an analyzer in pkg/fanal/analyzer/language/<lang>/ plus a parser in pkg/dependency/parser/<lang>/. Add a detector in pkg/detector/library/<lang>/.
• Add a distro — implement an OS analyzer in pkg/fanal/analyzer/os/<distro>/ and a detector in pkg/detector/ospkg/<distro>/.
• Change ignore behavior — pkg/result/result.go and pkg/result/policy.go (Rego-based filters).
• Add a metadata field — extend types.DetectedVulnerability in pkg/types/vulnerability.go and the renderers + RPC convert.

Key source files

File	Purpose
pkg/scan/local/service.go	Scan orchestration.
pkg/scan/ospkg/scanner.go	OS-package scanner.
pkg/scan/langpkg/scanner.go	Language-package scanner.
pkg/detector/ospkg/	Per-distro OS detectors.
pkg/detector/library/	Per-language library detectors.
pkg/vulnerability/vulnerability.go	DB query client.
pkg/types/vulnerability.go	DetectedVulnerability type.
pkg/types/report.go	Report.Results.Vulnerabilities.

See also

• VEX — exemption-aware filtering.
• SBOM — carry vulnerabilities with the SBOM.
• Database — what powers the lookups.