...

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

Prerequisites

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

...

1. :

   • Java JDK 8

   • Java JRE 8

   • Java JDK 11

...

1. • Java JDK 17

2. Depending on your project type,

...

1. make sure that the relevant package

...

1. manager is installed:

Unified Agent Usage Overview

Downloading the Unified Agent

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

...

...

Previous Unified Agent Versions

NOTE: Unified Agent versions will be available and supported for a year after their release.  

Setting Up the Unified Agent

There are several methods for configuring the Unified Agent:

...

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 wssnamed wss-unified-agent.config in 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, 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

Setting the Configuration Parameters

Set the following 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:

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

Scanning Best Practices

General Tips

...

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 product application are available. 
  During the detection, manifest 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

...

For each matched source file, the likely origin/repo of that source is determined. 

...

.

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

...

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 

•  

• 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 command on the machine where your code base is located, or 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:

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\export WS_APIKEY=<your-api-key>
export WS_USERKEY=<your-user-key>
export WS_PRODUCTNAME=<your-product-name>
export WS_PROJECTNAME=<your-project-name>
export WS_WSS_URL=https://saas.whitesourcesoftware.com/agent
java -jar wss-unified-agent.jar" -c "C:\path\to\

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.config" -d "C:\path\to\project\root\directory"

NOTES:

...

jar

NOTES:

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

• Full or relative paths can be usedWhenever an argument value includes spaces, it , however paths with spaces 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:

...

• ("").

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 ------------
-------------------
-------------------- Start: Pre-Step & Resolve Dependencies ------------
--------------------
[INFO] [2019----------------------------------------------------
[INFO] [2019-03-07 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 --------------
------------------------------------------------------------------------

...

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/=
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=<your-api-key>
export WS_USERKEY=<your-user-key>
WS_PRODUCTNAME=<your-product-name> WS_PROJECTNAME=<your-project-name> java -jar ./wss-unified-agent.jar

Executing the Unified Agent with the config file:

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

...

-c

...

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.

...

/path/to/config/file -d /directory/to/scan

Executing the Unified Agent on multiple folders or files:

export WS_APIKEY=<your-api-key>
export WS_USERKEY=<your-user-key>
export WS_PRODUCTNAME=<your-product-name>
export WS_PROJECTNAME=<your-project-name>
java -jar ./wss-unified-agent.jar

...

-d

...

/

...

directory/to/

...

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

...

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=<your-api-key>
export WS_USERKEY=<your-user-key>
export WS_PRODUCTNAME=<your-product-name>
export WS_PROJECTNAME=<your-project-name>
export WS_CHECKPOLICIES=true
export WS_FORCECHECKALLDEPENDENCIES=true
export WS_FORCEUPDATE=true
export WS_FORCEUPDATE_FAILBUILDONPOLICYVIOLATION=true
java -jar ./wss-unified-agent.jar

...

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.

Executing the Unified Agent with a proxy:

export WS_APIKEY=<your-api-key>
export WS_USERKEY=<your-user-key>
export WS_PRODUCTNAME=<your-product-name>
export WS_PROJECTNAME=<your-project-name>
export WS_PROXY_HOST=<your-proxy-host-name>
export WS_PROXY_PORT=<your-proxy-port-number>
export WS_PROXY_USER=<your-proxy-username>
export WS_PROXY_PASS=<your-proxy-password>
java -jar ./wss-unified-agent.jar 

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