At the end of last summer, I wrote a blog post explaining the merits of Vulnerability Exploitability eXchange (VEX) documents. 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 presenting on this very topic at S4x22, 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:
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, file hash, PURL, serial number, component ID, and SBOM ID 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 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.