gitleaks
Scan Git repositories for secrets
TLDR
Scan a remote repository
Scan a local directory
Output scan results to a JSON file
Use a custom rules file
Start scanning from a specific commit
Scan uncommitted changes before a commit
Display verbose output indicating which parts were identified as leaks during the scan
SYNOPSIS
gitleaks command [options]
gitleaks detect [flags]
gitleaks protect [flags]
gitleaks version
The primary command is detect for scanning a repository and protect for integrating into pre-commit hooks.
PARAMETERS
--config path
Path to a custom Gitleaks config file (e.g., .gitleaks.toml).
--repo-path path
Path to the repository to scan. Defaults to the current directory. (Alias: --source)
--verbose
Enable verbose output.
--log-level level
Set the log level (debug, info, warn, error, fatal).
--exit-code int
Exit code if a leak is found (default is 1).
--report-path path
Path to write the report file.
--report-format format
Format of the report file (json, sarif, csv, text, noop).
--redact
Redact secrets from the log and report output.
--branch name
Only scan a specific branch.
--staged
Scan only staged files (used with detect and protect).
--uncommitted
Scan only uncommitted changes.
--threads int
Number of threads to use for scanning (default depends on CPU cores).
--commit hash
Scan a specific commit.
--commit-from hash
Scan from a specific commit hash.
--commit-to hash
Scan to a specific commit hash.
--exclude-forks
Exclude scanning forked repositories.
--max-commit-delta int
Maximum number of commits to scan back (0 for unlimited).
--install-hook
Install the Gitleaks pre-commit hook (used with protect).
--remove-hook
Remove the Gitleaks pre-commit hook (used with protect).
DESCRIPTION
gitleaks is an open-source command-line tool designed to identify and prevent the accidental exposure of sensitive information, such as passwords, API keys, tokens, and other credentials, within Git repositories. It achieves this by scanning commit history, branches, and tags for patterns that indicate the presence of secrets.
The tool uses a comprehensive set of predefined rules (regex patterns and heuristics) to detect various types of secrets. Users can also define custom rules to tailor detection to their specific needs.
gitleaks is widely used in DevSecOps practices. It can be integrated into Continuous Integration/Continuous Deployment (CI/CD) pipelines to enforce security policies and catch secrets before they are pushed to remote repositories. It can also be run as a pre-commit hook on developer machines to prevent secrets from ever entering the Git history. Its primary goal is to help organizations maintain a strong security posture by preventing sensitive data from being publicly exposed.
CAVEATS
False Positives: While gitleaks uses sophisticated rules, it can still produce false positives, requiring manual review of findings.
Performance: Scanning very large repositories with extensive commit history can be time-consuming and resource-intensive.
Rule Updates: The effectiveness of gitleaks depends on its detection rules being up-to-date. Regularly updating the tool is crucial.
Not a complete solution: It's a critical component of security, but not a substitute for proper secret management solutions (e.g., vaults) and secure coding practices.
History Rewriting: gitleaks identifies secrets, but doesn't automatically remove them from history. Removing secrets from Git history requires tools like git filter-repo or BFG Repo-Cleaner, which should be used with extreme caution.
CI/CD INTEGRATION
gitleaks is commonly integrated into CI/CD pipelines (e.g., GitHub Actions, GitLab CI, Jenkins) to automatically scan code pushes or pull requests, failing builds if secrets are detected.
PRE-COMMIT HOOKS
Developers can install gitleaks as a Git pre-commit hook to scan changes locally before they are committed, preventing secrets from entering the repository history in the first place.
CUSTOM RULES
Beyond its extensive default rules, gitleaks allows users to define custom regular expressions and configurations in a TOML file (.gitleaks.toml) to detect organization-specific patterns or sensitive data.
DOCKER SUPPORT
gitleaks can be easily run as a Docker container, providing a consistent and isolated environment for scanning without requiring local installation of dependencies.
HISTORY
gitleaks was originally created by Zach Khan and released as an open-source project. It quickly gained traction within the cybersecurity and DevOps communities due to its effectiveness and ease of integration. It has evolved over time with community contributions, enhancing its rule set, performance, and features, becoming a staple tool for proactive secret detection in Git workflows.
SEE ALSO
git(1), grep(1), trufflehog(1), detect-secrets(1)