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:
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 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:
Setting the Configuration Parameters
Set the following configuration parameters, in any of the available methods, for the Unified Agent's execution:
The name of the project created after running a scan
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
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.
The following is an example of scanning C and C++ source files:
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 namedwss-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.
A start/end indication is displayed for each scan step. For example: