holocron/plugins/bin/skills/gitleaks/SKILL.md

name, description, metadata, allowed-tools

name	description	metadata	allowed-tools
gitleaks	Use when the user wants to install gitleaks, wire it as a git pre-commit secret scanner, update the hook in an existing repo, tune allowlist rules, resolve false positives, or debug a gitleaks scan finding. Do NOT use when the user wants a general security review of code (use security-review), wants to add secret scanning to a CI pipeline (use write-ci-pipeline), or is asking about a different secret scanning tool such as trufflehog or git-secrets.	category cross-cutting	Bash Read Edit

Required inputs

• Target repo path — absolute path to the git repository to configure; inferred from current working directory if not stated, ask if ambiguous
• Task type — install/configure, update hook, tune allowlist, debug finding; inferred from the user's request

Constraints

• Always state what you are about to do before running setup-gitleaks.sh — the script modifies .git/hooks/pre-commit and seeds .gitleaks.toml
• Never modify .gitleaks.toml if the user has not asked for allowlist changes — it is project-owned once seeded; treat it as user-controlled config
• Never run gitleaks git or gitleaks dir across the full history without warning the user it may be slow on large repos
• Redact any secret values that appear in gitleaks output before showing them to the user — show the rule ID, file, and line number only
• When the installed gitleaks version is unknown, check it with gitleaks version before suggesting config syntax — v8.24.2 uses [allowlist]; v8.25.0+ uses [[allowlists]]
• False positive suppression: prefer path-based allowlists in .gitleaks.toml over fingerprint-based entries in .gitleaksignore — fingerprints are line-number-sensitive and break on file edits

Process

Install and configure

1. Confirm target. State: "I will run scripts/setup-gitleaks.sh <path> which will install gitleaks (if absent), seed .gitleaks.toml (first run only), and write the pre-commit hook. Proceed?" Wait for confirmation — this modifies the repo's git hook.

2. Run setup script. Execute from the ai-development repo root:

   bash scripts/setup-gitleaks.sh <TARGET_REPO>
   

   The script is idempotent — it replaces the gitleaks block in the hook on every run without disturbing other hook content.

3. Verify installation. Run gitleaks version to confirm the binary is available. Run gitleaks git --staged --redact -v in the target repo to confirm the hook would work on a staged commit (add a dummy change if needed to test).

4. Commit .gitleaks.toml. Remind the user that .gitleaks.toml belongs in version control so all contributors share the same allowlist rules.

Update hook

Re-run bash scripts/setup-gitleaks.sh <TARGET_REPO> from the ai-development repo root. The managed block (delimited by # managed by setup-gitleaks.sh / # end gitleaks markers) is always replaced with the current version. Non-gitleaks hook content is preserved.

Tune allowlist / resolve false positives

1. Identify the false positive. Run gitleaks dir --log-level debug <path> to see which rule fired and which allowlist entries (if any) are already active.

2. Check the gitleaks version. Run gitleaks version. Use [allowlist] syntax for v8.24.2; use [[allowlists]] syntax for v8.25.0+. Using the wrong syntax silently produces no errors but the allowlist does nothing — this is the most common configuration trap.

3. Choose suppression strategy. Read .gitleaks.toml first. See references/allowlist-patterns.md for syntax examples and when to use each approach:

   • Path regex in [allowlist] — for files that can never contain real secrets (research notes, terminal captures, test fixtures). Preferred.
   • Stopwords in [allowlist] — for placeholder patterns like "example", "changeme".
   • disabledRules in [extend] — to disable a noisy default rule entirely. Use only when the rule has no value for this repo.
   • .gitleaksignore fingerprint — last resort; breaks when the file is edited because line numbers shift.

4. Edit .gitleaks.toml. Add the minimal allowlist entry needed. Do not suppress more than the identified false positive.

5. Verify. Re-run gitleaks dir -v <path> or gitleaks git -v to confirm the false positive is suppressed and no real findings are hidden.

Scan modes

Mode	Command	When to use
Staged changes (pre-commit)	gitleaks git --staged --redact -v	What the hook runs
Full commit history	gitleaks git -v	Audit existing repo history
Working directory files	gitleaks dir -v <path>	Scan uncommitted files
Debug allowlists	gitleaks dir --log-level debug <path>	See which files are skipped and which allowlists fire

Resolve a real finding

1. Do not redact or show the secret value. Reference the rule ID, file, and line number only.
2. The secret is compromised the moment it was committed — rotate it immediately, regardless of whether the commit is reachable from the public remote.
3. Remove the secret from history using git filter-repo (not git filter-branch). This is a history-rewrite — confirm with the user before running. Force-push to all remotes after rewriting.
4. Add the file path to the .gitleaks.toml allowlist only if the file is known to be a false-positive source going forward (e.g. a test fixture). Do not add an allowlist entry to suppress a real finding that has been removed.

Output format

No structured output file. The skill produces:

• Modified .git/hooks/pre-commit in the target repo (via the setup script)
• Modified .gitleaks.toml in the target repo (allowlist changes only, when requested)
• Terminal confirmation of what was changed and what to do next

Failure handling

• setup-gitleaks.sh not found — stop; instruct the user to run from the ai-development repo root at /root/ai-development/
• Target path is not a git repository — report the error from the script and ask the user to confirm the correct path
• gitleaks binary not installed and download fails — report the curl/network error; direct the user to manual install at https://github.com/gitleaks/gitleaks/releases
• Wrong TOML syntax for installed version — detect via gitleaks version, show the correct syntax for that version, do not guess

Self-check

• Target repo confirmed before running the setup script
• gitleaks version checked before writing any .gitleaks.toml allowlist syntax
• Secret values in scan output redacted before displaying to the user
• .gitleaks.toml edits are minimal — only the identified false positive suppressed
• After any allowlist change: re-ran scan to verify suppression works and no real findings are hidden
• For real findings: rotation step stated before history rewrite, user confirmed history rewrite before running git filter-repo