Docker Agent


General Information

The docker-agent is a simple java command line tool which extracts descriptive information from your Docker containers and integrates them with WhiteSource.

Once run, all usage of open source software in the organization will be synced with WhiteSource.

  • A new project will be created for each container
  • Existing projects will be updated
  • Policies will be enforced on every action

The plugin is licensed under the Apache 2.0 license.

Source code and issues are hosted on github.

How it Works

On execution, the docker-agent scans all active containers for open source libraries and sends them to WhiteSource.

See Installation and Executing sections below.

Normal Flow

WhiteSource uses the collected information to create new projects or update existing ones.

Policy Check Flow

The agent checks each new library against the organizational policies. If any library is automatically rejected by a policy then the build fails. Otherwise, your account is updated.

An informative report of the results will be generated regardless of the outcome in html and json formats (located in the 'whitesource' folder created in the directory where the agent was run from).

Installation

Prerequisites

  • Java version 7 or higher.

Download

Download the latest version.

VersionFileFeaturesRelease DateMD5
18.4.2whitesource-docker-agent-18.4.2.jar
  • Added support for user-level access control in integrations.
  • Minor bugs fixes
2018-05-1390926868993997EBEEFAF6E6ADC85BFB
18.4.1whitesource-docker-agent-18.4.1.jar
  • Minor bugs fixes
2018-04-294F4E51F75E971556326FD272E9E9FE70
18.3.2whitesource-docker-agent-18.3.2.jar
  • Minor bugs fixes
2018-04-1595B2A9A7BDF9074CCD08CF2C79403927
18.3.1whitesource-docker-agent-18.3.1.jar
  • Minor bugs fixes
2018-04-0195B2A9A7BDF9074CCD08CF2C79403927
18.2.2whitesource-docker-agent-18.2.2.jarAdd parameter "archiveExtractionDepth".2018-03-182FF034A4B09356F07481667AB4E0A7A9
18.1.2whitesource-docker-agent-18.1.2.jar
  1. Bug fix - StringIndexOutOfBoundsException error
  2. Bug fix - exception when excludes parameter does not exist
2018-02-0470D2CD5EF4C48C3B41E208C2AFA5816F
17.12.4whitesource-docker-agent-17.12.4.jar
  1. Added support for super hash calculation.
2018-01-07828D9DFD64BED52AA421FD438E328746
1.0.8whitesource-docker-agent-1.0.8.jar
  1. Added includes/excludes file extension parameter to config file.
2017-11-12A784414D17EAD8D5F2FB9228C4E26A1D
1.0.7whitesource-docker-agent-1.0.7.jar
  1. Collects Alpine and Arch Linux packages from active containers
  2. Upgraded build version to Java 8
2017-10-221234B42FCC402B5D59547FA91AAC28F
1.0.6whitesource-docker-agent-1.0.6.jarAdded support for Alpine packages scanning.2017-09-2689CC50CF8CB831E48044DD9638D870ED
1.0.5whitesource-docker-agent-1.0.5.jar

Added exit code :

  1. Success = 0
  2. Error = -1
  3. Policy Violation = -2
  4. Client Failure = -3
  5. Connection Failure = -4

Added parameter -i or --image, which allows to scan a specific image from Docker Hub

2017-08-06D3BB820693F9BC3AE582A0DF1C09958C
1.0.4whitesource-docker-agent-1.0.4.jar
  1. Added connection timeout parameter
  2. Added read timeout parameter
2017-04-0699E06CA3633AD5705E55DCB8E29715F7
1.0.3whitesource-docker-agent-1.0.3.jar
  1. Bug fix - archive extraction error
2017-03-08417738A8217A1659C6082D8226DD9527
1.0.2whitesource-docker-agent-1.0.2.jar
  1. Bug fixes - .tgz files archive extraction
  2. Bug fixes - animation progress bar
2016-03-248ECE69018ED6AD5F7312A809298D9F60
1.0.1whitesource-docker-agent-1.0.1.jar
  1. Bug fixes
  2. Added .tgz files
  3. Added debug logs
2016-01-31756A7F7247EFA199EF4F8942EDBF7175
1.0.0whitesource-docker-agent-1.0.0.jar
  1. Collects Debian and RPM package from active containers
  2. Scans open source libraries from active containers exported tar archive
2016-01-24ACE6B36C9834C12C654412FEBB0204E5

Installation

  1. Download the jar file.
  2. Create a text file with the name "whitesource-docker-agent.config" and place it in the same directory as the jar file.
  3. Copy the example below (or download) and fill in the apiKey parameter value taken from the API Key that is found here.
  4. Run the jar from the command line. See Executing.

Configuration file example (or download):

Configuration

General Parameters

AttributeTypeDescriptionRequiredAdditional Information
apiKeyStringUnique identifier of the organization to update. It can be retrieved from the admin page in your WhiteSource account.Yes
usrKeyStringUnique identifier of user. It can be generated from the profile page in your WhiteSource account Required if WhiteSource administrator has enabled "Enforce user level access" option. See also User Level Access Control in Integrations and APIs.
checkPoliciesBooleanWhether or not to send the check policies request before updating WhiteSource.No
productNameStringName of the product to update.No. If not defined then matching to existing WhiteSource projects is done by 'productToken'
productVersionStringVersion of the product and project to update. This overrides the project version.No. Only read if 'productName' is defined
productTokenStringUnique identifier of the product to update.No. If not defined then matching to existing WhiteSource products is done by name
docker.urlStringThe URL of your Docker engine.Yes
docker.certPathStringThe path to the certificates used to connect to docker-machine (the Docker daemon is on a virtual host that uses an encrypted TCP socket).No. Only if using docker-machine
docker.withDockerTlsVerifyBoolean

Configure Docker to be reachable via the network in a safe manner

Yes
offlineBooleanWhether or not to create an offline update request instead of sending one to WhiteSource.No
offline.zipBooleanWhether or not to zip the content of the offline request. Used to decrease the size of the offline update request file.No
offline.prettyJsonBooleanWhether or not to parse the content of the offline request (not required for sending to WhiteSource).No
wss.urlString

URL for sending the request.

Use the 'WhiteSource Server URL' which can be retrieved from your 'Profile' page on the 'Server URLs' panel. Then, add the '/agent' path to it. For example: 
"https://<domain>.whitesourcesoftware.com/agent".

No. Default is https://saas.whitesourcesoftware.com/agent.


docker.readTimeOutStringDocker agent read timeoutNo. Default is 300000 milliseconds
docker.connectionTimeOutStringDocker agent connection timeoutNo. Default is to 300000 milliseconds
includesGlob PatternComma, space or line separated list of Ant style GLOB patterns specifying which files to include in the scan.NoSupported since version 1.8.0
excludesGlob PatternComma, space or line separated list of Ant style GLOB patterns specifying which files to exclude from the scan.NoSupported since version 1.8.0
archiveExtractionDepthIntegerDrill down hierarchy to extract each layerNo. The drill down is 2 by defaultSupported since version 18.2.2


Docker URL

Non-Secure

The Docker Agent uses docker-java to connect to the docker engine, according to their documentation:

"By default Docker server is using UNIX sockets for communication with the Docker client, however docker-java client uses TCP/IP to connect to the Docker server by default, so you will need to make sure that your Docker server is listening on TCP port. To allow Docker server to use TCP add the following line to /etc/default/docker

DOCKER_OPTS="-H tcp://127.0.0.1:2375 -H unix:///var/run/docker.sock"

Now make sure that docker is up:

$ docker -H tcp://127.0.0.1:2375 version
Client version: 0.8.0
Go version (client): go1.2
Git commit (client): cc3a8c8
Server version: 1.2.0
Git commit (server): fa7b24f
Go version (server): go1.3.1"

On Linux there is no need for docker.certPath (It is only for the Docker Toolbox on Windows).

TLS Encrypted

In order to run Docker on Windows you'll need to install Docker for Windows.

docker.url

Get the IP of the docker-machine by executing:

$ docker-machine ip default

The default IP should be 192.168.99.100 but may vary according to your configuration.

Use tcp://192.168.99.100:2376 or https://192.168.99.100:2376 as the docker.url.

docker.certPath

The path of the folder created when installing Docker Toolbox that contains ca.pem, ca-key.pem, cert.pem and key.pem.

Usually "C:\\Users\\User\\.docker\\machine\\certs".

Best Practices

WhiteSource recommends placing the product name in the configuration file (versions are optional). This is preferable for a first time setup as it will automatically create a new project and product in WhiteSource.

Offline Request (Optional)

Instead of sending an HTTP request to WhiteSource, a request can be created "offline" and exported to a text file containing the analyzed information in JSON format, which can then be uploaded to WhiteSource from the Admin Console.
Follow these steps:

  1. a. Change the offline property in your configuration file to true.
    b. For very large projects it's recommend to add the property offline.zip=true to reduce the size of the file created. This setting simply zips the content of the file.
  2. Locate the file update-request.txt created in the folder whitesource, where the file system agent runs.
  3. Go to this page: https://saas.whitesourcesoftware.com/Wss/WSS.html#!updateRequest.
  4. Select the update request file and click submit.

Execution

Run the jar from the command line:

If you want to place the configuration file in a different folder then you can specify its path as follows:

If you want scan a specific image from Docker Hub, then you can specify its name as follows:

Copyright Notices

The project uses code taken from the whitesource/docker-java forked from docker-java licensed under Apache 2.0.