Contrast CLI commands

The following is a listing of the commands available to basic and advanced users of Contrast CLI.

Usage:contrast [command] [options]

Authentication/connectivity

auth

For CodeSec users, if you don't have a Contrast account, authenticate using your GitHub or Google account. A new browser window opens for login.

Usage: contrast auth

If you already have a Contrast account, run the following auth command to store your credentials locally.

Usage:

contrast auth 
--api-key <your API key> 
--authorization <your authorization header> 
--host <your host domain> 
--organization-id <your organization ID>

You can then run an analysis with the commands.

config

Displays stored credentials.

Usage: contrast config

Example:

contrastuser@userc-C02GD0LUMD6TTY ~ % contrast config
{  
version: '1.0.24',  
host: 'https://ce.contrastsecurity.com',  
apiKey: 'wwEHMnYEIAujE03fFGH',  
organizationId: '0fde1b36-6986-4a14-b16d-6258aa913e5bceerfj',  
authorization: 'Z2l1bGlhbmEubWFyaWFuaUBjb250cmFzdHNlY3VyaXR5LmNvbTpDUktMUTE3T1czMDU2NjlLOPDS',  
numOfRuns: 0
}

Options:
- -c, --clear
  Removes stored credentials.

version

Displays Contrast CLI version.

Usage: contrast version

Example:

contrastuser@usercsa-C02GD0LUMD6TTY ~ % contrast version
1.0.24

Main functions

audit

Searches for a dependency configuration file in the working directory to perform a security audit of dependencies and returns the results.

Usage:contrast audit [option]

Example:

contrastuser@usercsa-C02GD0LUMD6TTY ~ % contrast audit
Searching for package manager files from /Users/contrastuser/Documents/

Contrast SCA audit started...
Contrast audit complete

Found 4 vulnerable libraries with 4 CVEs

CONTRAST-001 - [CRITICAL]  minimist-1.2.5 introduces 1 vulnerability
       Issue:  1 Critical
               [C]CVE-2021-44906
       Advice: Update to version 1.2.6
 
CONTRAST-002 - [CRITICAL]  json-schema-0.2.3 introduces 1 vulnerability
       Issue:  1 Critical
               [C]CVE-2021-3918
       Advice: Update to version 0.4.0

CONTRAST-003 - [HIGH]  glob-parent-5.1.1 introduces 1 vulnerability
       Issue:  1 High
               [H]CVE-2020-28469
       Advice: Update to version 5.1.2

CONTRAST-003 - [HIGH]  ansi-regex-0.2.1 introduces 1 vulnerability
       Issue:  1 High
               [H]CVE-2021-3807
       Advice: Update to version 6.0.1

Options:
- --fail
  Fail a build based on the severity of CVEs found. Use with the --severity flag. For example, contrast audit --fail --severity high . Returns all failures if no severity level is specified. If a failure is detected the CLI will exit with code 2.
- --file
  Specify a directory or the file where dependencies are declared. (By default, Contrast CLI will search for project files in the current directory.) If multiple project files are found in the directory, you will be prompted to confirm the file to audit.
  Alias:-f
- --help
  Displays usage information for all audit command options.
- --ignore-dev
  Excludes developer dependencies from the results. All dependencies are included by default.
  Alias:-i
- --legacy
  Creates an application in Contrast (a legacy workflow). It displays a dependency tree for your piece of code and utilizes metadata. Note that this is only available for Contrast CLI V2.0 and later.
- --name
  Set a custom project name. If the name is already in use, it will replace the results for that project. Avoid special characters.
- --save
  Generate and save an SBOM (Software Bill of Materials). Valid options are: --save cyclonedx and --save spdx (CycloneDX is the default format.).
  Alias:-s
- --severity
  Specify the minimum severity of CVE to fail a build. Use with the --fail flag. For example, contrast audit --fail --severity high. Severity levels are critical, high, medium, low, or note.
- --track
  By default, results are not held or stored, which would allow you to do local checks via your console. Add the --track flag to view your projects' SCA results under the Static view on the Libraries page in the Contrast web interface. Note that this is only available for Contrast CLI V2.0.

Advanced options:
- --api-key
  Required for Enterprise users. Agent API key provided by Contrast. See agent keys to find your keys.
- --application-id
  The ID of the application cataloged by Contrast.
- --application-name
  The name of the application cataloged by Contrast.
- --app-groups
  Assign your application to one or more preexisting groups when onboarding an application. Group lists should be comma separated.
- --authorization
  Required for Enterprise users. Authorization header provided by Contrast.
- --code
  The application code the application should use in Contrast.
- --host
  Required for Enterprise users. The host name. For example, https://app.contrastsecurity.com.
- --maven-settings-path
  Displays the path to the maven settings.xml file.
- --metadata
  Define a set of key=value pairs (that conforms to RFC 2253) for specifying user-defined metadata associated with the application.
- --organization-id
  Required for Enterprise users. The ID of your organization in Contrast. See agent keys to find the ID.
- --tags
  Apply labels to an application. Labels must be formatted as a comma-delimited list. For example, label1,label2,label3.
Proxy settings:
- --cacert
  Displays the path to the CaCert (certificate authority (CA) certificates) file.
- --cert
  Displays the path to the Cert (certificate) file.
- --cert-self-signed
  For Contrast on-premises (EOP) users with a local install, will bypass the SSL certificate and recognize a self-signed certificate.
- --key
  Displays the path to the Certificate Key.
- --proxy
  Allows for connection via 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>".

To use audit in pipelines for failing builds, see the Contrast SCA Action.

assess

Reports vulnerabilities found at run-time on a server using a Contrast agent.

Usage:contrast assess [option]

Example:

contrastuser@usercsa-C02GD0LUMD6TTY ~ % contrast assess
✔ Configuration file found at "user_path"
✔ Session created.
CONTRAST-001 - [HIGH] Path Traversal from "RawQuery" QueryString Parameter on
"/pathTraversal/os.Open/:source/:mode" pagePath Traversal from "RawQuery" QueryString Parameter on "/pathTraversal/os.Open/:source/:mode" page
       App: CLIAssessApplication
    Source: GET
            /pathTraversal/os.Open/:source/:mode?input=..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2Fetc%2Fpasswd
  Location: /opt/homebrew/Cellar/go/1.19.1/libexec/src/os/file.go, line 316, in os.Open()
  Dataflow: "../../../../../../../../../../../../etc/passwd"
     Issue: Because there is untrusted data being used as part of the file path, it may be possible
            for an attacker to read sensitive data or write, update, or delete arbitrary files on the
            container's file system. The ability to write arbitrary files to the file system is also
            called Unrestricted or Arbitrary File Uploads.


CONTRAST-002 - [HIGH] Path Traversal from "RawQuery" QueryString Parameter on
"/pathTraversal/os.ReadFile/:source/:mode" pagePath Traversal from "RawQuery" QueryString Parameter on "/pathTraversal/os.ReadFile/:source/:mode" page
       App: CLIAssessApplication
    Source: GET
            /pathTraversal/os.ReadFile/:source/:mode?input=..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2Fetc%2Fpasswd
  Location: /opt/homebrew/Cellar/go/1.19.1/libexec/src/os/file.go, line 672, in os.ReadFile()
  Dataflow: "../../../../../../../../../../../../etc/passwd"
     Issue: Because there is untrusted data being used as part of the file path, it may be possible
            for an attacker to read sensitive data or write, update, or delete arbitrary files on the
            container's file system. The ability to write arbitrary files to the file system is also
            called Unrestricted or Arbitrary File Uploads.


CONTRAST-003 - [HIGH] Path Traversal from "input[0]" Parameter on "/pathTraversal/os.Open/:source/:mode"
pagePath Traversal from "input[0]" Parameter on "/pathTraversal/os.Open/:source/:mode" page
       App: CLIAssessApplication
    Source: POST /pathTraversal/os.Open/:source/:mode
            input=..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2F..%2Fetc%2Fpasswd
  Location: /opt/homebrew/Cellar/go/1.19.1/libexec/src/os/file.go, line 316, in os.Open()
  Dataflow: "../../../../../../../../../../../../etc/passwd"
     Issue: Because there is untrusted data being used as part of the file path, it may be possible
            for an attacker to read sensitive data or write, update, or delete arbitrary files on the
            container's file system. The ability to write arbitrary files to the file system is also
            called Unrestricted or Arbitrary File Uploads.

Options:
- --config-path <path>
  Specifies the path or directory for the contrast_security.yaml file that the Assess CLI and the agent share.
  If not specified, the default paths are:
  - MacOS and Linux: /etc/contrast
  - Windows:%ProgramData%\Contrast\
  Alias: -c
- --file <filename>
  Specifies the path or directory for the vulnerability results file so Contrast can read it and display the results in the terminal. The file name is contrast-assess-{Date}.jsonl., where the date is in epoch milli-seconds, For example: contrast-assess-1691520302714.jsonl.
  Alias: -f
- --help
  Displays usage information for all assess command options.
- --no-watch [true|false]
  If set to true when using Assess with a Contrast agent, the CLI does not watch (or poll) Contrast for available vulnerabilities. The CLI retrieves the vulnerabilities only once for a specific buildNumber. The default setting is false.
  Alias: -n
- --output-path <path>
  Specifies the path or directory where you want the vulnerability results file located. The output file is in JSONL format. The file name is contrast-assess-{Date}.jsonl., where the date is in epoch milli-seconds, For example: contrast-assess-1691520302714.jsonl.
  Alias: -o
- --report-notes [true|false]
  If set to true, the access command displays vulnerabilities with a notes severity level. The default value is false which displays higher priority vulnerabilities.
  Alias: -r

sarif

Generates a SARIF file (contrast.sarif) that contains findings from Contrast Assess and Contrast SCA for a specific application ID.

Note

You can also use the sarif API to generate the SARIF file.

Usage:contrast sarif [option]

Example

contrast sarif 
--application-id 8f32952c-987c-4b9e-882c-a2b59a2fb4ee 
--severity high 
--metadata 'repo=TS,commit=commit-49-61670e50-1e9c-11ef-9109-059d9bfadadd,developer=Dev-49-61670e50-1e9c-11ef-9109-059d9bfadadd'

Options:
- --application-id <id>
  The ID of the application cataloged by Contrast.
- --severity [type]
  Set the severity level to filter the findings included in the SARIF output. Severity levels are critical, high, medium, low or, note.
  The severity level you specify is the minimum level that the report includes. For example, if you specify --severity high, the report includes findings with a severity of high and critical.
- --metadata
  Define a set of key=value pairs (that conforms to RFC 2253) for specifying user-defined metadata associated with the application.
- --tool-type
  Filters the type of findings included in the report. The valid types are SCA and ASSESS. For example, --tool-type ASSESS includes Assess findings only.
  If you don't specify this option, the report includes findings for both SCA and Assess.
Advanced options:
- --api-key
  Required for Enterprise users. Agent API key provided by Contrast. See agent keys to find your keys.
- --authorization
  Required for Enterprise users. Authorization header provided by Contrast.
- --code
  The application code the application should use in Contrast.
- --host
  Required for Enterprise users. The host name. For example, https://app.contrastsecurity.com.
- --organization-id
  Required for Enterprise users. The ID of your organization in Contrast. See agent keys to find the ID.
Proxy settings:
- --cacert
  Displays the path to the CaCert (certificate authority (CA) certificates) file.
- --cert
  Displays the path to the Cert (certificate) file.
- --cert-self-signed
  For Contrast on-premises (EOP) users with a local install, will bypass the SSL certificate and recognize a self-signed certificate.
- --key
  Displays the path to the Certificate Key.
- --proxy
  Allows for connection via 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>".

scan

Performs a security SAST scan.

Usage: contrast scan [option]
Example:
```
contrastuser@usercsa-C02GD0LUMD6TTY ~ % contrast scan
Searching for files to scan from from /Users/contrast/Documents/
Searched 3 directory levels & found...
- spring-petclinic-1.5.1.jar
- webgoat-server-8.2.2.jar
- webgoat.jar

Java Scan requires a .war or.jar file. Javascript Scan requires a .js or .zip file.
To start a Scan enter "contrast scan -f <path-to-file>"
contrastuser@usercsa-C02GD0LUMD6TTY ~ % contrast scan -f webgoat.jar
Found existing project...
Uploading...
Uploaded file successfully.
Contrast Scan started.

Here are your top priorities to fix

CRITICAL    sql-injection (2)
            1. org/owasp/webgoat/plugin/challenge6/Assigment6.java @43
            2. org/owasp/webgoat/plugin/challenge5/challenge6/Assigment5.java @38
```
- --branch
  Specifies a branch in a repository to be scanned. When specified, scan results are aggregated against results for the current branch and not the main project.
  Alias: -b
- --fail
  Fail a build based on the severity of the vulnerability found. Use with the --severity flag. For example, contrast scan --fail --severity high . Returns all failures if no severity level is specified. If a failure is detected the CLI will exit with code 2.
- --file
  Path of the file you want to scan. Contrast searches for a .jar, .war, .js or .zip file in the working directory if a file is not specified.
  Alias: -f
- --help
  Displays usage information for all scan command options.
- --host
  Required for Enterprise users. The host name. For example, https://app.contrastsecurity.com.
- --language
  Valid values are JAVA and JAVASCRIPT.
  Important
  This option is not valid if you are using the multi-language source code scan engine.
  Alias: -l
- --memory
  Memory override for the multi-language source code scan engine. The default memory setting is 2 GB.
- --name
  Contrast project name. If not specified, Contrast uses contrast.settings to identify the project or creates a project.
  Alias: -n
- -r
  Contrast resource group name. This option is required for host-based customers if role-based access control is turned on.
- --save
  Download the results to a Static Analysis Results Interchange Format (SARIF) file. The file is downloaded to the current working directory with a default name of results.sarif. You can view the file with any text editor.
  Alias: -s
- --severity
  A Contrast vulnerability severity level that returns a build failure status code that you can use to gate builds in pipelines.\
  Valid values are: critical, high, medium, low, and note.
  The specified value is the minimum level of severity that returns a build failure status code. For example, if you specify --severity high, a finding of that severity or higher returns a build failure status code.
  Use with the --fail flag. For example, contrast scan --fail --severity high.
- --timeout
  Time in seconds to wait for the scan to complete. Default value is 300 seconds.
  Alias: -t
Options:
Advanced options:
- --api-key
  Required for Enterprise users. Agent API key provided by Contrast. See agent keys to find your keys
- --authorization
  Required for Enterprise users. Authorization header provided by Contrast.
- --ff
  Fire and forget. Do not wait for the result of the scan.
- --host
  Required for Enterprise users. The host name. For example, https://app.contrastsecurity.com.
- --label
  Adds a label to the scan. Defaults to Started by CLI tool at [current date].
- --organization-id
  Required for Enterprise users. The ID of your organization in Contrast. See agent keys to find the ID.
- --project-id
  The ID associated with a scan project. To find the ID, select a scan project in Contrast and locate the last number in the URL.
Proxy settings:
- --cacert
  Displays the path to the CaCert (certificate authority (CA) certificates) file.
- --cert
  Displays the path to the Cert (certificate) file.
- --cert-self-signed
  For Contrast on-premises (EOP) users with a local install, will bypass the SSL certificate and recognize a self-signed certificate.
- --key
  Displays the path to the Certificate Key.
- --proxy
  Allows for connection via 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>".

lambda

Name of AWS lambda function to scan.

Usage: contrast lambda --function-name <function> [options]
Alias: -f
Options:
- --endpoint-url
  AWS Endpoint override. Similar to AWS CLI.
  Alias: -e
- --help
  Displays usage information for all lambda command options.
- --region
  Region override. Defaults to AWS_DEFAULT_REGION. Similar to AWS CLI.
  Alias: -r
- --profile
  AWS configuration profile override. Similar to AWS CLI.
  Alias: -p
- --json
  Return response in JSON (versus default human-readable format).
  Alias: -j
- -–verbose
  Returns extended information to the terminal.
  Alias: -v
- --list-functions
  Lists all available lambda functions to scan.
- -–help
  Displays usage guide.
  Alias: -h
Proxy settings:
- --cacert
  Displays the path to the CaCert (certificate authority (CA) certificates) file.
- --cert
  Displays the path to the Cert (certificate) file.
- --cert-self-signed
  For Contrast on-premises (EOP) users with a local install, will bypass the SSL certificate and recognize a self-signed certificate.
- --key
  Displays the path to the Certificate Key.
- --proxy
  Allows for connection via 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>".

Help and learn

help

Displays usage guide. To list detailed help for any CLI command, add the -h or --help flag to the command.

Usage: contrast help

Example:

contrastuser@usercsa-C02GD0LUMD6TTY ~ % contrast help
Contrast CLI @ v1.0.24
Contrast Scan CLI
Pre-requisites  Java, Javascript and .NET supported                                             
To scan a Java project you will need a .jar or .war file for analysis           
To scan a Javascript project you will need a single .js or a .zip of            
multiple .js files                                                              
To scan a .NET c# webforms project you will need a .exe or a .zip file for      
analysis                                                                                                                                                                                                                                        

The file argument is optional. If no file is given, Contrast will search for    
a .jar, .war, .exe or .zip file in the working directory.                                                                                                       

Submitted files are encrypted during upload and deleted in 24 hours.          
Scan Options  
-l, --language string   (optional): Valid values are JAVA, JAVASCRIPT and DOTNET
--label string          (optional): adds a label to the scan - defaults to 'Started by CLI tool at                               
current date'                                                                   
-n, --name string       (optional): Contrast project name. If not specified, Contrast uses                                      
contrast.settings to identify the project or creates a project.                 
-f, --file string       (optional): Path of the file you want to scan. If no file is specified,                                 
Contrast searches for a .jar, .war, .exe or .zip file in the working                                    
directory.                                                                      
-t, --timeout number    (optional): Time in seconds to wait for scan to complete. Default value is                              
300 seconds.                                                                    
--fail                  (optional):  Use with contrast scan or contrast audit. Detects failures based                           
on the severity level specified with the --severity command. For example,                               
"contrast scan --fail --severity high". Returns all failures if no severity level is specified.                                                             
--severity type         (optional): Use with "contrast scan --fail --severity high" or "contrast                                
audit --fail --severity high". Set the severity level to detect                                         
vulnerabilities or dependencies. Severity levels are critical, high, medium,                            
low or note.                                                                    
-s, --save string       (optional): Saves the Scan Results SARIF to file. 
Advanced  
-o, --organization-id string   (required for Contrast Enterprise): The ID of your organization as provided
                               by Contrast UI
--api-key string               (required for Contrast Enterprise): An agent API key as provided by Contrast                                   
UI                                                                              
--authorization string         (required for Contrast Enterprise): An authorization header as provided by                                     
Contrast UI                                                                     
--host string                  (required for Contrast Enterprise): host name e.g.                                                             
https://app.contrastsecurity.com                                                
--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: "https://username:password@<host>:<port>".                  
--key string                   (optional): Path to the Certificate Key                                         
--cacert string                (optional): Path to the CaCert file                                             
--cert string                  (optional): Path to the Cert file                                               
--cert-self-signed             (optional):For EOP users with a local Teamserver install, this will bypass                                     
the SSL certificate and recognise a self signed certificate.                    
-p, --project-id string        (optional): 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.                                 
-l, --language string          (optional): Valid values are JAVA, JAVASCRIPT and DOTNET                        
--ff                           (optional): Fire and forget. Do not wait for the result of the scan.            
--label string                 (optional):adds a label to the scan - defaults to 'Started by CLI tool at                                      
current date'                                                                 

Need More Help? NEW users  
Check out: https://support.contrastsecurity.com                             
Learn more at: https://www.contrastsecurity.com/developer                   
Join the discussion: https://www.contrastsecurity.com/developer/community 

Existing Contrast Licensed user?  
Read our docs: https://docs.contrastsecurity.com/en/run-contrast-cli.html    
Want to UP your game? type 'contrast learn'                                  
💰 Advance your security knowledge and become an All-star coder ⭐  with         
Contrast Secure Code Learning Hub. 😺

Alias: -h

learn

Launch Contrast’s Secure Code Learning Hub.

Usage: contrast learn

Example:

contrastuser@usercsa-C02GD0LUMD6TTY ~ % contrast learn
Opening Contrast’s Secure Code Learning Hub...
If the page does not open you can open it directly via https://www.contrastsecurity.com/developer/learn

In this section:

Contrast CLI commands

Authentication/connectivity

auth

config

version

Main functions

audit

assess

sarif

Note

scan

Important

lambda

Help and learn

help

learn

Search results