TABLE OF CONTENTS

Overview

This topic explains general syntax used in the Command Line Interface (CLI) to scan container images. You can pass commands directly to scanner on the Linux or Windows operating systems. For information on Scanner CLI, refer to Scanner Command Line Interface.


General syntax can have one command and multiple general flags. Following sections explain different commands and general flags that can be used in the general command syntax.


This document explains the following key topics:

  • Scanning images from Linux and Windows operating system
  • General flags used in the scanner commands
  • Different scanner commands

Sample scanner command syntax on Linux

This section shows the sample command syntax used to scan container images in the docker container engine.

docker run -v /var/run/docker.sock:/var/run/docker.sock registry.aquasec.com/scanner:6.5 scan -H http://aqua-server:8080 --token <Aqua_scanner_token> --local myimage:latest


This syntax has the following parameters:

  • Container engine: docker run
  • Aqua scanner: scanner:6.2
  • Command: scan
  • Aqua server address: http://aqua-server:8080
  • Information to connect Aqua Server: -H, -U, and -P flags
  • Scanning on: local host
  • Image: myimage:latest
You can see the following sample output response after running the scanner command syntax on Linux. It shows the scan result and policy details which failed the image.

Scan successfully completed.
Compliance Failure (4): failed the following policies: [Vulnerability_6]


You can find results of the image scan operation on the Images page within the Aqua platform. For more information, refer to Images Screen Operations.

Sample Scanner Command Syntax on Windows

This section shows the sample command syntax used to scan container images on Windows operating system.

scannercli.exe scan -H http://aqua-server:8080 --token <Aqua_scanner_token> --local myimage:latest


This syntax has the following parameters:

  • Aqua scanner: scannercli.exe
  • Command: scan
  • Aqua server address: http://aqua-server:8080
  • Information to connect Aqua Server: -H, -U, and -P flags
  • Scanning on: local host
  • Image: myimage:latest

General flags (all commands)

Following is the list of flags that can be passed with all the scanner commands. All flags have both a short form and a long form.


FlagDescription
-H or --host stringThe address of the Aqua Server with which the scanner connects to. For more information, refer the Aqua Server and HTTPS section below.
--tokenA unique token generated for each scanner while adding a scanner daemon from the Administration > Scanners page. In the command examples, it is represented as --token <Aqua_scanner_token>. To add a token in the command example, you should collect the token of a specific scanner from the Scanners page or contact your Aqua admin.

For more information, refer to Add Scanner Daemons.
-D or --direct-ccThis flag enables the scanner communicates with Aqua CyberCenter directly, instead of via the Aqua Server. Adding this flag reduces the scan time. This flag is case-sensitive.

Note: If Aqua Trivy Premium scanner is enabled in your Aqua environment, Trivy always communicates with Aqua CyberCenter directly, irrespective of passing the -D or --direct-cc flag.
-n or --no-verifyThis flag enables the scanner runs without verifying the Transport Layer Security (TLS) certificate for the Aqua Server. You can use this flag in the following instances:
  • If the certificate is not genuine
  • When the scanner is connected to Server over HTTPS. For more information, refer to the Aqua Server and HTTPS section below
-h or --helpIf this flag is passed with a specific or no command through syntax, it provides help output for a specific command or general help output, respectively. For more information, refer the Help flag section in this document.
-T or --scan-timeout integerThis flag is passed to specify the maximum time that should be taken by scanner to communicate with the Aqua server. As there are multiple other requests made to communicate with the server, if the specified time mentioned through this flag is passed, the connection request to server will be failed and an error is thrown by system when connection timeout.
-v or --verbose-errors integerOutput exit code with string description. You can pass this flag to receive error details with error codes and the respective error description.
-w or --work-dir stringThis flag is passed to specify working directory for image scanning and store the scan results. This flag is used when a user does not have permissions to store scan results in the opt/aquascans. You can specify a working directory (example: /tmp/yyy/xxx) to store the scan results. This flag is case sensitive.


Aqua Server and HTTPS

If the Aqua Server uses HTTPS, you should take the following considerations into account:

  1. The URL specified with the -H or --host flag must begin with https://.
  2. If TLS certificate verification is not required, use the -n or --no-verify flag.
  3. If TLS certificate verification is required, the scanner should be rebuilt to include the certificate authority and server certificates.

Configure Aqua Scanner over HTTPS

By default, the Aqua Scanner daemon is configured to work with the Aqua Server over HTTP. To use HTTPS, you should build an SSL Scanner with the required certificates for communication.


Run this docker build command to create a scanner that can utilize SSL communication with the Aqua Server.


Note: Presently, the .pem certificate format is required.


To configure Aqua scanner over HTTPS:

  1. Copy the Docker command shown below to login to the Aqua registry. However, before running it, you should replace <AQUA_USERNAME> and <AQUA_PASSWORD> with the credentials that you have received from Aqua Security.

docker login registry.aquasec.com -u <AQUA_USERNAME> -p <AQUA_PASSWORD>


       2. Pull the scanner image and create a directory for the certs by running the following commands.

docker pull registry.aquasec.com/scanner:6.5
mkdir /dockerbuild
cd /dockerbuild
cp ./cert.pem /dockerbuild/cert.pem
cp ./key.pem /dockerbuild/key.pem

       3. Copy the text below to create the Dockerfile for building the SSL Scanner.

FROM registry.aquasec.com/scanner:6.5
RUN apk update && apk add ca-certificates && rm -rf /var/cache/apk/*
COPY ./cert.pem /usr/local/share/ca-certificates/cert.pem
COPY ./key.pem /usr/local/share/ca-certificates/key.pem
RUN update-ca-certificates


       4. Run this docker build command to create a scanner that can utilize SSL communication with the Aqua Server.

docker build -t registry.aquasec.com/ssl-scanner:latest

Scanner commands

The following table lists all the commands supported by the scanner that can be passed through command syntax. For more information on each scanner command operation, sample syntax, and its output, click document link in the "Command" column to navigate to the respective documentation.


CommandPurpose
scanScans a single image
register-allRegister and scan all local images on the host
importImports scan results
versionShows the version of the scanner
daemonShows image scanner daemon information


Help flag

For general help on the scanner command, you should pass the following command syntax with the --help flag on Linux OS:

docker run registry.aquasec.com/scanner:6.5 --help


For help on any specific command such as scan or version, you should pass one of the following command syntax with the --help flag: 

docker run registry.aquasec.com/scanner:6.5 scan --help

docker run registry.aquasec.com/scanner:6.5 register-all --help

docker run registry.aquasec.com/scanner:6.5 import --help

docker run registry.aquasec.com/scanner:6.5 version --help

docker run registry.aquasec.com/scanner:6.5 license --help