Versions Compared

Old Version 41

changes.mady.by.user Tsur Rothfeld

Saved on

compared with

New Version 42

changes.mady.by.user Tsur Rothfeld

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

Table of Contents

Overview

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

Prerequisites 

  • It is assumed that you have an authorized account to Amazon ECR and can pull images from Amazon ECR.

  • You have Amazon AWS CLI installed.

  • You have Docker installed.

  • Unified Agent will scan the images on your local host (after these have been pulled from Amazon ECR).

  • Unified Agent requires to download a JAR file and a configuration file. You can download them manually or by using the steps described below.

Downloading the Unified Agent and Configuration File

title
Info

Notice on periodically fetching the Unified Agent

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 WhiteSource Unified Agent JAR file and configuration file to your local host.

  1. Windows Using CURL

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

    2. Open a new command prompt

    3. Run the following commands:

      Windows Using CURL

      Code Block
      languagejavatitleWindows Using CURL
      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"

  2. Windows Using PowerShell

    1. Open a new command prompt

    2. Run the following commands:

      Windows Using PowerShell

      Code Block
      languagejavatitleWindows Using PowerShell
      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

      NOTE: Make sure that Background Intelligent Transfer Service (BITS) is enabled if you want to use PowerShell on Windows.

  3. Windows - Manual Download
    Download the following files manually using your web browser or any other download manager:
    https://github.com/whitesource/unified-agent-distribution/releases/latest/download/wss-unified-agent.jar
    https://github.com/whitesource/unified-agent-distribution/raw/master/standAlone/wss-unified-agent.config

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

    Linux/Unix Using CURL

    Code Block
    title
    languagejavaLinux/Unix Using CURL
    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"

...

Example of values for uncommented lines:

Code Block
languagejava
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 2 image tags in the 'exclude' section.

Alternatively, you can 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

WhiteSource 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:

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

...

The scanner saves your required images and scans all the 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'.

...

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
Code Block
languagebashtitleDocker Pull Image
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: