Analizar paquetes automáticamente

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

Artifact Analysis almacena información sobre vulnerabilidades como notas. Se crea una ocurrencia por cada instancia de una nota asociada a una imagen. Consulta los documentos de información general y precios para obtener más información.

Antes de empezar

  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.

    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.

    Go to project selector

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

  4. Enable the Artifact Registry and Container Scanning APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  5. Install the Google Cloud CLI.

  6. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init

  8. 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.

    Go to project selector

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

  10. Enable the Artifact Registry and Container Scanning APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  11. Install the Google Cloud CLI.

  12. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init
  14. Crea un repositorio en Artifact Registry y envía un paquete con el código de tu aplicación al repositorio. Si no sabes cómo gestionar paquetes en Artifact Registry, consulta los siguientes temas:
    1. Almacenar paquetes de Java en Artifact Registry
    2. Almacenar paquetes de Node.js en Artifact Registry
    3. Almacenar paquetes de Python en Artifact Registry

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

Ver 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 vulnerabilidades de tus imágenes en Artifact Registry mediante la Google Cloud consola, la CLI de Google Cloud o la API Container Analysis. Si una imagen tiene vulnerabilidades, puedes obtener los detalles.

El análisis de artefactos sigue analizando imágenes y paquetes siempre que se hayan extraído en los últimos 30 días. Transcurridos 30 días, los metadatos de las imágenes y los paquetes analizados dejarán de actualizarse y los resultados estarán obsoletos.

Análisis de artefactos archiva los metadatos que no se han actualizado en más de 90 días. Estos metadatos archivados solo se pueden evaluar mediante la API. Puedes volver a escanear una imagen con metadatos obsoletos o archivados extrayendo esa imagen. La actualización de los metadatos puede tardar hasta 24 horas. Los paquetes con metadatos obsoletos o archivados no se pueden volver a analizar.

Ver las incidencias en la consola Google Cloud

Para ver las vulnerabilidades de un paquete, sigue estos pasos:

  1. Obtén la lista de repositorios.

    Abre la página Repositorios.

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

  3. En la lista de paquetes, haga clic en el nombre de un paquete.

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

    Un paquete analizado con vulnerabilidades

  4. Para ver la lista de vulnerabilidades de un paquete, haga clic en el enlace de la columna Vulnerabilidades.

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

    La página de resultados del análisis, que muestra las vulnerabilidades, las correcciones y la gravedad efectiva

    En la tabla de vulnerabilidades se indica el nombre de la lista Common Vulnerabilities and Exposures (CVE) de cada vulnerabilidad detectada, la gravedad efectiva, la puntuación del sistema de puntuación Common Vulnerability Scoring System (CVSS), las correcciones (si están disponibles), el nombre del paquete que contiene la vulnerabilidad y el tipo de paquete. Puede filtrar y ordenar estos archivos para consultar un archivo, un directorio o un tipo de archivo específico por extensión de archivo. Google Cloud La consola muestra hasta 1200 vulnerabilidades por página en esta tabla.

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

  6. Para ver los detalles de la vulnerabilidad, como el número de versión y la ubicación afectada, en la fila con el nombre de la vulnerabilidad, haga clic en Ver o Ver corregido. El texto del enlace es Ver para las vulnerabilidades sin corrección y Ver corregidas para las vulnerabilidades en las que se ha aplicado una corrección.

Ver las incidencias con gcloud

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

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

Donde:

  • VERSION es la versión del paquete para la que estás viendo las incidencias.
  • 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.

Ver las incidencias con la API

Para obtener una lista de las incidencias 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

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 información sobre una incidencia concreta, 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/OCCURRENCE_ID

Filtrar incidencias

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

Ver las incidencias de un tipo específico

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

En los siguientes ejemplos se muestra cómo filtrar las ocurrencias de vulnerabilidades de paquetes:

gcloud

No se admite el filtrado de ocurrencias en la CLI de Google Cloud 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"

Donde:

  • 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 Google Cloud ID del proyecto de la consola.
    • 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 ámbito 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")

Donde:

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

Ver las ocurrencias de vulnerabilidades

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

gcloud

Para obtener una lista de las incidencias de vulnerabilidades de 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

Donde:

  • 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 de 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

Donde:

  • ENCODED_RESOURCE_URL es la ruta codificada de tu imagen. Para obtener información sobre la codificación, consulta el artículo sobre la codificación de URLs.

Para obtener más información sobre cómo usar la API, consulta projects.occurrences.get.

Ver las imágenes asociadas a una nota específica

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

Para enumerar todas las imágenes de un proyecto que estén asociadas a una nota concreta, utiliza la siguiente expresión de filtro:

gcloud

No se admite el filtrado de ocurrencias en la CLI de Google Cloud 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

Donde:

  • 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 sustituir este valor por el ID de tu proyecto de proveedor.
  • ENCODED_RESOURCE_URL es la ruta codificada de tu imagen. Para obtener información sobre la codificación, consulta el artículo sobre la 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 artefactos, a menudo se usará el formato de ID de CVE, como CVE-2019-12345.

Para comprobar si una imagen concreta tiene una nota específica, usa la siguiente expresión de filtro:

gcloud

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

API

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

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

Donde:

  • 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.

Siguientes pasos