Get started with Gitleaks tool

Photo by Jake Walker on Unsplash

Get started with Gitleaks tool

Gitleaks is an open-source SAST tool designed to detect and prevent secrets (such as API keys, passwords, and other sensitive information) from being committed to version control repositories. It scans the entire repository history, including directories and files, to identify potential secrets. By configuring it properly and integrating it into your development workflow, you can significantly reduce the risk of exposing sensitive information.

Key Features

  1. Detection:

    • Patterns and Rules: Gitleaks uses predefined patterns and rules to identify secrets. These patterns can include regular expressions for common types of secrets like AWS keys, Slack tokens, and more:

        id = "aws-access-token"
        description = "Identified a pattern that may indicate AWS credentials, risking unauthorized cloud resource access and data breaches on AWS platforms."
        regex = '''(?:A3T[A-Z0-9]|AKIA|ASIA|ABIA|ACCA)[A-Z0-9]{16}'''
        keywords = [
    • Custom Rules: Users can define custom rules to detect specific types of secrets relevant to their projects.

  2. Scanning:

    • Repository Scanning: Gitleaks can scan entire Git repositories, including commit history, directories and files.

    • Pre-commit Hook: It can be integrated as a pre-commit hook to scan changes before they are committed, preventing secrets from entering the repository.

  3. Configuration:

    • Config Files: Users can configure Gitleaks using a configuration file (gitleaks.toml) to customize the rules and behavior of the tool.

    • Ignore Files: Gitleaks can be configured to ignore specific files or directories using an ignore file (.gitleaksignore).

  4. Output:

    • Reports: Gitleaks generates detailed reports of identified secrets, including the location in the repository and the specific rule that triggered the detection.

        ~/code(master) gitleaks detect --source . -v
        Finding:     "export BUNDLE_ENTERPRISE__CONTRIBSYS__COM=cafebabe:deadbeef",
        Secret:      cafebabe:deadbeef
        RuleID:      sidekiq-secret
        Entropy:     2.609850
        File:        cmd/generate/config/rules/sidekiq.go
        Line:        23
        Commit:      cd5226711335c68be1e720b318b7bc3135a30eb2
        Author:      John
        Date:        2022-08-03T12:31:40Z
        Fingerprint: cd5226711335c68be1e720b318b7bc3135a30eb2:cmd/generate/config/rules/sidekiq.go:sidekiq-secret:23
    • Formats: Reports can be output in various formats such as JSON (default), CSV, junit, sarif or directly to the console.

Installation on Linux

Gitleaks can be installed as a binary from the GitHub releases page.

Ensure that you have the Go installed properly on your system as a prerequisite.

For Go installation you can use the following settings in ~/.bashrc:

# Golang 
export GOPATH=$HOME/go 
export GOROOT=/usr/local/go 

To install the latest version of the gitleaks:

  1. Compile the source code:

     # From Source
     git clone
     cd gitleaks
     make build

    After compiling the source code, you'll find the executable:

  2. Now move the gitleaks executable into your /usr/local/bin/ :

     sudo mv gitleaks /usr/local/bin/
  3. To verify the installation run:

     gitleaks version

Basic Usage

  1. To scan a repository's git log history, navigate to the repository directory and run:
gitleaks detect .

The detect command is used to scan repos, directories, and files.

  1. To scan files and directories while ignoring git log history use the --no-git option.

     gitleaks detect . --no-git
  2. To save finding into report JSON (default) file:

     gitleaks detect --report-path gitleaks-report.json
  3. To output current repository scan while ignoring the git log history:

     gitleaks detect . --no-git --report-format=json --report-path=gitleaks-report.json

If you need to process JSON report file for all found files with sensitive information (File field) use the following command:

jq -r '.[].File' gitleaks-report.json | sort | uniq > sensitive_files.txt

Gitleaks pre-commit

  1. To use gitleaks as pre-commit hook, first install pre-commit tool:

     pip install pre-commit
  2. Create .pre-commit-config.yaml file at the root of the project. Specify the configuration and the version of the gitleaks to use:

     # .pre-commit-config.yaml
     - repo:
       rev: v8.18.3
         - id: gitleaks
  3. To install the hook run:

     pre-commit install
  4. Optional. To update the gitleaks version used in the hook configuration to the latest:

     pre-commit autoupdate
  5. Optional. To disable the gitleaks pre-commit hook you can prepend SKIP=gitleaks to the commit command and it will skip running gitleaks:

     SKIP=gitleaks git commit -m "skip gitleaks check"

Create custom configuration of rules

Gitleaks offers a configuration format you can follow to write your own secret detection rules. Create a gitleaks.toml file to define custom rules and settings:

title = "Gitleaks Configuration"

description = "Generic API Key"
regex = '''[a-zA-Z0-9]{32}'''
tags = ["key", "api"]

# Ignoring paths
paths = ["path/to/ignore"]

For more information, see also Configuration section of gitleaks