Secret Scanning

Secret scanners find API keys, passwords and private keys in source code and Git history before an attacker does. This sheet covers gitleaks and TruffleHog (local and CI), pre-commit hooks, and GitHub’s built-in secret scanning with push protection. Related: Git, GitHub and the gh CLI, SOPS and age for storing secrets safely, Container Scanning for images.

Documentation: gitleaks · TruffleHog · GitHub secret scanning

If a secret was ever committed, treat it as compromised: rotate it first, then clean history. Deleting it in a later commit does not help.

gitleaks #

Older versions (before 8.19) use gitleaks detect and gitleaks protect --staged; both still work as deprecated aliases.

.gitleaks.toml #

[extend]
useDefault = true            # keep built-in rules and add yours

[[rules]]
id = "internal-api-token"
description = "Internal API token"
regex = '''myco_[A-Za-z0-9]{32}'''
keywords = ["myco_"]

[allowlist]
description = "Global allowlist"
paths = [
  '''(^|/)tests?/fixtures/''',
  '''\.lock$''',
]
regexes = ['''EXAMPLE_KEY_[A-Z0-9]+''']

Ignore one specific finding by adding its fingerprint (printed in the report) to .gitleaksignore, or add gitleaks:allow as a comment on the offending line.

TruffleHog #

--only-verified calls the provider API to check whether the credential is still valid, which means the key is sent to that provider. Drop it for an offline scan, at the cost of more false positives.

pre-commit Hooks #

Add to .pre-commit-config.yaml (install with pip install pre-commit && pre-commit install):

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: <TAG>                 # pin to a release tag, e.g. v8.x.y
    hooks:
      - id: gitleaks
  - repo: https://github.com/trufflesecurity/trufflehog
    rev: <TAG>
    hooks:
      - id: trufflehog
        args: ["--only-verified"]

Hooks are local and optional, so always back them with a CI check.

CI (GitHub Actions) #

name: secrets
on: [push, pull_request]
jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<SHA_OR_TAG>
        with:
          fetch-depth: 0              # full history, otherwise old leaks are missed
      - uses: gitleaks/gitleaks-action@<SHA_OR_TAG>
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The gitleaks action requires a licence key for organisation-owned repos; for those, run the binary directly instead. Pin actions to a tag or commit SHA.

GitHub Secret Scanning and Push Protection #

Free for public repos; private repos need GitHub Secret Protection (GitHub Advanced Security). Push protection blocks a push containing a recognised secret.

Enable on a repository via the API:

gh api -X PATCH repos/<OWNER>/<REPO> --input - <<'EOF'
{"security_and_analysis":{
  "secret_scanning":{"status":"enabled"},
  "secret_scanning_push_protection":{"status":"enabled"}}}
EOF

When a push is blocked, GitHub prints the file and line. Remove the secret (git commit --amend, or git rebase -i for older commits) and push again. A bypass option exists (“it’s used in tests”, “false positive”, “I’ll fix it later”) and is logged.

Removing a Leaked Secret from History #

pip install git-filter-repo
git filter-repo --replace-text expressions.txt     # lines like: literal:<LEAKED_VALUE>==>REDACTED
git push --force --all && git push --force --tags

Everyone with a clone must re-clone, and forks and caches (and GitHub pull-request refs) may still hold the old objects. Rotation is the only real fix.

Troubleshooting #