Gitleaks is a SAST tool for detecting and preventing hardcoded secrets like passwords, API keys, and tokens in git repos. Gitleaks is an easy-to-use, all-in-one solution for detecting secrets, past or present, in your code.

Getting Started

Gitleaks can be installed using Homebrew, Docker, or Go. Gitleaks is also available in binary form for many popular platforms and OS types on the releases page. In addition, Gitleaks can be implemented as a pre-commit hook directly in your repo or as a GitHub action using Gitleaks-Action.

Installing

GitHub Action

Check out the official Gitleaks GitHub Action

Pre-Commit

Install pre-commit from https://pre-commit.com/#install
Create a .pre-commit-config.yaml file at the root of your repository with the following content:

for a native execution of GitLeaks or use the gitleaks-docker pre-commit ID for executing GitLeaks using the official Docker images
Auto-update the config to the latest repos' versions by executing pre-commit autoupdate
Install with pre-commit install
Now you're all set!

Note: to disable the gitleaks pre-commit hook you can prepend SKIP=gitleaks to the commit command
and it will skip running gitleaks

Usage

Commands

⚠️ v8.19.0 introduced a change that deprecated detect and protect. Those commands are still available but
are hidden in the --help menu. Take a look at this gist for easy command translations.
If you find v8.19.0 broke an existing command (detect/protect), please open an issue.

There are three scanning modes: git, dir, and stdin.

Git

The git command lets you scan local git repos. Under the hood, gitleaks uses the git log -p command to scan patches.
You can configure the behavior of git log -p with the log-opts option.
For example, if you wanted to run gitleaks on a range of commits you could use the following
command: gitleaks git -v --log-opts="--all commitA..commitB" path_to_repo. See the git log documentation for more information.
If there is no target specified as a positional argument, then gitleaks will attempt to scan the current working directory as a git repo.

Dir

The dir (aliases include files, directory) command lets you scan directories and files. Example: gitleaks dir -v path_to_directory_or_file.
If there is no target specified as a positional argument, then gitleaks will scan the current working directory.

Stdin

You can also stream data to gitleaks with the stdin command. Example: cat some_file | gitleaks -v stdin

Creating a baseline

When scanning large repositories or repositories with a long history, it can be convenient to use a baseline. When using a baseline,
gitleaks will ignore any old findings that are present in the baseline. A baseline can be any gitleaks report. To create a gitleaks report, run gitleaks with the --report-path parameter.

Once as baseline is created it can be applied when running the detect command again:

After running the detect command with the --baseline-path parameter, report output (findings.json) will only contain new issues.

Pre-Commit hook

You can run Gitleaks as a pre-commit hook by copying the example pre-commit.py script into
your .git/hooks/ directory.

Configuration

Gitleaks offers a configuration format you can follow to write your own secret detection rules:

Refer to the default gitleaks config for examples or follow the contributing guidelines if you would like to contribute to the default configuration. Additionally, you can check out this gitleaks blog post which covers advanced configuration setups.

Additional Configuration

gitleaks:allow

If you are knowingly committing a test secret that gitleaks will catch you can add a gitleaks:allow comment to that line which will instruct gitleaks
to ignore that secret. Ex:

.gitleaksignore

You can ignore specific findings by creating a .gitleaksignore file at the root of your repo. In release v8.10.0 Gitleaks added a Fingerprint value to the Gitleaks report. Each leak, or finding, has a Fingerprint that uniquely identifies a secret. Add this fingerprint to the .gitleaksignore file to ignore that specific secret. See Gitleaks' .gitleaksignore for an example. Note: this feature is experimental and is subject to change in the future.

Decoding

Sometimes secrets are encoded in a way that can make them difficult to find
with just regex. Now you can tell gitleaks to automatically find and decode
encoded text. The flag --max-decode-depth enables this feature (the default
value "0" means the feature is disabled by default).

Recursive decoding is supported since decoded text can also contain encoded
text. The flag --max-decode-depth sets the recursion limit. Recursion stops
when there are no new segments of encoded text to decode, so setting a really
high max depth doesn't mean it will make that many passes. It will only make as
many as it needs to decode the text. Overall, decoding only minimally increases
scan times.

The findings for encoded text differ from normal findings in the following
ways:

The location points the bounds of the encoded text
- If the rule matches outside the encoded text, the bounds are adjusted to
  include that as well
The match and secret contain the decoded value
Two tags are added decoded: and decode-depth:

Currently supported encodings: