Skip to main content

Azure DevOps 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 Azure DevOps integration, enabling automated scanning of your Azure DevOps projects whenever the code is updated. Checkmarx One's Azure DevOps integration listens for Azure DevOps 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 the Checkmarx One Platform.

Additionally, for pull requests, a comment is created in Azure DevOps, which includes a scan summary, list of vulnerabilities and a link to 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 Azure DevOps repository. You can select several repositories to create multiple integrations in a bulk action.

Notice

This integration supports both public and private git based repos.

Prerequisites

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

    Warning

    Checkmarx One does not support integration with Azure DevOps Server 2019. If you require integration, consider upgrading to a newer version of ADO.

  • 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 Azure DevOps user has admin privileges for this repo, see Code Repository Integrations.

  • Verify that in the Azure DevOps Organization settings under Organization Settings → Policies → “Third-Party application access via OAuth” is enabled - For additional assistance use the following link: Azure DevOps connection and security policies.

    For example:

    6297288859.png

Generate a PAT in Azure DevOps

To generate a PAT for the relevant organization in Azure DevOps, perform the following steps:

  1. In your Azure DevOps account go to the organization for which you want to set up the integration.

  2. Click on your user > Security.

    Azure_SH_Security.png

  3. Click on Personal Access Tokens > + New Token.

    A panel will be opened on the right screen side.

  4. Configure the following fields:

    • Name - Token name.

    • Organization - Select the current organization.

      Note

      Alternatively, you can configure the integration using All accessible organizations. This option is not recommended, as it grants broader access than required (violating least-privilege principles) and is scheduled for deprecation by Microsoft. To connect multiple organizations, we recommend creating a separate PAT for each organization and adding each organization individually.

    • Scopes - Custom defined.

      • Code - Read, Status.

      • Pull Request Thread - Read & write.

        Azure_SH_Config_Token.png
        Azure_SH_Config_Token2.png

    • Click Create.

  5. Copy the token.

    Azure_SH_Copy_Token.png

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 Azure 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. You can also add additional organizations to an existing configuration.

To create Azure DevOps 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_558.png

  2. Select Self-Hosted > Azure.

    azureimport.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 Azure DevOps self-managed domain.

        For example: https://azure.example.com

      • Organization - Enter the Azure DevOps organization name. This value must be an exact match and is recommended to be copied directly from Azure DevOps.

        Notice

        If you would like to add additional organizations to this configuration, you can do so by clicking +Add Organization, as described below.

      • Token - Enter a Personal Access Token associated with the specified organization. Each Azure DevOps organization requires its own PAT. See Generate a PAT in Azure DevOps for retrieving your Azure DevOps token.

        azureA.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.

      azureB.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.

      azureC.png

      Notice

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

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

    You can use the search field to quickly locate a specific organization.

    You can also choose whether to enable the Monitor New Repositories feature by using the toggle next to "Automatically sync with new or transferred projects in the organization."

    For more information about this feature, see Monitor New Repositories.

    Image_124.png

    If the required organization is not listed, click + Add Organization, enter the Organization name (exact match) and a Token (PAT) scoped to that organization, then click Save and Close.

    Image_1055.png

    The Add Organization dialog opens. Fill in the Organization name (exact match) and the Token (PAT) for that organization.

    Image_1086.png

  5. Select Repositories inside the Azure Import 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.

    Image_125.png

    Notice

    You will be able to add additional repos from an organization that has been connected in a previous integration. However, the organization will only be saved once you complete the entire flow of connecting at least one repo from that organization.

  6. In the Repositories Settings step, you can optionally adjust the settings as follows:

    Image_389.png

    • If the project has multiple repositories, click All Repositories Settings to adjust the settings for all repositories, or select a specific repository, to adjust the settings for that repository.

    • Expand the Permissions Settings and adjust the following 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 (when a specific repository is selected): Specify the branches to be designated as "Protected Branches".

      Notice

      Specifying a branch as a Protected Branch affects three main areas: scan triggering (for PR and push), policy violation detection, and Feedback App notifications.

      You can also use a wildcard symbol "*" to designate which branches are protected. The wildcard can be used before the string, after the string, or both. All branches that match the wildcard pattern will be treated as protected branches.

      Notice

      Examples:

      • * → all branches

      • release* → branches that begin with "release"

      • *release → branches that end with "release"

      • * release * → branches that contain "release" anywhere in the name

      • Tags - For each protected branch, you can optionally assign Tags. When a scan is triggered for this branch (e.g., push or pull request), these tags will automatically be applied to the scan.

        Tags can be key:value pairs or simple values. For example, env:prod or security.

    • Add SSH key (when a specific repository is selected).

    • 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's criticality level.

  7. Click Next.

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

    For each repository, select the protected branches you want to scan during project creation, and then click Create Project.

    Image_127.png

  9. A Project is created for each repository and a scan is initiated for each project. The new projects are displayed on the Projects page,

    GitHub_scan_initiated.png

    Note

    In order to update the scanners see Imported Project Settings

Editing Project Settings

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

In this section: