Add and publish releases
Add each release to your Vulnlog file when you start working on it, and mark it as published when it ships. Entries and reports then refer to the right releases. So do OpenVEX documents, which tell your customers' tools whether a release is affected by a vulnerability.
Before you start
-
A Vulnlog file, for example
acme-shop.vl.yaml. To create one, see Create a Vulnlog file.
Add a release
-
Add the release at the end of
releases. Keep the list in order, oldest first, because--as-offollows this order. Leave outpublished_atuntil the release ships. -
List the artifacts of the release under
purls, each with its package URL (PURL) and tags. A PURL identifies a package and its version, for examplepkg:maven/com.acme/acme-shop-server@4.5.0. OpenVEX documents name the release by these PURLs. For the PURL of each kind of artifact, see Choose the PURL of each artifact.- id: 4.5.0 purls: - purl: "pkg:maven/com.acme/acme-shop-server@4.5.0" tags: [backend]The PURL of a container image contains its digest, so you add it once the image is built.
For all release fields, see Project and releases. For the tags, see Tag entries by component.
Publish a release
On the day the release ships, set published_at, and add the PURLs of artifacts that got their identity during the build, such as the container image:
- id: 4.4.0
published_at: 2026-11-07
purls:
- purl: "pkg:maven/com.acme/acme-shop-server@4.4.0"
tags: [backend]
- purl: "pkg:oci/acme-shop@sha256:350f97615163b67cbff8b015e60c77c2cbb954b4d9ffa9d48254e216e54899c8"
tags: [container]
The changelog shows a release without published_at as unreleased, and OpenVEX documents only cover published releases unless you name one with --release.
Choose the PURL of each artifact
A scanner applies an OpenVEX statement only if the statement’s product is the PURL that the scanner gives to what it scans. So use the PURL of the artifact your customers scan, written the way the scanner writes it.
With Trivy 0.76.2, statements apply to these artifacts:
| Artifact | What your customers scan | Release PURL |
|---|---|---|
Container image |
The image, with |
|
Go program |
The binary, built from a commit with a version tag, with |
|
.NET application |
The published output, which contains |
|
Maven project |
The project with its |
|
Python project with a |
The project |
|
npm, PyPI, or NuGet library |
Their own project, with |
|
To get the digest of an image after you push it, run docker inspect:
$ docker inspect --format '{{index .RepoDigests 0}}' ghcr.io/acme/acme-shop:4.4.0
ghcr.io/acme/acme-shop@sha256:350f97615163b67cbff8b015e60c77c2cbb954b4d9ffa9d48254e216e54899c8
The release PURL is then pkg:oci/acme-shop@sha256:350f97615163b67cbff8b015e60c77c2cbb954b4d9ffa9d48254e216e54899c8.
With Trivy 0.76.2, statements don’t apply when a scan sees the artifact in one of these ways:
-
An image named with a
pkg:dockerPURL. -
A JAR that contains its dependencies.
-
A project scanned from its
gradle.lockfile,requirements.txt, or its ownpackage-lock.json,poetry.lock, orpackages.lock.json, because these files don’t name the project. -
Installed packages in
node_modulesorsite-packageswithout a lock file. -
A Go module in the
go.modof another project. -
An image scanned from its software bill of materials (SBOM), the list of packages in the image, with
trivy sbom.
For a Gradle or npm application, publish it as a container image and use the image PURL. The statements then apply to every package in the image, including the libraries in a JAR.
If your customers scan the SBOM of the image, also list the PURL of your application under purls, with the same tag as the image.
Copy it from the SBOM.
trivy sbom then applies the statements to the dependencies of your application, but not to the operating system packages of the image.
This works only if the SBOM lists your application as a component with its dependencies under it.
A scanner other than Trivy can identify artifacts differently. To check that a document applies, scan the artifact with it. See Check the result.
Check the result
-
Validate the file:
$ vulnlog validate acme-shop.vl.yaml info: acme-shop.vl.yaml: releases[4.4.0]: Unreferenced release ID '4.4.0'. info: acme-shop.vl.yaml: releases[4.5.0]: Unreferenced release ID '4.5.0'. 2 infos Validated: acme-shop.vl.yamlAn
infoline about an unreferenced release only means that no entry refers to it yet. -
Fix what validation reports. A release whose
published_atis earlier than that of the release listed before it gives a warning:warning: acme-shop.vl.yaml: releases[4.4.0]: Release '4.4.0' published '2026-01-09' is declared after '4.3.0' published '2026-06-15'. Declare releases oldest first, because a release filter follows this order.
A release without
purlsgives a warning too, for example 4.5.0 without the PURLs from step 2:warning: acme-shop.vl.yaml: releases[4.5.0]: Release '4.5.0' declares no purls and is left out of VEX documents.