Bitbucket Cloud App PR scans

Learn how to enable PR scans using the Bitbucket Cloud App.
Beta

You can configure PR scans while creating a new Bitbucket Cloud App installation or for existing Bitbucket Cloud App integrations. Endor Labs automatically configures webhooks to scan your pull requests.

You can also choose to receive PR comments on your pull requests. After you configure PR comments, Endor Labs posts a comment on the pull request if any issues are detected during the PR scan. See Bitbucket Cloud PR comments for more information.

To enable PR scans and PR comments, you must provide an access token with read and write permissions for Webhooks and Pull requests, and read access for Projects. This access token allows Endor Labs to automatically configure webhooks for PR scanning functionality.

To create an access token:

  1. Sign in to Bitbucket Cloud and navigate to your workspace or project.

  2. Create a workspace access token or project access token. Ensure that you have a Bitbucket Cloud Premium account to create an access token at the workspace or project level.

  3. When creating the access token, ensure you select the following permissions:

    • Projects: Read
    • Webhooks: Read and Write
    • Pull requests: Read and Write
    • Repository: Read and Write

  4. Copy the generated access token and store it in a secure location. You need it when configuring the Bitbucket Cloud App integration in Endor Labs.

After you complete the initial installation of the Bitbucket Cloud App in Endor Labs, you can configure PR scans. At this point, the Bitbucket Cloud App will be operational.

You can also choose to apply PR scans to specific projects rather than all the projects in the workspace through a scan profile. See Scan profiles for more information.

  1. Select Pull Request Scans and enable it for automatic scanning of PRs submitted by users.

  2. Set the Scanning Preferences to:

    • Quick Scan for dependency resolution without reachability analysis. This provides rapid visibility into potential vulnerabilities for faster merges.
    • Full Scan (Reachability) for dependency resolution, reachability analysis, and call graph generation for supported languages. This provides full visibility but may take longer to complete.

    Pull request configurations in Bitbucket cloud

  3. Optionally, select Pull Request Comments to allow Endor Labs to comment on PRs for policy violations.

    When you enable PR comments, Endor Labs will post a comment on the pull request if any issues are detected during the PR scan. You need to set up PR comments in Endor Labs to receive the comments. See Bitbucket Cloud PR comments for more information.

  4. Click Save to save PR scan configuration.

Webhook Configuration
Endor Labs automatically generates and configures the webhook secret when PR scans are enabled. If you modify or delete the webhook in Bitbucket Cloud, you must delete and create a new Bitbucket Cloud App installation.

You can configure PR scans for existing Bitbucket Cloud integrations or after creating a new Bitbucket Cloud integration.

Permissions for the Access Token
The access token must have read and write permissions for Webhooks and Pull requests, as well as read access for Projects. See Create an access token for more information.
  1. Sign in to Endor Labs and select Integrations from the left sidebar.
  2. Click Manage in Bitbucket Cloud under Source Control Managers.
  3. Click the three dots menu next to the Bitbucket Cloud integration that you want to update.
  4. Select Edit Integration.
  5. Select Pull Request Scans in Integration Settings.

Edit Bitbucket Cloud PR settings

  1. Select Pull Request Scans to enable PR scans.

  2. Optionally, select Pull Request Comments to enable PR comments.

    Ensure that you complete the PR comments configuration in Endor Labs to receive the comments. See Bitbucket Cloud PR comments for more information.

  3. Click Save to save the changes.

    The changes are applied from the next scanning cycle.

Note
Click Rescan Org after editing the integration to apply changes immediately instead of waiting for the next scheduled scan.

You can configure PR scans and PR comments only for specific repositories. If you select the options to configure PR scans in your Bitbucket Cloud App integration, pull requests for all the repositories in your project or workspace are scanned. Instead, you can choose to configure PR scans and PR comments for selected repositories using scan profiles.

  1. Enable PR scans and PR comments during the initial Bitbucket Cloud App installation. This ensures that the webhooks are properly configured and recognized by Endor Labs.

  2. Edit the Bitbucket Cloud App integration and disable Pull Request Scans and Pull Request Comments. This prevents PR scans from running for all repositories in the workspace.

  3. Create a scan profile with Pull Request Scans and optionally Pull Request Comments enabled under Developer Workflow.

    Configure PR scans for selected projects

  4. Associate the scan profile with the specific repository where you want PR scans to run.

This approach allows you to control which repositories have PR scans enabled while ensuring that the webhook is properly configured during the initial installation.

PR comments are automated comments added to pull requests when Endor Labs detects policy violations or security issues during scans. When a PR is raised or updated, Endor Labs runs scans on the proposed changes and adds a comment if any violations are detected based on the configured action policies.

After you enable PR comments, you need to set up an action policy to allow comments to be posted on pull requests.

The action policy that you create triggers the posting of comments on your pull request after a scan is complete. See Action policy for more information. You can create multiple action policies based on your requirements, which the PR scan can trigger. If you create action policy with the Secret template, you get an inline comment with the line number where the secret is detected.

Ensure that you configure the following important settings in the action policy:

  1. Choose an appropriate action policy template or create a custom action policy.

    You can choose an action policy template like Containers or create a custom action policy.

  2. Under Action, select Enforce Policy, then choose:

    • Warn to post a comment without breaking the build.
    • Break the Build to fail the build and block the pull request.

  3. Define the scope of the policy using tags. Only projects that match the specified tags will receive PR comments.

  4. Select Propagate this policy to all child namespaces if you want to apply the policy to all child namespaces.

Action policy propagation in child namespaces
If you select Propagate this policy to all child namespaces, and update the policy in the child namespace, the policy in the child namespace takes precedence over the policy in the parent namespace. If you select the propagate option for the child namespace, its child namespaces will also inherit the policy. Since namespace hierarchy follows the workspace and projects hierarchy of Bitbucket Cloud, you can effectively use this option to control the policy for different levels of your organization.

Endor Labs provides a default template for PR comments that you can use out-of-the-box. You can also create custom templates using Go Templates.

The following section shows the default template for PR comments.

The file /content/includes/bitbucket_cloud_pr_comment_template.txt was not found.

You can create your custom template by editing the default template and saving the changes.

The following specification shows the additional functions that you can use in your custom template. You can access these functions by using their corresponding keys.

The file /content/includes/bitbucket_cloud_pr_comment_func_map.txt was not found.

To edit the default template:

  1. Select Manage > Integrations from the left sidebar.

  2. Click Edit Template next to Bitbucket Cloud under Template for PR Comments.

    Bitbucket Cloud only supports markdown in PR comments and does not support HTML tags.

  3. Update the template with the required changes.

  4. Select Propagate this template to all child namespaces if you want to apply the template to all child namespaces.

Template propagation in child namespaces
If you select Propagate this template to all child namespaces, and update the template in the child namespace, the template in the child namespace takes precedence over the template in the parent namespace. If you select the propagate option for the child namespace, its child namespaces will also inherit the template. Since namespace hierarchy follows the workspace and projects hierarchy of Bitbucket Cloud, you can effectively use this option to control the template for different levels of your organization.
  1. Click Save Template to save the changes.
Restore the default template
You can restore the default template by clicking Restore to Default in the template editor to go back to the initial template.

After you enable PR comments, Endor Labs posts a comment on the pull request if any issues are detected during the PR scan based on the action policies.

The following example shows a comment on the pull request as a result of the action policy for identifying leaked secrets.

You can expand and view the details of the finding.

Click Link to Finding to view the details of the finding in Endor Labs.

For secrets, Endor Labs also generates a comment with the line number where the secret is detected.

When you create a new pull request, the Endor Labs Bitbucket Cloud App scans the pull request. Endor Labs generates findings based on the finding policy.

  1. Sign in to Endor Labs and select Projects from the left sidebar.

  2. Select the project for which you want to view the PR scan findings.

  3. Select PR runs to view the PR scan findings.

    View PR scan findings

  4. Select the PR for which you want to view the findings.

    View PR scan findings

  5. Click View Findings to view the findings on the PR.

    View PR scan findings in detail

See View Findings for more information on Findings in Endor Labs.