Scan Java packages automatically

Stay organized with collections Save and categorize content based on your preferences.

Container Analysis provides vulnerability information for the container images in Artifact Registry. The metadata is stored as notes. An occurrence is created for each instance of a note associated with an image.

This document explains how to enable the Container Scanning API, push an image on Artifact Registry, and see the list of Maven package vulnerabilities found in the image.

Before you begin

  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.

    Go to project selector

  3. Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

  4. Enable the Container Scanning API.

    Enable the API

  5. Install and initialize the Google Cloud CLI.
  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  7. Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

  8. Enable the Container Scanning API.

    Enable the API

  9. Install and initialize the Google Cloud CLI.

Create a repository and push a container image

Create a Docker repository in Artifact Registry and push a container image with your Java code to the repository. For information on how you can use Cloud Build to build and containerize your Java applications, see Building Java applications. If you are not familiar with Artifact Registry, see the Docker quickstart.

View the image vulnerabilities

Container Analysis scans new images when they're uploaded to Artifact Registry. This scan extracts information about the Java packages in the container.

You can view vulnerability occurrences for your images in Artifact Registry using the Google Cloud console, Google Cloud CLI, or the Container Analysis API. If an image has vulnerabilities, you can then obtain the details.

Container Analysis only updates the vulnerability metadata for images that were pushed or pulled in the last 30 days. Container Analysis archives vulnerability metadata that is older than 30 days. To re-scan an image with archived vulnerability metadata, push or pull that image.

View occurrences in the Google Cloud console

To see the vulnerabilities in an image:

  1. Get the list of repositories.

    Open the Repositories page

  2. In the repositories list, click a repository.

  3. Click an image name.

    Vulnerability totals for each image digest are displayed in the Vulnerabilities column.

    Screenshot of an image with vulnerabilities

  4. To view the list of vulnerabilities for an image, click the link in the Vulnerabilities column.

    The vulnerability list shows the severity, availability of a fix, and the name of the package that contains the vulnerability.

    Google Cloud console displays up to 1200 vulnerabilities. If your image has more than 1200 vulnerabilities, use gcloud or the API to view the full list.

  5. To learn more about a specific vulnerability from the vulnerability source, click the View Fix link for that error. This opens a side panel with more details about the file.

  6. In the side panel, click View more info to open a list of the file locations where vulnerabilities were found. You can filter and sort these files to check a specific file, directory, or type of file by file extension.

View occurrences using gcloud

To view occurrences for an image in Artifact Registry, run the following command:

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

Where:

  • LOCATION is the regional or multi-regional location of the repository.
  • PROJECT_ID is your Google Cloud console project ID.
  • REPOSITORY is the name of the repository where the image is stored.
  • IMAGE_ID is the name of the image in the repository. You cannot specify an image tag with this command.

    By default, the command returns the 10 most recent images. To show a different number of images, use the --show-occurrences-from flag. For example, this command returns the 25 most recent images.

    gcloud artifacts docker images list --show-occurrences-from=25 \
    us-central1-docker.pkg.dev/my-project/my-repo/my-image
    

To view vulnerabilities for an image tag or a layer:

  gcloud artifacts docker images describe \
  LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID:TAG \
  --show-package-vulnerability

or

  gcloud artifacts docker images describe \
  LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@sha256:HASH \
  --show-package-vulnerability

Where:

  • LOCATION is the regional or multi-regional location of the repository.
  • PROJECT_ID is your Google Cloud console project ID.
  • REPOSITORY is the name of the repository where the image is stored.
  • IMAGE_ID is the name of the image in the repository.
  • TAG is the image tag about which you want to get information.
  • HASH is the image digest.

    Container Analysis returns results including the packageType. For example:

  - createTime: '2021-11-10T15:45:58.172549Z'
      kind: VULNERABILITY
      name: projects/[PROJECT_ID]/occurrences/[OCCURRENCE_ID]
      noteName: projects/goog-vulnz/notes/CVE-2019-10246
      resourceUri: [RESOURCE_URI]
      updateTime: '2021-11-10T15:45:58.172549Z'
      vulnerability:
        cvssScore: 5.0
        effectiveSeverity: MEDIUM
        fixAvailable: true
        longDescription: 'NIST vectors: AV:N/AC:L/Au:N/C:P/I:N/A:N'
        packageIssue:
        - affectedCpeUri: cpe:/o:alpine:alpine_linux:3.5
          affectedPackage: org.eclipse.jetty:jetty-server
          affectedVersion:
            fullName: 9.2.15.v20160210
            kind: NORMAL
            name: 9.2.15.v20160210
          effectiveSeverity: MEDIUM
          fixAvailable: true
          fixedCpeUri: cpe:/o:alpine:alpine_linux:3.5
          fixedPackage: org.eclipse.jetty:jetty-server
          fixedVersion:
            fullName: 9.2.28.v20190418
            kind: NORMAL
            name: 9.2.28.v20190418
          packageType: Java
        severity: MEDIUM
        shortDescription: CVE-2019-10246

To filter the vulnerability occurrences:

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

Where:

  • LOCATION is the regional or multi-regional location of the repository.
  • PROJECT_ID is your Google Cloud console project ID.
  • REPOSITORY is the name of the repository where the image is stored.
  • IMAGE_ID is the name of the image in the repository.
  • FILTER_EXPRESSION is a sample filter expression in the format explained in Filtering vulnerability occurrences.

View occurrences using the API

To get a list of occurrences in your project:

 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

To get a summary of vulnerabilities in your project:

 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

To get an occurrence:

 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

Filter occurrences

You can use filter strings in the gcloud commands and the Container Analysis API to filter occurrences before viewing them. The following sections describe the supported search filters.

Filtering by package type

To filter results and show only Java package results for an image, use the following gcloud command:

gcloud artifacts docker images list --show-occurrences --occurrence-filter='kind="VULNERABILITY" AND packageType="MAVEN"'

Where:

  • LOCATION is the regional or multi-regional location of the repository.
  • PROJECT_ID is your Google Cloud console project ID.
  • REPOSITORY is the name of the repository where the image is stored.
  • IMAGE_ID is the name of the image in the repository. You cannot specify an image tag with this command.
  • HASH is the image digest.

View vulnerability occurrences

To view vulnerability occurrences for a specific image, create a query with a filter expression including kind="VULNERABILITY" and resourceUrl="MY_RESOURCE_URL".

The following snippets show how to retrieve a list of vulnerability occurrences for an image.

gcloud

To view vulnerability occurrences for an image:

In this case the expression is not used directly in the command, but the same information is passed as arguments:

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

API

The desired resource URL should be URL encoded, and embedded in a GET request as follows:

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

See projects.occurrences.get API endpoint for more details.

Filter by occurrence type

In the two previous examples the only difference between the filter expressions is the value of kind, which identifies the type of occurrence. Use this field to limit the list of occurrences to a particular type, such as a vulnerability or deployment.

To retrieve occurrences for a specific image, use this filter expression:

kind="NOTE_KIND" AND resourceUrl="RESOURCE_URL"

Where:

  • NOTE_KIND is the kind of note.
  • To list vulnerability occurrences, use the kind VULNERABILITY.
  • RESOURCE_URL is the complete URL of the image https://LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@sha256:HASH
  • LOCATION is the regional or multi-regional location of the repository.
  • PROJECT_ID is your Google Cloud console project ID.
  • REPOSITORY is the name of the repository where the image is stored.
  • IMAGE_ID is the name of the image in the repository.

The filter expression to retrieve occurrences of a specific kind across many images is:

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

Where:

  • RESOURCE_URL_PREFIX is the URL prefix for some images
    • To list for all version of an image: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@
    • To list for all images in a project: LOCATION-docker.pkg.dev/PROJECT_ID/

View images associated with a specific note

You can retrieve a list of resources that are associated with a specific note ID. For example, you can list images with a specific CVE vulnerability.

To list all images within a project that are associated with a particular note, use the following filter expression:

noteProjectId="PROVIDER_PROJECT_ID" AND noteId="NOTE_ID"

To check a specific image for a specific note, use the following filter expression:

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

Where:

  • PROVIDER_PROJECT_ID is the ID of the provider project. For example, goog-vulnz provides the default vulnerability analysis.
  • NOTE_ID is the ID of the note. Security related notes are often formatted as CVE-2019-12345.
  • RESOURCE_URL is the complete URL of the image https://LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@sha256:HASH

For example, to check for all images that have an occurrence of CVE-2017-16231 as analyzed by Google, use the following filter expression:

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

What's next