vulnlog vex openvex

OpenVEX output is incubating. Its options and output can change in a later release.

vulnlog vex openvex generates an OpenVEX document from a Vulnlog file. VEX (Vulnerability Exploitability eXchange) is a machine-readable statement of whether a vulnerability affects a product, and OpenVEX is one format for it. Scanners such as Trivy and Grype read OpenVEX documents.

Synopsis

vulnlog vex openvex <input> [--release <release-id>] [--tag <tag>]... [--baseline <path>] [-o <path>]

Arguments and options

Name Value Default Description

<input>

A Vulnlog file, or -

required

File to read. - reads it from stdin.

--release

A release ID

every published release

Write the document for this release only. The release doesn’t need a published_at date.

--tag

A tag ID

all tags

Keep only the entries and the release package URLs (PURLs) with this tag. Repeat the option to keep those with any of the tags.

--baseline

A file path

none

An OpenVEX document you published before, to continue. See Baseline.

-o, --output

A file path, or -

vex.json

File to write, in the current directory by default. - writes the document to stdout.

--release and --tag here aren’t the shared options in Filter options. For global options and standard input and output, see Global options and Standard input and output.

What the document covers

The document has statements for releases that declare purls, the PURLs of the artifacts you ship. Without --release, it covers every release with a published_at date. For release PURLs, see Project and releases.

An entry gets a statement for each covered release from the earliest release it lists through every later release in the file. The statement names the release PURLs that share a tag with the entry. An entry without tags, or with tags that no release PURL has, isn’t in the document. A release PURL without tags matches no entry.

A release without purls isn’t in the document, and the command prints a warning: line about it.

What a statement says

Entry status Also written

No verdict

under_investigation

analysis as status_notes

verdict: not affected

not_affected

justification, and analysis as impact_statement

verdict: affected

affected

analysis as status_notes, and an action_statement

Release in resolution.in and every later release

fixed

Nothing from analysis

The action_statement of an affected statement depends on disposition and resolution.in:

disposition resolution.in action_statement

none or will fix

A published release

Update to release <id>.

none or will fix

A release without published_at

A fix is planned for release <id>.

none

none

No remediation is available yet.

will fix

none

A fix is planned but not yet available.

wont fix

Any release

The risk is accepted for this release. A fix ships with release <id>.

wont fix

none

The risk is accepted. No fix is planned.

Each statement also carries the vulnerability ID, aliases, and description, and the packages of the entry as subcomponents of each product. name, severity, comment, and reports aren’t written.

A statement’s timestamp is the date its status became true:

  • fixed: resolution.at, or the published_at of the release in resolution.in.

  • A verdict: analyzed_at.

  • No verdict, or a verdict without analyzed_at: the earliest reports[].at.

The document’s author is project.author with project.contact in brackets. Each statement’s supplier is project.organization.

For the entry fields, see Vulnerabilities. For the justification values, see Verdicts and justifications.

Baseline

Each run without --baseline issues a new document, with a new @id and version 1.

With --baseline, the run continues that document:

  • @id stays the same.

  • If the content changed, version goes up by one and timestamp is the time of the run.

  • If nothing changed, the document stays as it is. When the output is the baseline file, the command prints Unchanged: <file> and doesn’t write it.

The baseline must exist and be an OpenVEX document, otherwise the command stops.

Exit codes

Code When

0

The document was written, or the baseline was unchanged.

1

A general error, the baseline can’t be read, or a path is a directory. For the general errors, see Exit codes.

2

The Vulnlog file doesn’t pass validation, or no statement applies, so no document is written.

5

--release or --tag names an unknown release or tag, or the baseline doesn’t exist or isn’t an OpenVEX document.

Examples

Write the document for the published releases of Acme Shop, 4.2.0 and 4.3.0, and show what it contains:

$ vulnlog -vv vex openvex acme-shop.vl.yaml
verbose: parsed acme-shop.vl.yaml: schema version 1, releases: 3, tags: 4, vulnerabilities: 6
verbose: releases without published_at are not part of the document: '4.4.0'
verbose: anchored on 2 releases with purls: '4.2.0' (2 purls), '4.3.0' (2 purls)
debug: skipped CVE-2021-23337: no release purl in scope shares one of its tags
verbose: collected 8 statements: 3 affected, 1 fixed, 3 not_affected, 1 under_investigation
Wrote: vex.json
verbose: wrote vex.json: openvex format, version 1, 8 statements

The lodash entry has the tag frontend, and no release PURL has it, so it isn’t in the document. This is the statement for the XZ Utils entry:

{
  "vulnerability": {
    "@id": "https://nvd.nist.gov/vuln/detail/CVE-2024-3094",
    "name": "CVE-2024-3094",
    "description": "Backdoor in the liblzma library of XZ Utils"
  },
  "timestamp": "2026-07-02T00:00:00Z",
  "products": [
    {
      "@id": "pkg:oci/acme-shop@sha256%3A23a5bff22a95119dc4bcef9422a20038eb3c2fd355f03928b02791273ff1cc27",
      "identifiers": {
        "purl": "pkg:oci/acme-shop@sha256%3A23a5bff22a95119dc4bcef9422a20038eb3c2fd355f03928b02791273ff1cc27"
      },
      "subcomponents": [
        {
          "@id": "pkg:deb/debian/xz-utils@5.4.1",
          "identifiers": {
            "purl": "pkg:deb/debian/xz-utils@5.4.1"
          }
        }
      ]
    }
  ],
  "status": "not_affected",
  "justification": "vulnerable_code_not_present",
  "impact_statement": "The container image is based on Debian 12, which ships xz-utils 5.4.1. The backdoor is only in the upstream releases 5.6.0 and 5.6.1.",
  "supplier": "Acme Corp"
}

Write the document for the container image of the unpublished release 4.4.0:

$ vulnlog vex openvex acme-shop.vl.yaml --release 4.4.0 --tag container -o vex-4.4.0-container.json
Wrote: vex-4.4.0-container.json

It has five statements, one for each entry with the tag container. Log4Shell is fixed, because its fix shipped in 4.3.0.

Continue the published document:

$ vulnlog vex openvex acme-shop.vl.yaml --baseline vex.json -o vex.json
Unchanged: vex.json

A scope that leaves no statement stops the command:

$ vulnlog vex openvex acme-shop.vl.yaml --release 4.4.0 --tag frontend
warning: releases without purls in scope are not part of the document: '4.4.0'
error: no statement applies
  hint: no vulnerability entry and release purl in scope share one of the requested tags