secrets-scan

Secrets scan

When to use

• Before a commit (the git-commit skill calls this on staged files).
• When the user asks to check for secrets, keys or credentials.
• After a secret was pasted into code, a log, an issue or chat, or committed by mistake.
• As part of security-audit, which only scans the working tree; this skill also covers history.

Before you start

• Check that gitleaks is installed: gitleaks version. If it isn't, ask before installing it, and install only from the official source (package manager or the GitHub releases page).
• Agree the scope with the user: staged changes (default), the working tree, a commit range, or the full history. A full-history scan can be slow on large repos.
• Never print, echo or paste a secret value, even partly. Always pass --redact so gitleaks hides values in its output.
• Don't write a report file into the repo. If the user wants one, write it outside the working tree with --redact and delete it when done.

Steps

1. Run the scan for the agreed scope (from the repo root):

   Scope	Command
   Staged changes	gitleaks git --staged --redact --no-banner -v
   Unstaged changes	gitleaks git --pre-commit --redact --no-banner -v
   Working tree (all files, tracked or not)	gitleaks dir . --redact --no-banner -v
   A commit range	gitleaks git --log-opts="origin/main..HEAD" --redact --no-banner -v
   Full history	gitleaks git . --redact --no-banner -v

   Exit code 1 means leaks were found; 0 means none. Respect an existing .gitleaks.toml and .gitleaksignore.

2. Triage each finding. For each one, note the rule ID, file, line, commit (for history scans) and author. Decide:

   • Real secret: go to step 3.
   • Test fixture or example value: confirm it grants no access, then suggest a gitleaks:allow comment on that line, or a fingerprint in .gitleaksignore. Ask the user first; never add an ignore on your own.
   • False positive: same as above, with the reason.

3. Contain a real secret. Explain to the user, in this order:

   1. Revoke or rotate it first, at the provider (cloud console, GitHub token settings, npm token revoke, the API vendor's dashboard). A secret that reached a remote, a CI log, a package or chat is compromised even after it's deleted. Removing it from history doesn't make it safe.
   2. Check for misuse: review the provider's access logs for the period since the leak.
   3. Replace it with a reference to an env var or secret manager (process.env.STRIPE_SECRET_KEY, a CI secret, a vault). Add the file to .gitignore if it's a local config file.
   4. Remove it from the code in a normal commit.

4. Only if the user asks, rewrite history. Explain the cost first:

   • every commit hash after the first affected commit changes;
   • a force-push is required, and every collaborator must re-clone or rebase; forks, open PRs, caches and existing clones keep the old data;
   • on GitHub, cached views and PR refs may need GitHub Support to purge.