config

Active contributors: Zachary Rice, Richard Gomez

Purpose

config/ defines the schema for Gitleaks's TOML configuration, the runtime form of rules and allowlists with compiled regexes, the extend mechanism that lets user configs inherit from another config (or the embedded default), and the embedded default gitleaks.toml.

Directory layout

config/
├── config.go        # ViperConfig (TOML schema) + Config (runtime), Translate(), extend logic
├── allowlist.go     # Allowlist type, match conditions (AND/OR), commit/path/regex/stopword evaluation
├── rule.go          # Rule type, Required type, Validate()
├── utils.go         # joinRegexOr, anyRegexMatch
└── gitleaks.toml    # //go:embed; ~98k lines, generated by cmd/generate/config

Key abstractions

Symbol	File	Description
ViperConfig	config/config.go	TOML-shaped struct used as the Viper unmarshal target. Includes deprecated singular AllowList shim.
Config	config/config.go	Runtime form: compiled regexes, rule map keyed by ID, ordered rule list, deduped keyword set.
Rule	config/rule.go	One detection rule: Regex, Path, Entropy, SecretGroup, Keywords, Tags, Allowlists, RequiredRules, SkipReport.
Required	config/rule.go	One auxiliary rule pointer: RuleID, WithinLines, WithinColumns.
Allowlist	config/allowlist.go	Compiled allowlist: commits map, joined path/regex patterns, Aho-Corasick stopword trie.
AllowlistMatchCondition	config/allowlist.go	OR (default) or AND.
Extend	config/config.go	Path, URL, UseDefault, DisabledRules.
DefaultConfig	config/config.go	The embedded gitleaks.toml as a string (//go:embed gitleaks.toml).
ViperConfig.Translate()	config/config.go	Compiles regexes, builds keyword set, processes extend, validates the result.
Config.GetOrderedRules()	config/config.go	Ordered slice for SARIF reporter stability.
validateMinVersion(min, path)	config/config.go	Warns (doesn't fail) if the running Gitleaks is older than the config requests.

How it works

graph LR
    Toml[gitleaks.toml<br/>file or env var or embed] --> Viper[viper.ReadConfig]
    Viper --> VC[ViperConfig]
    VC --> T[ViperConfig.Translate]
    T --> Cfg[Config]
    Cfg --> Det[detect.Detector]

    T -->|UseDefault| ExtD[extendDefault]
    T -->|extend.path| ExtP[extendPath]
    ExtD --> Cfg
    ExtP --> Cfg

Translation

Translate walks every [[rules]] from the parsed TOML, compiles its Regex and Path regexes through the project's regexp/ package (so the build tag selects the engine), lowercases its keywords into the global keyword set, parses its [[rules.allowlists]] blocks into *Allowlists, and resolves any [[rules.required]] entries.

A few details worth knowing:

• Backwards compatibility for allowlists. [rules.allowlist] (singular) and [allowlist] are still accepted. They become [[rules.allowlists]] and [[allowlists]] respectively before processing, with an error if both old and new forms are present on the same rule. The shim fields are TODO-marked for v9.
• Required rule existence check. After all rules are processed, every RequiredRules[].RuleID is verified against the rule map, returning a config error if a required rule doesn't exist.
• Targeted allowlists. A global [[allowlists]] entry with targetRules = ["...", "..."] is not added to the global allowlist list. It's pushed into the named rules' own Allowlists after the extend pass runs (so even rules pulled in via extend can be targeted).
• extendDepth global. The extend implementation uses a package-level counter (extendDepth) to cap chained extend to depth 2. The author flagged this with // yea I know, globals bad.

Extend

There are two shapes:

• extend.useDefault = true — pulls in the embedded default config, then layers the user's rules on top. New rules are appended; rules with the same ID inherit the default and override per-field (Description, Entropy, SecretGroup, Regex, Path); tags, keywords, and allowlists are concatenated.
• extend.path = "..." — same logic, but reads from a path. Recursion limit: 2 levels.

extend.useDefault and extend.path are mutually exclusive; setting both is a config error.

Allowlist semantics

config/allowlist.go defines four kinds of checks:

| Check | Method | Notes | | --------- | ------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------ | | Commits | CommitAllowed | Case-insensitive map lookup | | Paths | PathAllowed | Joined (... | ...) regex when many paths; falls back to per-pattern match | | Regex | RegexAllowed | Joined regex; tested against secret, match, or line per RegexTarget | | Stopwords | ContainsStopWord | Aho-Corasick trie; targets the extracted secret (always) |

For MatchCondition == AND, all configured checks must pass. For OR (default), any one check is enough. An empty allowlist is a config error (Validate returns "must contain at least one check…").

Default config

config/gitleaks.toml is embedded into the binary via //go:embed gitleaks.toml and exposed as config.DefaultConfig. It is generated offline by cmd/generate/config/main.go, which assembles per-provider rule files from cmd/generate/config/rules/. Editing gitleaks.toml directly will be overwritten by the next go generate — always change the rule source instead. See how to contribute → adding a rule.

Integration points

• detect/ consumes Config via Detector.Config. The detector reads Rules, Allowlists, Keywords, and OrderedRules.
• cmd/ loads via initConfig (resolves the file path) and calls Config(cmd) (which is viper.Unmarshal + Translate).
• report/sarif.go uses Config.GetOrderedRules() so the SARIF tool driver lists rules in a stable order.
• regexp/ is the only regex compiler this package uses (regexp.MustCompile).
• version/ is consulted by validateMinVersion to compare the running version against minVersion.

Entry points for modification

• Adding a config field: extend ViperConfig (or a nested struct), translate it into Config/Rule/Allowlist, validate it, and update cmd/generate/config/rules/config.tmpl if it needs to render in the embedded default. Add coverage to config/config_test.go.
• Adding an allowlist criterion: extend Allowlist, update Validate and the four check methods, and update checkCommitOrPathAllowed / checkFindingAllowed in detect/detect.go so they know to consult the new field.
• Renaming a TOML key with backwards compatibility: follow the pattern of AllowList → Allowlists. Keep the old struct field as a Deprecated: shim that gets folded into the new slice during Translate.
• Bumping the embed: never edit config/gitleaks.toml directly. Edit the rule sources, then run make config/gitleaks.toml.