Cómo analizar paquetes de Java 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 que se encontraron en la imagen.

Artifact Analysis almacena la información de vulnerabilidades como notas. 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.

Antes de comenzar

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

    Si deseas obtener información para usar Cloud Build para compilar y crear contenedores para tus aplicaciones de Java, consulta Compila, prueba y crea contenedores para aplicaciones de Java.

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 en el contenedor.

Puedes ver los casos de vulnerabilidad 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 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 los metadatos 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. La actualización de los metadatos puede tardar hasta 24 horas.

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.

    Una imagen analizada con 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.

    La página de resultados del análisis muestra las vulnerabilidades, las 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 Common Vulnerability Scoring System (CVSS), las correcciones (cuando están disponibles), el nombre del paquete que contiene la vulnerabilidad y el tipo de paquete.

    La consola deGoogle Cloud muestra hasta 1,200 vulnerabilidades por página en esta tabla. Puedes filtrar y ordenar estos archivos para verificar un archivo, un directorio, una capa o un tipo de archivo específicos por extensión.

  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 corregido para las vulnerabilidades en las que se aplicó una corrección.

Cómo ver las vulnerabilidades en una capa específica

Artifact Analysis proporciona metadatos específicos de la capa para ayudarte a identificar qué paquete contiene vulnerabilidades y qué comando de compilación de Docker introdujo esa capa.

Para ver los metadatos de vulnerabilidades basados en capas en la consola de Google Cloud , haz lo siguiente:

  1. En Artifact Registry, abre tu lista de repositorios.

    Abrir la página repositorios

  2. En la página Repositorios, haz clic en un repositorio.

  3. En la página Detalles del repositorio, haz clic en una imagen.

  4. En la lista de versiones de la imagen, haz clic en un resumen de la imagen.

  5. En la página de detalles del resumen de la imagen, haz clic en la pestaña Vulnerabilidades.

    Cuando hay metadatos basados en capas disponibles, Artifact Analysis muestra una lista de capas seleccionables en la barra Capa:

    Imagen de la página Vulnerabilidades para un resumen de imagen, incluida la barra Capa. La barra de capas tiene un menú desplegable para seleccionar una capa de una lista numerada.

  6. Para ver la lista de capas, haz clic en el menú desplegable de capas.

    Se abrirá una lista desplegable que muestra una lista numerada de capas. La capa 0 representa la capa inferior, y cada capa siguiente se basa en la anterior. Solo se muestran las capas en las que se encontraron vulnerabilidades.

    Imagen de un menú desplegable de capas abierto. En el menú, se muestra el comando de Docker que se usó para compilar la capa, y el tipo y la cantidad de vulnerabilidades de cada capa.

    Para cada capa, Artifact Analysis muestra el comando de Docker que se usó para compilarla y la cantidad de vulnerabilidades que se encontraron en ella.

  7. Para obtener más información sobre las vulnerabilidades en una capa específica, selecciona una capa de la lista de capas.

    La tabla de vulnerabilidades se actualiza para mostrar solo las vulnerabilidades encontradas en la capa seleccionada. Puedes aplicar más filtros o investigar vulnerabilidades específicas.

  8. Haz clic en VER o VER LA CORRECCIÓN junto a una vulnerabilidad para ver información más detallada sobre ella.

    En el panel lateral Detalles de la vulnerabilidad, se muestran las ubicaciones de los archivos en los que los paquetes tienen vulnerabilidades.

  9. En la tabla Ubicaciones de archivos, coloca el cursor sobre el signo de interrogación para abrir metadatos de capas adicionales.

    En un diálogo, se muestran el índice de la capa, el comando de compilación de la capa, el resumen de la capa y la imagen base en la que puedes corregir la vulnerabilidad.

Visualiza las ocurrencias con gcloud

Para ver las ocurrencias de una imagen en Artifact Registry, ejecuta el comando gcloud artifacts docker images list:

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 el ID del proyecto de tu consola de Google Cloud .
  • 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

El resultado es similar al siguiente:

Imagen de salida de muestra

  {
      "name": "projects/my-project/locations/us-central1/occurrences/22d3edfb-34f2-4d3f-be08-fd90c549f010",
      "resource": {
        "uri": "https://us-central1-docker.pkg.dev/my-project/my-repo/golang-nginx@sha256:5b54ef20748417ccdb0b87afedf98c44e699e2f59bd6cv48cbdc1ca2e72c80e3"
      },
      "noteName": "projects/my-project/locations/us-central1/notes/CVE-2005-2541",
      "kind": "VULNERABILITY",
      "createTime": "2025-01-21T15:57:01.238832Z",
      "updateTime": "2025-01-21T15:57:01.238832Z",
      "vulnerability": {
        "severity": "CRITICAL",
        "cvssScore": 10,
        "packageIssue": [
          {
            "affectedLocation": {
              "cpeUri": "cpe:/o:debian:debian_linux:12",
              "package": "tar",
              "version": {
                "name": "1.34+dfsg",
                "revision": "1.2+deb12u1",
                "kind": "NORMAL"
              }
            },
            "fixedLocation": {
              "cpeUri": "cpe:/o:debian:debian_linux:12",
              "package": "tar",
              "version": {
                "kind": "MAXIMUM"
              }
            },
            "packageType": "OS",
            "effectiveSeverity": "LOW",
            "file_location": [
                {
                "file_path": "/var/lib/dpkg/status",
                "layerDetails": {
                  "index": 0,
                  "diffID": "sha256:123",
                  "buildCommand": "FROM golang:example_sha256",
                  "BaseImages": [
                    {
                      "name": "library/golang",
                    },
                  ],
                },
              },
            ],
          }
        ],
        "shortDescription": "CVE-2005-2541",
        "longDescription": "NIST vectors: AV:N/AC:L/Au:N/C:C/I:C/A:C",
        "relatedUrls": [
          {
            "url": "https://security-tracker.debian.org/tracker/CVE-2005-2541",
            "label": "More Info"
          }
        ],
        "effectiveSeverity": "LOW",
        "cvssVersion": "CVSS_VERSION_2",
        "cvssV2": {
          "baseScore": 10,
          "attackVector": "ATTACK_VECTOR_NETWORK",
          "attackComplexity": "ATTACK_COMPLEXITY_LOW",
          "authentication": "AUTHENTICATION_NONE",
          "confidentialityImpact": "IMPACT_COMPLETE",
          "integrityImpact": "IMPACT_COMPLETE",
          "availabilityImpact": "IMPACT_COMPLETE"
        }
      }
    }
  

Cómo ver las vulnerabilidades de una etiqueta de imagen

Para ver las vulnerabilidades de una etiqueta de imagen, ingresa uno de los siguientes comandos:

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 el ID del proyecto de tu consola de Google Cloud .
  • 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.

Artifact Analysis devuelve resultados que incluyen el packageType.

Cómo filtrar casos de vulnerabilidades

Para filtrar los casos de vulnerabilidades, usa el parámetro --occurrence-filter:

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 el ID del proyecto de tu consola de Google Cloud .
  • 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.

Cómo ver las vulnerabilidades de una capa específica

Puedes usar el campo layerDetails para determinar qué capa específica introdujo un paquete vulnerable y ver información adicional sobre esa capa. Por ejemplo, considera el siguiente resultado de layerDetails para una imagen:

  "layerDetails": {
    "index": 0,
    "diffID": "sha256:123",
    "buildCommand": "FROM golang:example_sha256",
    "BaseImages": [
      {
        "name": "library/golang",
      },
    ],
  }

El resultado muestra que el índice de la capa es 0 en la imagen del contenedor, con un hash de capa de sha256:123. El comando de compilación de Docker que se usó para compilar esta capa es FROM golang:example_sha256, y la capa también se encuentra en la imagen base library/golang.

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

Cómo ver vulnerabilidades 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.

Cómo ver 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 las ocurrencias de implementación de una imagen:

gcloud

En gcloud CLI, ejecuta el siguiente comando:

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

Aquí:

  • DEPLOYMENT es el tipo de ocurrencia.
  • LOCATION es la ubicación regional o multirregional del repositorio.
  • PROJECT_ID es el ID del proyecto de tu consola de Google Cloud .
  • REPOSITORY es el nombre del repositorio en el que se almacena la imagen.
  • IMAGE_ID es el nombre de la imagen en el repositorio.

API

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

kind="DEPLOYMENT" AND resourceUrl="RESOURCE_URL"

Aquí:

  • DEPLOYMENT es el tipo de ocurrencia.
  • RESOURCE_URL es la URL completa de la imagen en el formato https://LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@sha256:HASH.

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

Por ejemplo, los siguientes filtros para casos de un tipo específico en muchas imágenes:

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 una imagen, omite el resumen de la imagen. Usa el formato https://LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@.
    • Para filtrar todas las imágenes de un proyecto, solo especifica la ubicación del recurso y el proyecto. Usa el formato https://LOCATION-docker.pkg.dev/PROJECT_ID/.

Visualiza los casos de vulnerabilidades

Para recuperar una lista de casos de vulnerabilidades de una imagen, puedes filtrar por el tipo de caso VULNERABILITY.

gcloud

En gcloud CLI, ejecuta el siguiente comando:

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

Aquí:

  • VULNERABILITY es el tipo de ocurrencia.
  • LOCATION es la ubicación regional o multirregional del repositorio.
  • PROJECT_ID es el ID del proyecto de tu consola de Google Cloud .
  • REPOSITORY es el nombre del repositorio en el que se almacena la imagen.
  • IMAGE_ID es el nombre de la imagen en el repositorio.

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.

Filtrar por tipo de paquete

Para limitar los resultados del análisis de vulnerabilidades a un tipo de paquete, ejecuta el siguiente comando de gcloud CLI:

  gcloud artifacts docker images list /
      --show-occurrences /
      --occurrence-filter='kind="VULNERABILITY" AND packageType="PACKAGE_TYPE"' /
      LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID

Aquí:

  • VULNERABILITY es el tipo de ocurrencia.
  • PACKAGE_TYPE es el tipo de paquete de idioma de la aplicación. Los tipos disponibles son: COMPOSER, GO, MAVEN, NPM, NUGET, PYTHON, RUBYGEMS y RUST.
  • LOCATION es la ubicación regional o multirregional del repositorio.
  • PROJECT_ID es el ID del proyecto de tu consola de Google Cloud .
  • 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.

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:

gcloud

gcloud artifacts docker images list /
    --show-occurrences /
    --occurrence-filter='noteProjectId="goog-vulnz" AND noteId="NOTE_ID"' /
    LOCATION-docker.pkg.dev/PROJECT_ID

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 el ID de tu propio proyecto de proveedor.
  • LOCATION es la ubicación regional o multirregional del repositorio.
  • PROJECT_ID es el ID del proyecto de tu consola de Google Cloud .
  • 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.

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 el ID de tu propio proyecto de 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 URL.
  • 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 de una nota en particular, usa la siguiente expresión de filtro:

gcloud

gcloud artifacts docker images list /
    --show-occurrences /
    --occurrence-filter='noteProjectId="goog-vulnz" AND noteId="NOTE_ID"' /
    LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID

Dónde

  • LOCATION es la ubicación regional o multirregional del repositorio.
  • PROJECT_ID es el ID del proyecto de tu consola de Google Cloud .
  • 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.

API

En tu consulta a 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 de la imagen en el formato https://LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@sha256:HASH.
  • 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 el ID de tu propio proyecto de proveedor.
  • NOTE_ID es el ID de la nota. Las notas relacionadas con la seguridad suelen tener el formato CVE-2019-12345.

¿Qué sigue?