@contrast/contrast-cli

Contrast command line interface

The Contrast CLI provides composition analysis capabilities at the command line to show you the dependencies between open source libraries, including where vulnerabilities were introduced. By supplementing existing runtime instrumentation from Contrast agents, with data from pre-compile analysis (not typically available at runtime), Contrast can provide a more detailed and comprehensive view of your applications in the Contrast UI.

Our recommendation is that this is invoked as part of a CI pipeline so that running the cli is automated as part of your build process.

Install:

Please Note: The Contrast CLI is executed as a Node.js package. We currently support versions 10, 12 and 14.

npm i -g @contrast/contrast-cli

Prerequisites:

The Contrast CLI creates a dependency tree and shows library vulnerabilities and sends the information to the Contrast UI.

Supported languages and their requirements are:

Java: pom.xml AND Maven build platform, including the dependency plugin. For a Gradle project, use build.gradle. A gradle-wrapper.properties file is also required. Kotlin is also supported requiring a build.gradle.kts file.
*Please Note: Running "mvn dependency:tree" or "./gradlew dependencies" in the project directory locally must be successful.
We currently support v4.8 and upwards on Gradle projects

.NET framework and .NET core: MSBuild 15.0 or greater and have a packages.lock.json file are supported.
*Please Note: If the packages.lock.json file is not in place it can be generated by setting RestorePackagesWithLockFile to true within each *.csproj and running dotnet build

Node : package.json AND a lock file either package-lock.json or yarn.lock

Ruby : gemfile AND gemfile.lock

Python : pipfile AND pipfile.lock

Go : You must have go.mod file present

How to run:

You can run the tool on the command line and manually add the parameters or you can include the parameters in a YAML file. If you are assessing an application that has not been instrumented by a Contrast agent, you must first use the tool to register the application (Catalogue command). This gives you an application ID that you then use in the Run command.

Allowable language values are JAVA, NODE, PYTHON and RUBY.

Manual Input Of Command

Catalogue Command

To analyse a new application not already instrumented by Contrast, run the following command:

contrast-cli --catalogue_application --api_key YourApiKey --authorization YourAuthorizationKey --organization_id YourOrganizationId --host YourHost --application_name YourApplicationName --language YourApplicationLanguage

After you run this command, you are provided a new application ID in the console. Use this ID to run the following command:

Run Command:

contrast-cli --api_key YourApiKey --authorization YourAuthorizationKey --organization_id YourOrganizationId --host YourHost --application_id YourApplicationId

Please Note: Parameters may need to be quoted to avoid issues with special characters.

Yaml Catalogue Command:

contrast-cli --catalogue_application --yaml_path PathToYaml

Run Command:

contrast-cli --yaml_path PathToYaml

Example Yaml Note all parameters must be named as below

cli:
	api_key: YourApiKey
	authorization: YourAuthorizationKey
	organization_id: YourOrganizationId
	host: YourHost
	application_name: YourApplicationName
	language: YourApplicationLanguage
	application_id: YourApplicationId

TLS To enable TLS please use the YAML file with the following parameters:

key: pathToKey
cert: pathToCert
cacert: pathToCaCert

Options:

--yaml_path string Used only if you want to run the command with a yaml
--api_key string (required): An agent API key as provided by Contrast UI
--authorization string (required): An agent Authorization credentials as provided by Contrast UI
--organization_id string (required): The ID of your organization in Contrast UI
--application_id string (required): The ID of the application cataloged by Contrast UI
--host string (required): Provide the name of the host and optionally the port expressed as <host>:<port>.
--application_name string (optional): The name of the application cataloged by Contrast UI
--catalogue_application (required for catalogue): Provide this if you want to catalogue an application
--language string (required for catalogue): Valid values are JAVA, DOTNET, NODE, PYTHON and RUBY. If there are multiple project configuration files in the project path, language is also required.
--project_path string (optional): The directory root of a project/application that you would like analyzed. Defaults to current directory.
--app_groups string (optional for catalogue): Assign your application to one or more pre-existing groups when using the catalogue command. Group lists should be comma separated.
--metadata string (optional for catalogue): Define a set of key=value pairs (which conforms to RFC 2253) for specifying user-defined metadata associated with the application
--tags string (optional for catalogue): Apply labels to an application. Labels must be formatted as a comma-delimited list. Example - label1,label2,label3
--code string (optional for catalogue): The application code this application should use in the Contrast UI.
--maven_settings_path string (optional): Allows you to specify an alternative location for your maven settings.xml file.
--proxy string (optional): Allows for connection via a proxy server. If authentication is required please provide the username and password with the protocol, host and port. For instance: 'http://username:password@:'.
--silent (optional): Silences JSON output.
-v, --version Displays CLI Version you are currently on.
--sub_project string (optional): Specify the sub project within your gradle application.
-h, --help Display usage guide.
-r, --report Display vulnerability information for this application.
-f, --fail Set the process to fail if this option is set in combination with the --report and --cveseverity.
-s, --cve_severity _type Combined with the --report command, allows the user to report libraries with vulnerabilities above a chosen severity level. For example, cveseverity=medium only reports libraries with vulnerabilities at medium or higher severity. Values for level are high, medium or low.
--cve_threshold _number The number of CVE's that must be exceeded to fail a build
--ignore_dev Combined with the --report command excludes developer dependencies from the vulnerabilities report. By default all dependencies are included in a report.