Skip to content

Export VEX

You can give your customers and authorities the VEX statements of a release as a file. Affectra exports three formats. Each file holds the current statement for every vulnerability of the release. To record statements first, see Assess findings with VEX.

Everyone in your organization can export, including the viewer role, and so can an API key. You do not have to export all three. Pick the format your reader asks for.

Open the release under Releases, then its VEX tab. Above the list there is a button for each format: OpenVEX, CycloneDX and CSAF. Affectra builds the file when you select it.

The CSAF button appears only when the release has at least one statement and your organization has set a CSAF namespace, see Set the CSAF namespace.

Format Version File name Use it when
OpenVEX 0.2.0 <release id>-openvex.json Your reader uses OpenVEX tools, or you want the simplest form.
CycloneDX VEX 1.6 <release id>-vex.cdx.json Your reader works with CycloneDX.
CSAF 2.0, profile csaf_vex 2.0 <tracking id>.json Your reader expects CSAF advisories, for example an authority.

All three use the same statements. The statuses and justifications are the ones in VEX statuses and justifications.

OpenVEX. One document for the release. Its author is your organization. Each statement names the vulnerability (with the CVEs of an advisory as aliases), the time you made it, the status, and the justification, impact statement and action statement you gave. The release is the product, identified as urn:uuid:<release id>. The same statements always give the same document.

CycloneDX VEX. One document that describes the release, with an entry for each vulnerability. Statuses become CycloneDX analysis states: Not affected is not_affected, Affected is exploitable, Fixed is resolved and Under investigation is in_triage. Justifications become the closest CycloneDX justification. The impact and action statements go into the analysis detail.

CSAF 2.0. A csaf_vex document for the release, with your organization as the publisher. Its tracking ID is your organization’s slug and the release ID, and it names the file. Its revision history has one entry for each statement you ever made, so a reader sees how your assessment changed. Remediations are always of the kind vendor_fix. Each vulnerability lists the EUVD IDs of its CVEs among its ids, with the system name EUVD. The document also has a note called Data freshness: when the release was last matched, and which vulnerability data it was checked against. That note and the generation time change with every download. The rest is the same for the same statements.

None of the documents lists your components. They say which vulnerabilities do and do not affect the release.

CSAF can also describe one vulnerability across all your releases. On the VEX tab, each statement has a CSAF advisory link. The advisory holds your current statements on that vulnerability, on its CVEs and on the advisories that carry it, over every release that has one. Each release is one product version. Which advisories carry a CVE comes from vulnerability data, which changes. The revision history only grows: a revision keeps its number, date and summary, and a statement that enters the advisory later becomes the next revision.

A CSAF document names its publisher with a web address. Under Settings, an admin enters it in CSAF namespace, the field labelled Manufacturer URL. Use an https address of your company, such as https://example.com, without a user name, query or fragment, and at most 255 characters. Use an address you control, not Affectra’s.

Until it is set, nobody can download CSAF. An admin sees a link to Settings on the VEX tab. Other members see that an admin needs to set the namespace.

Use an API key. The routes are under /v1/orgs/{org}:

Format Route
OpenVEX GET /releases/{release}/vex/openvex
CycloneDX VEX GET /releases/{release}/vex/cyclonedx
CSAF, one release GET /releases/{release}/vex/csaf
CSAF, one vulnerability GET /vulnerabilities/{id}/vex/csaf
Terminal window
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer $AFFECTRA_API_KEY" \
--output release-openvex.json \
"https://affectra.example.com/v1/orgs/acme/releases/$release/vex/openvex"

The media types are application/openvex+json, application/vnd.cyclonedx+json and application/csaf+json.

  • A release that is not in your organization gives 404.
  • The CSAF routes give 409 while no CSAF namespace is set. The release route also gives 409 for a release without statements, because a CSAF document needs at least one vulnerability. The vulnerability route gives 404 when your organization has no statement on it.
  • A browser session may be redirected with 303 to a short-lived download link. API keys always get the file directly.

OpenVEX and CycloneDX give an empty list of statements for a release that has none.