Analyser automatiquement les packages de l'OS

Dans ce document, vous allez apprendre à activer l'API Container Scanning, à transférer une image vers Artifact Registry et à consulter la liste des failles détectées dans l'image.

Artifact Analysis fournit des informations sur les failles pour les images de conteneurs dans Artifact Registry et Container Registry (obsolète). Les métadonnées sont stockées sous forme de notes. Une occurrence est créée pour chaque occurrence d'une note associée à une image. Pour en savoir plus, consultez les documents Présentation et Tarifs.

L'activation de cette API permet également d'activer l'analyse des packages de langages dans Artifact Registry. Consultez la section Types de packages compatibles.

Avant de commencer

  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. Créez un dépôt Docker dans Artifact Registry et transférez-y une image de conteneur. Si vous ne connaissez pas Artifact Registry, consultez le guide de démarrage rapide Docker.

Afficher les failles des images

Artifact Analysis analyse les nouvelles images au fur et à mesure de leur importation dans Artifact Registry. Cette analyse extrait des informations sur les packages système du conteneur.

Vous pouvez afficher les occurrences de failles de vos images dans le registre à l'aide de la console Google Cloud, de Google Cloud CLI ou de l'API Container Analysis. Si une image présente des failles, vous pouvez obtenir les détails.

Artifact Analysis ne met à jour que les métadonnées des images transférées ou extraites au cours des 30 derniers jours. Au bout de 30 jours, les métadonnées ne seront plus mises à jour et les résultats seront obsolètes. De plus, Artifact Analysis archive les métadonnées obsolètes depuis plus de 90 jours. Elles ne seront pas disponibles dans la console Google Cloud, gcloud ni via l'API. Pour lancer une nouvelle analyse d'une image avec des métadonnées obsolètes ou archivées, extrayez cette image. L'actualisation des métadonnées peut prendre jusqu'à 24 heures.

Afficher les occurrences dans la console Google Cloud

Pour afficher les failles d'une image:

  1. Obtenez la liste des dépôts.

    Ouvrir la page "Dépôts"

  2. Dans la liste des dépôts, cliquez sur un dépôt.

  3. Dans la liste des images, cliquez sur un nom d'image.

    Le nombre total de failles pour chaque récapitulatif d'image est affiché dans la colonne Vulnerabilities (Failles).

    Capture d'écran d'une image avec des failles

  4. Pour afficher la liste des failles d'une image, cliquez sur le lien dans la colonne Vulnerabilities (Failles).

    La section Résultats de l'analyse affiche un récapitulatif des types de packages analysés, du nombre total de failles, des failles avec des correctifs disponibles, des failles sans correctifs et de la gravité effective.

    Capture d'écran de la section "Résultats de l'analyse" avec les failles, les correctifs et la gravité effective

    Le tableau des failles répertorie le nom de la faille CVE pour chaque faille détectée, la gravité effective, le score CVSS (Common Vulnerability Scoring System), les correctifs (le cas échéant), le nom du package contenant la faille et le type de package.

    Vous pouvez filtrer et trier ces fichiers pour vérifier un fichier, un répertoire ou un type de fichier spécifique par extension de fichier.

    La console Google Cloud affiche au maximum 1 200 vulnérabilités dans ce tableau. Si votre image comporte plus de 1 200 failles, vous devez utiliser gcloud ou l'API pour afficher la liste complète.

  5. Pour en savoir plus sur une faille CVE spécifique, cliquez sur son nom.

  6. Pour afficher les détails de l'occurrence de la faille, tels que le numéro de version et l'emplacement concerné, cliquez sur Afficher ou Afficher corrigé dans la ligne contenant le nom de la faille. Le texte du lien est Afficher pour les failles sans correctif et Afficher les failles corrigées pour les failles pour lesquelles un correctif a été appliqué.

Afficher les occurrences à l'aide de gcloud

Pour afficher les occurrences d'une image :

Artifact Registry

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

Où :

  • LOCATION est l'emplacement régional ou multirégional du dépôt.
  • PROJECT_ID est votre ID de projet Google Cloud.
  • REPOSITORY est le nom du dépôt où l'image est stockée.
  • IMAGE_ID est le nom de l'image dans le dépôt. Vous ne pouvez pas spécifier de tag d'image avec cette commande.

Par défaut, la commande renvoie les 10 images les plus récentes. Pour afficher un nombre différent d'images, utilisez l'option --show-occurrences-from. Par exemple, la commande suivante renvoie les 25 images les plus récentes.

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

Où :

  • HOSTNAME est le nom d'hôte multirégional :
    • gcr.io
    • asia.gcr.io
    • eu.gcr.io
    • us.gcr.io
  • PROJECT_ID est l'ID du projet contenant les images.
  • IMAGE_ID est l'ID de l'image pour laquelle vous souhaitez afficher les failles. Vous ne pouvez pas spécifier de tag d'image avec cette commande.

Par défaut, la commande renvoie les 10 images les plus récentes. Pour afficher un nombre différent d'images, utilisez l'option --show-occurrences-from. Par exemple, cette commande renvoie les 25 images les plus récentes.

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

Pour afficher les failles d'un tag d'image ou d'une couche :

Artifact Registry

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

ou

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

Où :

  • LOCATION est l'emplacement régional ou multirégional du dépôt.
  • PROJECT_ID est votre ID de projet Google Cloud.
  • REPOSITORY est le nom du dépôt où l'image est stockée.
  • IMAGE_ID est le nom de l'image dans le dépôt.
  • TAG est le tag d'image sur lequel vous souhaitez obtenir des informations.
  • HASH correspond au condensé de l'image.

Container Registry

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

Où :

  • HOSTNAME est le nom d'hôte multirégional :
    • gcr.io
    • asia.gcr.io
    • eu.gcr.io
    • us.gcr.io
  • PROJECT_ID est l'ID du projet contenant les images.
  • IMAGE_ID est l'ID de l'image pour laquelle vous souhaitez afficher les failles.
  • HASH correspond au condensé de l'image.

Pour filtrer les occurrences de failles :

Artifact Registry

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

Où :

  • LOCATION est l'emplacement régional ou multirégional du dépôt.
  • PROJECT_ID est votre ID de projet Google Cloud.
  • REPOSITORY est le nom du dépôt où l'image est stockée.
  • IMAGE_ID est le nom de l'image dans le dépôt.
  • FILTER_EXPRESSION est un exemple d'expression de filtre au format expliqué dans la section Filtrer les occurrences de failles.

Container Registry

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

Où :

  • HOSTNAME est le nom d'hôte multirégional :
    • gcr.io
    • asia.gcr.io
    • eu.gcr.io
    • us.gcr.io
  • PROJECT_ID est l'ID du projet contenant les images.
  • IMAGE_ID correspond à l'ID de l'image pour laquelle vous souhaitez afficher les occurrences de failles.
  • FILTER_EXPRESSION est un exemple d'expression de filtre au format expliqué dans la section Filtrer les occurrences de failles.

Afficher les occurrences à l'aide de l'API ou du code

Pour afficher les occurrences d'une image, utilisez l'extrait de code approprié. Les extraits de code spécifient les URL des images dans Container Registry. Si vous utilisez Artifact Registry, spécifiez les images avec une URL au format suivant:

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

API

Utiliser cURL

Pour obtenir la liste des occurrences dans votre projet :

 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

Pour obtenir un résumé des failles de votre projet :

 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

Pour obtenir des informations sur une occurrence spécifique:

 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

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Java.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Go.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.


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

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Node.js.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Ruby.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

# 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

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Python.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Afficher les occurrences dans Cloud Build

Si vous utilisez Cloud Build, vous pouvez également afficher les failles des images dans le panneau latéral Insights de sécurité de la console Google Cloud.

Le panneau latéral Insights sur la sécurité fournit une vue d'ensemble des informations de sécurité de la compilation pour les artefacts stockés dans Artifact Registry. Pour en savoir plus sur le panneau latéral et découvrir comment utiliser Cloud Build pour protéger votre chaîne d'approvisionnement logicielle, consultez Afficher des insights de sécurité sur la compilation.

Filtrer les occurrences

Vous pouvez utiliser des chaînes de filtre dans les commandes gcloud et l'API Artifact Analysis pour filtrer les occurrences avant de les afficher. Les sections ci-dessous décrivent les filtres de recherche compatibles.

Afficher les occurrences de découverte

Lorsqu'une image est initialement transférée dans Container Registry, elle crée une occurrence de découverte qui contient des informations sur l'analyse initiale de l'image de conteneur.

Pour récupérer l'occurrence de découverte d'une image, utilisez l'expression de filtre suivante :

kind="DISCOVERY" AND resourceUrl="RESOURCE_URL"

L'extrait suivant montre comment utiliser une expression de filtre pour afficher les occurrences de découverte d'une image. Les extraits de code spécifient les URL des images dans Container Registry. Si vous utilisez Artifact Registry, spécifiez les images avec une URL au format suivant:

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

gcloud

Pour afficher les occurrences de découverte d'une image :

Dans ce cas, l'expression n'est pas utilisée directement dans la commande, mais les mêmes informations sont transmises en tant qu'arguments :

Artifact Registry:

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

Container Registry:

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

API

Pour récupérer l'occurrence de découverte, votre expression de filtre doit être encodée en URL et intégrée dans une requête GET comme suit:

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

Pour en savoir plus, reportez-vous au point de terminaison projects.occurrences.get de l'API.

Java

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Java.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Go.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.


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

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Node.js.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Ruby.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

# 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

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Python.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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)

Afficher les occurrences de faille

Pour afficher les occurrences de faille pour une image spécifique, créez une requête avec une expression de filtre :

kind="VULNERABILITY" AND resourceUrl="RESOURCE_URL"

L'extrait de code suivant montre comment récupérer la liste des occurrences de failles d'une image. Les extraits de code spécifient les URL des images dans Container Registry. Si vous utilisez Artifact Registry, spécifiez les images avec une URL au format suivant:

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

gcloud

Pour afficher les occurrences de failles d'une image :

Dans ce cas, l'expression n'est pas utilisée directement dans la commande, mais les mêmes informations sont transmises en tant qu'arguments :

Artifact Registry

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

Container Registry

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

API

L'URL de la ressource doit être encodée en URL et intégrée dans une requête GET comme suit:

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

Pour en savoir plus, reportez-vous au point de terminaison projects.occurrences.get de l'API.

Java

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Java.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Go.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.


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

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Node.js.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Ruby.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

# 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

Pour savoir comment installer et utiliser la bibliothèque cliente pour l'Artifact Analysis, consultez la page Bibliothèques clientes d'analyse d'artefacts. Pour en savoir plus, consultez la documentation de référence de l'API Artifact Analysis Python.

Pour vous authentifier auprès d'Artifact Analysis, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Afficher les occurrences d'un type spécifique

Dans les deux exemples précédents, la seule différence entre les expressions de filtre est la valeur du champ kind, qui identifie le type d'occurrence. Utilisez ce champ pour limiter la liste des occurrences à un type particulier, tel qu'une faille ou un déploiement.

L'expression de filtre permettant de récupérer des occurrences pour une image spécifique est la suivante :

kind="NOTE_KIND" AND resourceUrl="RESOURCE_URL"

Où :

  • NOTE_KIND est le genre de note.
    • Par exemple, utilisez le genre DISCOVERY pour répertorier les occurrences de découverte. Celles-ci sont créées pour les images lorsqu'elles sont initialement placées dans Container Registry.
    • Pour répertorier les occurrences de failles, utilisez le genre VULNERABILITY.
  • RESOURCE_URL est l'URL complète de l'image https://HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH.

L'expression de filtre permettant de récupérer des occurrences d'un genre spécifique dans de nombreuses images est la suivante :

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

Où :

  • RESOURCE_URL_PREFIX est le préfixe de l'URL pour certaines images.
    • Pour répertorier toutes les versions d'une image : https://HOSTNAME/PROJECT_ID/IMAGE_ID@
    • Pour répertorier toutes les images d'un projet : https://HOSTNAME/PROJECT_ID/

Afficher les images associées à une note spécifique

Vous pouvez récupérer une liste de ressources associées à un ID de note spécifique. Par exemple, vous pouvez répertorier les images avec une faille CVE spécifique.

Pour répertorier toutes les images d'un projet associées à une note particulière, utilisez l'expression de filtre suivante :

noteProjectId="PROVIDER_PROJECT_ID" AND noteId="NOTE_ID"

Pour consulter une image spécifique pour une note spécifique, utilisez l'expression de filtre suivante :

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

Où :

  • PROVIDER_PROJECT_ID est l'ID du projet du fournisseur. Par exemple, goog-vulnz fournit l'analyse de faille par défaut.
  • NOTE_ID est l'ID de la note. Les notes relatives à la sécurité sont souvent au format CVE-2019-12345.
  • RESOURCE_URL est l'URL complète de l'image https://HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH.

Par exemple, pour vérifier que toutes les images ayant une occurrence de CVE-2017-16231 ont été analysées par Google, utilisez l'expression de filtre suivante :

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

Étape suivante