Bitbucket

bitbucket edition enterprise only the bitbucket integration scans repositories in bitbucket cloud, server, and data center for credentials and other sensitive data 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 four 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 basic auth uses an atlassian account email and an api token bitbucket server / data center with basic auth uses an account username and a token or password 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 basic auth block below if your account isn't on bitbucket cloud premium, you can't create a workspace access token use the basic auth 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 with basic auth use this for bitbucket cloud when a workspace access token isn't available, for example on accounts without bitbucket cloud premium, or when using a user based credential 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 basicauth password xxxxxxxxxxxxxxxxxxxxxxxxxx username scanner\@example com ignorerepos \ https //bitbucket org/myworkspace/ignore git \ https //bitbucket org/myworkspace/ignore2 git skipbinaries true name bitbucket cloud basic 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