Scan Java packages automatically

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

   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

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

4. Enable the Container Scanning API.

   Enable the API

5. Install the Google Cloud CLI.

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

   gcloud init

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

   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

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

9. Enable the Container Scanning API.

   Enable the API

10. Install the Google Cloud CLI.

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

    gcloud init

Important: When you enable the Container Scanning API, billing begins immediately. Once you enable the API for a project, Container Analysis automatically scans each newly pushed image to either Container Registry or Artifact Registry in that project. Container Analysis does not automatically scan existing images. To scan an existing image, you must push it again.

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

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

Artifact Analysis only updates the vulnerability metadata for images that were pushed or pulled in the last 30 days. Artifact 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.

   

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.

  Artifact 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: MAVEN
        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

View vulnerabilities in Cloud Build

Preview

This product or feature is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

If you're using Cloud Build, you can also view image vulnerabilities in the Security insights side panel within the Google Cloud console.

The Security insights side panel provides a high-level overview of build security information for artifacts stored in Artifact Registry. To learn more about the side panel and how you can use Cloud Build to help protect your software supply chain, see View build security insights.

Filter occurrences

You can use filter strings in the gcloud commands and the Artifact 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/

Note: This syntax is not supported by the gcloud command.

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

• Use Pub/Sub notifications to get notifications about vulnerabilities and other metadata.

• Kritis Signer and Voucher allow you create Binary Authorization attestations as part of your build pipeline. These tools can create Binary Authorization attestations based on vulnerability scanning results. For more information, see Creating attestations with Kritis Signer or Creating attestations with Voucher.