> [!WARNING]
>
> **Preview**
>
>
> This feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the
> [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

This document describes how to create
[Vulnerability Exploitability eXchange (VEX)](https://www.cisa.gov/sites/default/files/2023-04/minimum-requirements-for-vex-508c.pdf) 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. Have container images stored in an Artifact Registry repository, or [create a repository](https://docs.cloud.google.com/artifact-registry/docs/repositories/create-repos) and [push your images](https://docs.cloud.google.com/artifact-registry/docs/docker/pushing-and-pulling).

<br />

## 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:

- To create and update notes: [Container Analysis Notes Editor](https://docs.cloud.google.com/iam/docs/roles-permissions/containeranalysis#containeranalysis.notes.editor) (`roles/containeranalysis.notes.editor`)


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## Create VEX statements

Artifact Analysis supports the
[Common Security Advisory Format (CSAF)](https://oasis-open.github.io/csaf-documentation/) 2.0 standard in JSON. To
produce a new VEX statement, use the [CSAF schema](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/json_schema/csaf_json_schema.json).

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

- <var translate="no">PRODUCT_NAME</var> 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.
- <var translate="no">LOCATION</var> is the region or multi-regional location of your repository.
- <var translate="no">PROJECT_ID</var> is the ID for the project that contains your repository.
- <var translate="no">REPO_NAME</var> is the name of your Docker repository in Artifact Registry.
- <var translate="no">IMAGE_NAME</var> is the name of the image.
- <var translate="no">CVE_ID</var> is the identifier for the vulnerability, such as `CVE-2017-11164`.
- <var translate="no">PRODUCT_STATUS</var> 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](https://docs.cloud.google.com/artifact-analysis/docs/upload-vex) your existing VEX statements or VEX statements provided by other publishers.
- Prioritize vulnerability issues using VEX. Learn how to [view VEX statements](https://docs.cloud.google.com/artifact-analysis/docs/view-vex) and filter vulnerabilities by VEX status.