[Git] Gitleaks

Gitleaks

 gitleaks     git    security    sast  

https://github.com/gitleaks/gitleaks

Gitleaks is a SAST(Static Application Security Testing) tool for detecting hardcoded secrets like passwords, API keys, and tokens in Git repositories.

---

Installation

See https://github.com/gitleaks/gitleaks#installing

The quickest way is using Go.

git clone https://github.com/gitleaks/gitleaks.git \
cd gitleaks \
make build

After build, copy the gitleaks.exe to $GOBIN and check the version.

cp gitleaks.exe $GOBIN/
gitleaks version

---

Basic concepts

• Detect mode: scan a repository and report potential secrets.
• Exit code: by default, Gitleaks exits with a non‑zero code if leaks are found. This is useful for CI pipelines.

Commands

See full list at https://github.com/gitleaks/gitleaks#usage

Syntax:

gitleaks <COMMAND> [FLAGS]

Command	Description
completion	Generate the autocompletion script for the specified shell
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

Common flags:

Flag	Description
--source PATH_OR_URL	what to scan (local path or remote Git URL).
--report-path FILE	where to write the JSON report.
--redact	hide secret values in the output.
--no-git	scan files as a regular directory (ignore Git history).

---

Gitleaks Configuration

Default configuration(rules and allowlist) is at gitleaks.toml. You can use your custom configuration by flag --config <CONFIG_PATH>. e.g.

gitleaks detect --source . --config ~/gitleaks.toml --redact

---

Audit a local repository

From the repository root

Change into your repo and run:

gitleaks detect --source . --redact

• Scans the entire Git history of the repo
• Prints findings to stdout
• Redacts secret values in the output

Save a JSON report

gitleaks detect \
  --source . \
  --redact \
  --report-path gitleaks-report.json

You can then open gitleaks-report.json in any JSON viewer or feed it into other tools.

Scan only current files (no Git history)

The flag --no-git makes gitleaks only scans the current working tree.

gitleaks detect \
    --source . \
    --no-git \
    --redact \
    --report-path gitleaks-report.json

---

Audit a remote repository (e.g., GitHub)

We can scan a remote repository in two ways:

1. Manually clone it, then scan locally (recommended for repeat scans)
   • You want to scan the same repo multiple times.
   • You want to commit the gitleaks.toml config into the repo.
2. Let Gitleaks clone it on the fly (recommended for quick checks)

Scan Remote Repo by URL (no manual clone)

You can point --source directly at a Git URL.

Public Repository

gitleaks detect \
  --source https://github.com/OWNER/REPO.git \
  --redact
  --report-path gitleaks-OWNER-REPO-report.json

Gitleaks will:

• Clone the repo into a temporary directory
• Scan its history
• Remove the temporary clone after completion

Private Repository

For private repositories you must provide credentials (for example, a GitHub Personal Access Token via environment variables or your Git credential helper).

e.g. Using a GitHub token in the URL:

gitleaks detect \
  --source https://GITHUB_TOKEN@github.com/OWNER/REPO.git \
  --redact

For long-term usage, consider the safer approaches:

• Use environment variables and avoid hardcoding tokens in scripts.
• Use the CI tools, like GitHub Action.

---

Exit codes and CI integration

Gitleaks returns different exit codes depending on the result of the scan

• 0 = no leaks found
• non-zero = leaks or errors

This behavior makes it easy to integrate into CI pipelines (GitHub Actions, GitLab CI, etc.):

• Pass: No secrets detected → pipeline continues
• Fail: Secrets detected → pipeline fails, forcing remediation

Typical CI command:

gitleaks detect --source . --redact --report-path gitleaks-report.json