Contrast Scan local engine

The Contrast Scan local engine lets you scan your application using a Java JAR file instead of the Contrast CLI or the Contrast web interface. When a scan completes successfully, the Scan local engine uploads the results to the Contrast platform where you can view them. The uploaded files include:

Scan results in Static Analysis Results Format (SARIF) in a JSON file.
Output from the scan in a LOG file.

This method of scanning is useful if you want to scan files locally without uploading them to the Contrast platform.

Supported platforms

The Scan local engine is supported for Linux systems.
Multi-language Scan local engine: Java 17 and later is supported.
Binary Java scan engine: Java 17 only.

Proxy server settings for local scans

For security purposes, you might want to use a proxy server for communication between the local scan engine and the Contrast platform. Use the following environment variables to enable a proxy server when you run a local scan:

Variable	Description
CONTRAST__API__PROXY__ENABLE	Enables proxy settings.
CONTRAST__API__PROXY__URL	Required. The URL for the proxy server (for example, `http://host:port`)
CONTRAST__API__PROXY__TYPE	Required. The proxy server type (for example, BASIC)
CONTRAST__API__PROXY__USERNAME	Optional. Username for the proxy server
CONTRAST__API__PROXY__PASSWORD	Optional. Password for the proxy server

Package preparation for local scans

Consider these best practices when you prepare to run a local scan:

JAR or WAR files: Specify the binary file to be scanned.
Source code scanning: Place the source code you want to scan in a folder and not in a ZIP file.
There is no limit to the size of this folder for the local scanner. However some large source code repos may require more memory or a longer time to execute. Use the memory and timeout options to manage these situations.
Multi-JAR or WAR scanning: Specify a ZIP file that contains multiple JAR or WAR files. Place these files in the root of the ZIP file.
There is no limit to the size of the files in the ZIP file.

Use a consistent file structure

Using a consistent file structure for each scan is crucial to preventing duplicate vulnerability findings. After an initial scan, if you need to change the file structure for the files you are scanning, create a new scan project for those files instead of using an existing one. If you are planning to scan multiple branches without using the Contrast Scan Analyze GitHub action, create a separate scan project for your personal branch.

If you use an existing scan project, change the file structure, and then run a scan, Contrast sets the original vulnerability status to Remediated and reports a new, duplicate vulnerability. The new finding is linked to the same file and line number but shows the new path.

Consistent file structure affects files in ZIP files and files not in a ZIP file.

Example 1: Changing ZIP file name

In this example, we rename a ZIP file but maintain the file structure in the ZIP file. This change doesn't result in Contrast reporting duplicate vulnerabilities:

scan.zip
   |
   |-- source_files
  
changed to
  
contrastscan.zip
      |
      |-- source_files

In this case, the ZIP file name isn't part of the scan path, so changing it has no affect on the scan findings.

Example 2: Changing file structure in a ZIP file

In this example, we rename the ZIP file and also change the file structure by adding a new directory. This change causes Contrast to report duplicate vulnerabilities.

scan.zip
   |
   |-- source_files
  
changed to
  
contrastscan.zip
      |
      |-- contrastscan
              |
              |-- source files

In this case, changing the file structure within the ZIP file causes duplicate findings. To avoid this issue, create a new scan project and use it for future scans.

Example 3: Changing file structure in directories

In this example, we change the file structure by adding a new directory. This change causes Contrast to report duplicate vulnerabilities.

scan
   |
   |-- source_files
  
changed to
  
contrastscan
      |
      |-- contrastscan
              |
              |-- source files

In this case, changing the directory name and the file structure within the directory causes duplicate findings. To avoid this issue, create a new scan project and use it for future scans.

Scan process

To use the Scan local engine:

Download the Scan local engine application or contact Contrast Support to get the latest local engine application.
Decide if you want to use a proxy server for uploading results.
Run the scan on a local system.
View results in the Contrast web interface.

In this section: