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.

  • 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 (BETA) feature, use the procedure described in Running Exploitable Path Scans (BETA) 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

    -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

    -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

    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

    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.

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.

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.

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 -v flag, as shown:

./ScaResolver -v

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 [email protected]
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 [email protected]
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: "" }