Getting vulnerabilities and metadata for images

Container Analysis provides vulnerability information and other types of metadata for the container images in Container Registry or Artifact Registry. The metadata is stored as notes. An occurrence is created for each instance of a note associated with an image. See Pricing for pricing information.

This page describes how to view and filter notes and occurrences.

Before you begin

Connectez-vous à votre compte Google.
Si vous n'en possédez pas déjà un, vous devez en créer un.

Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

Accéder à la page de sélection du projet

Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier que la facturation est activée pour votre projet.

Activez l'API Container Scanning.
Activer l'API

Installez et initialisez le SDK Cloud.

Viewing vulnerabilities and other occurrences

You can view occurrences for your images in Container Registry or Artifact Registry using Cloud Console, gcloud command-line tool, or the Container Analysis API. If an image has vulnerabilities, you can then obtain the details.

Viewing occurrences in Google Cloud Console

To view occurrences for an image:

Go the list of images.
Artifact Registry
1. Open the Repositories page.
  
  Open the Repositories page
2. In the repository list, click the repository that contains the image.
Container Registry
Open the Repositories page.

Open the Repositories page
Click on the image name.

Vulnerability totals for the images are displayed in the Vulnerabilities column.
To view the list of vulnerabilities for an image, click the link in the Vulnerabilities column.

The vulnerability list shows the severity, availability of a fix, and the name of the package that contains the vulnerability.
To learn more about a specific vulnerability from the vulnerability source, click the link in the Documentation column.

Viewing occurrences using gcloud

To view occurrences for an image, run the following command:

Artifact Registry

gcloud artifacts docker images list --show-occurrences \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID

where:

LOCATION is the regional or multi-regional location of the repository.
PROJECT_ID is your Google Cloud Console project ID.
REPOSITORY is the name of the repository where the image is stored.
IMAGE_ID is the name of the image in the repository. You cannot specify an image tag with this command.

By default, the command returns the 10 most recent images. To show a different number of images, use the --show-occurrences-from flag. For example, this command returns the 25 most recent images.

gcloud artifacts docker images list --show-occurrences-from=25 \
us-central1-docker.pkg.dev/my-project/my-repo/my-image

Container Registry

gcloud container images list-tags \
HOSTNAME/PROJECT_ID/IMAGE_ID

where:

HOSTNAME is the multi-regional hostname:
- gcr.io
- asia.gcr.io
- eu.gcr.io
- us.gcr.io
PROJECT_ID is the ID of the project containing the images.
IMAGE_ID is the ID of the image for which you want to view vulnerabilities. You cannot specify an image tag with this command.

By default, the command returns the 10 most recent images. To show a different number of images, use the --show-occurrences-from flag. For example, this command returns the 25 most recent images.

gcloud container images list-tags --show-occurrences-from=25 \
gcr.io/my-project/my-image

To view information about a tag or a layer:

Artifact Registry

gcloud artifacts docker images describe \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID:TAG

gcloud artifacts docker images describe \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@sha256:HASH

where:

LOCATION is the regional or multi-regional location of the repository.
PROJECT_ID is your Google Cloud Console project ID.
REPOSITORY is the name of the repository where the image is stored.
IMAGE_ID is the name of the image in the repository.
TAG is the image tag about which you want to get information.
HASH is the image digest.

Container Registry

gcloud container images describe HOSTNAME/PROJECT_ID/IMAGE_ID:TAG

gcloud container images describe HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH

where:

HOSTNAME is the multi-regional hostname:
- gcr.io
- asia.gcr.io
- eu.gcr.io
- us.gcr.io
PROJECT_ID is the ID of the project containing the images.
IMAGE_ID is the ID of the image for which you want to view vulnerabilities.
TAG is the image tag about which you want to get information.
HASH is the image digest.

To view vulnerabilities for an image tag or a layer:

Artifact Registry

gcloud artifacts docker images describe \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID:TAG \
--show-package-vulnerability

gcloud artifacts docker images describe \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@sha256:HASH \
--show-package-vulnerability

Container Registry

gcloud container images describe HOSTNAME/PROJECT_ID/IMAGE_ID:TAG \
--show-package-vulnerability

gcloud container images describe HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH \
--show-package-vulnerability

To filter the vulnerability occurrences:

Artifact Registry

gcloud artifacts docker images list --show-occurrences \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID --occurrence-filter=FILTER_EXPRESSION

where:

LOCATION is the regional or multi-regional location of the repository.
PROJECT_ID is your Google Cloud Console project ID.
REPOSITORY is the name of the repository where the image is stored.
IMAGE_ID is the name of the image in the repository.
FILTER_EXPRESSION is a sample filter expression in the format explained in Filtering vulnerability occurrences.

Container Registry

gcloud container images list-tags \
HOSTNAME/PROJECT_ID/IMAGE_ID --occurrence-filter=FILTER_EXPRESSION

where:

HOSTNAME is the multi-regional hostname:
- gcr.io
- asia.gcr.io
- eu.gcr.io
- us.gcr.io
PROJECT_ID is the ID of the project containing the images.
IMAGE_ID is the ID of the image for which you want to view vulnerability occurrences.
FILTER_EXPRESSION is a sample filter expression in the format explained in Filtering vulnerability occurrences.

Viewing occurrences using the API or code

To view occurrences for an image, use the appropriate snippet. The code snippets specify URLs for images in Container Registry. If you are using Artifact Registry, specify images with a URL in the format:

LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID

API

Using cURL

To get a list of occurrences in your project:

 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

To get a summary of vulnerabilities in your project:

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

To get an occurrence:

 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

Java

To learn how to install and use the client library for Container Analysis, see the Container Analysis Client Libraries. For more information, see the Container Analysis Java API reference documentation.

View on GitHub Feedback

import com.google.cloud.devtools.containeranalysis.v1.ContainerAnalysisClient;
import io.grafeas.v1.GrafeasClient;
import io.grafeas.v1.Occurrence;
import io.grafeas.v1.ProjectName;
import java.io.IOException;
import java.lang.InterruptedException;

public class OccurrencesForImage {
  // Retrieves all the Occurrences associated with a specified image
  // Here, all Occurrences are simply printed and counted
  public static int getOccurrencesForImage(String resourceUrl, String projectId)
      throws IOException, InterruptedException {
    // String resourceUrl = "https://gcr.io/project/image@sha256:123";
    // String projectId = "my-project-id";
    final String projectName = ProjectName.format(projectId);
    final String filterStr = String.format("resourceUrl=\"%s\"", resourceUrl);

    // Initialize client that will be used to send requests. After completing all of your requests, 
    // call the "close" method on the client to safely clean up any remaining background resources.
    GrafeasClient client = ContainerAnalysisClient.create().getGrafeasClient();
    int i = 0;
    for (Occurrence o : client.listOccurrences(projectName, filterStr).iterateAll()) {
      // Write custom code to process each Occurrence here
      System.out.println(o.getName());
      i = i + 1;
    }
    return i;
  }
}

Go

To learn how to install and use the client library for Container Analysis, see the Container Analysis Client Libraries. For more information, see the Container Analysis Go API reference documentation.

View on GitHub Feedback


import (
	"context"
	"fmt"
	"io"

	containeranalysis "cloud.google.com/go/containeranalysis/apiv1"
	"google.golang.org/api/iterator"
	grafeaspb "google.golang.org/genproto/googleapis/grafeas/v1"
)

// getOccurrencesForImage retrieves all the Occurrences associated with a specified image.
// Here, all Occurrences are simply printed and counted.
func getOccurrencesForImage(w io.Writer, resourceURL, projectID string) (int, error) {
	// Use this style of URL when you use Google Container Registry.
	// resourceURL := "https://gcr.io/my-project/my-repo/my-image"
	// Use this style of URL when you use Google Artifact Registry.
	// resourceURL := "https://LOCATION-docker.pkg.dev/my-project/my-repo/my-image"
	ctx := context.Background()
	client, err := containeranalysis.NewClient(ctx)
	if err != nil {
		return -1, fmt.Errorf("NewClient: %v", err)
	}
	defer client.Close()

	req := &grafeaspb.ListOccurrencesRequest{
		Parent: fmt.Sprintf("projects/%s", projectID),
		Filter: fmt.Sprintf("resourceUrl=%q", resourceURL),
	}
	it := client.GetGrafeasClient().ListOccurrences(ctx, req)
	count := 0
	for {
		occ, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return -1, fmt.Errorf("occurrence iteration error: %v", err)
		}
		// Write custom code to process each Occurrence here.
		fmt.Fprintln(w, occ)
		count = count + 1
	}
	return count, nil
}

Node.js

To learn how to install and use the client library for Container Analysis, see the Container Analysis Client Libraries. For more information, see the Container Analysis Node.js API reference documentation.

View on GitHub Feedback

/**
 * TODO(developer): Uncomment these variables before running the sample
 */
// const projectId = 'your-project-id', // Your GCP Project ID
// If you are using Google Container Registry
// const imageUrl = 'https://gcr.io/my-project/my-repo/my-image:123' // Image to attach metadata to
// If you are using Google Artifact Registry
// const imageUrl = 'https://LOCATION-docker.pkg.dev/my-project/my-repo/my-image:123' // Image to attach metadata to

// Import the library and create a client
const {ContainerAnalysisClient} = require('@google-cloud/containeranalysis');
const client = new ContainerAnalysisClient();

const formattedParent = client.getGrafeasClient().projectPath(projectId);

// Retrieves all the Occurrences associated with a specified image
const [occurrences] = await client.getGrafeasClient().listOccurrences({
  parent: formattedParent,
  filter: `resourceUrl = "${imageUrl}"`,
});

if (occurrences.length) {
  console.log(`Occurrences for ${imageUrl}`);
  occurrences.forEach(occurrence => {
    console.log(`${occurrence.name}:`);
  });
} else {
  console.log('No occurrences found.');
}

Ruby

To learn how to install and use the client library for Container Analysis, see the Container Analysis Client Libraries. For more information, see the Container Analysis Ruby API reference documentation.

View on GitHub Feedback

# resource_url = "The URL of the resource associated with the occurrence."
#                # e.g. https://gcr.io/project/image@sha256:123"
# project_id   = "The Google Cloud project ID of the occurrences to retrieve"

require "google/cloud/container_analysis"

# Initialize the client
client = Google::Cloud::ContainerAnalysis.container_analysis.grafeas_client

parent = client.project_path project: project_id
filter = "resourceUrl = \"#{resource_url}\""
count = 0
client.list_occurrences(parent: parent, filter: filter).each do |occurrence|
  # Process occurrence here
  puts occurrence
  count += 1
end
puts "Found #{count} occurrences"

Python

To learn how to install and use the client library for Container Analysis, see the Container Analysis Client Libraries. For more information, see the Container Analysis Python API reference documentation.

View on GitHub Feedback

def get_occurrences_for_image(resource_url, project_id):
    """Retrieves all the occurrences associated with a specified image.
    Here, all occurrences are simply printed and counted."""
    # resource_url = 'https://gcr.io/my-project/my-image@sha256:123'
    # project_id = 'my-gcp-project'

    from google.cloud.devtools import containeranalysis_v1

    filter_str = 'resourceUrl="{}"'.format(resource_url)
    client = containeranalysis_v1.ContainerAnalysisClient()
    grafeas_client = client.get_grafeas_client()
    project_name = f"projects/{project_id}"

    response = grafeas_client.list_occurrences(parent=project_name,
                                               filter=filter_str)
    count = 0
    for o in response:
        # do something with the retrieved occurrence
        # in this sample, we will simply count each one
        count += 1
    return count

Filtering occurrences

You can use filter strings in the gcloud commands and the Container Analysis API to filter occurrences before viewing them. The following sections describe the supported search filters.

Viewing discovery occurrences

When an image is initially pushed to the Container Registry, it creates a discovery occurrence, which contains information about the initial scan of the container image.

To retrieve the discovery occurrence for an image, use the following filter expression:

kind="DISCOVERY" AND resourceUrl="RESOURCE_URL"

The following snippet shows how to use the above filter expression to view discovery occurrences for an image. The code snippets specify URLs for images in Container Registry. If you are using Artifact Registry, specify images with a URL in the format:

LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID

gcloud

To view discovery occurrences for an image:

In this case the expression is not used directly in the command, but the same information is passed as arguments:

Artifact Registry:

gcloud artifacts docker images list --show-occurrences \
--occurrence-filter='kind="DISCOVERY"' --format=json \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID

Container Registry:

gcloud container images list-tags \
--occurrence-filter='kind="DISCOVERY"' --format=json HOSTNAME/PROJECT_ID/IMAGE_ID

API

To retrieve the discovery occurrence, the above filter expression should be URL encoded and embedded in a GET request as follows:

GET https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences?filter=kind%3D%22DISCOVERY%22%20AND%20resourceUrl%3D%22ENCODED_RESOURCE_URL%22

See projects.occurrences.get API endpoint for more details.

Java

View on GitHub Feedback

import com.google.cloud.devtools.containeranalysis.v1.ContainerAnalysisClient;
import io.grafeas.v1.GrafeasClient;
import io.grafeas.v1.Occurrence;
import io.grafeas.v1.ProjectName;
import java.io.IOException;
import java.lang.InterruptedException;

public class GetDiscoveryInfo {
  // Retrieves and prints the Discovery Occurrence created for a specified image
  // The Discovery Occurrence contains information about the initial scan on the image
  public static void getDiscoveryInfo(String resourceUrl, String projectId) 
      throws IOException, InterruptedException {
    // String resourceUrl = "https://gcr.io/project/image@sha256:123";
    // String projectId = "my-project-id";
    String filterStr = "kind=\"DISCOVERY\" AND resourceUrl=\"" + resourceUrl + "\"";
    final String projectName = ProjectName.format(projectId);

    // Initialize client that will be used to send requests. After completing all of your requests, 
    // call the "close" method on the client to safely clean up any remaining background resources.
    GrafeasClient client = ContainerAnalysisClient.create().getGrafeasClient();
    for (Occurrence o : client.listOccurrences(projectName, filterStr).iterateAll()) {
      System.out.println(o);
    }
  }
}

Go

View on GitHub Feedback


import (
	"context"
	"fmt"
	"io"

	containeranalysis "cloud.google.com/go/containeranalysis/apiv1"
	"google.golang.org/api/iterator"
	grafeaspb "google.golang.org/genproto/googleapis/grafeas/v1"
)

// getDiscoveryInfo retrieves and prints the Discovery Occurrence created for a specified image.
// The Discovery Occurrence contains information about the initial scan on the image.
func getDiscoveryInfo(w io.Writer, resourceURL, projectID string) error {
	// Use this style of URL when you use Google Container Registry.
	// resourceURL := "https://gcr.io/my-project/my-repo/my-image"
	// Use this style of URL when you use Google Artifact Registry.
	// resourceURL := "https://LOCATION-docker.pkg.dev/my-project/my-repo/my-image"
	ctx := context.Background()
	client, err := containeranalysis.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("NewClient: %v", err)
	}
	defer client.Close()

	req := &grafeaspb.ListOccurrencesRequest{
		Parent: fmt.Sprintf("projects/%s", projectID),
		Filter: fmt.Sprintf(`kind="DISCOVERY" AND resourceUrl=%q`, resourceURL),
	}
	it := client.GetGrafeasClient().ListOccurrences(ctx, req)
	for {
		occ, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("occurrence iteration error: %v", err)
		}
		fmt.Fprintln(w, occ)
	}
	return nil
}

Node.js

View on GitHub Feedback

/**
 * TODO(developer): Uncomment these variables before running the sample
 */
// const projectId = 'your-project-id', // Your GCP Project ID
// If you are using Google Container Registry
// const imageUrl = 'https://gcr.io/my-project/my-repo/my-image:123' // Image to attach metadata to
// If you are using Google Artifact Registry
// const imageUrl = 'https://LOCATION-docker.pkg.dev/my-project/my-repo/my-image:123' // Image to attach metadata to

// Import the library and create a client
const {ContainerAnalysisClient} = require('@google-cloud/containeranalysis');
const client = new ContainerAnalysisClient();

const formattedParent = client.getGrafeasClient().projectPath(projectId);
// Retrieves and prints the Discovery Occurrence created for a specified image
// The Discovery Occurrence contains information about the initial scan on the image
const [occurrences] = await client.getGrafeasClient().listOccurrences({
  parent: formattedParent,
  filter: `kind = "DISCOVERY" AND resourceUrl = "${imageUrl}"`,
});

if (occurrences.length > 0) {
  console.log(`Discovery Occurrences for ${imageUrl}`);
  occurrences.forEach(occurrence => {
    console.log(`${occurrence.name}:`);
  });
} else {
  console.log('No occurrences found.');
}

Ruby

View on GitHub Feedback

# resource_url = "The URL of the resource associated with the occurrence."
#                # e.g. https://gcr.io/project/image@sha256:123
# project_id   = "The Google Cloud project ID of the occurrences to retrieve"

require "google/cloud/container_analysis"

# Initialize the client
client = Google::Cloud::ContainerAnalysis.container_analysis.grafeas_client

parent = client.project_path project: project_id
filter = "kind = \"DISCOVERY\" AND resourceUrl = \"#{resource_url}\""
client.list_occurrences(parent: parent, filter: filter).each do |occurrence|
  # Process discovery occurrence here
  puts occurrence
end

Python

View on GitHub Feedback

def get_discovery_info(resource_url, project_id):
    """Retrieves and prints the discovery occurrence created for a specified
    image. The discovery occurrence contains information about the initial
    scan on the image."""
    # resource_url = 'https://gcr.io/my-project/my-image@sha256:123'
    # project_id = 'my-gcp-project'

    from google.cloud.devtools import containeranalysis_v1

    filter_str = 'kind="DISCOVERY" AND resourceUrl="{}"'.format(resource_url)
    client = containeranalysis_v1.ContainerAnalysisClient()
    grafeas_client = client.get_grafeas_client()
    project_name = f"projects/{project_id}"
    response = grafeas_client.list_occurrences(parent=project_name,
                                               filter_=filter_str)
    for occ in response:
        print(occ)

Viewing vulnerability occurrences

To view vulnerability occurrences for a specific image, create a query with a filter expression:

kind="VULNERABILITY" AND resourceUrl="RESOURCE_URL"

The following snippet shows how to retrieve a list of vulnerability occurrences for an image. The code snippets specify URLs for images in Container Registry. If you are using Artifact Registry, specify images with a URL in the format:

LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID

gcloud

To view vulnerability occurrences for an image:

In this case the expression is not used directly in the command, but the same information is passed as arguments:

Artifact Registry

gcloud artifacts docker images list --show-occurrences \
--occurrence-filter='kind="VULNERABILITY"' --format=json \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID

Container Registry

gcloud container images list-tags \
--occurrence-filter='kind="VULNERABILITY"' --format=json HOSTNAME/PROJECT_ID/IMAGE_ID

API

The desired resource URL should be URL encoded, and embedded in a GET request as follows:

GET https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences?filter=kind%3D%22VULNERABILITY%22%20AND%20resourceUrl%3D%22ENCODED_RESOURCE_URL%22

See projects.occurrences.get API endpoint for more details.

Java

View on GitHub Feedback

import com.google.cloud.devtools.containeranalysis.v1.ContainerAnalysisClient;
import io.grafeas.v1.GrafeasClient;
import io.grafeas.v1.Occurrence;
import io.grafeas.v1.ProjectName;
import java.io.IOException;
import java.util.LinkedList;
import java.util.List;

public class VulnerabilityOccurrencesForImage {
  // Retrieve a list of vulnerability occurrences assoviated with a resource
  public static List<Occurrence> findVulnerabilityOccurrencesForImage(String resourceUrl, 
      String projectId) throws IOException {
    // String resourceUrl = "https://gcr.io/project/image@sha256:123";
    // String projectId = "my-project-id";
    final String projectName = ProjectName.format(projectId);
    String filterStr = String.format("kind=\"VULNERABILITY\" AND resourceUrl=\"%s\"", resourceUrl);

    // Initialize client that will be used to send requests. After completing all of your requests, 
    // call the "close" method on the client to safely clean up any remaining background resources.
    GrafeasClient client = ContainerAnalysisClient.create().getGrafeasClient();
    LinkedList<Occurrence> vulnerabilitylist = new LinkedList<Occurrence>();
    for (Occurrence o : client.listOccurrences(projectName, filterStr).iterateAll()) {
      vulnerabilitylist.add(o);
    }
    return vulnerabilitylist;
  }
}

Go

View on GitHub Feedback


import (
	"context"
	"fmt"

	containeranalysis "cloud.google.com/go/containeranalysis/apiv1"
	"google.golang.org/api/iterator"
	grafeaspb "google.golang.org/genproto/googleapis/grafeas/v1"
)

// findVulnerabilityOccurrencesForImage retrieves all vulnerability Occurrences associated with a resource.
func findVulnerabilityOccurrencesForImage(resourceURL, projectID string) ([]*grafeaspb.Occurrence, error) {
	// Use this style of URL when you use Google Container Registry.
	// resourceURL := "https://gcr.io/my-project/my-repo/my-image"
	// Use this style of URL when you use Google Artifact Registry.
	// resourceURL := "https://LOCATION-docker.pkg.dev/my-project/my-repo/my-image"
	ctx := context.Background()
	client, err := containeranalysis.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("NewClient: %v", err)
	}
	defer client.Close()

	req := &grafeaspb.ListOccurrencesRequest{
		Parent: fmt.Sprintf("projects/%s", projectID),
		Filter: fmt.Sprintf("resourceUrl = %q kind = %q", resourceURL, "VULNERABILITY"),
	}

	var occurrenceList []*grafeaspb.Occurrence
	it := client.GetGrafeasClient().ListOccurrences(ctx, req)
	for {
		occ, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return nil, fmt.Errorf("occurrence iteration error: %v", err)
		}
		occurrenceList = append(occurrenceList, occ)
	}

	return occurrenceList, nil
}

Node.js

View on GitHub Feedback

/**
 * TODO(developer): Uncomment these variables before running the sample
 */
// const projectId = 'your-project-id', // Your GCP Project ID
// If you are using Google Container Registry
// const imageUrl = 'https://gcr.io/my-project/my-repo/my-image:123' // Image to attach metadata to
// If you are using Google Artifact Registry
// const imageUrl = 'https://LOCATION-docker.pkg.dev/my-project/my-repo/my-image:123' // Image to attach metadata to

// Import the library and create a client
const {ContainerAnalysisClient} = require('@google-cloud/containeranalysis');
const client = new ContainerAnalysisClient();

const formattedParent = client.getGrafeasClient().projectPath(projectId);

// Retrieve a list of vulnerability occurrences assoviated with a resource
const [occurrences] = await client.getGrafeasClient().listOccurrences({
  parent: formattedParent,
  filter: `kind = "VULNERABILITY" AND resourceUrl = "${imageUrl}"`,
});

if (occurrences.length) {
  console.log(`All Vulnerabilities for ${imageUrl}`);
  occurrences.forEach(occurrence => {
    console.log(`${occurrence.name}:`);
  });
} else {
  console.log('No occurrences found.');
}

Ruby

View on GitHub Feedback

# resource_url = "The URL of the resource associated with the occurrence
#                e.g. https://gcr.io/project/image@sha256:123"
# project_id   = "The Google Cloud project ID of the vulnerabilities to find"

require "google/cloud/container_analysis"

# Initialize the client
client = Google::Cloud::ContainerAnalysis.container_analysis.grafeas_client

parent = client.project_path project: project_id
filter = "resourceUrl = \"#{resource_url}\" AND kind = \"VULNERABILITY\""
client.list_occurrences parent: parent, filter: filter

Python

View on GitHub Feedback

def find_vulnerabilities_for_image(resource_url, project_id):
    """"Retrieves all vulnerability occurrences associated with a resource."""
    # resource_url = 'https://gcr.io/my-project/my-image@sha256:123'
    # project_id = 'my-gcp-project'

    from google.cloud.devtools import containeranalysis_v1

    client = containeranalysis_v1.ContainerAnalysisClient()
    grafeas_client = client.get_grafeas_client()
    project_name = f"projects/{project_id}"

    filter_str = 'kind="VULNERABILITY" AND resourceUrl="{}"'\
        .format(resource_url)
    return list(grafeas_client.list_occurrences(parent=project_name, filter=filter_str))

Viewing occurrences of a specific type

In the two previous examples the only difference between the filter expressions is the value of kind, which identifies the type of occurrence. Use this field to limit the list of occurrences to a particular type, such as a vulnerability or deployment.

To retrieve occurrences for a specific image, use this filter expression:

kind="NOTE_KIND" AND resourceUrl="RESOURCE_URL"

where:

NOTE_KIND is the kind of note.
- For example, use the kind DISCOVERY to list discovery occurrences. These are created for images when they are initially pushed to the Container Registry.
- To list vulnerability occurrences, use the kind VULNERABILITY.
RESOURCE_URL is the complete URL of the image https://HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH

The filter expression to retrieve occurrences of a specific kind across many images is:

kind="NOTE_KIND" AND has_prefix(resourceUrl, "RESOURCE_URL_PREFIX")

where:

RESOURCE_URL_PREFIX is the URL prefix for some images
- To list for all version of an image: https://HOSTNAME/PROJECT_ID/IMAGE_ID@
- To list for all images in a project: https://HOSTNAME/PROJECT_ID/

Viewing images associated with a specific note

You can retrieve a list of resources that are associated with a specific note ID. For example, you can list images with a specific CVE vulnerability.

To list all images within a project that are associated with a particular note, use the following filter expression:

noteProjectId="PROVIDER_PROJECT_ID" AND noteId="NOTE_ID"

To check a specific image for a specific note, use the following filter expression:

resourceUrl="RESOURCE_URL" AND noteProjectId="PROVIDER_PROJECT_ID" \
    AND noteId="NOTE_ID"

where:

PROVIDER_PROJECT_ID is the ID of the provider project. For example, goog-vulnz provides the default vulnerability analysis.
NOTE_ID is the ID of the note. Security related notes are often formatted as CVE-2019-12345.
RESOURCE_URL is the complete URL of the image https://HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH

For example, to check for all images that have an occurrence of CVE-2017-16231 as analyzed by Google, use the following filter expression:

noteProjectId="goog-vulnz" AND noteId="CVE-2017-16231"

What's next

Use Pub/Sub notifications to get notifications about vulnerabilities and other metadata.
Kritis Signer and Voucher allow you create Binary Authorization attestations as part of your build pipeline. These tools can create Binary Authorization attestations based on vulnerability scanning results. For more information, see Creating attestations with Kritis Signer or Creating attestations with Voucher.