nevaberry Trivy Knowledge Patch
Use this patch
Load this patch when a task involves recent Trivy CLI behavior, scanner output, analyzers, vulnerability matching, misconfiguration evaluation, SBOM or VEX handling, secret detection, client/server transport, or embedding Trivy as a library.
Before changing code or configuration:
- Determine the Trivy version used by the project, image, Helm release, or client/server pair.
- Identify the scan target and enabled scanners.
- Read the matching topic reference below.
- Treat report fields, package identities, defaults, and filtering behavior as compatibility-sensitive API surface.
- Prefer the installed version's schema, code, and tests if they disagree with this guidance.
Reference index
| Reference | Topics |
|---|---|
| CLI, reports, and runtime | Flags, defaults, configuration, server behavior, report identities, templates, and metadata |
| Dependencies and licenses | Language analyzers, lockfiles, dependency graphs, package identity, and license discovery |
| Images, registries, and operating systems | Image acquisition, histories and layers, OS detection, package vulnerability matching, and lifecycle data |
| Misconfiguration and infrastructure as code | Terraform, OpenTofu, CloudFormation, Azure, GCP, Kubernetes, Helm, Dockerfile, Rego, and check metadata |
| SBOM, VEX, and attestations | CycloneDX, SPDX, VEX discovery, attestations, graph preservation, and SBOM metadata |
| Secrets and filtering | Secret inspection, detector rules, ignore semantics, scan exclusions, and result filtering |
Breaking changes and migrations
Replace provider-mapping AVDID with ID
Misconfiguration provider mappings use ID rather than AVDID (since
0.69.0). Update custom mappings and consumers before upgrading:
# Old
AVDID: AVD-AWS-0001
# Current
ID: AVD-AWS-0001
Do not add a compatibility fallback that silently accepts both fields unless the application intentionally supports versions on both sides of the change. See Misconfiguration and infrastructure as code.
Migrate Docker configuration consumers to dockers_v2
The Docker configuration representation moved to dockers_v2 (since 0.72.0).
Any integration coupled to the previous representation must migrate its
decoding, traversal, and tests. See
Images, registries, and operating systems.
Account for the package-listing default
--list-all-pkgs defaults to true (since 0.67.0). Automation expecting the
older selective output must opt out explicitly:
trivy image --list-all-pkgs=false alpine:3.22
Expect package counts and downstream report processing to change when the flag is not pinned.
Stop passing filesystem skip flags to sbom
The sbom command disables --skip-dir and --skip-files (since 0.63.0).
Remove those flags from wrappers rather than assuming they still filter SBOM
inputs.
High-value CLI and report behavior
Select an OS or severity source explicitly
Use --distro when automatic operating-system detection is missing or
unsuitable (since 0.59.0). Use --vuln-severity-source to select the severity
authority (since 0.60.0):
trivy image --distro "<distribution>" alpine:3.20
trivy image --vuln-severity-source nvd alpine:3.20
Treat reports as identifiable artifacts
Recent reports can carry a UUIDv7 ReportID, vulnerability fingerprints, the
image reference, Git repository metadata, and the producing Trivy version.
Scan targets expose an ArtifactID whose calculation includes registry and
repository. Persist these fields as identifiers instead of reconstructing them
from display strings.
Repository URLs are sanitized before entering reports, cache hits preserve
repository metadata, and repository scans require the repository-aware
ROOTPATH behavior in SARIF. See
CLI, reports, and runtime.
Validate client/server assumptions
Server values are schema-validated. HTTP tracing is available, server mode sets up an HTTP transport, and client/server reports can include both Trivy and server versions. Transport now preserves dependency relationships, repository class, build information, check aliases, and query data where applicable.
If the client and server differ, test the serialized fields your integration uses rather than assuming local-mode parity.
Use concurrent database access deliberately
The vulnerability database supports concurrent access (since 0.68.0). If database contents disappear while metadata remains, Trivy downloads the database again instead of trusting the stale metadata (since 0.67.0).
High-value analyzer changes
Lockfile and workspace coverage
Dependency analysis understands Poetry v2, uv development and optional
dependencies, bun.lock, PEP 751 pylock.toml, multi-document pnpm lockfiles,
overlapping pnpm workspaces, Yarn workspace relationships, Cargo workspaces and
monorepos, and .deps.json dependency graphs. Do not flatten these inputs into
unrelated package lists; preserve root, workspace, relationship, and package-ID
information described in
Dependencies and licenses.
Preserve package provenance and identity
Detected packages may expose AnalyzedBy. POM package IDs incorporate GAV
coordinates and the root-POM path, pnpm uses the snapshot string as
Package.ID, nested JARs have per-file digests, and an OS override also updates
OS-package PURLs. Consumers should treat these emitted identities as canonical.
Follow Maven configuration
Java analysis can consume environment substitutions, repositories, proxies,
and mirrors from Maven settings.xml, plus configured mirrors from
trivy.yaml. HTTP 429 during remote POM resolution is fatal rather than a
partial success. Preserve dependency exclusions and inherited model data.
Keep license expressions intact
License handling distinguishes SPDX identifiers from expressions, preserves
WITH exceptions as part of one license, supports compound expressions, and
uses canonical SPDX identifiers. Avoid splitting an expression into unrelated
licenses or normalizing literal unlicensed to Unlicense.
High-value image and vulnerability behavior
Recognize expanded operating-system coverage
Recent analyzers cover Bottlerocket, MinimOS, AlmaLinux 10, Root.io images,
Photon 5.0, CoreOS SBOMs, Ubuntu 26.04 LTS, RapidFort curated images, and other
new lifecycle and package cases. RHEL-derived images can be recognized through
os-release, while third-party Debian and Ubuntu packages are excluded from
distribution vulnerability matching.
Preserve image origin information
Layer metadata is available to report consumers. Custom resources can be
attributed to their origin layer after layers are merged, Docker archives keep
RepoTags, and embedded-SBOM scans are deterministic. Image history handling
also normalizes legacy and non-BuildKit instruction forms.
Handle missing or driver-owned vulnerability data
Packages covered by a detector driver's own advisory feed are no longer
skipped. When vulnerability details are unavailable, results use UNKNOWN
severity. Embedders using ospkg.NewScanner can expect detector options to be
forwarded.
High-value IaC behavior
Evaluate Terraform and OpenTofu with full context
Terraform evaluation handles module instances, block instances, map-based
for_each, unknown dynamic iteration, cached remote modules, plan schema
recovery, and filesystem-function traversal boundaries. OpenTofu-specific file
extensions, module detection, and language blocks are recognized.
Apply ignores using current semantics
Inline ignores work for Dockerfiles and Helm content. Chart-subdirectory paths
are respected, ignore IDs are case-insensitive, and .trivyignore resolves
check aliases. An ignore-marker expression only applies when its value is both
known and non-null.
Preserve Rego diagnostics
Embedders can inject a Rego scanner. Policies can consume raw Terraform data, ignore findings by type, and use a configurable error limit. Diagnostic snippets include map keys, and check metadata interprets boolean values as booleans.
High-value SBOM, VEX, and secret behavior
Preserve SBOM structure
CycloneDX updates retain the source SBOM's structure, including applications,
OS packages, dependency graphs, file components, hashes, licenses, and build
metadata. SPDX handling tolerates documents without a root component and uses
NOASSERTION for non-library package license assertions.
Discover VEX from supported locations
VEX can be referenced by CycloneDX, stored within the scanned repository, or published as an OCI artifact through generic in-toto referrers. Apply repository-specific TLS settings, reject non-local repository names where required, and do not suppress vulnerabilities merely because a package graph loops.
Keep secret scanning transport-safe
Client/server analysis performs secret inspection. Secret inputs are validated as UTF-8 before protobuf transport, multiline locations use corrected line numbers, and configured skip folders, files, and extensions are honored. The scanner excludes its own configuration file and supports newer cloud, Maven, OpenAI API-key, and GitHub App token patterns.