Cómo analizar paquetes del SO automáticamente

En este documento, aprenderás a habilitar la API de Container Scanning, enviar una imagen a Artifact Registry y ver la lista de vulnerabilidades que se encontraron en la imagen.

Artifact Analysis proporciona información sobre las vulnerabilidades de las imágenes de contenedor en Artifact Registry y Container Registry (obsoleto). Los metadatos se almacenan como [notas][notes]. Se crea un caso para cada instancia de una nota asociada con una imagen. Consulta los documentos de descripción general y precios para obtener más información.

Habilitar esta API también habilita el análisis de paquetes de idiomas en Artifact Registry. Consulta los tipos de paquetes admitidos.

Antes de comenzar

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 repositorio de Docker en Artifact Registry y envía una imagen de contenedor al repositorio. Si no conoces Artifact Registry, consulta la guía de inicio rápido de Docker.

Consulta las vulnerabilidades de la imagen

Artifact Analysis analiza las imágenes nuevas cuando se suben a Artifact Registry. Este análisis extrae información sobre los paquetes del sistema en el contenedor.

Puedes ver los casos de vulnerabilidades de tus imágenes en el registro con la consola de Google Cloud , Google Cloud CLI o la API de Container Analysis. Si una imagen tiene vulnerabilidades, puedes obtener los detalles.

Artifact Analysis solo actualiza los metadatos de las imágenes que se enviaron o extrajeron en los últimos 30 días. Después de 30 días, los metadatos ya no se actualizarán y los resultados estarán inactivos. Además, Artifact Analysis archiva los metadatos que están inactivos durante más de 90 días, y estos no estarán disponibles en la consola de Google Cloud , gcloud ni a través de la API. Para volver a analizar una imagen con metadatos inactivos o archivados, extráela. Los metadatos pueden tardar hasta 24 horas en actualizarse.

Visualiza las ocurrencias en la consola de Google Cloud

Para ver las vulnerabilidades de una imagen, sigue estos pasos:

1. Obtén la lista de repositorios.

   Abrir la página repositorios

2. En la lista de repositorios, haz clic en uno.

3. En la lista de imágenes, haz clic en el nombre de una imagen.

   Los totales de vulnerabilidades para cada resumen de imagen se muestran en la columna Vulnerabilidades.

   

4. Para ver la lista de vulnerabilidades de una imagen, haz clic en el vínculo de la columna Vulnerabilidades.

   En la sección Resultados del análisis, se muestra un resumen de los tipos de paquetes analizados, la cantidad total de vulnerabilidades, las vulnerabilidades con correcciones disponibles, las vulnerabilidades sin correcciones y la gravedad efectiva.

   

   En la tabla de vulnerabilidades, se indica el nombre de las vulnerabilidades y exposiciones comunes (CVE) para cada vulnerabilidad encontrada, la gravedad efectiva, la puntuación del Sistema Común de Puntuación de Vulnerabilidades (CVSS), las correcciones (cuando están disponibles), el nombre del paquete que contiene la vulnerabilidad y el tipo de paquete.

   Puedes filtrar y ordenar estos archivos para verificar un archivo, un directorio o un tipo de archivo específico por extensión.

   La consola deGoogle Cloud muestra hasta 1,200 vulnerabilidades en esta tabla. Si tu imagen tiene más de 1,200 vulnerabilidades, debes usar gcloud o la API para ver la lista completa.

5. Para obtener detalles sobre una CVE específica, haz clic en su nombre.

6. Para ver los detalles de la ocurrencia de la vulnerabilidad, como el número de versión y la ubicación afectada, haz clic en Ver o Ver corregida en la fila con el nombre de la vulnerabilidad. El texto del vínculo es Ver para las vulnerabilidades sin corrección y Ver corregidas para las vulnerabilidades en las que se aplicó una corrección.

Visualiza las ocurrencias con gcloud

Para ver los casos asociados a una imagen, sigue estos pasos:

Artifact Registry

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

Aquí:

• LOCATION es la ubicación regional o multirregional del repositorio.
• PROJECT_ID es tu Google Cloud ID del proyecto.
• REPOSITORY es el nombre del repositorio en el que se almacena la imagen.
• IMAGE_ID es el nombre de la imagen en el repositorio. No puedes especificar una etiqueta de imagen con este comando.

De forma predeterminada, el comando devuelve las 10 imágenes más recientes. Para mostrar una cantidad diferente de imágenes, usa la marca --show-occurrences-from. Por ejemplo, el siguiente comando devuelve las 25 imágenes más recientes.

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

Aquí:

• HOSTNAME es el nombre de host multirregional:
  • gcr.io
  • asia.gcr.io
  • eu.gcr.io
  • us.gcr.io
• PROJECT_ID es el ID del proyecto que contiene las imágenes.
• IMAGE_ID es el ID de la imagen para la que deseas ver las vulnerabilidades. No puedes especificar una etiqueta de imagen con este comando.

De forma predeterminada, el comando devuelve las 10 imágenes más recientes. Para mostrar una cantidad diferente de imágenes, usa la marca --show-occurrences-from. Por ejemplo, este comando devuelve las 25 imágenes más recientes.

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

Para ver las vulnerabilidades de una etiqueta de imagen o una capa, sigue estos pasos:

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

Aquí:

• LOCATION es la ubicación regional o multirregional del repositorio.
• PROJECT_ID es tu Google Cloud ID del proyecto.
• REPOSITORY es el nombre del repositorio en el que se almacena la imagen.
• IMAGE_ID es el nombre de la imagen en el repositorio.
• TAG es la etiqueta de imagen sobre la que deseas obtener información.
• HASH es el resumen de la imagen.

Container Registry

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

Aquí:

• HOSTNAME es el nombre de host multirregional:
  • gcr.io
  • asia.gcr.io
  • eu.gcr.io
  • us.gcr.io
• PROJECT_ID es el ID del proyecto que contiene las imágenes.
• IMAGE_ID es el ID de la imagen para la que deseas ver las vulnerabilidades.
• HASH es el resumen de la imagen.

Para filtrar los casos de vulnerabilidades, sigue estos pasos:

Artifact Registry

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

Aquí:

• LOCATION es la ubicación regional o multirregional del repositorio.
• PROJECT_ID es tu Google Cloud ID del proyecto.
• REPOSITORY es el nombre del repositorio en el que se almacena la imagen.
• IMAGE_ID es el nombre de la imagen en el repositorio.
• FILTER_EXPRESSION es una expresión de filtro de muestra con el formato que se explica en Filtrar casos de vulnerabilidades.

Container Registry

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

Aquí:

• HOSTNAME es el nombre de host multirregional:
  • gcr.io
  • asia.gcr.io
  • eu.gcr.io
  • us.gcr.io
• PROJECT_ID es el ID del proyecto que contiene las imágenes.
• IMAGE_ID es el ID de la imagen para la que deseas ver los casos de vulnerabilidades.
• FILTER_EXPRESSION es una expresión de filtro de muestra con el formato que se explica en Filtrar casos de vulnerabilidades.

Visualiza ocurrencias con la API o el código

Para ver las ocurrencias de una imagen, usa el fragmento adecuado. Los fragmentos de código especifican URLs para las imágenes en Container Registry. Si usas Artifact Registry, especifica las imágenes con una URL en el siguiente formato:

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

API

Usa cURL

Para obtener una lista de los casos en tu proyecto, sigue estos pasos:

 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

Para obtener un resumen de las vulnerabilidades de tu proyecto, sigue estos pasos:

 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

Para obtener detalles sobre un evento específico, haz lo siguiente:

 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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Java.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Go.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Node.js.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Ruby.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Python.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Visualiza las ocurrencias en Cloud Build

Si usas Cloud Build, también puedes ver las vulnerabilidades de imágenes en el panel lateral Estadísticas de seguridad dentro de la consola de Google Cloud .

El panel lateral Estadísticas de seguridad proporciona una descripción general de alto nivel de la información de seguridad de la compilación para los artefactos almacenados en Artifact Registry. Para obtener más información sobre el panel lateral y cómo puedes usar Cloud Build para proteger tu cadena de suministro de software, consulta Cómo ver estadísticas de seguridad de la compilación.

Filtra los casos

Puedes usar cadenas de filtro en los comandos de gcloud y en la API de Artifact Analysis para filtrar los casos antes de verlos. En las siguientes secciones, se describen los filtros de búsqueda admitidos.

Visualiza los casos de descubrimiento

Cuando se envía una imagen inicialmente a Container Registry, se crea un caso de descubrimiento que contiene información sobre el análisis inicial de la imagen del contenedor.

Para recuperar un caso de descubrimiento de una imagen, usa la siguiente expresión de filtro:

kind="DISCOVERY" AND resourceUrl="RESOURCE_URL"

En el siguiente fragmento, se muestra cómo usar una expresión de filtro para ver los casos de descubrimiento de una imagen. Los fragmentos de código especifican URLs para las imágenes en Container Registry. Si usas Artifact Registry, especifica las imágenes con una URL en el siguiente formato:

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

gcloud

Para ver los casos de descubrimiento de una imagen, sigue estos pasos:

En este caso, la expresión no se usa directamente en el comando, pero se pasa la misma información como argumentos:

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

Para recuperar el caso de descubrimiento, tu expresión de filtro debe estar codificada como una URL y también incorporada en una solicitud GET de la siguiente manera:

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

Consulta el extremo de la API de projects.occurrences.get para obtener más detalles.

Java

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Java.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Go.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Node.js.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Ruby.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Python.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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)

Visualiza los casos de vulnerabilidades

Para ver los casos de vulnerabilidades de una imagen específica, crea una consulta con una expresión de filtro:

kind="VULNERABILITY" AND resourceUrl="RESOURCE_URL"

El siguiente fragmento muestra cómo recuperar una lista de casos de vulnerabilidades de una imagen. Los fragmentos de código especifican URLs para las imágenes en Container Registry. Si usas Artifact Registry, especifica las imágenes con una URL en el siguiente formato:

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

gcloud

Para ver los casos de vulnerabilidades de una imagen, sigue estos pasos:

En este caso, la expresión no se usa directamente en el comando, pero se pasa la misma información como argumentos:

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

La URL del recurso debe estar codificada como URL y también incorporada en una solicitud GET de la siguiente manera:

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

Consulta el extremo de la API de projects.occurrences.get para obtener más detalles.

Java

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Java.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Go.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Node.js.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Ruby.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Artifact Analysis, consulta las bibliotecas cliente de Artifact Analysis. Para obtener más información, consulta la documentación de referencia de la API de Artifact Analysis Python.

Para autenticarte en Artifact Analysis, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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))

Cómo ver los casos de un tipo específico

En los dos ejemplos anteriores, la única diferencia entre las expresiones de filtro es el valor de kind, que identifica el tipo de caso. Usa este campo para limitar la lista de casos a un tipo determinado, como una vulnerabilidad o una implementación.

Para recuperar los casos de una imagen específica, usa esta expresión de filtro:

kind="NOTE_KIND" AND resourceUrl="RESOURCE_URL"

Aquí:

• NOTE_KIND es el tipo de nota.
  • Por ejemplo, usa el tipo DISCOVERY para enumerar los casos de descubrimiento. Estos se crean para las imágenes cuando se envían inicialmente a Container Registry.
  • Para enumerar los casos de vulnerabilidades, usa el tipo VULNERABILITY.
• RESOURCE_URL es la URL completa de la imagen https://HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH.

La expresión de filtro para recuperar casos de un tipo específico en muchas imágenes es la siguiente:

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

Aquí:

• RESOURCE_URL_PREFIX es el prefijo de URL para algunas imágenes.
  • Para visualizar una lista de todas las versiones de una imagen, utliza: https://HOSTNAME/PROJECT_ID/IMAGE_ID@
  • Para visualizar una lista de todas las imágenes de un proyecto, utiliza: https://HOSTNAME/PROJECT_ID/

Visualiza imágenes asociadas con una nota específica

Puedes recuperar una lista de recursos asociados con un ID de nota específico. Por ejemplo, puedes enumerar imágenes con una vulnerabilidad CVE específica.

Para enumerar todas las imágenes de un proyecto que están asociadas con una nota en particular, usa la siguiente expresión de filtro:

noteProjectId="PROVIDER_PROJECT_ID" AND noteId="NOTE_ID"

Para verificar una imagen específica de una nota en particular, usa la siguiente expresión de filtro:

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

Aquí:

• PROVIDER_PROJECT_ID es el ID del proyecto del proveedor. Por ejemplo, goog-vulnz proporciona el análisis de vulnerabilidades predeterminado.
• NOTE_ID es el ID de la nota. Las notas relacionadas con la seguridad suelen tener el formato CVE-2019-12345.
• RESOURCE_URL es la URL completa de la imagen https://HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH.

Por ejemplo, para verificar todas las imágenes que tengan un caso de CVE-2017-16231 según el análisis de Google, usa la siguiente expresión de filtro:

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

¿Qué sigue?

• Usa las notificaciones de Pub/Sub para recibir notificaciones sobre vulnerabilidades y otros metadatos.

• Crea certificaciones integrando Artifact Analysis en la autorización binaria para evitar que las imágenes de contenedor con problemas de seguridad conocidos se ejecuten en tu entorno de implementación.