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).
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.4.9 (build-id: 4ea80c2)
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 <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