Command Line Tool (CLT)

The Command Line Tool (hereafter referred to as the CLT) is an executable Java .jar file that has two main uses:

  • Scanning
    • source code projects that are built with any of the supported build systems / languages
    • compiled Java (JAR, WAR, or EAR files) or compiled Microsoft files (DLL or EXE files)
    • Docker Linux images that use a supported package manager
  • Preparing the application for run-time protection by inoculating Java applications with MergeBase’s runtime monitoring and protection instrumentation.

In both cases, the tool produces a vulnerability report and, unless offline mode is specified, the scan data is uploaded to the customer’s MergeBase dashboard where the components are monitored for new vulnerabilities.

Using the CLT

Downloading

To use the CLT, download the mergebase.jar file from your MergeBase dashboard. This jar file is a wrapper that will download the actual tool. It will check for updates and automatically upgrade if there is a new version.

Download via API

You can also download the mergebase.jar via API from your dashboard server:

Usage:

GET : [dashboard-domain]/api/update/clt/mergebase.jar

Authorization:
Must include "X-Authorization: [customer-token]" HTTP header with your unique customer token.
You can retrieve this token from the main Settings page on your dashboard.

Quick Help Page

Running the CLT with the “--help” option prints out the CLT’s quick-help page. As of version 3.4.9, it prints the following:

Usage:
  java -jar mergebase.jar [arguments...] [scan targets...]

A scan target can be a directory, file, or docker image name with tag (e.g. "alpine:latest").

Exit codes:          0  - No vulnerabilities above violation threshold found.
                     1  - One or more vulnerabilities were found.
                     2  - Failed to connect to MergeBase Intelligence service.
                   100  - This help message was printed.
                   101  - Error with command arguments.
                   200  - Other errors.
                  1xxx  - Tool execution errors where xxx is the tool exit code.

Note that the violation level for non-offline scanning (normal mode) is set in the MergeBase dashboard.

Arguments:

  --help             Print this help.

Processing option must be one of the following modes:

  --scan (default)   Scan the dependencies of a single source project per scan path.
                     To scan recursively, use --all.

  --binary           Scan for all binary files recursively (e.g. Java jars, dotNet DLLs, .whl files)
  --binary=X         Specify the binary type to scan. Available flags are 'jar' for java, 'dll' for .NET
                     or 'clib' for C/C++

  --import           Import SBOM files in CycloneDX JSON format

  --inoculate        Inject runtime monitoring and mitigation code into Java jars

  --revert           Undo the inoculation (jars are restored to their original contents)

Required for all modes except --revert:

  --name=NAME        The name of the application being scanned or inoculated.

Optional for scan mode:

  --group=NAME       Assign the application to the named group. If the group does not exist,
                     it will be created.

  --all              Scan for projects/subprojects recursively. Applies to --scan mode only.
                     Exercise caution with this option as it may generate a very large scan.
                     In particular, it should normally not be used with multi-module Maven projects.

  --enforceLicensePolicy Return an error exit code if the scan detects
                     a component with a license that violates a license
                     policy defined in the MergeBase dashboard (not applicable to offline scans)

  --scope=all        Include all dependencies in the scan, including development and test dependencies.

  --pipFile=X        Scan a requirements.txt-formatted file with a custom name.

  --toolOptions=X    Specify options for use with a build tool (e.g. "-Dprofile-name" for Maven).
                     If the tool options use double quotes, you must escape them.
                     Ignored if --all is specified.

  --includeOnly=X    When scanning a Gradle project, include only subprojects with ids matching
                     the prefix

  --exclude=X        When scanning a Gradle project, exclude subprojects with ids matching
                     the prefix. Note: when both "--exclude" and "--includeOnly" are specified
                     at the same time, the "--exclude" is applied first.

  --configuration=X  When scanning a Gradle project, use 'X' as the Gradle configuration
                     The default is 'runtimeClasspath'

  --offline          Scan in offline mode (Enterprise version only). See User Guide for limitations.

Optional for all modes (except --revert):

  --sbom             Write an SPDX Lite SBOM (JSON format) to stdout or file if --outputFile is used.

  --sbom-cyclonedx   Write a CycloneDX SBOM + VEX (JSON format) to stdout or file if --outputFile is used.
                     This option is not available in offline mode

  --csv              Output scan results in the specified format
  --json             (e.g., csv, json, or xml)
  --xml

  --outputFile=FILE  Write vulnerability report to FILE instead of STDOUT.

  --verbose          Show all CVEs associated with each file (normally
                     the results display only the worst 2 or 3), and
                     show every file processed, including files with no
                     vulnerabilities.

  --compareFile=FILE Generate a CSV comparison report between the vulnerabilities detected in the scanned components
                     and those found in the specified comparison file(s). The comparison file(s) should contain a
                     list of CVEs in a compatible file format. This option can be used multiple times to compare
                     against multiple files. Use in conjunction with the outputFile flag.

  --quiet            Do not print any output during the scan.

  --exitZero         Always return exit code 0.
                     (E.g., don't kill build scripts, just report findings).

  --timeout=X        Set timeout for MergeBase scanner in minutes. Default value: 60

  --no-timeout       Don't timeout the MergeBase wrapper. Use with caution in CI/CD scenarios.

Optional for offline usage (Enterprise version only):

  --disableIgnore    Disable the CVE ignore list (".mergebase.ignore" file
                     in the current project directory, or if such does not
                     exist, a file in "~/.mergebase/ignore".

See: https://mergebase.com/
(C) Copyright 2024 Mergebase Software Inc. All Rights Reserved.

MergeBase CLT version=v3.10.2 (build-id: 80d3a26)

Source Code Scan

To scan a source code project and upload the results to your dashboard, run:

java -jar mergebase.jar --name="App Name" <target>

where “App Name” is the name you want to see in the dashboard and &lt;target> is the root directory of a project.

Specific requirements for each project type are detailed below in the section on Supported Languages and Build Systems.

The tool will print out a report and exit with an error code if any vulnerabilities are found. You can modify this behaviour with the --exitZero or --threshold options.

Four report formats are supported: plain text, CSV, JSON, and XML. These reports contain only information on components with vulnerabilities.

A complete list of all components with vulnerability and licensing information is available if you use the --sbom option.

Binary Scan

To initiate a binary file scan, employ the --binary flag followed by the target. Additionally, there is the option to include the --binary=X flag, referencing the options listed in the help manual.

<target> can be any of the following:

  • A Java deployable artifact (e.g. .jar, .war, .ear, .aar)
  • A Windows .dll or .exe file
  • A Python .whl (wheel) file
  • A directory containing the above files

Inoculate and Revert (Runtime Protection only)

To inoculate an application, run the following command:

java -jar mergebase.jar --inoculate --name="App Name" <target>

where “App Name” is the name you want to see in the dashboard.

<target> can be one of the following:

  • A Java deployable artifact (e.g. .jar, .war, .ear)
  • A directory containing Java deployable artifacts

If you are inoculating a third party application with a large number of .jar files (e.g. several hundred) and you have limited memory available on the machine you are using to run the CLT, you may need to inoculate the .jar files in smaller batches (or even one at a time). To assemble the results together into a single application in the dashboard, use --append on every invocation of the CLT after the first.

To revert an inoculation, use the --revert option:

java -jar mergebase.jar --revert <target>

Proxy Settings

The Command Line Tool (CLT) needs to be able to open a network connection to the customer’s MergeBase dashboard server in order for the results of scans to be available. If the CLT is unable to establish a connection, it will immediately halt and display an error message.

In complex environments to open this type of network connection might require the use of proxy servers.

The Java Virtual Machine (JVM) has built-in support for HTTP and HTTPS proxies, which can be set using Java system properties. For HTTPS, the relevant system properties are:

`https.proxyHost -` the host name of the proxy server


`https.proxyPort - `the port number (default value is 443)

For example, in order to run the CLT using a proxy my.proxy.com on port 443, you will need to add the system property definition as follows:

    java -Dhttps.proxyHost=my.proxy.com mergebase.jar …

Setting the proxy for an inoculated application will vary depending on the application platform and how it is deployed.

Reference: Java Networking and Proxies

Proxy User Authentication

The CLT supports proxy user authentication using the https.proxyUser and https.proxyPassword (optional) system properties provided by the Java environment.

Option 1: Password provided as parameters on the command line

This option is likely more relevant as part of automated workflows and scripts.

Usage:

    java -Dhttps.proxyHost=my.proxy.com -Dhttps.proxyUser=userid\
    -Dhttps.proxyPassword=password -jar mergebase.jar …normal parameters…

Option 2: Password entered interactively by a user

This option is likely more relevant in development or testing situations.

Usage:

    java -Dhttps.proxyHost=my.proxy.com -Dhttps.proxyUser=userid\
    -jar mergebase.jar  …normal parameters…

    Enter proxy password: <type password>

CLT Auto-Upgrading

The mergebase.jar CLT checks the MergeBase dashboard server to see if the CLT should self-upgrade itself. This check happens with every invocation. If the CLT’s version is older compared to the dashboard server’s version, then the self-upgrade logic is triggered.

Behind the scenes the CLT maintains a “mergebase-actual.jar” file in a hidden “.mergebase” directory under <HOME>/.mergebase/clt/ on the machine where it runs. When “mergebase.jar” sees that an upgrade is required it downloads and replaces the “mergebase-actual.jar” with the newer version.

In some situations some users prefer to not have files downloaded into the user’s HOME directory. You can override the download location by specifying a “-DMERGEBASE_HOME=X” value among the command-line arguments. This “-DMERGEBASE_HOME=X” value must be specified before “-jar”. For example:

java -DMERGEBASE_HOME=/tmp/ -jar mergebase.jar ...

Include Test and Development Dependencies

For package managers that support defining test and development dependencies in their manifest files, the command line tool offers an option to include both test and development dependencies in the scan. By using the --scope=all option, the scanner extends its coverage beyond primary dependencies to encompass all auxiliary components, ensuring a more thorough analysis of your application.

Offline Usage (for Enterprise customers)

The command line tool can run in an offline mode with some limitations. In this case it produces a vulnerability report but does not attempt to upload the scan data to the customer’s MergeBase server. To run in offline mode, add the command line option “--offline”. This feature is available to enterprise customers. Contact MergeBase for further details.

Supported Languages and Build Systems

MergeBase supports the following languages and build systems:

  • Java - Maven and Gradle
  • DotNet - NuGet
  • Go
  • JavaScript - NPM and Yarn
  • PHP - Composer
  • Elixir - Hex
  • Python - PIP
  • Dart - Pub
  • Ruby - GEM
  • Swift - Swift Package Manager, Cocoapods
  • Rust - Cargo
  • C/C++ - CMake, Make, Vcpkg and Conan

Maven

The CLT requires a globally installed maven executable or a mavenw/mavenw.bat script. Maven 3.5.0 or later is required.

You do not need to pre-build the project but scanning time will be faster if the Maven packages are already installed locally and do not need to be downloaded.

If you have a multi-module Maven project and wish to scan a particular profile, you can pass Maven options to select the profile using --mavenOptions. For example:

java -jar mergebase.jar ... --mavenOptions="-Dprofile-name"

Gradle

The CLT requires a globally installed gradle executable or a gradlew/gradlew.bat script. You do not need to pre-build the project but scanning time will be faster if the Maven packages are already installed locally and do not need to be downloaded.

In the case of a multi-module Gradle project, you can use --includeOnly to filter the sub-modules by their ids. For example:

java -jar mergebase.jar ... --includeOnly=:storage:remote

\ will select all sub-modules with ids that start with “:storage:remote” and exclude all other sub-modules.

The CLT uses the default configuration ‘runtimeClasspath’ to determine the scope of the scan. You can override this with the --configuration option.

java -jar mergebase.jar ... --configuration=customConfig

For Gradle projects with default configurations for Android, use releaseRuntimeClasspath as the configuration name.

Note: if the CLT fails to scan a sub-project in a multi-project Gradle project, the tool will output an error message and continue to scan the remaining sub-projects.

DotNet

If the project is not built or restored, the CLT will derive a component’s version from the range specified in the project file. If the project is built, the CLT will use the exact version provided by the dotnet list package command.The DotNet project must be built before running the CLT.

Go

The CLT requires Go to be installed. You can verify this by running “go mod” in your project root directory.

NPM and Yarn

The CLT requires both a package.json file and a package-lock.json (NPM) or yarn.lock (Yarn) file.

PHP Composer

The CLT requires both a composer.json file and a composer.lock file.

Elixir

The project must contain a mix.exs file (used by the Hex package manager).You must have the Elixir development tools installed, including the Hex package manager.

Python

The recommended method is to install the pipdeptree tool and save the output in a file called pipdeptree.txt. The alternate method is to use the ‘pip freeze’ command and save the output in a file called requirements.txt. If you use the latter method, you will not have the structure view that is provided using pipdeptree.

You can also scan for .whl files using the --binary option.

Rust

The CLT supports scanning Rust projects using Cargo. To ensure a successful scan, make sure that both the Cargo.toml and Cargo.lock files are present in the project directory.

Ruby

The CLT requires both a Gemfile and a Gemfile.lock file.You must have the Ruby development tools installed.

Swift

The CLT supports scanning Swift projects using either the Swift Package Manager or CocoaPods. For Swift Package Manager projects, please ensure that both Package.swift and Package.resolved files are present in the project directory. For CocoaPods projects, ensure that both Podfile and Podfile.lock files are available for a successful scan.

Dart (Pub)

The CLT supports scanning Dart projects using Pub. To scan successfully, make sure that both the pubspec.yaml and pubspec.lock files are present in the project directory.

Cargo

The CLT requires both the Cargo.toml and Cargo.lock files for successful scanning.

C/C++ Make, CMake

C or C++ projects using Make or CMake must be built before running the CLT. To scan C/C++ source projects, we recommend including the --all flag (but not the --binary flag). This will search the file system under the supplied paths for dependency information by examining Makefiles, CMake configuration files, Auto-Config files (*.ac), and other similar C/C++ build-related metadata files.

To scan C/C++ binary artifacts, be sure to include the --binary flag. MergeBase currently supports EXE, DLL, and ELF file formats when scanning C/C++ binary artifacts (e.g., executables and shared libraries, including .DLL and .so).

Vcpkg

For successful scanning with vcpkg, it is essential to have vcpkg installed and a vcpkg.json file included in the project directory.

Conan

For projects using Conan, a conanfile.txt file must be present in the project directory. To perform a complete scan of all components, you will need Conan version 1.X or later installed.

Supported Docker Package Managers

The CLT can scan Linux images if the target supplied on the command line is of the form image-name:tag. In this case, the tool will run a binary scan as described above on the image files and will also scan packages installed by any of the following package managers:

  • APK - Alpine Linux
  • APR - Debian
  • RPM

You must run ‘docker pull’ on the image you wish to analyze before invoking the scan.

Example:

java -jar mergebase.jar --name=Ubuntu ubuntu:latest