Why Scan Git History Locally?
Leaking secrets like API keys, database credentials, and SSH private keys in your Git repository is one of the most common security vulnerabilities in software development. When a secret is accidentally committed, simply deleting the secret in a new commit does not solve the problem. Git is a version control system designed to preserve history; the secret remains fully accessible in your repository history, waiting for anyone with clone access to find it.
Scanning your Git history locally is the safest way to identify these leaks. By performing local-only scans, you prevent sensitive codebase data from being uploaded to third-party SaaS platforms during the detection phase. It allows you to find and remediate exposures before they are pushed to remote servers, keeping your credentials secure within your local sandbox environment.
Best Open Source Local Git Secrets Scanners
The best open-source tools for scanning local Git history are Gitleaks and TruffleHog. Both tools are designed to parse your entire Git commit history, analyzing diffs, files, and commit messages for high-entropy strings and known credential patterns. They run entirely on your local machine, ensuring complete privacy.
1. Gitleaks
Gitleaks is a highly popular, lightweight, and incredibly fast open-source scanner written in Go. It is designed specifically for detecting secrets in code and Git history. It uses regular expressions and entropy calculations defined in a customizable configuration file to identify credentials.
Key benefits of Gitleaks include its speed, low memory footprint, and the ability to run easily in local pre-commit hooks or automated continuous integration environments.
2. TruffleHog
TruffleHog is another powerful open-source security tool that excels at scanning Git repositories. Unlike basic regex scanners, TruffleHog specializes in high-fidelity detection by verifying identified secrets against the target APIs. While its verification feature requires network access to confirm if a key is active, its core scanning engine runs completely locally against your Git database.
TruffleHog is particularly effective at scanning deep historical branches, submodules, and individual commits to ensure no historical stone is left unturned.
Step-by-Step: How to Scan Local Git History for Secrets
To scan your local Git history, you can use Gitleaks. Follow this step-by-step process to perform a comprehensive scan of your repository from day one of its creation.
Step 1: Install Gitleaks on your local machine.If you are using macOS, you can install Gitleaks using Homebrew by running the command: brew install gitleaks. For Linux or Windows environments, you can download the pre-compiled binary directly from the official Gitleaks GitHub releases page and add it to your system path.
Step 2: Navigate to your local Git repository.
Open your terminal and change directories to the root of the local Git repository you want to scan: cd /path/to/your/local-repo
Step 3: Run the history detection command.
To scan the entire history of your current branch, execute the following command: gitleaks detect --source=. --verbose
The --source=. flag tells Gitleaks to analyze the current directory, and the --verbose flag ensures that any detected secrets are printed directly to your terminal screen, showing the exact commit hash, file path, line number, and the specific string that triggered the rule.
Step 4: Analyze the output.
If Gitleaks finds any secrets, it will display a detailed report. Each finding includes a commit hash, which you can use to inspect the commit using git show [commit-hash]. If no secrets are found, Gitleaks will exit with a success code, indicating your local history is clean of recognized patterns.
How to Run Git Secret Scan Before Push
Detecting secrets in your history is reactive; preventing them from reaching your remote repository is proactive. The most efficient way to enforce this is by setting up a local git secret scan before push or commit operations occur.
You can configure a pre-push hook that intercepts the git push command and runs a scan on the commits you are about to send to the remote server. To do this, create or edit the pre-push file in your local repository hooks directory: .git/hooks/pre-push
Add the following bash script to the file:
#!/bin/sh
gitleaks protect --verbose --staged
Make the hook script executable by running: chmod +x .git/hooks/pre-push
Now, every time you attempt to run git push, Gitleaks will automatically scan your staged changes and local commits. If a secret is detected, the command will exit with a non-zero status, and the push operation will be blocked, keeping the secret safely on your local machine.
For a more comprehensive setup, you can read our guide on How to Scan Code for Secrets Before Pushing: A Step-by-Step Guide or explore our tutorial on How to Set Up Pre-Commit Code Security Scanning to learn how to block credential leaks at the commit stage.
How to Completely Remove Secrets from Git History
If your local scan reveals that a secret was committed several months ago, simply deleting the file or changing the line of code and making a new commit will not secure your repository. The secret remains in the Git database. To completely remove secrets from git history, you must rewrite the repository history.
Do not use the old git filter-branch command, as it is slow, error-prone, and often leaves behind backup references that still contain the sensitive data. Instead, use the modern, officially recommended tool: git-filter-repo.
Follow these steps to completely purge a secret from your history:
- Create a fresh backup clone: Because history rewriting is destructive, clone your repository to a safe secondary directory before proceeding.
- Install git-filter-repo: Install the tool using your package manager, such as brew install git-filter-repo or via Python package managers.
- Create a replacement file: Create a text file named passwords.txt containing the secret you want to remove, formatted as the old value followed by the new value. For example: secret_api_key_here==>REMOVED_SECRET
- Run the rewriting command: Run the following command in the root of your repository: git-filter-repo --replace-text passwords.txt
- Verify and clean up: Check your git log to ensure the secret has been replaced with the string REMOVED_SECRET. Once verified, run Git garbage collection to delete the old loose objects: git gc --prune=now --aggressive
- Force push to remote: Since the history has been completely rewritten, you must force push the updates to your remote repository: git push origin --force --all
Remember that rewriting history alters commit hashes. Coordinate this action with your team, as anyone with an active local clone will need to re-clone or reset their local branches to match the new remote history.
Automating Security on GitHub with Patchhog
While local scanning is an essential first line of defense, developers occasionally bypass local hooks or forget to configure them on new development machines. To ensure absolute security coverage across your entire engineering team, you need an automated, server-side safety net.
This is where Patchhog fits into your workflow. Patchhog is a security analysis tool that automatically scans GitHub repositories for vulnerabilities and provides paste-ready fixes for identified issues. It integrates seamlessly with your GitHub repositories via OAuth, acting as a continuous security gatekeeper.
When connected, Patchhog automatically scans every single code push for vulnerabilities using multiple deterministic scanners. It covers a broad security scope, including:
- Secrets exposure detection
- Static Application Security Testing (SAST)
- Dependency and CVE checks
- Infrastructure as Code (IaC) misconfigurations
- Malware detection
- Container and API security analysis
Each finding is displayed on a centralized dashboard, accompanied by a precise, paste-ready fix, allowing developers to quickly resolve vulnerabilities without manual triage effort. Patchhog does not use artificial-intelligence features, ensuring reliable, deterministic results. For teams that want to bridge the gap between local development and cloud automation, Patchhog also ships a CLI (requiring Node 18+) designed for local pre-commit checks and CI/CD pipelines.
Patchhog offers flexible monthly and yearly subscription plans with a 7-day trial, starting with the Solo plan at 29 EUR/month for 3 private repositories, scaling up to Pro and Business plans for larger organizations.
Conclusion
Scanning your local Git history is a foundational security practice that keeps your credentials secure and prevents costly leaks. By leveraging open-source tools like Gitleaks and TruffleHog, setting up pre-push hooks, and knowing how to safely rewrite history with git-filter-repo, you can maintain a clean, secure codebase.
To automate this process and get paste-ready fixes for any security vulnerabilities in your GitHub repositories, explore the capabilities of Patchhog today.
FAQ
Why is running git rm not enough to delete a secret?
Git preserves the entire history of your project. Running git rm only removes the file from the current and future commits. The file, along with the secret inside it, still exists in the older Git objects and commits, meaning anyone can retrieve it by checking out an older commit hash.
What should I do immediately after finding a leaked secret in my history?
Your first step must always be to revoke and rotate the secret. Even if you plan to completely rewrite your Git history, you must assume that the secret has already been compromised from the moment it was committed or pushed.
How does git-filter-repo differ from git filter-branch?
Git-filter-repo is faster, safer, and recommended by the official Git documentation. Git filter-branch is deprecated because it is extremely slow on large repositories, difficult to use correctly, and often fails to remove all references to the purged data, leaving secrets hidden in the repository database.