Defame1297
25a6a454b9
- scripts/setup-gitleaks.sh — installs gitleaks v8.24.2, seeds .gitleaks.toml on first run, writes managed pre-commit hook block; re-run replaces block in place without disturbing other hook content - scripts/gitleaks.toml — base config template extending default ruleset - .gitleaks.toml — repo config with docs/research/ path allowlist (high-entropy terminal captures; v8.24.2 [allowlist] syntax) - tests/test-setup-gitleaks.sh — 6 behavior tests including stale-block replacement and idempotency - .agents/skills/gitleaks/ — cross-cutting skill covering install, update, allowlist tuning, scan modes, and real-finding remediation - .agents/evals/cross-cutting/gitleaks/eval.yaml — 7 trigger + 3 output tests including version-aware allowlist guidance case - docs/spec/overview.md — updated to reflect new tooling and skill Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
84 lines
2.0 KiB
Markdown
84 lines
2.0 KiB
Markdown
# Gitleaks allowlist patterns
|
|
|
|
## Version syntax
|
|
|
|
| Version | Allowlist syntax |
|
|
|---|---|
|
|
| v8.24.2 and earlier | `[allowlist]` (singular table) |
|
|
| v8.25.0 and later | `[[allowlists]]` (array of tables) |
|
|
|
|
**Critical**: using the wrong syntax produces no error but the allowlist silently does nothing. Always check `gitleaks version` first.
|
|
|
|
## v8.24.2 syntax (this repo uses 8.24.2)
|
|
|
|
### Suppress by path regex
|
|
|
|
Use for files that can never contain real secrets (research notes, terminal captures, test fixtures, generated docs).
|
|
|
|
```toml
|
|
[allowlist]
|
|
description = "research notes and terminal captures"
|
|
paths = [
|
|
'''docs/research/.*''',
|
|
'''tests/fixtures/.*''',
|
|
]
|
|
```
|
|
|
|
### Suppress by stopword
|
|
|
|
Use for placeholder values that match secret patterns but are clearly not real.
|
|
|
|
```toml
|
|
[allowlist]
|
|
description = "placeholder values"
|
|
stopwords = ["example", "placeholder", "changeme", "your-api-key-here"]
|
|
```
|
|
|
|
### Disable a default rule entirely
|
|
|
|
Use only when a rule has no value for this repo and produces pervasive false positives.
|
|
|
|
```toml
|
|
[extend]
|
|
useDefault = true
|
|
disabledRules = ["generic-api-key"]
|
|
```
|
|
|
|
## v8.25.0+ syntax (for reference)
|
|
|
|
```toml
|
|
[[allowlists]]
|
|
description = "research notes"
|
|
paths = ['''docs/research/.*''']
|
|
|
|
[[allowlists]]
|
|
description = "placeholder values"
|
|
stopwords = ["example", "placeholder"]
|
|
```
|
|
|
|
## .gitleaksignore (fingerprint-based — last resort)
|
|
|
|
```
|
|
# Format: <fingerprint>:<line-number>
|
|
# Generated by: gitleaks git -v --report-format json | jq -r '.[] | "\(.Fingerprint):\(.StartLine)"'
|
|
abc123def456:42
|
|
```
|
|
|
|
Avoid this approach: fingerprints embed line numbers. Any edit to the file shifts line numbers and invalidates the entry, re-surfacing the false positive.
|
|
|
|
## Verification after any change
|
|
|
|
```bash
|
|
# Scan current files
|
|
gitleaks dir -v .
|
|
|
|
# Scan with debug output to see which allowlists fired
|
|
gitleaks dir --log-level debug .
|
|
|
|
# Scan commit history
|
|
gitleaks git -v
|
|
|
|
# Scan only staged changes (what the pre-commit hook runs)
|
|
gitleaks git --staged --redact -v
|
|
```
|