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 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