Vex Documents: Status Justification & Updates

Vex documents answer common questions about status justification and updates by providing a structured, machine-readable format to record the status of vulnerabilities and the evidence supporting that status. This article explains what Vex documents are, how they handle status justification, how updates work, and how to use them effectively.

Formula

The calculator estimates how many VEX documents you can update per hour based on the average time to update one document (t) and the number of components (n). The formula is:

Documents per minute = 60 / t

Total documents updated in one hour = (60 / t) * n

Where:

• t = average time to update one VEX document (minutes)
• n = number of components (used to scale the output)

Worked Example

Using the default values (t = 10 minutes, n = 100 components):

1. Documents per minute = 60 / 10 = 6 docs/min
2. Total documents in one hour = 6 * 100 = 600 docs

So with a 10-minute average update time, you can process 600 VEX documents in an hour.

What is a VEX Document?

VEX (Vulnerability Exploitability eXchange) is a standardized format, developed under the OASIS CSAF (Common Security Advisory Framework) umbrella, that allows a supplier to communicate the exploitability status of a vulnerability in a product. Instead of just listing vulnerabilities, a VEX document states whether a product is not affected, affected, or under investigation for each vulnerability, along with a justification for that status.

The key value is that it reduces false positives: if a component has a known CVE but the product doesn’t use the vulnerable function, the VEX document says so, allowing consumers to deprioritize that finding.

Status Justification: The Core of VEX

Each vulnerability in a VEX document must have a status, and if the status is not affected or affected, a justification is required. The allowed justifications (per the CSAF standard) are:

• component_not_present – The vulnerable component is not included in the product.
• vulnerable_code_not_present – The component is present, but the specific vulnerable code is not (e.g., a patch or different build).
• vulnerable_code_cannot_be_controlled_by_adversary – The vulnerable code exists but is not reachable by an attacker in a way that matters.
• vulnerable_code_not_reachable – The code is present but not reachable due to the product’s architecture or configuration.
• inline_mitigations_already_exist – There are built-in mitigations that prevent exploitation.
• supported_versions_affected – Only certain versions are affected, and this version is not.

These justifications are not just labels; they are the basis for automated decision-making. A consumer’s vulnerability scanner can read the VEX document and automatically mark a CVE as “not exploitable” if the justification is strong, saving hours of manual triage.

How Updates Work in VEX

VEX documents are not static; they need to be updated when the status of a vulnerability changes. The standard supports versioning: each document has a version field (e.g., 1.0, 1.1, 2.0) and a timestamp of the last update. When a status changes, you publish a new version of the document, and consumers should track the latest version.

Updates are typically triggered by:

• New vulnerability disclosures (e.g., a new CVE affecting a component).
• Completion of an investigation (moving from under investigation to affected or not affected).
• Release of a patch that changes the status from affected to not affected.

There is no automatic “push” mechanism; consumers must poll the VEX document location (often a URL) or use a distribution service. Some organizations use a last_updated field to signal that the document has changed.

How to Choose the Right Justification

Selecting the correct justification is critical because it affects downstream decisions. Here is a practical guide:

1. First, check if the component is actually in the product. If not, use component_not_present.
2. If the component is present, check if the vulnerable code is present. If a patch has been applied or the code is in a different version, use vulnerable_code_not_present.
3. If the code is present, assess reachability. If the vulnerable function is not callable by an attacker (e.g., requires local access that is already restricted), use vulnerable_code_not_reachable.
4. If the code is reachable but there is a built-in mitigation (e.g., a WAF rule), use inline_mitigations_already_exist.
5. If none of the above apply, the status is affected, and you may include a impact_statement or remediation.

Remember: the justification must be accurate and defensible. Overusing vulnerable_code_not_reachable without evidence can erode trust.

Common Problems and Misconceptions

One common problem is confusing status with justification. The status is the overall conclusion (e.g., not_affected), while the justification is the reason. Both are required for a complete VEX entry.

Another misconception is that VEX documents are only for software vendors. In reality, any organization that distributes a product (hardware, software, or firmware) that includes third-party components can use VEX to communicate status. Also, VEX does not replace a full SBOM; it complements it by adding exploitability context.

A frequent issue is version control. If you update a VEX document but don’t increment the version, consumers may miss the change. Always bump the version and update the timestamp.

Comparing VEX with Other Formats

VEX is often compared with the CycloneDX vulnerabilities field or the SPDX reference. While CycloneDX can include vulnerability information, VEX is specifically designed to be a standalone, machine-readable statement of exploitability. The main difference is that VEX is not tied to a specific SBOM format; it can be used alongside any SBOM. Also, VEX focuses on the status and justification, whereas CycloneDX includes more detailed vulnerability data (like CVSS scores).

For consumers, VEX is easier to parse because it is a single-purpose document. For producers, it is simpler to generate than a full vulnerability report.

Costs and Effort of Maintaining VEX

Maintaining VEX documents has a real cost: you need to track vulnerabilities in every component, investigate each one, and update documents when statuses change. The effort is proportional to the number of components and the frequency of vulnerability disclosures. Automating the initial generation using SBOM data and vulnerability scanners can reduce the burden, but human analysis is still needed for justifications that require context (e.g., reachability).

There is no monetary cost to use the standard itself, but there is a cost in time and expertise. For small teams, it may be practical to focus on high-risk components first.

Safety and Accuracy Considerations

Accuracy is paramount: an incorrect justification can lead a consumer to ignore a real vulnerability, creating a security hole. Always verify that the justification matches the actual product behavior. For example, do not claim vulnerable_code_not_reachable if the code is reachable via a network interface.

Also, ensure that the VEX document is signed or has integrity checks (CSAF supports digital signatures) to prevent tampering. Consumers should validate the document against the official schema before trusting it.

Frequently Asked Questions

What is the difference between VEX and an SBOM?

An SBOM (Software Bill of Materials) lists all components in a product. A VEX document tells you whether each component’s known vulnerabilities are actually exploitable in that product. They are complementary: SBOM gives you the inventory, VEX gives you the status.

Can VEX be used for hardware or firmware?

Yes, VEX is product-agnostic. Any product that contains components with known vulnerabilities can have a VEX document, including hardware devices and firmware.

How often should I update a VEX document?

There is no fixed rule, but you should update it whenever a vulnerability’s status changes (e.g., a new CVE is published, or a patch is released). In practice, many organizations update on a regular cadence (e.g., weekly) or when a new vulnerability is disclosed.

Is VEX mandatory for compliance?

VEX is not mandatory under most regulations, but it is recommended by cybersecurity frameworks like NIST and is increasingly required by government procurement (e.g., US Executive Order 14028). Check your specific compliance requirements.

What if I don’t know the status of a vulnerability?

You can use the status under_investigation to indicate that you are still analyzing it. This is a valid status and does not require a justification. You should update it as soon as you reach a conclusion.

Can I use VEX for vulnerabilities without a CVE?

Yes, VEX is not limited to CVEs. You can reference any vulnerability identifier, such as a bug ID or an internal tracking number, as long as it is unique and consistent.

Related

• How to Archive a Webpage to the Internet Archive
• How to Fisch Events Schedule: Full Guide
• Future-Proof Finance Career: Automation Roadmap

in t | Time to update (minutes) | min | 10 | 1
in n | Number of components | - | 100 | 1
out per_min | Documents per minute | docs/min | 60 / t | 2
out total_docs | Documents updated | docs | 60 / t * n | 0