---
title: A Deeper Dive into VEX Documents
description: Learn how Vulnerability Exploitability eXchange (VEX) documents play a critical role in the efficient management of vulnerabilities in OT environments.
---

[aDolus Blog](https://blog.adolus.com)

# [A Deeper Dive into VEX Documents](https://blog.adolus.com/a-deeper-dive-into-vex-documents)

 Written by [Derek Kruszewski](https://blog.adolus.com/author/derek-kruszewski) | Apr 15, 2022 8:15:00 PM

 

At the end of last summer, I wrote a blog post explaining the merits of [Vulnerability Exploitability eXchange (VEX) documents](https://blog.adolus.com/what-is-vex-and-what-does-it-have-to-do-with-sboms). Almost 8 months later, I stand by the importance of these documents when it comes to efficient management of vulnerabilities. With our CTO, [Eric Byres](https://ca.linkedin.com/in/ericbyres) presenting on this very topic at [S4x22](https://whova.com/embedded/session/Nqhxm613natQMiiNsg9ZNQOHYGv9w0qUzpI1XJGVBAs=/1945563/?widget=primary), it seems like a good time to come back to VEX documents and dig into what they actually look like.

There are currently two standardized formats available for VEX documents:

- The [**Common Security Advisory Framework (CSAF)**](https://docs.oasis-open.org/csaf/csaf/v2.0/csaf-v2.0.html) was the first format available. This format is released by OASIS Open, which is an international not-for-profit dedicated to producing open-source standards for cybersecurity, blockchain, IoT, and other areas. For those already familiar with OASIS, CSAF is a renaming of and major revision to the [Common Vulnerability Reporting Framework (CVRF)](http://docs.oasis-open.org/csaf/csaf-cvrf/v1.2/cs01/csaf-cvrf-v1.2-cs01.pdf) v1.2, which was released by OASIS in 2017.

- [**Cyclone DX**,](https://cyclonedx.org/) a standardized format for SBOMs by OWASP (Open Web Application Security Project), has recently been adapted to also create VEX documents.

Either schema can be used as a standardized format for releasing a security advisory or a VEX document. In this post, I’ll go over CSAF in detail, but the general anatomy of a VEX document holds for either format.

When CSAF is used to release a VEX document, there are three main sections: *document*, *product\_tree*, and *vulnerabilities*. Take a look at the summary below to see how these sections and the information they contain are related:

The **document** section contains typical document information, such as document timestamp, csaf\_version, and author.

The **product\_tree** section includes details on the products that have been assessed for vulnerability exploitability.

The **vulnerabilities** section includes information on a vulnerability (or vulnerabilities) with details on the status as it relates to the products listed in the product\_tree section.

By combining the information provided in these three sections, a VEX document lays out a path that asset owners can follow to identify which products they need to address — the vendor products that actually contain exploitable vulnerabilities.

While this diagram does a good job of explaining the information included in a VEX document, it doesn’t prepare you for what you’ll see in an actual CSAF VEX document. But don’t let that worry you; in reality, VEX documents are intended to be machine-readable rather than human-friendly. Nevertheless, it’s useful to see and understand the structure, so let’s dive into a CSAF JSON schema and look at some of the key fields. At the head of the JSON, you can clearly see the three sections we’ve already discussed:

Expanding the document section, you can see the document properties, which are all straightforward:

The product\_tree section is more complex, so let’s focus on the branches property.

The branches property contains a hierarchy of products grouped together into families/product lines. Take a look at the following example to make sense of things:

Notice how the product tree becomes increasingly specific until landing on a distinct product. These trees typically start at a vendor and cascade through product groupings (i.e., branches) ending at  enumerated products — each one with a unique product\_id (the product\_id being the attribute used to associate the product to a vulnerability).

The CSAF specification also has a product\_identification\_helper attribute that VEX producers can use to help communicate what a product name refers to. A product's [CPE string](https://docs.oasis-open.org/csaf/csaf/v2.0/csaf-v2.0.html#31331-full-product-name-type---product-identification-helper---cpe), [file hash](https://docs.oasis-open.org/csaf/csaf/v2.0/csaf-v2.0.html#31332-full-product-name-type---product-identification-helper---hashes), [PURL](https://docs.oasis-open.org/csaf/csaf/v2.0/csaf-v2.0.html#31334-full-product-name-type---product-identification-helper---purl), [serial number](https://docs.oasis-open.org/csaf/csaf/v2.0/csaf-v2.0.html#31336-full-product-name-type---product-identification-helper---serial-numbers), [component ID](https://docs.oasis-open.org/csaf/csaf/v2.0/csaf-v2.0.html#31338-full-product-name-type---product-identification-helper---generic-uris), and [SBOM ID](https://docs.oasis-open.org/csaf/csaf/v2.0/csaf-v2.0.html#31335-full-product-name-type---product-identification-helper---sbom-urls) are all encouraged additions to a VEX document. Nothing is as challenging (or as frustrating!) as a security advisory with the specificity of “Intel Drivers.” These attributes help consumers ensure that the product they have in hand is the same product that was analyzed for vulnerability exploitability. 

Finally, we have the vulnerabilities section, where the product\_status property details which products are affected by what vulnerabilities:

The primary categories of this section are known\_affected, known\_not\_affected, under\_investigation, and fixed. These categories are self-explanatory, so I won’t go into too much detail. However, it’s worth pointing out that when a product is known\_affected, the remediations property provides details on what product users can do regarding the vulnerability (sometimes nothing). And when a product is known\_not\_affected, the threats property’s impact category provides details as to why a vulnerability is not exploitable in a product.

So with that, hopefully this brief tour of the anatomy of a VEX document provides insight and removes some of the mystery around what you’re seeing in these machine-readable documents. At aDolus we’ve been very fortunate to have some fantastic partner vendors that are using FACT for vulnerability detection and are also [piloting the creation of VEX documents](https://adolus.com/#solarturbines) through FACT, so I look forward to sharing more details in the future. Until then, stay tuned and don’t hesitate to reach out if you’d like to explore more with FACT.

[View full post](https://blog.adolus.com/a-deeper-dive-into-vex-documents)

```json
{
  "@context" : "http://schema.org",
  "@type" : "BlogPosting",
  "author" : {
    "@type" : "Person",
    "name" : "Derek Kruszewski"
  },
  "dateModified" : "2022-04-25T15:25:38.556Z",
  "datePublished" : "2022-04-15T20:15:00Z",
  "headline" : "A Deeper Dive into VEX Documents",
  "image" : {
    "@type" : "ImageObject",
    "height" : 730,
    "url" : "https://6687498.fs1.hubspotusercontent-na1.net/hubfs/6687498/Anatomy%20of%20VEX%20Documents2.png",
    "width" : 1298
  },
  "mainEntityOfPage" : "https://blog.adolus.com/a-deeper-dive-into-vex-documents",
  "publisher" : {
    "@type" : "Organization",
    "logo" : {
      "@type" : "ImageObject",
      "height" : 60.0,
      "url" : "https://f.hubspotusercontent40.net/hubfs/6687498/adolous-logo-320px-1.png",
      "width" : 145.45454
    },
    "name" : "aDolus Blog"
  }
}
```