| Table of Contents |
|---|
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.
Java JDK 8
Java JRE 8
Java JDK 11
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
...
...
3
...
Do one of the following:
Manually run the Unified Agent.
(WhiteSource best practice) Automatically run the Unified Agent from the relevant build server:
(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.8.1
...
...
...
29-08-2021
...
5E066881180AB1C1C24748145F784B32
...
N/A
...
| title | Previous Unified Agent Versions |
|---|
...
Version
...
File
...
Features
...
Release Date
...
MD5
...
Comments
...
21.8.1
...
...
...
29-08-2021
...
5E066881180AB1C1C24748145F784B32
...
N/A
...
21.7.2
...
...
...
15-08-2021
...
90BE9617B380EF507C5D5ABE0191FCFA
...
N/A
...
21.7.1
...
...
...
01-08-2021
...
B18E7F9CACB80993151F4518F852710B
...
N/A
...
21.6.3
...
...
...
18-07-2021
...
B897BADFEBA66A39963717899E327F86
...
N/A
...
21.6.2.2
...
wss-unified-agent-21.6.2.2.jar
...
...
06-07-2021
...
BAC44FB66BE88130ECA094A37B81F527
...
N/A
...
21.6.2
...
...
...
04-07-2021
...
5E7FE501C0B1BEF76F64EE683B917012
...
N/A
...
21.6.1
...
...
...
20-06-2021
...
F2EB843816A572904954052756EB66E7
...
N/A
...
21.5.2
...
...
...
06-06-2021
...
8E51FDC3C9EF7FCAE250737BD226C8F6
...
N/A
...
21.5.1
...
...
...
23-05-2021
...
B50664F3840004A868D34D608030005C
...
N/A
...
21.4.2
...
...
...
09-05-2021
...
19ADD8EB5637DBD6BE63B9553576DAF9
...
N/A
...
21.4.1
...
...
...
25-04-2021
...
AD4F3747F519F83A2DF8963FF36D61B4
...
N/A
...
21.3.2.1
...
wss-unified-agent-21.3.2.1.jar
...
...
13-04-2021
...
707B193FEB891C1B40DD98A0B433ECA8
...
N/A
...
21.3.2
...
...
...
11-04-2021
...
C3576952F70F574FE6745E754A16A0EE
...
N/A
...
21.3.1
...
...
...
04-04-2021
...
C5639E304DEC915F664CE2B391D5A9D7
...
N/A
...
21.2.2
...
...
...
14-03-2021
...
5118B3403C578EC3AD922901CF70EF85
...
N/A
...
21.2.1
...
...
...
28-02-2021
...
490F2217238889F0EC22A4D9352174B9
...
N/A
...
21.1.2.1
...
wss-unified-agent-21.1.2.1.jar
...
...
14-02-2021
...
9C6B4DE63AAC89EBB4E7411F792C0AA8
...
N/A
...
21.1.2
...
...
...
14-02-2021
...
15D50AB0EF4D43907393515BF19F6897
...
N/A
...
21.1.1
...
...
...
31-01-2021
...
FDC75043196E49882BCBE19CBCBBD81D
...
N/A
...
20.12.3
...
...
...
17-01-2021
...
00198172C5724A389CCD6EACD41B8D96
...
N/A
...
20.12.2
...
...
...
03-01-2021
...
DA174CC191818A3763CC79934C2AEAE8
...
N/A
...
20.12.1
...
...
...
20-12-2020
...
70C387ECCA4FA7DCEA02C6C27FFE9247
...
N/A
...
20.11.2
...
...
...
06-12-2020
...
20FC4F59F3183F98D12E82882039531A
...
N/A
...
20.11.1
...
...
...
22-11-2020
...
75293725F596010982E7B831B6BC2F98
...
N/A
...
20.10.2
...
...
...
08-11-2020
...
AD6F30452BAB599BA13CFBE6CDC59AC1
...
N/A
...
20.10.1
...
...
...
25-10-2020
...
2D4624B239234177C851F7204ADB21F3
...
N/A
...
20.9.2.1
...
wss-unified-agent-20.9.2.1.jar
...
...
15-10-2020
...
673218A312EB4BF2EB4BB2122E66D2EC
...
N/A
...
20.9.1
...
...
...
04-10-2020
...
F375670B1F651330254AF5C65830CB10
...
N/A
...
20.8.2
...
...
...
13-09-2020
...
6CD6522EB3BFA9D5893505B618303C72
...
N/A
...
20.8.1.1
...
wss-unified-agent-20.8.1.1.jar
...
...
09-02-2020
...
E4D40C9C156BA1F284D23A09061FCAA9
...
N/A
...
20.8.1
...
...
...
30-08-2020
...
2D4624B239234177C851F7204ADB21F3
...
N/A
...
20.7.3.1
...
wss-unified-agent-20.7.3.1.jar
...
...
24-08-2020
...
F15A81CA898EF48378C004F0C30DAC17
...
N/A
...
20.7.3
...
...
...
16-08-2020
...
088FE4495C2636DB12DDE290599D3487
...
N/A
...
20.7.2
...
...
...
02-08-2020
...
C4C1C03EAD650710F41BA06F934E6C8A
...
N/A
...
20.7.1
...
...
...
19-07-2020
...
B0E5171D9187DD5DCF0DC2E31065F210
...
N/A
...
Setting Up the Unified Agent
There are several methods for configuring the Unified Agent:
Configuration File
The path to the configuration file can be passed to the Unified Agent in the command line using the -c argument. If no file is specified, the Unified Agent will look for a configuration file named wss-unified-agent.config in the current working directory. Refer here for more information.
Download the latest Unified Agent's configuration file here.
For the full configuration parameters reference, refer to the Unified Agent Configuration Parameters page.Environment Variables
All the parameters available in the configuration file can be also passed to the Unified Agent using environment variables. For more information, refer here.Command-line Parameters
The Unified Agent supports command-line options and parameters. For more information refer here.
The configuration is applied in the following order of precedence:
Command-line parameters
Environment variables
Configuration file
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
Optimal detection using the WhiteSource tools is achieved when scanning during (or before) the build where dependency files used to create the product are available.
During the detection, manifest files (such as requirements.txt in python, for example) are being scanned and used to pinpoint a specific version of the package used.
In case the dependency/manifest files are missing during the scan and detection process, WhiteSource Unified Agent is detecting source files (such as .py files in Python) and matches them against the WhiteSource Index of source files.
For each matched source file, the likely origin/repo of that source is determined.
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:
Either full or relative paths can be used
Whenever an argument value includes spaces, it must be double-quoted
If no file is specified via the -c parameter, the Unified Agent will look for a configuration file named wss-unified-agent.config in the current working directory
If no path is specified via the -d parameter, the Unified Agent will scan the current working directory
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:
| Code Block |
|---|
------------------------------------------------------------------------
-------------------- 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:
Step: The relevant step of the scan
Completion Status: Either 'COMPLETED' or 'FAILED'
Elapsed: The time that step took. Note that the sub-steps are not included in the total elapsed running time (e.g., Maven, HTML).
Comments: When available, more information on the step.
For example:
| Code Block |
|---|
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:
| Code Block |
|---|
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:
| Code Block |
|---|
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:
| Code Block |
|---|
/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):
| Code Block |
|---|
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.
| Code Block |
|---|
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:
| Code Block |
|---|
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:
| Code Block |
|---|
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.
| Code Block |
|---|
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:
| Code Block |
|---|
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
| Code Block |
|---|
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
| Code Block |
|---|
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).
| Code Block |
|---|
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.is available at: https://docs.mend.io/bundle/unified_agent/page/getting_started_with_the_unified_agent.html