Bitbucket Cloud

Overview

Arnica Integrates directly with your Bitbucket Cloud application to help secure the development environment while identifying risks in real time - alerting your team and assisting with remediation actions. Arnica's integration is configurable allowing org-level provisioning or access to specified projects to extract the necessary data and take remediation actions.

Ensure service account continuity

Create a dedicated application user

Arnica's Bitbucket integration leverages a Bitbucket generated API Token tied to a specified user. To avoid the revocation of this token upon the impersonated user's departure, it is highly recommended to create and integrate using a standard application user.

The created user will be visible to all developers as part of Arnica's interactions, such as comments on merge requests. Hence, it is recommended to name the service account properly, such as arnica-service-account

Prerequisites

IP allowlist

In some cases, customers may use IP allowlist to restrict which source IP addresses can access a specific workspace. To validate this functionality, navigate to https://bitbucket.org/[WORKSPACE_NAME]/workspace/settings/access-controls and check the IP allowlisting configuration.

If this configuration is enabled, add Arnica's IP addresses, as documented in the Ingress traffic section of the On-Premises integrations page.

Grant permissions to application user

1. Login to the Bitbucket Cloud workspace

2. Navigate to the User Groups page located in https://bitbucket.org/[YOUR_WORKSPACE]/workspace/settings/groups

3. Click on the Administrators group and add the dedicated application security user to this group.

The following step will reduce the scope of the token to least privileges. This means that while the user will be assigned with administrator privileges, the token's privilege's will include a reduced scope.

If your environment is comprised of multiple workspaces, repeat the steps above for each workspace with the same user.

Installation process

Generate an API token

1. Login with the application user and navigate to the Atlassian API Tokens page.

2. Click on Create API token with scopes and provide a recognizable name and expiration in 1 year from the creation date.

3. The next step asks to choose the app will be accessed by the token. Select Bitbucket.

4. Add the following 15 scopes: read:account, read:me, read:user:bitbucket, read:pipeline:bitbucket, write:pipeline:bitbucket, read:project:bitbucket, read:pullrequest:bitbucket, write:pullrequest:bitbucket, read:repository:bitbucket, write:repository:bitbucket, admin:repository:bitbucket, read:webhook:bitbucket, write:webhook:bitbucket, delete:webhook:bitbucket and read:workspace:bitbucket.

5. Review the changes and create the token. When the token is displayed, copy it to a temporary location for later use during the Arnica integration.

Justification for write/admin permissions:

• Write Pipelines: allows Arnica to post a pipeline status during pull requests.

• Write Pull Requests: allows Arnica to post comments on pull requests.

• Write and Delete Webhooks: required to set up and re-create (update) webhooks for real-time scanning on code pushes and pull requests.

• Repository Admin and Write: required for real-time secrets mitigation.

Get the email address

1. Remain in the logged in session from the previous step and navigate to the Profile and visibility page.

2. Copy the email address of the account at the bottom of the page.

Integrate

1. Navigate to the Integrations page in Arnica and click on Bitbucket Cloud.

2. Fill in the email address (not username) and the API Token from the steps above.

3. Click on Validate to ensure that the credentials work properly and then click on OK.

Arnica will integrate with all workspaces associated with this user. Arnica's default policies include scan-only functionality. While scanning will begin immediately, developers will not see any impact until Arnica's polices are updated to take actions.

FAQ

Q: Why does the service account need to have administrative permissions? A: While the service account is granted with administrative permissions, the API Token used by Arnica has least privileges. It was designed this way to maintain access to required admin-only permissions without exposing the token to full admin rights.