Bitbucket Sensor Guide

Instructions for deploying the Bitbucket Sensor to scan for cryptographic assets and deliver findings to the AgileSec Platform for processing and analysis.

Overview

The Bitbucket Sensor integrates Bitbucket (cloud or Bitbucket Enterprise) with Keyfactor's AgileSec Platform. This Sensor allows you to discover, inventory, and analyze cryptographic assets across multiple source code repositories within a Bitbucket workspace.

What Gets Scanned

The Bitbucket Sensor downloads target repositories from Bitbucket and scans for use of cryptography algorithms and libraries in source code. The following cryptographic assets can be discovered:

• X.509 Certificates: SSL/TLS certificates, code signing certificates, client authentication certificates

• Keys: RSA, DSA, EC asymmetric public keys in PEM, DER, and PKCS8 formats as well as unencrypted private keys

• Java Keystores: JKS, JCEKS, PKCS12 keystores

• Tokens: JWT and JWE tokens

• Cryptographic Libraries: OpenSSL, BouncyCastle, http://cryptography.io , and other crypto implementations

• Code Artifacts: Embedded certificates in compiled code (JAR, WAR, EAR files)

Prerequisites

Ensure you meet the following requirements to enable scanning.

Update

Network Access

Ensure HTTPS network connectivity from AgileSec platform or remote execution machine to the Bitbucket server.

Supported Bitbucket API Versions

The Bitbucket Sensor supports Bitbucket Data Center API 1.0 and Bitbucket Cloud SaaS API 2.0. The appropriate API must be accessible to the Sensor.

Supported Authentication Methods

The Bitbucket Sensor uses either Basic Auth or Bearer Token Auth.

Basic Auth (API Token)

Basic auth requires both the username and password fields. The username is the
email of the account used for authentication. The password is the API token.

To create an API token, navigate to Atlassian Account Settings > Security > Create and manage API tokens > Create API token with scopes.

Grant the Bitbucket API token the following required scopes:

1. read:project:bitbucket

2. read:repository:bitbucket

3. read:workspace:bitbucket

Store the token securely.

Bearer Token Auth

Bearer Token auth is mutually exclusive with Basic Auth. Bearer Token auth requires setting a token in the configuration file.

The token field expects an appropriate access token:

• Cloud: a workspace, project, or repository access token.

• Data Center: HTTP access token.

The Bearer Token is required to have the Repository Read (repository) scope.

For more information, see https://support.atlassian.com/bitbucket-cloud/docs/using-workspace-access-tokens/.

Remote Execution Requirements

If running the Sensor remotely using CLI, the remote execution machine must meet these requirements:

Running the Sensor

AgileSec Bitbucket scans can be executed using the following methods:

1. Platform Scan Execution: Configure and execute scans directly through the Keyfactor AgileSec web UI with on-demand or scheduled execution options.

2. API Scan Execution: Programmatically trigger scans through REST API calls, enabling integration with CI/CD pipelines and automation workflows.

3. Remote Scan Execution: Deploy and run the sensor via CLI on customer-managed infrastructure for scenarios such as:

   1. Scanning air-gapped or internal instances the platform cannot directly reach

   2. Customers wanting to manage their own scheduling and execution environment.

Configuration Fields

The following parameters are used to configure AgileSec Bitbucket scans.

Remote Execution Configuration Fields

The following parameters are available for remote execution only.

Platform Scan Execution

Running scans through the user interface is the simplest and fastest way to get started. The platform enables running on-demand or scheduled scans in a dedicated environment.

Platform Scan Configuration

1. Open your browser and navigate to the Keyfactor AgileSec Platform Web URL

2. Log in with your credentials

3. Click on "Sensors" in the left navigation menu under Scan

   

4. Click "+ New Sensor".

   

5. Click on the correct card to open the configuration interface.

Configure Parameters and Start Scan

6. Fill in the required configuration parameters.

7. Click Save.

8. Click Action then Scan to begin a scan.
   Note: Click Edit to reconfigure parameters.

   

API Scan Execution

Scans may be programmatically triggered through REST API calls, enabling seamless integration with CI/CD pipelines, automation workflows, and custom applications. API execution provides flexibility for developers to incorporate cryptographic scanning into their existing development and deployment processes.

Generate AgileSec API Access Token

1. Open your browser and navigate to AgileSec Platform UI

2. Log in with your Keyfactor credentials

3. Click "Access Tokens" in the main navigation menu

4. Click "Generate Token" button

5. Set Token Type to API Token and provide the required details

6. Click "Generate" and copy the generated token

   

AgileSec API Endpoint

POST https://<platform-url>/v3/scan/create/

Request Format

Headers

Content-Type: application/json
isg-api-token: <your-api-token>

Request Body

  {
    "sensorName": "<sensor name>",
    "sensorType": "Bitbucket Sensor",
    "sensorConfig": {
       "url": "<bitbucket api url>",
       "username": "<email of the bitbucket account>",
       "password": "<API token>",
       "token": "<Bearer token>",
       "branch": "<branch name>",
       "include_paths": "<include patterns>",
       "exclude_paths": "<exclude patterns>"
    },
    "callbackId": "<callback id>",
    "labels": [
        {
            "<label name>": "<label value>"
        }
    ],
    "priority": "<priority>",
  }

Remote Scan Execution

Scans may be run on remote host machines with the AgileSec Remote Sensor Package.

Download Remote Sensor Package

Generate Platform Token

7. In the Download Remote UI, click "Generate Token"

8. Copy the generated token

9. Store securely in an environment variable such as SENSOR_TOKEN:

    export SENSOR_TOKEN="your-generated-token"
   

Create Configuration File

Create a YAML configuration file (e.g., bitbucket-config.yml) with your scan settings. An example configuration can be found in config/sample-configs/bitbucket.yml.

Step 4: Run the Sensor

Execute the Sensor with your configuration file:

• Linux

  Bash

  # Set environment variables
  export SENSOR_TOKEN="your-sensor-token"
  
  # Run Sensor
  ./unified_sensor_linux -c bitbucket-config.yml
  

Remote Scan Execution Configuration Examples

• Scan Specific Branch

  YAML

  scan_config:
    plugins:
      - isg_bitbucket
      - trigger_discover
      - export
    config:
      isg_bitbucket:
        name: bitbucket
        plugin_config:
          url: "<https://api.bitbucket.org/2.0>"
          username: "<account email>"
          password: "${env:BITBUCKET_PASS}" # ENV for unified sensor
          branch: "develop"
          include_paths:
            - "myorg/myrepo"
  

• Bitbucket Data Center On-Prem with Bearer Token Auth

  YAML

  scan_config:
    plugins:
      - isg_bitbucket
      - trigger_discover
      - export
   config:
      isg_bitbucket:
        name: bitbucket
        plugin_config:
          url: "<https://bitbucket.<domain>.com/rest/api/1.0>"
          token: "<oauth token>"
          include_paths:
            - "internal-team"
          exclude_paths:
            - "internal-team/archived-*"
  

• Bitbucket SaaS with Password (token) Auth

  YAML

  scan_config:
    plugins:
      - isg_bitbucket
      - trigger_discover
      - export
    config:
      isg_bitbucket:
        name: bitbucket
        plugin_config:
          url: "<https://api.bitbucket.org/2.0>"
          username: "<account email>"
          password: "${env:BITBUCKET_PASS}" # ENV for unified sensor
          include_paths:
            - "internal-team"
          exclude_paths:
            - "internal-team/archived-*"
  

Known Limitations

Binary Files

While the sensor scans files, opaque binary blobs without recognized headers may not be deeply analyzed.

Troubleshooting Common Errors

• repository not found (404)

  • Cause: The URL is incorrect or the credentials provided do not have access to the private repository.

  • Fix: Check the URL.

• Unauthorized (401)

  • Cause: Invalid credentials.

  • Fix: Verify the credentials are correct by testing with a manual git clone command.

• could not find remote branch

  • Cause: The specified branch does not exist on the remote.

  • Fix: Verify the branch name matches exactly (case-sensitive).

Getting Support

Collect diagnostic information:

• Sensor version

• Configuration file (redact tokens)

• Log output

• Bitbucket details (cloud vs enterprise, URL, version)

Contact Support

• Portal: https://support.keyfactor.com