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:
- Navigate to the Managed Clusters page.
- Select the cluster from the list, and click Reinstall.
- 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
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
Set the executable flag on the binary.
chmod +x ./tigera-scanner
noteYou must download and set the executable flag each time you get a new version of the CLI.
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.
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)
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.
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.
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
Create policy to block vulnerable containers from deploying to your cluster