# Gitleaks — Find Secrets in Git Repos and Code

> Gitleaks is a fast SAST tool for detecting hardcoded secrets like passwords, API keys, and tokens in Git repositories. It scans commit history and source code using regex patterns, preventing secret leaks before they reach production.

## Install

Save in your project root:

# Gitleaks — Find Secrets in Git Repos and Code

## Quick Use
```bash
# Install Gitleaks
brew install gitleaks
# Or: go install github.com/gitleaks/gitleaks/v8@latest

# Scan current repository (all commits)
gitleaks detect

# Scan only staged changes (pre-commit)
gitleaks protect --staged

# Scan a specific directory (no git)
gitleaks dir -s ./src

# Output as JSON
gitleaks detect --report-format json --report-path results.json
```

## Introduction
Gitleaks finds secrets that should never have been committed — AWS keys, database passwords, API tokens, private keys, and more. It scans the entire Git commit history (not just the current state), catching secrets that were committed and later "deleted" but still exist in Git history.

With over 26,000 GitHub stars, Gitleaks is the most popular open-source secret detection tool. It is used in CI/CD pipelines, pre-commit hooks, and security audits to prevent credential leaks before they cause breaches.

## What Gitleaks Does
Gitleaks uses configurable regex patterns to scan for secrets in two modes: detect (scan repository history) and protect (scan staged/uncommitted changes). It recognizes 100+ secret types including cloud provider keys, database URLs, JWT tokens, and private keys.

## Architecture Overview
```
[Git Repository]
        |
   [Gitleaks Scanner (Go)]
        |
+-------+-------+
|               |
[detect mode]   [protect mode]
Scan all        Scan staged
commit history  changes only
(find leaks)    (prevent leaks)
        |
   [Rule Engine]
   100+ regex patterns
   for secret types:
   AWS keys, GitHub tokens,
   DB passwords, private keys,
   JWT, OAuth, Stripe, etc.
        |
   [Allowlists]
   Skip known false positives
   Path, commit, regex-based
        |
   [Report]
   JSON, CSV, SARIF
   for CI/CD integration
```

## Self-Hosting & Configuration
```toml
# .gitleaks.toml — custom configuration
title = "Custom Gitleaks Config"

[extend]
# Extend the default ruleset
path = "https://raw.githubusercontent.com/gitleaks/gitleaks/master/config/gitleaks.toml"

# Add custom rules
[[rules]]
id = "custom-internal-token"
description = "Internal API Token"
regex = "INTERNAL_TOKEN_[A-Za-z0-9]{32}"
tags = ["internal", "token"]

# Allowlist specific paths or patterns
[allowlist]
paths = [
  "tests/fixtures",
  ".gitleaks.toml",
  "docs/examples"
]
```

```bash
# Pre-commit hook integration
# .pre-commit-config.yaml:
# repos:
#   - repo: https://github.com/gitleaks/gitleaks
#     rev: v8.18.0
#     hooks:
#       - id: gitleaks

# GitHub Actions integration
# - uses: gitleaks/gitleaks-action@v2
#   env:
#     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

## Key Features
- **Git History Scan** — finds secrets in all commits, not just current files
- **100+ Secret Types** — pre-built patterns for AWS, GCP, GitHub, Stripe, etc.
- **Pre-Commit Hook** — prevent secrets from being committed
- **CI/CD Ready** — GitHub Actions, GitLab CI, Jenkins integration
- **Custom Rules** — add organization-specific secret patterns
- **Allowlists** — suppress known false positives by path, commit, or regex
- **SARIF Output** — integrate with GitHub Security and code scanning
- **Fast** — Go-based with parallel scanning

## Comparison with Similar Tools
| Feature | Gitleaks | TruffleHog | detect-secrets | GitGuardian |
|---|---|---|---|---|
| Language | Go | Go | Python | Cloud |
| Git History | Yes | Yes | No (files only) | Yes |
| Verification | No | Yes (checks if active) | No | Yes |
| Custom Rules | TOML config | YAML | Plugin system | Dashboard |
| Speed | Very Fast | Fast | Moderate | Fast (cloud) |
| False Positives | Low-Moderate | Low (verified) | Low | Very Low |
| Cost | Free (OSS) | Free + Paid | Free (OSS) | Free + Paid |
| Best For | CI/CD + pre-commit | Verified scanning | Python projects | Enterprise |

## FAQ
**Q: Gitleaks vs TruffleHog — which should I use?**
A: Gitleaks for pre-commit hooks and fast CI scanning. TruffleHog if you want verified results (it checks if detected keys are actually active). Many teams use both.

**Q: How do I handle false positives?**
A: Add exceptions to .gitleaks.toml using allowlist paths, regex patterns, or specific commit hashes. Use inline comments like "gitleaks:allow" to suppress specific lines.

**Q: What if I find a leaked secret?**
A: Immediately rotate the credential (generate a new key/password). Even if you remove it from code, it still exists in Git history. Rotating is the only safe remediation.

**Q: Can Gitleaks scan non-Git directories?**
A: Yes. Use "gitleaks dir -s /path/to/directory" to scan any directory for secrets without Git history analysis.

## Sources
- GitHub: https://github.com/gitleaks/gitleaks
- Documentation: https://github.com/gitleaks/gitleaks#readme
- Created by Zach Rice
- License: MIT

---
Source: https://tokrepo.com/en/workflows/40b108c4-372b-11f1-9bc6-00163e2b0d79
Author: AI Open Source