View VEX status

This document describes how to view the Vulnerability Exploitability eXchange (VEX) statements stored in Artifact Analysis and filter vulnerabilities using VEX status.

Security and policy enforcers can use these features to prioritize among security issue mitigation tasks. You can also use VEX data to attest to the composition of your artifacts to help your organization meet regulatory requirements.

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.

View VEX status in the Google Cloud console

To view VEX information for container images stored in Artifact Registry:

  1. Open the Artifact Registry Repositories page.

    Open the Repositories page

    The page displays a list of your repositories.

  2. In the repositories list, click a repository name.

  3. In the images list, click an image name.

    A list of the image digests opens.

  4. In the digests list, click a digest name.

    A digest details page opens with a row of tabs. By default, the Overview tab is open.

  5. In the row of tabs, select the Vulnerabilities tab.

    The page displays a Scan results overview with a VEX Status section.

    The VEX Status summary section displays the number of packages that are categorized by each VEX status type. To see all packages with a specific VEX status, click the number beside the status type.

    The Vulnerabilities tab also displays the VEX status for each package is in the vulnerabilities list.

    To filter the vulnerabilities list:

    1. Above the vulnerabilities list, click Filter vulnerabilities.
    2. Choose a filter from the filter list.
    3. Specify the value that you want to use for filtering the list.

View VEX status in Cloud Build

If you're using Cloud Build, you can also view VEX information in the Security insights side panel within the Google Cloud console.

If you're using Cloud Build, you can view image metadata in the Security insights side panel within the Google Cloud console.

The Security insights side panel provides a high-level overview of build security information for artifacts stored in Artifact Registry. To learn more about the side panel and how you can use Cloud Build to help protect your software supply chain, see View build security insights.

View using the gcloud CLI

The following section explains how to retrieve VEX information and apply filters to limit results based on your needs.

View VEX info for a single artifact

To view uploaded VEX info, you can query the API and list notes with the note type VULNERABILITY_ASSESSMENT.

Use the following API call to request all of the vulnerability assessment notes for the specified artifact:

curl --data-urlencode "filter=(kind=\"VULNERABILITY_ASSESSMENT\" AND vulnerability_assessment.product.generic_uri=\"https://LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME@DIGEST\"" https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/notes

Where

  • LOCATION is the region or multi-regional location of your repository.
  • PROJECT_ID is the ID for the Google Cloud project where your image is stored in an Artifact Registry repository.
  • REPO_NAME is the name of the Artifact Registry repository that contains the image.
  • IMAGE_NAME is the name of the image.
  • DIGEST is the image digest, a string starting with sha256:.

Filter vulnerabilities by VEX status

Using gcloud, you can filter vulnerability metadata by VEX status. Artifact Analysis filters based on the status stored in each Grafeas vulnerability occurrence.

Run the following command to filter vulnerability occurrences based on a specified VEX status:

gcloud artifacts vulnerabilities list RESOURCE_URI \
    --occurrence-filter="vulnDetails.vex_assessment.state=\"STATUS\""

Where

  • RESOURCE_URI is the complete URL of the image, similar to https://LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@sha256:HASH.
  • STATUS is the VEX status to filter for, which can be one of the following values: known_affected, known_not_affected, under_investigation, or fixed.

For example, run the following command to filter for vulnerability occurrences with the VEX status AFFECTED:

gcloud artifacts vulnerabilities list RESOURCE_URI \
    --occurrence-filter="vulnDetails.vex_assessment.state=\"AFFECTED\""

List vulnerabilities without VEX

To identify which vulnerabilities don't yet have any VEX information associated with them, use the following gcloud command:

gcloud artifacts vulnerabilities list /
    LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME@DIGEST /--occurrence-filter="isNull(vulnDetails.vex_assessment.state)"

Where

  • LOCATION is the region or multi-regional location of your repository.
  • PROJECT_ID is the ID for the Google Cloud project where your image is stored in an Artifact Registry repository.
  • REPO_NAME is the name of the Artifact Registry repository that contains the image.
  • IMAGE_NAME is the name of the image.
  • DIGEST is the image digest, a string starting with sha256:.

Limitations

  • Uploading VEX statements is only supported for container images.
  • Uploaded VEX statements can't be exported into CSAF, OpenVex, or SPDX standards.

What's next