Skip to main content

Running Scans Using Checkmarx SCA Resolver

Prerequisites

  • Download and install the latest version of Checkmarx SCA Resolver for your OS, see Checkmarx SCA Resolver Download.

    Notice

    The Configuration.yml file, which is included in the zip archive, is a mandatory part of the installation and must be placed in the same folder as the ScaResolver binary.

    The ServerUrl, AuthenticationServerUrl and ScaAppUrl in the .yml file are set by default for the US environment. If you are using the EU environment, then you must change these to the appropriate values for the EU as specified here.

  • Checkmarx SCA Resolver requires dependency resolution utilities to be installed, and the project to be in a buildable state. For a list of requirements, see Package Managers Support in SCA Resolver.

  • You need to have the following info about your Checkmarx SCA account: account name, username and password.

Notice

If you authenticate via a SAML provider, then providing user credentials is not necessary. See SAML Authentication for Checkmarx SCA Resolver.

Warning

For authentication in Checkmarx SCA Resolver you need to use a Checkmarx SCA user account (local user or SSO integration) and not an account that was added via Master Access Control.

Running Scans Using the Checkmarx SCA Resolver

You can use the Resolver to scan an existing Project or to create a new Project. If you are scanning an existing Project, then the Project settings that you configured in the SCA web portal (e.g., teams assignment, notifications, Python version) are automatically applied to the scan. If you are creating a new Project in Resolver, then you can use the optional configuration arguments to configure these settings, see Checkmarx SCA Resolver Configuration Arguments.

Notice

If you would like to use the Policy feature to cause builds to break whenever the specified threshold of security threats is detected, you need to first create the Project in the web portal and assign it to a Policy (see Policy Management). Then, you can run the Project using Resolver.

Notice

If you would like to run scans using the Exploitable Path feature, use the procedure described in Running Exploitable Path Scans Using Resolver.

Checkmarx SCA Resolver Modes

Checkmarx SCA Resolver (version 1.5.4+) can be run either in Online mode or in Offline mode. When online mode is used (default), the resolved results are automatically sent to Checkmarx SCA Cloud for scanning. When offline mode is used, the resolved results are saved locally. You can then use Upload mode at a later time to send the results to Checkmarx SCA Cloud for scanning.

Notice

In order to run Checkmarx SCA Resolver in Online or Upload mode you need to provide authentication credentials. The procedures below describe the standard authentication method, which uses the username and password for authentication. Alternatively, if you have integrated your Checkmarx SCA account with a SAML provider, you can authenticate for Checkmarx SCA Resolver via your SAML provider, see SAML Authentication for Checkmarx SCA Resolver.

Running a Scan - Online Mode

To run a new scan using the Checkmarx SCA Resolver in Online mode:

  1. If you would like to view the list of available arguments, in the CLI, run ScaResolver.exe (Windows) or ScaResolver (Linux) with the -h flag, as shown:

    ./ScaResolver -h

    The available arguments are displayed.

  2. To start a scan, run ScaResolver.exe (Windows) or ScaResolver (Linux) with the following mandatory arguments:

    -s : path to the folder to scan

    Notice

    This must be the path to a local folder that contains the source code, not to a zip archive or a code repository.

    -n : to scan an existing Project, enter the name of the Project. OR,

    to create a new Project, enter a new name to assign to the Project

    -a : your Checkmarx SCA account name

    -u : your username

    -p : your password

    The following example shows a run command using the mandatory arguments:

    Notice

    You can add additional arguments to specify the desired scan configuration, see Checkmarx SCA Resolver Configuration Arguments. For example, the -e argument enables you to exclude specific folder and file patterns, see examples in the “Optional Arguments” section of Checkmarx SCA Resolver Configuration Arguments.

    After a successful completion, a risk report summary is displayed in the CLI.

    The following example shows a risk report summary:

    ################### Risk report summary ###################
Direct dependencies :                   10 (28 total)

High severity vulnerabilities:          11
Medium severity vulnerabilities:        1
Low severity vulnerabilities:           0
###########################################################

3. If you used the --report-type flag in the run command, then you can open the Risk Report file to view the results. Otherwise, you can view the results in the Checkmarx SCA web portal by searching for the Project by the name designated in the -n argument.

Running a Scan - Offline Mode

To run a new scan using the Checkmarx SCA Resolver in Offline mode:

  1. If you would like to view the list of available arguments, in the CLI, run ScaResolver.exe (Windows) or ScaResolver (Linux) with the -h flag, as shown:

    ./ScaResolver -h

    The available arguments are displayed.

  2. To start a scan, run ScaResolver.exe offline (Windows) or ScaResolver offline (Linux) with the following mandatory arguments:

    -s : path to the folder to scan

    Notice

    This must be the path to a local folder that contains the source code, not to a zip archive or a code repository.

    -n : to scan an existing Project, enter the name of the Project. OR,

    to create a new Project, enter a new name to assign to the Project

    -r : path to directory/file where results will be stored for future upload

    Notice

    When running a container scan in Offline mode, it is also mandatory to use --containers-result-path to specify the container results output location.

    The following example shows an Offline run command using the mandatory arguments:

    Notice

    You can add additional arguments to specify the desired scan configuration, see SCA Resolver Configuration Arguments. For example, the -e argument enables you to exclude specific folder and file patterns, see examples in the “Optional Arguments” section of SCA Resolver Configuration Arguments.

  3. When you are ready to run the scan, run ScaResolver.exe upload (Windows) or ScaResolver upload (Linux) with the following mandatory arguments:

    -n : enter the name of the Project (same as used for Offline mode)

    -a : your Checkmarx SCA account name

    -u : your username

    -p : your password

    -r : path to the file where results from the Offline mode were stored

    Notice

    When running a container scan in Offline mode, it is also mandatory to use --containers-result-path to refer to the location where the container results were stored.

    The following example shows an Upload run command using the mandatory arguments:

    Notice

    You can add additional arguments to specify the desired scan configuration, see Checkmarx SCA Resolver Configuration Arguments.

    After a successful completion, a risk report summary is displayed in the CLI.

    The following example shows a risk report summary:

    ################### Risk report summary ###################
Direct dependencies :                   10 (28 total)

High severity vulnerabilities:          11
Medium severity vulnerabilities:        1
Low severity vulnerabilities:           0
###########################################################

  4. If you used the --report-type flag in the Upload run command, then you can open the Risk Report file to view the results. Otherwise, you can view the results in the Checkmarx SCA web portal by searching for the Project by the name designated in the -n argument.

Reports

Checkmarx SCA generates two types of reports:

  • Risk Report - a comprehensive report which shows aggregated statistics for your Project as well as detailed info about the risks that were identified by the scan.

  • Software Bill of Materials (SBOM) - a report that gives a complete list of all components used by the program, including direct and transitive dependencies. The report follows the CycloneDX v1.3 format, which includes info for each component such as name, supplier name, version, hashes and other unique identifiers etc. Checkmarx SCA supplements this data with additional “property” fields that contain info about the risks associated with each package.

    Warning

    There is an alternative method for generating SBOM reports using the Export Service API. The Export Service API generates SBOMs that are more compliant with SBOM formatting specifications. Export Service also supports generating SBOMs in SPDX format.

You can generate a Risk Report in json, xml, csv or pdf format when running a scan using Checkmarx SCA Resolver (version 1.5.4+).

Risk Report Example:

You can generate an SBOM Report in json or xml format when running a scan using Checkmarx SCA Resolver (version 1.5.52+).

SBOM Report Example:

For more info about the arguments used for exporting reports, see the “Report Arguments” section of Checkmarx SCA Resolver Configuration Arguments.

Notice

In addition, you can download Risk Reports and SBOM Reports for any scans that have been run in your account via the web portal, see Scan Reports. You can also view detailed scan results in the web browser, see Viewing Results.

Container Scans

Warning

This article explains the functionality of scanning containers in the SCA standalone solution. Checkmarx One users who are using the new Container Securtiy scanner should refer to the documentation here.

In addition to scanning the packages in your source code itself, Checkmarx SCA also scans the Dockerfiles in your project to identify the container images used in your project. Checkmarx SCA extracts all layers of each public base image located in the Dockerfile, and identifies the packages used by each layer.

For scans run via SCA Resolver, in addition to scanning the Dockerfile itself, you can also scan the image that is created from the Dockerfile, using the Syft open source tool. This enables greater visibility into all packages used in the image for all languages supported by SCA as well as many non-supported languages (e.g., Dart, Haskell, Swift etc.). In addition, you can use SCA Resolver to submit specific images from public or private registries for analysis by SCA using the Syft tool.

For more info about container scans, see Container Scans.

Prerequisites

  • To run Resolver scans, it is required to have Syft version 0.83.1 installed on the machine where you are running Resolver. Download and install Syft from https://github.com/anchore/syft/releases/tag/v0.83.1.

  • If you would like to scan images that are not in your local Dockerfile, you need to have the name and tag for each of the images.

  • If you are using a private repo, you need to be authenticated for your registry.

    Notice

    Authentication can be done via Docker or Podman.

    Alternatively, you can use the syft login command, as follows: syft login <private_registry_domain> -u <your_username> -p <your_password>

    Before running the scan, it is recommended to verify that you are able to access the image on your local machine.

Running a Container Scan on your Dockerfile

  • Run an SCA Resolver scan, using the --scan-containers flag in the scan command.

Notice

When running a container scan in Offline mode, you must use the --containers-result-path flag to specify the container results output location. Then, when running Upload, you need to use the same flag to refer to the file location.

Example of scanning the project's Dockerfile:

The following example shows a command to run a container scan on the Dockerfile in your project.

Running a Container Scan on a Specific Image

  1. Add the --scan-containers flag to the SCA Resolver scan command.

  2. If you want to scan only specific images (not an entire project), do the following:

    1. Create a "dummy" folder in your project (for use in the -s parameter) and give it a name that indicates that it is used for scanning images, e.g., scan_ecr_image.

    2. In the Resolver scan command, for the -s parameter give the path to the "dummy" folder that you created, e.g., /Users/DemoUser/scan_ecr_image.

  3. Add the --images flag followed by a comma separated list of images. Specify each image using the following syntax {image_name}:{image_tag}.

Example of scanning a specific image:

The following example shows a command to run a container scan on specific images.

For more info about container scans, see Container Scans.

Proxy Scans

You can use a proxy server to make internet requests for SCA Resolver. You can configure proxies for HTTP and HTTPS and you can pass the authentication credentials.

Running Scans via Proxy

  1. To scan a project using a proxy server, add the --proxies flag to the scan command followed by comma separated host urls.

  2. If you you need to pass credentials, add them using the following syntax @<username>:<password>.

Proxy Scan Example:

The following example shows a command to run a scan using proxy HTTP and HTTPS servers. This command also passes the the authentication credentials for the HTTP server.

Exit Codes

The table below shows the possible exit codes that are received from Checkmarx SCA Resolver and explains their meaning.

Code

Name

Description

0

Success

The request ran successfully.

3

AuthenticationFailure

Request failed because unable to authenticate the user account.

4

InternalError

Request failed because of an internal error in the system.

5

ParsingError

Request failed because of an invalid command (e.g., invalid flags or configurations).

6

ExceededVulnerabilitySeverityThreshold

The results indicate that vulnerabilities were identified that exceed the threshold set for the scan (using the --severity_threshold flag in the run command). See Optional Arguments.

7

InsufficientPermissions

Request failed because the user credentials submitted don’t have the required permissions for this action.

8

BreakBuild

The scan results indicate that the build should be broken, based on a risk Policy configured for this Project. See Policy Management.

9

PackageManagerError

The scan failed because resolution failed for one or more of the manifest files.

Tip

This code is only returned if the scan was run with the flag --break-on-manifest-failure.

10

ConfigurationNotSupported

The scan failed because of an unsupported configuration.

Logging

Logs are printed to the standard output as well as to the “logs” directory, located where you run the Resolver.

Each run creates a log file with an appropriate timestamp.

The location of the log directory is determined by the LogsDirectory parameter in the config file.

By default, log verbosity is information level and higher. Use --log_level Debug to receive more output, or --log_level Error to receive only errors.

For more information, see SCA Resolver Configuration Arguments.

Troubleshooting

Some issues have occurred when attempting to run the Resolver on clean Ubuntu and Debian systems. This is mainly because the .NET CORE packed executable relies on some basic packages. If the executable fails to run, see SCA Resolver Download.

Contacting Support

With every support request, please verify the version of the Resolver used by running ScaResolver.exe (Windows) or ScaResolver (Linux) with the --version flag, as shown:

./ScaResolver --version

Notice

This command works only from version 1.2.3. If the command is not available, please let technical support know.

Every scan has a scan ID. When a scan is completed, the following line is displayed:

Information    Program "Scan Id: ce0ce194-39a0-4a00-9e09-7bad8c225dd2"

Please provide this Scan ID with all support calls and requests.

Troubleshooting Dependency Resolution

Checkmarx SCA Resolver requires dependency resolution utilities to be installed, and the project to be in a buildable state. Some errors may occur during dependency resolution.

For a list of requirements, see Package Managers Support in SCA Resolver.

If the Resolver run fails, the output displays error messages, as shown in the following NPM failure:

2020-06-17T20:09:22+03:00 Error  NpmDependencyResolver "Failed to create package lock file" {ResolvingModuleType=Npm, Command="i --package-lock-only", ProcessErrorResponse="npm ERR! code ETARGET
npm ERR! notarget No matching version found for unknown@1.2.3
npm ERR! notarget In most cases you or one of your dependencies are requesting
npm ERR! notarget a package version that doesn't exist.
npm ERR! notarget 
npm ERR! notarget It was specified as a dependency of 'artifactory'
npm ERR! notarget 

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\\Users\\test\\AppData\\Roaming\\npm-cache\\_logs\\2020-06-17T17_09_22_150Z-debug.log", ProcessInfoLog=""} { ResolvingModuleType: Npm, Command: "i --package-lock-only", ProcessErrorResponse: "npm ERR! code ETARGET
npm ERR! notarget No matching version found for unknown@1.2.3
npm ERR! notarget In most cases you or one of your dependencies are requesting
npm ERR! notarget a package version that doesn't exist.
npm ERR! notarget
npm ERR! notarget It was specified as a dependency of 'artifactory'
npm ERR! notarget

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\test\AppData\Roaming\npm-cache\_logs\2020-06-17T17_09_22_150Z-debug.log", ProcessInfoLog: "" }
In this section: