Skip to main content

scan

The scan command is used to run and manage scans in Checkmarx One.

Usage

./cx scan [command] [flags]

Note

--scan-timeout flag can't be used together with the --async flag.

When a scan is initiated in asynchronous mode using --async flag, Checkmarx One CLI does not wait for the result and completes the scan.

Scan Commands

scan can be used with the following commands:

scan cancel

The cancel command is used to cancel one or more running scans in Checkmarx One.

Usage

./cx scan cancel --scan-id <scan ID> [flags]

Flags

Glossary
--help, -h

Help for the cancel command.

--scan-id <string> (Required)

One or more comma separated scan IDs to cancel.

For example: <scan-id>, <scan-id>, ...

Workflow Examples

Retrieving all the scan ID’s statuses
Cancel a running scan
user@laptop:/AST$ ./cx.exe scan cancel --scan-id 29a2b1e6-87c9-43b9-9d38-2d8165b390e1
Canceling several running scans

You can specify several comma separated scan ids in order to cancel multiple scans.

user@laptop:/AST$ ./cx.exe scan cancel --scan-id <scan_id1>,<scan_id2>

scan create

The scan create command enables users to create and run new scans in Checkmarx One.

Usage

./cx scan create [flags]

Scanning Source Code

The scan create command can be used to scan source code using the following methods:

  • A compressed .zip archive

  • A repository URL

  • A local directory

    Note

    When you scan from a local directory, the CLI compresses the folder into a .zip archive and stores it in your system's temporary storage location until it is uploaded to Checkmarx One.

Scan Process

When a scan is run using multiple scanners, all scanners run in parallel.

When multiple scans are run in your account, the number of concurrent scans is specified in your account's license. This info is available under Account Settings > License > License Plan Summary. When the limit is exceeded, the scans are added to a queue which runs on a "first in first out" basis.

Notice

When you scan a folder that contains files with unsupported file formats, those files aren't scanned.

However, you can include those files in the scan by using the --file-include flag.

For more details see Scan with Inclusion of unsupported file formats

The following is a list of the supported extensions and file names that are included by default in scans.

*.javasln

*.project

*.java

*.jsp

*.jspf

*.tag

*.tld

*.hbs

*.properties

*.sln

*.csproj

*.cs

*.cshtml

*.xaml

*.vb

*.config

*.asp

*.bas

*.vbp

*.frm

*.cls

*.dsr

*.ctl

*.vb

*.cpp

*.c++

*.cxx

*.hpp

*.hh

*.h++

*.hxx

*.c

*.cc

*.h

*.php

*.php3

*.php4

*.php5

*.php56

*.phtm

*.phtml

*.tpl

*.ctp

*.twig

*.apex

*.apexp

*.page

*.component

*.cls

*.trigger

*.tgr

*.object

*.report

*.workflow

*.rb

*.rhtml

*.rxml

*.rjs

*.erb

*.js

*.htm

*.html

*.json

*.ts

*.tsx

*.vbs

*.pl

*.pm

*.plx

*.psgi

*.java

*.kt

*.m

*.h

*.swift

*.xib

*.html

*.htm

*.pls

*.sql

*.pkh

*.pks

*.pkb

*.pck

*.py

*.groovy

*.gsh

*.gvy

*.gy

*.scala

*.sc

*.conf

*.go

*.kt

*.kts

*.cbl

*.cob

*.eco

*.pco

*.sqb

*.cpy

*.aspx

*.ascx

*.config

*.xml

*.cgi

*.inc

*.jar

*.js

*.dll

*.tf

*.yaml

build.gradle

build.sbt

yarn.lock

requirements.txt

requirement.txt

composer.lock

Dockerfile*

dock*

*.dart

*.plist

go.mod

go.sum

Podfile

Podfile.lock

*.cmp

File Filters

There are two methods for applying filters to files and folders for Checkmarx One scans.

  • Filter Entire Scan - exclusions are applied during the pre-scan process, so that the excluded files aren't sent to any of the scanners.

  • Filters for Specific Scanners - apply filters for a specific scanner during the scan process, so that the specified scanner doesn't analyze the excluded files.

Filter Entire Scan

--file-filter flag provides the ability to filter the scanned file list as follows:

  • Include files, file extensions.

  • Exclude files, file extensions and folders.

The scan create command uses two flags, --file-include and --file-filter, in synergy. First, it applies the --file-include flag (or the default list of included file types) to establish the baseline of which files to include in the scan. Then, it further refines the file selection by applying the filters specified in the --file-filter flag.

Supported Functionalities:

  • Provide wildcard support by using the * sign.

    For example - *.html

  • Provides the ability to exclude files, files extensions, and folders. This is being performed by using the ! sign.

    For example - !*.html,!src

    Notice

    To exclude files, files extensions, and folders using the ! sign, use the argument in single quotes.

    For example:

    --file-filter !mycompany.jar

    For more details see Scan with exclusion of specific file or file type

  • Provides the ability to include files and files extensions.

    For example:

    • t* → Will include all the files starting with “t”.

    • *.txt → Will include all the files with “.txt” extension.

Limitations:

  • The --file-filter flag works only if the scanned source code is a directory or a zip file (not a GIT repository). However, this limitation does not apply when using the filter flags for specific scanners, see Filters for Specific Scanners.

  • Doesn’t support a full path.

    For example - java/src1/test.txt

  • .git folders and sub-folders can't be excluded

Filters for Specific Scanners

The following flags are used to apply filters to SAST, IaC Security and SCA scanners respectively: --sast-filter, --iac-security-filter, --sca-filter. You can use these flags to specify file types.

Notice

The filters for specific scanners can be used for all types of scans (directory, zip file or GIT repo), as opposed to --file-filter which does not work on GIT repositories.

The following are some examples of how these flags can be used:

  • for inclusion - --sast-filter *.java,

  • for exclusion - --sast-filter !*.java or --sca-filter !**\Dockerfile

If you would like to include only files inside specific folders, you need to first do a global exclude and then you can specify the folders to include.

For example:

--sast-filter !**/**,Folder01/**,**/Folder02/** would cause the SAST scanner to run only on files inside “Folder01” and “Folder02”.

Notice

For additional details about the syntax used for these filters, see Flags. Learn more about glob patterns syntax here.

Checkmarx SCA Resolver

Checkmarx SCA Resolver is an on-prem utility that enables you to resolve and extract dependencies and fingerprints from your source code and send them to the Checkmarx SCA cloud platform for risk analysis. This enables you to run a comprehensive SCA scan without the need to send your actual source code to the cloud. It also enables you to scan private (local) dependencies that aren’t accessible to the Checkmarx SCA cloud platform.

In order to use the SCA Resolver with the Checkmarx One CLI, you need to download the Checkmarx SCA Resolver separately in a location that the Checkmarx One CLI can find. Find the latest download at Checkmarx SCA Resolver Download and Installation.

To use the SCA Resolver, you need to add the --sca-resolver flag to your command line with an argument with the path to your local installation of the Resolver executable. See example below, Scan using SCA Resolver.

Warning

When running a CLI scan that uses SCA Resolver, the source code must be in a local folder, not in a zip archive or a code repository.

To add additional arguments to Checkmarx SCA Resolver, use the flag --sca-resolver-params with any additional arguments that you need. If necessary to use spaces and/or quotes, wrap the arguments in double quotes and use single quotes inside the value. For a complete list of SCA Resolver configuration arguments, see Checkmarx SCA Resolver Configuration Arguments.

Notice

Only arguments that can be used in Offline mode can be applied to scans run via the Checkmarx One CLI Tool and plugins.

For more information about using SCA Resolver in Checkmarx One CI/CD integrations, see Using SCA Resolver in Checkmarx One CI/CD Integrations.

Threshold

Configuring thresholds enables users to specify a threshold of vulnerability severities that, when found in a scan, will cause Checkmarx One to return a fail code for the scan. Users can then configure pipelines to break builds upon scan failure, so that scans that hit the threshold will break the build.

The threshold option supports a shorthand syntax with the format being a semi-colon separated list of key-value pairs.

The format for thresholds is <engine>-<severity>=<limit>

  • Options for engine: sast, iac-security, sca, api-security

  • Options for severity: High, Medium, Low, Info (Info is only for SAST engine)

  • Options for limit: A number equal to or greater than 1

More than one threshold can be defined for each engine and thresholds can be set for multiple engines. Multiple thresholds should be separated by a semi-colon. An OR operator is applied, so that if any one of the thresholds is reached the scan will fail.

For example, to set the threshold for SAST as 10 high severity or 20 medium severity vulnerabilities, and for SCA as 10 high severity vulnerabilities, use the following syntax:

--threshold "sast-high=10; sast-medium=20; sca-high=10"

Reports

You can generate reports for the scan results as part of the scan create command.

Notice

You can also generate reports for previous scans using the results show command.

There are two main types of reports:

  • Scan summary report - gives a summary of the scan results, including the number of risks of various types and severity levels that were identified by the scan. This type of report is available in HTML, json, console and markdown format.

  • Complete scan report - a comprehensive report showing details about each of the risks identified in the scan. This type of report can be generated in json, sarif or sonar format.

You can also generate PDF reports, for which you can specify which sections you would like to include in the report. In addition, for PDF reports, you can specify one or more email recipients who will receive an email with a download link for the report.

To generate a report as part of the scan create command, add the --report-format flag, specifying the format you would like to generate.

For PDF reports, use the following flags to specify email recipients and to specify which sections to include in the report.

./cx scan create --project-name <Project Name> -s <path> --branch <branch name> --report-format pdf --report-pdf-email <recipient_email> --report-pdf-options <specify_sections>

For information about the content of scan reports, see Scan Reports.

SBOM Reports

You can generate SBOM reports for the open source packages identified in your project by the SCA scanner. Reports can be generated in CycloneDX and SPDX formats, with additional “property” fields showing supplemental risk data. The reports can be exported in XML (for CycloneDX only) or JSON format. You can generate SBOM reports for Checkmarx One projects on which the SCA scanner has run. For more info about Checkmarx SBOMs, see SBOM Reports.

Example for generating a CycloneDX SBOM report in JSON format:

./cx scan create --project-name <Project Name> -s <path> --branch <branch name> --report-format sbom --report-sbom-format CycloneDxJson

Flags

Warning

Whenever a parameter value (e.g., project name, file location etc.) has a space or other special character in it, it needs to be escaped either by enclosing it in quotes or using an escape character. The specific syntax for escaping characters will vary depending on the command-line interface or programming language you are using.

Glossary
--async

Do not wait for scan completion.

--branch <string>, -b <string> (Required)

Branch to scan.

This is a required flag even when scanning from a zip archive. If the zip archive doesn't represent a specific branch, you can submit .unknown as the value and it will be shown in the UI as "N/A". (You should not enter N/A as the value, as this will be misinterpreted by the system.)

--file-filter <string>, -f <string>

Source file filtering pattern. Refer to File Filters.

--file-include <string>

Comma separated list of additional file extensions to be included in the scan.

For example: *.java2,file.txt

--file-source <string>, -s <string> (Required)

The path to the compressed zip file, the path to the folder or the repository URL to scan.

--filter <string>
  • Filter the list of results.

  • Use ';' as the delimiter for arrays.

  • Available filters are:

    scan-id, limit, offset, sort, include-nodes, note-ids, query, group, status, severiity, state.

  • Options for severity, state, status:

    • severity - High, Medium, Low, Info (Info is only for SAST scanner).

    • state - TO_VERIFY, NOT_EXPLOITABLE, PROPOSED_NOT_EXPLOITABLE, CONFIRMED, URGENT, IGNORED, NOT_IGNORED.

    • status - NEW, RECURRENT, FIXED.

--help, -h

Help for the create command.

--iac-security-filter <string>

Filter option specific to IaC Security scan

  • Including a file type - *.java

  • Excluding a file type - !*.java

  • Use "," sign to chain filter types.

    For example: *.java,*.js

  • The parameter also supports including/excluding folders.

--iac-security-platforms <string>, <string>

Specify the platforms that you would like the IaC Security scan to run on.

When this flag is used, it overrides your account's default settings.

--ignore-policy

Use this flag to ignore policies. For example, if you have a policy that will break the build if a high severity vulnerability is identified in the project, you can use this flag to prevent the scan from failing.

--output-name <string> (Default: "cx_result")

Output file name.

--output-path <string> (Default: ".")

Output path.

--project-groups <string>

List of groups associated with projects.

For example: (groupA,groupB).

Limitation: This flag only works when creating a new project. For an existing project, it won't update the groups.

--project-name <string> (Required)

Name of the project.

When using the --project-name flag, the Project name must be written in quotes if there is a space in the project name.

For example: Test, Test1, "Test 1".

--project-private-package NOT FULLY SUPPORTED YET (Default: false)

You can designate a scan as a "Private Package" and assign a package version to it. Once a private package has been scanned, info about the risks affecting that package will be identified by SCA when that package version is used in any of you projects. You can download an article about private packages here.

True = designate as private package.

False = not a private package.

When using this flag, you should also specify the package version using --sca-private-package-version.

--project-tags <string>

List of tags to associate to projects.

For example: (tagA,tagB:val, etc)

Warning

When this flag is used, the tags that are submitted overwrite any existing tags that were assigned to the project.

--report-format <string> (Default: summaryConsole)

Report output format.

Specify one of the following:

json, summaryHTML, summaryJSON, summaryCONSOLE, sarif, gl-sast, sonar, markdown or PDF, SBOM

Report formats json, sarif, gl-sast and sonar generate complete scan reports (gl-sast returns only sast results).

Report formats summaryHTML, summaryJSON, summaryCONSOLE and markdown generate summary reports.

For SBOM reports, you need to add the --report-sbom-format flag to specify the SBOM standard and output format.

--report-pdf-email <string>

Specify email recipients who will receive the pdf report. Multiple emails are separated by a ",".

This flag can only be used when --report-format is set as pdf.

--report-pdf-options <string> (Default: ScanSummary, ExecutiveSummary, and ScanResults)

Specify the sections that will be included in the pdf format report.

Available sections are:

Sast, Sca, Iac-Security, Api-Security, ScanSummary, ExecutiveSummary, ScanResults.

ScanResults includes results for all scanners (IaC-Security, Sast and Sca).

This flag can only be used when --report-format is set to pdf.

--report-sbom-format (Default: CycloneDxJson)

The type of SBOM standard (CycloneDX or SPDX) as well as the output format.

Specify one of the following:

CycloneDxJson, CycloneDxXml, SpdxJson

This needs to be specified when the --report-format is set to "SBOM".

--resubmit

Apply the configurations used in the most recent scan in this project branch to the current scan.

Even when this flag is used, if an argument in the current scan differs from the configuration of the previous scan, the argument in the current scan takes precedence.

--sast-filter <string>

Filter option specific to SAST engine or scan.

  • Including a file type - *.java

  • Excluding a file type - !*.java

  • Use "," sign to chain filter types.

    For example: *.java,*.js

  • The parameter also supports including/excluding folders.

--sast-incremental

Perform only an Incremental SAST scan (as opposed to a full scan).

--sast-preset-name <string>

The name of the Checkmarx preset to use.

--sca-exploitable-path (Default: According to your project settings configuration)

Enable/disable the Exploitable Path feature for this scan.

True = enabled

False = disabled

Learn more about Exploitable Path.

--sca-filter <string>

Filter option specific to SCA engine or scan.

  • Including a file type - *.java

  • Excluding a file type - !*.java

  • Use "," sign to chain file types.

    For example: *.java,*.js

  • The parameter also supports including/excluding folders.

--sca-last-sast-scan-time (Default: 1)

Specify the number of days that SAST scan results are considered valid for use in Exploitable Path (i.e., if there is no current SAST scan, how many days prior to the current SCA scan will Checkmarx One look for a SAST scan to use for analyzing Exploitable Path).

Options: integer ≥ 1

Tip

Only full SAST scans are used for Expoitable Path, results from incremental scans aren't considered.

Warning

The --sca-last-sast-scan-time flag is only supported for single-tenant environments, not for multi-tenant.

--scan-info-format <string> (Default: list)
  • Selects the scan info output format.

  • Select one of the follwoing formats:

    list, table, json

--scan-timeout <int>

Cancel the scan and fail after the timeout in minutes.

--scan-types <string> (Default: all scanners licensed for your account)

Scan engines to be run for this scan.

For example: (sast,iac-security,sca,api-security).

--sca-private-package-version NOT FULLY SUPPORTED YET (Default: False)

When you designate a scan as a private package using the --project-private-package flag, you should also specify the package version using this flag.

e.g., 0.1.1

You can download an article about private packages here.

--sca-resolver-params <string>

Additional arguments to use with CxSCA Resolver. The arguments can be found here. The SCA Resolver runs in offline mode, only arguments compatible with this mode will work. The resolver params must be enclosed in quotes "", see example below.

--sca-resolver <string>

Use Checkmarx SCA Resolver to locally resolve SCA project dependencies. Specify the path to your local installation of SCA Resolver binary (executable).

When running a CLI scan that uses SCA Resolver, the source code must be in a local folder, not in a zip archive or a code repository.

--ssh-key <string>

Path to ssh private key.

--tags <string>

List of tags associated to scans.

For example: (tagA,tagB:val,etc)

--threshold <string>

Threshold count of severity of scan results based on the engine.

The threshold format is:

<engine>-<severity>=<limit>

For more information, see Threshold.

--wait-delay <int> (Default: 5 seconds)

Polling wait time (seconds) to get scan status.

Examples

Scan from a Git repository
./cx scan create --project-name <Project Name> -s <Repository URL> --branch <branch name>

Sample command:

C:\ast-cli_2.0.53_windows_x64>cx scan create  --project-name elidemo -s https://github.com/juice-shop/juice-shop --branch master

Sample response:

Scan ID      : 492e1626-9489-4ee9-ac1b-628de56c5e33
Project ID   : a1b1b151-d763-4f34-bfbc-de8c1422c02c
Project Name : elidemo
Status       : Running
Created at   : 08-07-23
Branch       : master
Tags         : []
Type         : Full
Timeout      : NONE
Initiator    : eli
Origin       : ASTCLI 2.0.53
Engines      : [ sast kics sca apisec]

2023/08/07 22:14:02 Scan Finished with status:  Completed
            Scan Summary:
              Created At: 2023-08-07, 22:07:57
              Project Name: elidemo
              Scan ID: 492e1626-9489-4ee9-ac1b-628de56c5e33

            Results Summary:
              Risk Level: High Risk

              -----------------------------------
              API Security - Total Detected APIs: 0
              -----------------------------------

            Policy Management Violation:
              Policy: DemoHigh | Break Build: false | Violated Rules: highVulnerability;

              Total Results: 170
              -----------------------------------
              |             High: 90            |
              |           Medium: 66            |
              |              Low: 13            |
              |             Info: 1             |
              -----------------------------------
              |     IAC-SECURITY: 41            |
              |             SAST: 0             |
              |   APIS WITH RISK: 0             |
              |              SCA: 129           |

              Checkmarx One - Scan Summary & Details: https://eu.ast.checkmarx.net/projects/a1b1b151-d763-4f34-bfbc-de8c1422c02c/scans?id=492e1626-9489-4ee9-ac1b-628de56c5e33&branch=master
Scan from a source directory
./cx scan create -s <path> --branch <branch name> --project-name <Project Name>

Sample command:

user@laptop:~/ast-cli$ ./cx scan create -s . --branch main --project-name Test111
Scan in asynchronous mode
./cx scan create --project-name <Project Name> -s <Repository URL> --branch <branch name> --async

Sample command:

user@laptop:/AST$ ./cx scan create --project-name demo -s . --branch main --async
Scan using specific scanners
./cx scan create --project-name <Project Name> -s <Repository URL> --branch <branch name> --scan-types <scan types>

Sample command:

user@laptop:/AST$ ./cx scan create --project-name demo -s . --branch main --scan-types iac-security
Scan using SCA Resolver
./cx scan create --project-name <Project Name> -s <path> --branch <branch name> --sca-resolver <path-to-resolver> --sca-resolver-params <additional-resolver-arguments>

Sample command:

user@laptop:/AST$ ./cx scan create --project-name demo --scan-types sast,sca -s . --sca-resolver /sca/scaResolver --sca-resolver-params "-q -e my_file" --async
Scan with Inclusion of unsupported file formats
./cx scan create -s <path> --branch <branch name> --project-name <Project Name> --file-include <string>

Sample command:

user@laptop:~/ast-cli$ ./cx scan create -s ./Source-Folder/ --branch main --project-name Test111 --file-include sample.txt,*.myextension
Scan with exclusion of specific file or file type
./cx scan create -s <path> --branch <branch name> --project-name <Project Name> --file-filter <string>

Sample command:

user@laptop:~/ast-cli$ ./cx scan create -s scan_files/ --branch main --project-name Test111 --file-filter !*mycompany*.jar
Scan with exclusion of a specific folder
./cx scan create -s <path> --branch <branch name> --project-name <Project Name> --file-filter <folder name>

Sample command:

user@laptop:~/ast-cli$ ./cx scan create -s scan_files/ --branch main --project-name Test111 --file-filter !main
Scan with threshold
./cx scan create --project-name <Project Name> -s <path> --branch <branch name> --threshold <engine>-<severity>=<limit>

Sample command:

user@laptop:/ast-cli$ ./cx scan create --project-name myproject -s my_file.zip --branch main --threshold sast-high=1

Sample response:

         Created At: 2022-01-26, 11:24:20
               Risk: High Risk
         Project ID: 49e6d565-933b-4a55-8d08-ec026ddcd7e2
            Scan ID: bdab6a9e-eb90-4cab-8783-5c3a2a052b31
       Total Issues: 28
        High Issues: 3
      Medium Issues: 11
         Low Issues: 14
IaC Security Issues: 18
      CxSAST Issues: 9
       CxSCA Issues: 1
2022/01/26 11:25:14 Threshold check finished with status Failed : sast-high: Limit = 1, Current = 2 |
Scan and send report to email recipient
./cx scan create --project-name <Project Name> -s <path> --branch <branch name> --report-format pdf --report-pdf-email <recipient_email> --report-pdf-options <specify_sections>

Sample command:

user@laptop:/ast-cli$ ./cx scan create --project-name EliCLIDemo -s . --branch main --report-format pdf --report-pdf-email [email protected] --report-pdf-options ExecutiveSummary 

Sample response:

2023/08/07 22:30:45 Scan Finished with status:  Completed
2023/08/07 22:30:56 Sending PDF report to:  [[email protected]]
            Scan Summary:
              Created At: 2023-08-07, 22:24:56
              Project Name: elidemo
              Scan ID: 861ce408-f355-4692-9bff-3d35a6c17170

            Results Summary:
              Risk Level: High Risk

              -----------------------------------
              API Security - Total Detected APIs: 0
              -----------------------------------

            Policy Management Violation:
              Policy: EliHigh | Break Build: false | Violated Rules: high;

              Total Results: 170
              -----------------------------------
              |             High: 90            |
              |           Medium: 66            |
              |              Low: 13            |
              |             Info: 1             |
              -----------------------------------
              |     IAC-SECURITY: 41            |
              |             SAST: 0             |
              |   APIS WITH RISK: 0             |
              |              SCA: 129           |

              Checkmarx One - Scan Summary & Details: https://eu.ast.checkmarx.net/projects/a1b1b151-d763-4f34-bfbc-de8c1422c02c/scans?id=861ce408-f355-4692-9bff-3d35a6c17170&branch=master

scan delete

The delete command is used to delete one or more scans in Checkmarx One.

Usage

./cx scan delete --scan-id <scan ID>

Flags

Glossary
--help, -h

Help for the delete command.

--scan-id (Required)

One or more comma separated scan IDs to delete.

For example: <scan-id>,<scan-id>,...

Workflow Examples

Delete a scan
user@laptop:/AST$ ./cx scan delete --scan-id 7eb83ed3-5734-4428-92a2-4819fc6c490f
Delete several scans

You can specify several comma separated scan ids in order to delete multiple scans.

./cx scan delete --scan-id 7eb83ed3-5734-4428-92a2-4819fc6c490f,a2f45c91-18ba-4d69-a748-972d0ecc1453

scan list

The scan list command provides a list of all the scans in your Checkmarx One account.

Usage

./cx scan list [flags]

Flags

Glossary
--filter <string>
  • Filter scans lists.

  • Use the ";" sign as the delimiter for arrays.

  • Available filters are:

    limit, offset, scan-ids, tags-keys, tags-values, statuses, project-id, from-date, to-date.

    • status-enum - queued, running, completed, failed, partial, canceled.

    • from-date, to-date - must be entered in RFC3339 Date (Extend) format "YYYY-MM-DDThh:mm:ssZ" (e.g. 2023-02-22T12:00:00Z)

--fromat <string> (Default: table)

The output format for the response. Possible values are json, list or table.

---help, -h

Help for the list command.

Pagination

This command uses pagination. By default it returns the first 20 results (i.e., limit=20,offset=0). Use limit to adjust the maximum number of results to return and offset to specify the number of results to skip before starting to return results. You can use offset=0 and limit=0 to get all results.

Example: The following command returns records 21-30

./cx scan list --filter "limit=10,offset=20"

Applying Filters

You can limit results by filtering by various scan attributes such as scan IDs, project ID, scan tags, scan status and date range.

Filters are applied using the following syntax:

./cx scan list --filter "attributeA=value1,attributeB=value1;value2;value3,..."

Example: The following command returns records for all scans run on specific projects, based on project ID.

./cx scan list --filter "project-id=f761f24b-fbcc-4502-acef-7fa3f2de38ed"

When multiple filter attributes are used, an AND operator is applied between attributes. When multiple values are given for an attribute, an OR operator is used between values.

Example: The following command returns records for all scans with the tag key "product" and a tag value of either "AppA", "AppB" or "AppC" that were run since Jan 1, 2023.

./cx scan list --filter "tags-keys=product,tags-values=AppA;AppB;AppC,from-date=2023-01-01T00:00:00Z,limit=0"

Examples

Using the scan list command with format flags
user@laptop:/AST$ ./cx scan list --format table

Scan ID                              Project ID                           Status    Created at Tags Initiator Origin             
-------                              ----------                           ------    ---------- ---- --------- ------             
a2f45c91-18ba-4d69-a748-972d0ecc1453 9f47d3d7-76f2-418b-9513-e3e02cc5cbb9 Completed 08-27-21   []   org_admin ASTCLI 2.0.0-rc.21
user@laptop:/AST$ ./cx scan list --format list

Scan ID    : a2f45c91-18ba-4d69-a748-972d0ecc1453
Project ID : 9f47d3d7-76f2-418b-9513-e3e02cc5cbb9
Status     : Completed
Created at : 08-27-21
Tags       : []
Initiator  : org_admin
Origin     : ASTCLI 2.0.0-rc.21

scan show

The show command is used to retrieve information about a scan in Checkmarx One.

Usage

./cx scan show --scan-id <scan id> [flags]

Flags

Glossary
--format <string> (Default: table)

The output format for the response. Possible values are json, list or table.

--help, -h

Help for the show command.

--scan-id <string> (Required)

Scan ID to show.

Examples

Using the scan show command with default settings
C:\ast-cli_2.0.53_windows_x64>cx scan show --scan-id 0f405e10-10c4-4fe9-a356-86253a52ab20

Scan ID                              Project ID                           Project Name Status  Created at Branch Tags Type Timeout Initiator Origin        Engines                
-------                              ----------                           ------------ ------  ---------- ------ ---- ---- ------- --------- ------        -------                
0f405e10-10c4-4fe9-a356-86253a52ab20 a1b1b151-d763-4f34-bfbc-de8c1422c02c elidemo      Partial 08-05-23   master []   Full NONE    eli       ASTCLI 2.0.53 [sast kics sca apisec] 
Using the scan show command with format flag
C:\ast-cli_2.0.53_windows_x64>cx scan show --format json --scan-id 0f405e10-10c4-4fe9-a356-86253a52ab20
{"ID":"0f405e10-10c4-4fe9-a356-86253a52ab20","ProjectID":"a1b1b151-d763-4f34-bfbc-de8c1422c02c","ProjectName":"elidemo","Status":"Partial","CreatedAt":"2023-08-05T23:25:06.290004+03:00","UpdatedAt":"2023-08-05T20:28:43.918848Z","Branch":"master","Tags":{},"SastIncremental":"Full","Timeout":"NONE","Initiator":"eli","Origin":"ASTCLI 2.0.53","Engines":["sast","kics","sca","apisec"]}

scan tags

The tags command is used to provide a list of all the available tags in Checkmarx One.

Tags can be used for overriding Jira feedback app fields values. For additional information see:

Fields Override

Usage

./cx scan tags [flags]

Flags

Glossary
--help, -h

Help for the tags command.

Examples

Using the tags command
C:\ast-cli_2.0.53_windows_x64>cx scan tags
{"demotag":[""],"main":[""],"team":["dev01","dev02","qa"]

scan workflow

The workflow command is used to retrieve information about a scan workflow in Checkmarx One.

Usage

./cx scan workflow --scan-id <scan id> [flags]

Flags

Glossary
--format <string> (Default: table)

The output format for the response. Possible values are json, list or table.

---help, -h

Help for the show command.

--scan-id <string> (Required)

Scan ID for which you would like to retrieve the workflow.

Workflow Examples

Retrieve scan workflow
./cx scan workflow --scan-id <scan id>

Sample command:

user@laptop:/AST$ ./cx.exe scan workflow --scan-id a2f45c91-18ba-4d69-a748-972d0ecc1453 --format table

Sample response:

Source                         Timestamp                      Info                                                   
------                         ---------                      ----                                                   
scans                          2021-08-27T14:15:46.843323175Z Scan created                                           
scans                          2021-08-27T14:15:46.996620259Z Scan Running                                           
fetch-sources-default          2021-08-27T14:15:47.068Z       fetch-sources-default started                          
fetch-sources-default          2021-08-27T14:15:47.082Z       fetch-sources-default in progress                      
fetch-sources-default          2021-08-27T14:15:48.061Z       fetch-sources-default ended                            
config-as-code-default         2021-08-27T14:15:48.101Z       config-as-code-default started                         
config-as-code-default         2021-08-27T14:15:48.304Z       config-as-code-default checkmarx config file not found 
config-as-code-default         2021-08-27T14:15:48.346Z       config-as-code-default ended                           
kics-runner-default            2021-08-27T14:15:48.415Z       kics-runner-default started                            
kics-runner-default            2021-08-27T14:15:48.425Z       kics-runner-default Start scan files download          
sca-runner-default             2021-08-27T14:15:48.429Z       sca-runner-default started                             
fetch-queries-default          2021-08-27T14:15:48.43Z        fetch-queries-default started                          
sca-runner-default             2021-08-27T14:15:48.449Z       sca-runner-default Start scan files download           
kics-runner-default            2021-08-27T14:15:48.583Z       kics-runner-default Finished scan files download       
kics-runner-default            2021-08-27T14:15:48.597Z       kics-runner-default Start scan execution               
sca-runner-default             2021-08-27T14:15:48.637Z       sca-runner-default Finished scan files download        
sca-runner-default             2021-08-27T14:15:48.671Z       sca-runner-default Start scan execution                
fetch-queries-default          2021-08-27T14:15:48.975Z       fetch-queries-default ended                            
sast-scan-inc-default          2021-08-27T14:15:49.014Z       sast-scan-inc-default started                          
sast-scan-inc-default          2021-08-27T14:15:49.262Z       sast-scan-inc-default ended                            
sast-rm-default                2021-08-27T14:15:49.307Z       sast-rm-default started                                
sast-results-inc-default       2021-08-27T14:15:49.307Z       sast-results-inc-default started                       
sast-rm-default                2021-08-27T14:15:49.406Z       sast-rm-default Queued in sast resource manager        
sast-results-inc-default       2021-08-27T14:15:49.443Z       sast-results-inc-default ended                         
kics-runner-default            2021-08-27T14:15:51.285Z       kics-runner-default Finished scan execution            
kics-runner-default            2021-08-27T14:15:51.297Z       kics-runner-default Start results publish              
kics-runner-default            2021-08-27T14:15:51.311Z       kics-runner-default Finished results publish           
kics-runner-default            2021-08-27T14:15:51.331Z       kics-runner-default Start engine log publish           
kics-runner-default            2021-08-27T14:15:51.368Z       kics-runner-default Finished engine log publish        
kics-runner-default            2021-08-27T14:15:51.413Z       kics-runner-default ended                              
collect-logs-default           2021-08-27T14:15:51.464Z       collect-logs-default started                           
kics-results-processor-default 2021-08-27T14:15:51.464Z       kics-results-processor-default started                 
collect-logs-default           2021-08-27T14:15:51.613Z       collect-logs-default ended                             
kics-results-processor-default 2021-08-27T14:15:52.306Z       kics-results-processor-default ended                   
sca-runner-default             2021-08-27T14:16:20.583Z       sca-runner-default Finished scan execution             
sca-runner-default             2021-08-27T14:16:20.596Z       sca-runner-default Start results publish               
sca-runner-default             2021-08-27T14:16:20.62Z        sca-runner-default Finished results publish            
sca-runner-default             2021-08-27T14:16:20.664Z       sca-runner-default ended                               
sca-packages-processor-default 2021-08-27T14:16:20.716Z       sca-packages-processor-default started                 
sca-results-processor-default  2021-08-27T14:16:20.717Z       sca-results-processor-default started                  
sca-packages-processor-default 2021-08-27T14:16:20.924Z       sca-packages-processor-default ended                   
sca-results-processor-default  2021-08-27T14:16:21.246Z       sca-results-processor-default ended                    
sast-rm-default                2021-08-27T14:16:21.833Z       sast-rm-default ended                                  
collect-logs-default           2021-08-27T14:16:21.882Z       collect-logs-default started                           
sast-results-events-default    2021-08-27T14:16:21.883Z       sast-results-events-default started                    
collect-logs-default           2021-08-27T14:16:22.068Z       collect-logs-default ended                             
sast-results-events-default    2021-08-27T14:16:24.982Z       sast-results-events-default ended                      
scans                          2021-08-27T14:16:25.056678542Z Scan Completed                          

scan logs

The logs command is used to retreive the application logs for a single scan type.

The optional scan types are:

  • sast

  • kics

Usage

./cx scan logs --scan-id <scan Id> --scan-type <scan type>

Flags

Glossary
---help, -h

Help for the logs command.

--scan-id <string>

Scan ID to retrieve log for.

--scan-type <string> (Required)

Scan type to pull logs for.

Optional scan types: sast, iac-security

Workflow Examples

Retrieve logs for SAST scanner

Sample command:

user@laptop:~/ast-cli$ ./cx scan logs --scan-id f36b063a-84ca-4c4f-ad22-debacdd588aa --scan-type sast

Sample response for sast scanner:

26/09/2021 13:05:42,602 [1] INFO  Available memory: 12347 Used memory: 56 Elapsed Time: 00:00:00.1241647 [Unspecified] -
Product version: 9.4.0.0-202107110128-Release
Used memory: 56Mb
OS: Unix 5.4.129.63
Current Directory: /app/Engine

Processor Count: 3
CLR Version: 3.1.18
Executable PID: 19
Executable Location: /usr/share/dotnet/dotnet
Process ID: 19
/ 96 GB Free
/proc 0 GB Free
/dev 0 GB Free
/dev/pts 0 GB Free
/sys 0 GB Free
/sys/fs/cgroup 7 GB Free
/sys/fs/cgroup/systemd 0 GB Free
/sys/fs/cgroup/freezer 0 GB Free
/sys/fs/cgroup/net_cls,net_prio 0 GB Free
/sys/fs/cgroup/memory 0 GB Free
/sys/fs/cgroup/perf_event 0 GB Free
/sys/fs/cgroup/devices 0 GB Free
/sys/fs/cgroup/cpu,cpuacct 0 GB Free
/sys/fs/cgroup/blkio 0 GB Free
/sys/fs/cgroup/hugetlb 0 GB Free
/sys/fs/cgroup/pids 0 GB Free
/sys/fs/cgroup/cpuset 0 GB Free
/dev/mqueue 0 GB Free
/etc/podinfo 7 GB Free
/dev/shm 0 GB Free
/run/secrets/kubernetes.io/serviceaccount 7 GB Free
/proc/bus 0 GB Free
/proc/fs 0 GB Free
/proc/irq 0 GB Free
/proc/sys 0 GB Free
/proc/acpi 7 GB Free
/sys/firmware 7 GB Free

Disk Speed: 526 Ticks per one request
New Disk Speed: 292 Ticks per one request
64Bit platform
PROCESSOR IDENTIFIER: Intel(R) Xeon(R) Platinum 8275CL CPU @ 3.00GHz
Core Speed: 3.6GHz
Product: Checkmarx SAST Engine
-       Main Version:
-       Hotfix Version:
-       Path:
Current Product dll's version list:
___________________________________
Assembly name:                 File version:
ASP.dll                        9.4.0.0-202107110125-Release
CSharp.dll                     9.4.0.0-202107110125-Release
DataCollections.dll            9.4.0.0-202107110128-Release
EngineFacade.dll               9.4.0.0-202107110128-Release
Flowgraphs.dll                 9.4.0.0-202107110128-Release
Plugin.dll                     9.4.0.0-202107110125-Release
Query.dll                      9.4.0.0-202107110128-Release
CxWrm.dll                      9.4.0.0-202107110128-Release
====================================================


26/09/2021 13:05:42,628 [1] INFO  Available memory: 12265 Used memory: 127 Elapsed Time: 00:00:01.7149099 [Unspecified] - Initializing scan input
26/09/2021 13:05:42,645 [1] INFO  Available memory: 12265 Used memory: 128 Elapsed Time: 00:00:01.7321179 [Startup] - Current Engine Configuration from DefaultConfig.xml:
_____________________________
IMPORTANT_FILE_ONLY_SCAN*=true
SMALL_PROJECT_BORDER*=3000000
Retrieving logs for KICS scanner

Sample command:

user@laptop:~/ast-cli$ ./cx scan logs --scan-id f36b063a-84ca-4c4f-ad22-debacdd588aa --scan-type kics

Sample response for KICS scanner

1:03PM | DEBUG | console.scan()
1:03PM | INFO  | Scanning with Keeping Infrastructure as Code Secure v1.3.3
1:03PM | DEBUG | Looking for queries in executable path and in current work directory
1:03PM | DEBUG | helpers.GetDefaultQueryPath()
1:03PM | DEBUG | helpers.GetExecutableDirectory()
1:03PM | DEBUG | Queries found in /app/kics-deployment/assets/queries
1:03PM | INFO  | Loading queries of type: dockerfile, ansible
1:03PM | DEBUG | source.NewFilesystemSource()
1:03PM | DEBUG | storage.NewMemoryStorage()
1:03PM | DEBUG | engine.NewInspector()
1:03PM | INFO  | Inspector initialized, number of queries=289
1:03PM | INFO  | Query execution timeout=1m0s
1:03PM | DEBUG | provider.NewFileSystemSourceProvider()
1:03PM | DEBUG | parser.NewBuilder()
1:03PM | DEBUG | resolver.Add()
1:03PM | DEBUG | resolver.Build()
1:03PM | DEBUG | service.StartScan()
1:03PM | DEBUG | service.StartScan()
1:03PM | DEBUG | engine.Inspect()
1:03PM | DEBUG | engine.Inspect()
1:03PM | DEBUG | model.CreateSummary()
1:03PM | DEBUG | console.resolveOutputs()
1:03PM | DEBUG | helpers.PrintResult()
1:03PM | INFO  | Files scanned: 4
1:03PM | INFO  | Parsed files: 4
1:03PM | INFO  | Queries loaded: 289
1:03PM | INFO  | Queries failed to execute: 0
1:03PM | INFO  | Inspector stopped
1:03PM | DEBUG | console.printOutput()
1:03PM | DEBUG | Output formats provided [json]
1:03PM | DEBUG | helpers.ValidateReportFormats()
1:03PM | DEBUG | helpers.GenerateReport()
1:03PM | INFO  | Results saved to file /tmp/953972639/results.json fileName:results.json
1:03PM | INFO  | Scan duration: 3318ms

sca-realtime

The scan sca-realtime command is used to create and run a new sca scan on the contents of a folder. The SCA realtime scan is a free feature which does not require a Checkmarx account. Anyone can download the CLI tool and run this command without need for authentication. The results are returned in the response body as a JSON object.

Warning

Even for users with a Checkmarx account, the realtime scan results are not synced with the user's Checkmarx account.

For info about which languages and package managers are supported for the SCA scanner, see SCA Scanner - Supported Languages and Package Managers.

Warning

In order for this tool to be effective, you need to install all relevant package managers on your local environment, see Installing Supported Package Managers for Resolver.

Usage

./cx scan sca-realtime [flags]

Flags

Glossary
--project-dir <string>, -p <string> (Required)

Path to the project folder on which the SCA scan will run.

Warning

This must point to a regular project folder and NOT a zip archive.

Examples

kics-realtime

The scan kics-realtime command is used to create and run a new sca scan locally using a container. The SCA realtime scan is a free feature which does not require a Checkmarx account. Anyone can download the CLI tool and run this command without need for authentication. The results are returned in the response body as a JSON object.

Warning

Even for users with a Checkmarx account, the realtime scan results are not synced with the user's Checkmarx account.

Usage

./cx scan kics-realtime [flags]

Supported scan files extensions / technologies

The scan kics-realtime command provides the ability to scan individual files that are supported by the KICS tool (mentioned in the list below).

kics-realtime supports scanning multiple technologies, namely :

  • Ansible

  • Azure Resource Manager

  • CDK

  • CloudFormation

  • Azure Blueprints

  • Docker

  • Docker Compose

  • gRPC

  • Helm

  • Kubernetes

  • OpenAPI

  • Google Deployment Manager

  • SAM

  • Terraform

 

Notice

For more details please check KICS official documentation https://docs.kics.io/latest/platforms/

Additional Parameters

--additional-params flag provides the ability to send additional scan options supported by KICS. Should follow comma separated format.

Notice

More information about the additional scan options/flags supported by KICS in their official documentation

https://docs.kics.io/latest/commands/

Warning

The report format and output path cannot be overridden, even by explicitly setting those flags in the additional-params.

Flags

Glossary
--additional-params <string>,<string>

Comma separated additional scan options supported by KICS. See https://docs.kics.io/latest/commands/

--engine <string> (Default: docker)

Name for the container engine to run KICS.

--file <string> (Required)

Path to input file.

Examples

Scanning a file
./cx scan kics-realtime --file <FILE PATH>
Scanning a file with a specific engine
./cx scan kics-realtime --file <FILE PATH> --engine <ENGINE NAME>
Scanning a file with additional parameters
./cx scan kics-realtime --file <FILE PATH> --additional-params <KICS_COMMANDS>
Scanning a file in debug mode
./cx scan kics-realtime --file <FILE PATH> --debug