# Page Comparison

## Key

• This line was removed.
• Formatting was changed.

...

Project Type

Package Manager

C#

• NuGet + .Net

• Paket

Elixir, Erlang

MIX

Go

• Dep

• Godep

• Vndr

• Govendor

• Gopm

• Glide

• Vgo

• Modules

• Bazel

Cabal

Java

• Maven

• 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

• Conda

R

Packrat - if used

Ruby

Bundler

Rust

Cargo - required only if the project is not built

Scala

SBT

...

Step #

Step Name

1

2

Set up the Unified Agent.

3

Do one of the following:

• Manually run the Unified Agent.

• (WhiteSource best practice) Automatically run the Unified Agent from the relevant build server:

4

View the results in your WhiteSource organizational portal.

...

Latest Unified Agent Version

File

Features

Release Date

MD5

21.912.12

wss-unified-agent.jar

1709-10-2021

510303D7588212C666F16B042A05BC3F

N/A

...

 01-2022

## Previous Unified Agent Versions

Expand

Version

File

Features

Release Date

MD5

21.912.1

1726-1012-2021

510303D7588212C666F16B042A05BC3F9F459173DD2F4A1B0BCA16E3387248D6

N/A

21.811.2.1

0316-1012-2021

7F2D383794A6FBAA2B45C5D2E99B9FE1C938CB75252B312961D16FBA3FC0F443

N/A

21.811.1.12

3112-0812-2021

N/A

21.811.1

2928-0811-2021

5E066881180AB1C1C24748145F784B32BA19E92BC8B508AA93CC7652EC878B1B

N/A

21.710.2

1514-0811-2021

90BE9617B380EF507C5D5ABE0191FCFA90A989C0D60A70FCC9A62AF2D54F5E9B

N/A

21.710.1

0131-0810-2021

B18E7F9CACB80993151F4518F852710B74BB03F271E93CAB9FD3710FC6B786DB

N/A

21.69.1.31

1825-0710-2021

N/A

21.69.2.21

0617-0710-2021

BAC44FB66BE88130ECA094A37B81F527510303D7588212C666F16B042A05BC3F

N/A

21.68.1.21

0431-0708-2021

N/A

21.68.1

2029-0608-2021

F2EB843816A572904954052756EB66E75E066881180AB1C1C24748145F784B32

N/A

21.57.2

0615-0608-2021

8E51FDC3C9EF7FCAE250737BD226C8F690BE9617B380EF507C5D5ABE0191FCFA

N/A

21.57.1

2301-0508-2021

B50664F3840004A868D34D608030005CB18E7F9CACB80993151F4518F852710B

N/A

21.46.23

0918-0507-2021

N/A

21.6.42.12

2506-0407-2021

N/A

21.36.2.1

1304-0407-2021

707B193FEB891C1B40DD98A0B433ECA85E7FE501C0B1BEF76F64EE683B917012

N/A

21.36.21

1120-0406-2021

C3576952F70F574FE6745E754A16A0EEF2EB843816A572904954052756EB66E7

N/A

21.35.12

0406-0406-2021

C5639E304DEC915F664CE2B391D5A9D78E51FDC3C9EF7FCAE250737BD226C8F6

N/A

21.25.21

1423-0305-2021

N/A

21.4.2.1

2809-0205-2021

N/A

21.1.24.1

1425-0204-2021

N/A

21.13.2.1

1413-0204-2021

15D50AB0EF4D43907393515BF19F6897707B193FEB891C1B40DD98A0B433ECA8

N/A

21.13.12

3111-0104-2021

FDC75043196E49882BCBE19CBCBBD81DC3576952F70F574FE6745E754A16A0EE

N/A

2021.123.31

Release Notes 2021.123.31

1704-0104-2021 2021

00198172C5724A389CCD6EACD41B8D96C5639E304DEC915F664CE2B391D5A9D7

N/A

2021.122.2

14-03-01-2021

N/A

2021.122.1

2028-1202-20202021

70C387ECCA4FA7DCEA02C6C27FFE9247490F2217238889F0EC22A4D9352174B9

N/A

2021.111.2.1

0614-1202-20202021

20FC4F59F3183F98D12E82882039531A9C6B4DE63AAC89EBB4E7411F792C0AA8

N/A

2021.111.12

Release Notes 2021.111.12

2214-1102-20202021

75293725F596010982E7B831B6BC2F9815D50AB0EF4D43907393515BF19F6897

N/A

2021.101.21

Release Notes 2021.101.21

0831-1101-20202021

N/A

20.1012.13

2517-1001-20202021

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

# Setting Up the Unified Agent

There are several methods for configuring the Unified Agent:

• Environment Variables (Recommended)
All the parameters available in the configuration file can be passed to the Unified Agent using environment variables. For more information, refer here.

• Configuration File
A 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

...

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

...

...

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

...

...

N/A

...

20.7.1

...

wss-unified-agent-20.7.1.jar

...

Release Notes 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.
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:

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

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

...

• .config in the current working directory.  Refer here for more information.
It is recommended to create a blank configuration file and only add parameters that you want to change, in order to make use of the default configuration settings. As a reference, please 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:

1. Command-line parameters

2. Environment variables

3. Configuration file

4. Default values

For the full configuration parameters reference, refer to the Unified Agent Configuration Parameters page.

# Setting the Minimum Required 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. This can be found on the Integrate page of the WhiteSource User Interface under the Organization section. Requires admin level access to see this page.

WhiteSource URL

WS_WSS_URL

wss.url

-wss.url

The Server URL with /agent added. This can also be found on the Integrate page of the WhiteSource User Interface under the Organization section. Requires admin level access to see this page.

For example: https://saas.whitesourcesoftware.com/agent

User Key

WS_USERKEY

userKey

-userKey

Required. See the following link for how to generate a user key.

Product Name

WS_PRODUCTNAME

productName

-product

The name of the product created after running a scan.

Project Name

WS_PROJECTNAME

projectName

-project

The name of the project created after running a scan

# Scanning Best Practices

## General Tips

• Require a userKey by enabling enforce user level access in order to see which team members are scanning.
NOTE: The userKey is also required for API calls and reporting parameters such as generateScanReport.

• Optimal detection is achieved when scanning after a successful build where dependency files used to create the application are available.
NOTE: This will allow the Unified Agent to detect libraries with all three of its detection methods, as described below.

## Detection Methods

### Dependency Resolution

During the detection, manifest files (such as, requirements.txt in python) are used to pinpoint a specific version of the package used.

### Binary and Source File Matching Overview

The WhiteSource Unified Agent also detects binaries and source files (such as, .py files in Python or a .jar file in Java) and matches them against the WhiteSource Index.

• WhiteSource matches binary and source files to the repository (such as, GitHub, SourceForge) from which they most likely originated.

• The WhiteSource knowledge base includes ~340M files and ~45M open source projects.

• The file matching method is required when there are no known packages that can be resolved by utilizing the dependency resolution process.

• For each matched source file, the likely origin of that source is determined using a proprietary algorithm: SmartMatch
For details, see Source Files Matching Algorithm: SmartMatch

• It is recommended to enable SmartMatch for any existing organization.

• SmartMatch is enabled by default for any newly created organization.

• Supported File Formats lists all currently supported file formats for hash matching.

• Binary matches occur only for the exact hash of each file.

• This feature can be disabled by setting fileSystemScan=false as the default value is true.

# Running the Unified Agent

To run the Unified Agent from the command line, execute the following commands in a shell script task as part of your build pipeline or in the directory where your codebase is located:

cd <your codebase directory>

Linux/macOS:

export WS_APIKEY=my-apiKey
export WS_USERKEY=my-userKey
export WS_PRODUCTNAME=my-product
export WS_PROJECTNAME=my-project
export WS_WSS_URL=https://saas.whitesourcesoftware.com/agent
java -jar wss-unified-agent.jar

Windows:

set WS_APIKEY=<your-api-key>
set WS_USERKEY=<your-user-key>
set WS_PRODUCTNAME=<your-product-name>
set WS_PROJECTNAME=<your-project-name>
set WS_WSS_URL=https://saas.whitesourcesoftware.com/agent
java -jar wss-unified-agent.jar

NOTES:

• Specify the -d parameter to scan another directory besides the current working directory.

• Full or relative paths can be used, however paths with spaces must be double-quoted ("").

# 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] -
----------------------------------------------------------------------------------
-------------------- StartEnd: 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).

For example:

Code Block
Step-

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

For example:

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

======================================================================================================================================================
Elapsed running time:                            COMPLETED                                 00:00:0108.551                   2 updated projects

021
======================================================================================================================================================
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

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===============================
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 with Inline environment variables:

export WS_APIKEY=my-apiKey
export WS_USERKEY=my-userKey
WS_PRODUCTNAME=my-product WS_PROJECTNAME=my-project java -jar ./wss-unified-agent.jar

Executing the Unified Agent with the config file:

java -jar ./wss-unified-agent.jar

...

 -

...

c

...

 /path/to/config/file

...

 -d

...

 /

...

directory/to/

...

Run the Unified Agent to create one project per subfolder:

...

scan

Executing the Unified Agent on multiple folders or files:

export WS_APIKEY=my-apiKey
export WS_USERKEY=my-userKey
export WS_PRODUCTNAME=my-product
export WS_PROJECTNAME=my-project
java -jar ./wss-unified-agent.jar

...

-d /directory/to/

...

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

...

scan,/directory/to/scan2,/file/to/scan

Executing the Unified Agent with a policy check to return an error code in order to break a CI/CD pipeline:

export WS_APIKEY=my-apiKey
export WS_USERKEY=my-userKey
export WS_PRODUCTNAME=my-product
export WS_PROJECTNAME=my-project
export WS_CHECKPOLICIES=true
export WS_FORCECHECKALLDEPENDENCIES=true
export WS_FORCEUPDATE=true
export WS_FORCEUPDATE_FAILBUILDONPOLICYVIOLATION=true
java -jar ./wss-unified-agent.jar

...

Executing the Unified Agent with a proxy:

export WS_APIKEY=my-apiKey
export WS_USERKEY=my-userKey
export WS_PRODUCTNAME=my-product
export WS_PROJECTNAME=my-project
export WS_PROXY_HOST=my-proxy-host-name

...

export WS_PROXY_PORT=my-proxy-port-number

...

export WS_PROXY_USER=my-proxy-username

...

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

...

export WS_PROXY_PASS=my-proxy-password

...

java

...

 -jar

...

./wss-unified-agent.

...

*SmartMatch is trademarked.jar

Additional examples for CI/CD pipelines and executing WhiteSource Prioritize can be found at https://github.com/whitesource-ft/ws-examples.