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.
Gitleaks is a Static Application Security Testing (SAST) tool designed to detect and prevent hardcoded secrets like passwords, API keys, and tokens in Git repositories. It provides an easy-to-use, all-in-one solution for identifying sensitive information, whether present or historical, within your codebase.
Key Features:
Detects past and present secrets in Git repositories.
Works across multiple platforms and integrates seamlessly into CI/CD pipelines.
Supports scanning via Git history, directories, or standard input.
Customizable configurations to extend default rules or create new ones.
Generates reports in various formats, including JSON, CSV, JUnit, SARIF, and templates.
Can be installed using winget for easy setup.
Audience & Benefit:
Ideal for developers, DevOps teams, and security professionals looking to enhance code security. By identifying secrets early in the development cycle, Gitleaks helps prevent potential data breaches and ensures compliance with security best practices.
README
Gitleaks
┌─○───┐
│ │╲ │
│ │ ○ │
│ ○ ░ │
└─░───┘
Join our Discord!
Gitleaks is a tool for detecting secrets like passwords, API keys, and tokens in git repos, files, and whatever else you wanna throw at it via stdin. If you wanna learn more about how the detection engine works check out this blog: Regex is (almost) all you need.
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.
Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.
Git for Windows focuses on offering a lightweight, native set of tools that bring the full feature set of the Git SCM to Windows while providing appropriate user interfaces for experienced Git users and novices alike.
GitHub CLI (gh) is a command-line tool that brings pull requests, issues, GitHub Actions, and other GitHub features to your terminal, so you can do all your work in one place.
This is microsoft/git, a special Git distribution to support monorepo scenarios. If you are not working in a monorepo, you are likely searching for Git for Windows instead of this codebase.
In addition to the Git command-line interface (CLI), microsoft/git includes the Scalar CLI to further enable working with extremely large repositories. Scalar is a tool to apply the latest recommendations and use the most advanced Git features.
Sourcetree simplifies how you interact with your Git repositories so you can focus on coding. Visualize and manage your repositories through Sourcetree's simple Git GUI.
TortoiseSVN is a really easy to use Revision control/version control/source control software for Windows. It is based on Apache™ Subversion (SVN)®; TortoiseSVN provides a nice and easy user interface for Subversion.
Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.
Git for Windows focuses on offering a lightweight, native set of tools that bring the full feature set of the Git SCM to Windows while providing appropriate user interfaces for experienced Git users and novices alike.
GitHub CLI (gh) is a command-line tool that brings pull requests, issues, GitHub Actions, and other GitHub features to your terminal, so you can do all your work in one place.
This is microsoft/git, a special Git distribution to support monorepo scenarios. If you are not working in a monorepo, you are likely searching for Git for Windows instead of this codebase.
In addition to the Git command-line interface (CLI), microsoft/git includes the Scalar CLI to further enable working with extremely large repositories. Scalar is a tool to apply the latest recommendations and use the most advanced Git features.
Sourcetree simplifies how you interact with your Git repositories so you can focus on coding. Visualize and manage your repositories through Sourcetree's simple Git GUI.
TortoiseSVN is a really easy to use Revision control/version control/source control software for Windows. It is based on Apache™ Subversion (SVN)®; TortoiseSVN provides a nice and easy user interface for Subversion.
Usage:
gitleaks [command]
Available Commands:
dir scan directories or files for secrets
git scan git repositories for secrets
help Help about any command
stdin detect secrets from stdin
version display gitleaks version
Flags:
-b, --baseline-path string path to baseline with issues that can be ignored
-c, --config string config file path
order of precedence:
1. --config/-c
2. env var GITLEAKS_CONFIG
3. env var GITLEAKS_CONFIG_TOML with the file content
4. (target path)/.gitleaks.toml
If none of the four options are used, then gitleaks will use the default config
--diagnostics string enable diagnostics (comma-separated list: cpu,mem,trace). cpu=CPU profiling, mem=memory profiling, trace=execution tracing
--diagnostics-dir string directory to store diagnostics output files (defaults to current directory)
--enable-rule strings only enable specific rules by id
--exit-code int exit code when leaks have been encountered (default 1)
-i, --gitleaks-ignore-path string path to .gitleaksignore file or folder containing one (default ".")
-h, --help help for gitleaks
--ignore-gitleaks-allow ignore gitleaks:allow comments
-l, --log-level string log level (trace, debug, info, warn, error, fatal) (default "info")
--max-decode-depth int allow recursive decoding up to this depth (default "0", no decoding is done)
--max-archive-depth int allow scanning into nested archives up to this depth (default "0", no archive traversal is done)
--max-target-megabytes int files larger than this will be skipped
--no-banner suppress banner
--no-color turn off color for verbose output
--redact uint[=100] redact secrets from logs and stdout. To redact only parts of the secret just apply a percent value from 0..100. For example --redact=20 (default 100%)
-f, --report-format string output format (json, csv, junit, sarif, template)
-r, --report-path string report file
--report-template string template file used to generate the report (implies --report-format=template)
-v, --verbose show verbose output from scan
--version version for gitleaks
Use "gitleaks [command] --help" for more information about a command.
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.
gitleaks git --report-path gitleaks-report.json # This will save the report in a file called gitleaks-report.json
Once as baseline is created it can be applied when running the detect command again:
If none of the four options are used, then gitleaks will use the default config.
Configuration
Gitleaks offers a configuration format you can follow to write your own secret detection rules:
# Title for the gitleaks configuration file.
title = "Custom Gitleaks configuration"
# You have basically two options for your custom configuration:
#
# 1. define your own configuration, default rules do not apply
#
# use e.g., the default configuration as starting point:
# https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml
#
# 2. extend a configuration, the rules are overwritten or extended
#
# When you extend a configuration the extended rules take precedence over the
# default rules. I.e., if there are duplicate rules in both the extended
# configuration and the default configuration the extended rules or
# attributes of them will override the default rules.
# Another thing to know with extending configurations is you can chain
# together multiple configuration files to a depth of 2. Allowlist arrays are
# appended and can contain duplicates.
# useDefault and path can NOT be used at the same time. Choose one.
[extend]
# useDefault will extend the default gitleaks config built in to the binary
# the latest version is located at:
# https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml
useDefault = true
# or you can provide a path to a configuration to extend from.
# The path is relative to where gitleaks was invoked,
# not the location of the base config.
# path = "common_config.toml"
# If there are any rules you don't want to inherit, they can be specified here.
disabledRules = [ "generic-api-key"]
# 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 = "awesome 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'''
# Int used to extract secret from regex match and used as the group that will have
# its entropy checked if `entropy` is set.
secretGroup = 3
# Float representing the minimum shannon entropy a regex group must have to be considered a secret.
entropy = 3.5
# 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'''
# Keywords are used for pre-regex check filtering. Rules that contain
# keywords will perform a quick string compare check to make sure the
# keyword(s) are in the content being scanned. Ideally these values should
# either be part of the identiifer or unique strings specific to the rule's regex
# (introduced in v8.6.0)
keywords = [
"auth",
"password",
"token",
]
# Array of strings used for metadata and reporting purposes.
tags = ["tag","another tag"]
# ⚠️ In v8.21.0 `[rules.allowlist]` was replaced with `[[rules.allowlists]]`.
# This change was backwards-compatible: instances of `[rules.allowlist]` still work.
#
# You can define multiple allowlists for a rule to reduce false positives.
# A finding will be ignored if _ANY_ `[[rules.allowlists]]` matches.
[[rules.allowlists]]
description = "ignore commit A"
# When multiple criteria are defined the default condition is "OR".
# e.g., this can match on |commits| OR |paths| OR |stopwords|.
condition = "OR"
commits = [ "commit-A", "commit-B"]
paths = [
'''go\.mod''',
'''go\.sum'''
]
# note: stopwords targets the extracted secret, not the entire regex match
# like 'regexes' does. (stopwords introduced in 8.8.0)
stopwords = [
'''client''',
'''endpoint''',
]
[[rules.allowlists]]
# The "AND" condition can be used to make sure all criteria match.
# e.g., this matches if |regexes| AND |paths| are satisfied.
condition = "AND"
# note: |regexes| defaults to check the _Secret_ in the finding.
# Acceptable values for |regexTarget| are "secret" (default), "match", and "line".
regexTarget = "match"
regexes = [ '''(?i)parseur[il]''' ]
paths = [ '''package-lock\.json''' ]
# You can extend a particular rule from the default config. e.g., gitlab-pat
# if you have defined a custom token prefix on your GitLab instance
[[rules]]
id = "gitlab-pat"
# all the other attributes from the default rule are inherited
[[rules.allowlists]]
regexTarget = "line"
regexes = [ '''MY-glpat-''' ]
# ⚠️ In v8.25.0 `[allowlist]` was replaced with `[[allowlists]]`.
#
# Global allowlists have a higher order of precedence 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.
[[allowlists]]
description = "global allow list"
commits = [ "commit-A", "commit-B", "commit-C"]
paths = [
'''gitleaks\.toml''',
'''(.*?)(jpg|gif|doc)'''
]
# note: (global) regexTarget defaults to check the _Secret_ in the finding.
# Acceptable values for regexTarget are "match" and "line"
regexTarget = "match"
regexes = [
'''219-09-9999''',
'''078-05-1120''',
'''(9[0-9]{2}|666)-\d{2}-\d{4}''',
]
# note: stopwords targets the extracted secret, not the entire regex match
# like 'regexes' does. (stopwords introduced in 8.8.0)
stopwords = [
'''client''',
'''endpoint''',
]
# ⚠️ In v8.25.0, `[[allowlists]]` have a new field called |targetRules|.
#
# Common allowlists can be defined once and assigned to multiple rules using |targetRules|.
# This will only run on the specified rules, not globally.
[[allowlists]]
targetRules = ["awesome-rule-1", "awesome-rule-2"]
description = "Our test assets trigger false-positives in a couple rules."
paths = ['''tests/expected/._\.json$''']
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
Composite Rules (Multi-part or required Rules)
In v8.28.0 Gitleaks introduced composite rules, which are made up of a single "primary" rule and one or more auxiliary or required rules. To create a composite rule, add a [[rules.required]] table to the primary rule specifying an id and optionally withinLines and/or withinColumns proximity constraints. A fragment is a chunk of content that Gitleaks processes at once (typically a file, part of a file, or git diff), and proximity matching instructs the primary rule to only report a finding if the auxiliary required rules also find matches within the specified area of the fragment.
Proximity matching: Using the withinLines and withinColumns fields instructs the primary rule to only report a finding if the auxiliary required rules also find matches within the specified proximity. You can set:
withinLines: N - required findings must be within N lines (vertically)
withinColumns: N - required findings must be within N characters (horizontally)
Both - creates a rectangular search area (both constraints must be satisfied)
Neither - fragment-level matching (required findings can be anywhere in the same fragment)
Here are diagrams illustrating each proximity behavior:
Some final quick thoughts on composite rules.This is an experimental feature! It's subject to change so don't go sellin' a new B2B SaaS feature built ontop of this feature. Scan type (git vs dir) based context is interesting. I'm monitoring the situation. Composite rules might not be super useful for git scans because gitleaks only looks at additions in the git history. It could be useful to scan non-additions in git history for required rules. Oh, right this is a readme, I'll shut up now.
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:
class CustomClass:
discord_client_secret = '8dyfuiRyq=vVc3RRr_edRk-fK__JItpZ' #gitleaks:allow
.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:
percent - Any printable ASCII percent encoded values
Sometimes secrets are packaged within archive files like zip files or tarballs,
making them difficult to discover. Now you can tell gitleaks to automatically
extract and scan the contents of archives. The flag --max-archive-depth
enables this feature for both dir and git scan types. The default value of
"0" means this feature is disabled by default.
Recursive scanning is supported since archives can also contain other archives.
The --max-archive-depth flag sets the recursion limit. Recursion stops when
there are no new archives to extract, so setting a very high max depth just
sets the potential to go that deep. It will only go as deep as it needs to.
The findings for secrets located within an archive will include the path to the
file inside the archive. Inner paths are separated with !.
Git Extensions is a standalone UI tool for managing git repositories. It also integrates with Windows Explorer and Microsoft Visual Studio (2015/2017/2019).
Git Extensions is a standalone UI tool for managing git repositories. It also integrates with Windows Explorer and Microsoft Visual Studio (2015/2017/2019).
dev-sidecar, named after service-sidecar in service-mesh, is a side car tool that assists developers by proxying HTTPS requests to some domestic acceleration channels through a local proxy.
dev-sidecar, named after service-sidecar in service-mesh, is a side car tool that assists developers by proxying HTTPS requests to some domestic acceleration channels through a local proxy.
dev-sidecar, named after service-sidecar in service-mesh, is a side car tool that assists developers by proxying HTTPS requests to some domestic acceleration channels through a local proxy.
