Skip to main content

Run local scan

The Contrast Scan local engine is available as a Docker container or 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.

  • If you plan to use the Java JAR version of the Scan local engine, 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 12 GB of RAM.

  • 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

  1. Log in to the Contrast web interface.

  2. Under the user menu, select User settings.

  3. In Profile, under Your keys, get the following information:

    • Organization ID

    • Your API key

    • Service key

    • Contrast URL

    Image shows the user settings with arrows indicating the information you need
  4. 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.

  5. Start the scan:

    • If you are using the Docker version of the Scan local engine, start the scan with a command similar to this one:

      docker run -v $LOCAL_ARTIFACT_LOCATION:/app/artifacts \
          -v $LOCAL_OUTPUT_LOCATION:/app/results \
          -e CONTRAST__API__URL=${CONTRAST__API__URL} \
          -e CONTRAST__API__USER_NAME=${CONTRAST__API__USER_NAME} \
          -e CONTRAST__API__API_KEY=${CONTRAST__API__API_KEY}  \
          -e CONTRAST__API__SERVICE_KEY=${CONTRAST__API__SERVICE_KEY}  \
          -e CONTRAST__API__ORGANIZATION=${CONTRAST__API__ORGANIZATION} \
          ghcr.io/contrast-security-inc/contrast-sast-scanner-java:latest \
          --project-name "<ProjectName>-${CONTRAST__API__ORGANIZATION}" \
          --label "<LabelName>" \
          -r "<ResourceGroupName">\
          /app/artifacts/<FileName> \
          -o $LOCAL_TARGET_OUTPUT_LOCATION/results.sarif 
      
      • Replace <ProjectName> with the name of a scan project.

      • Replace <LabelName> with a label for the scan. For example, you could specify a build number as: "build:1.0.1".

      • Replace <ResourceGroupName> with the name of the resource group where you want to add the project.

      • Replace <FileName> with the name of the file that you want to scan. This file must reside in the directory that you specified for the $LOCAL_ARTIFACT_LOCATION.

    • If you are using the Java JAR file to run the Scan local engine, 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".

  6. 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.

Command options

Use any of these command options with the Docker container or the Java JAR file:

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

--memory <value>

Lets you override the default memory usage of 2 GB 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.

-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.

--label <label>

A label for the current scan.

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