â—‹
│╲
│ ○
â—‹ â–‘
â–‘ gitleaks
Gitleaks is a SAST tool for detecting 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.
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.
brew install gitleaksdocker pull zricethezav/gitleaks:latest
docker run -v ${path_to_host_folder_to_scan}:/path zricethezav/gitleaks:latest [COMMAND] --source="/path" [OPTIONS]docker pull ghcr.io/zricethezav/gitleaks:latest
docker run -v ${path_to_host_folder_to_scan}:/path zricethezav/gitleaks:latest [COMMAND] --source="/path" [OPTIONS]- Download and install Go from https://golang.org/dl/
- Clone the repo
git clone https://github.com/zricethezav/gitleaks.git- Build the binary
cd gitleaks
make buildUsage:
gitleaks [OPTIONS]
Application Options:
-v, --verbose Show verbose output from scan
-q, --quiet Sets log level to error and only output leaks, one json object per line
-r, --repo-url= Repository URL
-p, --path= Path to directory (repo if contains .git) or file
-c, --config-path= Path to config
--repo-config-path= Path to gitleaks config relative to repo root
--clone-path= Path to clone repo to disk
--version Version number
--username= Username for git repo
--password= Password for git repo
--access-token= Access token for git repo
--threads= Maximum number of threads gitleaks spawns
--ssh-key= Path to ssh key used for auth
--unstaged Run gitleaks on unstaged code
--branch= Branch to scan
--redact Redact secrets from log messages and leaks
--debug Log debug messages
--no-git Treat git repos as plain directories and scan those files
--leaks-exit-code= Exit code when leaks have been encountered (default: 1)
--append-repo-config Append the provided or default config with the repo config.
--additional-config= Path to an additional gitleaks config to append with an existing config. Can be used with --append-repo-config
to append up to three configurations
-o, --report= Report output path
-f, --format= json, csv, sarif (default: json)
--files-at-commit= Sha of commit to scan all files at commit
--commit= Sha of commit to scan or "latest" to scan the last commit of the repository
--commits= Comma separated list of a commits to scan
--commits-file= Path to file of line separated list of commits to scan
--commit-from= Commit to start scan from
--commit-to= Commit to stop scan
--commit-since= Scan commits more recent than a specific date. Ex: '2006-01-02' or '2006-01-02T15:04:05-0700' format.
--commit-until= Scan commits older than a specific date. Ex: '2006-01-02' or '2006-01-02T15:04:05-0700' format.
--depth= Number of commits to scan
Help Options:
-h, --help Show this help message
There are two commands you will use to detect secrets; detect and protect.
The detect command is used to scan repos, directories, and files. This comand can be used on developer machines and in CI environments.
When running detect on a git repository, gitleaks will parse the output of a git log -p command (you can see how this executed
here).
git log -p generates patches which gitleaks will use to detect secrets.
You can configure what commits git log will range over by using the --log-opts flag. --log-opts accepts any option for git log -p.
For example, if you wanted to run gitleaks on a range of commits you could use the following command: gitleaks --source . --log-opts="--all commitA..commitB".
See the git log documentation for more information.
You can scan files and directories by using the --no-git option.
The protect command is used to uncommitted changes in a git repo. This command should be used on developer machines in accordance with
shifting left on security.
When running detect on a git repository, gitleaks will parse the output of a git diff command (you can see how this executed
here). You can set the
--staged flag to check for changes in commits that have been git added. The --staged flag should be used when running Gitleaks
as a pre-commit.
NOTE: the protect command can only be used on git repos, running protect on files or directories will result in an error message.
You can verify a finding found by gitleaks using a git log command.
Example output:
{
"Description": "AWS",
"StartLine": 37,
"EndLine": 37,
"StartColumn": 19,
"EndColumn": 38,
"Context": "\t\t\"aws_secret= \\\"AKIAIMNOJVGFDXXXE4OA\\\"\": true,",
"Secret": "AKIAIMNOJVGFDXXXE4OA",
"File": "checks_test.go",
"Commit": "ec2fc9d6cb0954fb3b57201cf6133c48d8ca0d29",
"Entropy": 0,
"Author": "zricethezav",
"Email": "thisispublicanyways@gmail.com",
"Date": "2018-01-28 17:39:00 -0500 -0500",
"Message": "[update] entropy check",
"Tags": [],
"RuleID": "aws-access-token"
}
We can use the following format to verify the leak:
git log -L {StartLine,EndLine}:{File} {Commit}
So in this example it would look like:
git log -L 37,37:checks_test.go ec2fc9d6cb0954fb3b57201cf6133c48d8ca0d29
Which gives us:
commit ec2fc9d6cb0954fb3b57201cf6133c48d8ca0d29
Author: zricethezav <thisispublicanyways@gmail.com>
Date: Sun Jan 28 17:39:00 2018 -0500
[update] entropy check
diff --git a/checks_test.go b/checks_test.go
--- a/checks_test.go
+++ b/checks_test.go
@@ -28,0 +37,1 @@
+ "aws_secret= \"AKIAIMNOJVGFDXXXE4OA\"": true,
You can run Gitleaks as a pre-commit hook by copying the example pre-commit.py script into
your .git/hooks/ directory.
Gitleaks offers a configuration format you can follow to write your own secret detection rules:
# Title for the gitleaks configuration file.
title = "Gitleaks title"
# An array of tables that contain information that define instructions
# on how to detect secrets
[[rules]]
# Unique identifier for this rule
id = "awesome-rule-1"
# Short human readable description of the rule.
description = "awsome rule 1"
# Golang regular expression used to detect secrets. Note Golang's regex engine
# does not support lookaheads.
regex = '''one-go-style-regex-for-this-rule'''
# Golang regular expression used to match paths. This can be used as a standalone rule or it can be used
# in conjunction with a valid `regex` entry.
path = '''a-file-path-regex'''
# Array of strings used for metadata and reporting purposes.
tags = ["tag","another tag"]
# Int used to check shannon entropy of a specific group in a regex match.
entropyGroup = 3
# Float representing the minimum shannon entropy a regex group must have to be considered a secret.
entropy = 3.5
# You can include an allowlist table for a single rule to reduce false positives or ignore commits
# with known/rotated secrets
[rules.allowlist]
description = "ignore commit A"
commits = [ "commit-A", "commit-B"]
paths = ['''one-file-path-regex''']
regexes = ['''one-regex-within-the-already-matched-regex''']
# This is a global allowlist which has a higher order of precendence than rule-specific allowlists.
# If a commit listed in the `commits` field below is encountered then that commit will be skipped and no
# secrets will be detected for said commit. The same logic applies for regexes and paths.
[allowlist]
description = "ignore commit A"
commits = [ "commit-A", "commit-B"]
paths = ['''one-file-path-regex''']
regexes = ['''one-regex-within-the-already-matched-regex''']Refer to the default gitleaks config for examples and advice on writing regular expressions for secret detection.
You can always set the exit code when leaks are encountered with the --exit-code flag. Default exit codes below:
0 - no leaks present
1 - leaks or error encountered