Cómo escanear paquetes automáticamente

En este documento, se explica cómo habilitar la API de Container Scanning, enviar una imagen a Artifact Registry y ver la lista de vulnerabilidades encontradas en la imagen.

Artifact Analysis almacena la información de vulnerabilidades como notas. Se crea un objeto occurrence para cada instancia de una nota asociada a una imagen. Consulta los documentos de descripción general y precios para obtener más información.

Antes de comenzar

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

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Verify that billing is enabled for your Google Cloud project.

3. Enable the Artifact Registry and Container Scanning APIs, if any are not already enabled.

   Roles required to enable APIs

   To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

   Enable the APIs

4. Install the Google Cloud CLI.

5. Configure the gcloud CLI to use your federated identity.

   For more information, see Sign in to the gcloud CLI with your federated identity.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

7. Crea un repositorio en Artifact Registry y envía un paquete con el código de la aplicación al repositorio. Si no sabes cómo administrar paquetes en Artifact Registry, consulta los siguientes temas:
   1. Almacena paquetes de Java en Artifact Registry
   2. Almacena paquetes de Node.js en Artifact Registry
   3. Almacena paquetes de Python en Artifact Registry

Si habilitas esta API, también se habilitará el análisis de paquetes de lenguaje en Artifact Registry. Consulta los tipos de paquetes admitidos.

Importante: Cuando habilitas la API de Artifact Analysis, esta comienza automáticamente a analizar cada imagen nueva a medida que se envían a los repositorios de Artifact Registry en tu proyecto. Sin embargo, el análisis está inhabilitado de forma predeterminada para los paquetes enviados a los repositorios de Artifact Registry. Para habilitar el análisis en un repositorio, consulta Cómo controlar la configuración del análisis para un repositorio individual.

Roles obligatorios

Para obtener los permisos que necesitas para ver los resultados del análisis de paquetes, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:

• Agente de servicio de Container Scanner (roles/containerscanning.ServiceAgent)
• Visualizador de casos de Container Analysis (roles/containeranalysis.occurrences.viewer)
• Visualizador de notas de Container Analysis (roles/containeranalysis.notes.viewer)
• Lector de Artifact Registry (roles/artifactregistry.reader)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Consulta las vulnerabilidades del paquete

Artifact Analysis analiza los paquetes nuevos cuando se suben a Artifact Registry. Este análisis extrae información sobre el paquete y sus dependencias.

Puedes ver las ocurrencias de vulnerabilidades de tus imágenes en Artifact Registry 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 sigue analizando imágenes y paquetes siempre que se hayan extraído en los últimos 30 días. Después de 30 días, ya no se actualizarán los metadatos de las imágenes y los paquetes analizados, y los resultados estarán inactivos.

Artifact Analysis archiva los metadatos que han estado inactivos durante más de 90 días. Estos metadatos archivados solo se pueden evaluar con la API. Puedes volver a analizar una imagen con metadatos inactivos o archivados extrayéndola. Los metadatos pueden tardar hasta 24 horas en actualizarse. No se pueden volver a analizar los paquetes con metadatos obsoletos o archivados.

Visualiza las ocurrencias en la consola de Google Cloud

Para ver las vulnerabilidades de un paquete, haz lo siguiente:

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 paquetes, haz clic en el nombre de un paquete.

   Los totales de vulnerabilidades de cada paquete se muestran en la columna Vulnerabilidades.

   

4. Para ver la lista de vulnerabilidades de un paquete, 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 de puntuación de vulnerabilidades común (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 de archivo.La consola de Google Cloud muestra hasta 1,200 vulnerabilidades por página en esta tabla.

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, en la fila con el nombre de la vulnerabilidad, haz clic en Ver o Ver corregida. El texto del vínculo es Ver para las vulnerabilidades sin corrección y Ver corregido para las vulnerabilidades en las que se aplicó una corrección.

Visualiza las ocurrencias con gcloud

Para ver las ocurrencias de los paquetes en Artifact Registry, ejecuta el comando gcloud artifacts versions describe:

gcloud artifacts versions describe VERSION \
    --location=LOCATION --repository=REPOSITORY --package=PACKAGE --show-package-vulnerability

Aquí:

• VERSION es la versión del paquete para la que estás viendo las ocurrencias.
• LOCATION es la ubicación regional o multirregional del repositorio.
• REPOSITORY es el nombre del repositorio en el que se almacena el paquete.
• PACKAGE es el nombre del paquete en el repositorio. No puedes especificar una etiqueta de paquete con este comando.

Visualiza las ocurrencias con la API

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

Filtrar ocurrencias

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

Visualiza los casos de un tipo específico

Puedes usar el valor kind para filtrar por tipo de ocurrencia. Consulta los tipos disponibles.

En los siguientes ejemplos, se muestra cómo filtrar los casos de vulnerabilidad de paquetes:

gcloud

El filtrado de ocurrencias no se admite en Google Cloud CLI para el análisis basado en paquetes.

API

En tu consulta a la API, usa la siguiente expresión de filtro:

kind="PACKAGE_VULNERABILITY" AND resourceUrl="RESOURCE_URL"

Aquí:

• PACKAGE_VULNERABILITY es el tipo de ocurrencia.
• RESOURCE_URL es la URL completa del paquete en el formato projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/packages/PACKAGE_ID/PACKAGE_TYPE/VERSION_ID:
  • PROJECT_ID es el ID del proyecto de la consola de Google Cloud .
  • LOCATION es la ubicación regional o multirregional del repositorio.
  • REPOSITORY es el nombre del repositorio en el que se almacena la imagen.
  • PACKAGE_ID es el nombre del paquete en el que se almacena la imagen.
  • PACKAGE_TYPE es el tipo de paquete de idioma de la aplicación. Los tipos disponibles son pythonPackages, mavenArtifacts y npmPackages.
  • VERSION es el número de versión del paquete.

Puedes usar la función hasPrefix para filtrar con un alcance más amplio.

Por ejemplo, los siguientes filtros se aplican a las ocurrencias de un tipo específico en varias versiones del mismo paquete:

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

Aquí:

• RESOURCE_URL_PREFIX especifica una subcadena de una URL de recurso.
  • Para filtrar todas las versiones de un paquete, omite la versión. Usa el siguiente formato:projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID
  • Para filtrar todos los paquetes de un proyecto, solo especifica la ubicación del recurso y el proyecto. Usa el formato projects/PROJECT_ID/locations/LOCATION.

Visualiza los casos de vulnerabilidad

Puedes ver listas de ocurrencias de vulnerabilidades con gcloud CLI o la API de Artifact Analysis.

gcloud

Para recuperar una lista de ocurrencias de vulnerabilidades para un paquete, usa la marca --show-package-vulnerability:

gcloud artifacts versions describe VERSION_ID --repository=REPOSITORY_ID
  --package=GROUP_ID:ARTIFACT_ID --show-package-vulnerability

Aquí:

• VERSION es el número de versión del paquete.
• REPOSITORY es el nombre del repositorio en el que se almacena el paquete.
• GROUP_ID es el identificador de grupo de tu paquete.
• ARTIFACT_ID es el identificador del artefacto de tu paquete.

API

En tu consulta a la API, usa la siguiente expresión de filtro:

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

Aquí:

• ENCODED_RESOURCE_URL es la ruta de acceso codificada a tu imagen. Para obtener información sobre la codificación, consulta Codificación de URL.

Para obtener más información sobre el uso de la API, consulta projects.occurrences.get.

Cómo ver las imágenes asociadas a 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:

gcloud

El filtrado de ocurrencias no se admite en Google Cloud CLI para el análisis basado en paquetes.

API

GET https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences?filter=noteProjectId%3D%22goog-vulnz%22%20AND%20resourceUrl%3D%22ENCODED_RESOURCE_URL%22%20AND%20noteId%3D%22NOTE_ID%22

Aquí:

• goog-vulnz es el PROVIDER_PROJECT_ID para el análisis de vulnerabilidades de Artifact Analysis. Si usas Artifact Analysis en un proyecto personalizado, puedes reemplazar este valor por tu propio ID del proyecto del proveedor.
• ENCODED_RESOURCE_URL es la ruta de acceso codificada a tu imagen. Para obtener información sobre la codificación, consulta Codificación de URLs.
• NOTE_ID es el ID de la nota. Por ejemplo, cuando veas una vulnerabilidad en los resultados del análisis de Artifact Analysis, a menudo se usará el formato de ID de CVE similar a CVE-2019-12345.

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

gcloud

El filtrado de ocurrencias no se admite en Google Cloud CLI para el análisis basado en paquetes.

API

En tu consulta de la API, agrega la siguiente expresión de filtro:

resourceUrl="RESOURCE_URL" AND noteProjectId="goog-vulnz" \
AND noteId="NOTE_ID"

Aquí:

• RESOURCE_URL es la URL completa del paquete en el formato projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/packages/PACKAGE_ID/PACKAGE_TYPE/VERSION_ID.
• goog-vulnz es el PROVIDER_PROJECT_ID para el análisis de vulnerabilidades de Artifact Analysis.
• NOTE_ID es el ID de la nota. Las notas relacionadas con la seguridad suelen tener el formato CVE-2019-12345.

¿Qué sigue?

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