Create VEX statements

This document describes how to create Vulnerability Exploitability eXchange (VEX) statements.

For every container image pushed to Artifact Registry, Artifact Analysis can store an associated VEX statement. VEX is a type of security advisory that indicates whether a product is affected by a known vulnerability.

Each statement provides:

  • The publisher of the VEX Statement
  • The artifact for which the statement is written
  • The vulnerability assessment (VEX status) for any known vulnerabilities

Software publishers can create VEX statements to describe the security posture of an application. VEX statements note any vulnerabilities discovered in specific artifacts and provide context about their impact to their customers or regulatory bodies.

Security and policy enforcers can use VEX status to triage risks in their software supply chains and use VEX statements to attest to the composition of their artifacts to help organizations meet regulatory requirements.

VEX status

The VEX status indicates whether an artifact is affected by a known vulnerability.

The status can be one of:

  • Not affected: No remediation is required regarding this vulnerability.
  • Affected: Remediation actions are recommended.
  • Fixed: In this version of the product, a fix has been applied to address the vulnerability.
  • Under Investigation: The status of this product is yet to be determined. The publisher will provide an updated status in a later release.

Before you begin

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Container Analysis, Artifact Registry APIs.

    Enable the APIs

  5. Install the Google Cloud CLI.

  6. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  7. To initialize the gcloud CLI, run the following command: 

    gcloud init

  8. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  9. Verify that billing is enabled for your Google Cloud project.

  10. Enable the Container Analysis, Artifact Registry APIs.

    Enable the APIs

  11. Install the Google Cloud CLI.

  12. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  13. To initialize the gcloud CLI, run the following command: 

    gcloud init
  14. Have container images stored in an Artifact Registry repository, or create a repository and push your images.

Required roles

To get the permissions that you need to upload VEX assessments and check the VEX status of vulnerabilities, ask your administrator to grant you the following IAM roles on the project:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Create VEX statements

Artifact Analysis supports the Common Security Advisory Format (CSAF) 2.0 standard in JSON. To produce a new VEX statement, use the CSAF schema.

The following is an example of a VEX statement for an image in Artifact Registry with one cve branch for a known vulnerability.

You must define the value of the product_status for each CVE.


{
  "document": {
    "csaf_version": "2.0",
    "lang": "en-US",
    "publisher": {
      "name": "Sample-Company",
      "namespace": "https://sample-company.com"
    },
    "title": "Vex document 1.1"
  },
  "product_tree": {
    "branches": [
      {
        "name": "https://LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME",
        "product": {
          "name": "PRODUCT_NAME",
          "product_id": "IMAGE_NAME"
        }
      }
    ]
  },
  "vulnerabilities": [
    {
      "cve": "CVE_ID",
      "product_status": {
        "PRODUCT_STATUS": [
          "IMAGE_NAME"
        ]
      }
    }
  ]
}

Where

  • PRODUCT_NAME Human-readable product name for the image. Takes a string value. The value should be the product's full canonical name, including version number and other attributes.
  • LOCATION is the region or multi-regional location of your repository.
  • PROJECT_ID is the ID for the project that contains your repository.
  • REPO_NAME is the name of your Docker repository in Artifact Registry.
  • IMAGE_NAME is the name of the image.
  • CVE_ID is the identifier for the vulnerability, such as CVE-2017-11164.
  • PRODUCT_STATUS is the assessment of the security risk. Artifact Analysis supports four status types: known_affected, known_not_affected, under_investigation, and fixed.

For each vulnerability that you want to list in your VEX statement, you must create a cve branch and define the value of the product_status.

The value of the name field in product_tree.branches.name is the image URI. Including this value associates the VEX statement to a specific Docker image.

What's next

  • Upload VEX statements your existing VEX statements or VEX statements provided by other publishers.
  • Prioritize vulnerability issues using VEX. Learn how to view VEX statements and filter vulnerabilities by VEX status.