This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Deploy Endor Labs Bitbucket App in Bitbucket Cloud

Learn how to continuously monitor your environment with the Endor Labs Bitbucket App.

Table of Contents

This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Learn how to continuously monitor your environment with the Endor Labs Bitbucket App.

Endor Labs provides a Bitbucket App that continuously monitors users’ projects for security and operational risks in Bitbucket Cloud. You can use the Bitbucket App to selectively scan your repositories for SCA, secrets, and SAST.

When you use the Endor Labs Bitbucket App, it creates namespaces based on your workspace and projects in Bitbucket Cloud. The namespaces created by the Endor Labs Bitbucket App are not like regular namespaces and are called managed namespaces. You can either configure the URL to Bitbucket Cloud to import all the projects or configure the project key to import a specific project in Endor Labs.

Note
The following characters are allowed in Endor Labs namespaces: lowercase letters (a–z), digits (0–9), hyphens (-), and underscores (_). Additionally, the namespace is limited to a maximum of 64 characters in length. If the Bitbucket host or your projects have a different naming convention, the corresponding namespaces will be converted to comply with the naming convention of Endor Labs namespaces.

See Manage Bitbucket Cloud App to learn how to manage your Bitbucket Cloud App integration in Endor Labs.

You need to add the Bitbucket Cloud workspace or a project to an Endor Labs namespace. Bitbucket Cloud workspace and projects are mapped as managed namespaces in Endor Labs.

Managed namespaces have the following restrictions:

  • You cannot delete managed namespaces.
  • You cannot delete repositories within managed namespaces.
  • You cannot add projects or create namespaces within managed namespaces.
  • You cannot create new Endor Labs App installations within managed namespaces.

When you add a Bitbucket Cloud workspace to an Endor Labs namespace, Endor Labs creates a child namespace for the Bitbucket Cloud workspace and creates child namespaces for each project in the workspace under the workspace namespace. The namespaces of the workspace and projects are managed namespaces. You can add multiple Bitbucket Cloud workspaces to the same Endor Labs namespace. Each workspace will have its own managed namespace.

If your workspace name is deerinc and you have three projects, buck, doe, and fawn, Endor Labs creates four managed namespaces: deerinc, buck, doe, and fawn. The namespaces buck, doe, and fawn are child namespaces of the deerinc namespace.

The following image shows the namespace structure in Endor Labs.

graph TD

      %% Endor Labs namespace
      EN[endor-bitbucket]

      %% Bitbucket projects
      O1[deerinc]
      P1[buck]
      P2[doe]
      P3[fawn]


      %% connections
      EN --> O1
      O1 --> P1
      O1 --> P2
      O1 --> P3

      class EN,EN2 endor
      class O1,P1,P2,P3 managed
      classDef managed fill:#5EEAD4

When you add a Bitbucket Cloud project to an Endor Labs namespace, Endor Labs creates a child namespace for the Bitbucket Cloud project and maps all repositories in that project to this namespace. The child namespace that maps to the Bitbucket Cloud project is a managed namespace. The managed namespace has the name, <workspace name>_<project name>. For example, if your Bitbucket Cloud workspace name is deerinc and project name is doe, the managed namespace will have the name, deerinc_doe.

You can add multiple projects to the same Endor Labs namespace. Each project will have its own managed namespace. For example, your workspace name is deerinc, which has three projects, buck,doe, andfawn. You add each project to the Endor Labs namespace, endor-bitbucket.

The following image shows the namespace structure in Endor Labs.

graph TD

      %% Endor Labs namespace
      EN[endor-bitbucket]

      %% Bitbucket projects
      A1[deerinc_buck]
      A2[deerinc_doe]
      A3[deerinc_fawn]


      %% connections
      EN --> A1
      EN --> A2
      EN --> A3

      class EN,EN2 endor
      class A1,A2,A3 managed
      classDef managed fill:#5EEAD4

When Endor Labs scans a repository for the first time, it detects the default branch of the repository. The findings that are created in the scan are associated with the default branch.

When you change the default branch in your source control system (for example, from main to dev):

  • Endor Labs automatically detects the new default branch and sets that as the default reference
  • The previous default branch becomes a reference branch
  • Scans continue on the new default branch and the reference branch

The findings associated with the previous default branch are no longer associated with the default context reference. You can view them in the reference context.

When you rename the default branch in your source control system:

  • Endor Labs automatically switches to the renamed branch
  • Scans continue without disruption

When you add a new repository version (for example, a dev branch), both the default branch and the new version are scanned by the Endor Labs App.

You can control the default branch detection by setting the ENDOR_SCAN_TRACK_DEFAULT_BRANCH environment variable in a scan profile. You need to configure the project to use the scan profile. See Configure scan profiles for more information.

By default, the environment variable is set to true. When set to true, the default branch detection is enabled, and the first branch you scan is automatically considered as the default branch.

Ensure the following prerequisites are in place before you install the Endor Labs Bitbucket App.

  • Bitbucket Cloud instance with workspace and projects
  • A Bitbucket access token either at the workspace level to import a workspace, or the project level to import a project. The token must have at least Project read permission.
Note
Endor Labs Bitbucket App for Bitbucket Cloud requires a Bitbucket Cloud premium plan since Bitbucket Cloud standard plan does not support project-level access tokens.

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

  2. Click Add Project.

  3. Select Bitbucket on the Scan your repositories page.

  4. Select Bitbucket Cloud.

    Bitbucket App

  5. Enter the Bitbucket Cloud workspace URL.

    • To import all the projects in the workspace, provide the workspace URL in the format https://bitbucket.org/{workspace}.
    • To import a specific project, provide the project URL in the format https://bitbucket.org/{workspace}/projects/{project-key}. For example, https://bitbucket.org/endor-labs/projects/lab.

    Endor Labs creates namespaces for all projects that are available in the Bitbucket Cloud workspace.

  6. Enter the Bitbucket access token.

Permissions for the Access Token

The access token must have at least the Project:read permission.

If you want to scan pull requests, you need to provide an access token with read and write permissions for Webhooks and Pull requests, as well as read access for Projects. For more information, see Create an access token.

  1. Select the scan types to enable in SCANNERS.

    • SCA: Perform software composition analysis and discover AI models used in your repository.
    • Secret: Scan Bitbucket projects for exposed secrets.
    • SAST: Scan Bitbucket projects to generate SAST findings.

    The available scan types depend upon your license.

  2. Click Create.

  3. Optionally, you can continue to Configure Bitbucket Cloud App PR scans to scan your pull requests.

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

    You can also enable PR scans later in the Bitbucket Cloud App integration.

Endor Labs Bitbucket Cloud App scans your Bitbucket projects every 24 house and reports any new findings or changes to release versions of your code.

Bitbucket Cloud App PR scans

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.

{{- /* Do not modify the placement of the CommentHeader.
It is being used to identify the comments generated by Endor Labs. */ -}}
{{ .CommentHeader.Value }}

{{ $policiesTriggeredNumber := len .PolicyFindingsMap }}
{{ $dataMap := .DataMap }}
{{ $findingsMap := .FindingsMap }}
{{ $packageVersionsMap := .PackageVersionsMap }}
{{ $apiURL := .ApiEndpoint.Value }}
{{ $totalFindings := getTotalFindingsCount $dataMap }}

{{/* ALERT BANNER */}}
> **:warning: WARNING**
> Endor Labs detected {{ $policiesTriggeredNumber }} policy violations associated with this pull request.

Please review the findings that caused the policy violations.

## Summary

- **Policies:** {{ $policiesTriggeredNumber }}
- **Total Findings:** {{ $totalFindings }}

---

{{ range $policyUUID, $policyName := .PoliciesMap }}
{{ $policyFindings := index $dataMap $policyUUID }}
{{/* POLICY HEADER */}}
## :clipboard: Policy: {{ $policyName }} ({{ getFindingsCountString $policyFindings }})

{{ range $packageVersionUUID, $packageVersionFindings := $policyFindings.PackageToDependencies }}
{{ if ne getOtherFindingsPackageMarker $packageVersionUUID }}
{{ $packageVersionObject := index $packageVersionsMap $packageVersionUUID }}
{{ if $packageVersionObject }}
{{/* PACKAGE HEADER */}}
- **:inbox_tray: Package:** [{{ $packageVersionObject.Meta.Name.Value }}]({{ getPackageVersionURL $apiURL $packageVersionObject }})
{{ range $dependencyName, $dependencyFindings := $packageVersionFindings.DependencyToFindings }}

{{/* DEPENDENCY HEADER */}}
  - **:arrow_heading_down: Dependency:** [{{ $dependencyName }}]({{ $dependencyName }})
{{ range $findingCounter, $findingUUID := $dependencyFindings.Uuids }}
{{ $findingObj := index $findingsMap $findingUUID }}

{{/* FINDING HEADER */}}
    - **:triangular_flag_on_post: Finding:** [{{ $findingObj.Meta.Description.Value }}]({{ getFindingURL $apiURL $findingObj }})

{{/* FINDING DETAILS */}}
      - **[Details]({{ getFindingURL $apiURL $findingObj }})**
      - **Severity:** ` + "`" + `{{ enumToString $findingObj.Spec.Level }}` + "`" + `
      - **Tags:** {{ range $i, $t := $findingObj.Spec.FindingTags }}` + "`" + `{{ enumToString $t }}` + "`" + ` {{ end }}
      - **Categories:** {{ range $i, $c := $findingObj.Spec.FindingCategories }}` + "`" + `{{ enumToString $c }}` + "`" + ` {{ end }}
{{- with getFirstPartyReachableFunctions $findingObj }}
      - **Reachable via:** ` + "`" + `{{ . }}` + "`" + `
{{- end }}
      - **Remediation:** {{ fixBackticks $findingObj.Spec.Remediation.Value }}

{{ end }} {{/*range $findingCounter, $findingUUID...*/}}
{{ end }} {{/*range $dependencyName, $depend...*/}}
{{ end }}  {{/* if $packageVersionObject */}}
{{ else }} {{/* if ne getOtherFindingsPackageMarker... */}}
{{ $depMarker := getOtherFindingsDependencyMarker }}
{{ $otherFindings := index $packageVersionFindings.DependencyToFindings $depMarker }}
{{ $otherFindingsLen := len $otherFindings.Uuids }}
{{ if ne $otherFindingsLen 0 }}
{{/* OTHER FINDINGS HEADER */}}
- **:mag: Findings**
{{ range $findingCounter, $findingUUID := $otherFindings.Uuids }}
{{ $findingObj := index $findingsMap $findingUUID }}

{{/* FINDING HEADER */}}
   - **:triangular_flag_on_post: Finding:** [{{ $findingObj.Meta.Description.Value }}]({{ getFindingURL $apiURL $findingObj }})

{{/* FINDING DETAILS */}}
    - **[Link To Finding]({{ getFindingURL $apiURL $findingObj }})**
    - **Severity:** ` + "`" + `{{ enumToString $findingObj.Spec.Level }}` + "`" + `
    - **Tags:** {{ range $i, $t := $findingObj.Spec.FindingTags }}` + "`" + `{{ enumToString $t }}` + "`" + ` {{ end }}
    - **Categories:** {{ range $i, $c := $findingObj.Spec.FindingCategories }}` + "`" + `{{ enumToString $c }}` + "`" + ` {{ end }}
    - **Summary:** {{ $findingObj.Spec.Summary.Value }}
    - **Remediation:** {{ fixBackticks $findingObj.Spec.Remediation.Value }}
{{- if hasFindingCategory $findingObj "SAST" }}
    - **Location:** {{ getCustomLocation $findingObj }}
{{- if isNotEmptyString (getCustomCodeSnippet $findingObj) }}
    - **Code Snippet:**
` + "```" + `
{{ getCustomCodeSnippet $findingObj }}
` + "```" + `
{{- end }}
{{- end }}

{{ end }} {{/*range $findingCounter, $findingUUID...*/}}
{{ end }} {{/*{{ if ne $otherFindingsLen 0*/}}
{{ end }} {{/* if ne getOtherFindingsPackageMarker... */}}
{{ end }} {{/* range $packageVersionUUID, $packageVersionFindings := $policyFindings */}}
{{ end}}  {{/* {{ range $policyUUID, $policyObj := .PoliciesMap */}}

{{ .CommentFooter.Value }}
_Scanned @ {{ now }} UTC_

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.


// FuncMap contains additional template functions used in GitLab comment templates.
var FuncMap = template.FuncMap{
	"now":                              utils.ToTime,
	"enumToString":                     utils.EnumToString,
	"getFindingURL":                    utils.GetFindingURL,
	"getPackageVersionURL":             utils.GetPackageVersionURL,
	"getPullRequestURL":                getEndorLabsPullRequestRunURL,
	"getFindingsCountString":           utils.GetFindingsCountString,
	"hasOtherFindings":                 hasOtherFindings,
	"getOtherFindingsPackageMarker":    getOtherFindingsPackageMarker,
	"getOtherFindingsDependencyMarker": getOtherFindingsDependencyMarker,
	"fixBackticks":                     utils.FixUnclosedBackticks,
	"getFirstPartyReachableFunctions":  utils.GetFirstPartyReachableFunctions,
	"hasFindingCategory":               utils.HasFindingCategory,
	// isNotEmptyString checks if a string is not empty
	"isNotEmptyString": utils.IsNotEmptyString,
	// getCustomLocation extracts the location from Custom field
	"getCustomLocation": func(finding *endorpb.Finding) string {
		return utils.GetCustomFieldValue(finding, "location")
	},
	// getCustomCodeSnippet extracts the code snippet from Custom field
	"getCustomCodeSnippet": func(finding *endorpb.Finding) string {
		return utils.GetCustomFieldValue(finding, "code_snippet")
	},
	// add returns the sum of two integers
	"add": func(n int, incr int) int {
		return n + incr
	},
	// getTotalFindingsCount returns the total count of unique findings across all policies
	"getTotalFindingsCount": getTotalFindingsCount,
}

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.

Bitbucket comment example

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.

Bitbucket secrets comment example

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.

Manage Bitbucket Cloud App on Endor Labs

You can make changes to the Bitbucket Cloud App integrations or delete them. You can view the activity logs for the Bitbucket App and rescan your Bitbucket projects on demand.

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

  2. Click Manage next to Bitbucket Cloud under Source Control Managers.

  3. Click the three vertical dots next to the integration.

    You can choose from the following options:

    Manage Bitbucket App

To edit the Bitbucket App integration:

  1. Click the three vertical dots next to the integration, and select Edit Integration.

  2. In EDIT INSTALLATION, you can update your personal access token and choose the scanners. Edit Bitbucket App

  3. Select Pull Request Settings to edit the PR scans configuration.

    See Bitbucket Cloud App PR scans for more information.

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. For more information, see Create an access token.

  1. Click Save.

    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.

To delete a Bitbucket App integration, click the three vertical dots next to the integration, and select Delete Integration.

When you delete the integration, it will also delete all child namespaces, projects and references associated with the auto-generated root group namespace. It also deletes any manually created namespaces and projects under auto-generated namespace.

The workspace or project URL cannot be edited in an integration. Delete the existing one and create a new integration in Endor Labs in the following scenarios to prevent duplication of findings in your tenant:

  • You modify the Bitbucket Cloud workspace or project host URL.
  • You want to update the integration to workspace level from project level.

Endor Labs detects and reports installation and synchronization errors during organization sync. These include expired tokens, insufficient permissions, invalid host configurations, and certificate issues. Sync logs report those errors that you can resolve.

Sync logs showing error

To view sync logs, click the three vertical dots next to the integration, and select View Sync Logs.

The sync logs display details of synchronization attempts, including timestamps, error types, and diagnostic messages. These logs help identify issues such as authentication failures or configuration problems.

The sync logs detect and display the following categories of sync failures:

  • Expired or invalid Personal Access Tokens (PATs): The PAT used for authentication has expired or is no longer valid. Edit the integration and provide a valid token.
  • Insufficient PAT permissions: The PAT does not have the required scopes, such as repository read access. You must generate and provide a PAT with the correct access.
  • Certificate related access issues: The certificates required to connect to the SCM are invalid, outdated, or untrusted. This error occurs in self-hosted GitLab instances that use custom SSL certificates. Update the certificate configuration or ensure the certificate chain is properly trusted to resolve the issue.
  • Incorrect or invalid host URLs: The configured URL is incorrect or unreachable. Since you cannot edit the host URL, you need to delete and reinstall the integration using the correct URL.

After you resolve the issue, the error is automatically cleared during the next successful scan. You can manually re-trigger the scan using Rescan Org to verify the resolution immediately.

sync logs

Bitbucket Cloud App scans your repositories every 24 hours. Click Rescan Org to manually trigger a scan outside the 24-hour period.

Click Scan More Repositories to go to Projects, where you can add more projects to scan through the Bitbucket App.