LinuxCommandLibrary

gitleaks

Scan Git repositories for secrets

TLDR

Scan a remote repository

$ gitleaks detect --repo-url [https://github.com/username/repository.git]
copy

Scan a local directory
$ gitleaks detect --source [path/to/repository]
copy

Output scan results to a JSON file
$ gitleaks detect --source [path/to/repository] --report [path/to/report.json]
copy

Use a custom rules file
$ gitleaks detect --source [path/to/repository] --config-path [path/to/config.toml]
copy

Start scanning from a specific commit
$ gitleaks detect --source [path/to/repository] --log-opts [--since=commit_id]
copy

Scan uncommitted changes before a commit
$ gitleaks protect --staged
copy

Display verbose output indicating which parts were identified as leaks during the scan
$ gitleaks protect --staged --verbose
copy

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)

Copied to clipboard