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à rilevate nell'immagine.
Artifact Analysis fornisce informazioni sulle vulnerabilità per le immagini container in Artifact Registry e Container Registry (Ritirata). I metadati vengono archiviati come note. Viene creata un'occorrenza per ogni istanza di una nota associata a un'immagine. Per ulteriori informazioni, consulta la panoramica e la documentazione relativa ai prezzi.
L'abilitazione di questa API consente anche l'analisi 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.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Artifact Registry and Container Scanning APIs.
- Install the Google Cloud CLI.
-
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.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Artifact Registry and Container Scanning APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
- Crea un repository Docker in Artifact Registry ed esegui il push di un'immagine container al repository. Se non hai dimestichezza 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 su Artifact Registry. Questa scansione estrae informazioni sui pacchetti di sistema nel contenitore.
Puoi visualizzare le occorrenze di vulnerabilità per le tue immagini nel registry 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 che sono state inviate o rimosse negli ultimi 30 giorni. Dopo 30 giorni, i metadati non verranno più aggiornati e i risultati non saranno più aggiornati. Inoltre, Artifact Analysis archivia i metadati inattivi da più di 90 giorni, che non saranno disponibili nella console Google Cloud, in gcloud o tramite 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à di un'immagine:
Recupera l'elenco dei repository.
Nell'elenco dei repository, fai clic su un repository.
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à.
Per visualizzare l'elenco delle vulnerabilità di un'immagine, fai clic sul link nella colonna Vulnerabilità.
La sezione Risultati della scansione mostra un riepilogo dei tipi di pacchetti esaminati, delle vulnerabilità totali, delle vulnerabilità con correzioni disponibili, delle vulnerabilità senza correzioni e della gravità effettiva.
La tabella delle vulnerabilità elenca il nome della 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.
La console Google Cloud mostra fino a 1200 vulnerabilità in questa tabella. Se la tua immagine presenta più di 1200 vulnerabilità, devi utilizzare gcloud o l'API per visualizzare l'elenco completo.
Per informazioni dettagliate su una CVE specifica, fai clic sul nome della CVE.
Per visualizzare i dettagli relativi alle occorrenze 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 ID progetto Google Cloud.
- 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 ID progetto Google Cloud.
- REPOSITORY è il nome del repository in cui è archiviata l'immagine.
- IMAGE_ID è il nome dell'immagine nel repository.
- TAG è il tag immagine di 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 di 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 ID progetto Google Cloud.
- 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à.
Visualizza 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 visualizzare un elenco di 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 visualizzare 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 una 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 Java.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
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 Go.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
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 Node.js.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
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 Ruby.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
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 Python.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Visualizzare le occorrenze in Cloud Build
Se utilizzi Cloud Build, puoi anche visualizzare le vulnerabilità delle immagini nel riquadro laterale Approfondimenti sulla sicurezza della console Google Cloud.
Il riquadro laterale Approfondimenti sulla sicurezza fornisce una panoramica generale delle informazioni sulla sicurezza della compilazione per gli elementi archiviati in Artifact Registry. Per scoprire di più sul riquadro laterale e su come utilizzare Cloud Build per contribuire a proteggere la tua catena di fornitura del software, consulta Visualizzare gli insight sulla sicurezza della build.
Filtra le occorrenze
Puoi utilizzare stringhe di filtro nei comandi gcloud
e nell'API Artifact Analysis per filtrare le occorrenze prima di visualizzarle. Le seguenti sezioni 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 del contenitore.
Per recuperare l'occorrenza della scoperta di un'immagine, utilizza la seguente expression di filtro:
kind="DISCOVERY" AND resourceUrl="RESOURCE_URL"
Lo snippet seguente 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 di un'immagine:
In questo caso l'espressione non viene utilizzata direttamente nel comando, ma le stesse informazioni vengono passate 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 della scoperta, l'espressione del filtro deve essere codificata in URL e incorporata in una richiesta GET
come segue:
GET https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences?filter=kind%3D%22DISCOVERY%22%20AND%20resourceUrl%3D%22ENCODED_RESOURCE_URL%22
Per ulteriori 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 Java.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
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 Go.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
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 Node.js.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
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 Ruby.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
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 Python.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Visualizzare 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"
Lo snippet seguente 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 passate 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 e incorporato in una richiesta GET come segue:
GET https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences?filter=kind%3D%22VULNERABILITY%22%20AND%20resourceUrl%3D%22ENCODED_RESOURCE_URL%22
Per ulteriori 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 Java.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
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 Go.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
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 Node.js.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
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 Ruby.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
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 Python.
Per autenticarti ad Artifact Analysis, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
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. Vengono creati per le immagini quando vengono inizialmente eseguiti push in Container Registry. - Per elencare le occorrenze di vulnerabilità, utilizza il tipo
VULNERABILITY
.
- Ad esempio, utilizza il tipo
-
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 di alcune immagini
- Per elencare tutte le versioni di un'immagine:
https://HOSTNAME/PROJECT_ID/IMAGE_ID@
- Per visualizzare l'elenco di tutte le immagini di un progetto:
https://HOSTNAME/PROJECT_ID/
- Per elencare tutte le versioni di un'immagine:
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 se in un'immagine specifica è presente 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 provider. 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 controllare tutte le immagini che contengono 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.
Kritis Signer e Voucher ti consentono di creare attestazioni di Autorizzazione binaria come parte della pipeline di compilazione. Questi strumenti possono creare attestazioni di Autorizzazione binaria in base ai risultati della scansione delle vulnerabilità. Per ulteriori informazioni, consulta la sezione Creare attestazioni con Kritis Signer o Creare attestazioni con Voucher.