Checkmarx One CLI Quick Start Guide
Overview
The Checkmarx One CLI 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
Getting Started
Download and Installation
To download the CLI tool, perform the following:
Go to the following link: CLI Releases
Download the relevant tool that is compatible with your Operating System.
Place the tool in any location on the client that you are using.
Notice
The CLI tool can be installed on any Linux/Windows/MAC distributions.
Initial Setup
For this quick start tutorial, describes how to authenticate using an an API Key. For the alternative method using an OAuth Client, see Configuring the Checkmarx One CLI.
Generate a Checkmarx One API Key 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-scanneras well as the IAM roledefault-roles. See Managing RolesWarning
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.
To Log in to Checkmarx One:
Open the URL for your environment.
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.
Generating an API Key Figure 5.
GIF - How to generate an API Key
To generate an API Key:
Log in to the Checkmarx One web portal and select Settings
> Identity and Access Management in the main navigation.The IAM portal opens.
In the main navigation, click API Keys, then click on the Create Key button.
The API Key configuration window opens.
You can optionally adjust the configuration as follows:
Note - Add a descriptive note to the API Key.
Expiration period - Adjust the period of time until the key expires. The value can be from 30 to 365 days.
Notice
If an administrator set the default expiration period to be "enforced", then this field will be locked.
Notification emails - Enter emails of each recipient who you would like to receive notifications regarding expiration of the key. After entering each email, click Add. By default the email of the current user is included.
Click Create.
The API Key is created and a window opens showing the key.
Copy the key and save it in a place where you will be able to retrieve it for future use.
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.
Open the CLI on your machine, and navigate to the CLI tool file location.
Run the
cx configurecommand.The CLI will prompt you to enter your credentials.
Skip the prompt for AST Tenant by hitting Enter.
When you are prompted Do you want to use API Key authentication?, enter "y".
When you are prompted for AST API Key, enter your API Key.
You can skip the rest of the prompts by hitting Enter.
Creating a Project
To create a new Project, use the project create command and enter a name for the project using the --project-name flag. See project create
./cx project create --project-name <Project name>
Running a Scan
To run a scan, use the scan create command and specify the project name, branch and 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 <Repository URL>
Viewing the Results
To view the scan results, use the results show command and provide the Scan ID you received after running the scan using the --scan-id flag. See results show
./cx results show --scan-id <Scan ID>