--- title: Bitbucket slug: docs/bitbucket description: Learn how to configure your connection to BitBucket for repository scanning. Discover various authentication methods, including token, basic authentication with password, and basic authentication with app password/token. icon: {"faIcon":"fa-brands fa-bitbucket"} docTags: createdAt: 2024-04-17T14:46:03.050Z --- # Bitbucket :::BlockQuote **Edition:** Enterprise only ::: The Bitbucket integration scans repositories in Bitbucket Cloud, Server, and Data Center for credentials and other sensitive data. ## Dependencies (Self-Hosted Deployment Only) This setup requires specific tools for effective operation. Git is essential for repository management, while rpm2cpio, binutils, and cpio are necessary for extracting files from .rpm and .deb package formats. - **Git**: For cloning repositories. - **rpm2cpio**: To extract content from RPM packages. - **binutils**: Includes the "ar" tool, crucial for extracting contents from .deb files. - **cpio**: A versatile file archiver utility, compatible with various archive formats including .rpm and .deb. ### Installing Dependencies on Ubuntu To install these dependencies on an Ubuntu system, follow these steps: 1. Open a terminal. 2. Update your package lists to ensure you get the latest version available: ```shell $ sudo apt update ``` 1. Install the required packages: ```shell sudo apt install git rpm2cpio binutils cpio ``` ## Configuration The Bitbucket integration can be configured in TruffleHog under **Integrations**, or via a local configuration file (below). ### Web configuration Configure this integration from the **Integrations** page in TruffleHog. You'll need credentials appropriate to your Bitbucket deployment. See the Local configuration section below for the supported authentication methods. ### Local configuration Local configuration supports five authentication modes, depending on your Bitbucket deployment: - **Bitbucket Cloud with Workspace Access Token**. Recommended for Bitbucket Cloud. Provides the broadest project and repository coverage. - **Bitbucket Cloud with API Token**. Uses atlassian account email, username(optional) and api token(prefix ATAT). - **Bitbucket Server / Data Center with basic auth**. Uses an account username and a token or password. - **Bitbucket Server / Data Center with API Token**. Uses atlassian account email, username(optional) and API token(prefix ATAT). - **Bitbucket Server / Data Center with OAuth**. Uses an OAuth application link with refresh-token-based authentication. **Bitbucket Cloud with Workspace Access Token** Use this for Bitbucket Cloud. The token field requires a **Workspace Access Token**, generated in Bitbucket under **Workspace settings → Access tokens**. Workspace Access Tokens are a Bitbucket Cloud Premium feature, are tied to the workspace rather than to a user, and authenticate via the Authorization: Bearer header. The token needs at least the read\:repository\:bitbucket and read\:workspace\:bitbucket scopes. Other Bitbucket Cloud credentials do not work in this mode: - **Project Access Tokens** are scoped to a single project and cannot enumerate the workspace. - **Repository Access Tokens** are scoped to a single repository and, as of Atlassian's deprecation of cross-workspace APIs, can no longer list workspaces. Repository enumeration will fail. - **API tokens** (user-based, prefix ATAT) authenticate via Basic Auth, not Bearer. Use these in the API Token block below. If your account isn't on Bitbucket Cloud Premium, you can't create a Workspace Access Token. Use the **API Token** block below instead. :::BlockQuote sources: \- connection: "@type": type.googleapis.com/sources.Bitbucket endpoint: https\://bitbucket.org/myworkspace ignoreRepos: \- https\://bitbucket.org/myworkspace/ignore.git \- https\://bitbucket.org/myworkspace/ignore2.git skipBinaries: true token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx name: Bitbucket Cloud Token Auth scanPeriod: 12h type: SOURCE\_TYPE\_BITBUCKET verify: true ::: **Bitbucket Cloud / Data Center with API Token** Use this for Bitbucket Cloud or Data Center when a Workspace Access Token isn't available, for example on accounts without Bitbucket Cloud Premium. The email field accepts the atlassian account email which was used to generate the **API token.** The username field is optional and accepts the atlassian account username which was used to generate the **API token.** The password field accepts a Bitbucket **API token** (prefix ATAT), generated at id.atlassian.com under **Security → Create and manage API tokens**. Select **Create API token with scopes**, choose **Bitbucket Cloud** as the app, and grant at least read\:repository\:bitbucket and read\:workspace\:bitbucket. The username is the Atlassian account email associated with the token. Workspace, Project, and Repository Access Tokens are not used in this mode. They go in the token field of the Workspace Access Token block above. :::BlockQuote sources: \- connection: "@type": type.googleapis.com/sources.Bitbucket endpoint: https\://bitbucket.org/myworkspace apiToken: password: ATAT\_xxxxxxxxxxxxxxxxxxxxxxxxxx # Atlassian API token email: scanner\@example.com # Atlassian account email username: my-bitbucket-username # username is optional ignoreRepos: \- https\://bitbucket.org/myworkspace/ignore.git \- https\://bitbucket.org/myworkspace/ignore2.git skipBinaries: true name: Bitbucket Cloud API Token Auth scanPeriod: 12h type: SOURCE\_TYPE\_BITBUCKET verify: true ::: **Bitbucket Server / Data Center with basic auth** Use this for Bitbucket Server or Data Center deployments. The password field accepts either a service account password or a token. :::BlockQuote sources: \- connection: "@type": type.googleapis.com/sources.Bitbucket endpoint: https\://bitbucket.ourbusiness.com basicAuth: password: xxxxxxxxxxxxxxxxxxxxxxxxxx username: scanner-account ignoreRepos: \- https\://bitbucket.ourbusiness.com/linux-kernel/ignore.git \- https\://bitbucket.ourbusiness.com/torvalds/ignore2.git name: Bitbucket Server scanPeriod: 12h type: SOURCE\_TYPE\_BITBUCKET verify: true ::: **Bitbucket Server / Data Center with OAuth** Use this for Bitbucket Server or Data Center deployments where OAuth is preferred over basic auth. Setup requires a Bitbucket application link and a refresh token generated via the helper script below. :::BlockQuote sources: \- connection: "@type": type.googleapis.com/sources.Bitbucket endpoint: https\://bitbucket.ourbusiness.com oauth: refreshToken: \ clientId: \ clientSecret: \ redirectUri: \ allowSecretsManagerWrite: true oauthAuthorizationEndpoint: https\://bitbucket.ourbusiness.com/rest/oauth2/latest/authorize oauthTokenEndpoint: https\://bitbucket.ourbusiness.com/rest/oauth2/latest/token oauthScopes: \- REPO\_READ ignoreRepos: \- https\://bitbucket.ourbusiness.com/linux-kernel/ignore.git \- https\://bitbucket.ourbusiness.com/torvalds/ignore2.git name: Bitbucket Server scanPeriod: 12h type: SOURCE\_TYPE\_BITBUCKET verify: true ::: **Bitbucket Data Center OAuth setup** Setting up OAuth for Bitbucket Data Center requires admin access to your Bitbucket instance and a one-time helper script run to generate the refresh token. **Step 1: Create the application link** Create an external incoming application link in your Bitbucket Data Center for TruffleHog to use. The redirect URL can be any trusted URL you have access to. The permissions granted to TruffleHog must include repository read access. **Step 2: Generate a refresh token** Save the script below as bitbucket-oauth.sh and run ./bitbucket-oauth.sh -a to authorize TruffleHog and generate the initial refresh token. Use -b to refresh an existing token. :::BlockQuote \#!/bin/bash \# Replace these with your OAuth consumer details CLIENT\_ID="\" CLIENT\_SECRET="\" REDIRECT\_URI="\" AUTH\_URL="https\://bitbucket.ourbusiness.com/rest/oauth2/latest/authorize" TOKEN\_URL="https\://bitbucket.ourbusiness.com/rest/oauth2/latest/token" SCOPES="REPO\_READ" \# Function to authorize access and get an access token for the first time oauth\_access\_token() \{ echo "Step 1: Open the following URL in your browser and authorize access:" echo "" echo "${AUTH\_URL}?client\_id=${CLIENT\_ID}\&response\_type=code\&scope=${SCOPES}\&redirect\_uri=${REDIRECT\_URI}" echo "" echo "After authorizing, you will be redirected to ${REDIRECT\_URI}?code=YOUR\_AUTH\_CODE" echo "Copy the 'code' from the URL and enter it below:" read -p "Enter the authorization code: " AUTH\_CODE echo "Requesting access token..." response=$(curl --request POST --url \\ "${TOKEN\_URL}?client\_id=${CLIENT\_ID}\&client\_secret=${CLIENT\_SECRET}\&code=${AUTH\_CODE}\&grant\_type=authorization\_code\&redirect\_uri=${REDIRECT\_URI}" \\ \--header 'content-type: application/x-www-form-urlencoded') echo $response ACCESS\_TOKEN=$(echo $response | grep -o '"access\_token":"\[^"]\*' | cut -d'"' -f4) REFRESH\_TOKEN=$(echo $response | grep -o '"refresh\_token":"\[^"]\*' | cut -d'"' -f4) if \[\[ -z "$ACCESS\_TOKEN" ]]; then echo "Failed to retrieve access token. Response: $response" exit 1 fi echo "OAuth token generated successfully!" echo "Access token: $ACCESS\_TOKEN" echo "Refresh token: $REFRESH\_TOKEN" } \# Function to generate a new access token using a refresh token oauth\_refresh\_token() \{ read -p "Enter the refresh token: " REFRESH\_TOKEN echo "Requesting access token..." response=$(curl --request POST --url \\ "${TOKEN\_URL}?client\_id=${CLIENT\_ID}\&client\_secret=${CLIENT\_SECRET}\&refresh\_token=${REFRESH\_TOKEN}\&grant\_type=refresh\_token\&redirect\_uri=${REDIRECT\_URI}" \\ \--header 'content-type: application/x-www-form-urlencoded') echo $response ACCESS\_TOKEN=$(echo $response | grep -o '"access\_token":"\[^"]\*' | cut -d'"' -f4) REFRESH\_TOKEN=$(echo $response | grep -o '"refresh\_token":"\[^"]\*' | cut -d'"' -f4) if \[\[ -z "$ACCESS\_TOKEN" ]]; then echo "Failed to retrieve access token. Response: $response" exit 1 fi echo "OAuth token generated successfully!" echo "Access token: $ACCESS\_TOKEN" echo "Refresh token: $REFRESH\_TOKEN" } if \[\[ $# -eq 0 ]]; then echo "Usage: $0 -a | -b" echo " -a: Authorize and generate the initial OAuth token" echo " -b: Use a refresh token to get a new access token" exit 1 fi while getopts "ab" opt; do case $opt in a) oauth\_access\_token ;; b) oauth\_refresh\_token ;; \*) echo "Invalid option: $OPTARG"; exit 1 ;; esac done ::: **Step 3: Configure TruffleHog** Use the refresh token from Step 2 in the OAuth configuration block above. ## Configuration options | Field | Type | Required | Description | | -------------------------- | ------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | endpoint | string | Conditional | Endpoint URI for Bitbucket. Required for basic auth and OAuth modes. | | repositories | list | No | Explicit list of repositories to scan. Omit to enumerate instead. | | ignoreRepos | list | No | Repositories to skip during scanning. Typically used with enumeration. | | skipBinaries | boolean | No | Skip binary files. | | skipArchives | boolean | No | Skip archive files. | | installationType | string | No | One of autodetect, CLOUD, or DATA\_CENTER. Defaults to autodetect. See Notes. | | allowSecretsManagerWrite | boolean | No | Allow TruffleHog to overwrite the secret in your secrets manager that contains its config. Used to keep the OAuth refresh token current when the config is pulled from a secrets manager. Currently compatible only with AWS Secrets Manager and requires the secretsmanager\:PutSecretValue permission. | | oauthAuthorizationEndpoint | string | Conditional | OAuth authorization endpoint for Bitbucket Data Center. Required for OAuth mode. | | oauthTokenEndpoint | string | Conditional | OAuth token endpoint for Bitbucket Data Center. Required for OAuth mode. | | oauthScopes | list | Conditional | OAuth scopes for the access token. Should typically be REPO\_READ only. Required for OAuth mode. | ## Capabilities | Feature | Supported | | -------------------------- | --------- | | Scan archive files | ✅ | | Scan archived repositories | ✅ | | Scan base64-encoded data | ✅ | | Scan binaries | ✅ | | History | ✅ | | Include / exclude filters | ✅ | | Pre-commit | ✅ | | Pre-receive | ✅ | | Auto-resume | ✅ | ## Notes TruffleHog does not scan diffs larger than 1 GB. **Self-hosted Scanner Auto Detection of Cloud vs. Data Center** By default, TruffleHog auto detects whether you're connecting to Bitbucket Cloud or Bitbucket Data Center. In rare cases this auto detection causes errors with Data Center connections. To disable auto detection and detect the right version of Bitbucket, open your self-hosted **config.yaml**, and add: `installationType:CLOUD`or `installationType:DATA_CENTER` **** **Migrating from app passwords:** Existing configurations using a Bitbucket app password in the basic auth block continue to work. Atlassian is deprecating app passwords for Bitbucket Cloud, so plan to migrate to an API token (ATAT prefix) before the deprecation completes. See the Bitbucket Cloud with basic auth section above for the API token setup steps. **Troubleshooting** | Error | Cause | Solution | | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cannot process 'refs/remotes/origin/...' and 'refs/remotes/origin/...' at the same time | Repository contains refs that conflict on disk during clone (for example, a branch and a tag with overlapping paths). | Uncommon, but the scan will skip the affected repo and continue. If you need to scan a repo that consistently throws this error, open a bug report for workaround guidance. | | Repository enumeration returns no results, or authentication fails when using a Bitbucket Cloud token in the Workspace Access Token block. | Token is a Repository Access Token, Project Access Token, or user-based API token (ATAT prefix). The Workspace Access Token block requires a Workspace Access Token specifically. Other Bitbucket Cloud token types will not work. Repository-scoped tokens additionally no longer support workspace listing per Atlassian's deprecation of cross-workspace APIs. | Generate a Workspace Access Token under **Workspace settings → Access tokens** in Bitbucket (requires Bitbucket Cloud Premium) and use it in the Workspace Access Token block. If Premium isn't available, use an API token (ATAT prefix) in the basic auth block instead, with the associated Atlassian account email as the username. |