Skip to main content
Skip table of contents

Getting Started with the Unified Agent

Prerequisites

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

    • Java JDK 21

  2. The Unified Agent requires HTTPS, port 443 outbound network access to your Mend environment. For example, https://saas.mend.io. This is required unless --offline mode is specified.

  3. Depending on your project type, make sure that the relevant package manager is installed:

Project Type

Package Manager

C#

  • NuGet + .Net

  • Paket

Elixir, Erlang

MIX

Go

  • Dep

  • Godep

  • Vndr

  • Gogradle

  • Govendor

  • Gopm

  • Glide

  • Vgo

  • Modules

  • Bazel

Haskell

Cabal

Java

  • Maven

  • Gradle

  • ANT

  • Bazel

JavaScript

  • Yarn - required only if the project is not built

  • NPM - required only if the project is not built (or the detection was set to use NPM)

  • PNPM

  • Bower

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

  • PIP

  • Poetry

  • Pipenv

  • Conda

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 (below) and verify its integrity.

2

Set up the Unified Agent

3

Do one of the following:

(See execution examples on this page)

4

View the results in your Mend organizational portal.

Downloading the Unified Agent

NOTE: The Unified Agent versions will be available and supported for one year after their release.  

JAR File

SHA256 Checksum

GitHub Repository

Features

wss-unified-agent.jar

SHA256

unified-agent-distribution

Mend Server Release Notes

Tip: The latest version of our Unified Agent and its download can also be accessed by visiting our Product Downloads page. Previous versions of the Unified Agent can be found here.

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.  For more information see the Command-line Parameters section below.
    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 see the Unified Agent Configuration Parameters.

The configuration is applied in the following order of precedence:

  1. Command-line parameters

  2. Environment variables

  3. Configuration file

  4. 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 Mend User Interface under the Organization section. Requires admin level access to see this page.

Mend URL

WS_WSS_URL

wss.url

-wss.url

The Server URL with /agent added. This can also be found on the Integrate page of the Mend User Interface under the Organization section. Requires admin level access to see this page.

For example: https://saas.whitesourcesoftware.com/agent

User Key

WS_USERKEY

userKey

-userKey

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

  • A setting entitled New products are automatically assigned to the admin group prevents users from scanning anonymously by always assigning scans to the admin group by default. Note that:

    • Existing organizations must enable this option as it will not be enabled by default.

    • New organizations will have New products automatically assigned to the admin group selected by default.

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

  • A detailed article with more Unified Agent scanning best practices can be found 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 Mend 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 Mend Index.

  • Mend matches binary and source files to the repository (such as, GitHub, SourceForge) from which they most likely originated. 

  • The Mend 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: SmartMatch

    • It 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 is true.

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

Unified Agent - Local Scanning

This video demonstrates how to perform a scan with the Unified Agent using the minimally required command line parameters.

Summary Table

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.

For example: 

CODE 
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 Mend Prioritize can be found at https://github.com/mend-toolkit/mend-examples/tree/main/CI-CD.  

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close