Pre-commit hooks

16 min

Using pre-commit hooks

Pre-commit hooks are a useful way to prevent secrets in code from being pushed from a git repository. Preventing them from being leaked in the first place is always the best approach. If you run your own git server, consider the pre-receive hook option which can block commits with secrets from being accepted.

This guide covers how to set up TruffleHog as a pre-commit hook using two popular frameworks:

Git's hooksPath feature - A built-in Git feature for managing hooks globally

Using Pre-commit framework - A language-agnostic framework for managing pre-commit hooks

Using Husky - A Git hooks manager for JavaScript/Node.js projects

Prerequisites

All of the methods require TruffleHog to be installed.

Install TruffleHog:

# Using Homebrew (macOS)
brew install trufflehog

# Using installation script for Linux, macOS, and Windows (and WSL)
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin

Global setup using Git's hooksPath feature

This approach uses Git's core.hooksPath to apply hooks to all repositories without requiring any per-repository setup:

Create a global hooks directory:

mkdir -p ~/.git-hooks

Create a pre-commit hook file:

touch ~/.git-hooks/pre-commit
chmod +x ~/.git-hooks/pre-commit

Add the following content to ~/.git-hooks/pre-commit:

#!/bin/sh

docker run --rm -v "$(pwd):/workdir" -i --rm trufflesecurity/trufflehog:latest git file:///workdir --since-commit HEAD --results=verified,unknown --fail

Configure Git to use this hooks directory globally:

git config --global core.hooksPath ~/.git-hooks

Now all your repositories will automatically use this pre-commit hook without any additional setup.

Using the Pre-commit Framework

The pre-commit framework is a powerful, language-agnostic tool for managing Git hooks.

Installation of Pre-commit

Install the pre-commit framework:

# Using pip (Python)
pip install pre-commit

# Using Homebrew (macOS)
brew install pre-commit

# Using conda
conda install -c conda-forge pre-commit

Repository-Specific Setup

To set up TruffleHog as a pre-commit hook for a specific repository:

Create a .pre-commit-config.yaml file in the root of your repository:

repos:
  - repo: local
    hooks:
      - id: trufflehog
        name: TruffleHog
        description: Detect secrets in your data.
        entry: bash -c 'trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail'
        language: system
        stages: ["commit", "push"]

Install the pre-commit hook:

pre-commit install

Using Husky

Husky is a popular tool for managing Git hooks in JavaScript/Node.js projects.

Installation of Husky

Install Husky in your project:

# npm
npm install husky --save-dev

# yarn
yarn add husky --dev

Enable Git hooks:

# npm
npx husky init

Setting Up TruffleHog with Husky

Add the following content to .husky/pre-commit:

echo 'docker run --rm -v "$(pwd):/workdir" -i --rm trufflesecurity/trufflehog:latest git file:///workdir --since-commit HEAD --results=verified,unknown --fail' > .husky/pre-commit

Best Practices

Commit Process

For optimal hook efficacy:

Execute git add followed by git commit separately. This ensures TruffleHog analyzes all intended changes.

Avoid using git commit -am, as it might bypass pre-commit hook execution for unstaged modifications.

Skipping Hooks

In rare cases, you may need to bypass pre-commit hooks:

git commit --no-verify -m "Your commit message"

Troubleshooting

Hook Not Running

If your pre-commit hook isn't running:

Ensure the hook is executable:

chmod +x .git/hooks/pre-commit

Check if hooks are enabled:

git config --get core.hooksPath

False Positives

If you're getting false positives:

Use the --results=verified flag to only show verified secrets

Add trufflehog:ignore comments on lines with known false positives or risk-accepted findings

Conclusion

By integrating TruffleHog into your pre-commit workflow, you can prevent credential leaks before they happen. Choose the setup method that best fits your project's needs and development workflow.

For more information on TruffleHog's capabilities, refer to the main documentation.