Configuring the Checkmarx One CLI
Configuration Methods
CLI configuration parameters can be submitted using three different methods, as follows:
CLI parameters - when submitting any CLI command you can add the configuration parameters.
Configuration file - a configuration file can be created by running the CLI
configurecommand. See configureNote
The Configuration files are kept in the users home directory under a subdirectory named ($HOME/.checkmarx)
Environment variables - the environment variables of your system.
Variables Hierarchy
When variables are submitted using multiple methods, the following precedence is used when there is a conflict between the different provided values:
CLI parameters
Configuration file
Environment variables
Authentication
In order to submit CLI commands you need to be authenticated for your Checkmarx One account. The required authentication parameters can be submitted as part of the CLI command or via Config or Environment variables, see Using Checkmarx One CLI Variables. Authentication can be done either via an OAuth Client or an API Key.
Required Parameters
The following parameters are required for authentication, depending on the type of authentication used.
cx_apikey
To generate an API Key use the following procedure:
Creating an API Key for Checkmarx One Integrations 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 11.
GIF - How to generate an API Key
To generate an API Key:
Log in to the Checkmarx One web portal and select
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.
Notice
The CLI automatically extracts all relevant account info (Base URL, Auth URL, Tenant name) from the API Key. You can use arguments to submit these values explicitly, overriding the extracted values. However, this is generally not recommended.
cx_base_uri
cx_base_auth_uri
cx_tenant
cx_client_id
cx_client_secret
To create an OAuth client, use the following procedure:
Creating an OAuth Client for Checkmarx One Integrations You can create an OAuth Client by logging in to Checkmarx One and creating a new client.
Figure 12.
GIF - How to create an OAuth Client for use with plugins
To create an OAuth Client:
Logging in to Checkmarx One 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
To create an OAuth Client, you need to be signed in as an admin user.
Creating an OAuth Client Figure 13.GIF - How to create an OAuth Client
To create an OAuth Client:
Log in to Checkmarx One and click on the
Identity and Access Management icon in the Menu panel.
In the Identity and Access Management console, click OAuth Clients and then click Create Client.
In the Client ID field, enter a descriptive name for Client, and then click Create client.
The Client Settings screen is shown.
Copy the Client ID for use in the plugin configuration.
Click on the Regenerate button to generate the Secret,
In the dialog that opens, copy the Secret for use in the plugin configuration, and then click Ok to close the dialog
You can optionally adjust the Settings as follows:
Name - Specify the name that will be displayed for this Client.
Other - Enter additional information about this Client.
Description - Enter a description of this Client.
Expiration period - Specify 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.
Days before notification - Specify the number of days before the Client will expire that notifications will start being sent. Notifications will be sent on a daily basis from the day on.
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.
Under Groups, you can optionally assign the Client to one or more groups.
Under Role Mapping > AST roles, search for either ast-admin or ast-scanner and click Add in the relevant row to add the role to the client.
Click Save Client.