TABLE OF CONTENTS

Introduction

The Aqua Scanner scans images one at a time. An image is typically scanned in about one minute. 


When Aqua is first deployed, the Aqua server is configured to perform scanning of all images. As the number of images grows, you will probably want to add additional scanners, in the form of scanner daemons, to handle the additional workload.


Aqua has two types of scanners: one for Linux platforms, which scans Linux images and one for Windows platforms, which scans Windows images. You can add scanners of each type, according to need, following the instructions below. 

Overview

This topic explains how to deploy an additional scanner daemon for the image scanning. The scanner CLI (Command Line Interface) can deploy additional scanners to the Aqua server that can handle registration scans. This allows the scan load to get pushed from the console to the scanners for more throughput. You can see the deployment of new daemon scanner on the Aqua Security page, Administration > Scanners. The new scanner will be deployed in daemon mode as a running container and the Aqua console will route scans to the specific scanner when it is available and there are enough pending jobs in queue with other scanners.


When the Server needs an image to be scanned, it sends a request to one of the scanner processes that is not busy. This implements a basic load-balancing mechanism. The request includes:

  • Name of the registry in which the image is found
  • Image name

The actual image scanning performed by the daemon is affected by the Scan options that have been configured by your Aqua admin.


After daemon scanner is deployed, Aqua admins can reserve this specific scanner with any registry integration manually. This action allows images from the specific registry scanned using the scanner exclusively. This will also helps reducing image scanning load on Aqua server by distributing image scanning jobs to various scanner daemons as configured.


Prerequisites

  • Ensure that the registry has been added to Aqua so the scanner assigned to the specific registry can access it.
  • Ensure that your Aqua admin should grant you the permission as scanner role to deploy additional scanner daemon.

Registry specification

Logic

The scanner should communicate with the registry directly, to obtain the image for scanning. For various reasons, including those of physical deployment and data security, you can optionally configure each daemon to work only with specific image registries. Each scanner can be configured individually as follows:

  • The flag -R (or --registries) specifies one or more registries that the daemon scans.
  • The flag -E (or --registries-exclusion) specifies one or more registries that the daemon does not scan.

When the daemon receives a request for scanning an image, it performs one of the following actions:

  • If the registry is within the set of registries that the daemon scans, it scans the image
  • Otherwise, it informs the Aqua server that it refuses to scan the image. The server then dispatches the image to a different scanner daemon (if available) for scanning.

Examples

The following examples show how the flags operate. Each flag can accept either a single registry name or a comma-separated list of registries. You can also include either or both flags more than once. To be generic, the term "list" below is used to denote all the registry names supplied with the respective flags.


-R or --registries-E or --registries-exclusionThe scanner scans the image...
Not passed any registryNot passed any registryalways
-R list-1Not passed any registryIf it is in any registry in list-1
Not passed any Registry-E list-2

If it is NOT in any registry in list-2

-R list-1-E list-2If it is in any registry in list-1
AND
It is NOT in any registry in list-2


Add a Scanner for Linux environment

The Linux version of the Aqua scanner is deployed as a container on a Linux host. You should use it to scan Linux images. To add a Aqua scanner:

  1. Navigate to Administration > Scanners.
  2. Click Connect Scanner. Connect New Scanner dialog appears.
  3. Enter scanner name. No spaces or special characters allowed in this field.
  4. (Optional) Enter the description as required to identify the scanner. For example, This scanner supports Docker Hub.
  5. Select the Linux radio button. 
  6. Click Save And Get Deployment Command. Deployment Command dialog appears which shows the docker command that can be used to deploy a new scanner.


      7. Click the Copy button next to the command to copy the docker command.



       8. Open a command line on the host on which the scanner will run, and paste the copied command line text. 

       9. Make substitutions to <aqua_server_url>.

    10. (Optional) Add the required flags from the Command flags section below to apply the respective configurations to the new scanner. Following is the sample command syntax to deploy scanner as a daemon to the Aqua console on your Linux host. 

docker run -d -e SCALOCK_LOG_LEVEL=DEBUG -e AQUA_TOKEN=f49fb2c6922c6e23b397931c450bf00ce0284d2f -v /var/run/docker.sock:/var/run/docker.sock registry.aquasec.com/scanner:6.2 daemon --host <aqua_server_url> -R "Docker Hub" 


In the above command, the -R flag is passed to dedicate this scanner to specific registry for image scanning.


  11. Run the command. This action will start adding an additional scanner on the host.


You can see that the new scanner is registered in the Aqua platform and shown in the scanner list with the last heartbeat. You can repeat this procedure to add multiple scanners, as required.


Add a Scanner for Windows environment

The Windows scanner is installed on a Windows server. You can use it to scan images based on Windows. To add a scanner for Windows environment:

  1. Navigate to Administration > Scanners.
  2. Click Connect Scanner. Connect New Scanner dialog appears.
  3. Enter scanner name. No spaces or special characters allowed in this field.
  4. (Optional) Enter the description as required to identify the scanner. For example, This scanner supports Window images.
  5. Select the Windows radio button.
  6. Click Save And Get Deployment Command. Deployment Command dialog appears which shows the Executable and MSI commands that can be used to deploy a new scanner. 

       7. To use the Executable command to deploy a scanner, download and setup Aqua Scanner Installer for Windows. For more information, refer to Scanner Command Line Interface.

       8. In the Executable textbox, click the Copy button to copy the Executable command.



       9. Open a command line on the host on which the scanner will run, and paste the copied command line text. 

     10. Make substitutions to <aqua_server_url>.

     11. Run the command. Following is the sample command syntax to deploy scanner as a daemon to the Aqua console on your Windows host.

scannercli.exe --token fb1cd58f4ec2e2d95adb1d12f967e0ea682533a2 --host <aqua_console_url> daemon -R “Docker Hub”


12. To use MSI command to deploy a scanner, create a folder c:\Aqua on your Windows server and copy and extract the installation file AquaScannerWindowsInstaller*.msi to this folder.

    13. In the MSI textbox, click the Copy button to copy the MSI command.

    14. In the command prompt from the location of the MSI file, run the following MSI command after substituting the <aqua_server_url>.

msiexec /I scannercli_windows_msi SERVER=<aqua_console_url> --TOKEN=fb1cd58f4ec2e2d95adb1d12f967e0ea682533a2 /qn


You can see that the new scanner is registered in the Aqua platform and shown in the scanner list with the last heartbeat. You can repeat this procedure to add multiple scanners, as required.


Command flags for daemon argument

Following is the list of different flags used while passing daemon command to deploy a new scanner. 


FlagDescription
-R or --registries string arrayThis flag is followed by a registry name. You can pass this flag to include the registry or registries (comma-separated list) that you want to dedicate this scanner for images scanning. You can define one scanner for each registry being used for image scanning. You can pass this flag multiple times to include multiple registries. Passing this flag is optional.

You can include an asterisk as a wildcard character in a registry name. Examples: acr*, *acr, a*r.

Sample Command Syntax: -R “Docker Hub”

For more information, refer to the Registry specification section.
-E or --registries-exclusion string arrayThis flag is followed by a registry name. You can pass this flag to exclude the registry or registries (comma-separated list) that you want to exclude this scanner from scanning. You can define one scanner for each registry being used for image scanning. You can pass this flag multiple times to exclude multiple registries. Passing this flag is optional.

You can include an asterisk as a wildcard character in a registry name. Examples: acr*, *acr, a*r.

Sample Command Syntax: -E “Docker Hub”

For more information, refer to the Registry specification section.
--filehash-encoding stringFile hash encoding algorithm. Valid values are zlib (default) and snappy. This flag is required to encode the scanner. You receive the scanner ID after passing this flag. For more information, refer to Usage of Scanner Command Syntax.
--scannername stringThis flag can be passed to assign a logical name to the scanner. Passing this flag is optional. If you do not pass this flag, the scanner logical name is assigned as defined in the optional environment variable.


Deploy daemon scanner with --filehash-encoding

This flag is used to encode the scanner while deploying to the Aqua console. Valid values are zlib (default) and snappy. In the following command, snappy is passed as file-encoding. 


docker run -d -v /var/run/docker.sock:/var/run/docker.sock registry.aquasec.com/scanner:6.2 daemon -H http://aqua-server:8080 -U <SCAN_USER> -P <SCAN_PASSWORD> --filehash-encoding snappy

Output Response

You receive scanner id from Aqua console as output response. 


docker run -d -v /var/run/docker.sock:/var/run/docker.sock registry.aquasec.com/scanner:6.2 daemon -H http://aqua-server:8080 -U <SCAN_USER> -P <SCAN_PASSWORD> --filehash-encoding snappy
c4ce1a309c17b33f87a299e5e57ce6b17bdb978115dc8260df2e73448437435e

Help flag

You can get help on the scanner daemon argument, by running with the -h or --help flag as shown below:

docker run -v /var/run/docker.sock:/var/run/docker.sock registry.aquasec.com/scanner:6.2 daemon --help

Scanner list

After you add the required scanner daemons, you can find the list of all scanners deployed from the Administration > Scanners page. You can find the following information in each scanner:

  • Name: Scanner's name assigned
  • Type: Linux/Windows
  • Description: that if you have added to identify the scanner and its purpose
  • Last Heartbeat: last timestamp when was the scanner used to scan images or added to Aqua
  • Connected Registries: list of image registries that you have passed through CLI command (using the -R flag) to dedicate the scanner to scan the registries


Setting: Scan only with 'scanner' daemons (optional)

If you add scanners, your Aqua admin can configure the Aqua server to not scan images using the Aqua server itself, using the Only scan images with scanner-cli daemons (if exist) checkbox from the Settings page. If this action is performed, all images will be scanned by the scanners (scanner daemons) that you have added. This will reduce the load on the Aqua server. For more information, refer to Configure Scanning Options.