Agent Skills: Trivy Knowledge Patch

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:

1. Determine the Trivy version used by the project, image, Helm release, or client/server pair.
2. Identify the scan target and enabled scanners.
3. Read the matching topic reference below.
4. Treat report fields, package identities, defaults, and filtering behavior as compatibility-sensitive API surface.
5. 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.