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).



  • Java version 7 or higher.


Download the latest version.

VersionFileFeaturesRelease DateMD5
  • Added support for user-level access control in integrations.
  • Minor bugs fixes
  • Minor bugs fixes
  • Minor bugs fixes
  • Minor bugs fixes
18.2.2whitesource-docker-agent-18.2.2.jarAdd parameter "archiveExtractionDepth".2018-03-182FF034A4B09356F07481667AB4E0A7A9
  1. Bug fix - StringIndexOutOfBoundsException error
  2. Bug fix - exception when excludes parameter does not exist
  1. Added support for super hash calculation.
  1. Added includes/excludes file extension parameter to config file.
  1. Collects Alpine and Arch Linux packages from active containers
  2. Upgraded build version to Java 8
1.0.6whitesource-docker-agent-1.0.6.jarAdded support for Alpine packages scanning.2017-09-2689CC50CF8CB831E48044DD9638D870ED

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

  1. Added connection timeout parameter
  2. Added read timeout parameter
  1. Bug fix - archive extraction error
  1. Bug fixes - .tgz files archive extraction
  2. Bug fixes - animation progress bar
  1. Bug fixes
  2. Added .tgz files
  3. Added debug logs
  1. Collects Debian and RPM package from active containers
  2. Scans open source libraries from active containers exported tar archive


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


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

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

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

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: 

No. Default is

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


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:// -H unix:///var/run/docker.sock"

Now make sure that docker is up:

$ docker -H tcp:// 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.


Get the IP of the docker-machine by executing:

$ docker-machine ip default

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

Use tcp:// or as the docker.url.


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 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:!updateRequest.
  4. Select the update request file and click submit.


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.