Amazon Elastic Container Registry (ECR) - Docker Integration

Overview

This page describes how to integrate Amazon ECR with the Unified Agent to be able to scan Docker Images.

Prerequisites

An authorized account to Amazon ECR and can pull images from Amazon ECR
Installations of Amazon AWS CLI and Docker
Unified Agent will scan the images on your local host (after these have been pulled from Amazon ECR)
Unified Agent requires downloading a JAR file and a configuration file. You can download them manually or by using the steps described below.
The relevant package manager must be installed. For details, see the Unified Agent Prerequisites .

Downloading the Unified Agent and Configuration File

It is advised to use the below commands only once a week to download the latest version of the Unified Agent for performance reasons, and not as part of every build. You can do this using a scheduler task, such as cron.

Use the following options to download the latest version of the Mend Unified Agent JAR file and configuration file to your local host.

Windows Using CURL

Download CURL, and add it to your PATH environment variable.

Open a new command prompt, and run the following commands:

Windows Using CURL

JAVA

curl -LJO "https://github.com/whitesource/unified-agent-distribution/releases/latest/download/wss-unified-agent.jar"
curl -LJO "https://github.com/whitesource/unified-agent-distribution/raw/master/standAlone/wss-unified-agent.config"

Windows Using PowerShell

Open a new command prompt, and run the following commands:

Windows Using PowerShell

JAVA

powershell bitsadmin /transfer mydownload /dynamic /download /priority FOREGROUND https://github.com/whitesource/unified-agent-distribution/releases/latest/download/wss-unified-agent.jar $pwd\wss-unified-agent.jar 
powershell bitsadmin /transfer mydownload /dynamic /download /priority FOREGROUND https://github.com/whitesource/unified-agent-distribution/raw/master/standAlone/wss-unified-agent.config $pwd\wss-unified-agent.config

NOTE: To use PowerShell on Windows, ensure that Background Intelligent Transfer Service (BITS) is enabled.

Windows - Manual Download
Download the following files manually using your web browser or any other download manager:
1. unified agent jar file
2. unified agent config file

Linux/Unix
Run the following commands from the Linux/Unix bash prompt :

Linux/Unix Using CURL

JAVA

curl -LJO "https://github.com/whitesource/unified-agent-distribution/releases/latest/download/wss-unified-agent.jar"
curl -LJO "https://github.com/whitesource/unified-agent-distribution/raw/master/standAlone/wss-unified-agent.config"

Update Configuration File

Update the configuration file (wss-unified-agent.config) that you previously downloaded according to your specific requirements.
Enable the relevant lines by removing the '#' symbol at the beginning of the lines.

Example of values for uncommented lines:

JAVA

docker.includes=.*alpine.*
docker.excludes=.*2017.10.01.* .*2017.06.01.*
docker.scanImages=true
docker.pull.enable=false
docker.pull.images=.*.*
docker.pull.tags=.*.*
docker.pull.digest=.*.*
docker.delete.force=false
docker.aws.enable=false
docker.aws.registryIds=XXXXXXXXXXXX
docker.pull.maxImages=10
docker.login.sudo=true

This configuration sets the Unified Agent to scan all the docker repositories named *alpine.* except for the two image tags in the exclude section.

Alternatively, leave the docker.excludes parameter commented if you want to scan all your image containers.

Configuration Parameters

Attribute	Type	Description	Required
docker.includes	String	Space separated list specifying which files to include in the scan.	No
docker.excludes	String	Space separated list specifying which files to exclude in the scan.	No
docker.scanImages	Boolean	Indicates whether or not to scan images.	No. Default is true
docker.pull.enable	Boolean	When true then pulls from all relevant registries. When false does not pull from registries.	No. Default is false
docker.pull.images	String	Indicates which images to pull. Value can be a GLOB pattern or a list of values separated by spaces. Example:' .* github .*' includes among others, 'github-scanner' and 'test/github'.	No. Default is '. * . * '
docker.pull.tags	String	Indicates which tags to pull. Value can include GLOB pattern or a list of values separated by space (e.g., 'latest' or GLOB pattern such as '. * 18.6 . *').	No. Default is '. * . * '
docker.pull.digest	String	The content-addressable identifier called a digest. As long as the input used to generate the image is unchanged, the digest value is predictable. Can be '.' or or a list of explicit values separated by space. Cannot include GLOB patterns such as '.98765'.	No. Default is '. * . * '
docker.delete.force	Boolean	Enables to use Docker to delete images with the 'force' flag. This is required if the user pulled images that are related to other images, and in such cases a regular delete may not work properly.	No. Default is false
docker.aws.enable	Boolean	Enables pulling Docker Images from Amazon ECR.	No. Default is false
docker.aws.registryIds	String	The Registry IDs list on Amazon Web Services (the AWS 12-digit account IDs that correspond to the Amazon ECR registries). The list must include the following: Full registry IDs and no GLOB patterns. At least one registry ID. Values are space-delimited. NOTE: Required if docker.aws.enable=true.	Yes
docker.pull.maxImages	Integer	Mend stops pulling more images when the indicated value of pulled images is reached,	No. Defualt is 10
docker.login.sudo	Boolean	Docker login requires user to use 'sudo' or 'root' user. When set to true, login is as a 'sudo' user.	No. Default is true.

Running the Unified Agent

Run the Unified Agent with the modified configuration file via this command:

BASH

java -jar wss-unified-agent.jar -apiKey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx -c wss-unified-agent.config

Scanning Information

The scanner saves your required images and scans the entire file system and installed packages.
It scans all the image layers, and handles archive files in the layers based on the value in the property archiveExtractionDepth.

The Docker image is saved to the temporary directory defined in your environment and is deleted immediately after the scan.

The scanning results are presented in a new Mend project identified by the name of the image in the following format: <image id> <repository> <tag>.
The project is created in the Mend product specified in the configuration file or command line.

(Optional) Performing Manual Scanning of Images (instead of using ECR automated image pulling)

Pull Docker Images From Amazon ECR Before Scanning

You need to pull the Docker images that you want to scan. Pull the images from Amazon ECR using Docker's command:

Docker Pull Image

BASH

docker pull {aws_account_id}.dkr.ecr.{region}.amazonaws.com/{image}:{tag}

Examples:

docker pull {aws_account_id}.dkr.ecr.us-west-2.amazonaws.com/amazonlinux:latest

docker pull {aws_account_id}.dkr.ecr.us-east-1.amazonaws.com/ubuntu:trusty

For more information, refer to the following Amazon website links: