If your patch pipeline uses an EPSS cutoff to decide what is urgent, it will miss about a quarter of CISA’s Known Exploited Vulnerabilities (KEV) catalog, and roughly half of the entries CISA added in the last 90 days. Joining KEV catalog 2026.11.06 to the EPSS file for November 6, 2026, 436 of 1,768 scored KEV CVEs sit below 0.1. Tracking recent additions day by day shows why: EPSS scores for newly listed CVEs typically start low and take about two weeks to cross 0.1, which is the window in which a KEV listing matters most.

We argued in our CVSS vs EPSS vs KEV comparison that KEV should be checked before EPSS. This article measures what happens when it is not, and gives you a script to test your own cutoff.

The snapshot: KEV CVEs below common EPSS cutoffs

Data: the KEV JSON (catalog version 2026.11.06, released 2026-11-06T19:44Z, 1,769 entries) and the EPSS daily file for November 6, 2026 (model_version:v2026.06.15, 400,985 scored CVEs). One KEV entry, CVE-2026-19868, added that day, had no EPSS score yet.

The median KEV CVE scores 0.536 (99.0th percentile), so the typical entry is well above any cutoff. The problem is the tail, and the tail is not random. If you are unsure what the epss and percentile columns mean, our EPSS data feed guide covers them.

Newest KEV entries score lowest

Split by dateAdded, the share below 0.1 falls as entries age:

Several recent listings we covered are in that first row. On November 6, WordPress CVE-2026-119977 (added November 3) scored 0.0116, Ivanti CVE-2026-111357 and CVE-2026-118527 (added October 30) scored 0.0053 and 0.0082, and VMware ESX CVE-2026-41709 (added October 28) scored 0.0069. Each would sit below even a 0.05 cutoff.

Tracking the lag: 113 KEV additions, day by day

A snapshot cannot show whether low scores are permanent or just early. So we took the 113 KEV entries added between June 16 and October 7, 2026, and looked up each one in every daily EPSS file from June 15 to November 6 (145 files). That window starts the day after EPSS v5 replaced v4, so every score comes from the same model (v2026.06.15); our EPSS v5 analysis explains why mixing models would distort this. The October 7 end date gives every entry at least 30 days of follow-up.

Notes on reading it:

• Missing scores are real. 36 of the 113 had no EPSS score the day before listing and 22 had none on the day itself, usually because the CVE had only just been published. By day 7 all 113 were scored.
• Crossing time. 15 entries were already at or above 0.1 the day before listing. Of the rest, 64 crossed 0.1 later, after a median of 14 days (23 within a week). 34 had not reached 0.1 by November 6, 36 to 115 days after listing.
• Timing, not cause. EPSS files publish only the score. We cannot see which inputs moved a score, so we do not claim the KEV listing itself caused any rise.

Why the gap exists is consistent with how each list is built. CISA adds a CVE when there is “reliable evidence that the vulnerability has been actively exploited in the wild” (CISA). EPSS is “the probability [0-1] of exploitation in the wild in the next 30 days (following score publication)”, estimated from data (EPSS scores README). The community Risk Based Prioritization guide puts it this way: EPSS reflects “the automated data we receive and collect”, while KEV is “a list of human curated CVEs with historical exploitation activity”, so a CVE can be in one and score low in the other. It also quotes FIRST’s EPSS FAQ: where exploitation is evidenced, “that information should supersede anything EPSS has to say”.

What to change in a pipeline

These are our recommendations from the data above; we have not measured them on anyone’s backlog.

1. Route on KEV membership before any EPSS rule. A listed CVE goes to the urgent queue whatever its score. This is the first step in our prioritization workflow.
2. Do not “promote” KEV entries by adding a bonus to the EPSS score. A bonus sized for the median KEV entry (0.536) does nothing for an entry at 0.005.
3. Treat a missing EPSS score as “unknown”, not zero. 22 of the 113 entries had no score on the day they were listed. A join that fills nulls with 0 drops exactly those.
4. Refresh KEV more often than you refresh thresholds. The KEV JSON feed updates on listing days; the lag above means the KEV check is doing nearly all of the work for the first two weeks.
5. Re-run the audit after every EPSS model change, since cutoffs shift with the model.

Audit your own cutoff

This script joins the two public files and reports how many KEV entries your cutoff misses, by listing age. We ran it with Python 3.12 on the files named above; the output below is for 0.1.

#!/usr/bin/env python3
"""How many CISA KEV entries would an EPSS cutoff miss?
usage: kev_epss_audit.py known_exploited_vulnerabilities.json epss_scores-YYYY-MM-DD.csv.gz CUTOFF"""
import csv, gzip, json, sys
from datetime import date

kev_path, epss_path, cutoff = sys.argv[1], sys.argv[2], float(sys.argv[3])
catalog = json.load(open(kev_path))
with gzip.open(epss_path, "rt") as f:
    header = f.readline().strip()                 # "#model_version:...,score_date:..."
    scores = {r["cve"]: float(r["epss"]) for r in csv.DictReader(f)}
score_day = date.fromisoformat(header.split("score_date:")[1][:10])

print(f"KEV catalog {catalog['catalogVersion']}, EPSS {header[1:]}, cutoff {cutoff}")
buckets = {"added <= 90 days ago": [], "91-365 days": [], "over 1 year": []}
unscored = []
for v in catalog["vulnerabilities"]:
    if v["cveID"] not in scores:
        unscored.append(v["cveID"])
        continue
    age = (score_day - date.fromisoformat(v["dateAdded"])).days
    name = "added <= 90 days ago" if age <= 90 else "91-365 days" if age <= 365 else "over 1 year"
    buckets[name].append((v["cveID"], scores[v["cveID"]]))

total = below = 0
for name, rows in buckets.items():
    n_below = sum(1 for _, s in rows if s < cutoff)
    total += len(rows); below += n_below
    print(f"{name:22} {len(rows):5} KEV CVEs, {n_below:4} below cutoff ({n_below/len(rows):.1%})")
print(f"{'all scored':22} {total:5} KEV CVEs, {below:4} below cutoff ({below/total:.1%})")
print(f"not in EPSS file: {len(unscored)} {unscored[:5]}")

$ python3 kev_epss_audit.py known_exploited_vulnerabilities.json epss_scores-2026-11-06.csv.gz 0.1
KEV catalog 2026.11.06, EPSS model_version:v2026.06.15,score_date:2026-11-06T12:00:23Z, cutoff 0.1
added <= 90 days ago     106 KEV CVEs,   52 below cutoff (49.1%)
91-365 days              207 KEV CVEs,   57 below cutoff (27.5%)
over 1 year             1455 KEV CVEs,  327 below cutoff (22.5%)
all scored              1768 KEV CVEs,  436 below cutoff (24.7%)
not in EPSS file: 1 ['CVE-2026-19868']

Get the KEV file from raw.githubusercontent.com/cisagov/kev-data/main/known_exploited_vulnerabilities.json and the EPSS file from the empiricalsec/epss_scores repository (one gzip file per day under the year folder). The script reads the whole EPSS file into memory, which is fine for about 400,000 rows.

Limits of this article

The snapshot is one day (November 6, 2026). The day-by-day sample is 113 entries over one model version, which is enough to show a pattern but not to estimate a precise lag for any vendor or CVE type. “Day of listing” compares KEV dateAdded to the EPSS file of the same date; their publication times within the day differ. We did not examine why the 34 entries that stayed below 0.1 scored as they did.

Sources and verification

The EPSS daily file changed models on June 15, 2026. The first line of the June 14 file reads #model_version:v2025.03.14 (v4). The June 15 file reads #model_version:v2026.06.15 (v5). We compared those two files, which together hold 340,204 CVEs scored on both days. If your pipeline gates on a fixed EPSS probability, it lost about a quarter of its flagged CVEs overnight: 23,069 CVEs scored 0.1 or higher under v4 and 17,041 under v5. Nothing about those vulnerabilities changed that day; the model did.

This article covers what changed in v5, what the shift looks like in the data, and what to re-baseline. For the file format itself (columns, header line, how to join it to a scanner export), see our EPSS data feed guide. That guide already lists the five model versions and their start dates; this one measures the most recent change.

What changed in v5

Empirical Security, which runs the EPSS model and hosts the data, announced EPSS V5 on May 13, 2026. The release says v5 “incorporates improved modeling techniques and optimization algorithms” and that “the calibration step has been refined.” It also cites a better classifier for published exploit code and “the addition of new data feeds.”

The headline claim is a 23% improvement. Empirical’s research post defines the metric only loosely, as one that rewards “ranking genuinely exploited vulnerabilities above ones that pose no real threat.” On data from May 4, 2026, it reports that v4 scored 0.514 and v5 scored 0.633, where “a random guess would score around 0.025, and a perfect model would score 1.0.” We did not reproduce that evaluation.

The rollout is visible in the public empiricalsec/epss_scores repository:

The beta files carry a different model label (v2026.05.12) from the production model, so treat beta scores as a preview of v5, not as v5 itself. The repository README lists the model changes for v2, v3 and v4 but, as of November 6, 2026, has no v5 entry. The file header was the reliable signal.

The CSV format did not change. Both files have the same comment line followed by cve,epss,percentile.

How the scores moved

We loaded 2026/epss_scores-2026-06-14.csv.gz and 2026/epss_scores-2026-06-15.csv.gz from the repository and compared CVEs present in both. For a baseline, we ran the same comparison on June 13 and June 14, two consecutive v4 days.

Three patterns stand out.

The distribution got narrower. The lowest v4 score was 0.00001 and 93,484 CVEs sat below 0.001. Under v5 the minimum is 0.00046 and only 3,552 CVEs are below 0.001. At the top end, the 99th percentile fell from 0.772 to 0.595. The median ratio of v5 to v4 score was 2.89: most low-scored CVEs went up, while many of the high scorers came down. That fits the release’s description of recalibration, but the release does not say this is the intended effect, so treat it as our reading of the data.

Fixed cutoffs shrank. A rule like epss >= 0.1 matched 26.1% fewer CVEs the day v5 went live, and epss >= 0.5 matched 40.9% fewer. Of the CVEs that crossed 0.1, 9,847 dropped below it and only 3,820 rose above it.

Percentile rules kept their size, not their members. A percentile is a rank, so the 90th-percentile bucket stays about 10% of scored CVEs. But 9,837 CVEs entered it and 9,944 left it in one day, compared with 25 and 29 on a normal v4 day. If you track “new CVEs in the top decile” as a work queue, June 15 would have looked like a flood.

1,146 CVEs scored on June 14 were missing from the June 15 file and 43 appeared for the first time. By November 5, all but 119 of the missing ones were back in the feed. We did not establish why they were absent that day.

What happened to KEV-listed CVEs

To see whether v5 demoted known-exploited vulnerabilities, we took the CISA KEV catalog (catalog version 2026.11.04) and kept only the 1,619 entries whose dateAdded is on or before June 14, 2026, so the set matches what was known on the switch date. All 1,619 were scored on both days.

The probability for KEV entries came down along with the rest of the high end. But almost the same number cleared 0.1, and more of them landed in the top decile. KEV-listed CVEs that a 0.1 rule already caught were still caught. A rule set to 0.5 or 0.7 on the assumption that KEV CVEs sit there would have lost many of them, since the median is now about 0.54.

This is one reason KEV should stay a separate input instead of being folded into an EPSS cutoff. Our CVSS vs EPSS vs KEV comparison covers why; the prioritization workflow shows where each signal sits in the patch decision.

What to re-baseline

These are our recommendations, based on the data above. We have not measured their effect on any team’s backlog.

1. Find every fixed probability cutoff. SLA rules, ticket triggers, dashboard colours and scanner policies. If one was tuned against v4 data, check how many CVEs it matches today versus before June 15.
2. Decide what the cutoff is for. If it sizes a queue (“the top few thousand CVEs”), switch it to a percentile. If it expresses risk (“at least a 10% chance of exploitation in 30 days”), keep the probability, because v5’s calibration is meant to make that reading more accurate, but accept that the queue size will move.
3. Do not compare scores across the switch. A CVE that went from 0.4 to 0.2 on June 15 did not become less likely to be exploited that day. If you chart EPSS history, mark June 15, 2026 (and the earlier switches on 2022-02-04, 2023-03-07 and 2025-03-17).
4. Keep KEV as an override. Do not rely on EPSS to bring KEV entries above a high cutoff.
5. Store model_version next to every score. Then you can always tell which model produced a score your system acted on.

A guard for the next model change

There is no API callback when the model changes, but the file tells you. This script compares the header of yesterday’s and today’s file and exits non-zero on a model change, so a CI job or cron wrapper can stop before ingesting.

"""Stop an EPSS ingest when the model version changes.
Usage: python3 epss_model_guard.py yesterday.csv.gz today.csv.gz"""
import gzip, sys

def header(path):
    with gzip.open(path, "rt") as f:
        first = f.readline().strip()
    if not first.startswith("#"):
        return {"model_version": "pre-v2 (no header)", "score_date": ""}
    return dict(kv.split(":", 1) for kv in first.lstrip("#").split(","))

old, new = header(sys.argv[1]), header(sys.argv[2])
print(f"previous: {old['model_version']} scored {old['score_date']}")
print(f"current:  {new['model_version']} scored {new['score_date']}")
if old["model_version"] != new["model_version"]:
    print("MODEL CHANGE: hold threshold-based alerts and re-baseline before ingesting")
    sys.exit(2)

We ran it with Python 3 against files from the repository:

$ python3 epss_model_guard.py epss_scores-2026-06-14.csv.gz epss_scores-2026-06-15.csv.gz
previous: v2025.03.14 scored 2026-06-14T12:55:00Z
current:  v2026.06.15 scored 2026-06-15T12:03:41Z
MODEL CHANGE: hold threshold-based alerts and re-baseline before ingesting
exit=2

$ python3 epss_model_guard.py epss_scores-2026-11-04.csv.gz epss_scores-2026-11-05.csv.gz
previous: v2026.06.15 scored 2026-11-04T12:03:12Z
current:  v2026.06.15 scored 2026-11-05T12:03:04Z
exit=0

When the guard trips, run the same comparison we did above (counts at your cutoffs, percentile churn, KEV coverage) before you turn alerts back on. Note the score_date format also changed with v4 (from +0000 offsets to Z), so parse it as ISO 8601 instead of matching a fixed string.

Limits of this article

• We compared one pair of days. Scores on later v5 days have kept moving as new signals arrive, so today’s counts differ from June 15.
• The 23% improvement figure and the description of model changes come from Empirical Security. We did not test model accuracy.
• KEV is a list of vulnerabilities known to be exploited, not a ground truth for EPSS’s 30-day prediction window, so the KEV table shows coverage, not accuracy.
• We did not find a FIRST page describing v5 in the sources we could reach. If FIRST publishes a different start date or model description, the file headers above are still what your pipeline will see.

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