Run local scan

The Contrast Scan local engine is available as a Java JAR file. It requires the location of a build artifact so it can process the scan.

Before you begin

Identify where the build artifacts that you want to scan are located.
Determine where you want to store scan results on your local system.
If you don't specify a path for output results, the Scan local engine writes results to the current working directory in a file named results.sarif.
Ensure that this software is installed on your system:
- Java 11
- If you are scanning JavaScript project files, Semgrep App version 0.114.0
Internet access exists to let the Scan local engine upload scan results and scanner output to Contrast.
Verify that you have 1 CPU available (the Contrast Scan local engine is single threaded) and have 12 GB of RAM free.
Ensure the Scan local engine has read and write permissions for the directory where it runs or for the specified output directory.

Important

Make sure that the path for the files you want to scan does not include spaces.

Steps

Log in to the Contrast web interface.
Under the user menu, select User settings.
In Profile, under Your keys, get the following information:
- Organization ID
- Your API key
- Service key
- Contrast URL
Configure the environment variables that let the local scanner communicate with Contrast:
Note
If you want to use a proxy server for communication between the local scan engine and the Contrast platform, include the proxy server environment variables.
```
export CONTRAST__API__URL=<URL>
export CONTRAST__API__USER_NAME=<Username>
export CONTRAST__API__API_KEY=<APIKey>
export CONTRAST__API__SERVICE_KEY=<ServiceKey>
export CONTRAST__API__ORGANIZATION=<OrgId>
export LOCAL_ARTIFACT_LOCATION=<LocalArtifactLocation>
export LOCAL_OUTPUT_LOCATION=<LocalOutputLocation>
```
- Replace <URL> with the address of the Contrast installation where you want to report scan results. The URL should include Contrast/api/sast at the end of the URL. For example:
```
export CONTRAST__API__URL=https://app.contrastsecurity.com/Contrast/api/sast
```
- Replace <Username> with your Contrast user account (in most cases your login ID).
- Replace <APIKey> with the Contrast API key.
- Replace <ServiceKey> with the Contrast service key.
- Replace <OrgID> with the Contrast organization ID.
- Replace <LocalArtifactLocation> with the path for the JAR or WAR files for Java scans. For JavaScript scans, specify the folder containing the source code.
  Optional: You can specify the path in the command instead of using a variable.
- Replace <LocalOutputLocation> with the path on the local system where you want to store results files.
  Optional You can specify the path in the command instead of using a variable.
Start the scan with a command similar to this one:
```
java -jar sast-local-scan-runner.jar <ScanArtifact> --project- \
name <ProjectName> --label <LabelName>
```
- Replace <ScanArtifact> with the path of the JAR, WAR, or ZIP file that you want to scan. You can also specify folders.
- Replace <ProjectName> with a name for a project. For example: "my project name".
- Replace <LabelName> with a label for the scan. For example, you could specify a build number as: "build:1.0.1".
Wait several minutes after the scan completes to view results in the Contrast web application. Results are not immediately viewable due to upload and processing times.

Scan branches in repositories

To scan branches in a repository (for example, for a pull request (PR), use the --branch option when you run the scan. For example:

java -jar sast-local-scan-runner-1.0.10.jar --project-name <ProjectName> --label <LabelName> --branch <BranchName> <ScanArtifact>

Scans of branches return a pass or fail status in the GitHub action. Currently, scan results are not uploaded to the Contrast web interface.

Command options

Use any of these command options:

Option	Description
`-o, --output-results`	Specifies the location for output results. If you don't specify a location, the local scanner writes the results to the current working directory.
`-V, --version`	Prints version information
`-b, --branch`	Specifies a branch in a repository to be scanned. When specified, scan results are aggregated against results for the current branch, without affecting scans for a main branch.
`--fail`	Fail a build based on the severity of the vulnerability found. Use with the -`-severity` option. For example, `contrast scan --fail --severity high` . Returns all failures if no severity level is specified. If a failure is detected, the CLI exits with code 2.
`--label <label>`	A label for the current scan.
`--memory <value>`	Lets you override the default memory usage of 2 GB. This option is only available for the multi-language source code scan engine.
`--project-name <ProjectName>`	The name of a scan project. If you specify a project name that already exists, the Scan local engine adds the scan to that project. Otherwise, it creates a new project with the specified name. If the project name includes spaces, enclose the name in double quotes ("). For example: "My Scan Project". This option is required if you don't use a project ID.
`--project-ID`	The ID for an existing project. This option is required if you don't use a project name.
`--severity <SeverityLevel>`	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` option.
`-r <ResourceGroupName>`	The name of the resource group where you want to add the project. If you are a hosted customer and role-based access control is turned on, this option is required.
`--timeout <minutes>`	Lets you control the maximum time the source code scan engine scans the provided code. Specify a value in minutes. The maximum value is 1440 minutes (24 hours). This option is only available for the Scan local engine. This option applies to each language found in the code to be scanned. For example if you set this to 120 minutes and your repo contains four languages, there is a potential for the scan to run for hours (4 languages x 120 minutes each).

Exit codes

The Scan local engine returns these exit codes when a scan completes:

Exit code	Description
0	Scan completed successfully and uploaded results to Contrast
1	Input validation error
2	Error connecting to Contrast API server
3	Contrast API error returned
4	Scan local engine returned an error, details are in the log files
5	Unexpected error occurred, details are in the log files

In this section: