Running SCS Scans

SCS scans can be run on your Checkmarx One projects via web application, CLI or REST API.

Running a Scan via the Web Application (UI)

When you run a scan on a project, a dialog opens enabling you to select which scanners will run. To run Secret Detection and Repository Health (OSSF Scorecard) scans, ensure that they are toggled on (default). OSSF Scorecard is supported only when scanning from a repo URL (as opposed to Secret Detection which is supported for scanning either a zip archive or a repo URL).

Warning

OSSF Scorecard isn't shown when scanning from a zip file, because it isn't supported.

Warning

Running OSSF Scorecard scans from the web application (UI) is currently supported only for private repos. To run OSSF Scorecard scans on public repos you must initiate the scan via CLI or API, as described below.

Running a Scan via the Checkmarx One CLI Tool

When running a scan via the CLI tool, you can now specify Software Supply Chain Security (SCS) as one of the scan engines to run. When running the Scorecard scanner, it is mandatory to submit the repo url and an access token with at least read permissions for that repo.

Prepare the command to run a scan, using the scan create command and specifying the project name, branch and zip file location or repository URL using the --project-name , --branch and -s flags. See scan create
```
./cx scan create --project-name <Project name> --branch <branch name> -s <path to zip archive>
```
By default, all licensed scanners are run, including SCS (assuming that all mandatory SCS parameters are specified). If you are using the --scan-types flag to specify the scanners that run, you need to explicitly include the scs scanner, e.g., --scan-types sast,scs.
By default, when scs is included, both Secret Detection and OSSF Scorecard are run. If you would like to run only one of these scanners, add the --scs-engines flag and specify the engine that you want to run: secret-detection, or scorecard.
When running the scorecard scanner, it is mandatory to add the following flags:
- Specify the URL of the repo that you are scanning.
  Caution
  Even when -s specifies a repo url, you still need to use this flag to submit the URL for the SCS scanner.
- --scs-repo-token <string> - specifying a token with read permission on the specified repo.
  Notice
  This flag is required for both private and public repos.
If you would like to generate a scan report (optional), add the --report-format flag, specifying the desired format (e.g., --report-format json). For more information about scan reports, see here.

Run the scan command.

The following is an example of a command to run SAST on a zip archive and run Scorecard on the project's repo.

user@laptop:~/ast-cli$ ./cx scan create -s . --branch master --project-name Test111 --scan-types sast,scs --scs-engines scorecard --scs-repo-url https://github.com/juice-shop/juice-shop --scs-repo-token <TOKEN> --report-format json

Running a Scan via REST API

When running a scan using POST /scans, you can now specify Software Supply Chain Security (SCS) as one of the scan engines to run. OSSF Scorecard is supported only when scanning from a repo URL. (Secret Detection is supported for scanning either a zip archive or a repo URL.)

When running POST /scans, in the "config" object specify "microengines" in the scanner "type" section and submit the "value" section indicating which of the scs scan engines to run: "scorecard" and/or "2ms".

Caution

There is no need to specify the repo url since that info is provided as part of the general "handler" object.

The following is an example of the body for running an SCS scan using only the OSSF Scorecard scanner.

{"type":"git","handler":{"repoUrl":"https://github.com/k-tamura/easybuggy","branch":"master"},"project":{"id":"2be13e9a-88ea-431e-a276-010cb8f139b0","tags":{}},"config":[{"type":"microengines","value":{"scorecard":"true","2ms":"false"}}],"tags":{}}

Code Repository Integrations

You can create a code repository integration that runs SCS scans automatically whenever a pull request or push event occurs in your repository.

To set up a code repository integration:

In the web application Workspace , click on + New and select New Project - Code Repository Integration.
Fill in the integration wizard, following the relevant procedure for your SCM, as described in Code Repository Integrations.
In the Repositories Settings (step 5), ensure that Scan Trigger: Push, Pull request is turned on (default).
Then, scroll down and and ensure that the relevant SCS scanners (Secret Detection and/or OSSF Scorecard are turned on.