Betriebssystempakete automatisch scannen

In diesem Dokument erfahren Sie, wie Sie die Container Scanning API aktivieren, ein Image an Artifact Registry pushen und eine Liste der im Image gefundenen Sicherheitslücken aufrufen.

Die Artefaktanalyse bietet Informationen zu Sicherheitslücken für die Container-Images in Artifact Registry und Container Registry (Eingestellt). Die Metadaten werden als Hinweise gespeichert. Für jede mit einem Image verknüpfte Instanz eines Hinweises wird ein Vorkommen erstellt. Weitere Informationen finden Sie in den Dokumenten Übersicht und Preise.

Wenn Sie diese API aktivieren, wird auch das Scannen von Sprachpaketen in Artifact Registry aktiviert. Unterstützte Pakettypen

Hinweise

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Artifact Registry and Container Scanning APIs.

    Enable the APIs

  5. Install the Google Cloud CLI.
  6. To initialize the gcloud CLI, run the following command:

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

    Go to project selector

  8. Make sure that billing is enabled for your Google Cloud project.

  9. Enable the Artifact Registry and Container Scanning APIs.

    Enable the APIs

  10. Install the Google Cloud CLI.
  11. To initialize the gcloud CLI, run the following command:

    gcloud init
  12. Erstellen Sie ein Docker-Repository in Artifact Registry und verschieben Sie ein Container-Image in das Repository. Wenn Sie mit Artifact Registry nicht vertraut sind, lesen Sie die Docker-Kurzanleitung.

Image-Sicherheitslücken ansehen

Artefaktanalyse scannt neue Images, sobald sie in Artifact Registry hochgeladen werden. Bei diesem Scan werden Informationen zu den Systempaketen im Container extrahiert.

Sie können Vorkommen von Sicherheitslücken für Ihre Images in der Registry mit der Google Cloud Console, der Google Cloud CLI oder der Container Analysis API ansehen. Wenn ein Image Sicherheitslücken aufweist, können Sie dann die Details abrufen.

Die Artefaktanalyse aktualisiert nur die Metadaten für Images, die in den letzten 30 Tagen per Push oder Pull übertragen wurden. Nach 30 Tagen werden die Metadaten nicht mehr aktualisiert und die Ergebnisse sind veraltet. Außerdem archiviert die Artefaktanalyse Metadaten, die seit mehr als 90 Tagen inaktiv sind. Diese Metadaten sind dann nicht mehr in der Google Cloud Console, in gcloud oder über die API verfügbar. Wenn Sie ein Image mit veralteten oder archivierten Metadaten noch einmal scannen möchten, übertragen Sie es per Pull. Das Aktualisieren von Metadaten kann bis zu 24 Stunden dauern.

Vorkommnisse in der Google Cloud Console ansehen

So rufen Sie die Sicherheitslücken in einem Bild auf:

  1. Liste der Repositories abrufen

    Zur Seite „Repositories“

  2. Klicken Sie in der Liste der Repositories auf ein Repository.

  3. Klicken Sie in der Bilderliste auf einen Bildnamen.

    Die Gesamtzahl der Sicherheitslücken für jeden Image-Digest wird in der Spalte Sicherheitslücken angezeigt.

    Screenshot eines Images mit Sicherheitslücken

  4. Wenn Sie die Liste der Sicherheitslücken für ein Image aufrufen möchten, klicken Sie auf den Link in der Spalte Vulnerabilities (Sicherheitslücken).

    Im Bereich Scanergebnisse finden Sie eine Zusammenfassung der gescannten Pakettypen, der Sicherheitslücken insgesamt, der Sicherheitslücken mit verfügbaren Lösungen, der Sicherheitslücken ohne Lösungen und des effektiven Schweregrads.

    Screenshot des Bereichs „Scanergebnisse“ mit Sicherheitslücken, Fehlerkorrekturen und effektivem Schweregrad

    In der Tabelle mit den Sicherheitslücken sind der CVE-Name (Common Vulnerabilities and Exposures) für jede gefundene Sicherheitslücke, der effektive Schweregrad, die CVSS-Punktzahl (Common Vulnerability Scoring System), Fehlerkorrekturen (falls verfügbar), der Name des Pakets, das die Sicherheitslücke enthält, und der Pakettyp aufgeführt.

    Sie können diese Dateien filtern und sortieren, um eine bestimmte Datei, ein bestimmtes Verzeichnis oder einen bestimmten Dateityp anhand der Dateiendung zu prüfen.

    In der Google Cloud Console werden in dieser Tabelle bis zu 1.200 Sicherheitslücken angezeigt. Wenn Ihr Image mehr als 1.200 Sicherheitslücken aufweist, müssen Sie gcloud oder die API verwenden, um die vollständige Liste aufzurufen.

  5. Klicken Sie auf den Namen der CVE, um Details zu einer bestimmten CVE aufzurufen.

  6. Wenn Sie Details zum Vorkommen der Sicherheitslücke wie die Versionsnummer und den betroffenen Speicherort aufrufen möchten, klicken Sie in der Zeile mit dem Namen der Sicherheitslücke auf Anzeigen oder Behoben ansehen. Der Linktext lautet Anzeigen für Sicherheitslücken ohne Korrektur und Behoben ansehen für Sicherheitslücken, für die eine Korrektur angewendet wurde.

Vorkommnisse mit gcloud ansehen

So zeigen Sie Vorkommen für ein Image an:

Artifact Registry

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

Wobei:

  • LOCATION ist der regionale oder multiregionale Speicherort für das Repository.
  • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
  • REPOSITORY ist der Name des Repositorys, in dem das Image gespeichert ist.
  • IMAGE_ID ist der Name des Images im Repository. Mit diesem Befehl können Sie kein Image-Tag angeben.

Standardmäßig gibt der Befehl die zehn neuesten Bilder zurück. Wenn Sie eine andere Anzahl von Bildern anzeigen möchten, verwenden Sie das Flag --show-occurrences-from. Mit dem folgenden Befehl werden beispielsweise die 25 neuesten Bilder zurückgegeben.

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

Container Registry

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

Wobei:

  • HOSTNAME ist der multiregionale Hostname:
    • gcr.io
    • asia.gcr.io
    • eu.gcr.io
    • us.gcr.io
  • PROJECT_ID ist die ID des Projekts, das die Images enthält.
  • IMAGE_ID ist die ID des Images, für das Sie Sicherheitslücken sehen möchten. Mit diesem Befehl können Sie kein Image-Tag angeben.

Standardmäßig gibt der Befehl die zehn neuesten Bilder zurück. Wenn Sie eine andere Anzahl von Bildern anzeigen möchten, verwenden Sie das Flag --show-occurrences-from. Mit diesem Befehl werden beispielsweise die 25 neuesten Bilder zurückgegeben.

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

So zeigen Sie Sicherheitslücken für ein Image-Tag oder eine Ebene an:

Artifact Registry

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

oder

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

Wobei:

  • LOCATION ist der regionale oder multiregionale Speicherort für das Repository.
  • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
  • REPOSITORY ist der Name des Repositorys, in dem das Image gespeichert ist.
  • IMAGE_ID ist der Name des Images im Repository.
  • TAG ist das Image-Tag, über das Sie Informationen erhalten möchten.
  • HASH ist der Image-Digest.

Container Registry

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

Wobei:

  • HOSTNAME ist der multiregionale Hostname:
    • gcr.io
    • asia.gcr.io
    • eu.gcr.io
    • us.gcr.io
  • PROJECT_ID ist die ID des Projekts, das die Images enthält.
  • IMAGE_ID ist die ID des Images, für das Sie Sicherheitslücken sehen möchten.
  • HASH ist der Image-Digest.

So filtern Sie die Vorkommen von Sicherheitslücken:

Artifact Registry

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

Wobei:

  • LOCATION ist der regionale oder multiregionale Speicherort für das Repository.
  • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
  • REPOSITORY ist der Name des Repositorys, in dem das Image gespeichert ist.
  • IMAGE_ID ist der Name des Images im Repository.
  • FILTER_EXPRESSION ist ein Beispiel für einen Filterausdruck in dem Format, das unter Vorkommen von Sicherheitslücken filtern erläutert wird.

Container Registry

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

Wobei:

  • HOSTNAME ist der multiregionale Hostname:
    • gcr.io
    • asia.gcr.io
    • eu.gcr.io
    • us.gcr.io
  • PROJECT_ID ist die ID des Projekts, das die Images enthält.
  • IMAGE_ID ist die ID des Images, für das Sie Vorkommen von Sicherheitslücken aufrufen möchten.
  • FILTER_EXPRESSION ist ein Beispiel für einen Filterausdruck in dem Format, das unter Vorkommen von Sicherheitslücken filtern erläutert wird.

Vorkommnisse mit der API oder Code ansehen

Verwenden Sie das entsprechende Snippet, um Vorkommen für ein Bild aufzurufen. Die Code-Snippets geben URLs für Images in Container Registry an. Wenn Sie Artifact Registry verwenden, geben Sie Images mit einer URL im folgenden Format an:

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

API

cURL verwenden

So rufen Sie eine Liste der Vorkommen in Ihrem Projekt ab:

 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

So erhalten Sie eine Zusammenfassung der Sicherheitslücken in Ihrem Projekt:

 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

So rufen Sie Details zu einem bestimmten Vorkommen ab:

 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

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Java API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Go API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.


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: %w", 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: %w", err)
		}
		// Write custom code to process each Occurrence here.
		fmt.Fprintln(w, occ)
		count = count + 1
	}
	return count, nil
}

Node.js

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Node.js API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

/**
 * 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@sha256: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@sha256: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

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Ruby API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

# 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

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Python API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

from google.cloud.devtools import containeranalysis_v1


def get_occurrences_for_image(resource_url: str, project_id: str) -> int:
    """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'

    filter_str = f'resourceUrl="{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

Vorkommen in Cloud Build ansehen

Wenn Sie Cloud Build verwenden, können Sie sich Image-Sicherheitslücken auch in der Seitenleiste Sicherheitsinformationen in der Google Cloud Console ansehen.

Im Seitenbereich Sicherheitsinformationen finden Sie einen allgemeinen Überblick über die Informationen zur Build-Sicherheit für Artefakte, die in Artifact Registry gespeichert sind. Weitere Informationen zum Seitenbereich und dazu, wie Sie Cloud Build zum Schutz Ihrer Softwarelieferkette verwenden können, finden Sie unter Sicherheitserkenntnisse zu Builds ansehen.

Vorkommen filtern

Sie können Filterstrings in den gcloud-Befehlen und der Artifact Analysis API verwenden, um Vorkommen vor dem Abruf zu filtern. In den folgenden Abschnitten werden die unterstützten Suchfilter beschrieben.

Erkennungsvorkommnisse ansehen

Wenn Sie ein Image zum ersten Mal in Container Registry hochladen, wird ein Erkennungsvorkommen erstellt, das Informationen zum ersten Scan des Container-Images enthält.

Mit diesem Filterausdruck rufen Sie das Erkennungsvorkommen für ein Image ab:

kind="DISCOVERY" AND resourceUrl="RESOURCE_URL"

Das folgende Snippet zeigt, wie Sie mit einem Filterausdruck Erkennungsvorkommnisse für ein Image abrufen. Die Code-Snippets geben URLs für Images in Container Registry an. Wenn Sie Artifact Registry verwenden, geben Sie Images mit einer URL im folgenden Format an:

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

gcloud

So zeigen Sie das Erkennungsvorkommen für ein Image an:

In diesem Fall wird der Ausdruck nicht direkt im Befehl verwendet. Stattdessen werden dieselben Informationen als Argumente übergeben:

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 beta container images list-tags \
--occurrence-filter='kind="DISCOVERY"' --format=json HOSTNAME/PROJECT_ID/IMAGE_ID

API

Zum Abrufen des Erkennungsvorkommens muss Ihr Filterausdruck URL-codiert und so in eine GET-Anfrage eingebettet sein:

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

Weitere Informationen finden Sie unter dem API-Endpunkt projects.occurrences.get.

Java

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Java API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Go API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.


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: %w", 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: %w", err)
		}
		fmt.Fprintln(w, occ)
	}
	return nil
}

Node.js

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Node.js API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

/**
 * 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

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Ruby API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

# 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

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Python API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

from google.cloud.devtools import containeranalysis_v1


def get_discovery_info(resource_url: str, project_id: str) -> None:
    """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'

    filter_str = f'kind="DISCOVERY" AND resourceUrl="{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)

Vorkommen von Sicherheitslücken ansehen

Erstellen Sie eine Abfrage mit einem Filterausdruck, um Sicherheitslücken für ein bestimmtes Image aufzurufen:

kind="VULNERABILITY" AND resourceUrl="RESOURCE_URL"

Das folgende Snippet zeigt, wie Sie eine Liste von Vorkommnissen von Sicherheitslücken für ein Image abrufen. Die Code-Snippets geben URLs für Images in Container Registry an. Wenn Sie Artifact Registry verwenden, geben Sie Images mit einer URL im folgenden Format an:

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

gcloud

So zeigen Sie das Vorkommen von Sicherheitslücken für ein Image an:

In diesem Fall wird der Ausdruck nicht direkt im Befehl verwendet. Stattdessen werden dieselben Informationen als Argumente übergeben:

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 beta container images list-tags \
--occurrence-filter='kind="VULNERABILITY"' --format=json HOSTNAME/PROJECT_ID/IMAGE_ID

API

Die Ressourcen-URL muss URL-codiert und folgendermaßen in eine GET-Anfrage eingebettet sein:

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

Weitere Informationen finden Sie unter dem API-Endpunkt projects.occurrences.get.

Java

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Java API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Go API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.


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: %w", 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: %w", err)
		}
		occurrenceList = append(occurrenceList, occ)
	}

	return occurrenceList, nil
}

Node.js

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Node.js API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

/**
 * 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

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Ruby API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

# 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

Informationen zum Installieren und Verwenden der Clientbibliothek für die Artefaktanalyse finden Sie unter Clientbibliotheken für die Artefaktanalyse. Weitere Informationen finden Sie in der Referenzdokumentation zur Artifact Analysis Python API.

Richten Sie zur Authentifizierung bei der Artefaktanalyse Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

from typing import List

from google.cloud.devtools import containeranalysis_v1
from grafeas.grafeas_v1 import types


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

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

Vorkommen eines bestimmten Typs aufrufen

In den beiden vorherigen Beispielen besteht der einzige Unterschied zwischen den Filterausdrücken im Wert von kind, der die Art des Vorkommens angibt. Mit diesem Feld können Sie die Liste der Vorkommen auf eine bestimmte Art beschränken, z. B. eine Sicherheitslücke oder Bereitstellung.

Verwenden Sie folgenden Filterausdruck, um Vorkommen für ein bestimmtes Image abzurufen:

kind="NOTE_KIND" AND resourceUrl="RESOURCE_URL"

Wobei:

  • NOTE_KIND ist die Art des Hinweises.
    • Verwenden Sie beispielsweise DISCOVERY zum Auflisten der Erkennungsvorkommen. Diese werden für Images erstellt, wenn sie ursprünglich per Push-Befehl in Container Registry verschoben werden.
    • Verwenden Sie zum Auflisten der Vorkommen von Sicherheitslücken die Art VULNERABILITY.
  • RESOURCE_URL ist die vollständige URL des Images https://HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH.

Der Filterausdruck zum Abrufen von Vorkommen einer bestimmten Art für mehrere Images lautet:

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

Wobei:

  • RESOURCE_URL_PREFIX ist das URL-Präfix für einige Images.
    • Zum Auflisten aller Versionen eines Images: https://HOSTNAME/PROJECT_ID/IMAGE_ID@
    • Zum Auflisten aller Images in einem Projekt: https://HOSTNAME/PROJECT_ID/

Bilder aufrufen, die einem bestimmten Hinweis zugeordnet sind

Sie können eine Liste von Ressourcen abrufen, die einer bestimmten Hinweis-ID zugeordnet sind. So können Sie beispielsweise Images mit einer bestimmten CVE-Sicherheitslücke auflisten.

Verwenden Sie den folgenden Filterausdruck, um alle Images in einem Projekt aufzulisten, die einem bestimmten Hinweis zugeordnet sind:

noteProjectId="PROVIDER_PROJECT_ID" AND noteId="NOTE_ID"

Mit dem folgenden Filterausdruck können Sie ein bestimmtes Image auf einen konkreten Hinweis prüfen:

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

Wobei:

  • PROVIDER_PROJECT_ID ist die ID eines Provider-Projekts. Beispielsweise stellt goog-vulnz die Standardanalyse für Sicherheitslücken bereit.
  • NOTE_ID ist die ID des Hinweises. Sicherheitsrelevante Hinweise werden häufig als CVE-2019-12345 formatiert.
  • RESOURCE_URL ist die vollständige URL des Images https://HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH.

Mit dem folgenden Filterausdruck können Sie beispielsweise prüfen, ob alle Images gemäß der Google-Analyse CVE-2017-16231 enthalten:

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

Nächste Schritte