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.
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.
- Download the jar file.
- Create a text file with the name "whitesource-docker-agent.config" and place it in the same directory as the jar file.
- Copy the example below (or download) and fill in the apiKey parameter value taken from the API Key that is found here.
- Run the jar from the command line. See Executing.
Configuration file example (or download):
|apiKey||String||Unique identifier of the organization to update. It can be retrieved from the admin page in your WhiteSource account.||Yes|
|usrKey||String||Unique 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.|
|checkPolicies||Boolean||Whether or not to send the check policies request before updating WhiteSource.||No|
|productName||String||Name of the product to update.||No. If not defined then matching to existing WhiteSource projects is done by 'productToken'|
|productVersion||String||Version of the product and project to update. This overrides the project version.||No. Only read if 'productName' is defined|
|productToken||String||Unique identifier of the product to update.||No. If not defined then matching to existing WhiteSource products is done by name|
|docker.url||String||The URL of your Docker engine.||Yes|
|docker.certPath||String||The 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
|offline||Boolean||Whether or not to create an offline update request instead of sending one to WhiteSource.||No|
|offline.zip||Boolean||Whether or not to zip the content of the offline request. Used to decrease the size of the offline update request file.||No|
|offline.prettyJson||Boolean||Whether 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 https://saas.whitesourcesoftware.com/agent.
|docker.readTimeOut||String||Docker agent read timeout||No. Default is 300000 milliseconds|
|docker.connectionTimeOut||String||Docker agent connection timeout||No. Default is to 300000 milliseconds|
|includes||Glob Pattern||Comma, space or line separated list of Ant style GLOB patterns specifying which files to include in the scan.||No||Supported since version 1.8.0|
|excludes||Glob Pattern||Comma, space or line separated list of Ant style GLOB patterns specifying which files to exclude from the scan.||No||Supported since version 1.8.0|
|archiveExtractionDepth||Integer||Drill down hierarchy to extract each layer||No. The drill down is 2 by default||Supported since version 18.2.2|
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).
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 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.
The path of the folder created when installing Docker Toolbox that contains ca.pem, ca-key.pem, cert.pem and key.pem.
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:
- 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.
- Locate the file update-request.txt created in the folder whitesource, where the file system agent runs.
- Go to this page: https://saas.whitesourcesoftware.com/Wss/WSS.html#!updateRequest.
- 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:
The project uses code taken from the whitesource/docker-java forked from docker-java licensed under Apache 2.0.