Defame1297
e50c98f722
Skills and evals migrated from .agents/ to plugins/bin/ plugin directory. Remove .mcp.json, provider-manifest.sh, and skills-lock.json legacy artifacts. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
112 lines
6.9 KiB
Markdown
112 lines
6.9 KiB
Markdown
---
|
|
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>
|