Skip to main content

Bitbucket Self-Hosted

Notice

It is possible to add the Checkmarx One external IP addresses to the customer Firewall allowlist - For more information see Managing Checkmarx One Traffic and AWS S3 Access

Additionally, if the code repository is not internet accessible, it is possible to configure the code repository IP address instead of its hostname during the initial integration with the code repository - as it is not resolved via DNS.

Overview

Checkmarx One supports Bitbucket integration, enabling automated scanning of your Bitbucket projects whenever the code is updated. Checkmarx One’s Bitbucket integration listens for Bitbucket commit events and uses a webhook to trigger Checkmarx scans when a push, or a pull request occurs. Once a scan is completed, the results can be viewed in Checkmarx One.

Additionally, for pull requests, a comment is created in Bitbucket, which includes a scan summary, list of vulnerabilities and a link to view the scan results in Checkmarx One.

The integration is performed on a per-project basis, where a dedicated Checkmarx One Project corresponds to a specific Bitbucket repository. You can select several repositories to create multiple integrations in a bulk action.

It is possible to configure multiple configurations for connecting to Bitbucket self-hosted code repositories, each using a different URL and/or different authentication credentials. Once the initial configuration is set up, for each subsequent import action you can choose either to use the existing configuration or to create a new one.

Notice

This integration supports both public and private git based repos.

Prerequisites

  • The source code for your project is hosted on a Bitbucket repo.

  • You have a Checkmarx One account and have credentials to log in to your account.

    Important

    Creating new import configurations or editing existing configurations requires update-tenant-params permission. Importing new Projects using an existing configuration requires create-project permission.

    Our best practice recommendation is to create a dedicated service user for the purpose of creating the integration. This will ensure that scans created via the integration will have a representative name.

  • The Bitbucket user has Admin privileges for this repository, see Code Repository Integrations.

Retrieving Bitbucket Username & Token

To integrate Bitbucket self-hosted with Checkmarx One, a Bitbucket authentication token is required.

Bitbucket versions below 7.18

Older Bitbucket versions (below 7.18) use Personal Access tokens. For more details, refer to Personal Access tokens.

Bitbucket 7.18 and above

In newer versions of Bitbucket (7.18 and above), Personal Access tokens have been replaced with HTTP Access tokens.

HTTP Access tokens can be associated with a Bitbucket user account, project, or repository. For more details, refer to HTTP Access tokens. Checkmarx One only supports HTTP Access tokens linked to a user account.

Note

The example below relates to Bitbucket self-hosted versions below 7.18

To retrieve your Bitbucket Username & Token, perform the following steps:

  1. In your Bitbucket account, click on your user > View Profile.

    Bitbucket_View_Profile.png

  2. Retrieve your Username.

    Bitbucket_Username.png

  3. To create a Token, click on your user > Manage account.

    Bitbucket_Manage_Account.png

  4. Click on Personal access tokens.

    Bitbucket_Personal_Access_Tokens.png

  5. Click on Create a token.

    Bitbucket_Create_Token.png

  6. Give the token at least Read permissions for Projects and Repositories.

    Bitbucket_SH_PAT.png

  7. Click Create.

Setting up the Integration and Initiating a Scan

This process involves first connecting to your repo by specifying the repo URL and your authentication credentials, and then selecting the repos to import and configuring the Project settings.

It is possible to configure multiple configurations for connecting to Bitbucket self-hosted code repositories, each using a different URL and/or different authentication credentials. Once the initial configuration is set up, for each subsequent import action you can choose either to use the existing configuration or to create a new one.

To create Bitbucket self-hosted code repository Projects:

  1. In the Workspace Workspace.png, click on New > New Project - Code Repository Integration

    Code_Repo_Integration.png

    The Import From window opens.

    Image_946.png

  2. Select Self-Hosted > Bitbucket.

    Image_043.png

  3. Configure the connection to your code repository, as follows:

    • If you are setting up an import configuration for the first time, enter data for the following fields and then click Save & Continue.

      • Instance Name - Designate a name for this import configuration.

      • URL - Your Bitbucket self-managed domain.

        For example: https://bitbucket.example.com

      • Token - see Retrieving Bitbucket Username & Token for retrieving your Bitbucket token.

        Image_044.png

    • If you are adding Projects using an existing configuration, select the radio button next to the configuration that you would like to use, and then click Next.

      Image_045.png

    • If you are adding a new configuration in addition to an existing configuration, click + Add Configuration, then fill in the data for this configuration as described above, and then click Save & Continue.

      Image_046.png

      Notice

      If you would like to edit an existing configuration (e.g., change the URL or credentials), go to Global Settings > Code Repository.

  4. Select the Bitbucket Organization or Group (for the requested repository) and click Select Organization.

    The screen contains the following functionalities:

    • Search bar - Auto-complete is implemented. The search is not case sensitive.

    • Infinite scroll - For enterprises with a large amount of organizations.

    GitHub_Select_Org.png

  5. Select Repositories inside the Bitbucket organization and click Select Repositories.

    If the organization contains active repositories, suggested repos will be presented and selected automatically. For additional information see Suggested Repositories.

    Note

    • A separate Checkmarx One Project will be created for each repo that you import.

    • There can’t be more than one Checkmarx One Project per repo. Therefore, once a Project has been created for a repo, that repo is greyed out in the Import dialog.

    GitHub_Select_Repo.png

  6. In the Repositories Settings screen, if you need to adjust the settings, configure the following and click Next.

    Note

    If multiple repositories are selected, click All Repositories Settings to apply changes to all of them. To adjust settings for a specific repository, click that repository’s name.

    Image_232.png

    • Expand the Permissions Settings:

      • Scan Trigger: Push, Pull request - Automatically trigger a scan when a push event or pull request is done in your SCM. (Default: On)

      • Pull Request Decoration - Automatically send the scan results summary to the SCM. (Default: On)

      • SCA Auto Pull Request - Automatically send PRs to your SCM with recommended changes in the manifest file, in order to replace the vulnerable package versions. (Default: Off)

    • Expand the Scanner Settings: and enable the toggle for each scanner you want to use (SAST, SCA, IaC Security, Container Security, API Security, OSSF Scorecard, Secret Detection) for your repositories. At least 1 scanner must be selected for each repository.

    • Protected Branches: Select which Protected Branches to scan for each repository.

      Note

      For additional information about Protected Branches see About Protected Branches

    • Add SSH key.

    • Assign Groups: Add Groups to the Project. Groups can be added as a simple strings or as key:value pairs.

    • Assign Tags: Add Tags to the Project. Tags can be added as a simple strings or as key:value pairs.

    • Set Criticality Level: Manually set the project criticality level.

      Image_232.png

  7. In the Protected Branches screen you can decide whether to enable the "Scan the default Branch upon the creation of the project" feature.

    Next, Select which Protected Branches you want to scan for each Repository and click Create Project.

    Note

    For additional information about Protected Branches see About Protected Branches

    Image_235.png

  8. The Project is successfully added to the Projects page.

Editing Project Settings

To learn about editing Project Settings for an existing code repository integration Project, see Code Repository Project Settings.

In this section: