Bitbucket Pre-Hook Configuration

Overview

This page contains all the information needed to install and configure the Bitbucket pre-hook. This is needed to allow GuardRails to scan Git commits for vulnerabilities before they are accepted and included in the remote Git repository.

Note: The pre-hook will only do a light scan, which will look for passwords and secrets in the commit. It will also run the custom rules defined for the General Engine.

IMPORTANT: The way you access the GuardRails API depends on your deployment type, e.g SWARM (deprecated), or Kubernetes (NodePort, or Ingress). These are the options:

• SWARM: <YOUR_HOST> will be the configured DNS (i.e.: guardrails.your-company.com) of your GuardRails instance. On SWARM GuardRails exposes the API on port 1444.
• Kubernetes - Nodeports: <YOUR_HOST> will be the configured DNS (i.e.: guardrails.your-company.com) of your GuardRails instance. On Kubeneretes, with NodePorts GuardRails exposes the API on port 31444 by default, but this can be changed to an arbitrary port number.
• Kubernetes - Ingress: The <YOUR_HOST> is different for every service, e.g the API may run on the configured DNS (i.e.: guardrails-api.your-company.com) of your GuardRails instance. There is no default value for this, and it is a required part of the initial configuration. On Kubeneretes, with Ingress GuardRails exposes the API either on port 80 or 443 based on your SSL settings.

The best way to verify that you have the correct API URL is to access http(s)://<YOUR_HOST>:<API_PORT>/swagger in the browser and see whether the swagger API docs are showing.

Install the Bitbucket pre-hook application

The GuardRails Pre-Receive Hook Plugin can be installed from the marketplace and follow the on screen instructions.

Configure the Bitbucket pre-hook application

1. Navigate to the repository settings for the repository that you want to enable the GuardRails pre-hook for in the Bitbucket UI.
2. Click on hooks in the sidebar.
3. Under Pre receive click on the dropdown next to GuardRails.
4. Click on Enabled.
5. In the popup fill in the following - GuardRails API URL: http(s)://<YOUR_HOST>:<API_PORT> - GuardRails CLI Token: (Enter the GuardRails CLI token for this organization. This can be found in the organization settings in the GuardRails dashboard) - Scan Timeout: (Leave as it is) - Trust all certificates: (If you use a self signed certificate then check this box, otherwise leave it unchecked) - Debug Mode: (Leave it unchecked)
6. Click on Enable

The pre-hook is now enabled and will scan all new commits that is pushed to the repository for vulnerabilities.

Test the pre-hook

To test if the pre-hook is working, clone the repository and make a new commit and push it to the remote repository. If the commit doesn't contain any vulnerabilities the Git push will finish successfully and a message will be displayed in the terminal that the scan was finished with no vulnerabilities found.

If one or more vulnerability is found then the commit the Git push command will fail and a message will be displayed in the terminal (see screenshot below).

Supported Bitbucket server versions

This plugins has been tested with Bitbucket server version 5.14.0 to 7.9.1. Any version of Bitbucket server lower than 5.14.0 is not supported.