Eseguire la scansione automatica dei pacchetti del sistema operativo

In questo documento scoprirai come abilitare l'API Container Scanning, eseguire il push di un'immagine in Artifact Registry e visualizzare l'elenco delle vulnerabilità trovate nell'immagine.

Artifact Analysis fornisce informazioni sulle vulnerabilità per le immagini container in Artifact Registry e Container Registry (ritirato). I metadati vengono archiviati come [note][note]. Viene creata un'occorrenza per ogni istanza di una nota associata a un'immagine. Per saperne di più, consulta i documenti relativi alla panoramica e ai prezzi.

L'abilitazione di questa API attiva anche la scansione dei pacchetti di lingua in Artifact Registry. Consulta i tipi di pacchetti supportati.

Prima di iniziare

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.

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

Go to project selector

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

Enable the Artifact Registry and Container Scanning APIs.

Enable the APIs

Install the Google Cloud CLI.

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

To initialize the gcloud CLI, run the following command:

gcloud init

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

Go to project selector

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

Enable the Artifact Registry and Container Scanning APIs.

Enable the APIs

Install the Google Cloud CLI.

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

To initialize the gcloud CLI, run the following command:

gcloud init

1. Crea un repository Docker in Artifact Registry ed esegui il push di un'immagine container nel repository. Se non hai familiarità con Artifact Registry, consulta la guida rapida di Docker.

Visualizza le vulnerabilità dell'immagine

Artifact Analysis esegue la scansione delle nuove immagini quando vengono caricate in Artifact Registry. Questa scansione estrae informazioni sui pacchetti di sistema nel contenitore.

Puoi visualizzare le occorrenze di vulnerabilità per le tue immagini nel registro utilizzando la console Google Cloud , Google Cloud CLI o l'API Container Analysis. Se un'immagine presenta vulnerabilità, puoi ottenere i dettagli.

Artifact Analysis aggiorna solo i metadati delle immagini di cui è stato eseguito il push o il pull negli ultimi 30 giorni. Dopo 30 giorni, i metadati non verranno più aggiornati e i risultati saranno obsoleti. Inoltre, Artifact Analysis archivia i metadati che sono rimasti inattivi per più di 90 giorni e i metadati non saranno disponibili nella console Google Cloud , in gcloud o utilizzando l'API. Per eseguire di nuovo la scansione di un'immagine con metadati obsoleti o archiviati, esegui il pull dell'immagine. L'aggiornamento dei metadati può richiedere fino a 24 ore.

Visualizzare le occorrenze nella console Google Cloud

Per visualizzare le vulnerabilità in un'immagine:

1. Recupera l'elenco dei repository.

   Apri la pagina Repository

2. Nell'elenco dei repository, fai clic su un repository.

3. Nell'elenco delle immagini, fai clic sul nome di un'immagine.

   I totali delle vulnerabilità per ogni digest dell'immagine vengono visualizzati nella colonna Vulnerabilità.

   

4. Per visualizzare l'elenco delle vulnerabilità di un'immagine, fai clic sul link nella colonna Vulnerabilità.

   La sezione Risultati scansione mostra un riepilogo dei tipi di pacchetti scansionati, delle vulnerabilità totali, delle vulnerabilità con correzioni disponibili, delle vulnerabilità senza correzioni e della gravità effettiva.

   

   La tabella delle vulnerabilità elenca il nome delle vulnerabilità ed esposizioni comuni (CVE) per ogni vulnerabilità trovata, la gravità effettiva, il punteggio del Common Vulnerability Scoring System (CVSS), le correzioni (se disponibili), il nome del pacchetto che contiene la vulnerabilità e il tipo di pacchetto.

   Puoi filtrare e ordinare questi file per controllare un file, una directory o un tipo di file specifico in base all'estensione del file.

   La consoleGoogle Cloud mostra fino a 1200 vulnerabilità in questa tabella. Se la tua immagine ha più di 1200 vulnerabilità, devi utilizzare gcloud o l'API per visualizzare l'elenco completo.

5. Per i dettagli di una CVE specifica, fai clic sul nome della CVE.

6. Per visualizzare i dettagli dell'occorrenza della vulnerabilità, come il numero di versione e la posizione interessata, fai clic su Visualizza o Visualizza correzione nella riga con il nome della vulnerabilità. Il testo del link è Visualizza per le vulnerabilità senza correzione e Visualizza correzione per le vulnerabilità a cui è stata applicata una correzione.

Visualizzare le occorrenze utilizzando gcloud

Per visualizzare le occorrenze di un'immagine:

Artifact Registry

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

Dove:

• LOCATION è la posizione regionale o multiregionale del repository.
• PROJECT_ID è il tuo Google Cloud ID progetto.
• REPOSITORY è il nome del repository in cui è archiviata l'immagine.
• IMAGE_ID è il nome dell'immagine nel repository. Non puoi specificare un tag immagine con questo comando.

Per impostazione predefinita, il comando restituisce le 10 immagini più recenti. Per mostrare un numero diverso di immagini, utilizza il flag --show-occurrences-from. Ad esempio, il seguente comando restituisce le 25 immagini più recenti.

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

Dove:

• HOSTNAME è il nome host multiregionale:
  • gcr.io
  • asia.gcr.io
  • eu.gcr.io
  • us.gcr.io
• PROJECT_ID è l'ID del progetto contenente le immagini.
• IMAGE_ID è l'ID dell'immagine per cui vuoi visualizzare le vulnerabilità. Non puoi specificare un tag immagine con questo comando.

Per impostazione predefinita, il comando restituisce le 10 immagini più recenti. Per mostrare un numero diverso di immagini, utilizza il flag --show-occurrences-from. Ad esempio, questo comando restituisce le 25 immagini più recenti.

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

Per visualizzare le vulnerabilità per un tag immagine o un livello:

Artifact Registry

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

o

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

Dove:

• LOCATION è la posizione regionale o multiregionale del repository.
• PROJECT_ID è il tuo Google Cloud ID progetto.
• REPOSITORY è il nome del repository in cui è archiviata l'immagine.
• IMAGE_ID è il nome dell'immagine nel repository.
• TAG è il tag immagine su cui vuoi ottenere informazioni.
• HASH è il digest dell'immagine.

Container Registry

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

Dove:

• HOSTNAME è il nome host multiregionale:
  • gcr.io
  • asia.gcr.io
  • eu.gcr.io
  • us.gcr.io
• PROJECT_ID è l'ID del progetto contenente le immagini.
• IMAGE_ID è l'ID dell'immagine per cui vuoi visualizzare le vulnerabilità.
• HASH è il digest dell'immagine.

Per filtrare le occorrenze della vulnerabilità:

Artifact Registry

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

Dove:

• LOCATION è la posizione regionale o multiregionale del repository.
• PROJECT_ID è il tuo Google Cloud ID progetto.
• REPOSITORY è il nome del repository in cui è archiviata l'immagine.
• IMAGE_ID è il nome dell'immagine nel repository.
• FILTER_EXPRESSION è un'espressione di filtro di esempio nel formato spiegato in Filtrare le occorrenze di vulnerabilità.

Container Registry

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

Dove:

• HOSTNAME è il nome host multiregionale:
  • gcr.io
  • asia.gcr.io
  • eu.gcr.io
  • us.gcr.io
• PROJECT_ID è l'ID del progetto contenente le immagini.
• IMAGE_ID è l'ID dell'immagine per cui vuoi visualizzare le occorrenze di vulnerabilità.
• FILTER_EXPRESSION è un'espressione di filtro di esempio nel formato spiegato in Filtrare le occorrenze di vulnerabilità.

Visualizzare le occorrenze utilizzando l'API o il codice

Per visualizzare le occorrenze di un'immagine, utilizza lo snippet appropriato. Gli snippet di codice specificano gli URL delle immagini in Container Registry. Se utilizzi Artifact Registry, specifica le immagini con un URL nel formato:

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

API

Utilizzo di cURL

Per ottenere un elenco delle occorrenze nel progetto:

 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

Per ottenere un riepilogo delle vulnerabilità nel tuo progetto:

 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

Per visualizzare i dettagli di un'occorrenza specifica:

 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

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Java.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Go.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Node.js.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Ruby.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

# 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

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Python.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Visualizza le occorrenze in Cloud Build

Se utilizzi Cloud Build, puoi anche visualizzare le vulnerabilità delle immagini nel riquadro laterale Approfondimenti sulla sicurezza all'interno della console Google Cloud .

Il riquadro laterale Approfondimenti sulla sicurezza fornisce una panoramica generale delle informazioni sulla sicurezza delle build per gli artefatti archiviati in Artifact Registry. Per saperne di più sul riquadro laterale e su come utilizzare Cloud Build per proteggere la catena di fornitura del software, consulta Visualizzare gli insight sulla sicurezza delle build.

Filtra occorrenze

Puoi utilizzare le stringhe di filtro nei comandi gcloud e nell'API Artifact Analysis per filtrare le occorrenze prima di visualizzarle. Le sezioni seguenti descrivono i filtri di ricerca supportati.

Visualizzare le occorrenze del rilevamento

Quando un'immagine viene inizialmente inviata a Container Registry, viene creata un'occorrenza di rilevamento, che contiene informazioni sulla scansione iniziale dell'immagine container.

Per recuperare l'occorrenza di rilevamento per un'immagine, utilizza la seguente espressione di filtro:

kind="DISCOVERY" AND resourceUrl="RESOURCE_URL"

Il seguente snippet mostra come utilizzare un'espressione di filtro per visualizzare le occorrenze di rilevamento per un'immagine. Gli snippet di codice specificano gli URL delle immagini in Container Registry. Se utilizzi Artifact Registry, specifica le immagini con un URL nel formato:

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

gcloud

Per visualizzare le occorrenze di scoperta per un'immagine:

In questo caso l'espressione non viene utilizzata direttamente nel comando, ma le stesse informazioni vengono trasmesse come argomenti:

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

Per recuperare l'occorrenza di rilevamento, l'espressione di filtro deve essere codificata come URL e incorporata in una richiesta GET nel seguente modo:

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

Per maggiori dettagli, consulta l'endpoint API projects.occurrences.get.

Java

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Java.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Go.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Node.js.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Ruby.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

# 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

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Python.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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)

Visualizza le occorrenze di vulnerabilità

Per visualizzare le occorrenze di vulnerabilità per un'immagine specifica, crea una query con un'espressione di filtro:

kind="VULNERABILITY" AND resourceUrl="RESOURCE_URL"

Il seguente snippet mostra come recuperare un elenco di occorrenze di vulnerabilità per un'immagine. Gli snippet di codice specificano gli URL delle immagini in Container Registry. Se utilizzi Artifact Registry, specifica le immagini con un URL nel formato:

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

gcloud

Per visualizzare le occorrenze di vulnerabilità per un'immagine:

In questo caso l'espressione non viene utilizzata direttamente nel comando, ma le stesse informazioni vengono trasmesse come argomenti:

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

L'URL della risorsa deve essere codificato come URL e incorporato in una richiesta GET nel seguente modo:

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

Per maggiori dettagli, consulta l'endpoint API projects.occurrences.get.

Java

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Java.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Go.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Node.js.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Ruby.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

# 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

Per scoprire come installare e utilizzare la libreria client per Artifact Analysis, consulta Librerie client di Artifact Analysis. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Artifact Analysis per Python.

Per eseguire l'autenticazione in Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Visualizzare le occorrenze di un tipo specifico

Nei due esempi precedenti, l'unica differenza tra le espressioni di filtro è il valore di kind, che identifica il tipo di occorrenza. Utilizza questo campo per limitare l'elenco delle occorrenze a un tipo specifico, ad esempio una vulnerabilità o un deployment.

Per recuperare le occorrenze di un'immagine specifica, utilizza questa espressione di filtro:

kind="NOTE_KIND" AND resourceUrl="RESOURCE_URL"

Dove:

• NOTE_KIND è il tipo di nota.
  • Ad esempio, utilizza il tipo DISCOVERY per elencare le occorrenze di scoperta. Questi vengono creati per le immagini quando vengono inizialmente inviati a Container Registry.
  • Per elencare le occorrenze di vulnerabilità, utilizza il tipo VULNERABILITY.
• RESOURCE_URL è l'URL completo dell'immagine https://HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH

L'espressione di filtro per recuperare le occorrenze di un tipo specifico in molte immagini è:

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

Dove:

• RESOURCE_URL_PREFIX è il prefisso URL per alcune immagini
  • Per elencare tutte le versioni di un'immagine: https://HOSTNAME/PROJECT_ID/IMAGE_ID@
  • Per elencare tutte le immagini in un progetto: https://HOSTNAME/PROJECT_ID/

Visualizzare le immagini associate a una nota specifica

Puoi recuperare un elenco di risorse associate a un ID nota specifico. Ad esempio, puoi elencare le immagini con una vulnerabilità CVE specifica.

Per elencare tutte le immagini all'interno di un progetto associate a una determinata nota, utilizza la seguente espressione di filtro:

noteProjectId="PROVIDER_PROJECT_ID" AND noteId="NOTE_ID"

Per controllare un'immagine specifica per una nota specifica, utilizza la seguente espressione di filtro:

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

Dove:

• PROVIDER_PROJECT_ID è l'ID del progetto del fornitore. Ad esempio, goog-vulnz fornisce l'analisi delle vulnerabilità predefinita.
• NOTE_ID è l'ID della nota. Le note relative alla sicurezza sono spesso formattate come CVE-2019-12345.
• RESOURCE_URL è l'URL completo dell'immagine https://HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH

Ad esempio, per verificare la presenza di tutte le immagini che hanno un'occorrenza di CVE-2017-16231 come analizzato da Google, utilizza la seguente espressione di filtro:

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

Passaggi successivi

• Utilizza le notifiche Pub/Sub per ricevere notifiche su vulnerabilità e altri metadati.

• Crea attestazioni integrando Artifact Analysis con Autorizzazione binaria per impedire l'esecuzione di immagini container con problemi di sicurezza noti nel tuo ambiente di deployment.