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 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.
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 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.
--threshold=X Minimum CVSS score (between 0.0 and 10.0) that
vulnerabilities must possess to be included in
results. If not specified, the default is 0.0.
NOTE: Vulnerabilities with no CVSS entry in the
federal NVD database are implicitly assigned a
score of 10.0 by this tool (a rare situation).
--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)
--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
--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, excludes --revert:
--sbom Write an SBOM (SPDX Lite) to stdout or file if --outputFile is used.
--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.
--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 ...
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
- Ruby - GEM
- C/C++ - CMake, Make, 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.
Ruby
The CLT requires both a Gemfile and a Gemfile.lock file.You must have the Ruby development tools installed.
C/C++ Make, CMake, and Conan
Most C or C++ projects must be built before running the CLT, although MergeBase can scan Conan dependency files pre-build. 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 config, Auto-Config (*.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).
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