This page describes how to get started with the Unified Agent.
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:
Unified Agent Usage Overview
Do one of the following:
(See execution examples on this page)
Downloading the Unified Agent
Latest Unified Agent Version
Click here for earlier versions of the Unified Agent (previously called the File System Agent (FSA)).
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.
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.
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:
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:
Environment Variable Name
Configuration File Parameter Name
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.
The Server URL with
The name of the product created after running a scan
The name of the project created after running a scan
Scanning Best Practices
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
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
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=falseas 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
-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 containers.
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.
A start/end indication is displayed for each scan step. For example:
A summary at the end of the 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.
The following are several syntax examples for various use cases of the Unified Agent execution:
Executing the Unified Agent with environment variables:
Executing the Unified Agent with inline environment variables:
Executing the Unified Agent with the config file:
Executing the Unified Agent on multiple folders or files:
Executing the Unified Agent with a policy check to return an error code in order to break a CI/CD pipeline:
Executing the Unified Agent with a proxy:
Additional examples for CI/CD pipelines and executing WhiteSource Prioritize can be found at https://github.com/whitesource-ft/ws-examples