scan repo

Note

You must have version 0.17.0 or higher of the Vault Radar CLI installed.

To check the current version of your CLI, use the version command.

The scan repo command is used for scanning a git repository.

Authentication

The scan repo command can either scan an existing repo clone or automatically clone the repo using provided repo URL. If existing clone is used, then no authentication needed. If a repo is public, then no authentication is needed. Otherwise, a git token must be provided, so CLI can clone the repo. CLI will read the token from VAULT_RADAR_GIT_TOKEN environmental variable. The environment variable value depends on git server provider. For GitHub and GitLab it can be just a personal access token (PAT). For Bitbucket and Azure DevOps, it should be in format <username>:<PAT>.

Note

CLI internally uses https:// to clone the repo and sets HTTP username:password part of the clone URL to the value of VAULT_RADAR_GIT_TOKEN. Contact your git server provider documentation about the exact format used for https:// auth in case the format described above does not work.

Usage

Usage: vault-radar scan repo [options]

Command options

--url, -u: If specified clones and scans the given repo
--clone-dir, -c: If specified scans the given existing repo clone
--outfile, -o: Specifies the file to store information about found secrets (required for offline only)
--format, -f: Specifies the output format, csv and json are supported. Defaults to csv
--baseline, -b: Specifies the file with previous scan results. Only new secrets will be reported
--limit, -l: Specifies the maximum number of secrets to be reported. The scan will stop when the limit is reached
--commit-limit: Specifies the maximum number of commits to be scanned. The scan will stop when the limit is reached
--index-file: Specifies the index file path to use in order to determine which risks are Vaulted
--skip-history: If specified, skips full git history and only scans tip of the (default) branch. Only supported when --offline is specified
--offline: Specifies that the scan should be run in offline mode, without connecting to HCP
--disable-ui: Specifies that the scan summary should not be logged to stdout
--skip-activeness: If specified, skips activeness checks

Scanning a repo

Automatically clones and scans all commits available in a repo and uploads the results to HCP.

$ vault-radar scan repo -u <REPO URL>

Scanning an existing clone

Scan an existing repo (clone) and write the results to a file in CSV format

$ vault-radar scan repo -c <PATH TO CLONE DIR> -o <PATH TO OUTPUT>.csv

Note

The difference between automatically cloning a repo and above is that with existing clone only commits available in the clone will be scanned, not all the repo reachable commits. The clone might have much fewer commits than the repo itself, e.g. if the clone is a shallow clone or if only a single branch was cloned. To scan all the reachable commits it is recommended to scan repo using the -u parameter.

Scanning an existing clone and output in JSON

Scan a repo (clone) and write the results to a file in JSON Lines format.

$ vault-radar scan repo -c <PATH TO CLONE DIR> -o <PATH TO OUTPUT>.jsonl -f json

HCP connection scanning behavior

The default behavior of scan commands is to require an HCP cloud connection to scan. This is to ensure that hashes are generated using a shared salt from the cloud keeping consistency across scans. In order to populate the HCP connection information needed, refer to the HCP upload page.

To allow for scanning to continue working without the need for HCP cloud connection you can use the new --offline flag as such.

$ vault-radar scan repo --offline -u <REPO URL> -o <PATH TO OUTPUT>.csv

Scanning a clone excluding history

Scan a repo (clone) skipping full git history and and write the results to a file in CSV format. Offline flag is required for skipping history.

$ vault-radar scan repo  -c <PATH TO CLONE DIR> -o <PATH TO OUTPUT>.csv --skip-history --offline

Note

To properly attribute found risks to git_reference (branch) where risks were introduced, it is expected that the default branch is checked out or the clone is a bare clone. If non-default branch is checked out most risks will be attributed to that branch instead.

Note

Only risks that are still on tip of that branch will be reported.

Scanning using a baseline file

Perform a scan using a previous scan's result and write the new changes to an outfile. With -b option, only new risks, risks that were not found in the previous scan will be reported.

$ vault-radar scan repo -u <REPO URL> -b <PATH TO BASELINE>.csv \
    -o <PATH TO OUTPUT>.csv

Note

It is expected that previous and current scans are "similar", e.g. both either clone or repo scans, with or without history, etc.

Scanning using a Vault index file

Perform a scan using a generated vault index and upload results to HCP. In this mode, if a risk was previously found in Vault, the scan results will report the location in Vault as well.

$ vault-radar scan repo -u <REPO URL> \
    --index-file <PATH TO VAULT INDEX>.jsonl

How to generate a Vault Index

Scan and restrict the number of secrets found

Stop scanning the repo when a defined number of secrets are found.

$ vault-radar scan repo -u <REPO URL> -l <NUM OF SECRETS>

Scan and restrict the number of commits scanned

Stop scanning the repo when a defined number of commits are scanned.

$ vault-radar scan repo -u <REPO URL> --commit-limit <NUM OF COMMITS>