GitLeaks detects secrets and sensitive information across repositories, commit history, branches, tags, and CI pipelines. It uses high-accuracy regex rules, entropy checks, and policy-based scanning to prevent credential leaks. GitLeaks is fast, lightweight, ideal for automation, and widely used for secure DevSecOps workflows.
Why GitLeaks Matters
Secrets often leak through accidental commits, debug files, test code, refactoring leftovers, and old branches. Even if removed later, these secrets remain in git history. GitLeaks detects:
• API keys
• Tokens
• Private keys
• Passwords
• OAuth secrets
• Cloud credentials
• Database URLs
• JWTs
• Certificates
• Environment variables
GitLeaks prevents compromised accounts, privilege escalation, supply-chain attacks, and repository takeovers caused by leaked credentials.
How GitLeaks Works
Regex Detection
Matches known secret formats such as AWS keys, GitHub tokens, Stripe secrets, etc.
Entropy Detection
Flags random-looking high-entropy strings.
Git History Scanning
Scans all commits, branches, and tags.
Differential Scanning
Scans only new changes (PRs), allowing fast CI feedback.
Policy-Based Detection
Uses configuration files to enforce custom rules and exclusions.
Audit Mode
Produces detailed reports for compliance and governance.
GitLeaks provides precise, high-speed scanning suitable for both local and CI environments.
Installation
Download Binary (Recommended)
Get GitLeaks from GitHub releases:
curl -sSL https://github.com/gitleaks/gitleaks/releases/latest/download/gitleaks-linux-amd64 -o gitleaks
chmod +x gitleaks
Docker Image
docker run --rm -v $(pwd):/repo zricethezav/gitleaks:latest detect -s /repo
Homebrew (macOS)
brew install gitleaks
Basic Usage
Scan repository:
gitleaks detect
Scan a specific path:
gitleaks detect -s .
Scan a remote repo:
gitleaks detect -r https://github.com/user/repo.git
Generate JSON report:
gitleaks detect -s . -f json -o report.json
Audit mode for detailed scanning:
gitleaks detect --verbose --redact
Exit code 0 means clean; non-zero indicates secrets found.
What GitLeaks Detects
Cloud Provider Keys
• AWS Access Keys
• GCP Keys
• Azure Keys
• DigitalOcean Tokens
DevOps & CI Tokens
• GitHub PATs
• GitLab Tokens
• CircleCI Tokens
• TravisCI Keys
Application Secrets
• JWTs
• API keys
• DB credentials
• OAuth client secrets
• SMTP passwords
Cryptographic Material
• RSA PRIVATE KEY
• EC PRIVATE KEY
• TLS keys
• Certificates
File-Based Leaks
• .env files
• config.json
• credentials.txt
• debug logs
Commit History Leaks
Secrets added and removed later still get detected.
GitLeaks enforces clean repositories across time.
GitLeaks Configuration
GitLeaks uses a configuration file named:
.gitleaks.toml
This file defines:
• Allowed patterns
• Custom rules
• Exclusion patterns
• Redaction settings
• Commit ignore lists
Example minimal config:
title = "My Security Policy"
[extend]
useDefaultRules = true
Add custom rule:
[[rules]]
id = "MyCustomAPIKey"
regex = '''mycompany_[0-9a-fA-F]{32}'''
secretGroup = 1
Exclude files:
[[allowlist.files]]
regex = '''testdata/'''
Exclude specific commits:
[[allowlist.commit]]
id = "abc123"
GitLeaks Modes
detect
Runs full detection based on rules and entropy.
protect
Runs continuous scanning on staged changes.
Protect mode blocks insecure commits:
gitleaks protect --staged
Add as pre-commit hook.
audit
Produces rich reports with metadata, severity, context, and commit details.
Best Practices
• Scan full history before onboarding a repo
• Add GitLeaks to pre-commit hooks
• Run GitLeaks in CI pipelines
• Redact results in logs
• Use suppression lists for false positives
• Rotate all found secrets immediately
• Scan all branches, not just main
• Include GitLeaks in release pipelines
• Maintain custom rules for enterprise-specific patterns
GitLeaks should be part of every secure development workflow.
Full-Length Practical Section
Below are deep, hands-on practicals to master GitLeaks across real-world use cases.
Practical 1: Install GitLeaks and Run a Basic Scan
gitleaks detect -s .
Check results for:
• AWS keys
• JWTs
• DB URLs
Fix leaks immediately.
Practical 2: Scan Full Git History
gitleaks detect -s . --no-gitignore
Review secrets found in historic commits.
Practical 3: Scan Remote Repository
gitleaks detect -r https://github.com/some/project.git
Use for third-party audits.
Practical 4: Generate JSON Report
gitleaks detect -s . -f json -o gitleaks-report.json
Use for dashboards and compliance.
Practical 5: Enable Protect Mode for Pre-Commit
Add hook:
gitleaks protect --staged
Add to .git/hooks/pre-commit:
#!/bin/sh
gitleaks protect --staged --redact || exit 1
Attempt to commit a secret to test.
Practical 6: Custom Rule Creation
Add rule to .gitleaks.toml:
[[rules]]
id = "InternalDBKey"
regex = '''db_[0-9a-fA-F]{24}'''
secretGroup = 0
Rerun scan to detect custom secrets.
Practical 7: Exclude False Positives
Create allowlist entry:
[[allowlist.files]]
regex = '''tests/mock_data'''
Re-scan and confirm exclusion.
Practical 8: Scan Docker Image Layers
Extract image:
docker save myimage | tar -xf -
Scan:
gitleaks detect -s .
Check for secrets in environment layers.
Practical 9: GitHub Actions Integration
Create:
.github/workflows/gitleaks.yml
Add:
- name: GitLeaks Scan
uses: gitleaks/gitleaks-action@v2
with:
args: detect -s . --redact
Push commit and review results.
Practical 10: GitLab CI Integration
secret_scan:
script:
- gitleaks detect -s . --redact
artifacts:
paths:
- gitleaks-report.json
Pipeline fails when secrets discovered.
Practical 11: Audit Mode for Compliance
gitleaks detect -s . --verbose --redact
Review:
• commit hash
• author
• timestamp
• file path
Use for forensic investigations.
Practical 12: Scan All Branches
gitleaks detect -s . --branch="*"
Secrets often hide in feature branches.
Practical 13: Detect Encoded Secrets
GitLeaks flags:
• Base64 encoded creds
• Hex encoded secrets
• JWT-like patterns
Decode manually to verify.
Practical 14: Rotate Exposed Secrets
Rotate:
• AWS IAM keys
• GitHub PATs
• Slack tokens
• DB URLs
• Encryption keys
Document rotation workflow.
Practical 15: Secure GitLeaks Output in CI
Use:
--redact
Ensure secrets do not appear in logs.
Practical 16: Create Enterprise-Wide Policy
Central .gitleaks.toml defines:
• custom rules
• exclusions
• commit block lists
• severity thresholds
Apply to all repositories.
Practical 17: Run GitLeaks on Monorepos
gitleaks detect --all-projects
This scans nested dependency folders.
Practical 18: Automated Scheduled Scans
Use GitHub scheduled workflows:
on:
schedule:
- cron: "0 2 * * *"
Daily scans reduce exposure window.
Practical 19: Produce Team Training Material
Export top recurring issues.
Write secure coding guidelines based on findings.
Practical 20: Build Full GitLeaks Security Architecture
Include:
• pre-commit scanning
• CI scanning
• scheduled scanning
• Docker scanning
• custom policies
• dashboards
• key rotation workflows
• enterprise governance
This architecture secures source-code secrets end-to-end.
Intel Dump
• GitLeaks detects secrets via regex, entropy, and commit history scanning
• Supports filesystem, git history, remote repos, Docker layers, differential scans, and CI integrations
• Configurable via .gitleaks.toml for rules, exclusions, and policies
• Protect mode blocks insecure commits
• Practicals include local scans, Docker scans, CI integration, custom rules, encoded secret detection, suppression, enterprise policies, and full secrets governance architecture