Overview

This page describes how to get started with the Unified Agent.

Prerequisites

Ensure you have one of the following Java versions on the computer on which you want to run the Unified Agent. 

Additionally, depending on your project type, ensure that the relevant package managers are installed:

Project Type

Package Manager

C#

  • NuGet + .Net

  • Paket

Elixir, Erlang

MIX

Go

  • Dep

  • Godep

  • Vndr

  • Gogradle

  • Govendor

  • Gopm

  • Glide

  • Vgo

  • Modules

  • Bazel

Haskell

Cabal

Java

  • Maven

  • Gradle

  • ANT

  • Bazel

JavaScript

  • Yarn - required only if the project is not built

  • NPM - required only if the project is not built (or the detection was set to use NPM)

  • Bower

Objective-C, Swift

CocoaPods - required only if the project is not built  

OCaml

Opam

PHP

Composer - required only if the project is not built

Python

  • PIP

  • Poetry

  • Pipenv

R

Packrat - if used

Ruby

Bundler

Rust

Cargo - required only if the project is not built

Scala

SBT

Unified Agent Usage Overview

Step #

Step Name

1

Download the latest version of the Unified Agent and verify its integrity.

2

Set up the Unified Agent.

3

Do one of the following:

(See execution examples on this page)

4

View the results in your WhiteSource organizational portal.

Downloading the Unified Agent

The Unified Agent latest version can be downloaded from Amazon S3 or GitHub.

Latest Unified Agent Version

File

Features

Release Date

MD5

Comments

21.7.2

wss-unified-agent.jar

Release Notes 21.7.2

15-08-2021

90BE9617B380EF507C5D5ABE0191FCFA

N/A


Version

File

Features

Release Date

MD5

Comments

21.7.2

wss-unified-agent-21.7.2.jar

Release Notes 21.7.2

15-08-2021

90BE9617B380EF507C5D5ABE0191FCFA

N/A

21.7.1

wss-unified-agent-21.7.1.jar

Release Notes 21.7.1

01-08-2021

B18E7F9CACB80993151F4518F852710B

N/A

21.6.3

wss-unified-agent-21.6.3.jar

Release Notes 21.6.3

18-07-2021

B897BADFEBA66A39963717899E327F86

N/A

21.6.2.2

wss-unified-agent-21.6.2.2.jar

Release Notes 21.6.2.2

06-07-2021

BAC44FB66BE88130ECA094A37B81F527

N/A

21.6.2

wss-unified-agent-21.6.2.jar

Release Notes 21.6.2

04-07-2021

5E7FE501C0B1BEF76F64EE683B917012

N/A

21.6.1

wss-unified-agent-21.6.1.jar

Release Notes 21.6.1

20-06-2021

F2EB843816A572904954052756EB66E7

N/A

21.5.2

wss-unified-agent-21.5.2.jar

Release Notes 21.5.2

06-06-2021

8E51FDC3C9EF7FCAE250737BD226C8F6

N/A

21.5.1

wss-unified-agent-21.5.1.jar

Release Notes 21.5.1

23-05-2021

B50664F3840004A868D34D608030005C

N/A

21.4.2

wss-unified-agent-21.4.2.jar

Release Notes 21.4.2

09-05-2021

19ADD8EB5637DBD6BE63B9553576DAF9

N/A

21.4.1

wss-unified-agent-21.4.1.jar

Release Notes 21.4.1

25-04-2021

AD4F3747F519F83A2DF8963FF36D61B4

N/A

21.3.2.1

wss-unified-agent-21.3.2.1.jar

Release Notes 21.3.2.1

13-04-2021

707B193FEB891C1B40DD98A0B433ECA8

N/A

21.3.2

wss-unified-agent-21.3.2.jar

Release Notes 21.3.2

11-04-2021

C3576952F70F574FE6745E754A16A0EE

N/A

21.3.1

wss-unified-agent-21.3.1.jar

Release Notes 21.3.1

04-04-2021

C5639E304DEC915F664CE2B391D5A9D7

N/A

21.2.2

wss-unified-agent-21.2.2.jar

Release Notes 21.2.2

14-03-2021

5118B3403C578EC3AD922901CF70EF85

N/A

21.2.1

wss-unified-agent-21.2.1.jar

Release Notes 21.2.1

28-02-2021

490F2217238889F0EC22A4D9352174B9

N/A

21.1.2.1

wss-unified-agent-21.1.2.1.jar

Release Notes 21.1.2.1

14-02-2021

9C6B4DE63AAC89EBB4E7411F792C0AA8

N/A

21.1.2

wss-unified-agent-21.1.2.jar

Release Notes 21.1.2

14-02-2021

15D50AB0EF4D43907393515BF19F6897

N/A

21.1.1

wss-unified-agent-21.1.1.jar

Release Notes 21.1.1

31-01-2021

FDC75043196E49882BCBE19CBCBBD81D

N/A

20.12.3

wss-unified-agent-20.12.3.jar

Release Notes 20.12.3

17-01-2021 

00198172C5724A389CCD6EACD41B8D96

N/A

20.12.2

wss-unified-agent-20.12.2.jar

Release Notes 20.12.2

03-01-2021

DA174CC191818A3763CC79934C2AEAE8

N/A

20.12.1

wss-unified-agent-20.12.1.jar

Release Notes 20.12.1

20-12-2020

70C387ECCA4FA7DCEA02C6C27FFE9247

N/A

20.11.2

wss-unified-agent-20.11.2.jar

Release Notes 20.11.2

06-12-2020

20FC4F59F3183F98D12E82882039531A

N/A

20.11.1

wss-unified-agent-20.11.1.jar

Release Notes 20.11.1

22-11-2020

75293725F596010982E7B831B6BC2F98

N/A

20.10.2

wss-unified-agent-20.10.2.jar

Release Notes 20.10.2

08-11-2020

AD6F30452BAB599BA13CFBE6CDC59AC1

N/A

20.10.1

wss-unified-agent-20.10.1.jar

Release Notes 20.10.1

25-10-2020

2D4624B239234177C851F7204ADB21F3

N/A

20.9.2.1

wss-unified-agent-20.9.2.1.jar

Release Notes 20.9.2.1

15-10-2020

673218A312EB4BF2EB4BB2122E66D2EC

N/A

20.9.1

wss-unified-agent-20.9.1.jar

Release Notes 20.9.1

04-10-2020

F375670B1F651330254AF5C65830CB10

N/A

20.8.2

wss-unified-agent-20.8.2.jar

Release Notes 20.8.2

13-09-2020

6CD6522EB3BFA9D5893505B618303C72

N/A

20.8.1.1

wss-unified-agent-20.8.1.1.jar

Release Notes 20.8.1.1

09-02-2020

E4D40C9C156BA1F284D23A09061FCAA9

N/A

20.8.1

wss-unified-agent-20.8.1.jar

Release Note 20.8.1

30-08-2020

2D4624B239234177C851F7204ADB21F3

N/A

20.7.3.1

wss-unified-agent-20.7.3.1.jar

Release Notes 20.7.3.1

24-08-2020

F15A81CA898EF48378C004F0C30DAC17

N/A

20.7.3

wss-unified-agent-20.7.3.jar

Release Notes 20.7.3

16-08-2020

088FE4495C2636DB12DDE290599D3487

N/A

20.7.2

wss-unified-agent-20.7.2.jar

Release Notes 20.7.2

02-08-2020

C4C1C03EAD650710F41BA06F934E6C8A

N/A

20.7.1

wss-unified-agent-20.7.1.jar

Release Notes 20.7.1

19-07-2020

B0E5171D9187DD5DCF0DC2E31065F210

N/A


Click here for earlier versions of the Unified Agent (previously called the File System Agent (FSA)).

Setting Up the Unified Agent

There are several methods for configuring the Unified Agent:

The configuration is applied in the following order of precedence:

  1. Command-line parameters

  2. Environment variables

  3. Configuration file

  4. Default values

Setting the Configuration Parameters

Set the following configuration parameters, in any of the available methods, for the Unified Agent's execution:

Parameter Name

Environment Variable Name

Configuration File Parameter Name

Command Line Parameter Name 

Description

API Key

WS_APIKEY

apiKey

-apiKey

The identifier of the organization

WhiteSource URL

WS_WSS_URL

wss.url

-wss.url

WhiteSource URL: 

https://[saas/app/app-eu/saas-eu].whitesourcesoftware.com/agent

Project Name

WS_PROJECTNAME

projectName

-project

The name of the project created after running a scan

Includes

WS_INCLUDES

includes

N/A

Which files to include/exclude in the scan (file extensions, file names. folder names, etc.) by use of GLOB patterns (i.e. **/*.c to scan all .c files). Refer here for details.

For setting more advanced and specific environment-related parameters, refer here.

Scanning Best Practices

General Tips

Scanning Source Files Overview

WhiteSource matches your source files to the source library (from GitHub, SourceForge, or other SCM) from which they most likely originated, done by utilizing a set of advanced algorithms. WhiteSource’s knowledge base includes ~340M source files and ~45M open-source projects (source libraries).

The source files matching method is required when there are no known packages that can be resolved by utilizing the dependency resolution process. It is instead required to match a list of scanned source files to a source library from where the files are downloaded - along with its version - in order to detect open source licensing information.

Note that the algorithm does not affect security vulnerabilities reporting as this information depends on source files.

Scanning Procedure 

The following is an example of scanning C and C++ source files:

includes=**/*.c **/*.cc **/*.cp **/*.cpp **/*.cxx **/*.c++ **/*.h **/*.hpp **/*.hxx

ignoreSourceFiles=false (default)

It is recommended to enable SmartMatch* (an enhanced matching algorithm) for an existing organization in the Advanced Settings section in the Integrate tab.

Running the Unified Agent 

To run the Unified Agent from the command line, execute the following command on the machine where your code base is located, or in a shell script task as part of your build pipeline:

Linux/macOS:

java -jar /path/to/wss-unified-agent.jar -c /path/to/wss-unified-agent.config -d /path/to/project/root/directory

Windows:

java -jar "C:\path\to\wss-unified-agent.jar" -c "C:\path\to\wss-unified-agent.config" -d "C:\path\to\project\root\directory"

NOTES:

Running the Unified Agent in a Docker Container

The Unified Agent can also be executed via Docker container. A Dockerfile template containing different package managers (e.g. maven, npm, etc.) can be found here. The file includes installation commands that enable you to create a customizable run environment for scanning projects/files, plus a basic (editable) set of package managers.

NOTE: This option currently does not support Docker scanning.

Viewing and Understanding the Scan Steps and Summary

The Unified Agent command-line interface enables you to view the steps that ran as part of a scan and understand how long each step took.

Start/End Indication

A start/end indication is displayed for each scan step. For example:

------------------------------------------------------------------------
-------------------- Start: Pre-Step & Resolve Dependencies ------------
------------------------------------------------------------------------
[INFO] [2019-03-07 13:58:02,775 +0200] - Trying to resolve MAVEN dependencies
[INFO] [2019-03-07 13:58:02,776 +0200] - topFolder = C:\Users\Me\Desktop\UAtests\GenerateScanReport\generateScanReport\Data
[INFO] [2019-03-07 13:58:07,105 +0200] - Start parsing pom files
[INFO] [2019-03-07 13:58:07,112 +0200] - End parsing pom files , found : search-engine,search-engine-client,search-engine-server
[INFO] [2019-03-07 13:58:07,191 +0200] - Trying to resolve HTML dependencies
[INFO] [2019-03-07 13:58:09,113 +0200] -
------------------------------------------------------------------------
-------------------- End: Pre-Step & Resolve Dependencies --------------
------------------------------------------------------------------------

Summary Table

A summary at the end of scan with all the relevant information on each step is also displayed. It Includes the following columns:

For example: 

Step                                 Completion Status                              Elapsed                              Comments
======================================================================================================================================================
Fetch Configuration                     COMPLETED                                 00:00:00.078                           --------
Scan Files Matching 'Includes' Pattern  COMPLETED                                 00:00:00.014                   1 source/binary files
Pre-Step & Resolve Dependencies         COMPLETED                                 00:00:06.378                   7 total dependencies (7 unique)
   MAVEN                                COMPLETED                                 00:00:04.416                   5 total dependencies (5 unique)
   HTML                                 COMPLETED                                 00:00:01.922                   2 total dependencies (2 unique)
Update Inventory                        COMPLETED                                 00:00:01.551                   2 updated projects

======================================================================================================================================================
Elapsed running time:                                                             00:00:08.021
======================================================================================================================================================
Process finished with exit code SUCCESS (0)

Execution Examples

The following are several syntax examples for various use cases of the Unified Agent execution:

Executing the Unified Agent: 

java -jar /path/to/jar/wss-unified-agent.jar -d /path/to/lib/folder

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

java -jar /path/to/jar/wss-unified-agent.jar -c /path/to/config/file -d /path/to/lib/folder

Multiple folders and files from text file:

(1)  To avoid a long command line string, use a text file with folders and files separated by new lines. For example:

/path/to/javascript/lib
/path/to/ruby/lib
/path/to/jars/aopalliance-1.0.jar
/path/to/jars/antlr-2.7.7.jar
/path/to/cpp/httpclient.cpp

 (2)  Run the agent using the argument '-f' (see Command Line Parameters):

java -jar /path/to/jar/wss-unified-agent.jar -f files.list

Multiple Folders and Files

Multiple folders and files can be scanned by entering comma-separated paths and using the argument '-d':

NOTE: Single files inserted via the -d argument are not excluded if they match the exclude glob pattern.

java -jar /path/to/jar/wss-unified-agent.jar -c /path/to/config/file -d /path/to/java/lib,/path/to/cpp/lib,/path/to/js/lib,/path/to/file/myfile.rb

Run the Unified Agent with the project and/or product parameters from the command line instead of the configuration file:

java -jar /path/to/jar/wss-unified-agent.jar -c /path/to/config/file -d /path/to/lib/folder -product my-product-name -productVersion 1.0.0 -project my-project-name -projectVersion 1.0.0

Allow downloading and using a configuration file from remote locations as well:

java -jar /path/to/jar/wss-unified-agent.jar -c http://user:password@example.com:8080/ -d /path/to/lib/folder

Run the Unified Agent with updateType from the command line:

NOTE: Supported from version 17.11.2. If not specified, the default value is updateType OVERRIDE.

java -jar /path/to/jar/wss-unified-agent.jar -updateType APPEND -c /path/to/config/file -d /path/to/lib/folder

Run the Unified Agent to create one project per subfolder:

java -jar /path/to/jar/wss-unified-agent.jar -projectPerFolder true -c /path/to/config/file -d /path/to/lib/folder

Run the Unified Agent with apiKey from the command line instead of the configuration file

java -jar /path/to/jar/wss-unified-agent.jar -c /path/to/config/file -apiKey your-api-key -d /path/to/lib/folder

Example:

Run the Unified Agent with proxy parameters from the command line instead of the configuration file

java -jar /path/to/jar/wss-unified-agent.jar -c /path/to/config/file -d /path/to/lib/folder -proxy.host my-proxy-host-name -proxy.port my-proxy-port-number -proxy.user my-proxy-username -proxy.pass my-proxy-password

Allow downloading and using the configuration file from remote locations with proxy 

NOTE: Running the Unified Agent with '-product' and '-project' parameters from the CLI will ignore the same parameters set in the configuration file (supported from version 1.7.1).

java -jar /path/to/jar/wss-unified-agent.jar -c path/to/config/file/in/remote -proxy scheme://<user>:<password>@host:port/ -d /path/to/lib/folder

*SmartMatch is trademarked.