Investigate vulnerabilities

When you hear about a new vulnerability, acting quickly is important. This page provides a list of essential API calls and filters that are pre-constructed for you. Use these API calls to retrieve scan results from Artifact Analysis and gather information about the status of your artifacts.

This content is designed for use with automatic scanning metadata. If your images have exceeded the 30-day continuous analysis window, you can run a new scan by pushing to Artifact Registry again.

All of the examples on this page access the API directly, but you can also use the Container Analysis client libraries, or gcloud commands.

Required permissions

All of these examples use the ListOccurrences API method. To call this method, you will need the Container Analysis Occurrences Viewer (roles/containeranalysis.occurrences.viewer) role for the project that you're analyzing.

  • If you are analyzing projects that you own, you already have the required permissions.

  • If you are analyzing projects that you do not own, use the IAM access management instructions to grant permissions.

For more information on types of access for providers and customers using Artifact Analysis, see permissions.

View all the vulnerability metadata for an image

Use the filter KIND="VULNERABILITY" with your project ID and the full resource URL for your image including https://:

  curl -G -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "filter=(kind=\"VULNERABILITY\" AND resourceUrl=\"RESOURCE_URL\")" \
    https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences

Replace the following:

Output includes a vulnerability list with details such as the severity, mitigation options if available, and the name of the package that contains the vulnerability.

Check for a specific vulnerability in a project

In most cases, Artifact Analysis uses the CVE ID as the vulnerability identifier. However, there are some vulnerabilities listed in the GitHub Advisory Database that don't have an associated CVE ID. In this case Artifact Analysis uses the GHSA ID instead.

The vulnerability ID is included as part of the noteName field. It starts with the prefix CVE for CVE IDs, and GHSA for GHSA IDs. For example, if the following output is the result of running the command to view all the vulnerabilities for an image:

vulnerabilities:
  HIGH:
  - name: projects/my-project/occurrences/1234fh2c-699a-462f-b920-93a80f56f544
    resourceUri: https://my_region-docker.pkg.dev/my-project/my-repo/my-image@sha256:8a1a79b587797c5164ec95977cf7aaaa828694a615947bdaed6a327d5b6a17bb
    noteName: projects/goog-vulnz/notes/CVE-2021-32798
    kind: VULNERABILITY
    ...
  - name: projects/my-project/occurrences/OCCURRENCE_ID
    resourceUri: https://my_region-docker.pkg.dev/my-project/my-repo/my-image@sha256:8a1a79b587797c5164ec95977cf7aaaa828694a615947bdaed6a327d5b6a17bb
    noteName: projects/goog-vulnz/notes/GHSA-884p-74jh-xrg2
    kind: VULNERABILITY
    ...

The first vulnerability has the ID CVE-2021-32798, the second one has the ID GHSA-884p-74jh-xrg2.

  1. Get the identifier for the vulnerability.

  2. Use the CVE ID or GHSA ID in the following filter expression to retrieve a list of affected images:

  curl -G -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "filter=(noteProjectId=\"goog-vulnz\" AND noteId=\"VULN_ID\")" \
    https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences

Replace the following:

  • PROJECT_ID is your Google Cloud project ID. To view a list of your projects, you can use gcloud projects list.
  • VULN_ID is the ID of the vulnerability. The CVE ID or GHSA ID number, such as CVE-2021-32798 or GHSA-884p-74jh-xrg2.

For example, the following call demonstrates how to retrieve scan results for images in your project that have an occurrence of CVE-2023-23915:

  curl -G -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "filter=(noteProjectId=\"goog-vulnz\" AND noteId=\"CVE-2023-23915\")" \
    https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences

Replace the following:

  • PROJECT_ID is your Google Cloud project ID. To view a list of your projects, you can use gcloud projects list.

Search for vulnerabilities across multiple projects

Use curl globbing to make queries across projects.

For example, the following snippet sets a variable to contain two project IDs, then sends an API call for each project to search for occurrences.

  PROJECT_IDS="PROJECT_ID_1,PROJECT_ID_2"

  curl -G -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://containeranalysis.googleapis.com/v1/projects/{$PROJECT_IDS}/occurrences"

Replace the following:

  • PROJECT_ID_1 is the Google Cloud project ID for the first project you want to examine.
  • PROJECT_ID_2 is the Google Cloud project ID for the second project you want to examine.

If you need to find project IDs, you can view a list of your projects using gcloud projects list.

There isn't support for a single API call across multiple projects.

Get a broad understanding of all the metadata for a project

Request all occurrences associated with your project ID:

  curl -X GET -H "Content-Type: application/json" -H \
    "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences

Replace the following:

  • PROJECT_ID is your Google Cloud project ID.

Output includes vulnerability information and other supported metadata types associated with your project. For example, your project might have build details or attestations.

Query a specific occurrence for all available details

To get more details about an individual occurrence, use the following request.

For example, if you're using Pub/Sub to get notifications about vulnerability occurrences, Pub/Sub sends basic details to help you identify the occurrence that changed and when. The payload includes an occurrence ID. You can use the occurrence ID to query for details to help you triage issues and take action.

  curl -X GET -H "Content-Type: application/json" -H \
    "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences/OCCURRENCE_ID

Replace the following:

  • PROJECT_ID is your Google Cloud project ID.
  • OCCURRENCE_ID is a numerical value from the occurrences list from the previous example. Or, if you receive a message from Pub/Sub, use the numerical value at the end of the URL in that message.

Output includes information such as package type, vulnerability severity, CVSS score, and information on fixes, if available.

What's next