# Bitbucket Plugin

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-MkdG_XIkldQnp9MV2kj%2F-MkdGfsG5Xki1qYqnKe6%2Fbitbucket-plugin-header.jpg?alt=media\&token=a1d0792b-3951-44f1-a7be-657b00a543f2)

## Features

* Retrieve secrets from the Keeper Vault within BitBucket Pipelines
* Set secret credentials as build arguments or environment variables in BitBucket Pipeline scripts
* Copy secure files from the Keeper Vault

{% hint style="info" %}
For a complete list of Keeper Secrets Manager features see the [Overview](https://docs.keeper.io/en/keeperpam/secrets-manager/overview)
{% endhint %}

## Prerequisites

This page documents the Secrets Manager BitBucket integration. In order to utilize this integration, you will need:

* Keeper Secrets Manager access (See the [Quick Start Guide](https://docs.keeper.io/en/keeperpam/secrets-manager/quick-start-guide) for more details)
  * Secrets Manager addon enabled for your Keeper account
  * Membership in a Role with the Secrets Manager enforcement policy enabled
* A Keeper [Secrets Manager Application](https://docs.keeper.io/en/keeperpam/about/terminology#application) with secrets shared to it
  * See the [Quick Start Guide](https://docs.keeper.io/en/keeperpam/quick-start-guide#2.-create-an-application) for instructions on creating an Application
* An initialized Keeper [Secrets Manager Configuration](https://docs.keeper.io/en/keeperpam/secrets-manager/about/secrets-manager-configuration)
  * The BitBucket integration accepts JSON and Base64 format configurations

## Setup

### Getting a configuration

Using Keeper Commander, add a new client to an application and initialize the configuration to a Base64 string. This will be the long text hash that appears after the "Initialized Config:" label.

```
My Vault> sm client add --app MyApp --config-init b64

Successfully generated Client Device
====================================

Initialized Config: eyJob3N0bmFtZSI6ICJr....OUk1ZTV1V2toRucXRsaWxqUT0ifQ==
IP Lock: Enabled
Token Expires On: 2021-10-19 15:31:31
App Access Expires on: Never
```

That value can be added to your BitBucket **Repository variables**, under **Repository settings** menu, as a secure secret with the name **KSM\_CONFIG**. This will allo the configuration to be available to the Keeper Secrets Manager pipe as a variable.

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FXA3sVeoGMCD2PZeB4Rij%2FScreen%20Shot%202021-10-19%20at%202.39.08%20PM.png?alt=media\&token=d3b61789-85a8-4403-ac85-db999a44ab4f)

### Adding to bitbucket-pipeline.yml

```
image: atlassian/default-image:2

pipelines:
  default:
    - step:
        name: 'Build My Stuff'
        script:
          - pipe: keepersecurity/keeper-secrets-manager-pipe:<tag>
            variables:
              KSM_CONFIG: "${KSM_CONFIG}"
              SECRETS: |
                1adh_WZxtbbHWqf6IALMVg/field/login > MY_LOGIN
                V8lFbio0Bs0LuvaSD5DDHA/file/IMG_0036.png > file:my.png
              SCRIPT_TEXT: |
                #!/usr/bin/env bash
                echo "My Login = \${MY_LOGIN}"
                ls my.png
              SHOW_OUTPUT: "True"
              SECRETS_FILE: "secret.env"
              SECRETS_FILE_TYPE: "export"
          - source secret.env
```

#### Pipe Integration

The name of the pipe integration is the following.

```
        script:
          - pipe: keepersecurity/keeper-secrets-manager-pipe:<tag>
```

{% hint style="info" %}
The pipe requires you to choose a git tag for the version. The [README.md](https://bitbucket.org/keepersecurity/keeper-secrets-manager-pipe/src/master/README.md) will always have the latest tag in the YAML Definition.
{% endhint %}

### Variables

#### Required

`KSM_CONFIG` - The Keeer Secrets Mananger pipe requires configuration information. This can be stored in the Repository variables and pulled into a variable using "${KSM\_CONFIG}"

`SECRETS` - The secrets are a new line separted list of Keeper Notation and destinations. The notation and desitnation are separated by the '>' character.

#### Optional

`SCRIPT_FILE` - The script file is an application, or shell script, that you wish to run inside of the pipe. The script will be able to access the secrets.

`SCRIPT_TEXT` - The script text allows you to hardcode a script inside of the bitbucket-pipeline.yml. It will be used if a `SCRIPT_FILE` does not exist. If used, you will need to escape any shell related special characters.

`SECRETS_FILE` - If set, secrets that were to be place into environmental varaibles will also be placed into a file. The format of the file depends on the `SECRET_FILE_TYPE`.

`SECRETS_FILE_TYPE` - If a SECRET\_FILE is used, this variable will determine it's format. Valid formats are 'json', 'export', 'setenv', and 'set'. The default is 'json'

`SHOW_OUTPUT` - A boolean flag to show the output from the `SCRIPT_FILE` or `SCRIPT_TEXT`. The REDACT variable will determine if you will be able to see your secrets in the ouput. By default, this flag is True.

`SAVE_OUTPUT_FILE` - If set, the output from the `SCRIPT_FILE` or `SCRIPT_TEXT` will be saved to a file.

`REDACT` - If **True**, any secret displayed from the `SCRIPT_FILE` or `SCRIPT_TEXT` will be replaced with '\*\*\*\*'. By default, this flag is **True**. This does not redact output saved to a file.

`REMOVE_FILES` - If **True**, when the pipe exits it will delete any files it created. Those files will not be available outside of the pipe unless the value is set to **False**. By default, this is True.

`CLEANUP_FILE` - The name of a shell script that will remove any files created inside of the pipe. While the build workspace is removed when the build finishes, this shell file can be run to make sure the files are deleted. If not set, no clean up file will be created.

`DEBUG` - Enable debug message inside of the pipe. By default, this is **False**.

## Retrieving Secrets

The SECRETS variable in the YAML contains a list of [Keeper Notation](https://docs.keeper.io/en/keeperpam/secrets-manager/about/keeper-notation) and where the value should be stored. Secrets can be stored as an environmental variable or in a file.

The default destination for a variable is a environmental variable. The prefix **env:** can be added to the front of the environmental variable name, but is not required.

{% hint style="info" %}
The environmental variable name must be a valid Unix environmental variable name
{% endhint %}

### Saving secrets to an environment variable

The example below will take the login secret and place them into environmental variables. Both lines do the same, one without the **env:** prefix and one with.

```
        script:
          - pipe: keepersecuirty/keeper-secrets-manager-pipe:<tag>
            variables:
              KSM_CONFIG: "${KSM_CONFIG}"
              SECRETS: |
                1adh_WZxtbbHWqf6IALMVg/field/login > MY_LOGIN
                1adh_WZxtbbHWqf6IALMVg/field/login > env:SAME_LOGIN          
```

In the example, `1adh_WZxtbbHWqf6IALMVg` is a record UID.

### Saving secrets to a file

If the secret is binary data it is highly recommended not to store the secret in an environmental variable due to encoding issues. Use the **file:** destination instead.

```
        script:
          - pipe: keepersecurity/keeper-secrets-manager-pipe:<tag>
            variables:
              KSM_CONFIG: "${KSM_CONFIG}"
              SECRETS: |
                1adh_WZxtbbHWqf6IALMVg/file/server.xml > file:server.xml
                1adh_WZxtbbHWqf6IALMVg/file/domain.crt > file:config/path/domain.crt             
```

If the variable `REMOVE_FILES` is True, the file will be removed when the pipe exits. Set this variable to False if you wish to use the files outside of the pipe.

## Examples

### Example 1 - Docker Build

This example will create a Tomcat server Docker image that contains a custom server.xml config and keystore containing the SSL certs. The server.xml and keystore are stored in the Keeper Vault.

The first step is to create a repo in BitBucket, then add a Dockerfile. This Dockerfile will add two files created by the Keeper Secrets Manager pipe to an official Tomcat Docker image.

```
FROM tomcat:10-jdk16

ADD /server.xml /usr/local/tomcat/conf/server.xml
ADD /localhost-rsa.jks /usr/local/tomcat/conf/localhost-rsa.jks

# Expose port 8443 for SSL
EXPOSE 8443
```

Next a configuration is needed for the Keeper Secrets Manager pipe. This can be created using Keeper Commander and initializing the config as Base64.

```
My Vault> sm client add --app MyApp --config-init b64

Successfully generated Client Device
====================================

Initialized Config: eyJob3N0bmFtZSI6ICJr....OUk1ZTV1V2toRucXRsaWxqUT0ifQ==
IP Lock: Enabled
Token Expires On: 2021-10-19 15:31:31
App Access Expires on: Never
```

{% hint style="info" %}
For more options creating a configuration, see the [configuration documentation](https://docs.keeper.io/en/keeperpam/about/secrets-manager-configuration#creating-a-secrets-manager-configuration)
{% endhint %}

The **Initialized Config:** Base64 string needs to be cut-n-pasted into your **Repository variables**. In this example the name of the variable is **KSM\_CONFIG**. A private Docker Hub username and password are also added to the **Repository variables**.

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FECT7H9rIz94bdhYKiPHI%2FScreen%20Shot%202021-11-01%20at%2010.49.46%20AM.png?alt=media\&token=56b2b0b9-5274-45eb-95e6-d807642e387a)

Next a `bitbucket-pipelines.yml` file needs to be added to the repository.

```
image: atlassian/default-image:2

pipelines:
  default:
    - step:
        name: 'Build Custom Tomcat Server'
        script:
          - pipe: keepersecuirty/keeper-secrets-manager-pipe:<tag>
            variables:
              KSM_CONFIG: "${KSM_CONFIG}"
              SECRETS: |
                3GGclNXOoU0DwZwdn6iZmg/file/server.xml > file:server.xml
                3GGclNXOoU0DwZwdn6iZmg/file/localhost-rsa.jks > file:localhost-rsa.jks
              REMOVE_FILES: "False"
              CLEANUP_FILE: "ksm_cleanup.sh"
          - VERSION="1.$BITBUCKET_BUILD_NUMBER"
          - IMAGE="$DOCKERHUB_USERNAME/$BITBUCKET_REPO_SLUG"
          - docker login --username "$DOCKERHUB_USERNAME" --password "${DOCKERHUB_PASSWORD}"
          - docker image build -t ${IMAGE}:${VERSION} .
          - docker image tag ${IMAGE}:${VERSION} ${IMAGE}:latest
          - docker image push ${IMAGE}
          - git tag -a "${VERSION}" -m "Tagging for release ${VERSION}"
          - git push origin ${VERSION}
          - ./ksm_cleanup.sh
        services:
          - docker
```

The above is used to build a Docker image and push it to your Docker Hub account. The first step will use the Keeper Secrets Manager pipe to retrieve the two files and place them into the work directory.

The `REMOVE_FILES` variable is set to **False** since we don't want to delete them after the pipe has finished.

The `CLEANUP_FILE` variable is set to **ksm\_cleanup.sh** which will create a script that will remove the two files when we are done.

When we build the Dockerfile, it will add the two files into the correct locations inside the image. When done it will push the image to the Docker Hub account.

The last part is running the ksm\_cleanup.sh script that was set by the `CLEANUP_FILE` variable. This will make sure the two files we created are deleted. BitBucket Pipeline does delete the work space when it is done, however this guarantees the files are deleted.

### Example 2 - Using Keeper Secrets Manager pipe with other pipes.

This example will retrieve secrets that are used as variables for another pipe. The other pipe is the AWS S3 Deploy pipe which will copy a local directory into a S3 bucket.

In the Keeper Vault, a record was created that contains our AWS credentials and information about the S3 bucket.

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FtBve4dEQOb4qlm0Tw8pI%2FScreen%20Shot%202021-11-01%20at%204.19.38%20PM.png?alt=media\&token=1c223504-041f-48bb-8669-cc1206b97f82)

The first step is to create a repo in BitBucket, and then store the Keeper Secrets Manager pipe configuration in the **Repository variables**. This can be created using Keeper Commander and initializing the config as Base64.

```
My Vault> sm client add --app MyApp --config-init b64

Successfully generated Client Device
====================================

Initialized Config: eyJob3N0bmFtZSI6ICJr....OUk1ZTV1V2toRucXRsaWxqUT0ifQ==
IP Lock: Enabled
Token Expires On: 2021-10-19 15:31:31
App Access Expires on: Never
```

{% hint style="info" %}
For more options creating a configuration, see the [configuration documentation](https://docs.keeper.io/en/keeperpam/about/secrets-manager-configuration#creating-a-secrets-manager-configuration)
{% endhint %}

The **Initialized Config:** Base64 string needs to be cut-n-pasted into your **Repository variables**. In this example the name of the variable is **KSM\_CONFIG**.

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FHxpNKxYvEfBGnuFCPGOy%2FScreen%20Shot%202021-11-01%20at%204.16.04%20PM.png?alt=media\&token=34c39cae-b40d-4bc4-ad1f-6e1bd201f713)

Next a `bitbucket-pipelines.yml` file needs to be added to the repository.

```
image: atlassian/default-image:2

pipelines:
  default:
    - step:
        name: 'Copy Image To S3'
        script:
          - pipe: keepersecurity/keeper-secrets-manager-pipe:<tag>
            variables:
              KSM_CONFIG: "${KSM_CONFIG}"
              SECRETS: |
                IumwT1QYRr8TTCtY8rqzhw/custom_field/AWS_ACCESS_KEY_ID > AWS_ACCESS_KEY_ID
                IumwT1QYRr8TTCtY8rqzhw/custom_field/AWS_SECRET_ACCESS_KEY > AWS_SECRET_ACCESS_KEY
                IumwT1QYRr8TTCtY8rqzhw/custom_field/AWS_DEFAULT_REGION > AWS_DEFAULT_REGION
                IumwT1QYRr8TTCtY8rqzhw/custom_field/S3_BUCKET > S3_BUCKET
                V8lFbio0Bs0LuvaSD5DDHA/file/IMG_0036.png > file:to_s3/my_image.png
              SECRETS_FILE: "secrets.env"
              SECRETS_FILE_TYPE: "export"
          - source ./secrets.env
          - pipe: atlassian/aws-s3-deploy:1.1.0
            variables:
              AWS_ACCESS_KEY_ID: "${AWS_ACCESS_KEY_ID}"
              AWS_SECRET_ACCESS_KEY: "${AWS_SECRET_ACCESS_KEY}"
              AWS_DEFAULT_REGION: "${AWS_DEFAULT_REGION}"
              S3_BUCKET: "${S3_BUCKET}"
              LOCAL_PATH: "to_s3"
```

The `bitbucket-pipelines.yml` contains the Keeper Secrets Manager pipe which will retrieve our AWS credential from a record and place them into environment variables. It will also get a PNG image and write it into a directory called **to\_s3**. The pipe will create a secrets file called secrets.env.

The `SECRETS_FILE_TYPE` is **export** which will allow the contents to be sourced and the secret values placed into environment.

Next the secrets file is sourced. This allows other pipes, and applications, access to the secrets as environmental variables.

The last step is using the **aws-s3-deploy** pipe to copy the image to the S3 bucket. The variables for the aws-s3-deploy pipe are set using the environmental variables provided by the Keeper Secrets Manager pipe's secret file.