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

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:

  [[rules]]
  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 = [
      "akia","asia","abia","acca",
  ]

Custom Rules: Users can define custom rules to detect specific types of secrets relevant to their projects.

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.
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).

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
  Email:       john@users.noreply.github.com
  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 
PATH=$PATH:$GOROOT/bin/:$GOPATH/bin

To install the latest version of the gitleaks:

Compile the source code:

 # From Source
 git clone https://github.com/gitleaks/gitleaks.git
 cd gitleaks
 make build

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

Now move the gitleaks executable into your /usr/local/bin/ :
```
 sudo mv gitleaks /usr/local/bin/
```
To verify the installation run:
```
 gitleaks version
```

Basic Usage

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.

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

To save finding into report JSON (default) file:

 gitleaks detect --report-path gitleaks-report.json

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

To use gitleaks as pre-commit hook, first install pre-commit tool:
```
 pip install pre-commit
```

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: https://github.com/zricethezav/gitleaks
   rev: v8.18.3
   hooks:
     - id: gitleaks

To install the hook run:
```
 pre-commit install
```
Optional. To update the gitleaks version used in the hook configuration to the latest:
```
 pre-commit autoupdate
```
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"

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

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

For more information, see also Configuration section of gitleaks