scan git pre-receive

The scan git pre-receive command is used to enable scanning content in a Git pre-receive hook.

Pre-receive hooks are only available in some Git hosting services. Please check with your Git hosting service to see if pre-receive hooks are supported. For example, GitHub Cloud does not support pre-receive hooks, but the self-hosted version of GitHub, GitHub Enterprise, does support pre-receive hooks.

Because pre-receive hooks are run on the server side, they can be used to enforce policies centrally. For example, you can use a pre-receive hook to enforce that all code changes are scanned for secrets before they are accepted into the repository.

Most implementations of pre-receive hooks have a timeout to ensure the hook's execution does not block the Git operation for too long. If the hook takes too long to execute, the operation will be aborted and likely result in the commit being rejected by the server. The scan git pre-receive command is designed to require a user to configure the exact set of risks they want to scan. The recommendation is to limit the set of risks to a small number of patterns you know are relevant to your use cases. By default, the scan will not check whether a secret is active or not. This is to ensure that the scan does not take too long to execute because most activeness checks require making a network call, which can add a lot of time to the overall evaluation.

For larger scans, consider using a pre-commit hook instead with the vault-radar CLI.

Prerequisites

The scan git pre-receive command requires a valid license. Please reach out to your customer support contact for help generating a license.

The license can be saved:

As the environment variable VAULT_RADAR_LICENSE
In a file defined by VAULT_RADAR_LICENSE_PATH
In a file at the default path $HOME/.hashicorp/vault-radar/vault-radar.hclic

Additionally, vault-radar must be installed on the server where the Git repository is hosted. Installation instructions can be found here.

Configuration

The scan git pre-receive command is configured using a configuration file. By default Vault Radar will look for the file at $HOME/.hashicorp/vault-radar/config.json. This can be overridden by setting the VAULT_RADAR_CONFIG_PATH environment variable to the path of the configuration file.

An example of the configuration file contents is shown below using the default values:

{
  "pre_receive_skip_activeness": true,
  "pre_receive_fail_severity":"medium",
  "pre_receive_risk_allowlist": []
}

Note

The command requires pre_receive_risk_allowlist to be set to a non-empty list of risk types to scan. The example shown would exit with a non-zero status code as a result.

The values for the pre_receive_risk_allowlist option can either be a risk type or risk description. For example:

{
    "pre_receive_risk_allowlist": [
        "jwt_token",
        "GitHub personal access token"
    ]
}

Review the Vault Radar secret types documentation for a list of the supported types and descriptions that can be used in the configuration.

Configuration options

pre_receive_skip_activeness: true results in skipping activeness checks. The default is true. Enabling activeness checks will likely add more time to the evaluation, set to false with caution.
pre_receive_fail_severity: Specifies the minimum severity of the risk that will cause the scan to fail. The default is medium. Additional documentation about severity can be found here.
pre_receive_risk_allowlist: Specifies the list of risk types or descriptions to scan. The scan will only scan for risks in this list. The command will exit with a non-zero status code if the list is empty.

Usage

The command is expected to be called from a pre-receive hook.

$ vault-radar scan git pre-receive

Testing locally

Since the pre-receive hook is typically run on the central Git server, it's often critical to have confidence that the change will work without disrupting others working on projects. Fortunately, it's possible to test the pre-receive hook locally on a repo.

This can be done on an existing repo or by creating a new bare repo. In our example we will create a repo within a directory called pre-receieve-test.

Make a directory to test in.

$ mkdir pre-receieve-test && cd pre-receieve-test

Create a new bare repo:
```
$ git init --bare repo.git
```
Create a ~/hashicorp/vault-radar/config.json if you do not have one. In the example we use a simple configuration that checks just for JWT tokens:
```
{
    "pre_receive_risk_allowlist": [ "jwt_token" ]   
}
```
Set the pre-receive hook for the project and make it invoke the vault-radar scan pre-receive command:
```
$ echo "exec vault-radar scan git pre-receive" > repo.git/hooks/pre-receive
$ chmod +x repo.git/hooks/pre-receive
```
Note
In the example we are assuming vault-radar is in the PATH. If it's not, you can specify the full path to the vault-radar binary.
Then clone the repo:
```
$ git clone repo.git repo
```

From the clone, create a new file and commit it. In the example we create a file called jwt.txt with a JWT token from jwt.io:

$ cd repo
$ echo 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' >> jwt.txt
$ git add jwt.txt
$ git commit -m "Add jwt token"

And then finnally push the changes back to the origin repo:
```
$ git push origin main
```

If things are configured correctly there should be output from vault-radar indicating the commit was reject because of the JWT token.

git push origin main
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Delta compression using up to 12 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 380 bytes | 380.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
remote: error: HC001: Repository rule violations found
remote:
remote: - Hashicorp Vault Radar PUSH PROTECTION
remote:  —————————————————————————————————————————
remote:    Resolve the following violations before pushing again
remote:
remote:    - Push cannot contain secrets
remote:
remote:      (?) Learn how to resolve a blocked push
remote:      https://developer.hashicorp.com/hcp/docs/vault-radar/cli/scan/git/pre-receive
remote:
remote:
remote:     —— Generic JWT token ———————————————————————————————————————————
remote:        - ref:      refs/heads/main
remote:          commit:   94b08e4f24065b5c435199d363932d42014f247d
remote:          path:     jwt.txt:1
remote:          severity: medium
remote:
remote:
remote:
To /Users/someone/pre-receive-test/repo.git
 ! [remote rejected] main -> main (pre-receive hook declined)
error: failed to push some refs to '/Users/someone/pre-receive-test/repo.git'

The exact configuration of a pre-receive hook on a Git server is unique to the provider. Please refer to the documentation for your specific Git server for more information on how to configure a pre-receive hook.