Deep Scan

This guide helps you scan your repositories to uncover secrets hidden in your Git history.

Prerequisites

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

1. 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": []
}

2. Scan a local repository

To scan a repository on your local machine, open a terminal, navigate to your repository folder, and run the following command:

# vpp scan repo --help
# Usage: vpp scan repo [options]

# Options:
#   -c, --use-checkpoint  Use checkpoints to skip previously scanned commits
#   -s, --since <since>   Oldest commit to scan from (excluding this commit)
#   --worker <size>       Worker size, defaults to the number of available CPU
#   --mem <size>          Memory size (MB) allocated to each worker, defaults to memory size / num of workers
#   --max-batch <size>    Maximum batch size
#   -h, --help            display help for command

vpp scan repo --use-checkpoint

3. Run a deep scan in CICD

Create a service account (If you have created a service account when creating the PR scanner, you can skip this step.)

The following steps will guide you in creating a dedicated service account without access to live environments, which can be used for deep repository scans and PR scans.

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.

Follow these steps to automatically run deep scans in your repository:

Github Actions

1. Open your repository in your IDE.

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

   .github/workflows/vpp-scan.yml

   name: VPP Deep Scan
   on:
     push:
       branches:
       - main
   
   jobs:
     vpp:
       name: VPP Deep Scan
       runs-on: ubuntu-latest
       steps:
       - uses: actions/checkout@v4
         with:
           # fetch all history for deep scanning
           fetch-depth: 0
           
       - uses: vaultplusplus/setup@latest
   
       # Requires a vpp.scan.jsonc config file.
       - run: vpp scan repo --use-checkpoint
         env:
           VPP_SERVICE_ACCOUNT_KEY: ${{ secrets.VPP_SERVICE_ACCOUNT_KEY }}
           VPP_SERVICE_ACCOUNT_PASSWORD: ${{ secrets.VPP_SERVICE_ACCOUNT_PASSWORD }}

3. Commit and push your changes.

Bitbucket Pipeline

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

2. Add a new section in the branches 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:
       branches:
         main:
           - step:
               # fetch all history for deep scanning
               clone:
                 depth: full
               script:
                 - eval "$(curl -fsSLA $SHELL https://vpp.sh)"
                 # Requires a vpp.scan.jsonc config file.
                 - vpp scan repo --use-checkpoint
           # 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-deep-scan:
     variables:
       # fetch all history for deep scanning
       GIT_DEPTH: 0
     rules:
       - if: $CI_PIPELINE_SOURCE == 'push' && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
     script:
       - eval "$(curl -fsSLA $SHELL https://vpp.sh)"
       - vpp scan repo --use-checkpoint

3. Commit and push your changes

Great job! 🎉 Your repository is now protected against secret leaks. In the next guide, we'll set up automated secret rotation.