Skip to main content

Checkmarx One Jenkins Plugin - Installation and Initial Setup

First, you need to install the plugin. Then you can configure the CLI Tool installation and the plugin’s global settings. Once that is in place, you can start creating Checkmarx One build steps in Jenkins.

Installing the Jenkins Checkmarx One Plugin

The Checkmarx One Jenkins plugin can be installed using any one of the following methods.

Installing Checkmarx One Jenkins Plugin from the Marketplace

  1. Go to your Jenkins Dashboard and select Manage Jenkins > Manage Plugins.

    5973114916.png

  2. Click on the Available tab and enter “checkmarx ast” in the search box.

  3. Select the checkbox next to Checkmarx One scanner and click on Download now and install after restart.

    6287328700.png

    The plugin is installed.

Install Checkmarx One Jenkins plugin using the HPI file

A Jenkins administrator can install the plugin by uploading the HPI file via the Jenkins UI.

  1. Go to the Checkmarx One Jenkins Plugin download page.

  2. Scroll down to the desired version (recommended to install the latest version), and click on the direct link to download the file.

    5975146533.png

  3. Go to your Jenkins Dashboard and select Manage Jenkins > Manage Plugins.

    5973114916.png

  4. Click on the Advanced tab.

    5973114922.png

  5. In the Upload Plugin section, click on Choose File and navigate to the “checkmarx-ast-scanner.hpi” file that you downloaded. Then, click on the Upload button.

    The installation window is displayed. When the installation is finished, you will be prompted to restart the Jenkins server.

    5973114928.png

Install Checkmarx One Jenkins plugin using command line

Jenkins provides a CLI tool that allows administrators to install plugins from the command line.

To install the latest version of the Checkmarx One Jenkins plugin, run the following command in the Jenkins CLI.

Note

The following is a description of the elements of this command and the available arguments.

java -jar jenkins-cli.jar -s http://{JenkinsURL}/ install-plugin SOURCE ... [-deploy] [-name VAL] [-restart]

This command installs a plugin either from a file, a URL, or from update center.

SOURCE : If this points to a local file, that file will be installed. If this is a URL, Jenkins downloads the URL and installs the plugin. Otherwise the name is assumed to be the short name of the plugin in the existing update center (like "findbugs"), and the plugin will be installed from the update center.

-deploy : Deploy plugins right away without postponing them until the reboot.

-name VAL : If specified, the plugin will be installed as this short name (by default the name is inferred from the source name automatically).

-restart : Restart Jenkins upon successful installation.

Installing the CLI Tool (Required)

Because the Jenkins plugin acts as a wrapper around the Checkmarx One CLI tool, you need to install the CLI tool itself in Jenkins.

This can be done automatically or you can manually configure the installation.

To install the CLI tool:

  1. In the main navigation, click Manage Jenkins.

    5969119681.png

  2. Click on Global Tool Configuration.

    162d7918d72911.png

  3. Scroll down to the Checkmarx section and click on the Add Checkmarx button.

    5969185016.png

    The Checkmarx installation fields are displayed.

    5970167794.png

  4. In the Name field, enter a name for the installation (required).

  5. By default, Install automatically is selected, theInstallermethod is “Checkmarx.com”, the Version is specified as “latest”, and the Update policy interval (hours) is specified as “24”. This will ensure that every day you will have the latest version of the CLI tool installed in Jenkins. The following options are also available:

    • You can change the automatic installation settings from the default configuration, but this is generally not recommended.

    • You can add additional Installers for the Checkmarx CLI tool by clicking on Add Installer and then selecting the type of installer and filling in the required fields.

    • If you would like to install Checkmarx manually from a specific directory, then deselect Install automatically, and enter the location of theInstallation directory.

  6. Click Save at the bottom of the screen.

    5971673096.png

    The CLI is configured, and you are returned to the System Configuration screen.

Configuring Global Settings

The global settings are used as the default configuration for your Checkmarx projects. They can be overridden by specifying different settings for individual projects.

In order to configure the global settings you need to have the Client ID and Client Secret for an OAuth Client in Checkmarx One, see Creating an OAuth Client for Checkmarx One Integrations.

Note

Configuring global settings is recommended best practice, although it isn’t required. Alternatively, it is possible to configure all of the settings within the build step for each project.

To configure the global settings for Checkmarx One:

  1. In the main navigation, click Manage Jenkins. Then click Configure System.

  2. Scroll down to the Checkmarx section.

    5972886090.png

  3. Fill in the Checkmarx server URL with the appropriate URL for your environment.

  4. If the authentication URL is different that the server URL, then leave the Use Authentication URL selected (default), and enter the appropriate authentication URL.

    Notice

    For Checkmarx One cloud platform, leave the checkbox selected and enter the URL for your environment.

  5. For Tenant Name, enter the name of your Checkmarx One Tenant account.

  6. For Credentials, click Add and select Jenkins.

    5972918327.png

    The Add Credentials window opens.

  7. ForDomain, select Global credentials (default).

  8. For Kind, select Checkmarx Client Id and Client Secret.

    The Add Credentials window options are updated.

    6013452345.png

  9. For Scope select Global (default).

  10. In the Client Id and Secret fields, enter your Checkmarx One OAuth Client ID and Secret.

    Notice

    If you need to create an OAuth client, see Creating an OAuth Client for Checkmarx One Integrations.

  11. In the ID field, it is recommended to give a descriptive name to these credentials (e.g., AST_Credentials) in order to make it easy to identify in the future.

  12. In the Description field, optionally add a description to help distinguish between similar credentials.

  13. Click Add.

  14. Back in the main screen, under Credentials, select from the dropdown list the ID of the credentials that you just configured.

  15. Under Checkmarx Installation, verify that the Checkmarx One CLI installation that you previously configured is selected.

  16. If you want to test your connection, optionally click Test Connection.

  17. In the Additional Arguments section you can specify any CLI arguments that you would like to apply to scans of this project. See documentation here.

    Notice

    Make sure that all argument values are inside double quotes (not single quotes) when using pipeline scripts.

    Notice

    By default all scanners that you are authorized to run (licensed or open source) will run. To limit scans to one or more specific scanners, add the argument --scan-types {scanner} , where {scanner} is one or more of the following scanners sast or sca or kics.

  18. Click Save at the bottom of the screen.

Setting up a Proxy Environment Variable (Optional)

To set up an environment variable:

  1. In the main navigation, click on Manage Jenkins, then click Configure Settings.

    6151831832.bmp

  2. Scroll down to the Global Properties section, select the Environment variables checkbox and then click Add.

    6151831839.bmp

  3. In the Value field, enter the proxy address, e.g., http://proxyuser:proxypassword@localhost:3128.

    6151831845.bmp

  4. Click Save at the bottom of the screen.

  5. If the environment variable in Jenkins is named "HTTP_PROXY", the plugin uses the proxy automatically.

In this section: