Scan Argument
TABLE OF CONTENTS
Overview
This topic explains the scan command syntax and different parameters passed through the Image Scanning Command Line Interface (CLI). When attempting to run singular scans or ad-hoc scans, the appropriate argument is 'scan' with the appropriate flags for the scan logistics.
The scan command syntax contains different command flags, scanner output and processing options. You can also pass specific image assurance policies that should be evaluated while scanning images. This also includes whether the image is local to the scanner (--local) or is hosted in a registry (--registry) that Aqua server is aware of. With the additional flags, you can specify different conditions for the scan results to be returned. For more information on the flags, refer the following sections in this document.
This command deploys either a scanner image or a scanner executable binary to scan a single image. This command can scan images stored in one of the following registries:
- Remote: in a registry that has been added to Aqua.
- Local: on the host on which this command is issued.
For more information on the usage of scan command, refer to Usage Examples of Scanner Commands.
Command flags
Following is the list of flags that can be passed with the scan command. Refer to General flags (all commands) for more information on the general flags.
For documentation purposes, the command-specific flags are arranged in multiple sections in the context of their usage.
Location and type of images to scan
Following is the list of flags supported for the images, depending on the type and location where they are scanned.
| Flag | Description |
|---|---|
| --local string | Scans an image by name from a local Docker client. The Docker default socket location is used (/var/run/docker.sock). Syntax example: --local ubuntu:latest |
| --oci-archive string | Scans a local OCI tar image. This flag should include the .tar name and its full path. Syntax example: --oci-archive /home/tmp/image.tar imagename Refer the OCI tar image support limitations section for more information. This flag has been tested on images built with Buildah or Podman. Syntax example:
For more information on the usage of this flag, refer to Usage Examples of Sample command (--oci-archive flag). |
| --docker-archive string | Scans a local docker tar file which has image. This flag is associated with folder path where docker tar file is stored. Syntax example: --docker-archive /home/ubuntu/alpine-latest.tar alpine:latest For more information on the usage of this flag, refer to Usage Examples of Sample command (--docker-archive flag). |
| --registry | The use and effect of the --registry flag depends on whether the image is remote or local. |
| --registry string (when used with remote scans) | Scans an image from a remote registry. While using the --registry flag, you should pass the name of the registries defined in the Aqua Integrations > Registry page. When you use this flag, the default registry is “Docker Hub”. This flag can take either a single registry name or a comma-separated list of registries. You can include this flag more than once. It is required that all registries have already been added to Aqua. For examples, using both the flags specify four registries reg-A, reg-B, reg-C, and reg-D Syntax Examples:
|
| --registry < registry_name > (when used with local scans) | Scans a local image, and register it with Aqua as if it came from the registry named. Example: --registry reg-A It is required that all registries have already been added to Aqua. While passing this flag to scan local images, the --local string and --register flags must be passed. |
| --root-dir string | Scans a directory in a local file system from where the images should be scanned |
| -- type string | Artifact type scanned from root directory (image or cf-app) |
OCI tar and docker tar image support limitations
Following flags are not supported with --oci-archive:
- The --register flag is not supported with --oci-archive due to a limitation in the Docker registry where the image ID is changed after pushing image to the registry. Aqua Security recommends that after the --oci-archive scan, you should push the image to the registry and register it from this registry.
- The --local flag is not supported with --oci-archive and --docker-archive due to both being arguments that point to the image source. Only one source can be defined while scanning an image.
Processing options
Following are the different processing options that you can pass through respective flags:
| Flag | Description |
|---|---|
| --checkonly | Returns a zero return code even if the image fails an assurance policy. Refer to the Return Codes section for more information. Use case: When you want to have multiple teams working on the same project with assurance policy that would fail the CI/CD pipeline and you want that one of the team’s pipeline should not fail. |
| --policiesstrings | Forces Aqua to use the provided image assurance policies. This is applicable to local scans only. This flag is case-sensitive. You can pass multiple policies as comma separated. You cannot pass this flag with --registry flag, means policies cannot be applied on the image scanning from a remote registry. For more information on the usage of policies, refer to the Pass Assurance Policies section. |
| --collect-executables | Search and list down non-package executables in the scan results, after scanning images. This flag gives results of non-package executables only when you scan images locally by passing the --local flag. |
| --collect-sensitive | Search sensitive data while scanning image and show in the scan results. This flag forces scanner to scan images for sensitive data even though the respective checkbox, Search for sensitive data in images and functions in the Aqua UI, Settings > Scanning page is disabled. |
| --scan-malware | Search malware files while scanning image and show in the scan results. This flag forces scanner to scan images for sensitive data even though the respective checkbox, Scan for malware in the Aqua UI, Settings > Scanning page is disabled. |
| --register-compliant | Registers the image in the Aqua server only if is determined to be compliant. While passing this flag to register an image, the --registry flag with the registry name must also be passed to determine where to register the image. It is required that all registries have already been added to Aqua. |
| --register | Always registers the image in the Aqua server. While passing this flag to register an image, the --registry flag with the registry name must also be passed to determine where to register the image. It is required that all registries have already been added to Aqua. |
Image architecture
Following is the list of flags that can be passed to scan images from multiple architectures.
Notes:
- Providing a Docker socket to the Aqua Scanner container is not required.
- If you use the --architecture flag, the image will not be registered to the Aqua server.
| Flag | Description |
|---|---|
| --architecturestring | Scans an image with a specific architecture. You can specify any architecture string from which the image was built. The architecture values depend on the build tools and are set by convention. Note: If you use this flag, the image will not be registered to the Aqua Server (even if you use the --register flag). |
| --osstring | Scans an image with a specific operating system |
| --os-versionstring | Scans an image with a specific operating system version |
| --variantstring | Scans an image with a specific operating system variant |
Output options
Following are the different output options that you can pass through respective flags. For more information, refer to the Scanner output section.
| Flag | Description |
|---|---|
| --jsonfilestring | Saves results in JSON format to the provided path |
| --html | Shows output in the HTML format |
| --htmlfilestring | Saves results in HTML format to the provided path |
| --text | Shows output in text-only format |
| --textfilestring | Saves results in text format to the provided path |
| --full-output | Shows full scanner output (including non-vulnerable files and image metadata) |
| --layer-vulnerabilities | Shows vulnerabilities by image layer |
| --hide-base | Hides vulnerabilities in the base image. This is used to hide any existing vulnerabilities from a base image. These vulnerabilities are known from the base image and not required to be reported on every image created from the specific base image. |
| --show-negligible | Shows vulnerabilities of negligible and unknown severity |
| --show-will-not-fix | Shows vulnerabilities that will not be fixed by the software vendor. For example, If you scan an image created from a software vendor engine which has vulnerabilities and is not fixed by software vendor due to the usage of outdated software version. |
| --emit-defaults | Shows Zero (0) values in the scan results. For example: "malware": "0". This flag will display values of the numeric data type fields as string values. To prevent difficulty in parsing string values for numeric fields, an additional JSON attribute "numeric_image_scan_result" will be displayed in the scan result, to show the numeric conversions of the non-string data type fields.” |
Scanning images in Harbor registry
Following are the specific command flags used by the Harbor Scanner Adapter to scan images stored in the Harbor registry. For more information on the Harbor Scanner Adapter for Aqua CSP Scanner and its integration, refer to the Aqua Github repository, harbor-scanner-aqua.
| Flag | Description |
|---|---|
| --robot-usernamestring | Harbor Robot account name |
| --robot-passwordstring | Harbor Robot account password |
Scanning the image file system using the Podman container engine
Following are the specific command flags used exclusively for scanning the local image file system using the Podman container engine. To understand the scan command for scanning the image file system using the Podman container engine, refer to General Command Syntax.
| Flag | Description |
|---|---|
| --image-namestring | Name of the image stored locally in the host, which can be scanned using the Podman container engine. Syntax example: --image-name alpine:latest |
| --fs-scanstring | Scans a local file system using the Podman container engine. This flag should have the location of the image file system to be scanned. Syntax example: --fs-scan /home/ubuntu |
Pass Assurance Policies
You can pass specific image assurance policies through command syntax, to apply on the respective images for scanning. While scanning an image through scanner CLI, Aqua evaluates the scan results such as the security issues found, according to all applicable assurance policies.
The applicable policies are determined as follows:
- Remote image: The scanner uses all the respective image assurance policies, the scope of which includes the specific image.
- Local image: Scanner uses the respective image assurance policies named in the --policies flag(s) specified with the command. If this flag is not specified, the scanner uses only the Default Assurance Policy.
For more information on the usage of the respective flags, refer to Examples of Scanner command Syntax.
Scanner output
When you run the scanner, a log is displayed showing steps of the scan. After the log, the scanner creates an output file which includes:
- Image metadata
- List of components found in the image such as malware, sensitive data, vulnerabilities, and so on
- List of vulnerabilities found in the image. If the --layer-vulnerabilities flag is specified, the vulnerabilities will be listed in the image layer(s) in which they were found.
- List of image assurance policy controls that were evaluated based on the Image Assurance Policies selected
- Summary section
Scanner output options
Scanner command provides output results in the JSON format, by default. You can use the output result file for the reporting purposes. To save output to a specified file format, perform the following steps:
- Include a volume mount on the host in the scan command. This is where the scanner container will place the output file. You should add the volume mount such as -v /tmp:/tmp.
- Specify the flag(s) as described, per the desired output format:
- JSON (default): Use --jsonfile to specify the path and name of the output file.
- HTML: Use --html (without parameters), and --htmlfile to specify the path and name of the output file.
- Text-only: Use --text (without parameters), and --textfile to specify the path and name of the output file.
For more information on the usage of the respective flags, refer to Examples of Scanner command Syntax.
Return codes
You should pass echo $? after Aqua scanner completes the scan operation and exits. You receive one of the following return codes to notify the status of the scan operation.
After passing any command, If the return code is a non-zero (other than zero), it indicates an error.
Following is the list of different return codes with their meanings, after passing the scan command.
| Return code | Meaning |
|---|---|
| 0 | The image passed all applicable image assurance policies successfully |
| 1 | An error occurred in processing the scan request (example: invalid command line options, image not pulled, operational error) |
| 4 | The image scanned failed at least one of the image assurance Policies specified |
Did you find it helpful? Yes No
Send feedback