Versions Compared

Old Version 186

changes.mady.by.user Nabeel Saabna

Saved on

compared with

New Version 240

changes.mady.by.user David Jaffe

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

...

    • Java JDK 17

  2. Depending on your project type,

...

  1. make sure that the relevant package

...

  1. manager is 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)

  • Yarn

  • 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

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.

...

Latest Unified Agent Version

File

Features

Release Date

MD5

Comments

21.9.1.122.4.2

wss-unified-agent.jar

Release Notes 2122.94.1.12

2515-10-2021

706694E349EA14CB04C4621B70D99A93

N/A

...

05-2022

Previous Unified Agent Versions

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

Expand

Version

File

Features

Release Date

MD5

Comments

2122.94.1.1

wss-unified-agent-2122.94.1.1.jar

22.4.1

wss-unified-agent-22.4.1.jar

Release Notes 2122.94.1.1

2501-1005-20212022

706694E349EA14CB04C4621B70D99A93N/A

N/A

2122.93.13

wss-unified-agent-2122.93.13.jar

Release Notes 2122.93.13

17-1004-20212022

510303D7588212C666F16B042A05BC3FN/A

N/A

2122.83.2.1

wss-unified-agent-2122.83.2.1.jar

Release Notes 2122.83.2.1

0306-1004-20212022

7F2D383794A6FBAA2B45C5D2E99B9FE1N/A

N/A

2122.83.1.12

wss-unified-agent-2122.83.12.1.jar

Release Notes 2122.83.1.12

3103-0804-20212022

239DAD256F1E8BFAF7361FDEECE3E2CEN/A

N/A

2122.83.1

wss-unified-agent-2122.83.1.jar

Release Notes 2122.83.1

2920-0803-20212022

5E066881180AB1C1C24748145F784B32N/A

N/A

2122.72.2.2

wss-unified-agent-2122.2.72.2.jar

Release Notes 2122.2.72.2

1520-0803-20212022

90BE9617B380EF507C5D5ABE0191FCFAN/A

N/A

2122.2.72.1

wss-unified-agent-2122.2.72.1.jar

Release Notes 2122.2.72.1

0109-0803-20212022

B18E7F9CACB80993151F4518F852710BN/A

N/A

2122.62.32

wss-unified-agent-2122.62.32.jar

Release Notes 2122.62.32

1806-0703-20212022

B897BADFEBA66A39963717899E327F86N/A

N/A

2122.6.2.21

wss-unified-agent-2122.6.2.21.jar

Release Notes 2122.6.2.21

0620-0702-20212022

BAC44FB66BE88130ECA094A37B81F527N/A

N/A

2122.61.2

wss-unified-agent-2122.61.2.jar

Release Notes 2122.61.2

0406-0702-20212022

5E7FE501C0B1BEF76F64EE683B917012N/A

N/A

2122.1.61.1

wss-unified-agent-2122.1.61.1.jar

Release Notes 2122.61.1.1

2027-0601-20212022

F2EB843816A572904954052756EB66E7N/A

N/A

2122.51.21

wss-unified-agent-2122.51.21.jar

Release Notes 2122.51.21

0623-0601-20212022

8E51FDC3C9EF7FCAE250737BD226C8F6N/A

N/A

21.512.12

wss-unified-agent-21.512.12.jar

Release Notes 21.512.12

2309-0501-20212022

B50664F3840004A868D34D608030005CN/A

N/A

21.412.21

wss-unified-agent-21.412.21.jar

Release Notes 21.412.21

0926-0512-2021

19ADD8EB5637DBD6BE63B9553576DAF99F459173DD2F4A1B0BCA16E3387248D6

N/A

21.11.42.1

wss-unified-agent-21.411.2.1.jar

Release Notes 21.411.2.1

2516-0412-2021

AD4F3747F519F83A2DF8963FF36D61B4C938CB75252B312961D16FBA3FC0F443

N/A

21.311.2.1

wss-unified-agent-21.311.2.1.jar

Release Notes 21.311.2.1

1312-0412-2021

707B193FEB891C1B40DD98A0B433ECA81EEDF78497CD5801D152B19CC7E65C69

N/A

21.311.21

wss-unified-agent-21.311.21.jar

Release Notes 21.311.21

28-11-04-2021

C3576952F70F574FE6745E754A16A0EEBA19E92BC8B508AA93CC7652EC878B1B

N/A

21.310.12

wss-unified-agent-21.310.12.jar

Release Notes 21.310.12

0414-0411-2021

C5639E304DEC915F664CE2B391D5A9D790A989C0D60A70FCC9A62AF2D54F5E9B

N/A

21.210.21

wss-unified-agent-21.210.21.jar

Release Notes 21.210.21

1431-0310-2021

5118B3403C578EC3AD922901CF70EF8574BB03F271E93CAB9FD3710FC6B786DB

N/A

21.29.1.1

wss-unified-agent-21.9.21.1.jar

Release Notes 21.29.1.1

2825-0210-2021

490F2217238889F0EC22A4D9352174B9706694E349EA14CB04C4621B70D99A93

N/A

21.1.29.1

wss-unified-agent-21.19.2.1.jar

Release Notes 21.19.2.1

1417-0210-2021

9C6B4DE63AAC89EBB4E7411F792C0AA8510303D7588212C666F16B042A05BC3F

N/A

21.8.1.21

wss-unified-agent-21.8.1.21.jar

Release Notes 21.8.1.21

1431-0208-2021

15D50AB0EF4D43907393515BF19F6897239DAD256F1E8BFAF7361FDEECE3E2CE

N/A

21.18.1

wss-unified-agent-21.18.1.jar

Release Notes 21.18.1

3129-0108-2021

FDC75043196E49882BCBE19CBCBBD81D5E066881180AB1C1C24748145F784B32

N/A

2021.127.32

wss-unified-agent-2021.127.32.jar

Release Notes 2021.127.32

1715-0108-2021 2021

00198172C5724A389CCD6EACD41B8D9690BE9617B380EF507C5D5ABE0191FCFA

N/A

2021.127.21

wss-unified-agent-2021.127.21.jar

Release Notes 2021.127.21

0301-0108-2021

DA174CC191818A3763CC79934C2AEAE8B18E7F9CACB80993151F4518F852710B

N/A

2021.126.13

wss-unified-agent-2021.126.13.jar

Release Notes 2021.126.13

2018-1207-20202021

70C387ECCA4FA7DCEA02C6C27FFE9247B897BADFEBA66A39963717899E327F86

N/A

2021.6.112.2

wss-unified-agent-2021.6.112.2.jar

Release Notes 2021.6.112.2

06-1207-20202021

20FC4F59F3183F98D12E82882039531ABAC44FB66BE88130ECA094A37B81F527

N/A

2021.116.12

wss-unified-agent-2021.116.12.jar

Release Notes 2021.116.12

2204-1107-20202021

75293725F596010982E7B831B6BC2F985E7FE501C0B1BEF76F64EE683B917012

N/A

2021.106.21

wss-unified-agent-2021.106.21.jar

Release Notes 2021.106.21

0820-1106-20202021

AD6F30452BAB599BA13CFBE6CDC59AC1F2EB843816A572904954052756EB66E7

N/A

2021.105.12

wss-unified-agent-2021.105.12.jar

Release Notes 2021.105.12

2506-1006-20202021

2D4624B239234177C851F7204ADB21F38E51FDC3C9EF7FCAE250737BD226C8F6

N/A

2021.95.2.1

wss-unified-agent-2021.9.25.1.jar

Release Notes 2021.95.2.1

1523-1005-20202021

673218A312EB4BF2EB4BB2122E66D2ECB50664F3840004A868D34D608030005C

N/A

2021.94.12

wss-unified-agent-2021.94.12.jar

Release Notes 2021.94.12

0409-1005-20202021

F375670B1F651330254AF5C65830CB1019ADD8EB5637DBD6BE63B9553576DAF9

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

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

...

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
    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.
    It is recommended to create a blank configuration file and only add parameters that you would like to change in order to make use of the default configuration settings.

  • Command-line Parameters
    The Unified Agent supports a select number of 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

...

Description

...

API Key

...

WS_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

The Server URL with /agent added aftewards. 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.

...

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

...

User Key

...

WS_USERKEY

...

userKey

...

Required if enforce user level access has been enabled as shown here. See the following link for how to generate a user key.

...

Product Name

...

WS_PRODUCTNAME

...

productName

...

The name of the product created after running a scan

...

Project Name

...

WS_PROJECTNAME

...

projectName

...

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.

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

    • This is will allow the unified agent to detect libraries with all three of its detections methods shown below

  • Dependency Resolution

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

  • Binary and Source File Hash Matching

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

Scanning Binary and Source Files Overview

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

  • The WhiteSource Index includes ~340M files and ~45M open-source projects.

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

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

  • For each matched source file, the likely origin of that source is determined using a property algorithm

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

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

*SmartMatch is trademarked

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

Code Block
cd <your codebase directory>

Linux/macOS:

Code Block
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

Windows:

Code Block
set WS_APIKEY=<your-api-key>
set WS_USERKEY=<your-user-key>
set WS_PRODUCTNAME=<your-product-name>
set WS_PROJECTNAME=<your-project-name>
java -jar wss-unified-agent.jar
Info

Specify the -d parameter to scan another directory besides the current working directory. Full or relative paths can be used, however paths with spaces needed to be enclosed with ""

Running the Unified Agent in a Docker Container

The Unified Agent can also be executed via Docker container which is available on https://hub.docker.com/r/whitesourceft/dockerua

The original Dockerfile template containing different package managers (e.g. maven, npm, etc.) can be found here. Within the file are installation instructions that enable you to create a customizable environment for scanning projects/files, plus a basic (editable) set of package managers.

NOTE: The dockerized unified agent is currently not capable of scanning docker images or containersjava -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

...

Summary Table

A summary at the end of the scan with all the relevant information on each step is also displayed. It includes 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.

...

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

Executing the Unified Agent with environment variables:

https://whitesource.atlassian.net/wiki/spaces/WD/pages/1140852201/Getting+Started+with+the+Unified+Agent#Running-the-Unified-Agent various use cases of the Unified Agent execution.

Executing the Unified Agent with inline Inline environment variables: 

...

languagebash

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

...

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

...

...

languagebash

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

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.