Examiner les failles

Lorsque vous entendez parler d'une nouvelle faille, il est important d'agir rapidement. Cette page fournit une liste d'appels d'API et de filtres essentiels prédéfinis pour vous. Utilisez ces appels d'API pour récupérer les résultats d'Artifact Analysis et collecter des informations sur l'état de vos artefacts.

Ce contenu est conçu pour être utilisé avec les métadonnées de recherche automatique. Si vos images ont dépassé la période de analyse continue de 30 jours, vous pouvez exécuter une nouvelle analyse en poussant à nouveau vers Artifact Registry.

Tous les exemples de cette page accèdent directement à l'API, mais vous pouvez également utiliser les bibliothèques clientes Container Analysis ou les commandes gcloud.

Autorisations requises

Tous ces exemples utilisent la méthode d'API ListOccurrences. Pour appeler cette méthode, vous devez disposer du rôle (roles/containeranalysis.occurrences.viewer) Lecteur d'occurrences d'analyse de conteneurs pour le projet que vous analysez.

  • Si vous analysez des projets dont vous êtes le propriétaire, vous disposez déjà des autorisations requises.

  • Si vous analysez des projets dont vous n'êtes pas propriétaire, utilisez les instructions de gestion des accès IAM pour accorder des autorisations.

Pour en savoir plus sur les types d'accès des fournisseurs et des clients à l'Artifact Analysis, consultez les autorisations.

Afficher toutes les métadonnées de failles d'une image

Utilisez le filtre KIND="VULNERABILITY" avec l'ID de votre projet et l'URL complète de la ressource de votre image, y compris https://:

  curl -G -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "filter=(kind=\"VULNERABILITY\" AND resourceUrl=\"RESOURCE_URL\")" \
    https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences

Remplacez les éléments suivants :

  • PROJECT_ID correspond à votre ID de projet Google Cloud. Pour afficher la liste de vos projets, vous pouvez utiliser gcloud projects list.
  • RESOURCE_URL est l'URL complète de l'image, au format https://HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH. Vous devez utiliser https:// au début de l'URL. Si vous devez trouver l'URL d'une image, vous pouvez utiliser l'appel dans "Je souhaite comprendre toutes les métadonnées de mon projet".

La sortie inclut une liste de failles avec des informations telles que la gravité, les options d'atténuation, le cas échéant, et le nom du package contenant la faille.

Rechercher une faille spécifique dans un projet

Dans la plupart des cas, l'Artifact Analysis utilise l'ID CVE comme identifiant de la faille. Toutefois, certaines failles listées dans la base de données Advisory GitHub ne sont pas associées à un ID CVE. Dans ce cas, l'Artifact Analysis utilise l'ID GHSA à la place.

L'ID de la faille est inclus dans le champ noteName. Il commence par le préfixe CVE pour les ID CVE et GHSA pour les ID GHSA. Par exemple, si le résultat suivant est obtenu en exécutant la commande pour afficher toutes les failles d'une image:

vulnerabilities:
  HIGH:
  - name: projects/my-project/occurrences/1234fh2c-699a-462f-b920-93a80f56f544
    resourceUri: https://my_region-docker.pkg.dev/my-project/my-repo/my-image@sha256:8a1a79b587797c5164ec95977cf7aaaa828694a615947bdaed6a327d5b6a17bb
    noteName: projects/goog-vulnz/notes/CVE-2021-32798
    kind: VULNERABILITY
    ...
  - name: projects/my-project/occurrences/OCCURRENCE_ID
    resourceUri: https://my_region-docker.pkg.dev/my-project/my-repo/my-image@sha256:8a1a79b587797c5164ec95977cf7aaaa828694a615947bdaed6a327d5b6a17bb
    noteName: projects/goog-vulnz/notes/GHSA-884p-74jh-xrg2
    kind: VULNERABILITY
    ...

La première faille porte l'ID CVE-2021-32798, la seconde l'ID GHSA-884p-74jh-xrg2.

  1. Obtenez l'identifiant de la faille.

  2. Utilisez l'ID CVE ou l'ID GHSA dans l'expression de filtre suivante pour récupérer la liste des images concernées:

  curl -G -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "filter=(noteProjectId=\"goog-vulnz\" AND noteId=\"VULN_ID\")" \
    https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences

Remplacez les éléments suivants :

  • PROJECT_ID correspond à votre ID de projet Google Cloud. Pour afficher la liste de vos projets, vous pouvez utiliser gcloud projects list.
  • VULN_ID est l'ID de la faille. ID CVE ou numéro GHSA, par exemple CVE-2021-32798 ou GHSA-884p-74jh-xrg2.

Par exemple, l'appel suivant montre comment récupérer les résultats d'analyse des images de votre projet qui comportent une occurrence de CVE-2023-23915:

  curl -G -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "filter=(noteProjectId=\"goog-vulnz\" AND noteId=\"CVE-2023-23915\")" \
    https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences

Remplacez les éléments suivants :

  • PROJECT_ID correspond à votre ID de projet Google Cloud. Pour afficher la liste de vos projets, vous pouvez utiliser gcloud projects list.

Rechercher des failles dans plusieurs projets

Utilisez le globbing curl pour effectuer des requêtes dans plusieurs projets.

Par exemple, l'extrait de code suivant définit une variable pour contenir deux ID de projet, puis envoie un appel d'API pour chaque projet afin de rechercher des occurrences.

  PROJECT_IDS="PROJECT_ID_1,PROJECT_ID_2"

  curl -G -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://containeranalysis.googleapis.com/v1/projects/{$PROJECT_IDS}/occurrences"

Remplacez les éléments suivants :

  • PROJECT_ID_1 est l'ID du projet Google Cloud du premier projet que vous souhaitez examiner.
  • PROJECT_ID_2 est l'ID du projet Google Cloud du deuxième projet que vous souhaitez examiner.

Si vous devez trouver des ID de projet, vous pouvez afficher la liste de vos projets à l'aide de gcloud projects list.

Il n'est pas possible d'effectuer un seul appel d'API dans plusieurs projets.

Obtenir une compréhension globale de toutes les métadonnées d'un projet

Demandez toutes les occurrences associées à votre ID de 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

Remplacez les éléments suivants :

  • PROJECT_ID correspond à votre ID de projet Google Cloud.

La sortie inclut des informations sur les failles et d'autres types de métadonnées compatibles associés à votre projet. Par exemple, votre projet peut contenir des informations de compilation ou des attestations.

Interroger une occurrence spécifique pour obtenir tous les détails disponibles

Pour en savoir plus sur une occurrence spécifique, utilisez la requête suivante.

Par exemple, si vous utilisez Pub/Sub pour recevoir des notifications sur les occurrences de failles, Pub/Sub envoie des informations de base pour vous aider à identifier l'occurrence qui a changé et quand. La charge utile inclut un ID d'occurrence. Vous pouvez utiliser l'ID d'occurrence pour interroger des informations afin de vous aider à hiérarchiser les problèmes et à prendre des mesures.

  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

Remplacez les éléments suivants :

  • PROJECT_ID correspond à votre ID de projet Google Cloud.
  • OCCURRENCE_ID est une valeur numérique de la liste des occurrences de l'exemple précédent. Si vous recevez un message de Pub/Sub, utilisez la valeur numérique à la fin de l'URL dans ce message.

La sortie inclut des informations telles que le type de package, la gravité de la faille, le score CVSS et des informations sur les correctifs, le cas échéant.

Étape suivante