...

Unified Agent Usage Overview

...

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

...

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 , in 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 what team members are scanning.

• Optimal detection is achieved when scanning after a successful build where dependency files used to create the product 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

  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 Binary and Source File Hash Matching

  • The WhiteSource Unified Agent also detects binaries and source files (such as .py files in Python

  )  and

  • or a .jar files in Java) 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 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.

...

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.

...

• 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

  • Source Files Matching Algorithm: SmartMatch

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

    • This feature is enabled by default for any new organization created.

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

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:java -jar "C:\path\to\wss-unified-agent.jar" -c "C:\path\to\

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

...

NOTES:

...

...

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

...

Running the Unified Agent in a Docker Container

The Unified Agent can also be executed via Docker container . A 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. The Within the file includes are installation commands instructions 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 The dockerized unified agent is currently not capable of scanning docker images or containers.

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: 

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 wellAgent execution:

Executing the Unified Agent with environment variables:

https://whitesource.atlassian.net/wiki/spaces/WD/pages/edit-v2/1140852201#Running-the-Unified-Agent

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 /path/to/jar/./wss-unified-agent.jar -c http:/path//user:password@example.com:8080/to/config/file -d /pathdirectory/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.

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 /path/to/jar./wss-unified-agent.jar -updateType APPEND -c /pathd /directory/to/scan,/directory/to/configscan2,/file -d /path/to/lib/folderscan

Run Executing the Unified Agent to create one project per subfolderwith a policy check to return an error code in order to break a CI/CD pipeline:

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

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 ./path/to/jar/wss-unified-agent.jar -c /path/to/config/file -apiKey your-api-key -d /path/to/lib/folder

Example:

...

Executing the Unified Agent with proxy parameters from the command line instead of the configuration filea proxy:

java -jar /path/to/jar/wss-unified-agent.jar -c /path/to/config/file -d /path/to/lib/folder -proxy.host 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
-proxy.port export WS_PROXY_PORT=my-proxy-port-number
-proxy.user export WS_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).

export WS_PROXY_PASS=my-proxy-password
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

...

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