Migrating to the Mend CLI from the Unified Agent

Overview

The Mend CLI is Mend’s newest scanning utility that combines all Mend scanning capabilities to a single tool/binary. It is the recommended tool for scanning within a CI/CD pipeline or on a developer desktop. If you are using the Unified Agent, transitioning from the Unified Agent to the CLI can seem overwhelming. This document will detail the benefits of transitioning to the Mend CLI and what changes are required in your pipeline to start scanning with the Mend CLI.

Benefits of Mend CLI VS UA

No Scan Configuration Required

By scanning after a build, the Mend CLI does not require scan configuration to achieve the best scan results like the Unified Agent. There are still some configuration that can be done via command line flags. These flags can specify which project to send the scan results to, add a label to the project, or fail on a policy violation.

See Configure the Mend CLI for SCA or Configure the Mend CLI for Container Images for a full list of command line flags

Rich Output to Console

The Mend CLI will display all detected vulnerabilities and policy violations right in the console window. There is no need to go to the Mend UI in order to see the results of the scan.

Local Scanning Without Upload

For SCA, The Mend CLI does not upload results to the Mend UI without a command line flag. This allows developers to scan their applications locally for feedback without introducing noise into the Mend UI.

For Image Scanning, the Upload can be disabled via the command line flag: --no-upload

Secrets Detection within Container Images

The Mend CLI is able to detect secrets within your container images and provide alerts. This feature is turned on by default and requires no additional flag.

Differences between the Mend CLI VS Unified Agent

A full breakdown of the feature differences between the Mend CLI and the Unified agent can be found here.

Image Only

Results in the Mend UI

UA

Image scan results with the Mend Unified Agent will be uploaded to a Mend Project with the <Image Name> <Image Tag> <Image ID> as the default project name.

Mend CLI

Image scan results with the Mend CLI will be uploaded to the Cloud Native UI on the Legacy UI or the Mend Platform if activated for your organization. Results in the Mend Platform can be directed to a specific application or project by setting the --scope flag. See Setting Application and Project for more details on this flag.

Advisory Information

The Unified Agent does not factor advisory information for container vulnerabilities. Images scans done by the Unified Agent will always show vulnerabilities even if the advisory has explicitly said the container version is safe from a vulnerability.

The Mend CLI does factor advisory information as part of its results analysis so these vulnerabilities will not be displayed.

Scanning with the CLI in a Pipeline

Download the CLI

If your pipeline pulls down the Unified Agent every run, the step will need to be changed to download the Mend CLI.

Authentication

The Mend CLI requires authentication in order to execute a scan and upload results. It is recommend to use a service user to authenticate with the Mend CLI.

Once the service user is created, three environment variables will to be set. These variables are:

MEND_URL
MEND_USER_KEY
MEND_EMAIL

With these environment variables in place, any scan call will automatically be authenticated with the values.

Setting Application and Project

The organization will automatically be assigned based on the last logged in organization of the user authenticated with the Mend CLI. For a service user, this will be always be the org the service user is created in.

To set the application and project the CLI results are sent to requires the --scope command.

The supported formats of the --scope command is as follows:

Full hierarchy: -s "ORG//APPLICATION//PROJ"
Partial hierarchy: -s "APPLICATION//PROJ"
Single hierarchy: -s "PROJ"

Failing the Pipeline on Policy Violation

It is common use case of the Unified Agent to have the pipeline fail if Mend detects a policy violation. This functionality is supported in the Mend CLI with the --fail-policy flag.
Unlike the Unified Agent, the Mend CLI will only change it’s exit code to 9 if a policy violation is detected. This will need to be checked within the pipeline to prevent further execution.

CODE

# Run the scan command with fail-policy
mend dep --fail-policy

# Check the exit code and take action if it's 9
if [ $? -e 9 ]; then
    echo "Dependencies scan found policy violation"
    # Add error handling logic here
    exit 1  # Terminate the pipeline process
fi

# The process continues if no policy violation was detected
echo "Pipeline process continues..."

SCA Only

Calling the SCA Scan

The Mend CLI requires a completed build or for the dependencies to be installed in the local environment in order to scan. To scan your dependencies with the Mend CLI use command mend dep

Update the Mend UI

Updating the Mend UI is an optional flag for the Mend CLI. To update the Mend CLI add the flag -u

Image Only

Calling the Image Scan

To scan an image with the Mend CLI use the following command: mend image <image_name[:image_tag]>

If the image tag is not provided, the CLI will pull the latest version of that image.

Unlike the Unified Agent, the Mend CLI requires the full name of the image.

Pulling Images from Another Registry

By Default, the Mend CLI will attempt pull the image from Docker Hub. To pull an image from another container registry the full path to the image must be provided for the image name. See Mend CLI Container Image Supported Registries for the full list of registries.

mend image gcr.io/google-containers/<image_name[:image_tag]>

Scanning Local Images

The Mend CLI can scan images saved locally on your machine instead of pulling the image down from a docker registry. To scan a local image add the --local-pull command line flag

SCA Pipeline Comparison

Below is an example pipeline with the Unified Agent steps commented out and replaced with the Mend CLI. For more pipeline examples please go to the Mend Toolkit.

YAML

name: Mend CLI Scan

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Set up JDK
      uses: actions/setup-java@v2
      with:
        java-version: '11'
        distribution: 'adopt'
## Maven example - replace with your build steps
#
#    - name: Build with Maven
#      run: mvn clean install -DskipTests=true
##
# The Mend scan should be called AFTER a package manager build step such as "mvn clean install -DskipTests=true" or "npm install --only=prod"
    - name: Mend SCA Scan
      env:
        #WS_APIKEY: ${{secrets.PROD_APIKEY}}
        #WS_USERKEY: ${{secrets.PROD_USERKEY}}
        #WS_WSS_URL: https://saas.mend.io/agent
        #WS_PRODUCTNAME: ${{github.event.repository.name}}
        #WS_PROJECTNAME: ${{github.event.repository.name}}_${{github.ref_name}}
        MEND_EMAIL: ${{secrets.MEND_EMAIL}}
        MEND_USER_KEY: ${{secrets.MEND_USER_KEY}}
        MEND_URL: https://saas.mend.io
      run:
        # echo Downloading Mend Unified Agent
        # curl -LJO https://unified-agent.s3.amazonaws.com/wss-unified-agent.jar
        # if [[ "$(curl -sL https://unified-agent.s3.amazonaws.com/wss-unified-agent.jar.sha256)" != "$(sha256sum wss-unified-agent.jar)" ]] ; then
        #   echo "Integrity Check Failed"
        # else
        #   echo "Integrity Check Passed"
        #   echo Starting Unified Agent Scan
        #   java -jar wss-unified-agent.jar
        # fi
        |
        echo Downloading Mend CLI
        curl https://downloads.mend.io/cli/linux_amd64/mend -o /usr/local/bin/mend && chmod +x /usr/local/bin/mend
        echo run Mend dependencies scan
        mend dep -u -s ${{github.event.repository.name}}//${{github.event.repository.name}}_${{github.ref_name}}

Additional Information

Mend CLI Container Image-Supported Distributions

Mend CLI Container Image-Supported Runtime Entities