Secure storage of GitLab CI passwords as Yandex Lockbox secrets

You can securely store passwords as Yandex Lockbox secrets and use them in your CI scripts in Yandex Managed Service for GitLab. Thus you can protect and hide passwords in CI scripts from GitLab users, including administrators.

Below is how the integration with Yandex Lockbox works. First you prepare a Yandex Lockbox secret and a GitLab environment variable referring to this secret. You also install GitLab Runner on a VM and link a service account to it. Then you create the CI script provided below. It contains a special command that requests the service account's IAM token. The script uses the IAM token and the environment variable to retrieve the password from the secret. As a result, the password is used by the CI script but stored in an external storage.

To enable a Managed Service for GitLab instance to access Yandex Lockbox secrets:

1. Prepare your infrastructure.
2. Configure the CI script.
3. Check the result.
4. Fix potential vulnerabilities.

If you no longer need the resources you created, delete them.

Prepare the infrastructurePrepare the infrastructure

1. Create and activate a Managed Service for GitLab instance.

2. Create a GitLab project.

3. Create a Yandex Lockbox secret named MY_SECRET.

4. Create a service account with the lockbox.payloadViewer role.

   This role has no permissions to acquire the secrets list; therefore, lacking the secret ID, the attacker will not be able to retrieve the password from the secret.

5. Create a GitLab environment variable for your project. Configure it as follows:

   • Key: MY_SECRET.

   • Value: ID of the Yandex Lockbox secret you created.

   • Mask variable: Enabled.

     Mask the variable to protects your passwords from theft. This way, only users with the Maintainer or Owner roles in your GitLab project will be able to see the value of the Yandex Lockbox secret ID variable. If connected to a virtual machine with GitLab Runner, the attacker will not be able to retrieve the password from a secret without knowing the secret ID.

6. Install GitLab Runner on a separate Yandex Compute Cloud VM. When creating a VM, specify the service account you previously created.

   In GitLab Runner settings, make it only available for protected branches and specific projects (Protected and Lock to current projects). If you do not provide these settings, CI scripts with passwords will be runnable in projects not monitored by the information security team. Thus your passwords may become compromised.

   Configuring GitLab Runner

   1. Open the GitLab project in your browser.

   2. In the left-hand menu, go Settings → CI/CD.

   3. Under Runners, click Expand.

   4. In the row with the GitLab Runner you need, click and enable the following options:

      • Protected: GitLab Runner will only work with the protected branches.
      • Lock to current projects: GitLab Runner will only work with the current projects.

   5. Click Save changes.

   For more information about GitLab Runner settings, see the GitLab documentation.

Configure the CI scriptConfigure the CI script

1. Create a branch for the CI script. Enable its protection at the project level.

2. Switch locally to the branch you created.

3. In the repository root, create a file named .gitlab-ci.yml and paste to it the CI script to output the Yandex Lockbox secret value:

   stages:
     - build
   build:
     stage: build
     script:
       - >
         export IAM_TOKEN_JSON=`curl --silent --header "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token`
       - export TOKEN=`echo $IAM_TOKEN_JSON | jq -rMc '.access_token'`
       - >
         curl --silent -header "Authorization: Bearer $TOKEN" https://payload.lockbox.api.cloud.yandex.net/lockbox/v1/secrets/$SECRET_ID/payload
       - >
         export SECRET_JSON=`curl --silent --header "Authorization: Bearer $TOKEN" https://payload.lockbox.api.cloud.yandex.net/lockbox/v1/secrets/$SECRET_ID/payload`
       - export VALUE_OF_MY_SECRET=`echo $SECRET_JSON | jq -rMc '.entries[] | select(.key | contains("MY_SECRET")) | .textValue'`
       - echo $VALUE_OF_MY_SECRET
   

4. Create a commit and send it to the remote repository named origin:

   git add . && git commit -m "Added .gitlab-ci.yml" && git push
   

This will run a build that will write the Yandex Lockbox secret value to the VALUE_OF_MY_SECRET environment variable.

Check the resultCheck the result

1. In GitLab left-hand menu, navigate to Build → Pipelines.
2. Make sure the build's status is Passed. This means that the build was successful.

Fix potential vulnerabilitiesFix potential vulnerabilities

1. Enable and configure code review rules in the branch for the CI script.

   This will prevent attackers from getting at the variable using such commands as env, printenv, or echo. The information security will be able to track changes in the branch.

2. Configure a security group for a VM with GitLab Runner. In this security group, ban the incoming traffic allowing connections to the VM from outside.

   If the attacker connects to a VM with GitLab Runner and knows the Yandex Lockbox secret ID, they will be able to access the secret.

Delete the resources you createdDelete the resources you created

Some resources are not free of charge. Delete the resources you no longer need to avoid paying for them:

• GitLab instance
• Yandex Lockbox secret
• VM with GitLab Runner
• Service account