...
This page describes how to get started with the Unified Agent.
Prerequisites
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
...
Java JDK 17
Depending on your project type,
...
make sure that the relevant package
...
manager is installed:
Project Type | Package Manager |
---|---|
C# |
|
Elixir, Erlang | MIX |
Go |
|
Haskell | Cabal |
Java |
|
JavaScript |
|
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 |
|
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 | |
3 | Do one of the following:
(See execution examples on this page) |
4 |
Downloading the Unified Agent
The Unified Agent latest version can be downloaded from Amazon S3 or GitHub.
...
Latest Unified Agent Version | File | Features | Release Date |
---|
MD5
Comments
22.4.2 |
15- |
F2EB843816A572904954052756EB66E7
N/A
...
05-2022 |
Previous Unified Agent Versions
NOTE: Unified Agent versions will be available and supported for a year after their release.
Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
20-12-2020 70C387ECCA4FA7DCEA02C6C27FFE9247 | 2006N/A
20.5.1 24-05-2020 6C2BDD65B57EF8480C49C33D5B202185 N/A 20.4.2.1
12-05-2020 4FE20039F2323181A7B218E444D08D3B N/A 20.4.2
10-05-2020 A4311921A3C24D8B82401CA79765AC93 N/A 20.4.1.2
04-05-2020 EBDEF558C11911F312A43B3754D63516 N/A 20.4.1.1
27-04-2020 EA949C737B5F4F3B979BE3AEF71F9BC6 N/A 20.4.1
26-04-2020 11C15925E4A6DB42FED71BCC8B10351F N/A 20.3.2
12/04-2020 ACE029C7C78501DD4144ADEAFBC1F0F8 N/A 20.3.1
29-March-2020 570732B7B4993626886C7277DDEABEBE N/A 20.2.2
15-March-2020 265FDCDFE4957F563839CDAD5B69DB37 N/A 20.2.1
1-March-2020 EFA11408B05BD091C42BAA3D99C9E0A2 N/A 20.1.3
16-Feb-2020 EFA11408B05BD091C42BAA3D99C9E0A2 20.1.2
02-Feb-2020 F9A65505858A17C50B02E6A1FF0D0340 20.1.1
26-JAN-2020 386D855084E6BAC388E673BDCFF9C18E 19.12.2
05-JAN-2020 5600023FB14724540AB2FF41B906B2A7 19.12.1.2
26-DEC-2019 05CC57719938D46BCA7CCCB0585EB330 19.12.1.1
22-DEC-2019 62D3A4910D85548355789A7738E222AD 19.12.1
22-DEC-2019 0EC3A0C76513A2482D84C3B8434E22D7 19.11.2
08-DEC-2019 FEECAEDFEB849735627D68E005A6459F 19.11.1
24-NOV-2019 0000A3B0790E02FDF59FA88C1A726F2E 19.10.1
24-NOV-2019 5CAB6CA5092EDB9906E108DCD9332233 19.9.2.3
28-OCT-2019 68CBA721502F66E011A4CCCD7339C89D 19.9.2.2
27-OCT-2019 EE304EA7C5BD7D57041FBDD38C1FB446 19.9.1.1
26-SEP-2019 900C228DD11F4E1F4E2226E62486F8BB 19.9.1
22-SEP-2019 97B3136DD6756D70E68D3ABC3FA28AB9 19.8.1
08-SEP-2019 D2E1DEFCD0E378B65F16B8AA250A22C8 19.7.3.3
21-AUG-2019 98143FDF996818AAB937FAF9B09E0C44 19.7.3.2
20-AUG-2019 C150CF3D43A8699E9A3D21AE035F7EC1 19.7.3.1
19-AUG-2019 51B5BB8538EA2A82E10DF2E5285F8553 19.7.3
18-AUG-2019 54427B4C04E1C629DBC2D4089DAEAFAD 19.7.2
04-AUG-2019 4BD05463F66AE0BAC607F067923ADF71 19.7.1
21-JUL-2019 EC017302E7FCCEC507D769A105558177 19.6.1
07-JUL-2019 64986C756521FC446BC0700D71D43B74 19.5.3.1
23-JUN-2019 478F162CB95FAAC8684D90BCA3C56DD1 19.5.3
User can provide any parameters starting with '-' or '--', and Unified Agent should add these at the end of the gradle dependencies or gradlew dependencies command. For example:
23-JUN-2019 E71F5F36C466F11E71A1B194DF447638 19.5.2
02-JUN-2019 EC909172A7429CC7847BC6BE08F4F7DC 19.5.1.2
27-MAY-2019 914B9C20FC70455AAB93873DC98ECE05 19.5.1.1
20-MAY-2019 D1D0A3A9F1142B6B99DF40E60E4B7FE3 19.5.1
19-MAY-2019 D1D0A3A9F1142B6B99DF40E60E4B7FE3 19.4.2.1
13-MAY-2019 A622E7DA33353BBACC65C3CE7686927A 19.4.2
05-MAY-2019 E46756D06E43E5B317A1ABC7E508E9FD 19.4.1.1
22-APR-2019 FA72DF9C4CDE9B0F6C14E5D0404C9665 19.4.1
21-APR-2019 9F37EB3DAAD94F49F865132478E19143 19.3.2.1
08-APR-2019 0D46F5FBAB5496232BACB9907C8BDF94 19.3.2
07-APR-2019 CB8013F47AFFEB9E1A1DA4861FF8A91C 19.3.1
24-MAR-2019 02F4B9C66A4FF2EC8941E5F507F6C0C2 19.2.2.2
17-MAR-2019 B45A15A7A9B12A9297411211C9D067A6 19.2.2.1
13-MAR-2019 16030BB5E6CFC6E8CD9B3CCC011E340D 19.2.2
10-MAR-2019 EE59E98203D567163A1275517D11431B 19.2.1.1
25-FEB-2019 58C607518E8CD3BF760099E3F6FCF885 19.2.1
24-FEB-2019 754A658FC4A6CAA2B6F3F585C5178EF7 19.1.2
10-FEB-2019 08B8241D8D0096B55D5EF912C82C7867 19.1.1
27-JAN-2019 A928EE6FD80A747933D378838C9EAF9A 18.12.2
13-JAN-2019 28F2B17BC7AEF31B2832B28996BDAABD 18.12.1
30-DEC-2018 A0B04D6F8922D07DC9225FF27619815 18.11.2.1
30-DEC-2018 656C065FF61D346F2BC8A002439DAA0F 18.11.1
02-DEC-2018 BDB9D6867813EB25AFD8324904110409 18.10.3
18-NOV-2018 8EBDEAE146BCEF47D2E53FB6CFCC388F 18.10.2.1
05-NOV-2018 74F359FF56E3B4A426BD13A43D1C7BF7 18.10.2
04-NOV-2018 6DAE5432F21817CD8DAAAA0FAFC7117F 18.10.1
21-OCT-2018 8E343F78D76A98D650EB504FEB3D4314 18.9.1.1
09-OCT-2018 089FBF27CD1F6EA530EFC455856F22DF 18.9.1
07-OCT-2018 D9FCDC2F85CC9E6095A97DD3E86A88B4 18.8.3.1
17-SEP-2018 9CFEFE1B7D529E0E84BAAEBC46B94B3A 18.8.3
16-SEP-2018 550B87D9AED5561CA230B6C30CA5A158 18.8.2
02-SEP-2018 70B01D9E7204D68C93558E9444B28702 18.8.1
19-AUG-2018 2C390264F7BD4F737A3403114B64EC5C 18.7.2
05-AUG-2018 E0F44F15C1F33BE76248A78A6547416A 18.7.1
22-JUL-2018 018EA81E0A89DE35D5968D39B9B02F4D 18.6.3
08-JUL-2018 16C93A64450FA4265F2E47E398F134CC 18.6.2
24-JUN-2018 | 18.5.221A5029C6AF2852DE66C8F226B17D305
10-JUN-2018 6B7F6022D08FAA38B1DD0A5ECACC8ABD 18.5.1
27-MAY-2018 8F25D5E8EA83DF3107133EA6A573B121 18.4.2
13-MAY-2018 3897BB8AE4DBCA0F3D1FBE792C563829 18.4.1
29-APR-2018 6DBBE0F301874AE6287F92B8BF85D0EC 18.3.2
15-APR-2018 44654A53BA445F4DEA77852D74237B54 18.3.1
04-APR-2018 08E75B61DA9CBB47C002B818D9358A9F 18.2.2
18-MAR-2018 CD111E1D774F97ACE931E4734F1AB327 18.2.1
04-MAR-2018 7FD0BB04C8F6C2A1951FA0B431D4AAEB 18.1.3
18-FEB-2018 8EF2C85EA5F63F5451907F3ED0578F22 18.1.2
04-Feb-2018 0AE008C1F3EADEE99C5A45C13DDB9C8B 18.1.1
21-Jan-2018 E335C27978D2EF88E735612601BA9EFA 17.12.4
07-Jan-2018 8CB2174EA7CDF5FDF6EB1AE23D5E71EC 17.12.2
24-Dec-2017 7E2CE04A4542123810655F873B2C782B 17.12.1
17-Dec-2017 417A15BE609EDB1F2FDE29558A92E184 17.11.4
03-Dec-2017 979B5221EC7A20A61FF350A4CABF6E80 17.11.3
26-Nov-2017 d4af724a29a69f99540432638111c5e8 17.11.2
19-Nov-2017 47236E596CF529B7C7D450698DBA00BE 1.9.0
05-Nov-2017 C6396D64F974A09B5E353FEB767867B2 1.8.9 Added apiKey via command line using "-apiKey" Added support for sending offline requests via command line using "-requestFiles" Improved memory usage:
22-Oct-2017 4B2ECBF250F0C1DE683715637E10F5E4 1.8.8 Added ability to calculate more sha1 checksums to improve matching of source files. Resolved issues WSA-213, WSA-256:
24-Sep-2017 355DAC0C30B07339F437D2B75BE52CD0 1.8.7 Resolved issues WSA-100, WSA-104:
04-Sep-2017 5AAC786F099D2AF3B4731F178A56A960 1.8.6 Resolved issues WSA-64, WSA-69, WSA-75, WSA-76, #7 and #8:
2017-08-28 8D5377A99B359E97B405300C71031C3A 1.8.5
2017-08-08 B1983464ACDDC8E0D290850539AD0EBF 1.8.4 Added NuGet recognition through packages.config files 2017-07-31 195BB14CE51277EF99E5FE876182F43A 1.8.3 Reads productVersion and projectVersion from command line 2017-07-31 5ACC4D2E889ED8BB5E017A9C53D37860 1.8.2 Fixed issues of missing 'version' tag on dependency listing 2017-07-23 07DB808A24ABC9E27F6FE4F111CADAA1 1.8.1
2017-07-19 CFAF17D45D0FE43151148A9064D4F141 1.8.0
2017-07-12 B38BD003DE107D26CA0E45F2E4595CBC Java 8 is required. |
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:
Command-line parameters
Environment variables
Configuration file
Default values
Setting the 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
...
WhiteSource URL
...
WS_WSS_URL
...
wss.url
...
-wss.url
...
WhiteSource URL:
https://[saas/app/app-eu/saas-eu].whitesourcesoftware.com/agent
...
Project Name
...
WS_PROJECTNAME
...
projectName
...
-project
...
The name of the project created after running a scan
...
Includes
...
WS_INCLUDES
...
includes
...
N/A
...
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
General Tips
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.
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.
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 in a shell script task as part of your build pipeline:
Linux/macOS:
java -jar /path/to/wss-unified-agent.jar -c /path/to/wss-unified-agent.config -d /path/to/project/root/directory
Windows:
java -jar "C:\path\to\wss-unified-agent.jar" -c "C:\path\to\wss-unified-agent.config" -d "C:\path\to\project\root\directory"
NOTES:
Either full or relative paths can be used
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
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.
Start/End Indication
A start/end indication is displayed for each scan step. For example:
Code Block |
---|
------------------------------------------------------------------------
-------------------- Start: Pre-Step & Resolve Dependencies ------------
------------------------------------------------------------------------
[INFO] [2019-03-07 13:58:02,775 +0200] - Trying to resolve MAVEN dependencies
[INFO] [2019-03-07 13:58:02,776 +0200] - topFolder = C:\Users\Me\Desktop\UAtests\GenerateScanReport\generateScanReport\Data
[INFO] [2019-03-07 13:58:07,105 +0200] - Start parsing pom files
[INFO] [2019-03-07 13:58:07,112 +0200] - End parsing pom files , found : search-engine,search-engine-client,search-engine-server
[INFO] [2019-03-07 13:58:07,191 +0200] - Trying to resolve HTML dependencies
[INFO] [2019-03-07 13:58:09,113 +0200] -
------------------------------------------------------------------------
-------------------- End: Pre-Step & Resolve Dependencies --------------
------------------------------------------------------------------------ |
Summary Table
A summary at the end of 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.
For example:
Code Block |
---|
Step Completion Status Elapsed Comments
======================================================================================================================================================
Fetch Configuration COMPLETED 00:00:00.078 --------
Scan Files Matching 'Includes' Pattern COMPLETED 00:00:00.014 1 source/binary files
Pre-Step & Resolve Dependencies COMPLETED 00:00:06.378 7 total dependencies (7 unique)
MAVEN COMPLETED 00:00:04.416 5 total dependencies (5 unique)
HTML COMPLETED 00:00:01.922 2 total dependencies (2 unique)
Update Inventory COMPLETED 00:00:01.551 2 updated projects
======================================================================================================================================================
Elapsed running time: 00:00:08.021
======================================================================================================================================================
Process finished with exit code SUCCESS (0) |
Execution Examples
The following are several syntax examples for various use cases of the Unified Agent execution:
Executing the Unified Agent:
Code Block |
---|
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:
Code Block |
---|
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:
Code Block |
---|
/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):
Code Block |
---|
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.
Code Block |
---|
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:
Code Block |
---|
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 well:
Code Block |
---|
java -jar /path/to/jar/wss-unified-agent.jar -c http://user:password@example.com:8080/ -d /path/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.
Code Block |
---|
java -jar /path/to/jar/wss-unified-agent.jar -updateType APPEND -c /path/to/config/file -d /path/to/lib/folder |
Run the Unified Agent to create one project per subfolder:
Code Block |
---|
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
Code Block |
---|
java -jar /path/to/jar/wss-unified-agent.jar -c /path/to/config/file -apiKey your-api-key -d /path/to/lib/folder |
Example:
Run the Unified Agent with proxy parameters from the command line instead of the configuration file
Code Block |
---|
java -jar /path/to/jar/wss-unified-agent.jar -c /path/to/config/file -d /path/to/lib/folder -proxy.host my-proxy-host-name -proxy.port my-proxy-port-number -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).
Code Block |
---|
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 |
...
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.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:
Command-line parameters
Environment variables
Configuration file
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 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: 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=<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
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>
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
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.
Start/End Indication
A start/end indication is displayed for each scan step. For example:
Code Block |
---|
------------------------------------------------------------------------
-------------------- Start: Pre-Step & Resolve Dependencies ------------
------------------------------------------------------------------------
[INFO] [2019-03-07 13:58:02,775 +0200] - Trying to resolve MAVEN dependencies
[INFO] [2019-03-07 13:58:02,776 +0200] - topFolder = C:\Users\Me\Desktop\UAtests\GenerateScanReport\generateScanReport\Data
[INFO] [2019-03-07 13:58:07,105 +0200] - Start parsing pom files
[INFO] [2019-03-07 13:58:07,112 +0200] - End parsing pom files , found : search-engine,search-engine-client,search-engine-server
[INFO] [2019-03-07 13:58:07,191 +0200] - Trying to resolve HTML dependencies
[INFO] [2019-03-07 13:58:09,113 +0200] -
------------------------------------------------------------------------
-------------------- End: Pre-Step & Resolve Dependencies --------------
------------------------------------------------------------------------ |
Summary Table
A summary at the end of 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.
For example:
Code Block |
---|
Step Completion Status Elapsed Comments
======================================================================================================================================================
Fetch Configuration COMPLETED 00:00:00.078 --------
Scan Files Matching 'Includes' Pattern COMPLETED 00:00:00.014 1 source/binary files
Pre-Step & Resolve Dependencies COMPLETED 00:00:06.378 7 total dependencies (7 unique)
MAVEN COMPLETED 00:00:04.416 5 total dependencies (5 unique)
HTML COMPLETED 00:00:01.922 2 total dependencies (2 unique)
Update Inventory COMPLETED 00:00:01.551 2 updated projects
======================================================================================================================================================
Elapsed running time: 00:00:08.021
======================================================================================================================================================
Process finished with exit code SUCCESS (0) |
Execution Examples
The following are several syntax examples for various use cases of the Unified Agent execution.
Executing the Unified Agent with Inline environment variables:
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:
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.