This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

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

For every container image pushed to Artifact Registry, Artifact Analysis canstore an associated VEX statement. VEX is a type of security advisory thatindicates 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 postureof an application. VEX statements note any vulnerabilities discovered inspecific artifacts and provide context about their impact to their customers orregulatory bodies.

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

VEX status

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

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 addressthe 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

Sign in to your Google Account.

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

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Container Analysis, Artifact Registry APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

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

Toinitialize the gcloud CLI, run the following command:

gcloudinit

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Container Analysis, Artifact Registry APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

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

Toinitialize the gcloud CLI, run the following command:

gcloudinit

1. Have container images stored in an Artifact Registry repository, orcreate a repository andpush 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:

• To create and update notes:Container Analysis Notes Editor (roles/containeranalysis.notes.editor)

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

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Create VEX statements

Artifact Analysis supports theCommon Security Advisory Format (CSAF) 2.0 standard in JSON. Toproduce a new VEX statement, use theCSAF schema.

The following is an example of a VEX statement for an image in Artifact Registrywith onecve branch for a known vulnerability.

You must define the value of theproduct_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 fullcanonical name, including version number and other attributes.
• LOCATION is the region or multi-regional location of yourrepository.
• PROJECT_ID is the ID for the project that contains yourrepository.
• 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 asCVE-2017-11164.
• PRODUCT_STATUS is the assessment of the security risk.Artifact Analysis supports four status types:known_affected,known_not_affected,under_investigation, andfixed.

For each vulnerability that you want to list in your VEX statement, you mustcreate acve branch and define the value of theproduct_status.

The value of thename field inproduct_tree.branches.name is the imageURI. Including this value associates the VEX statement to a specific Dockerimage.

What's next

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