PR Check

This guide helps you integrate Vault++ into your pull request pipeline to detect secret leaks and display warnings.

Prerequisites

1. Have a Vault++ account.
2. Have a git repository.

1. Create a PR service account

A dedicated service account with no access to live environments is required to securely scan secrets in PR pipelines. Follow these steps to create one:

Github Actions

1. Log in to your Vault++ account, choose the desired application, and navigate to the Settings tab.

2. Find the Service Accounts section and click the Add () button.

3. Enter a descriptive label, for example PR Scan, then press Enter.

4. A dialog will display the private key and an encryption password. Do not close the dialog as you cannot access these credentials again after closing.

5. In a new browser tab, open your GitHub repository and click the Settings tab.

6. In the left sidebar, under Security , click Secrets and variables > Actions.

7. Add the following secrets from the Vault++ dialog to Repository secrets:

   • VPP_SERVICE_ACCOUNT_KEY
   • VPP_SERVICE_ACCOUNT_PASSWORD
   warning

   Do not grant this service account access to any environment, as it will be used in PR pipelines, which run on unprotected branches.

Bitbucket Pipeline

1. Log in to your Vault++ account, choose the desired application, and navigate to the Settings tab.

2. Find the Service Accounts section and click the Add () button.

3. Enter a descriptive label, for example PR Scan, then press Enter.

4. A dialog will display the private key and an encryption password. Do not close the dialog as you cannot access these credentials again after closing.

5. In a new browser tab, open your Bitbucket repository.

6. In the left sidebar, click Repository Settings and then click Repository variables under the Pipelines section.

7. Add the following secrets from Vault++:

   • VPP_SERVICE_ACCOUNT_KEY
   • VPP_SERVICE_ACCOUNT_PASSWORD
   warning

   Do not grant this service account access to any environment, as it will be used in PR pipelines, which run on unprotected branches.

8. In the left sidebar, click Access tokens under the Security section.

9. Click Create Repository Access Token.

10. Enter a name, e.g., VPP PR Check

11. Enable Repositories: Write and Pull requests: Write, then click Create.

12. Copy the access token from the modal (the first token shown).

13. Go back to Repository variables (as in step 6) and add a new secret:

    • Name: BITBUCKET_REPO_TOKEN
    • Value: The access token you just created.

Gitlab Pipeline

1. Log in to your Vault++ account, choose the desired application, and navigate to the Settings tab.

2. Find the Service Accounts section and click the Add () button.

3. Enter a descriptive label, for example PR Scan, then press Enter.

4. A dialog will display the private key and an encryption password. Do not close the dialog as you cannot access these credentials again after closing.

warning

Do not grant this service account access to any environment, as it will be used in PR pipelines, which run on unprotected branches.

5. In a new browser tab, open your GitLab repository.

6. In the left sidebar, click Settings, then select Access tokens.

7. Click Add new token and use the following details:

   1. Name: e.g., VPP
   2. Expiration: Recommended to set it to 6 months.
   3. Role: Set to Reporter
   4. Scopes: Enable api

8. Copy the generated token.

info

For repositories in groups, Repository Access Tokens are only available with paid plans. On the free plan, Repository Access Tokens are available only for repositories in personal accounts. If you're working with a group repository on a free plan, use a Personal Access Token instead.

9. In the left sidebar, click Settings, then select CI/CD.

10. Scroll to the Variables section and click Add Variable.

11. Add the following variables:

    • GITLAB_PROJECT_TOKEN (with the token generated in step 8)
    • VPP_SERVICE_ACCOUNT_KEY and VPP_SERVICE_ACCOUNT_PASSWORD from Vault++

    Use these settings for each variable:

    1. Type: Variable
    2. Environments: All (default)
    3. Visibility: Masked and hidden
    4. Disable the Protect variable flag (so it's accessible from all branches)
    5. Disable the Expand variable reference option
    6. Key: Set to the respective variable name (GITLAB_PROJECT_TOKEN, VPP_SERVICE_ACCOUNT_KEY or VPP_SERVICE_ACCOUNT_PASSWORD)
    7. Value: Enter the corresponding value for each key

tip

You can use the same variable key with different values in GitLab CICD variables. This allows you to assign different values to VPP_SERVICE_ACCOUNT_KEY and VPP_SERVICE_ACCOUNT_PASSWORD for each environment, which implies using different service accounts for each environment.

2. Add a vpp scan config file

If you haven't already, create a vpp.scan.jsonc file in the root folder of your repository as shown below.

vpp.scan.jsonc

{
  "$schema": "https://vaultplusplus.com/scan-schema.json",
  "organization": "<your org slug>", // change to your organization slug
  
  // Whitelisted Signatures
  "whitelist": []
}

3. Create a PR pipeline

Github Actions

1. Open your repository in your IDE.

2. Create a new PR workflow YAML file, e.g., .github/workflows/vpp-pr.yml, with the following content:

   .github/workflows/vpp-pr.yml

   name: VPP PR Scan
   on:
     pull_request:
       branches: # Adjust according to your needs
       - main
   
   jobs:
     vpp:
       permissions:
         contents: read
         pull-requests: write
       name: VPP PR Check
       runs-on: ubuntu-latest
       timeout-minutes: 5
       steps:
       - uses: actions/checkout@v4
       - uses: vaultplusplus/setup@latest
   
       # In a monorepo, run vpp status for each application.
       # Use the working-directory parameter to select the application folder.
       #
       # Requires a vpp.jsonc config file.
       - run: vpp status
         # working-directory: ./apps/app1   # example for monorepo
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           VPP_SERVICE_ACCOUNT_KEY: ${{ secrets.VPP_SERVICE_ACCOUNT_KEY }}
           VPP_SERVICE_ACCOUNT_PASSWORD: ${{ secrets.VPP_SERVICE_ACCOUNT_PASSWORD }}
   
       # Run vpp scan pr at the repository root.
       # Requires a vpp.scan.jsonc config file.
       - run: vpp scan pr
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           VPP_SERVICE_ACCOUNT_KEY: ${{ secrets.VPP_SERVICE_ACCOUNT_KEY }}
           VPP_SERVICE_ACCOUNT_PASSWORD: ${{ secrets.VPP_SERVICE_ACCOUNT_PASSWORD }}

3. Commit and push your changes.

Allow GitHub Actions to approve PR

Vault++ will automatically approve your PR if no secrets are detected. By default, GitHub disables PR approvals from Actions. To enable it:

1. For GitHub Enterprise or Organization accounts:

   • Go to your Enterprise or Organization settings page.
   • In the left sidebar, click Actions > General.
   • Enable Allow GitHub Actions to create and approve pull requests, then click Save.

2. For repositories on personal accounts (or after completing step 1 for Enterprise/Organization repositories):

   • Go to your repository settings.
   • Click Actions > General.
   • Enable Allow GitHub Actions to create and approve pull requests, then click Save.

Bitbucket Pipeline

1. Open the bitbucket-pipelines.yml file in your repository.

2. Add a new section in the pull-requests pipeline, or create a new step if you already have an existing one, with the following content:

   bitbucket-pipelines.yml

   image: atlassian/default-image:4
   pipelines:
     pull-requests:
       "**":
         - step:
             name: VPP PR Check
             script:
               - eval "$(curl -fsSLA $SHELL https://vpp.sh)"
               # In a monorepo, run vpp status for each application (cd to each app).
               - vpp status
               - vpp scan pr
         # Existing steps...

3. Commit and push your changes

Gitlab Pipeline

1. Open the .gitlab-ci.yml file in your repository.

2. Add the following snippet at the end of the file:

   .gitlab-ci.yml

   vpp-pr:
     rules:
       - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
     script:
       - eval "$(curl -fsSLA $SHELL https://vpp.sh)"
       # In a monorepo, run vpp status for each application (cd to each app).
       - vpp status
       - vpp scan pr

3. Commit and push your changes

Well done! 🎉 Your PR is now protected against secret leaks. Next, we'll perform a Deep Scan to uncover hardcoded secrets hidden in your repository's history.