Bitbucket

13 min

Bitbucket

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:

Open a terminal.

Update your package lists to ensure you get the latest version available:

$ sudo apt update

Install the required packages:

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.

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.

sources: - connection: "@type": type.googleapis.com/sources.Bitbucket endpoint: https://bitbucket.org/myworkspace apiToken: password: ATAT_xxxxxxxxxxxxxxxxxxxxxxxxxx # Atlassian API token email: [email protected] # 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.

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.

sources: - connection: "@type": type.googleapis.com/sources.Bitbucket endpoint: https://bitbucket.ourbusiness.com oauth: refreshToken: <refresh token generated by the helper script> clientId: <client ID from the Bitbucket application link> clientSecret: <client secret from the Bitbucket application link> redirectUri: <redirect URI configured in the Bitbucket application link> 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.

#!/bin/bash # Replace these with your OAuth consumer details CLIENT_ID="<client ID from the Bitbucket application link>" CLIENT_SECRET="<client secret from the Bitbucket application link>" REDIRECT_URI="<redirect URI configured in the Bitbucket application link>" 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.

Autodetection of Cloud vs. Data Center: By default, TruffleHog autodetects whether you're connecting to Bitbucket Cloud or Bitbucket Data Center. In rare cases this autodetection causes errors with Data Center connections. To disable autodetection, set installationType to either cloud or 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.