Best Practices for the Unified Agent

Unified Agent Overview

The Mend Unified Agent can be executed by any tool or method that supports shell execution (executing a pipeline shell task, calling an external shell script, or even executing manually via the terminal/command prompt).

Refer to Getting Start with the Unified Agent for some basic scanning best practices.

When using the Unified Agent as part of an automated process that's intended to be halted upon any identified issues or violations, it is recommended to execute the scan before any other tests and otherwise time-consuming processes that are not directly required to build the project.

Refer to the Mend Field Toolkit repository for examples of running the Unified Agent.

Configuration

It is recommended to use Environment Variables to configure the Unified Agent, so that both the scan's execution and configuration would be managed in the same place. Make sure to set the minimum required parameters in order to use the default configuration.

The Unified Agent also supports configuration by an external config file, in case you prefer to create configuration "profiles" and maintain them separately.

If using configuration files, name the file whitesource.config and check this into the repository that is being scanned for reference. This will also allow the repository integration to use the same configuration if the scanSettings configMode is changed from AUTO to LOCAL.

Whether using environment variables or the config file, it recommended to only add configuration parameters that require a change in order to use the default scan settings.

Keeping the Unified Agent Up to Date

Mend releases a new Unified Agent with new features, improved detection accuracy and bug fixes every two weeks. It is strongly recommended to always use the latest version.

Downloading the latest version

The simplest way to keep the agent up to date when setting up automated scans using CI pipelines is to download the latest version on every execution via curl or wget. A generic example can be found in the Mend Toolkit alongside more specific CI/CD examples grouped by technology stack.

Using specific versions

If you do not wish to use the latest version of the Unified Agent, it is recommended to either point to a specific version or download a specific version and host this in a local repository or file system that build agents can pull from. It is NOT recommended to build this into a container as the unified agent requires packages managers located in the pipeline for the most accurate scan. Using specific versions is a recommended approach when there is a need to test the Unified Agent internally rather than downloading the latest version onto production environments. This process should be scheduled & performed quarterly in order to avoid using obsolete versions.

Caching

If you do not wish to download a new instance of the Unified Agent on every execution, it is possible to configure your pipeline to only download the latest version if there is a new one available. This can be done using your CI tool’s native artifact caching capability or the file system if you use a self-hosted build agent. Examples can be found in the mend toolkit by searching for “cache”.

Integrity Verification

It is recommended to verify the integrity of the downloaded Unified Agent per each release by comparing it to the published checksum file. The Mend Toolkit examples show how to verify the integrity in a bash scripted pipeline.

Scan Use Cases

The Mend Unified Agent can be used for monitoring your Open Source inventory at almost any stage of the Software Development Lifecycle (SDLC).

Scanning the Default Branch

The default branch is the main codebase, and typically forms the latest snapshot of a software project. In most organizations, the default branch is constantly built and tested on every merge to maintain integrity, monitor security and compliance issues and identify regressions. It is recommended to add the Unified Agent to a pipeline a shell script task that occurs on every push to this branch. There is no need to configure the Unified Agent to perform a policy check as a policy check is automatically executed on the server side once a project inventory is updated.

Scanning Release Branches

The release branch represents a complete feature set that's about to be published as a specific version of the project.
A release branch scan should be treated the same as a default branch scan with the corresponding release version appended to the project name as shown in the pipeline integration example.

Scanning Feature Branches or Pull/Merge Requests

It is recommended to scan feature branches and pull/merge requests using a Mend Repository integration as detailed in Organization/Product/Project Mapping Best Practices. If this is not an option, then refer to the pipeline integration example and ensure that you are using a separate organization and cleaning up the orphaned scans from merged branches.