Allowlists

Allowlists suppress findings. They can be scoped globally (any rule) or to a specific rule, and each can combine multiple criteria with OR (default) or AND.

Where they live

Scope	TOML	Runtime
Global	[[allowlists]]	Config.Allowlists
Per-rule	[[rules.allowlists]]	Rule.Allowlists
Targeted (global allowlist applied only to named rules)	[[allowlists]] with targetRules	folded into the named rules' Allowlists after extend

The runtime type is config.Allowlist (config/allowlist.go).

Criteria

A single allowlist can combine four kinds of criteria:

Criterion	TOML field	What it matches
Commits	commits = [...]	Specific git commit SHAs (case-insensitive)
Paths	paths = ['''regex''']	File path regexes
Regexes + RegexTarget	regexes = [...], regexTarget = "secret"|"match"|"line"	Content regex against the secret/match/line
StopWords	stopwords = [...]	Substrings inside the extracted secret (case-insensitive, Aho-Corasick)

An empty allowlist (no criteria at all) is a config error — Allowlist.Validate returns "must contain at least one check…".

Match condition

condition = "OR" (the default) means any one criterion is enough. condition = "AND" means every populated criterion must match.

Implementation is in two helpers in detect/detect.go:

• checkCommitOrPathAllowed — runs at fragment intake. With OR, returns true if either commit or path matches. With AND, builds a check list of only the populated criteria; regex/stopword checks are skipped here (they need a finding) and revisited later.
• checkFindingAllowed — runs against an extracted finding. Same dual mode; for AND it re-evaluates all criteria including commit/path so the conjunction is fully checked once a finding exists.

graph TD
    F[Fragment] --> Path{checkCommitOrPathAllowed?}
    Path -->|allowed| Skip1[skip fragment]
    Path -->|not allowed| Run[run rules]
    Run --> Find[Finding]
    Find --> CFA{checkFindingAllowed<br/>against Finding's secret/match/line?}
    CFA -->|allowed| Skip2[drop finding]
    CFA -->|not allowed| Out[emit finding]

RegexTarget

When a regex is part of the allowlist, regexTarget controls what's tested:

• "secret" (default if empty) — the extracted secret in Finding.Secret
• "match" — the entire regex match (the substring the rule's regex matched, before secretGroup extraction)
• "line" — the full line containing the match

A common use case is regexTarget = "line" with a regex that recognizes test fixtures or example code:

[[rules.allowlists]]
description = "ignore example values"
regexTarget = "line"
regexes = ['''(?i)(?:example|placeholder)''']

Stopwords

Stopwords are simple substring filters against the extracted secret. They use a precompiled Aho-Corasick trie (stopwordTrie in Allowlist) for efficiency. Common stopwords like client, endpoint, example, your_token_here strip out obvious placeholders.

ContainsStopWord returns the matched stopword for log output:

allowed-stopword: example

Targeted global allowlists

Introduced in v8.25.0, a global allowlist can opt to apply only to specific rules:

[[allowlists]]
targetRules = ["awesome-rule-1", "awesome-rule-2"]
description = "Our test assets trigger false-positives in a couple rules."
paths = ['''tests/expected/._\.json$''']

In ViperConfig.Translate, allowlists with non-empty TargetRules aren't added to the global Config.Allowlists. Instead they go into a ruleAllowlists[ruleID] map and, after the extend pass completes, are appended to each named rule's own Allowlists. This means even rules pulled in from extend.useDefault can be targeted.

Backwards compatibility

The TOML key has changed twice in the v8 series:

• v8.21.0: [rules.allowlist] (singular) → [[rules.allowlists]] (plural)
• v8.25.0: [allowlist] → [[allowlists]] and the targetRules field is added

Both old forms still work. ViperConfig keeps AllowList (singular) shim fields with // TODO: Remove this in 9.x comments. Mixing old and new on the same rule is a config error.

Inline gitleaks:allow

A magic marker — the constant gitleaksAllowSignature in detect/detect.go is "gitleaks:allow". If the matched line contains this string, the finding is skipped:

api_key = "AKIAIOSFODNN7EXAMPLE"  # gitleaks:allow

This check runs inside detectRule, after the regex match but before content allowlist evaluation. The flag --ignore-gitleaks-allow disables it.

Per-finding fingerprints (.gitleaksignore)

A separate mechanism, but conceptually adjacent: .gitleaksignore is a newline-delimited file of fingerprints. See baselines for details.

Related

• Secret detection — the rule pipeline overall
• systems/config — how Allowlist is parsed and validated
• systems/detect — checkCommitOrPathAllowed / checkFindingAllowed implementation