Migrating to the Mend CLI from the Unified Agent

Overview

The Mend CLI is Mend’s latest all-in-one scanning utility, designed to combine all of Mend's scanning solutions SCA, SAST, and Container images. It is recommended for both CI/CD pipelines and developer desktops, offering a streamlined experience and enhanced capabilities.

Benefits of the Mend CLI

Unified Tool: Combines Mend SCA, SAST, and Container images scanning capabilities into a single binary.
No Scan Configuration Required: Scans after a build without the need for complex configuration. Most options are available as command-line flags.
Rich Console Output: Displays vulnerabilities and policy violations directly in the console, reducing the need to check the Mend UI.
Local Scanning: By default, SCA scans do not upload results to the Mend UI unless specified, allowing for local feedback without UI noise.
Broader Language and Package Manager Support: CLI supports more modern and diverse package managers and languages than UA (e.g., Bower, PNPM, Poetry, Conda, CocoaPods, Cargo, etc.).
Default Exclusions: CLI excludes dev dependencies and common test/example folders by default, but this can be configured.
Unified Agent Included: The Mend CLI binary contains the Unified Agent, allowing you to invoke legacy UA functionality directly via the CLI when needed.

Migration from Unified Agent to Mend CLI

Download and Setup: Replace the Unified Agent download step in your pipeline with the Mend CLI download.
Authentication: Set the following environment variables for authentication:
- MEND_URL
- MEND_USER_KEY
- MEND_EMAIL
Project and Application Assignment: Use the --scope flag to specify the organization, application, and project for scan results.
Failing on Policy Violations: Use the --fail-policy flag. The CLI exits with code 9 on policy violations, which should be handled in your pipeline scripts.
Build First: Ensure your application is built and dependencies are installed before scanning, as the CLI does not perform pre-build steps.

Comparing Scan Results and Configuration

Dependency Resolution: The CLI requires a completed build or installed dependencies. Use mend dep for SCA scans.
Uploading Results: Add the -u flag to upload results to the Mend UI.
Strict Mode: Use --strict to match the Unified Agent’s failerrorlevel=all.
Policy Checks: --fail-policy in the CLI is equivalent to checkPolicies=true in the UA.
Result Output: The CLI provides table output by default; use --export-results for JSON output.
Dev Dependencies: By default, CLI excludes dev dependencies (e.g., npm devDependencies, Maven test/provided, Gradle test configs). Use --dev to include them.
Directory and Path Exclusions: CLI excludes common folders (e.g., .git, test, docs) by default. Use --no-default-exclusions or environment variables to adjust. UA uses config file patterns.
File System Scan: CLI can perform a file system scan with --extended, but does not scan binaries (JAR, ZIP, DLL). UA supports more flexible file inclusion/exclusion.
Logging: CLI logs to .mend/logs/sca by default. Use --log-level or MEND_BASEDIR to adjust. UA uses config file or command-line log level.
Supported Languages: CLI supports a broader set of package managers and languages

When to Use the Unified Agent Instead of the Mend CLI

While the Mend CLI is recommended for most modern SCA workflows, there are scenarios where the Unified Agent (UA) remains the preferred or required tool:

Scanning Binary Files: If you need to scan binary files such as JAR, ZIP, DLL, or other archives for open source components, use the Unified Agent. The Mend CLI does not support binary scanning in its file system scan mode.
Archive Extraction: The Unified Agent supports archive extraction and can analyze the contents of compressed or packaged files, which is not available in the Mend CLI.
Monorepo and Multi-Project Scanning (projectPerFolder): If you need to scan and report on multiple projects within a monorepo or multi-project repository, the Unified Agent's projectPerFolder functionality allows you to automatically create a separate project for each folder. This feature is not available in the Mend CLI.
Legacy or Specialized Package Managers: For some legacy or less common package managers not yet supported by the CLI, the UA may still be required.
- Examples include:
  - Ant/Ivy (Java)
  - Paket (.NET)
  - RPM/DEB (Linux system packages)
  - Chocolatey (Windows)
  - Bazel
  - Older or complex Bower setups
  - NuGet with system packages (CLI does not support system package inclusion)
  - Custom or proprietary package managers
- This list is not exhaustive and may change as CLI support expands. For the latest, see our documentation on supported package managers: Mend CLI Supported Languages & Package Managers and Unified Agent Supported Languages & Package Managers.

Example: Migrating from Unified Agent to Mend CLI in a GitHub Actions Pipeline

Additional pipeline examples can be found in the Mend-Examples Repository

CODE

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