TABLE OF CONTENTS

Overview

This topic explains how to download, setup, and use the scanner executable binary to scan images on your Linux and Windows hosts. You can run the binary scanner either on a VM or a container on your Linux host.


Following are the use cases to use the executable binary: 

  • Docker engine is not available
  • When you do not have required permissions to configure image scanning in the CI/CD plugin per your requirement, you can apply these customizations in the executable binary to scan the images


Prerequisite

The scanner binary depends on package managers to query the packages in the images. Therefore, the relevant package managers (e.g., apt, dpkg, and rpm) must be installed on the host. Otherwise, scanning will be incomplete. The partial results will include a warning.


Scanning in a non-Docker environment (such as podman)

When you scan images in a non-Docker environment such as podman or Windows, you should pass the following flags as explained below:

  • While scanning images using the executable binary (scanner CLI) and when you use a different environment, other than docker (when docker is not installed on your host) such as podman or Windows, you should not pass the --local flag to scan local images. You can only scan images from a specific registry by passing the --registry "registry name" flag.

Download scanner executable binary on Linux

You can download the executable binary file using the following link:


https://download.aquasec.com/scanner/6.2.0/scannercli


You should enter the username and password that you have received from Aqua Security.


Note: The scanner executable binary available in the previous link is Intel Linux binary, works with Linux and Windows OS. There is no executable binary available for MacOS X hence you cannot scan images using executable binary on MacOS X.


Run Scanner on a VM

Perform the following steps to download and run scanner binary on VM:

  1. Download the binary using the following sample command:

wget --user <YOUR_AQUA_EMAIL_ADDRESS> --password <YOUR_AQUA_PASSWORD> https://download.aquasec.com/scanner/6.5.0/scannercli


You can see the following output response:

--2021-03-27 11:14:08--  https://download.aquasec.com/scanner/6.5.0/scannercli
Resolving download.aquasec.com (download.aquasec.com)... 13.80.76.187
Connecting to download.aquasec.com (download.aquasec.com)|13.80.76.187|:443... connected.
HTTP request sent, awaiting response... 401 Unauthorized
Authentication selected: Basic realm="Aqua Download"
Reusing existing connection to download.aquasec.com:443.
HTTP request sent, awaiting response... 200 OK
Length: 86290864 (82M) [binary/octet-stream]
Saving to: ‘scannercli’
scannercli               100%[==================================>]  82.29M  9.60MB/s    in 11s
2021-03-27 11:14:20 (7.63 MB/s) - ‘scannercli’ saved [86290864/86290864]

        2. Give the binary execute permissions:

chmod +x scannercli


  1. Scan an image using executable binary scanner:

./scannercli scan --token {Aqua_scanner_token} -H {host} {image_name} --registry {registry}


Following is the output response for scanning an image using the scannercli executable binary.

  "image": "registry-1.docker.io/library/alpine:latest",
  "registry": "Docker Hub",
  "scan_started": {
    "seconds": 1616766075,
    "nanos": 811751481
  },
  "scan_duration": 13,
  "image_size": 133048305,
  "digest": "sha256:6084105296a952523c36eea261af38885f41e9d1d0001b4916fa426e45377ffe",
  "os": "debian",
  "version": "10",
  "image_assurance_results": {},
  "vulnerability_summary": {
    "total": 0,
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0,
    "negligible": 20,
    "sensitive": 0,
    "malware": 0
  },
  "scan_options": {
    "scan_executables": true,
    "scan_sensitive_data": true,
    "scan_malware": true,
    "scan_files": true,
    "scan_timeout": 3600000000000,
    "manual_pull_fallback": true,
    "save_adhoc_scans": true,
    "use_cvss3": true,
    "dockerless": true,
    "system_image_platform": "amd64:::",
    "telemetry_enabled": true,
    "memoryThrottling": true,
    "suggest_os_upgrade": true
  },
  "initiating_user": "administrator",
  "data_date": 1616716642,
  "pull_name": "registry-1.docker.io/library/alpine:latest",
  "changed_result": false,
  "original_registry": "Docker Hub",
  "required_image_platform": "amd64:::",
  "scanned_image_platform": "amd64::linux:",
  "security_feeds_used": {
    "executables": "05a8291eed26d1"
  },
  "CanSkipFileHashSave": true
}
2021-03-26 13:41:28.894 INFO    Deregistering from console
2021-03-26 13:41:28.897 INFO    Scan successfully completed.

Run scanner executable binary on a container

Perform the following steps to download and run scanner binary on a container: 

  1. Mount a volume with the container. 
  2. Create the /opt/aquascans directory on the host, if not already. 


Notes:

1. Make sure you have disk space in this directory to hold the maximum size of the scanned image.
2. This directory is mounted in the container to allow the Aqua scanner to temporarily pull images.

sudo mkdir /opt/aquascans


  1. Download the binary scanner to the same directory:

sudo wget https://download.aquasec.com/scanner/6.5.0/scannercli -P /opt/aquascans/
  1. Give the binary execute permissions:
chmod +x /opt/aquascans/scannercli
  1. Run the container with the mounted volume. In this example, image "alpine:3.9.4" is used.
docker run -it --volume=/opt/aquascans:/opt/aquascans alpine:3.9.4 sh
  1. Scan an image using the scanner binary within the running container.

./opt/aquascans/scannercli scan --token {Aqua_scanner_token} -H {host} {image_name} --registry {registry}
Note: If you are rebuilding a container image and using COPY or ADD to insert the scanner binary, you must also create the /opt/aquascans/ directory for pulling images.

Following is the output response for scanning an image using scanner binary on a container:

{
  "image": "registry-1.docker.io/library/alpine:latest",
  "registry": "Docker Hub",
  "scan_started": {
    "seconds": 1616843511,
    "nanos": 581795115
  },
  "scan_duration": 6,
  "image_size": 5608905,
  "digest": "sha256:302aba9ce190db9e247d710f4794cc303b169035de2048e76b82c9edbddbef4e",
  "os": "alpine",
  "version": "3.13.3",
  "resources": [
    {
      "resource": {
        "format": "apk",
        "name": "busybox",
        "version": "1.32.1-r3",
        "arch": "x86_64",
        "cpe": "pkg:/alpine:3.13.3:busybox:1.32.1-r3",
        "license": "GPL-2.0-only",
        "layer": "/bin/sh -c #(nop) ADD file:6b081cabb4b256ee07587d249c4989b5b679375529542b81550a65b                                   6f19f274e in / ",
        "layer_digest": "sha256:9aae54b2144e5b2b00c610f8805128f4f86822e1e52d3714c463744a431f0f4a",
        "src_name": "busybox",
        "src_version": "1.32.1-r3"
      },
      "scanned": true,
      "vulnerabilities": [
        {
          "name": "CVE-2021-28831",
          "description": "decompress_gunzip.c in BusyBox through 1.32.1 mishandles the error bit on                                    the huft_build result pointer, with a resultant invalid free or segmentation fault, via malformed gz                                   ip data.",
          "nvd_score": 5,
          "nvd_score_version": "CVSS v2",
          "nvd_vectors": "AV:N/AC:L/Au:N/C:N/I:N/A:P",
          "nvd_severity": "medium",
          "nvd_url": "https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2021-28831",
          "publish_date": "2021-03-19",
          "modification_date": "2021-03-25",
          "nvd_score_v3": 7.5,
          "nvd_vectors_v3": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
          "nvd_severity_v3": "high",
          "aqua_score": 7.5,
          "aqua_severity": "high",
          "aqua_vectors": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
          "aqua_scoring_system": "CVSS V3",
          "aqua_severity_classification": "NVD CVSS V3 Score: 7.5",
          "aqua_score_classification": "NVD CVSS V3 Score: 7.5"
        }
      ]
    }
  ],
  "image_assurance_results": {},
  "vulnerability_summary": {
    "total": 1,
    "critical": 0,
    "high": 1,
    "medium": 0,
    "low": 0,
    "negligible": 0,
    "sensitive": 0,
    "malware": 0,
    "score_average": 7.5
  },
  "scan_options": {
    "scan_executables": true,
    "scan_sensitive_data": true,
    "scan_malware": true,
    "scan_files": true,
    "scan_timeout": 3600000000000,
    "manual_pull_fallback": true,
    "save_adhoc_scans": true,
    "use_cvss3": true,
    "dockerless": true,
    "system_image_platform": "amd64:::",
    "telemetry_enabled": true,
    "memoryThrottling": true,
    "suggest_os_upgrade": true
  },
  "initiating_user": "administrator",
  "data_date": 1616797786,
  "pull_name": "registry-1.docker.io/library/alpine:latest",
  "changed_result": false,
  "original_registry": "Docker Hub",
  "required_image_platform": "amd64:::",
  "scanned_image_platform": "amd64::linux:",
  "security_feeds_used": {
    "executables": "05a8291eed26d1"
  },
  "CanSkipFileHashSave": true
}
2021-03-27 11:11:57.731 INFO    Deregistering from console
2021-03-27 11:11:57.736 INFO    Scan successfully completed.


Run scanner executable binary on Windows host

Perform the following steps to download and run scanner binary on your Windows host:

  1. Download and setup scanner executable binary for Windows. For more information, refer to Scanner Command Line Interface.
  2. Run the scan command using scanner executable binary as shown in the following command syntax:

./scannercli scan --dockerless -H http://aqua-server:8080 --token {Aqua_scanner_token} --registry "Docker Hub" imageName:tag <flags>


You receive the following output response showing the result of scan:

  "image_assurance_results": {},
  "vulnerability_summary": {
    "total": 28,
    "critical": 15,
    "high": 13,
    "medium": 0,
    "low": 0,
    "negligible": 0,
    "sensitive": 3,
    "malware": 0,
    "score_average": 9.310716
  },
  "scan_options": {
    "scan_executables": true,
    "scan_sensitive_data": true,
    "scan_malware": true,
    "scan_files": true,
    "scan_timeout": 3600000000000,
    "manual_pull_fallback": true,
    "save_adhoc_scans": true,
    "use_cvss3": true,
    "dockerless": true,
    "system_image_platform": "amd64:::",
    "telemetry_enabled": true,
    "memoryThrottling": true,
    "suggest_os_upgrade": true
  },
  "initiating_user": "administrator",
  "data_date": 1616716642,
  "pull_name": "registry-1.docker.io/aquasec/nano-malware-example:1.1",
  "changed_result": false,
  "original_registry": "Docker Hub",
  "required_image_platform": "amd64:::",
  "scanned_image_platform": "amd64::windows:10.0.14393.2551",
  "security_feeds_used": {
    "executables": "05a8291eed26d1"
  }
}
2021-03-26 20:06:14.350 INFO    Deregistering from console
2021-03-26 20:06:14.624 INFO    Scan successfully completed.