---
name: gitleaks
description: 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.
metadata:
  category: cross-cutting
allowed-tools:
  - Bash
  - Read
  - Edit
---

<requirements>

## 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

</requirements>

<steps>

## 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

</steps>

<checks>

## 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`

</checks>