An OpenVEX statement only changes a scanner’s output if its product, its subcomponents and the purls inside them match what the scanner found. In the go-vex library that Trivy v0.76.2 uses, the rules are short: the VEX purl is a pattern (no version means every version, and every qualifier it lists must be present), subcomponents narrow a statement to specific packages, and among matching statements the one with the newest timestamp wins. Most “VEX didn’t work” tickets come down to one of those three.

This article is about the identifiers and the matching. For what the statuses and justifications mean, see VEX explained. For converting CycloneDX VEX to OpenVEX, see the CycloneDX VEX mapping. For CSAF’s product tree, see CSAF VEX product_tree.

Products and subcomponents in the spec

The OpenVEX specification v0.2.0 defines a product as “a logical unit representing a piece of software”, broad enough that “anything that can be described in a Software Bill of Materials (SBOM) can be thought of as a product.” A subcomponent is “any components possibly included in the product where the vulnerability originates.” The spec adds that subcomponents “SHOULD also list software identifiers and they SHOULD also be listed in the product SBOM.”

Products and subcomponents share one structure, which the spec calls Component:

All three identifying fields are optional, but the spec says a valid statement “MUST identify a product.” It also says the product should list “as many software identifiers as possible to help VEX processors when matching the product.”

products itself is optional in a statement because it can be inherited from an encapsulating document, such as the subject of an in-toto attestation. Timestamps can be inherited too. The spec’s inheritance rules are: a statement timestamp overrides the document timestamp, which overrides the encapsulating document’s; a product ID in a statement overrides product data in the encapsulating document.

How go-vex matches a statement

Trivy loads OpenVEX documents with openvex/go-vex, pinned to v0.2.9 in Trivy v0.76.2’s go.mod. Its matching code is small enough to read in full. For a finding (CVE, product, optional subcomponent), a statement matches when all of these hold:

1. Vulnerability. The CVE ID equals the statement’s vulnerability.name, its @id, or one of its aliases.
2. Product. One entry in products matches the product identifier. A component matches if its @id equals the identifier exactly, or its @id is a purl that matches by the purl rules below, or any value in identifiers equals it (with purl matching for the purl key), or any value in hashes equals it.
3. Subcomponent. If that product entry has no subcomponents, or the caller passed no subcomponent, the product match is enough. Otherwise one listed subcomponent must match the subcomponent identifier by the same component rules.

The purl rules

go-vex’s PurlMatches(purl1, purl2) treats the VEX purl as the general one and the scanned purl as the specific one:

The function’s own comment says “Purl version ranges are not supported yet.” A statement covering versions 1.0 to 1.4 needs either one purl per version or no version at all. Leaving the version off is the broadest possible statement, so use it only when you mean every version. Trivy’s documentation notes that these matching rules come from a community discussion, not from the purl specification.

Which statement wins

go-vex collects every matching statement and sorts them by timestamp, using the document timestamp for any statement without its own. Trivy takes the last one. It removes the finding only if that statement’s status is not_affected or fixed; affected and under_investigation leave the finding in the report.

This is why the spec’s update example keeps the original document timestamp on the first statement when a second one is added. If you edit a document, bump timestamp and version at the document level, and the old statements lose their original time, the ordering of statements for the same CVE can change.

A tested example

The document below has two statements for CVE-2024-32002 on a container image (the first under_investigation with its own timestamp, the second not_affected inheriting the newer document timestamp) and one statement for a Go service. It validates against the OpenVEX JSON schema (openvex_json_schema.json from the spec repository, checked with Python jsonschema).

{
  "@context": "https://openvex.dev/ns/v0.2.0",
  "@id": "https://example.com/vex/app-2026-11-06",
  "author": "Example Security Team <security@example.com>",
  "timestamp": "2026-11-06T09:00:00Z",
  "version": 2,
  "statements": [
    {
      "vulnerability": {"name": "CVE-2024-32002"},
      "timestamp": "2026-11-01T10:00:00Z",
      "products": [
        {
          "@id": "pkg:oci/app?repository_url=ghcr.io%2Facme%2Fapp",
          "subcomponents": [{"@id": "pkg:apk/alpine/git"}]
        }
      ],
      "status": "under_investigation"
    },
    {
      "vulnerability": {"name": "CVE-2024-32002"},
      "products": [
        {
          "@id": "pkg:oci/app?repository_url=ghcr.io%2Facme%2Fapp",
          "subcomponents": [{"@id": "pkg:apk/alpine/git"}]
        }
      ],
      "status": "not_affected",
      "justification": "vulnerable_code_not_in_execute_path",
      "status_notes": "git is installed for build-time use only; the runtime entrypoint never invokes git clone."
    },
    {
      "vulnerability": {"name": "CVE-2023-0001"},
      "products": [
        {
          "@id": "pkg:golang/example.com/svc@v1.4.0",
          "subcomponents": [{"@id": "pkg:golang/golang.org/x/net@v0.17.0"}]
        }
      ],
      "status": "not_affected",
      "justification": "vulnerable_code_not_present"
    }
  ]
}

The image, service names and CVE-2023-0001 statement are illustrative. To check the matching without a registry or a real image, we wrote a Python port of go-vex v0.2.9’s PurlMatches, Component.Matches, Product.Matches, Statement.Matches and timestamp sort, using the packageurl-python parser, and ran it with Python 3 against the document. It is a port, not the Go library itself, so treat it as a reading aid. Output, with long purls shortened:

product                                    subcomponent                          result
pkg:oci/app?repository_url=…%2Fapp         pkg:apk/alpine/git@2.43.0-r0?arch=…   2 matches, effective=not_affected
pkg:oci/app?repository_url=…%2Fapp         pkg:apk/alpine/git-daemon@2.43.0-r0   no match
pkg:oci/app?repository_url=…%2Fapp         (none)                                2 matches, effective=not_affected
pkg:oci/app                                pkg:apk/alpine/git@2.43.0-r0          no match
pkg:oci/app?repository_url=…%2Fapp&tag=v2  pkg:apk/alpine/git@2.43.0-r0          2 matches, effective=not_affected
pkg:golang/example.com/svc@v1.4.0          pkg:golang/golang.org/x/net@v0.17.0   1 match,  effective=not_affected
pkg:golang/example.com/svc@v1.5.0          pkg:golang/golang.org/x/net@v0.17.0   no match
pkg:golang/example.com/svc@v1.4.0          pkg:golang/golang.org/x/net@v0.18.0   no match

What the rows show:

• Row 1: the versionless pkg:apk/alpine/git subcomponent covers the installed git@2.43.0-r0. Both statements match, and the not_affected one wins because it inherits the later document timestamp.
• Row 2: git-daemon is a different package name, so the statement does not cover it, even though it ships from the same source.
• Row 3: with no subcomponent passed, the product match alone is enough. Trivy does not hit this case for an image root (see below), but other consumers of go-vex may.
• Rows 4 and 5: the repository_url qualifier on the VEX side must be present on the scanned side. A scan purl without it fails; one with an extra tag qualifier passes.
• Rows 6 to 8: pinned versions on both product and subcomponent mean a new service release (v1.5.0) or a dependency bump (x/net v0.18.0) silently drops the statement. That is often what you want, since the reachability analysis was for that build, but it means the document needs updating each release.

How Trivy applies it to a dependency tree

Trivy’s VEX guide and its filterVulnerabilities code show how it feeds this matcher. For each finding it first asks whether the vulnerable package itself is a not-affected product (no subcomponent). If not, it walks up the dependency graph from the vulnerable package and asks, for each parent, whether “parent as product, vulnerable package as subcomponent” is not affected. The finding is removed only if no path reaches the root without passing a not-affected node.

Two consequences:

• A statement on an intermediate dependency can suppress a finding, but only if every path goes through it. Trivy’s documentation gives the example of Module C reached through both B and D: a VEX statement for B does not suppress the finding, because D might still be affected.
• A statement on the image with no subcomponents suppresses the CVE in every package in that image. Trivy’s docs call this out and recommend subcomponents for “reducing the risk of incorrect filtering.”

Trivy needs a purl on the scanned side. Its OpenVEX matcher returns nothing when the product has no purl, so cpe-only or hash-only VEX products are not matched by Trivy even though the spec allows them. Use the purls Trivy prints in its JSON report.

Writing statements that match

These are our recommendations, based on the rules above:

1. Copy purls from the scanner or SBOM output. Do not type them by hand; the type, namespace and name must match exactly. Our guide to CVE packageURL and SBOM purls covers common purl pitfalls.
2. Always add subcomponents for image-level or application-level products. A product with no subcomponents is a blanket statement.
3. Add a version only when the claim depends on the build. Reachability claims (vulnerable_code_not_in_execute_path) usually do. “This package never ships the vulnerable file” claims may not.
4. Be sparing with qualifiers in the VEX purl. Each one is a requirement. arch is useful if only one architecture is unaffected; otherwise leave it out.
5. Keep timestamps on old statements when you append new ones, and bump the document version. Use status_notes to record how the status was determined. Trivy does not read it, but reviewers do.
6. Track the result. Our prioritization workflow shows where a VEX decision sits between the CVE record and the ticket.

Limits of this article

• Matching behaviour is from go-vex v0.2.9 and Trivy v0.76.2 source and docs. Grype, vexctl and commercial scanners have their own matchers and may differ.
• Our test used a Python port of the go-vex rules, not the Go library or a Trivy scan. The port follows the source shown in the references; differences in purl parsing between packageurl-python and packageurl-go are possible for unusual purls.
• We did not cover OpenVEX attestations attached to OCI images (--vex oci) or VEX repositories.

Sources and verification

Scope. This is a specification explainer with measurements from public data. We read the CVE Record Format schema on the CVEProject/cve-schema main branch (default dataVersion 5.2.0), RFD 0002 in the same repository, and the Package URL specification in the package-url/purl-spec repository. We counted fields across every record in the cvelistV5 release cve_2026-11-05_0400Z (the “all CVEs at midnight” bundle for 5 November 2026) with Python 3.13, and ran the join script below against that data. The script is illustrative.

The short answer

Since CVE Record Format 5.2.0, each entry in a record’s affected array can carry a packageURL:

{
  "vendor": "fast-uri",
  "product": "fast-uri",
  "packageURL": "pkg:npm/fast-uri",
  "defaultStatus": "unaffected",
  "versions": [
    {"versionType": "semver", "status": "affected", "version": "2.4.2", "lessThan": "2.4.8"}
  ]
}

That fragment is from CVE-2026-110180 (trimmed to its first version range). Three rules decide how you use it:

1. No version in the purl. The schema says the Package URL “MUST NOT include a version”. Strip the version from your SBOM purl before you look it up.
2. The versions array still decides. A purl match finds the records about your package. Whether your version is affected comes from versions and defaultStatus, read with the record’s versionType.
3. It is optional and still rare. 1.6% of published records carry it today, from 12 CNAs. Treat it as a fast, precise path where it exists, and keep your CPE and name-based matching for the rest.

What the schema says

The field definition in the 5.2.0 schema:

“A Package URL, a unified URL specification for identifying packages hosted by known package hosts. The Package URL MUST NOT include a version.”

The schema types it as a URI and lists examples such as pkg:deb/debian/curl?arch=i386&distro=jessie, pkg:npm/%40angular/animation and pkg:golang/google.golang.org/genproto#googleapis/api/annotations. So qualifiers and subpaths are allowed; only the version is out.

packageURL does not satisfy the identifier requirement on its own. The product definition still requires either vendor and product or collectionURL and packageName, plus either versions or defaultStatus. In our scan, every one of the 7,324 entries with a purl also had one of those identifier pairs.

Why it was added

RFD 0002, “Supporting Package URLs in CVE”, is the design record. It argues that the existing identifier fields “are of limited value for automated applicability matching” and that Package URLs “are better suited than CPEs for capturing distinctions between different distributions of particular open source software”.

Two design choices in the RFD matter to consumers:

• Validation is mostly outside the schema. The JSON schema only checks that the value is a URI; the RFD says it “would be further constrained by CVE Services” to ensure the values are valid purls, because encoding purl rules in a regular expression “would be excessive and difficult to maintain”. Do not assume the schema has validated purl syntax for you.
• Versions live in one place. “All version information should only be included within the existing versions field.” That keeps one version-matching code path for consumers.

The cve-schema repository tags v5.2.0; the tagged commit is dated 3 September 2025. Records that declare dataVersion 5.1 cannot use the field. In our snapshot, 144,619 published records (36.1%) declared 5.2 and 255,826 declared 5.1.

What the data shows

We read every record in the 5 November 2026 bundle: 400,445 published and 18,890 rejected. Only CNA containers carried the field; no ADP container had a packageURL.

Who writes it

VulnCheck accounts for 78.8% of records with a purl. If you build matching around this field, most of your hits will come from one CNA’s conventions, so test against its records.

Which purl types

The most common types across the 7,324 entries: github 2,371, npm 1,729, pypi 805, maven 533, golang 498, composer 314, hex 309, cargo 242, cpan 210, otp 82, software-id 72, nuget 40, gem 31, generic 31.

Two of those need care:

• pkg:github identifies a source repository, not a registry package. VulnCheck wrote 1,917 of the GitHub entries and EEF 413. Your SBOM will usually describe the same software as pkg:npm/... or pkg:pypi/..., so a pkg:github record will not match it directly. You need a mapping from repository to registry package, or a fallback on collectionURL and packageName.
• pkg:software-id appears 72 times (for example pkg:software-id/erlang.org/otp), but the purl-spec decision record that registers it, dated 21 October 2026, still has the status “proposed”. Expect parsers to reject it until the type is registered.

How fast it is growing

By the month each record was first published (as the records stand today, so later updates are included):

October’s 2,000 are 11.7% of the 17,058 records first published that month.

Normalize before you join

The purl specification makes the type case-insensitive with lowercase as the canonical form, and some types go further. The type definitions say a GitHub namespace and name are “not case sensitive and shall be lowercased”, and a PyPI name “shall be lowercased and underscore _ replaced with a dash -”. npm names are case-sensitive.

CVE records do not always follow those rules:

• 756 of the 2,371 pkg:github entries (31.9%) contain uppercase letters, for example pkg:github/Finsys/dockhand.
• 9 pkg:pypi entries have uppercase letters and 24 contain an underscore.
• GitPython is a concrete case. In the 34 records we found for it, 28 use pkg:pypi/gitpython and 6 use pkg:pypi/GitPython. An exact string join misses one set or the other, depending on how your SBOM tool spells it.

So normalize both sides the same way before comparing: lowercase the type; lowercase github and pypi paths; replace _ with - for pypi; drop the version and qualifiers from the SBOM purl. Leave npm, Maven and other case-sensitive types alone.

A tested join

Two scripts. The first builds an index from the cvelistV5 bundle; the second joins a CycloneDX SBOM to it and applies the versions ranges.

#!/usr/bin/env python3
"""build_index.py: index CNA affected[] entries that carry packageURL,
keyed by a normalized purl (no version, no qualifiers)."""
import json, sys, zipfile

def norm(purl):
    core = purl.split("#")[0].split("?")[0]
    if "@" in core.rsplit("/", 1)[-1]:                 # drop a version (SBOM side)
        core = core.rsplit("@", 1)[0]
    scheme, rest = core.split(":", 1)
    ptype, _, path = rest.partition("/")
    ptype = ptype.lower()
    if ptype in ("github", "pypi"):                     # case-insensitive types per purl-spec
        path = path.lower()
    if ptype == "pypi":
        path = path.replace("_", "-")
    return f"pkg:{ptype}/{path}"

def main(zip_path, out_path):
    z = zipfile.ZipFile(zip_path)
    with open(out_path, "w") as out:
        for n in z.namelist():
            if not n.endswith(".json") or "/CVE-" not in n:
                continue
            rec = json.loads(z.read(n))
            meta = rec["cveMetadata"]
            if meta.get("state") != "PUBLISHED":
                continue
            for a in rec["containers"].get("cna", {}).get("affected", []):
                if a.get("packageURL"):
                    out.write(json.dumps({"key": norm(a["packageURL"]), "cve": meta["cveId"],
                        "defaultStatus": a.get("defaultStatus"), "versions": a.get("versions", [])}) + "\n")

if __name__ == "__main__":
    main(sys.argv[1], sys.argv[2])

#!/usr/bin/env python3
"""join_sbom.py: join CycloneDX component purls to the CVE packageURL index, then apply versions[] ranges.
Illustrative: only semver-like versionType values are compared; everything else is flagged for review."""
import json, sys
from packaging.version import Version, InvalidVersion
from build_index import norm

def status_for(ver, entry):
    try:
        v = Version(ver)
    except InvalidVersion:
        return "review: unparseable version"
    for r in entry["versions"]:
        if r.get("versionType") not in ("semver", "maven", "python", None):
            return f"review: versionType={r.get('versionType')}"
        try:
            lo = Version(r["version"]) if r["version"] not in ("0", "*") else Version("0")
            if "lessThan" in r:
                inside = lo <= v < Version(r["lessThan"])
            elif "lessThanOrEqual" in r:
                inside = lo <= v <= Version(r["lessThanOrEqual"])
            else:
                inside = v == lo
        except InvalidVersion:
            return "review: unparseable range"
        if inside:
            return r["status"]
    return entry.get("defaultStatus") or "unknown"

def main(index_path, sbom_path):
    index = {}
    for line in open(index_path):
        e = json.loads(line)
        index.setdefault(e["key"], []).append(e)
    for c in json.load(open(sbom_path))["components"]:
        for e in index.get(norm(c["purl"]), []):
            print(f'{c["purl"]}\t{e["cve"]}\t{status_for(c["version"], e)}')

if __name__ == "__main__":
    main(sys.argv[1], sys.argv[2])

Test run

python3 build_index.py cves.zip purl-index.jsonl took about 30 seconds and wrote 7,324 lines, one per entry. We then ran python3 join_sbom.py purl-index.jsonl sbom.cdx.json (packaging 26.3) with a three-component CycloneDX 1.6 SBOM:

GitPython 3.1.62 comes out affected by the six records whose ranges end at lessThan: 3.2.0, and unaffected by the 28 whose fixes landed at or before 3.1.62. Without normalization, the SBOM spelling GitPython would have matched 6 records and missed 28. The ?type=jar qualifier on the Maven purl is dropped before lookup.

What this does not handle: versionType values such as custom, git or distribution schemes (it flags them for review), changes arrays inside version ranges, purl types that need a repository-to-package mapping, and the order sensitivity of overlapping ranges. The CVE affected versions guide covers those rules in detail.

When the CVE has no purl

For the other 98% of records, you still need the older paths. The cpeApplicability explainer covers CPE-based matching, and collectionURL plus packageName is often enough to build a purl yourself: https://www.npmjs.com/package/x with packageName x is pkg:npm/x. Record which path produced each match, because a purl match and a name match deserve different confidence.

A match is only the start of the patch decision. In our vulnerability prioritization workflow, the purl join is the “does this apply to us” step; KEV, EPSS and SSVC decide how fast. If your supplier also ships VEX, apply it after the join; our CSAF VEX guide shows how to resolve its product IDs to purls.

Limits of this article

The counts describe one snapshot (the 5 November 2026 midnight bundle); CNAs update records, so the numbers will move. Month counts use each record’s original datePublished, so a purl added later to an old record is counted in the month the record was first published. We checked purl spelling only for the github and pypi rules; other types have their own normalization rules we did not test. We did not check how CVE Services validates purls at submission time. The join script uses Python’s packaging version ordering, which is close to, but not the same as, every ecosystem’s own ordering.

Sources and verification

Scope. This is a field-level guide for engineers who consume vendor CSAF VEX files and need to apply them to their own SBOMs. We read the CSAF 2.0 prose and JSON schema in the OASIS CSAF TC’s GitHub repository, Red Hat’s July 2024 announcement of its CSAF VEX files, and Trivy’s CSAF matcher and documentation at tag v0.76.1. The example document and the Python script below are ours; we validated the document against the CSAF 2.0 JSON schema and ran the script with Python 3.13. The script is illustrative, not a production matcher.

The short answer

A CSAF VEX file never puts a purl next to a status. It says “product ID GW-4.2.1:LIB-1.8.0 is known_not_affected”, and you have to work out what that ID is:

1. Find the ID in the product_tree: at the end of a branches path, in full_product_names, or as the full_product_name of a relationships entry.
2. If it is a relationship, resolve both sides: product_reference (the component) and relates_to_product_reference (the product it sits in).
3. Read product_identification_helper.purl (or cpe) for each side.
4. Apply the status only when your SBOM contains the component and the parent matches the product you are assessing.
5. Collapse the eight product_status lists to the four VEX answers before you write anything to a ticket.

The rest of this article goes through each step, shows a schema-valid example, and gives a script that does the join.

What the VEX profile requires

CSAF 2.0 has been an OASIS Standard since 18 November 2022. The VEX profile is section 4.5. A document satisfies it when /document/category is csaf_vex and it contains:

• a product_tree “which lists all products referenced later on in the CSAF document regardless of their state”;
• vulnerabilities, each with notes and at least one of cve or ids;
• at least one of the fixed, known_affected, known_not_affected or under_investigation lists.

Two conditions are per product, and they are the ones consumers should check:

• Every product in known_not_affected needs an impact statement, either “as machine readable flag in /vulnerabilities[]/flags or as human readable justification in /vulnerabilities[]/threats” with category set to impact.
• Every product in known_affected needs “additional product specific information” in remediations “as an action statement”. The categories no_fix_planned and none_available count.

The five flag labels are the CISA justification codes: component_not_present, vulnerable_code_not_present, vulnerable_code_cannot_be_controlled_by_adversary, vulnerable_code_not_in_execute_path and inline_mitigations_already_exist. If you need the meaning of each one, the VEX explainer covers them. The CycloneDX VEX mapping guide covers converting between CSAF and other VEX formats. This article is about something they do not cover: finding the products a CSAF statement actually refers to.

Step 1: walk the product tree

The product_tree can name products in three places. A consumer has to read all three.

Every one of these is a “full product name”: name and product_id are required, and product_identification_helper is optional. That helper is where purl, cpe, hashes and SBOM URLs go. The CSAF schema only checks the purl against a loose pattern (^pkg:[A-Za-z\.\-\+][A-Za-z0-9\.\-\+]*/.+) and says it “does not completely evaluate whether a PURL is valid”, so validate purls yourself before matching on them.

There is also product_groups, which bundles product IDs under a group ID. Product status lists only hold product IDs, but flags, threats and remediations can reference groups through group_ids, so expand groups when you collect impact and action statements.

The spec recommends the vendor → product_name → product_version shape “whenever possible to support the identification and matching of products on the consumer side”. It also allows product_version_range branches, but recommends enumerating versions instead. If you meet a range branch, you need a version-range parser for whatever scheme it uses; the purl join below will not help.

Step 2: treat relationships as “component in product”

A relationship has four required fields: category, product_reference, relates_to_product_reference and full_product_name. The categories are default_component_of, external_component_of, installed_on, installed_with and optional_component_of. The spec gives the reason relationships exist: a product may be “vulnerable only when installed together with another”, or you may need “to describe operating system components”.

This is the part consumers get wrong. In our example below, LIB-1.8.0 is the library on its own and GW-4.2.1:LIB-1.8.0 is “libexample 1.8.0 as shipped in Example Gateway 4.2.1”. A vendor that marks the second ID known_not_affected is saying the gateway does not reach the vulnerable code. It is not saying libexample 1.8.0 is safe everywhere. If your matcher resolves the relationship ID to the component purl alone, you will suppress the CVE for every other image that ships libexample 1.8.0. That is the false negative VEX is supposed to prevent.

The rule we use: for a relationship ID, apply the status only when the component purl matches a component in the SBOM and the parent purl matches the SBOM’s subject (for CycloneDX, metadata.component).

Red Hat’s VEX files are a real case of this structure. Red Hat publishes one CSAF VEX file per CVE. Its July 2024 announcement says each file has a product_tree object listing “products, their components, and the relationships between them”. In the general-availability release Red Hat “extended the scope of the purl identifiers to unfixed components as well” for rpm, oci and rpmmod components. In the October 2023 beta, only fixed components carried a purl. Check which one you are parsing.

Step 3: collapse eight status lists into four answers

CSAF defines eight product_status lists. VEX consumers need four answers. The spec’s own test for contradicting statuses (section 6.1.6) gives the grouping, and the sets “MUST be pairwise disjoint” within one vulnerability:

If you find one product ID in two groups for the same CVE, the document fails the CSAF mandatory test. Reject the statement for that product rather than picking one.

For affected products, the remediation categories tell you what kind of action is available: vendor_fix, workaround, mitigation, none_available or no_fix_planned. vendor_fix cannot be combined with none_available or no_fix_planned for the same product.

A schema-valid example

This document is ours, written for this article. It has one product version where a library is not reachable and a later version where it was updated. It passes validation against the CSAF 2.0 JSON schema from the OASIS repository (Python jsonschema, Draft 2020-12, format checks on; 0 errors). Schema validation does not run CSAF’s mandatory tests, so it does not prove the profile rules are met. We checked those by hand.

{
  "document": {
    "category": "csaf_vex",
    "csaf_version": "2.0",
    "publisher": {"category": "vendor", "name": "Example Vendor", "namespace": "https://vendor.example"},
    "title": "Example Gateway: CVE-2099-0001 in libexample",
    "tracking": {"id": "EXV-2099-0001", "status": "final", "version": "2", "...": "..."}
  },
  "product_tree": {
    "branches": [{"category": "vendor", "name": "Example Vendor", "branches": [
      {"category": "product_name", "name": "Example Gateway", "branches": [
        {"category": "product_version", "name": "4.2.1",
         "product": {"name": "Example Gateway 4.2.1", "product_id": "GW-4.2.1",
           "product_identification_helper": {"purl": "pkg:oci/example-gateway@sha256%3A1111?tag=4.2.1"}}}
      ]},
      {"category": "product_name", "name": "libexample", "branches": [
        {"category": "product_version", "name": "1.8.0",
         "product": {"name": "libexample 1.8.0", "product_id": "LIB-1.8.0",
           "product_identification_helper": {"purl": "pkg:deb/debian/libexample@1.8.0-1"}}}
      ]}
    ]}],
    "relationships": [
      {"category": "default_component_of",
       "product_reference": "LIB-1.8.0",
       "relates_to_product_reference": "GW-4.2.1",
       "full_product_name": {"name": "libexample 1.8.0 in Example Gateway 4.2.1",
                             "product_id": "GW-4.2.1:LIB-1.8.0"}}
    ]
  },
  "vulnerabilities": [{
    "cve": "CVE-2099-0001",
    "notes": [{"category": "description", "text": "Illustrative vulnerability in libexample's XML parser."}],
    "product_status": {"known_not_affected": ["GW-4.2.1:LIB-1.8.0"], "fixed": ["GW-4.3.0:LIB-1.8.2"]},
    "flags": [{"label": "vulnerable_code_not_in_execute_path", "product_ids": ["GW-4.2.1:LIB-1.8.0"]}],
    "threats": [{"category": "impact", "details": "Example Gateway never calls the XML parser in libexample.",
                 "product_ids": ["GW-4.2.1:LIB-1.8.0"]}]
  }]
}

The excerpt trims the tracking block and the 4.3.0 / 1.8.2 branches and relationship, which follow the same pattern. The CVE ID is a placeholder.

Step 4: join to the SBOM

The script resolves every product ID in product_status to purls, follows relationships, and checks both sides against a CycloneDX SBOM. For purl comparison it uses the matching rules Trivy documents, which Trivy itself notes “are not formally defined within the current official PURL specification”: a VEX purl without a version matches every version; every qualifier in the VEX purl must be present in the SBOM purl; extra SBOM qualifiers are ignored.

#!/usr/bin/env python3
"""Resolve CSAF VEX product_status entries to purls and join them to a CycloneDX SBOM.
Illustrative: purl matching follows the rules in purl_match(); no version-range logic."""
import json, sys
from urllib.parse import unquote

def parse(p):
    """Split a purl into (type/namespace/name, version or None, qualifiers dict). Subpath ignored."""
    p = p.split("#")[0]
    core, _, q = p.partition("?")
    quals = dict(kv.split("=", 1) for kv in q.split("&") if "=" in kv)
    path, _, ver = core.rpartition("@") if "@" in core.rsplit("/", 1)[-1] else (core, "", "")
    return unquote(path).lower(), unquote(ver) or None, {k.lower(): unquote(v) for k, v in quals.items()}

def purl_match(vex_purl, sbom_purl):
    """Community matching rules (as documented by Trivy): a VEX purl without a version matches
    every version; VEX qualifiers must all be present in the SBOM purl; extra SBOM qualifiers are ignored."""
    vp, vv, vq = parse(vex_purl)
    sp, sv, sq = parse(sbom_purl)
    return vp == sp and (vv is None or vv == sv) and all(sq.get(k) == v for k, v in vq.items())

def walk_branches(branches, out):
    for b in branches or []:
        if "product" in b:
            fpn = b["product"]
            out[fpn["product_id"]] = fpn.get("product_identification_helper", {}).get("purl")
        walk_branches(b.get("branches"), out)

def load_products(doc):
    tree = doc["product_tree"]
    purls = {}
    walk_branches(tree.get("branches"), purls)
    for fpn in tree.get("full_product_names", []):
        purls[fpn["product_id"]] = fpn.get("product_identification_helper", {}).get("purl")
    rels = {}
    for r in tree.get("relationships", []):
        rels[r["full_product_name"]["product_id"]] = (
            r["category"], r["product_reference"], r["relates_to_product_reference"])
    groups = {g["group_id"]: g["product_ids"] for g in tree.get("product_groups", [])}
    return purls, rels, groups

def main(vex_path, sbom_path):
    doc = json.load(open(vex_path))
    assert doc["document"]["category"] == "csaf_vex", "not a VEX profile document"
    purls, rels, groups = load_products(doc)
    sbom = json.load(open(sbom_path))
    parent = sbom["metadata"]["component"]["purl"]
    inventory = [c["purl"] for c in sbom.get("components", []) if c.get("purl")]
    in_sbom = lambda vex_purl: any(purl_match(vex_purl, s) for s in inventory)

    for v in doc["vulnerabilities"]:
        flags = {pid: f["label"] for f in v.get("flags", [])
                 for pid in f.get("product_ids", []) + sum((groups[g] for g in f.get("group_ids", [])), [])}
        for status, pids in v.get("product_status", {}).items():
            for pid in pids:
                if pid in rels:                      # component-in-product: match BOTH sides
                    cat, comp, prod = rels[pid]
                    comp_p, prod_p = purls.get(comp), purls.get(prod)
                    hit = bool(comp_p and prod_p and purl_match(prod_p, parent) and in_sbom(comp_p))
                    target = f"{comp_p} {cat} {prod_p}"
                else:                                # standalone product
                    p = purls.get(pid)
                    hit = bool(p and (in_sbom(p) or purl_match(p, parent)))
                    target = p
                print(f"{v.get('cve')}\t{status}\t{flags.get(pid, '-')}\t{'MATCH' if hit else 'no match'}\t{target}")

if __name__ == "__main__":
    main(*sys.argv[1:3])

Test run

We ran it (python3 -I csaf_vex_join.py vex.json sbom.cdx.json) against the full example document and three small CycloneDX 1.6 SBOMs.

SBOM 1, image 4.2.1 (metadata.component.purl = pkg:oci/example-gateway@sha256%3A1111?tag=4.2.1), containing pkg:deb/debian/libexample@1.8.0-1?arch=amd64&distro=debian-12:

CVE-2099-0001  known_not_affected  vulnerable_code_not_in_execute_path  MATCH     pkg:deb/debian/libexample@1.8.0-1 default_component_of pkg:oci/example-gateway@sha256%3A1111?tag=4.2.1
CVE-2099-0001  fixed               -                                    no match  pkg:deb/debian/libexample@1.8.2-1 default_component_of pkg:oci/example-gateway@sha256%3A2222?tag=4.3.0

The SBOM’s extra arch and distro qualifiers did not block the match, because the VEX purl has none.

SBOM 2, image 4.3.0 with libexample 1.8.2: the results flip. The fixed statement matches and the known_not_affected one does not.

SBOM 3, the 4.2.1 SBOM again, but with the VEX component purl changed to ...libexample@1.8.0-1?arch=arm64: no match, because the VEX purl now requires a qualifier value the SBOM lacks.

What the script does not do: version ranges (product_version_range), CPE-only products, hashes, product_groups in status lists (the schema does not allow them there), or the mandatory-test checks. It also prints matches and nothing else; it does not decide what to do with a CVE your scanner found but the VEX file does not mention.

How Trivy applies CSAF VEX

Trivy is a common place engineers first meet CSAF VEX. At tag v0.76.1, its documentation says CSAF works for container images, filesystems, code repositories, VM images, Kubernetes and SBOM targets, passed with --vex. Its matcher (pkg/vex/csaf.go) shows three things worth knowing:

• Only two statuses act. The status map holds known_not_affected and fixed. A match on either filters the finding. known_affected and under_investigation statements never change the result.
• Matching is by purl. If the detected package has no purl, or the vulnerability has no product_status, nothing is filtered.
• Relationship categories are not distinguished. The documentation says “the specified relationship category is not taken into account” and that default_component_of, installed_on and installed_with “are treated internally as depends_on”. For a relationship, the code requires the parent purl to match a product higher in the dependency tree (such as the scanned image) and the component purl to match the sub-component, which is the both-sides rule from Step 2. external_component_of and optional_component_of relationships are skipped. A status on a plain product ID, with no relationship, is matched against the package’s own purl, so it applies wherever that package appears.

So if a vendor’s CSAF file uses optional_component_of for a component, Trivy will not apply that status through the relationship. That is safe in direction (no false suppression), but it can surprise you if you expect the finding to drop.

Common mistakes

• Matching the component alone. Covered above. It turns a statement about one product into a statement about all of them.
• Trusting known_not_affected with no impact statement. The profile requires a flag or an impact threat for each such product. If neither exists, the document does not satisfy the profile; send it back to the vendor rather than suppressing.
• Reading only branches. Products in full_product_names and relationships carry IDs too. A parser that only walks branches will report “unknown product” for most relationship-heavy files.
• Treating recommended as fixed. The spec allows recommending a version from the affected group.
• Ignoring tracking.version and current_release_date. VEX files are revised as investigations finish. Store the version you applied, and re-apply when it changes.

Where this fits

VEX is one input to a patch decision, not the decision. In our vulnerability prioritization workflow, a supplier VEX statement is the step that can close a ticket before KEV, EPSS or SSVC are weighed. For the SBOM side of the join, the SBOM minimum elements guide covers which identifiers your SBOM should carry in the first place. Without purls in the SBOM, none of this matching works.

Limits of this article

We read CSAF 2.0 from the OASIS TC’s GitHub repository (the editor’s draft prose, headed “OASIS Standard, 18 November 2022”, and the JSON schema) rather than the copy hosted on docs.oasis-open.org. CSAF 2.1 is still a draft in that repository and may change field names or add statuses. We did not download a Red Hat VEX file; Red Hat’s structure is described from its own announcements. The purl matching rules are a community convention, not part of the purl standard. Our test document is synthetic.

Sources and verification

Scope. This is a field-level mapping guide. We compared the CycloneDX JSON schemas for 1.6 and 1.7 (identical enums for the fields below), OpenVEX specification v0.2.0 and its JSON schema, and the CSAF 2.0 JSON schema and VEX profile text from the OASIS TC repository, then read how Trivy (main branch, commit 1d1ab074, November 2, 2026) consumes CycloneDX VEX. The converter below was run with Python 3.13; its output validated against the OpenVEX 0.2.0 JSON schema and its inputs against the CycloneDX 1.6 schema. Our VEX explainer covers what the statuses mean and how far to trust them; this article is only about moving statements between formats.

The short answer

If you receive CycloneDX VEX and your pipeline speaks OpenVEX or CSAF (or the reverse), the states map almost one-to-one, but the justifications do not.

Of CycloneDX’s nine justifications, only code_not_present and code_not_reachable have a clear counterpart among the five CISA-derived labels that OpenVEX and CSAF share. Convert those two; carry the other seven as text.

Where VEX sits in a CycloneDX document

CycloneDX has no separate VEX document type. VEX is the vulnerabilities array of a BOM, and the fields that matter are:

• id: the vulnerability identifier, such as a CVE ID.
• affects[].ref: what the statement is about. The schema allows a bom-ref in the same document or a BOM-Link element. A BOM-Link has the form urn:cdx:serialNumber/version#bom-ref, and the schema’s pattern requires the serial number UUID, a version of 1 or more, and a fragment.
• analysis.state: one of resolved, resolved_with_pedigree, exploitable, in_triage, false_positive, not_affected.
• analysis.justification: one of nine reasons, described below.
• analysis.response: zero or more of can_not_fix, will_not_fix, update, rollback, workaround_available.
• analysis.detail: free text. The schema says that if a vulnerability is not exploitable, “this field should include specific details on why the component or service is not impacted.”

A VEX statement can sit inside the SBOM itself or in a separate BOM that only has vulnerabilities and refers back to the SBOM by BOM-Link. That second pattern matters for tooling, below.

States: four clean pairs and two lossy ones

The CycloneDX schema defines the six states in its meta:enum. Four map directly:

• not_affected: “The component or service is not affected by the vulnerability. Justification should be specified for all not_affected cases.” This is OpenVEX not_affected and CSAF known_not_affected.
• exploitable: “The vulnerability may be directly or indirectly exploitable.” This is OpenVEX affected and CSAF known_affected.
• in_triage: “The vulnerability is being investigated.” This is under_investigation in both.
• resolved: “The vulnerability has been remediated.” This is fixed in both.

Two lose meaning:

• false_positive: “The vulnerability is not specific to the component or service and was falsely identified or associated.” OpenVEX and CSAF have no status for “the scanner was wrong”. The safe target is not_affected, which is also what Trivy’s cdxStatus function does (case cdx.IASFalsePositive, cdx.IASNotAffected: return types.FindingStatusNotAffected). Keep the word false_positive in the impact statement so a reviewer can see it.
• resolved_with_pedigree: remediated “and evidence of the changes are provided in the affected components pedigree”. It becomes fixed, and the pointer to pedigree evidence is lost unless you keep it as text.

Justifications: two of nine line up

OpenVEX’s five justification labels come from CISA’s June 2022 status-justification document, and the CSAF 2.0 schema’s flags[].label uses the same five strings. CycloneDX defines a different set of nine. Here is each one with its CycloneDX definition and our reading of the closest OpenVEX/CSAF label.

Why so strict? The OpenVEX spec defines inline_mitigations_already_exist as built-in protections that “cannot be subverted by the attacker and cannot be configured or disabled by the user.” A CycloneDX protected_at_runtime or protected_by_compiler claim does not tell you that. protected_at_perimeter and protected_by_mitigating_control describe the deployment, not the product, and a mitigating control that “reduce[s] the likelihood and/or impact” is weaker than “not affected” in the CISA sense.

This mapping is our editorial reading of the published definitions. We did not find a mapping table published by the CycloneDX project or CISA.

OpenVEX gives you a way out: for not_affected, “a VEX statement MUST include either a status justification or an impact_statement.” So you can emit a not_affected statement with no label and an impact statement that preserves the original CycloneDX reason. CSAF’s VEX profile has the same escape hatch: each known_not_affected product needs either a machine-readable flag or a human-readable justification in threats with category impact.

Responses and action statements

For affected products, both targets require an action:

• OpenVEX: for affected, “a VEX statement MUST include a statement that SHOULD describe actions to remediate or mitigate the vulnerability” (action_statement).
• CSAF VEX profile: for known_affected, “additional product specific information SHALL be provided in /vulnerabilities[]/remediations as an action statement.”

CycloneDX’s response values give you a starting point. update and rollback fit CSAF’s vendor_fix remediation category, workaround_available fits workaround, and will_not_fix / can_not_fix fit no_fix_planned (or none_available), which the CSAF profile explicitly permits for an action statement. OpenVEX takes a free-text action_statement, so join the responses with analysis.detail. If an exploitable statement has neither a response nor detail, the converted statement will be valid but useless; send it back to the supplier.

BOM-Link: the part that silently drops statements

A CycloneDX VEX BOM that references components by BOM-Link is bound to one SBOM version. Trivy’s docs (v0.67) say the tool “only supports the Independent BOM and VEX BOM format, so you need to provide a separate VEX file alongside the SBOM,” that “BOM-Links must be placed in affects.ref,” and that the input SBOM must be CycloneDX. The usage example is trivy sbom trivy.sbom.cdx --vex trivy.vex.cdx. The feature is marked experimental.

Trivy’s code adds a detail the docs do not spell out: if the BOM-Link’s serial number or version does not equal the scanned SBOM’s, it logs URN doesn't match with SBOM and skips the statement. Regenerate the SBOM (new serial number or version) without regenerating the VEX, and every suppression stops applying. That fails safe, since findings come back rather than disappear, but it surprises teams.

OpenVEX has no BOM-Link. Products are identified by an @id such as a Package URL, so a converter has to resolve each BOM-Link to the referenced component’s purl in the SBOM. That is why the converter below takes both files.

A tested converter: CycloneDX VEX to OpenVEX

This Python 3 script reads a CycloneDX SBOM and a separate CycloneDX VEX BOM and writes an OpenVEX 0.2.0 document. It maps states as in the first table, maps only the two clean justifications, and keeps everything else as text. It is illustrative, not production-ready: it does not handle version ranges in affects[].versions, services, or nested BOMs beyond components.

#!/usr/bin/env python3
"""Convert a CycloneDX VEX BOM (independent VEX, BOM-Link refs) to OpenVEX v0.2.0.
Usage: python3 cdx2openvex.py sbom.cdx.json vex.cdx.json author > out.openvex.json"""
import json, sys, hashlib
from datetime import datetime, timezone

STATUS = {  # CycloneDX analysis.state -> OpenVEX status
    "not_affected": "not_affected", "false_positive": "not_affected",
    "exploitable": "affected", "in_triage": "under_investigation",
    "resolved": "fixed", "resolved_with_pedigree": "fixed",
}
# Only the pairs whose definitions line up; everything else is carried as text.
JUSTIFICATION = {
    "code_not_present": "vulnerable_code_not_present",
    "code_not_reachable": "vulnerable_code_not_in_execute_path",
}

def purls_by_ref(sbom):
    serial, version = sbom["serialNumber"], sbom.get("version", 1)
    out, stack = {}, list(sbom.get("components", []))
    while stack:
        c = stack.pop()
        if "bom-ref" in c and "purl" in c:
            out[f"urn:cdx:{serial.removeprefix('urn:uuid:')}/{version}#{c['bom-ref']}"] = c["purl"]
        stack.extend(c.get("components", []))
    return out

def convert(sbom, vex, author):
    refs, statements, problems = purls_by_ref(sbom), [], []
    for v in vex.get("vulnerabilities", []):
        a = v.get("analysis", {})
        state = a.get("state")
        if state not in STATUS:
            problems.append(f"{v['id']}: no analysis.state, skipped"); continue
        products = []
        for af in v.get("affects", []):
            purl = refs.get(af["ref"])
            if purl: products.append({"@id": purl})
            else: problems.append(f"{v['id']}: {af['ref']} not found in SBOM")
        if not products: continue
        s = {"vulnerability": {"name": v["id"]}, "products": products, "status": STATUS[state]}
        detail = a.get("detail", "").strip()
        if s["status"] == "not_affected":
            j = JUSTIFICATION.get(a.get("justification"))
            if j: s["justification"] = j
            note = f"CycloneDX state={state}, justification={a.get('justification', 'none')}"
            s["impact_statement"] = f"{note}. {detail}".strip()
        elif s["status"] == "affected":
            resp = ", ".join(a.get("response", [])) or "none given"
            s["action_statement"] = f"CycloneDX response: {resp}. {detail}".strip()
        statements.append(s)
    body = json.dumps(statements, sort_keys=True).encode()
    doc = {"@context": "https://openvex.dev/ns/v0.2.0",
           "@id": "https://example.com/vex/" + hashlib.sha256(body).hexdigest()[:16],
           "author": author,
           "timestamp": datetime.now(timezone.utc).isoformat(timespec="seconds"),
           "version": 1, "statements": statements}
    return doc, problems

if __name__ == "__main__":
    sbom, vex = (json.load(open(p)) for p in sys.argv[1:3])
    doc, problems = convert(sbom, vex, sys.argv[3])
    json.dump(doc, sys.stdout, indent=2)
    for p in problems: print("WARN", p, file=sys.stderr)

Test run

We fed it a three-component CycloneDX 1.6 SBOM (log4j-core 2.14.1, jackson-databind 2.13.0, snakeyaml 1.30) and a VEX BOM with four statements. The assessments in the VEX are invented test data, not real vendor findings:

1. CVE-2021-44228 on log4j-core: not_affected, code_not_reachable.
2. CVE-2022-42003 on jackson-databind: not_affected, requires_configuration.
3. CVE-2022-1471 on snakeyaml: exploitable, response update.
4. CVE-2021-44228 again, but with a BOM-Link naming SBOM version 2 instead of 1.

Both input files passed check-jsonschema against the CycloneDX 1.6 schema. The run printed one warning to stderr and three statements; the output validated against openvex_json_schema.json (v0.2.0) with the Python jsonschema package:

WARN CVE-2021-44228: urn:cdx:3e671687-395b-41f5-a30f-a58921a69b79/2#pkg-log4j not found in SBOM

The statements array of the output:

[
{
  "vulnerability": { "name": "CVE-2021-44228" },
  "products": [ { "@id": "pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1" } ],
  "status": "not_affected",
  "justification": "vulnerable_code_not_in_execute_path",
  "impact_statement": "CycloneDX state=not_affected, justification=code_not_reachable. JNDI lookups are never invoked; the app logs through SLF4J with Logback."
},
{
  "vulnerability": { "name": "CVE-2022-42003" },
  "products": [ { "@id": "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.13.0" } ],
  "status": "not_affected",
  "impact_statement": "CycloneDX state=not_affected, justification=requires_configuration. The deserialization feature this issue depends on is disabled in our ObjectMapper configuration."
},
{
  "vulnerability": { "name": "CVE-2022-1471" },
  "products": [ { "@id": "pkg:maven/org.yaml/snakeyaml@1.30" } ],
  "status": "affected",
  "action_statement": "CycloneDX response: update. Dependency upgrade ships in release 4.2."
}
]

The second statement is the important one: it stays not_affected with no invented label, and the reason survives as text. The fourth input statement was dropped with a warning instead of being applied to the wrong SBOM.

Common mistakes

• Mapping every protected_* justification to inline_mitigations_already_exist. That label claims the protection cannot be disabled. A WAF rule or a compiler flag can.
• Dropping false_positive statements because the target format has no matching status. Map them to not_affected and say why.
• Dropping the detail text. It is often the only evidence a reviewer has, and both OpenVEX and CSAF have a place for it.
• Reusing a VEX BOM after regenerating the SBOM. BOM-Links name an exact serial number and version.
• Treating converted VEX as first-party. Keep the original author. OpenVEX author should be the organization that made the assessment, not the converter.

Where this fits

VEX is the “is my product actually affected” step in our vulnerability prioritization workflow, after the CVE record and before KEV, SSVC and EPSS. The SBOM that the VEX points at is covered in our guide to SBOM minimum elements in 2026. If you want a signal for which exploitable statements to fix first, our CVSS vs EPSS vs KEV comparison covers the trade-offs.

Limits of this article

The justification mapping is our reading of the published definitions; no standards body has published it. We read CSAF 2.0 from the OASIS TC’s GitHub repository (schema and editor’s draft prose) rather than the OASIS-hosted standard. We read Trivy’s main branch, not a tagged release, and its docs for v0.67; behaviour may differ in the version you run. We did not run Trivy itself or test the reverse conversion (OpenVEX or CSAF to CycloneDX), which is harder because CycloneDX affects needs a component reference the OpenVEX product may not resolve to.

Sources and verification

Scope. This is a specification explainer with measurements from public data. We read the CVE JSON schema (version 5.2.0, CVEProject/cve-schema main branch) and its version-encoding guide, sampled 1,000 random 2026 records from the cvelistV5 repository at commit 451e97a (November 2, 2026), and ran the Python script below against real records. We did not test commercial scanners.

The short answer

A CVE record’s affected block does not hand you a list of bad versions. For each product it gives a small decision procedure:

1. Walk the versions list in order.
2. An entry with only version and status matches that exact version.
3. An entry with versionType plus lessThan or lessThanOrEqual matches a range, and an optional changes list can flip the status partway through it.
4. The first matching entry wins. If nothing matches, the answer is defaultStatus, and if that is missing, the answer is unknown.

The possible answers are affected, unaffected and unknown. Your tooling needs a fourth, “I cannot order these versions”, because the record does not always give you enough to decide.

Where the fields live

The CNA (CVE Numbering Authority) writes containers.cna.affected, an array of product objects. The schema requires each product to be identified by either vendor and product or collectionURL and packageName, and to carry versions, defaultStatus or both. A 5.2 record can also carry a packageURL (a purl, which the schema says must not include a version).

{
  "vendor": "GitoxideLabs",
  "product": "gitoxide",
  "defaultStatus": "unaffected",
  "packageURL": "pkg:cargo/gix-fs",
  "versions": [
    {"version": "0", "status": "affected", "versionType": "semver", "lessThan": "0.23.0"},
    {"version": "0.23.0", "status": "unaffected", "versionType": "semver"}
  ]
}

That is the product entry from CVE-2026-100419 (a gix-fs symlink worktree escape), shown in full. Read it as: semantic versions from 0 up to but not including 0.23.0 are affected, 0.23.0 is unaffected, and anything else is unaffected by default.

The fields, one by one

The upper limit can end in *, which the schema defines as “an arbitrarily large number in the version ordering”. {version: 1.0, lessThan: 1.*} describes the whole 1.x branch, and lessThan: * means “and everything after”.

Why versionType is not optional

The schema guide explains that “there is no single definition of ’less than’ for versions” and gives the example that in semantic versioning 1.0.0-cr1 sorts before 1.0.0-m1, while in Maven the opposite is true. If your code compares every version string with one generic routine, it will be wrong for some ecosystems.

The guide is blunt about custom: it “means that the version status algorithm cannot be executed, so its use is discouraged”. It exists to convert older data.

Three records, three encodings

Allow-list style (gix-fs, CVE-2026-100419). The range is affected and defaultStatus is unaffected. Version 0.22.1 is affected, 0.23.0 is unaffected by exact match, and 0.25.4 is unaffected by default.

List without a default (quickjs, CVE-2026-0821). The CNA lists eleven single versions from 0.1 to 0.11.0 as affected and sets no defaultStatus. Version 0.10 is affected. Version 0.12.0 is unknown: the record makes no claim about it. A naive matcher that treats “not listed” as “not affected” would clear it.

Deny-list style (Linux, CVE-2026-100075). The second product entry sets "defaultStatus": "affected" and lists unaffected ranges per stable branch:

{"version": "4.7", "status": "affected"},
{"version": "0", "lessThan": "4.7", "status": "unaffected", "versionType": "semver"},
{"version": "6.6.157", "lessThanOrEqual": "6.6.*", "status": "unaffected", "versionType": "semver"},
{"version": "7.3", "lessThanOrEqual": "*", "status": "unaffected", "versionType": "original_commit_for_fix"}

(Excerpt; the record also lists 5.10, 5.15, 6.1, 6.12, 6.18 and 7.2 branches.) Kernels before 4.7 are unaffected, 6.6.157 and later 6.6 releases are unaffected, and anything not covered, such as 6.6.150 or a 5.4 kernel, falls through to affected. The first product entry in the same record describes the same flaw with versionType: git commit ranges, which you cannot evaluate without the kernel’s commit history.

What a sample of 2026 records contains

We drew 1,000 CVE IDs at random (seeded) from the 83,665 record files under cves/2026 at cvelistV5 commit 451e97a. 16 were REJECTED; the 984 published records held 2,061 product entries, 4,555 version entries and 2,831 ranges. Counts were computed with a Python script over the JSON.

Two numbers matter most for automation. More than half of product entries leave unlisted versions as unknown, and about a third of ranges use custom, so a generic comparator cannot decide them. This is one sample at one point in time; the mix varies by CNA, and a different year or sample would give different shares.

A tested evaluator

The script implements the schema’s algorithm. It handles dotted numeric versions (so 1.2.10 sorts after 1.2.9) and *, and it refuses any range whose versionType it has not been told how to order. It does not implement semver pre-release ordering, RPM epochs or Maven qualifiers; treat it as a reference, not a drop-in matcher. Python 3.10 or later, standard library only.

#!/usr/bin/env python3
"""Decide affected / unaffected / unknown for one product version from a CVE record,
following the algorithm in the CVE JSON 5 schema (product.versions + defaultStatus).
Usage: affected_status.py RECORD.json VERSION [vendor/product filter] [--numeric TYPE,...]
"""
import json, sys

SUPPORTED = {"semver"}  # extend with real comparators (rpm, maven, python...) before use

def key(v):
    parts = []
    for p in v.split("."):
        if p == "*":
            parts.append(float("inf"))
        elif p.isdigit():
            parts.append(int(p))
        else:
            raise ValueError(f"non-numeric version part {p!r} in {v!r}")
    return parts

def cmp(a, b):
    ka, kb = key(a), key(b)
    n = max(len(ka), len(kb))
    # pad: a missing part is 0, except after a wildcard, which stays infinite
    ka += [float("inf") if ka and ka[-1] == float("inf") else 0] * (n - len(ka))
    kb += [float("inf") if kb and kb[-1] == float("inf") else 0] * (n - len(kb))
    return (ka > kb) - (ka < kb)

def status(product, v):
    for e in product.get("versions", []):
        is_range = "lessThan" in e or "lessThanOrEqual" in e
        if not is_range:
            if v == e["version"]:
                return e["status"], "exact match"
            continue
        vt = e.get("versionType")
        if vt not in SUPPORTED:
            return "undetermined", f"range uses versionType {vt!r}; needs that ordering"
        lo_ok = cmp(e["version"], v) <= 0
        hi_ok = (cmp(v, e["lessThan"]) < 0) if "lessThan" in e else (cmp(v, e["lessThanOrEqual"]) <= 0)
        if lo_ok and hi_ok:
            s = e["status"]
            for c in sorted(e.get("changes", []), key=lambda c: key(c["at"])):  # schema: re-sort yourself
                if cmp(c["at"], v) <= 0:
                    s = c["status"]
            return s, "range match"
    return product.get("defaultStatus", "unknown"), "defaultStatus" + ("" if "defaultStatus" in product else " (absent, so unknown)")

if __name__ == "__main__":
    args = sys.argv[1:]
    if "--numeric" in args:  # opt-in: treat these extra versionTypes as dotted numeric
        i = args.index("--numeric")
        SUPPORTED.update(args[i + 1].split(","))
        del args[i:i + 2]
    sys.argv[1:] = args
    rec = json.load(open(sys.argv[1]))
    version = sys.argv[2]
    want = sys.argv[3].lower() if len(sys.argv) > 3 else ""
    if rec["cveMetadata"]["state"] != "PUBLISHED":
        sys.exit(f"{rec['cveMetadata']['cveId']} is {rec['cveMetadata']['state']}")
    for i, p in enumerate(rec["containers"]["cna"].get("affected", [])):
        name = f"{p.get('vendor', '')}/{p.get('product', p.get('packageName', ''))}"
        if want and want not in name.lower():
            continue
        print(f"{rec['cveMetadata']['cveId']} [{i}] {name} {version}: %s (%s)" % status(p, version))

We ran it with Python 3.13 on November 2, 2026 against records downloaded from cvelistV5 (raw.githubusercontent.com/CVEProject/cvelistV5/<commit>/cves/2026/<block>/<CVE>.json). Selected output:

CVE-2026-100419 [0] GitoxideLabs/gitoxide 0.22.1: affected (range match)
CVE-2026-100419 [0] GitoxideLabs/gitoxide 0.23.0: unaffected (exact match)
CVE-2026-100419 [0] GitoxideLabs/gitoxide 0.25.4: unaffected (defaultStatus)
CVE-2026-0821 [0] quickjs-ng/quickjs 0.12.0: unknown (defaultStatus (absent, so unknown))
CVE-2026-100075 [0] Linux/Linux 6.6.150: undetermined (range uses versionType 'git'; needs that ordering)
CVE-2026-100075 [1] Linux/Linux 6.6.150: undetermined (range uses versionType 'original_commit_for_fix'; needs that ordering)
CVE-2026-103345 [0] Shamim Rajani/Pie Register 3.8.4.13: undetermined (range uses versionType 'custom'; needs that ordering)
CVE-2026-23915 is REJECTED

The Linux result is the instructive one. For 6.6.150 the evaluator reaches the 7.3 ... * entry, whose versionType is original_commit_for_fix, a value that is not among the schema’s examples. A strict implementation stops there. If you decide, for this CNA’s data, that those values are ordinary kernel version numbers, you can opt in with --numeric original_commit_for_fix, and the second product entry then gives 4.4.302 unaffected, 4.7 affected, 6.6.150 affected (by defaultStatus), 6.6.157 unaffected and 7.3 unaffected. That opt-in is our judgment about one CNA’s encoding, not something the schema states.

Common mistakes

• Treating “not listed” as “not affected”. Without defaultStatus: unaffected, unlisted versions are unknown.
• Off-by-one on the upper bound. lessThan: 0.23.0 excludes 0.23.0; lessThanOrEqual: 3.8.4.13 includes 3.8.4.13.
• Comparing strings. As text, “0.10” sorts before “0.9”. Parse versions with the ecosystem’s rules.
• Assuming changes is sorted. The schema tells clients to re-sort.
• Reading only the first product entry. The same record can describe a product twice, as the Linux record does with git ranges and version ranges.
• Ignoring the record state. A REJECTED record has no affected block to evaluate; see CVE record states.

Where this fits in triage

Version matching answers “do we run an affected version?”, which comes before any priority signal. If the answer is unknown or undetermined, check the vendor advisory, or a supplier VEX statement that says whether the product is affected (see how to read a VEX not-affected statement). An SBOM with accurate component versions is what makes this lookup possible at scale; our summary of the 2026 SBOM minimum elements covers what to ask suppliers for. Once a finding is confirmed as affected, our vulnerability prioritization workflow takes it from record to ticket using KEV, EPSS and SSVC.

Limits of this article

The sample covers 2026 records only and reflects the repository on November 2, 2026; CNAs update records, so shares will drift. Our evaluator is a reference implementation of the schema’s algorithm for numeric versions, not a full comparator for semver pre-releases, RPM, Maven, Python or git ranges. We did not examine ADP containers, which can carry their own affected data (15 of the 984 sampled records had one), or NVD’s separate CPE configurations.

Sources and verification