Gitleaks Custom Rules & False-Positive Tuning Prompt
Tune a Gitleaks config — custom rules, allowlists, and entropy thresholds — to catch real secrets while cutting the false positives that train developers to ignore the gate.
- Target user
- AppSec and platform engineers running secret scanning in CI who are fighting alert fatigue
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior AppSec engineer who has tuned secret-scanning gates across many repositories and knows that precision, not recall alone, decides whether a gate gets respected or bypassed. I will provide: - The current Gitleaks config (TOML) or note that we use defaults — [CONFIG] - A sample of recent findings, ideally labeled true/false positive — [FINDINGS SAMPLE] - The languages, frameworks, and any synthetic/test secrets in the repo — [REPO CONTEXT] - Where Gitleaks runs (pre-commit, CI, full-history scan) and whether it blocks — [GATE PLACEMENT] Your job, step by step: 1. **Triage the sample** — bucket each finding as true positive, false positive, or needs-verification, and name the pattern driving each false positive (test fixtures, high-entropy non-secrets like hashes/UUIDs, example credentials in docs). 2. **Custom rules** — write or refine Gitleaks rules (regex + entropy) for the secret types this repo actually handles that defaults miss, with a clear description and an example match for each. 3. **Targeted allowlists** — design path-, regex-, and commit-scoped allowlists that suppress the named false-positive patterns *narrowly*, never with a broad catch-all that would also hide real leaks. Justify each allowlist entry. 4. **Entropy thresholds** — recommend stopwords and entropy tuning where high-entropy non-secrets dominate, and explain the precision/recall tradeoff of each change. 5. **Gate strategy** — recommend pre-commit (fast, advisory) vs CI (blocking) placement, whether to scan full history or only the diff, and how to handle a confirmed historical leak (rotate first, then scrub). 6. **Measure** — propose how to track false-positive rate over time so the config keeps earning trust. Output as: (a) the triage table, (b) the updated Gitleaks TOML diff, (c) a one-line justification per allowlist entry, (d) the recommended gate config. Present the config changes as a proposal to review — never allowlist a value without confirming it is genuinely not a live secret, and always recommend rotation before scrubbing a real one.
Why this prompt works
Secret scanning fails not when it misses things but when it cries wolf: a gate that flags test fixtures, UUIDs, and example credentials on every push trains developers to skip it or blanket-allowlist their way past it, at which point a real leak sails through. This prompt centers precision — it makes the model triage actual findings, name the pattern behind each false positive, and then suppress those patterns narrowly rather than reaching for a broad allowlist that would also hide genuine secrets.
Gitleaks tuning is a craft of regex, entropy thresholds, and scoped allowlists, and the prompt walks each lever deliberately so the model produces a reviewable TOML diff with a justification per allowlist entry instead of a config dump. The explicit precision/recall framing keeps it honest about the tradeoffs: loosening entropy to silence hash false positives can also blind the scanner, and the prompt forces that cost to be stated rather than buried.
Crucially, the prompt encodes the one non-negotiable of secret handling: a confirmed leak means rotate first, then scrub. By instructing the model to never allowlist a value it has not confirmed is non-live, and to recommend rotation before history surgery, it keeps the AI in the role of a drafting assistant for a human who owns the call — which is the only safe posture when the subject is live credentials.