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.


FlagDescription
--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 stringScans a local OCI tar image. This flag should include the .tar name and its full path.

Syntax example: --oci-archive /home/tmp/image.tar

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:
  • buildah push imageID oci-archive:/path/to/archive:image:tag
  • podman push imageID oci-archive:/tmp/alpine-latest.tar


For more information on the usage of this flag, refer to Usage Examples of Sample command (--oci-archive flag).

--docker-archive stringScans 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.tar

For more information on the usage of this flag, refer to Usage Examples of Sample command (--docker-archive flag).
--registryThe 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 reg-A
  • --registry reg-B, reg-C, reg-D
--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 

While passing this flag to scan local images, the --local string and *--register flags must be passed. 
--root-dir stringScans a directory in a local file system from where the images should be scanned
-- type stringArtifact 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.

It is supported only in direct scanning mode and set globally in the console.


Processing options

Following are the different processing options that you can pass through respective flags:


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

--policies stringsForces 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-executablesSearch 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-sensitiveSearch 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-malwareSearch 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-compliantRegisters the image in the Aqua server only if is determined to be compliant.
--registerAlways registers the image in the Aqua server.


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.



FlagDescription
--architecture string

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. Passing this value overrides the architecture specified in the Server environment variable AQUA_IMAGE_PLATFORM.



Note: If you use this flag, the image will not be registered to the Aqua Server (even if you use the --register flag). The Server will register images only of the architecture specified by the AQUA_IMAGE_PLATFORM Server environment variable configured in the Aqua server.
--os stringScans an image with a specific operating system.
--os-version stringScans an image with a specific operating system version.
--variant stringScans 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.


FlagDescription
--jsonfile stringSaves results in JSON format to the provided path.
--htmlShows output in the HTML format.
--htmlfile stringSaves results in HTML format to the provided path.
--textShows output in text-only format.
--textfile stringSaves results in text format to the provided path.
--full-outputShows full scanner output (including non-vulnerable files and image metadata)
--layer-vulnerabilities

Shows vulnerabilities by image layer.

Note: If direct scanning mode is not set globally, you should pass the --dockerless flag while passing the --layer-vulnerabilities flag to scan images through Scanner CLI.

--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-negligibleShows vulnerabilities of negligible and unknown severity.
--show-will-not-fixShows 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.


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.


FlagDescription
--robot-username stringHarbor Robot account name
--robot-password stringHarbor Robot account password

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:

  1. 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.
  2. 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 codeMeaning
0The image passed all applicable image assurance policies successfully.
1An error occurred in processing the scan request (example: invalid command line options, image not pulled, operational error)
4The image scanned failed at least one of the image assurance Policies specified.