Scan images for vulnerabilities

Big picture

Scan images for vulnerabilities using Calico Cloud Image Assurance.

Value

Calico Cloud Image Assurances helps you identify vulnerabilities in workloads that you deploy to Kubernetes clusters. A vulnerability can be a weakness in an application (for example, a design flaw or an implementation bug) that allows attackers to cause additional harm. With Image Assurance you can:

• Scan an image for vulnerabilities
• Assess the impact of newly-found vulnerabilities and prioritize remediation efforts
• Create exceptions to ignore specific vulnerabilities
• Create alerts on high-severity vulnerabilities so you can delegate remediation efforts to the appropriate team
• Block non-compliant workloads using policy as part of your cloud-native security posture

About Image Assurance

Image Assurance is based on the Common Vulnerabilities and Exposures (CVE) system, which provides a catalog of publicly-known security vulnerabilities and exposures. Known vulnerabilities are identified by a unique CVE ID based on the year it was reported (for example, CVE-2021-44228).

Image Assurance provides a command-line interface (CLI) to scan images, with the option to send results to the Manager UI. Scanned image content includes:

• Libraries and content (for example, python, ruby gems, jars and go)
• Packages (OS and non-OS)
• Image layer

Before you begin

Update your cluster

Update your cluster to get the latest version of Image Assurance:

1. Navigate to the Managed Clusters page.
2. Select the cluster from the list, and click Reinstall.
3. Copy the updated install script command and run it against your cluster.

Image requirements

To be included in scan results, images must:

• Be available locally through the container runtime environment where the CLI scanner is running

• Have a RepoDigest ID

  To verify RepoDigestIDs, run this command:

  docker images --digests

CLI scanner requirements

• Must have internet access to download and update the vulnerability database
• To see image scan results in Manager UI, the CLI scanner must communicate with an external API endpoint outside your environment

How to

• Start the CLI scanner
• Scan images using CLI
• Scan images using a config file
• Understand scan results in Manager UI
• Create vulnerability exceptions
• Export scan results

Start the CLI scanner

1. Download the latest version of the CLI scanner.

   Linux

   curl -Lo tigera-scanner https://installer.calicocloud.io/tigera-scanner/v3.16.1-5/image-assurance-scanner-cli-linux-amd64

   MacOS

   curl -Lo tigera-scanner https://installer.calicocloud.io/tigera-scanner/v3.16.1-5/image-assurance-scanner-cli-darwin-amd64

2. Set the executable flag on the binary.

   chmod +x ./tigera-scanner
   note

   You must download and set the executable flag each time you get a new version of the CLI.

3. Verify the CLI scanner works correctly by running the version command.

   ./tigera-scanner version
   v1.5.6

Scan images using CLI

You can scan images and report results back to Calico Cloud, or scan images locally without reporting results to Calico Cloud.

Syntax:

tigera-scanner scan [OPTIONS] <image_name>

Options:

• --apiurl - Calico Cloud API URL path. You can get this URL in Manager UI, Image Assurance, Scan settings.
• --token - secure API or authorization token to make requests to Calico Cloud API URL. You can get this URL in Manager UI, Image Assurance, Scan settings.
• --warn_threshold - CVSS threshold for Warn scan results. Range from 0.0 - 10.0.
• --fail_threshold - CVSS threshold for Fail scan results. Range from 0.0 - 10.0.
• --vulnerability_db_path - path to a folder to store vulnerability data (defaults to $XDG_CACHE_HOME; if it is not set, defaults to $HOME/.cache).
• --input_file <file-path> - Path to a JSON file containing image URLs.
• --output_file <file-path> - File path that will contain scan results in a JSON format.

Examples

Scan an image, report results

./tigera-scanner scan ubuntu:latest --apiurl https://<my-org>.calicocloud.io --token ezBhbGcetc...

Scan an image locally, do not report results

./tigera-scanner scan ubuntu:latest

Scan an image with a failure and warning threshold

./tigera-scanner scan ubuntu:latest --fail_threshold 7.0 --warn_threshold 3.9

Scan multiple images locally, do not report results

./tigera-scanner scan ubuntu:latest alpine:latest

Scan multiple images using an input and output file

The input file must have the following JSON structure:

{
  "images": [
    "ubuntu:latest",
    "alpine:latest"
  ]
}

./tigera-scanner scan --input_file images.json --output_file results.json

Scan images using a config file

Create a configuration file in $HOME/.tigera-scanner.yaml for the CLI to read.

note

Key names must match the full name of arguments passed to the CLI. The configuration precedence order is options > environment variables > file configuration.

Options

Options	Shorthand	Environment variable	Description
--apiurl	-a	CC_API_URL	Calico Cloud API URL path. You can get this URL in Manager UI, Image Assurance, Scan settings.
--token	-t	CC_TOKEN	Secure API or authorization token to make requests to Calico Cloud API URL.
--warn_threshold	-w	CC_WARN_THRESHOLD	CVSS threshold for Warn scan results. Range from 0.0 - 10.0.
--fail_threshold	-f	CC_FAIL_THRESHOLD	CVSS threshold for Fail scan results. Range from 0.0 - 10.0.
--vulnerability_db_path	-p	CC_VULNERABILITY_DB_PATH	Path to a folder to store vulnerability data (defaults to $XDG_CACHE_HOME; if it is not set, defaults to $HOME/.cache).
--input_file	-i	CC_INPUT_FILE	Path to the JSON file containing image URLs.
--output_file	-o	CC_OUTPUT_FILE	File path that will contain scan results in a JSON format.

Update the CLI scanner

To get the latest updates, you'll need to update the CLI scanner binary. To see the current version you are running, run this command:

./tigera-scanner version
v1.5.6

To see the latest version, see Release notes.

To download the latest version, see Start the CLI scanner.

Understand scan results in Manager UI

In the left navbar in Manager UI, click Image Assurance, Scan Results.

Scan Results tab

The left panel lists scanned images (assuming you set up the CLI scanner to report scan results to Calico Cloud).

The right pane lists:

• Number of images grouped by Fail, Warn, Pass, and Unknown (the CLI scanner has not yet reported results)
• High Risk Repos (top five repos based on total Fails)

Runtime tab

The left panel lists images running in your cluster. Because you can see the CVEs associated with running pods, you can assess pod vulnerability. The columns, Clusters and Running Instances, show the number of running instances in clusters that are connected to Calico Cloud.

The right panel lists:

• Number of running pods that have images with scan results of Fail, Warn, Pass, and Unknown (the CLI scanner has not yet reported results)
• High Risk Namespaces (top five namespaces based on total Fails)

note

In the Scan Results and Runtime tabs, the Registry path field may be blank if Calico Cloud cannot access this metadata. For example, images from Docker Hub do not specify the registry in the image metadata.

How Pass, Warn, and Fail scores map to CVSS scores

Calico Cloud image scoring is based on the Common Vulnerability Scoring System v3 (CVSS Scores). You can change the CVSS score threshold between a Pass and a Warn, and between a Warn and a Fail. Currently, only CVSS v3 scores are displayed. CVEs that do not have a CVSS v3 score (too old to have one, or are too new to be assigned one), display a blank score in the UI, and N/A in the CLI.

CVSS v3 scores	Image Assurance mapping	Default settings
0.0 – (None) 0.1 – 3.9 (Low)	Pass = 3.9	Low
4.0 – 6.9 (Medium)	Warn = 7	Medium severity – 7
7.0 – 8.9 (High) 9.0 – 10.0 (Critical)	Fail = 8.0	Critical or high – 8

Changing the default CVSS threshold values

The default threshold values (shown below) will work for the majority of Calico Cloud deployments. However, you may need to change the defaults because of security requirements.

To change the CVSS threshold values, note the following:

• Changes to threshold values take effect immediately and alter the scan results for images already in the system
• If you are using admission controller policies, changing a value may allow pods in your Kubernetes cluster that were previously being blocked, to now be deployed or vice versa.

Enable Runtime View

You can configure your scan settings to directly monitor pods that are running in your Kubernetes clusters. When enabled, Runtime View checks image information from the active container images in all of your connected clusters. These images are correlated with the images you have recorded in the Image Assurance system.

To enable Runtime View, select the Enable Runtime View checkbox in the Scan Results tab. You can clear the checkbox to disable Runtime View. After disabling Runtime View, some runtime information for existing images will remain in the system.

note

If your cluster does not use the default containerd socket path (/run/containerd/containerd.sock), then you must change the path to allow the Runtime View service to collect image information.

To update the CRI socket path for a cluster, run the following command:

kubectl patch imageassurance default --type='merge' -p '{"spec":{"criSocketPath":"<path-to-cri-socket>"}}'

See the installation reference for more details on the ImageAssurance CR.

Create vulnerability exceptions

In some cases, you may want to ignore specific vulnerabilities or CVEs. For example:

• You determine scan results are "false positives" (based on how you are using the affected package)
• You decide to exclude a vulnerability based on your own internal assessment

To exclude a vulnerability from scanning results, create a vulnerability exception.

In the left navbar in Manager, click Image Assurance, Vulnerability Exceptions.

Before creating an exception, it is important to understand the effects to Image Assurance.

• Maximum CVSS score

  An image’s maximum CVSS score may be reduced to a lower score. An exception could eliminate the vulnerability with the highest CVSS score for an image.

• Scan results

  Scan results for Pass/Warn/Fail could change because they are based on the maximum CVSS score. For example, Fail could change to Warn, and Warn could change to Pass.

• Vulnerability global alerts

  Alerts may no longer be generated. Alerts are triggered based on scan results or maximum CVSS score values of images.

• Admission controller

  Pods could be created where they were previously blocked. Admission controller policies are based on vulnerability information (scan result and/or maximum CVSS score).

Export scan results

To export the scan results for images you have scanned and uploaded to Image Assurance:

On the Scan Results or Runtime tab of the Manager UI, click Export.

The export generates a CSV file with image and CVE metadata for the current list of images you have selected (based on your current filter options). Options include:

• Export one row for each image and CVE ID exports a unique image + CVE combination for each row. For example, if an image has 10 CVEs, 10 rows are created (1 for each CVE).
• Export one row per image exports one row for each image, with all associated CVEs condensed into a single column.
• Export for scanning exports a JSON file that contains image URLs which can be used as an input to the scanner.

note

Images with no associated CVEs are not included in the exported data (regardless of whether or not it is included by the filters).

Next steps

• Set up alerts on vulnerabilities

• Create policy to block vulnerable containers from deploying to your cluster