TABLE OF CONTENTS

Overview

This topic explains the usage examples of Scan command for image scanning, passed with different parameters. Command syntax for the multiple use cases is shown by passing different processing, output options, image architecture types, and so on.


You can run command either on Linux environment through docker or Windows environment, per your requirement. Scanner information in the scan command syntax is different in the Linux docker and Windows OS. Rest of the command in the syntax does not change.


Following is the Scanner command while running on the Linux OS through docker:

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


Following is the Scanner command using scanner executable binary while running on the Windows OS:

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


As a prerequisite, scanner executable binary should be installed to the host before submitting the scan command. For more information, refer to Scanner Command Line Interface.


In this document, scanner commands are shown for Linux environment. To use the scanner commands for Windows, you should replace the docker run command with scannercli.exe (for example) and usage of rest of the flags is same for both the environments.


Image locations

You can scan images if they are in one of the following locations:

  • Local
  • Remote registry (Example: Docker Hub)
  • OCI Archive tar image (Local file path) for images built with either Buildah or Podman
  • Docker Archive tar image (Local file path)

--oci-archive

For tar images built with either Buildah or Podman, you should push them to archive storage in the system. In this sample command, you should specify the --oci-archive flag and location of the tar image stored in the system. The specific image passed through the command is scanned successfully.


podman push Image ID oci-archive:/tmp/alpine-latest.tar       
Getting image source signatures
Copying blob cb381a32b229 done  
Copying config d2248bd8b5 done  
Writing manifest to image destination
Storing signatures

docker run -v /tmp:/tmp registry.aquasec.com/scanner:6.5 scan -H http://aqua-server:8080 --token <Aqua_scanner_token> alpine:latest --oci-archive /tmp/alpine-latest.tar

Output response

In the following output response, you can see that tar image passed through the sample command is scanned successfully.


  "image_assurance_results": {},
  "vulnerability_summary": {
    "total": 1,
    "critical": 0,
    "high": 0,
    "medium": 1,
    "low": 0,
    "negligible": 0,
    "sensitive": 0,
    "malware": 0,
    "score_average": 5.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:::",
    "enable_fast_scanning": true,
    "memoryThrottling": true,
    "suggest_os_upgrade": true
  },
  "initiating_user": "administrator",
  "data_date": 1615771485,
  "pull_name": "alpine:latest",
  "changed_result": false,
  "scan_id": 4,
  "required_image_platform": "amd64:::",
  "scanned_image_platform": "amd64::linux:",
  "security_feeds_used": {
    "executables": "2707460d07216e"
  },
  "image_id": 3,
  "internal_digest_id": {
    "id": 3
  },
  "local": true
}
2021-03-15 13:40:55.206 INFO    Deregistering from console
2021-03-15 13:40:55.207 INFO    Scan successfully completed.

--docker-archive

For tar images built with Docker, you should push them to archive storage in the system. In this sample command, you should specify the --docker-archive flag and location of the tar image stored in the system. The specific image passed through the command is scanned successfully.


docker run -v /home/ubuntu:/home/ubuntu registry.aquasec.com/scanner:6.5 scan -H http://aqua-server:8080 --token <Aqua_scanner_token> alpine:local --docker-archive /home/ubuntu/alpine-local.tar

Output response

In the following output response, you can see that tar image passed through the sample command is scanned successfully.


{
  "image": "alpine:local",
  "scan_started": {
    "seconds": 1616770101,
    "nanos": 174234820
  },
  "scan_duration": 2,
  "image_size": 5608905,
  "digest": "sha256:302aba9ce190db9e247d710f4794cc303b169035de2048e76b82c9edbddbef4e",
  "os": "alpine",
  "version": "3.13.3",
  "image_assurance_results": {},
  "vulnerability_summary": {
    "total": 0,
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0,
    "negligible": 0,
    "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": "alpine:local",
  "changed_result": false,
  "scan_id": 35,
  "required_image_platform": "amd64:::",
  "scanned_image_platform": "amd64::linux:",
  "security_feeds_used": {
    "executables": "05a8291eed26d1"
  },
  "image_id": 11,
  "internal_digest_id": {
    "id": 9
  },
  "local": true,
  "CanSkipFileHashSave": true
}
2021-03-26 14:48:23.267 INFO    Scan successfully completed.

Processing options

--register and --register-compliant

Following is the sample command syntax to scan an image from remote registry, Docker Hub. You can pass either --register or --register-compliant flag to register image in the Aqua server without or with compliance, respectively.


docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock -v /tmp:/tmp registry.aquasec.com/scanner:6.5 scan -H http://aqua-server:8080 --token <Aqua_scanner_token> --registry "Docker Hub" nginx:latest --textfile /tmp/foo.text –register or --register-compliant

Output response

You receive the output result as shown below, after showing detailed scan logs. If you pass the --register flag, image is registered in the Aqua server. If you pass the --register-compliant flag, image is not registered when it is not compliant with any Aqua image assurance policy.


Output response (--register flag)

Following is the output response that you receive if you pass the --register flag through sample command.


"initiating_user": "administrator",
  "data_date": 1614821618,
  "pull_name": "registry-1.docker.io/library/nginx:latest",
  "changed_result": false,
  "original_registry": "Docker Hub",
  "required_image_platform": "amd64:::",
  "scanned_image_platform": "amd64::linux:",
  "security_feeds_used": {
    "executables": "df5a106efd0416"
  },
  "isAdhocRegister": true,
  "FileHashEncoding": "zlib"
}
2021-03-04 14:00:38.757 INFO    Deregistering from console
2021-03-04 14:00:38.760 INFO    Scan successfully completed.

Output response (--register-compliant flag)

Following is the output response that you receive if you pass the --register-compliant flag through sample command.


2021-03-04 13:34:06.465 INFO    Processing results...   {"registry": "Docker Hub", "image": "nginx:latest", "requested platform": "amd64:::", "job ID": "114c086e-cf33-4c57-925a-73a3537e0ff4", "server version": "6.5.c66bc8d93e", "scanning platform": "amd64::linux:"}
2021-03-04 13:34:06.468 INFO    Applying image assurance policies...    {"registry": "Docker Hub", "image": "nginx:latest", "requested platform": "amd64:::", "job ID": "114c086e-cf33-4c57-925a-73a3537e0ff4", "server version": "6.2.c66bc8d93e", "scanning platform": "amd64::linux:"}
2021-03-04 13:34:06.469 INFO    Image does not comply with assurance policy and will not be registered since '--register-compliant' option was specified.
Test Status: Image is non-compliant (failed on CI/CD pipeline)

--checkonly, --scan-malware, and --collect-sensitive

Following is the sample command syntax to scan an image from the local registry using a specific image assurance policy. Following flags are passed to scan the image:

  • --policies: Passed to scan the image with specific image assurance policy
  • --checkonly: Passed to scan the image and make sure the scan does not fail as per any policy. This prevents failing the pipeline due to the scan failure of any image.
  • --scan-malware: Passed to collect any malware files in the image while scanning
  • --collect-sensitive: Passed to find any sensitive data in the image while scanning
docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock -v /tmp:/tmp registry.aquasec.com/scanner:6.5 scan -H http://aqua-server:8080 --token <Aqua_scanner_token> --local nginx:latest --policies Vulnerability_6 --textfile /tmp/foo.text --collect-sensitive --scan-malware --check-only

Output response

In the following output response, you can find that:

  • There are no malware files and sensitive data found
  • Image scanned successfully and passed scan even though there is an image assurance policy supposed to fail the scan. You can observe the same with the return code, 0.
"vulnerability_summary": {
    "total": 4,
    "critical": 0,
    "high": 3,
    "medium": 0,
    "low": 1,
    "negligible": 16,
    "sensitive": 0,
    "malware": 0,
    "score_average": 6.55,
    "max_score": 10,
    "max_fixable_score": 7.5
  },
  "scan_options": {
    "scan_executables": true,
    "scan_sensitive_data": true,
    "scan_malware": true,
    "scan_files": true,
    "image_assurance_policies": [
      "Vulnerability_6"
    ],
    "scan_timeout": 3600000000000,
    "manual_pull_fallback": true,
    "save_adhoc_scans": true,
    "use_cvss3": true,
    "dockerless": true,
    "system_image_platform": "amd64:::",
    "telemetry_enabled": true,
    "enable_fast_scanning": true,
    "memoryThrottling": true,
    "suggest_os_upgrade": true
  },
  "initiating_user": "administrator",
  "data_date": 1615507538,
  "pull_name": "nginx:latest",
  "changed_result": false,
  "required_image_platform": "amd64:::",
  "scanned_image_platform": "amd64::linux:",
  "security_feeds_used": {
    "executables": "97a58e6823fbbb"
  },
  "local": true,
  "CanSkipFileHashSave": true
}
2021-03-12 12:52:53.273 INFO    Deregistering from console
2021-03-12 12:52:53.277 INFO    Scan successfully completed.

You can now pass echo $? to get the return code 0, which notifies that “The image passed all applicable Image Assurance Policies successfully” as shown in the following response.


ubuntu@ip-10-0-5-233:~$ echo $?
0

For more information on the Return codes, refer to Scan Argument.


--collect executables

Following is the sample command syntax to scan an image locally. The --collect-executables flag is passed to list down all the non-package executables in the image with scan results. This flag gives results of non-package executables only when you scan images locally by passing the --local flag. 


docker run registry.aquasec.com/scanner:6.5 scan -H http://aqua-server:8080 --token <Aqua_scanner_token> --local nginx:latest --collect-executables

Output response

In the following output response, non-package executables are listed down with the image scan results. 


  },
  "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,
    "enable_fast_scanning": true,
    "memoryThrottling": true,
    "suggest_os_upgrade": true
  },
  "partial_results": true,
  "initiating_user": "administrator",
  "warnings": [
    {
      "subject": "Packages",
      "message": "package manager error: failed finding dpkg: exec: \"dpkg\": executable file not found in $PATH"
    }
  ],
  "data_date": 1615852168,
  "pull_name": "registry-1.docker.io/library/nginx:latest",
  "changed_result": false,
  "original_registry": "Docker Hub",
  "scan_id": 5,
  "required_image_platform": "amd64:::",
  "scanned_image_platform": "amd64::linux:",
  "security_feeds_used": {
    "executables": "97a58e6823fbbb"
  },
  "image_id": 1,
  "internal_digest_id": {
    "id": 1
  },
  "CanSkipFileHashSave": true
}
2021-03-16 05:04:43.796 INFO    Scan successfully completed.

Image architecture

--architecture

Following is the sample command syntax to scan an image from remote registry, Docker Hub with different architecture than the default architecture mentioned in the environment variables. Following flags are passed in the sample command syntax:

  • --registry: Docker Hub
  • -D or --direct-cc: To contact Aqua CyberCenter directly
  • --architecture: arm
docker run registry.aquasec.com/scanner:6.5 scan -H http://aqua-server:8080 -D --token <Aqua_scanner_token> --architecture arm --registry "Docker Hub" alpine:latest

Output response

You receive the output result as shown below, after showing detailed scan logs. The scan on the image from remote registry is completed successfully. Architecture type arm is considered for image scanning and Aqua CyberCenter is contacted directly. This result is shown in the highlighted output response below.


2021-03-16 05:46:37.939 INFO    Contacting CyberCenter...       {"registry": "Docker Hub", "image": "nginx:latest", "requested platform": "arm:::", "job ID": "12d9b425-0b59-40af-88cd-1b8fba9edc77", "server version": "6.2.02686e3619", "scanning platform": "arm:v5:linux:", "url": "https://cybercenter5-dev.aquasec.com"}
{
  "image": "nginx:latest",
  "registry": "Docker Hub",
  "scan_started": {
    "seconds": 1615873594,
    "nanos": 440131573
  },
  "scan_duration": 15,
  "image_size": 117053240,
  "os": "debian",
  "version": "10",
  "image_assurance_results": {},
  "vulnerability_summary": {
    "total": 0,
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0,
    "negligible": 19,
    "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,
    "enable_fast_scanning": true,
    "memoryThrottling": true,
    "suggest_os_upgrade": true
  },
  "initiating_user": "administrator",
  "data_date": 1615852168,
  "pull_name": "registry-1.docker.io/library/nginx:latest",
  "changed_result": false,
  "required_image_platform": "arm:::",
  "scanned_image_platform": "arm:v5:linux:",
  "security_feeds_used": {
    "executables": "97a58e6823fbbb"
  },
  "CanSkipFileHashSave": true
}
2021-03-16 05:46:49.996 INFO    Deregistering from console
2021-03-16 05:46:50.000 INFO    Scan successfully completed.

Scanning a Windows-based image with a Linux Scanner

Following is the sample command syntax to scan a windows-based image from remote registry, Docker Hub.


docker run registry.aquasec.com/scanner:6.5 scan -H http://aqua-server:8080 --token <Aqua_scanner_token> --os windows --registry "Docker Hub" microsoft/nanoserver:1803

Output response

You receive the output result as shown below, after showing detailed scan logs.


2021-03-04 13:43:17.149 INFO    Fast Scanning: sending ScanByLayers request to CyberCenter      {"registry": "Docker Hub", "image": "microsoft/nanoserver:1803", "requested platform": "::windows:", "job ID": "34dc7d8c-714d-4758-8a53-75ac9ed34ab4", "server version": "6.2.c66bc8d93e", "scanning platform": "amd64::windows:10.0.17134.1305"}
2021-03-04 13:43:17.925 INFO    Processing results...   {"registry": "Docker Hub", "image": "microsoft/nanoserver:1803", "requested platform": "::windows:", "job ID": "34dc7d8c-714d-4758-8a53-75ac9ed34ab4", "server version": "6.5.c66bc8d93e", "scanning platform": "amd64::windows:10.0.17134.1305"}
2021-03-04 13:43:17.928 INFO    Applying image assurance policies...    {"registry": "Docker Hub", "image": "microsoft/nanoserver:1803", "requested platform": "::windows:", "job ID": "34dc7d8c-714d-4758-8a53-75ac9ed34ab4", "server version": "6.2.c66bc8d93e", "scanning platform": "amd64::windows:10.0.17134.1305"}
2021-03-04 13:43:17.928 WARN    Cannot register image, The console supports registering images in a single platform. In order to register images with specific architecture please remove the Platform flags(Architecture, Variant ,OS, OS Version) and set them globally as an environment variables in the console
{
  "image": "microsoft/nanoserver:1803",
  "registry": "Docker Hub",
  "scan_started": {
    "seconds": 1614865394,
    "nanos": 611266484
  },
  "scan_duration": 3,
  "image_size": 378006570,
  "os": "windows",
  "version": "10.0.17134",
  "resources": [
    {
      "resource": {
        "name": "kernel",
        "version": "17134.48",
        "cpe": "pkg:/windows:10.0.17134:kernel:17134.48",
        "layer": "Apply image 10.0.17134.1",
        "layer_digest": "sha256:e46172273a4e4384e1eec7fb01091c828a256ea0f87b30f61381fba9bc511371"
      },
      "scanned": true,
      "vulnerabilities": [
        {
          "name": "KB4540689",
          "nvd_score": 6.8,
          "nvd_score_version": "CVSS v2",
          "nvd_vectors": "AV:N/AC:M/Au:N/C:P/I:P/A:P",
          "nvd_severity": "medium",
          "vendor_score_version": "CVSS v2",
          "vendor_url": "https://support.microsoft.com/en-us/help/KB4540689",
          "publish_date": "2020-03-10",
          "fix_version": "17134.1365",
          "solution": "Upgrade package kernel to version 17134.1365 or above.",
          "ref_vulns": [
            {

Output options

Following are the sample commands with the respective output option flags (--jsonfile/--htmlfile/--text) that you can pass on Linux OS. This syntax will generate scanner output file in the respective formats and store files in the volume mount specified in the command.


--html and --htmlfile

docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock -v /tmp:/tmp registry.aquasec.com/scanner:6.5 scan -H http://aqua-server:8080 --token <Aqua_scanner_token> --local ubuntu:latest --html --htmlfile /tmp/foo.html [flags]

Output response

You receive the output result as shown below, after showing detailed scan logs.

                                        <tbody><tr><td colspan="2"><em>No sensitive data found during scan</em></td></tr></tbody>
                                </table>
                        </div>
                </div>
                <input type="radio" class="tab" name="tabs" id="51982-tab5">
                <label for="51982-tab5" class="label">Malware</label>
        <div class="panel">
                        <div class="wrapper">
                                <table class="sensitive-data table-data">
                                        <thead>
                                        <tr>
                                                <th scope="col">Path</th>
                                                <th scope="col">Type</th>
                                        </tr>
                                        </thead>
                                        <tbody><tr><td colspan="2"><em>No malware detected during         scan</em></td></tr></tbody>
                                </table>
                        </div>
                </div>
    </div>
</main>
</div>
</body>
</html>2021-03-03 09:35:31.850  INFO    Deregistering from console
2021-03-03 09:35:31.854 INFO    Scan successfully completed.

--jsonfile

docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock -v /tmp:/tmp registry.aquasec.com/scanner:6.5 scan -H http://aqua-server:8080 --token <Aqua_scanner_token> --local ubuntu:latest --jsonfile /tmp/foo.json [flags]

Output response

You receive the output result as shown below, after showing detailed scan logs.

  "image_assurance_results": {},
  "vulnerability_summary": {
    "total": 4,
    "critical": 0,
    "high": 3,
    "medium": 0,
    "low": 1,
    "negligible": 16,
    "sensitive": 0,
    "malware": 0,
    "score_average": 6.55
  },
  "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,
    "enable_fast_scanning": true,
    "memoryThrottling": true,
    "suggest_os_upgrade": true
  },
  "initiating_user": "administrator",
  "data_date": 1614726599,
  "pull_name": "nginx:latest",
  "changed_result": false,
  "required_image_platform": "amd64:::",
  "scanned_image_platform": "amd64::linux:",
  "security_feeds_used": {
    "executables": "df5a106efd0416"
  },
  "local": true,
  "CanSkipFileHashSave": true
}
2021-03-03 10:27:46.492 INFO    Deregistering from console
2021-03-03 10:27:46.498 INFO    Scan successfully completed.

--text and --textfile

docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock -v /tmp:/tmp registry.aquasec.com/scanner:6.5 scan -H http://aqua-server:8080 --token <Aqua_scanner_token> --local ubuntu:latest --text --textfile /tmp/foo.text [flags]

Output response

You receive the output result like the one received by passing the --jsonfile flag.


--layer-vulnerabilities

Following is the sample command syntax to scan an image from the remote registry, Docker Hub by passing the --registry flag. A specific image assurance Policy is passed through the --policies flag to consider scanning the image. The --layer-vulnerabilities flag is passed to show vulnerabilities by image layer in the output response.

docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock -v /tmp:/tmp registry.aquasec.com/scanner:6.5 scan -H http://aqua-server:8080 --token <Aqua_scanner_token> --local nginx:latest --policies Vulnerability_6 --textfile /tmp/foo.text --layer-vulnerabilities

Output response

In the following output response, vulnerabilities are shown by image layers. A couple of layers are shown for reference.


      "layer": "sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4",
      "created": 1613589625,
      "createdBy": "/bin/sh -c #(nop)  STOPSIGNAL SIGQUIT",
      "resources": [],
      "vulnerability_summary": {
        "total": 0,
        "critical": 0,
        "high": 0,
        "medium": 0,
        "low": 0,
        "negligible": 0,
        "sensitive": 0,
        "malware": 0
      }
    },
    {
      "layer": "sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4",
      "created": 1613589626,
      "createdBy": "/bin/sh -c #(nop)  CMD [\"nginx\" \"-g\" \"daemon off;\"]",
      "resources": [],
      "vulnerability_summary": {
        "total": 0,
        "critical": 0,
        "high": 0,
        "medium": 0,
        "low": 0,
        "negligible": 0,
        "sensitive": 0,
        "malware": 0
      }
    }
  ],
  "security_feeds_used": {
    "executables": "a9dbbbca38e413"
  },
  "local": true,
  "CanSkipFileHashSave": true
}
2021-03-05 05:57:46.598 INFO    Deregistering from console
2021-03-05 05:57:46.601 INFO    Scan successfully completed.