Securing your data in Continuous Delivery

Protecting your sensitive data in Continuous Delivery

The Continuous Delivery service encrypts customer-owned sensitive data before it stores it in databases that are used internally by the service. Sensitive data includes third-party tool integration configuration data and Delivery Pipeline property values. Data is encrypted by using encryption keys that are internal to the Continuous Delivery service or by using encryption keys from the root key that is specified within an instance of the IBM® Key Protect for IBM Cloud® service or the IBM Cloud® Hyper Protect Crypto Services service.

DevOps processes often require various types of credentials (such as usernames and passwords, API keys, service keys, and SSH keys) to interact with other systems to build, test, and deploy applications. You are responsible for ensuring that these credentials aren't inadvertently shared outside of their intended audience. Access to these credentials by malicious actors might disrupt your IT operations, cause unexpected costs, or use your resources to start attacks. IBM is not responsible for protecting and maintaining the security of your credentials.

To keep your credentials secure, make sure that you follow this guidance:

• Do not store credentials in Git repos. Depending on the repo settings, files within a repo might be visible to other members of your organization, other IBM Cloud users, or the public internet.
• Do not include user credentials in Delivery Pipeline definitions because they might be visible to other users. Specifically, do not place user credentials within Delivery Pipeline Classic job definition scripts, Delivery Pipeline Tekton yaml files, or scripts that are started by delivery pipelines.
• Do not publish user credentials in log files that are created when a pipeline runs because these files might be shared.
• Do not specify credentials in plain text in calls to Continuous Delivery APIs, such as when you configure tool integrations, Tekton pipeline environment properties, or Tekton pipeline trigger properties.
• Do not include credentials, personal identifying information, or other sensitive information in calls to the POST /toolchains/{toolchain_id}/events API. The API sends events containing the data you specify to instances of Event Notifications that are integrated into the toolchain. Event Notifications will subsequently forward the events to configured destinations such as email, SMS, and Slack.
• Do not specify credentials in plain text in Terraform configuration files, such as when you define tool integration resources, Tekton pipeline environment property resources, or Tekton pipeline trigger property resources. Instead, manage credentials in a secrets storage service and specify them by reference in API calls and Terraform configurations. For more information about managing secrets by reference, see Protecting your credentials by using secrets references.

IBM Cloud provides several options that you can use for secure key storage and secrets.

• Classic pipeline secure environment properties
• Tekton pipeline secure environment properties
• IBM® Key Protect for IBM Cloud®
• IBM Cloud® Hyper Protect Crypto Services
• HashiCorp Vault

For more information about secure DevOps best practices, see DevOps Security.

Protecting your credentials by using secrets references

Many of the properties that you can configure when you are working with Continuous Delivery toolchains and delivery pipelines, such as passwords, API keys, certificates, or other tokens, are classified as secrets or credentials. To set the value of a secure property, you can either use plain text or a secrets reference. Using a secrets reference is the recommended method for setting the value of a secure property.

When you set a secure property with a plain text secret value, Continuous Delivery actively encrypts and stores the value internally. Although the value is kept secure within the Continuous Delivery service, the service cannot protect the value on the client side. When you set a secure property by using the console in your browser, by calling an API, or by configuring a Terraform resource, the plain text secret might be exposed on your local systems. Plain text secrets are also more difficult to rotate. When a secret, such as an API key, must be rotated, all secure properties that carry the secret value must also be located and updated.

When you set a secure property with a secrets reference value, the value is a specially formatted string that refers to the location or address of a secret that is managed within a secrets storage service such as IBM® Key Protect for IBM Cloud®, IBM Cloud® Secrets Manager, or HashiCorp Vault. Although Continuous Delivery actively encrypts and stores the secrets reference value internally, the secret value is not exposed on the client side. When Continuous Delivery must retrieve the secret to perform processing on your behalf, it internally retrieves the value from the referenced secrets store. Secrets references are also resilient to rotation. Typically, when a secret is rotated within a secrets store, the location or address of the secret remains the same. Only the secret value itself is changed.

Two types of secrets references are supported: by name or by Cloud Resource Name (CRN). Currently, only Secrets Manager tool integrations support referencing secrets by CRN. This format allows for greater flexibility because you can reference secrets from a Secrets Manager instance in a different account if the correct authorization is in place.

Make sure that you consider the following prerequisites for specifying a secrets reference within the scope of a toolchain:

• The secrets store must be added to the toolchain as a tool integration. For more information about secrets store tool integrations, see Configuring Key Protect, Configuring Secrets Manager, and Configuring HashiCorp Vault.
• An IAM service-to-service authorization policy must be configured to allow the source toolchain to retrieve secrets from the target secrets store. For more information about service-to-service authorizations, see Using authorizations to grant access between services.

When you work outside of the console, such as with the API or Terraform, use the following format for secrets references by name:

Secret value:

• ref://secrets-manager.REGION.RESOURCE-GROUP.SECRETS-MANAGER-INSTANCE-NAME1/SECRETS-GROUP-NAME/SECRET-NAME when you reference secrets that are contained within Key Protect.
• ref://secrets-manager.eu-de.EU-RG.SM-1/default/api-key when you reference secrets that are contained within Secrets Manager.

For example, if the secert is of a key value, then you can select the key:

• ref://secrets-manager.eu-gb.Default.Secrets%20Manager-zc/Default/mk-kv-pair?key=ibmcloud-api-key

where:

• SECRETS-MANAGER-INSTANCE-NAME1 is the name of the secrets store integration in the toolchain, not the name of the secrets store service instance.
• SECRET_GROUP_NAME is the name of the group that contains the secret within Secrets Manager.
• SECRET_NAME is the name of the secret in the secrets store.
• KEY_NAME is the name of the key in the key-value secret.

To use a CRN secrets reference, obtain the secret CRN directly from the Secrets Manager UI or programmatically by using the CLI, API, or SDKs.

export CD_TOOLCHAIN_AUTH_TYPE=iam && \
export CD_TOOLCHAIN_APIKEY={iam_api_key} && \
export CD_TOOLCHAIN_URL=https://api.us-south.devops.cloud.ibm.com/toolchain/v2

curl -X POST \
https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/01234567-89ab-cdef-0123-456789abcdef/tools \
-H "Authorization: Bearer $TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "tool_type_id": "slack",
    "parameters": {
    "api_token": "{vault::my-kms-tool-integration.my-slack-webhook}",
    "channel_name": "my_slack_channel_name",
    "team_url": "my_slack_team_name"
    }
}' 

const CdToolchainV2 = require('@ibm-cloud/continuous-delivery/cd-toolchain/v2');
...
(async () => {
    const toolchainService = CdToolchainV2.newInstance();
    const slackParameters = {
        api_token: "{vault::my-kms-tool-integration.my-slack-webhook}",
        channel_name: "my_slack_channel_name",
        team_url: "my_slack_team_name"
    };

    const toolPrototypeModel = {
        toolchainId: "01234567-89ab-cdef-0123-456789abcdef",
        toolTypeId: "slack",
        parameters: slackParameters
    };

    const slackTool = await toolchainService.createTool(toolPrototypeModel);
})();

import (
    "github.com/IBM/continuous-delivery-go-sdk/cdtoolchainv2"
)
...
toolchainClientOptions := &cdtoolchainv2.CdToolchainV2Options{}
toolchainClient, err := cdtoolchainv2.NewCdToolchainV2UsingExternalConfig(toolchainClientOptions)
slackParameters := map[string]interface{}{
    "api_token": "{vault::my-kms-tool-integration.my-slack-webhook}",
    "channel_name": "my_slack_channel_name",
    "team_url": "my_slack_team_name",
}
createToolOptions := toolchainClient.NewCreateToolOptions("01234567-89ab-cdef-0123-456789abcdef", "slack")
createToolOptions.SetParameters(slackParameters)
slackTool, response, err := toolchainClient.CreateTool(createToolOptions)

from ibm_continuous_delivery.cd_toolchain_v2 import CdToolchainV2
...
toolchain_service = CdToolchainV2.new_instance()
slack_parameters = {
    "api_token": "{vault::my-kms-tool-integration.my-slack-webhook}",
    "channel_name": "my_slack_channel_name",
    "team_url": "my_slack_team_name"
}
slack_tool = toolchain_service.create_tool(
    toolchain_id = "01234567-89ab-cdef-0123-456789abcdef",
    tool_type_id = "slack",
    parameters = slack_parameters
)

   import com.ibm.cloud.continuous_delivery.cd_toolchain.v2.CdToolchain;
   import com.ibm.cloud.continuous_delivery.cd_toolchain.v2.model.*;
   ...
   CdToolchain toolchainService = CdToolchain.newInstance();
   HashMap<String, Object> slackParameters = new HashMap<>();
   slackParameters.put("api_token", "{vault::my-kms-tool-integration.my-slack-webhook}");
   slackParameters.put("channel_name", "my_slack_channel_name");
   slackParameters.put("team_url", "my_slack_team_name");
   CreateToolOptions createSlackToolOptions = new CreateToolOptions.Builder()
      .parameters(slackParameters)
      .toolchainId({toolchain_id})
      .toolTypeId("slack")
      .build();
   Response<ToolchainToolPost> response = toolchainService.createTool(createSlackToolOptions).execute();
   ToolchainToolPost slackTool = response.getResult();

curl -X POST \
https://api.us-south.devops.cloud.ibm.com/toolchain/v2/toolchains/01234567-89ab-cdef-0123-456789abcdef/tools \
-H "Authorization: Bearer $TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "tool_type_id": "slack",
    "parameters": {
    "api_token": "crn:v1:bluemix:public:secrets-manager:us-south:a/9bb43e401a7a87d15145da761da98571:604de62c-c04f-3f5e-b7e8-4acafe0ecde7:secret:5ec17023-b631-fbcb-ef9c-4f2eb01f1dda",
    "channel_name": "my_slack_channel_name",
    "team_url": "my_slack_team_name"
    }
}' 

const CdToolchainV2 = require('@ibm-cloud/continuous-delivery/cd-toolchain/v2');
...
(async () => {
    const toolchainService = CdToolchainV2.newInstance();
    const slackParameters = {
        api_token: "crn:v1:bluemix:public:secrets-manager:us-south:a/9bb43e401a7a87d15145da761da98571:604de62c-c04f-3f5e-b7e8-4acafe0ecde7:secret:5ec17023-b631-fbcb-ef9c-4f2eb01f1dda",
        channel_name: "my_slack_channel_name",
        team_url: "my_slack_team_name"
    };

    const toolPrototypeModel = {
        toolchainId: "01234567-89ab-cdef-0123-456789abcdef",
        toolTypeId: "slack",
        parameters: slackParameters
    };

    const slackTool = await toolchainService.createTool(toolPrototypeModel);
})();

import (
    "github.com/IBM/continuous-delivery-go-sdk/cdtoolchainv2"
)
...
toolchainClientOptions := &cdtoolchainv2.CdToolchainV2Options{}
toolchainClient, err := cdtoolchainv2.NewCdToolchainV2UsingExternalConfig(toolchainClientOptions)
slackParameters := map[string]interface{}{
    "api_token": "crn:v1:bluemix:public:secrets-manager:us-south:a/9bb43e401a7a87d15145da761da98571:604de62c-c04f-3f5e-b7e8-4acafe0ecde7:secret:5ec17023-b631-fbcb-ef9c-4f2eb01f1dda",
    "channel_name": "my_slack_channel_name",
    "team_url": "my_slack_team_name",
}
createToolOptions := toolchainClient.NewCreateToolOptions("01234567-89ab-cdef-0123-456789abcdef", "slack")
createToolOptions.SetParameters(slackParameters)
slackTool, response, err := toolchainClient.CreateTool(createToolOptions)

from ibm_continuous_delivery.cd_toolchain_v2 import CdToolchainV2
...
toolchain_service = CdToolchainV2.new_instance()
slack_parameters = {
    "api_token": "crn:v1:bluemix:public:secrets-manager:us-south:a/9bb43e401a7a87d15145da761da98571:604de62c-c04f-3f5e-b7e8-4acafe0ecde7:secret:5ec17023-b631-fbcb-ef9c-4f2eb01f1dda",
    "channel_name": "my_slack_channel_name",
    "team_url": "my_slack_team_name"
}
slack_tool = toolchain_service.create_tool(
    toolchain_id = "01234567-89ab-cdef-0123-456789abcdef",
    tool_type_id = "slack",
    parameters = slack_parameters
)

   import com.ibm.cloud.continuous_delivery.cd_toolchain.v2.CdToolchain;
   import com.ibm.cloud.continuous_delivery.cd_toolchain.v2.model.*;
   ...
   CdToolchain toolchainService = CdToolchain.newInstance();
   HashMap<String, Object> slackParameters = new HashMap<>();
   slackParameters.put("api_token", "crn:v1:bluemix:public:secrets-manager:us-south:a/9bb43e401a7a87d15145da761da98571:604de62c-c04f-3f5e-b7e8-4acafe0ecde7:secret:5ec17023-b631-fbcb-ef9c-4f2eb01f1dda");
   slackParameters.put("channel_name", "my_slack_channel_name");
   slackParameters.put("team_url", "my_slack_team_name");
   CreateToolOptions createSlackToolOptions = new CreateToolOptions.Builder()
      .parameters(slackParameters)
      .toolchainId({toolchain_id})
      .toolTypeId("slack")
      .build();
   Response<ToolchainToolPost> response = toolchainService.createTool(createSlackToolOptions).execute();
   ToolchainToolPost slackTool = response.getResult();

variable "slack_webhook" {}
variable "slack_channel" {}
variable "slack_team" {}

data "ibm_resource_group" "rg" {
    name = "default"
}

resource "ibm_resource_instance" "kms" {
    name              = "my-kms-service-instance"
    service           = "kms"
    plan              = "tiered-pricing"
    location          = "us-south"
    resource_group_id = data.ibm_resource_group.rg.id
}

resource "ibm_kms_key" "key" {
    instance_id  = ibm_resource_instance.kms.guid
    key_name     = "my-slack-webhook"
    standard_key = true
    payload      = base64encode(var.slack_webhook)
}

resource "ibm_cd_toolchain" "toolchain" {
    name              = "tf-toolchain-secret-refs"
    resource_group_id = data.ibm_resource_group.rg.id
}

resource "ibm_iam_authorization_policy" "s2s" {
    source_service_name         = "toolchain"
    source_resource_instance_id = ibm_cd_toolchain.toolchain.id
    target_service_name         = "kms"
    target_resource_instance_id = ibm_resource_instance.kms.guid
    roles                       = ["Viewer", "ReaderPlus"]
}

resource "ibm_cd_toolchain_tool_keyprotect" "integration" {
    toolchain_id = ibm_cd_toolchain.toolchain.id
    parameters {
        name           = "my-kms-tool-integration"
        region         = var.region
        resource_group = data.ibm_resource_group.rg.name
        instance_name  = ibm_resource_instance.kms.name
    }
    depends_on = [
        ibm_iam_authorization_policy.s2s
    ]
}

resource "ibm_cd_toolchain_tool_slack" "integration" {
    toolchain_id = ibm_cd_toolchain.toolchain.id
    parameters {
        webhook      = "{vault::my-kms-tool-integration.my-slack-webhook}"
        channel_name = var.slack_channel
        team_name    = var.slack_team
    }
    depends_on = [
        ibm_cd_toolchain_tool_keyprotect.integration
        ibm_kms_key.key
    ]
}

variable "slack_webhook" {}
variable "slack_channel" {}
variable "slack_team" {}
variable "secrets_manager_name" {}

data "ibm_resource_group" "rg" {
    name = "default"
}

data ibm_resource_instance "sm" {
    name = var.secrets_manager_name
}

resource "ibm_sm_arbitrary_secret" "key" {
    instance_id     = data.ibm_resource_instance.sm.guid
    region          = data.ibm_resource_instance.sm.location
    secret_group_id = "default"
    name            = "my-slack-webhook"
    payload         = "var.slack_webhook"
}

resource "ibm_cd_toolchain" "toolchain" {
    name              = "tf-toolchain-secret-refs"
    resource_group_id = data.ibm_resource_group.rg.id
}

resource "ibm_iam_authorization_policy" "s2s" {
    source_service_name         = "toolchain"
    source_resource_instance_id = ibm_cd_toolchain.toolchain.id
    target_service_name         = "secrets-manager"
    target_resource_instance_id = data.ibm_resource_instance.sm.guid
    roles                       = ["Viewer", "SecretsReader"]
}

resource "ibm_cd_toolchain_tool_secretsmanager" "integration" {
    toolchain_id = ibm_cd_toolchain.toolchain.id
    parameters {
        name             = "my-sm-tool-integration"
        instance_id_type = "instance-crn"
        instance_crn     = data.ibm_resource_instance.sm.resource_crn
    }
    depends_on = [
        ibm_iam_authorization_policy.s2s
    ]
}

resource "ibm_cd_toolchain_tool_slack" "integration" {
    toolchain_id = ibm_cd_toolchain.toolchain.id
    parameters {
        webhook      = ibm_sm_arbitrary_secret.key.crn
        channel_name = var.slack_channel
        team_name    = var.slack_team
    }
    depends_on = [
        ibm_cd_toolchain_tool_secretsmanager.integration
    ]
}

Protecting your data with customer-managed keys

By default, Continuous Delivery encrypts your data by using keys that are internal to the Continuous Delivery service. For greater security and control, you can configure Continuous Delivery to encrypt your data by using keys that you manage. This option is available only under the Professional plan, and only at the time that you are provisioning an instance of the Continuous Delivery service. If you select your own Key Management Service, such as Key Protect or IBM Cloud® Hyper Protect Crypto Services, the following values are encrypted by using your own key instead of the encryption keys that are internal to the Continuous Delivery service.

The following components encrypt personal data by using only the provider-managed encryption key.

For more information about creating a Continuous Delivery service instance that encrypts data with a customer key, see Creating a Continuous Delivery service instance.

Protecting your data when you use third-party tool integrations

When you configure a tool integration for a toolchain, you explicitly enable data sharing between the Continuous Delivery service and the tool integration. The kind of data that is shared, and whether data is sent to the tool, received from the tool, or both, varies depending on the type of tool integration.

Before you configure a tool integration, make sure you understand what data is shared. If you work with regulated data or data that you consider sensitive, make sure that the third-party tool usage and any data that might be shared with it do not compromise the confidentiality, integrity, or availability of your resources, or otherwise violate regulatory controls.

To learn more about tool integrations, see Configuring tool integrations.

Protecting your data when you use Git Repos and Issue Tracking

Git Repos and Issue Tracking is an IBM-hosted component of the Continuous Delivery service. All of the data that you provide to Git Repos and Issue Tracking, including but not limited to source files, issues, pull requests, and project configuration properties, is managed securely within Continuous Delivery. However, Git Repos and Issue Tracking supports various mechanisms for exporting, sending, or otherwise sharing data to users and third parties.

The ability of Git Repos and Issue Tracking to share information is typical of many social coding platforms. However, such sharing might conflict with regulatory controls that apply to your business. After you create a project in Git Repos and Issue Tracking, but before you entrust any files, issues, records, or other data with the project, review the project settings and change any settings that you deem necessary to protect your data. Settings to review include visibility levels, email notifications, integrations, web hooks, access tokens, deploy tokens, and deploy keys.

Protecting your data when you use Delivery Pipelines

Continuous Delivery pipelines run the jobs and steps that you provide. The Continuous Delivery service securely manages the log output and build artifacts that are produced by your pipeline runs. However, Continuous Delivery does not limit or manage the function of your pipeline job or step scripts.

When you develop and configure your pipeline job and step scripts, make sure that your scripts do not run actions that might compromise the confidentiality, integrity, or availability of your resources, or otherwise violate regulatory controls.

To learn more about Delivery Pipelines, see and Working with pipelines and Working with Tekton pipelines.

Protecting your data when you use Terraform

When you use Terraform to manage Continuous Delivery resources, some of the variables, arguments, and attributes that are processed by Terraform might carry secret values such as passwords or API tokens. These values might be specified by you in your Terraform configuration language files, they might be retrieved and stored in Terraform state by the Terraform tool, or both. The following list provides examples of secret values that you must protect when you use Terraform.

• The IAM API Key that the IBM Cloud Terraform Provider requires to authenticate to the IBM Cloud. This key is specified in the ibmcloud_api_key argument of your Terraform module's provider "ibm" block.
• The arguments or attributes that represent passwords, access tokens, API keys, or other kinds of secrets in some ibm_cd_toolchain_tool resources and data sources.
• Property values that are designated as secrets in some ibm_cd_tekton_pipeline_property or ibm_cd_tekton_pipeline_trigger_property resources or data sources.

Use IBM Cloud Schematics and the following practices to limit the exposure of sensitive data:

• Use Terraform variables to inject values into Terraform blocks.
• Use IBM Cloud Schematics to securely manage and share secrets.
• Use IBM Cloud Schematics to securely manage and share the Terraform state.
• Use the Continuous Delivery secrets references when you specify secrets within the ibm_cd_toolchain_tool, ibm_cd_tekton_pipeline_property, or ibm_cd_tekton_pipeline_trigger_property resources.

If you are using the Terraform command-line tool, use the following practices to limit the exposure of sensitive data:

• Use Terraform variables to inject values into Terraform blocks.
• Allow the Terraform command-line tool to prompt for values when you run commands such as terraform plan or terraform apply.
• Control access to your Terraform state since it might contain secrets. Local Terraform state is written in plain text.
• Use the Continuous Delivery secrets references when you specify secrets within the ibm_cd_toolchain_tool, ibm_cd_tekton_pipeline_property, or ibm_cd_tekton_pipeline_trigger_property resources.

To limit the exposure of sensitive data, avoid the following practices:

• Writing secrets in plain text inside any Terraform blocks, such as resource blocks, data blocks, or provider blocks.
• Writing secrets in plain text within the terraform.tfvars, terraform.tfvars.json, *.auto.tfvars, or *.auto.tfvars.json files.
• Delivering the terraform.tfvars, terraform.tfvars.json, *.auto.tfvars, or *.auto.tfvars.json files that contain secrets to source code repos.
• Delivering your Terraform state into source code repos.

Use IBM Cloud Schematics instead of the Terraform command-line tool to process your Terraform configurations. IBM Cloud Schematics offers several advantages such as secure storage of sensitive configuration properties.

For more information about IBM Cloud Schematics, see the IBM Cloud Schematics documentation.

For more information about sensitive data in Terraform state, see Sensitive Data in State.

For more information about how to set input variables in Terraform, see Assigning Values to Root Module Variables.

Deleting your data from Continuous Delivery

When you delete a Continuous Delivery service instance, the related toolchains, tool integrations, tools, and data (including personal data) are not deleted. For more information about how to manage and delete data that is stored with toolchains, tool integrations, and tools, see Modifying, exploring, and deleting personal data.