Integrate Bitbucket with Boost Security¶

Boost Security lets you connect your Bitbucket organization to scan repositories, pull requests, and code commits for security issues.

Prerequisites¶

Before you connect Bitbucket to Boost Security, ensure you have:

An Atlassian account that is a member of the Bitbucket workspace you want to connect. A workspace member can create the API token with the scopes Boost Security requires, and Boost Security uses that token to access the workspace. See Using API tokens in the Bitbucket documentation.

As a prerequisite to enabling Zero Touch Provisioning, ensure to also have:

Repository admin permission for the account on the repositories of every Bitbucket project selected for Zero Touch Provisioning. Granting the account the Admin permission on a project gives it admin permission on all the repositories in that project. See Configure project permissions for users and groups in the Bitbucket documentation.
Created a non-empty .boost repo in the Bitbucket workspace. To do this, go to the Bitbucket workspace you connect to Boost Security and create a new .boost repo that contains a Readme file.
Turned on the Enable Pipelines settings for your workspaces' .boost repository, i.e, https://bitbucket.org/<your-bitbucket-org>/.boost/admin/pipelines/settings. You can do this by clicking the Enable Pipelines button as shown above and turning it on.

1. Create an Atlassian API Token¶

Boost Security connects to your Bitbucket workspace with an Atlassian API token. To create the token:

Sign in with the Atlassian account that has access to the workspace, and open the Atlassian API tokens page.
Click Create API token with scopes.
Enter a Name that describes the token's purpose (for example, Boost Security), select an Expires on date, and click Next. Atlassian API tokens last no longer than 365 days.
Select Bitbucket as the API token app and click Next.

Select the following scopes and click Next:

Permission	Scopes
Admin	`admin:repository:bitbucket`
Read	`read:repository:bitbucket`, `read:pullrequest:bitbucket`, `read:pipeline:bitbucket`, `read:user:bitbucket`, `read:webhook:bitbucket`, `read:workspace:bitbucket`
Write	`write:repository:bitbucket`, `write:pullrequest:bitbucket`, `write:pipeline:bitbucket`, `write:webhook:bitbucket`
Delete	`delete:webhook:bitbucket`

Review the token name, expiration, app, and scopes, then click Create token. A token can't be modified after it is created.
Copy the token and store it securely. Atlassian displays it only once. You enter it in Boost Security in the next section.

Note

Boost Security stops accessing your workspace when the token expires. Create a new token before the expiration date and update it in Boost Security to keep the integration working.

2. Connect Bitbucket to Boost Security¶

To connect your Bitbucket workspace to Boost Security, follow these steps:

Go to Settings > Integrations and select Bitbucket in the Available section.
Select Install to open the New Bitbucket Integration dialog.
On the Enter your credentials step, enter the Email of your Atlassian account and the API Token created in the previous section, then click Next. The dialog also lists the scopes the token requires, with a link to the Atlassian API tokens page.

If the email or the token is not valid, the dialog displays Authentication error. Invalid credentials. Check that the email matches the account that created the token, that the token was copied in full and has not expired, and that it was created with Create API token with scopes for the Bitbucket app with the scopes listed above.
On the Select the workspace step, select the Workspace to connect and click Complete.

Once the integration is connected, the Boost Security Bitbucket card is added to the Settings > Integrations > Installed section.

Update the API Token¶

To replace the API token, for example before it expires:

Create a new token by following Create an Atlassian API Token.
Go to Settings > Integrations, select your Bitbucket integration, and click on the configuration tab.
Open the menu next to the ZTP status of the integration and select Update Personal Access Token.
Enter the Email of your Atlassian account and the new API Token, then click Save.

3. Zero Touch Provisioning for Bitbucket¶

Follow these steps to set up ZTP for Bitbucket:

Go to the Integrations page, select your Bitbucket integration, and click on the configuration tab.
On the ZTP column, you will notice that the status is set to Not Set. Click on the menu next to the status and select Enable.
On the Give Boost permissions for the Zero Touch flow step, no additional permissions are required. Select Skip initial scan after provisioning if you don't want repositories to be scanned right after provisioning, then click Next.
On the Configure the Boost Repository step, pick where the Boost Security scans pipeline runs. The default is use .boost repository from the same organization. Click Select And Continue.
On the Display Pipeline Configuration step, you are redirected to Atlassian to authorize the pipeline configuration.
Sign in with your Atlassian account if prompted. Atlassian displays the access that BoostSecurity CI Provisioning requests on your Atlassian account: access to your repositories' build pipelines and their variables, and read and modify access to your pull requests and repositories. Click Accept.
You are returned to Boost Security, which configures the pipeline in the .boost repository. The wizard displays Zero Touch Provisioning is now enabled! Click Enable Boost Recommended Scanners, or Go to Scanner Coverage page to start adding scanners to provision scanners yourself.

Note

By clicking the Enable Boost Recommended Scanners button, Boost will provision multiple scanners for every repository it has access to. These scanners will then request new scans to be conducted for each of those repositories. Please note that this process would have a financial impact on your services, so ensure that this is the correct course of action before proceeding.

If you are connecting to a large collection of repos, you may want to enable scanning in a more targeted manner.