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.