Skip to main content

Checkmarx One CLI Quick Start Guide

Overview

The legacy CLI (v1) only configures and initiates a SAST, SCA and OSA scans.

The Checkmarx One CLI (v2) is a Command Line Interface that acts as a wrapper and enables the ability to perform all tasks that are normally done via the REST APIs.

There are specific executables for the main use cases in order to perform the following:

  • create/delete/get/set projects

  • create/delete/get/set scans for all of our engines

  • get results

The latest CLI is also in a container, in case the user wants to deploy and use it in that way: checkmarx/ast-cli

How-to

Installation

Download the latest release from: https://github.com/Checkmarx/ast-cli/releases

Quick Start

First, you need to generate a Checkmarx One API Key. Then, you can run the CLI installation, using the API Key that you generated for authentication.

Generating an API Key

You can generate an API Key by logging in to Checkmarx One and generating a new API Key, as described below. Alternatively, an API Key can be generated using the Authentication API.

The roles (permissions) assigned to an API Key are inherited from the user who is logged in when the API key is generated. Therefore, make sure that you are logged in to an account with the appropriate permissions. The minimum required roles for running an end-to-end flow of scanning a project and viewing results are the out-of-the-box composite role ast-scanner as well as the IAM role default-roles. See Managing Roles

Warning

Whenever you update your Checkmarx One license (e.g., adding a new scanner) all existing API Keys become invalid. You will need to generate new API Keys to replace those that are used in your integrations and plugins.

Figure 1. 
Generating_an_API_Key.gif

GIF - How to generate an API Key



To Log in to Checkmarx One:

  1. Open the URL for your environment.

  2. Log in to your Checkmarx One account by entering your Tenant Account, Username and Password.

Notice

The roles (permissions) assigned to the API Key are inherited from the user account that generates the key. Therefore, make sure that you are logged in to an account with the appropriate.

To generate an API Key via Checkmarx One:

  1. Log in to the Checkmarx One web portal and select Identity_and_Access_MGMT.png Identity and Access Management in the main navigation.

    The IAM portal opens.

  2. In the main navigation, click API Keys, then click on the Create Key button.

    Image_995.png

    A new key is created with the permissions of the current user assigned to it.

  3. Copy the key and save it in a place where you will be able to retrieve it for future use.

    6028853316.bmp

Notice

Once you close the window, you will no longer be able to access this API Key.

Notice

You can obtain a curl for submitting the request for an access token, by clicking on Show details and copying the content.

Command Line

$ ./cx.exe configure
Setup guide: https://checkmarx.atlassian.net/wiki/x/mIKctw

Checkmarx One Base URI []: https://ast.checkmarx.net/
Checkmarx One Base Auth URI (IAM) []: https://iam.checkmarx.net/
Checkmarx One Tenant [organization]: mytenantname
Do you want to use API Key authentication? (Y/N): Y
Checkmarx One API Key []: <paste api key>

$ ./cx.exe scan create --project-name demotest -s https://github.com/WebGoat/WebGoat.git --sast-preset-name "High and Medium" --file-filter "!test/" --branch "main"

Scan ID    : 46996ef8-729b-4eff-b0ef-658346caae2a
Project ID : 9c7c3a2f-8126-484b-b1f6-7f24ccbecb4b
Status     : Running
Created at : 09-20-21
Tags       : []
Initiator  : org_admin
Origin     : ASTCLI 2.0.0-rc.23

wait for scan to complete 46996ef8-729b-4eff-b0ef-658346caae2a Running
In this section: