...
Previous Unified Agent Versions
Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
...
Environment Variables (Recommended)
All the parameters available in the configuration file can be also 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 namedwss-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 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.
...
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 For example: https://saas.whitesourcesoftware.com/agent |
User Key | WS_USERKEY | 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 | -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 |
...
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 using the WhiteSource tools is achieved when scanning during (or before) the build where dependency files used to create the product are available. 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 shown described below.
Detection Methods
Dependency Resolution
...
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: SmartMatchIt 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 istrue
.
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=my-apiKey
export WS_USERKEY=my-userKey
export WS_PRODUCTNAME=my-product
export WS_PROJECTNAME=my-project
java -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>
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 ("").
...
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 ./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=my-apiKey
export WS_USERKEY=my-userKey
export WS_PRODUCTNAME=my-product
export WS_PROJECTNAME=my-project
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:
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 ./wss-unified-
agentagent.jar
Executing the Unified Agent with a proxy:
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
export WS_PROXY_PORT=my-proxy-port-number
export WS_PROXY_USER=my-proxy-username
export WS_PROXY_PASS=my-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.