CLI commands

The CLI offers a command line help guide with the -h or --help option. The help guide contains the following commands to help you understand more about Contrast configuration, applications, and vulnerabilities.

In the following examples, replace <string> or <level> with the string or level value that applies to your particular situation.

General commands

Commands for connection and configuration.

Command

Description

--api_key <string>

An agent API key provided by Contrast (required)

--application_id <string>

The ID of the application cataloged by Contrast (required)

--application_name <string>

The name of the application cataloged by Contrast (optional)

--authorization <string>

User authorization credentials provided by Contrast (required)

-h, --help

Displays the help guide

--host <string>

The name of the host and, optionally, the port expressed as <host>:<port>. Does not include the protocol section of the URL (https://). Defaults to app.contrastsecurity.com. (optional)

--language <string>

Valid values are JAVA, DOTNET, NODE, PYTHON, RUBY, and GO. If there are multiple project configuration files in the project_path, language is required. (required for catalogue)

--organization_id <string>

The ID of your organization in Contrast (required)

--project_path <string>

The directory root of a project/application that you want to analyze. Defaults to the current directory. (optional; required if running on Windows)

--proxy <string>

Allows for connection over a proxy server. If authentication is required, provide the username and password with the protocol, host and port. For example, http://username:password@<host>:<port>. (optional)

--silent

Silences JSON output (optional)

--sub_project <string>

Specifies the subproject within a Gradle application (optional)

-v, --version

Displays the CLI version you are currently using

--yaml_path <string>

The path to display parameters from the YAML file (optional)

If yaml_path is used, the following connection parameters are ignored from the terminal:

  • yamlOnly:

  • key:pathToKey

  • cert:pathToCert

  • cacert:pathToCaCert

Note

Parameters in these commands may need to be quoted to avoid issues with special characters. For example:

--application_name = "My_app_name_$+=(/\"

SCA

Commands related to Contrast SCA examination.

Command

Description

Catalog applications

--app_groups <string>

Assigns your application to one or more pre-existing groups when using the catalogue command. Group lists should be comma separated. (optional)

--catalogue_application

Catalog an application (required). If the application name does not exist, create the application and send the dependency tree, else append the dependency tree to an existing application.

--code <string>

The application code this application should use in Contrast (optional)

--metadata <string>

Define a set of key=value pairs (which conforms to RFC 2253) for specifying user-defined metadata associated with the application (optional)

--tags <string>

Apply labels to an application. Labels must be formatted as a comma-delimited list. Example - label1,label2,label3 (optional)

Snapshot - default command does not have a command on the terminal. Java only.

--maven_settings_path <PathToFile>

Allows you to specify an alternative location for your maven settings.xml file. Replace <PathToFile> with the full path for the file. Add this path to the full set of keys when youregister your application with the CLI. (optional)

Register an application

--cli_api_key <string>

--cli_authorization <string>

--cli_organization_id <string>

--cli_host <string>

--language <string>

--application_name <string>

--sbom

Use this set of commands (values described in the tables above and below) to register an application and get an SBOM report at the same time.

Note: The "cli_" prefix in the parameters will be deprecated in a future release.

Reports

--cve_severity <level>

Combined with --report, allows the user to report libraries with vulnerabilities above a chosen severity level. For example, cve_severity medium only reports vulnerabilities at Medium or higher severity.

--cve_threshold <number>

Sets the number of CVEs allowed before a build is failed. If there are more CVEs than the threshold, the build will fail.

--fail

Fails the build if any vulnerabilities are found. Can be used in combination with cve_severity to fail builds with vulnerabilities at severity levels defined by the user.

--report

Shows a report of vulnerabilities in the application from compile time

--ignore_dev

Combined with the --report command excludes developer dependencies from the vulnerabilities report. By default, all dependencies are included in a report.

SBOM

--sbom

Generate and download a Software Bill of Materials (SBOM) in CycloneDX JSON format

Tip

The --report command can be used to return details of all vulnerable libraries in the terminal response. Every CVE found will have output like this:

org.webjars/jquery-ui/1.11.4 is vulnerable

CVE-2016-7103 MEDIUM Cross-site scripting (XSS) vulnerability in jQuery UI before 1.12.0 might allow remote attackers to inject arbitrary web script or HTML via the closeText parameter of the dialog function.

The vulnerable records returned can be restricted by using the --cve_severity parameter which sets the minimum threshold for a CVE to be reported.

To prevent an application from being deployed with a library above a severity threshold the --fail parameter can be used as part of an automated CI/CD pipeline. For example, you can run the CLI using a YAML file with:

contrast-cli --yaml_path path/to/yaml --report --cve_severity high --fail

Scan

Commands related to Contrast Scan. See also Integrate scans with builds.

Contrast Scan supports EXE and ZIP files for .NET projects.  The language must be set to DOTNET and the ZIP should be a ZIP of the ./bin folder that contains your dlls.

Command

Description

--project_id <ProjectID>

The ID associated with a scan project. Replace <ProjectID> with the ID for the scan project. To find the ID, select a scan project in Contrast and locate the last number in the URL.

Recommended: For the first scan, use the --project_name command instead of this one. Scan creates the project for you.

--project_name <ProjectName>

The name of the scan project. If the name includes spaces, enclose it in double quotes (").

If you specify a new name, Scan creates the project. If you specify the name of an existing project, Scan adds the uploaded file to that project.

--scan<FileToBeScanned>

Starts a static scan of the specified WAR or JAR file. Replace <FileToBeScanned> with the path of the WAR or JAR file that you want to upload for scanning.

--scan_timeout

Set a specific time span (in seconds) before the function times out. The default timeout is 20 seconds if scan_timeout is not set.

--wait_for_scan

Waits for the result of the scan