Bitbucket Setup Guide for CBOM Source Code Sensor
1. Purpose
The CBOM Source Code sensor (Discover_SourceCode) scans Bitbucket repository contents to discover cryptographic material embedded in source code and configuration files. This includes:
Hardcoded private keys, public keys, and key pairs (RSA, EC, DSA, Ed25519)
X.509 certificates and certificate chains stored in repository files
API tokens, secret keys, and access credentials committed to repositories
Symmetric encryption keys, passphrases, and initialization vectors
SSH keys and known-hosts entries stored within repository contents
Cryptographic configuration artifacts such as
.pem,.crt,.key,.jks, and.p12files
This guide covers credential creation and sensor configuration for both Bitbucket Cloud and Bitbucket Server / Data Center deployments. All access granted to the CBOM sensor is read-only. No repository contents are modified during scanning.
2. Prerequisites
Before beginning, ensure the following are in place:
A Bitbucket Cloud account with administrative access to the workspace, or a Bitbucket Server / Data Center instance (version 7.x or later) with a user account that has at minimum Project Read and Repository Read permissions.
Network connectivity from the CBOM sensor host to the Bitbucket API endpoint: - Bitbucket Cloud:
https://api.bitbucket.org- Bitbucket Server / Data Center:https://<your-bitbucket-host>The CBOM platform installed and the
Discover_SourceCodesensor binary available on the sensor host.Outbound HTTPS (port 443) allowed from the sensor host to the Bitbucket API endpoint.
The Bitbucket workspace slug (Cloud) or project key (Server / Data Center) for the repositories to be scanned.
Python 3.8+ or the CBOM sensor runtime dependencies installed on the sensor host (refer to the CBOM Installation Guide).
3. Create Bitbucket Cloud App Password
Bitbucket Cloud uses app passwords for API authentication. App passwords are scoped credentials tied to a specific user account and are separate from the account's primary password.
3.1 Navigate to App Passwords
Log in to Bitbucket Cloud at
https://bitbucket.orgusing the account that will be used for CBOM scanning.Click the user avatar in the bottom-left corner of the interface.
Select Personal settings from the menu.
In the left-hand navigation panel, click App passwords under the Access management section.
Click Create app password.
3.2 Configure App Password Permissions
Enter a descriptive label for the app password, for example:
CBOM-SourceCode-Sensor.Under Permissions, locate the Repositories section.
Enable the Read permission checkbox under Repositories.
Leave all other permission checkboxes unchecked to enforce least-privilege access.
Click Create.
Copy the generated app password immediately. It will not be shown again after navigating away from this page.
Record the Bitbucket username (not the email address) associated with this account. This is found under Personal settings > Account settings > Username.
3.3 Verify Cloud API Access
Run the following command from the sensor host to confirm the credentials are valid and have access to the target workspace:
curl -u "your_username:your_app_password" \
"https://api.bitbucket.org/2.0/repositories/{workspace}"A successful response returns a JSON object containing a values array of repository objects. An HTTP 200 status confirms connectivity and credential validity.
4. Create Bitbucket Server / Data Center HTTP Access Token
Bitbucket Server and Data Center use HTTP access tokens for API authentication instead of app passwords. Tokens are scoped per user and support fine-grained permission control.
4.1 Navigate to HTTP Access Tokens
Log in to your Bitbucket Server or Data Center instance at
https://<your-bitbucket-host>.Click the user avatar in the top-right corner.
Select Manage account from the dropdown menu.
In the left-hand navigation panel, click HTTP access tokens.
Click Create token.
4.2 Configure Token Permissions
Enter a descriptive name for the token, for example:
CBOM-SourceCode-Sensor.Under Permissions, set the permission level to Project read.
Ensure Repository read is also selected (it is typically included when Project read is selected).
Leave Write and Admin permissions unselected.
Optionally set an expiry date aligned with your organization's credential rotation policy.
Click Create.
Copy the generated token value immediately. It will not be displayed again after this screen.
Note the token value; this will be used in place of a password in sensor configuration.
4.3 Verify Server API Access
Run the following command from the sensor host to confirm token validity:
curl -H "Authorization: Bearer your_access_token" \
"https://<your-bitbucket-host>/rest/api/1.0/projects/{projectKey}/repos"A successful response returns a JSON object with a values array listing repositories in the specified project. An HTTP 200 status confirms connectivity and token validity.
5. Configure CBOM Sensor
Create or update the sensor configuration file for the Discover_SourceCode sensor. The configuration differs slightly between Bitbucket Cloud and Bitbucket Server / Data Center deployments.
5.1 Bitbucket Cloud Configuration
sensor:
name: Discover_SourceCode
enabled: true
provider: bitbucket_cloud
connection:
base_url: "https://api.bitbucket.org/2.0"
workspace: "your-workspace-slug"
auth:
type: basic
username: "your_bitbucket_username"
password: "your_app_password"
scan:
repositories:
- "*" # Scan all repositories; replace with specific repo slugs to limit scope
branches:
- "main"
- "master"
- "develop"
file_extensions:
- ".pem"
- ".crt"
- ".cer"
- ".key"
- ".p12"
- ".jks"
- ".env"
- ".yaml"
- ".yml"
- ".json"
- ".xml"
- ".conf"
- ".properties"
exclude_paths:
- "node_modules/"
- ".git/"
- "vendor/"
- "dist/"
max_file_size_kb: 512
depth: full
output:
format: cbom_json
destination: "/var/cbom/output/bitbucket_cloud"
report_name: "bitbucket_cloud_crypto_inventory"
schedule:
interval: "24h"
start_time: "02:00"
logging:
level: info
log_file: "/var/log/cbom/discover_sourcecode_bitbucket_cloud.log"5.2 Bitbucket Server / Data Center Configuration
sensor:
name: Discover_SourceCode
enabled: true
provider: bitbucket_server
connection:
base_url: "https://your-bitbucket-host.example.com"
auth:
type: bearer_token
token: "your_http_access_token"
ssl_verify: true
ssl_ca_bundle: "/etc/ssl/certs/ca-certificates.crt" # Update path if using a custom CA
scan:
projects:
- "PROJ" # Replace with your Bitbucket project key(s)
repositories:
- "*" # Scan all repositories in the listed projects
branches:
- "main"
- "master"
- "develop"
file_extensions:
- ".pem"
- ".crt"
- ".cer"
- ".key"
- ".p12"
- ".jks"
- ".env"
- ".yaml"
- ".yml"
- ".json"
- ".xml"
- ".conf"
- ".properties"
exclude_paths:
- "node_modules/"
- ".git/"
- "vendor/"
- "dist/"
max_file_size_kb: 512
depth: full
output:
format: cbom_json
destination: "/var/cbom/output/bitbucket_server"
report_name: "bitbucket_server_crypto_inventory"
schedule:
interval: "24h"
start_time: "02:00"
logging:
level: info
log_file: "/var/log/cbom/discover_sourcecode_bitbucket_server.log"6. Validation
After saving the configuration file, perform the following steps to confirm the sensor is operating correctly:
Start the sensor manually to run an immediate scan and observe the output:
cbom-sensor run --config /etc/cbom/sensors/bitbucket-setup.yamlConfirm the sensor logs a successful authentication message:
INFO [Discover_SourceCode] Authenticated to Bitbucket successfully.
INFO [Discover_SourceCode] Discovered 42 repositories in workspace 'your-workspace-slug'.
INFO [Discover_SourceCode] Scan initiated. Processing repository contents...Verify that the output report file is created in the configured destination directory:
ls -lh /var/cbom/output/bitbucket_cloud/Open the generated CBOM JSON report and confirm it contains cryptographic asset entries:
cat /var/cbom/output/bitbucket_cloud/bitbucket_cloud_crypto_inventory.json | python3 -m json.tool | head -60Cross-reference at least one discovered asset against a known cryptographic file in your repositories to confirm accurate detection.
For Bitbucket Cloud, verify the API rate limit is not being exceeded by checking the
X-RateLimit-Remainingheader in response logs. Adjust the scan schedule interval if needed.
7. Common Errors and Resolution
Error 1: HTTP 401 Unauthorized
ERROR [Discover_SourceCode] Authentication failed: HTTP 401 Unauthorized
Response: {"type": "error", "error": {"message": "Username/Password not accepted"}}Cause: The Bitbucket username or app password (Cloud) / HTTP access token (Server) is incorrect or has been revoked. On Bitbucket Cloud, this error also occurs when an email address is used instead of the account username.
Resolution:
Confirm the
usernamefield contains the Bitbucket account username, not the email address. The username is found under Personal settings > Account settings > Username.Regenerate the app password or HTTP access token if it has been revoked or expired.
Ensure there are no leading or trailing whitespace characters in the credential values in the configuration file.
Error 2: HTTP 403 Forbidden — Insufficient Permissions
ERROR [Discover_SourceCode] Access denied: HTTP 403 Forbidden
Response: {"type": "error", "error": {"message": "No permission to read repository contents"}}Cause: The app password (Cloud) or HTTP access token (Server) was created without the required Repository Read permission, or the associated user account does not have access to the target workspace or project.
Resolution:
For Bitbucket Cloud: Navigate to Account Settings > App passwords, delete the existing app password, and create a new one with the Repositories: Read permission explicitly enabled.
For Bitbucket Server / Data Center: Confirm the token's permission level includes Project read and Repository read. Also verify the user account is a member of the project with at least Read access.
Confirm the
workspace(Cloud) orprojects(Server) values in the configuration file match the actual workspace slug or project key.
Error 3: SSL Certificate Verification Failed
ERROR [Discover_SourceCode] Connection error: SSL: CERTIFICATE_VERIFY_FAILED
ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1129)Cause: The Bitbucket Server / Data Center instance uses a TLS certificate signed by an internal or private Certificate Authority (CA) that is not present in the sensor host's system trust store.
Resolution:
Obtain the CA certificate bundle used to sign the Bitbucket Server TLS certificate from your internal PKI team.
Place the CA bundle file on the sensor host, for example at
/etc/ssl/certs/internal-ca.crt.Update the sensor configuration to reference the CA bundle:
connection:
ssl_verify: true
ssl_ca_bundle: "/etc/ssl/certs/internal-ca.crt"Alternatively, append the internal CA certificate to the system CA bundle:
sudo cp internal-ca.crt /usr/local/share/ca-certificates/internal-ca.crt
sudo update-ca-certificatesDo not set ssl_verify: false in production environments, as this disables TLS validation and exposes the sensor to man-in-the-middle attacks.
8. Security Recommendations
Use dedicated service accounts: Create a dedicated Bitbucket user account exclusively for the CBOM sensor. Do not reuse personal or shared accounts. This isolates sensor activity in audit logs and simplifies credential rotation.
Enforce least-privilege access: Grant only the minimum required permissions (Repositories: Read for Cloud; Project Read / Repository Read for Server). Do not grant Write, Admin, or Webhook permissions to the sensor account.
Rotate credentials regularly: App passwords and HTTP access tokens should be rotated on a schedule consistent with your organization's credential management policy (typically every 90 days). Use Bitbucket's token expiry feature on Server / Data Center to enforce rotation.
Store credentials in a secrets manager: Do not store app passwords or access tokens in plaintext configuration files on disk. Integrate the CBOM sensor configuration with a secrets management solution (such as HashiCorp Vault or AWS Secrets Manager) and reference secrets by path rather than embedding values directly in YAML.
Restrict sensor host network access: Limit outbound network access from the sensor host to only the Bitbucket API endpoint (Cloud:
api.bitbucket.org:443; Server:<your-bitbucket-host>:443). Use firewall rules or network security groups to prevent the sensor host from initiating connections to other external services.
9. Conclusion
This guide has provided complete instructions for configuring read-only API credentials in both Bitbucket Cloud and Bitbucket Server / Data Center, and for deploying the CBOM Discover_SourceCode sensor to scan repository contents for cryptographic material. By following the least-privilege credential setup and security recommendations outlined above, the sensor operates safely within your source code environment without risk of modifying repository data. Once configured, the sensor will continuously inventory cryptographic assets across your Bitbucket repositories, feeding discovery results into the CBOM platform for centralized analysis and compliance reporting.