Config Schema Reference

This page is generated from the configuration schema supported by the current Picket config loaders.

Config Selection

Strict Gitleaks-compatible commands use this precedence:

1. --config / -c
2. GITLEAKS_CONFIG
3. GITLEAKS_CONFIG_TOML
4. {target}/.gitleaks.toml
5. embedded Gitleaks-compatible default config

Picket-native commands use this precedence:

1. --config / -c
2. PICKET_CONFIG
3. PICKET_CONFIG_TOML
4. GITLEAKS_CONFIG
5. GITLEAKS_CONFIG_TOML
6. {target}/.gitleaks.toml
7. embedded Picket default config

Top-Level Fields

Top-level fields apply to the whole TOML document.

Field	TOML type	Applies to	Notes
minVersion	string	strict + native	Accepted Gitleaks-compatible version gate. A leading `v` is allowed.

[extend]

The [extend] table controls inheritance from another config or from the embedded default rule set.

Field	TOML type	Applies to	Notes
path	string	strict + native	Loads another local TOML config as the base config.
url	string	strict + native	Accepted for compatibility and ignored by the current loader.
useDefault	bool	strict + native	Extends the embedded Gitleaks-compatible default rule set.
disabledRules	string[]	strict + native	Removes inherited rules by ID before merging local rules.

[[rules]]

Each [[rules]] table defines one scanner rule. Native metadata fields are ignored by older Gitleaks consumers but are used by Picket reports, rule QA, and native rule packs.

Field	TOML type	Applies to	Notes
id	string	strict + native	Stable rule identifier. Required.
description	string	strict + native	Human-readable rule description.
regex	string	strict + native	Rule regex pattern.
path	string	strict + native	Path regex pattern.
secretGroup	integer	strict + native	Capture group containing the secret. `0` keeps Gitleaks-compatible automatic behavior.
entropy	number	strict + native	Minimum Shannon entropy threshold. The comparison is strict `>`.
randomnessThreshold	number	native	Minimum deterministic randomness score from `0.0` through `1.0`. Zero disables score filtering.
detector	string	native	Stable built-in structured detector name. The regex and keywords remain the candidate prefilter.
keywords	string[]	strict + native	Literal prefilter terms for the rule.
tags	string[]	strict + native	Rule tags copied into findings and reports.
skipReport	bool	strict + native	Runs the rule but omits matching findings from reports.
severity	string	native metadata	Native severity label used in Picket reports and triage.
confidence	string	native metadata	Native confidence label used in Picket reports and triage.
rulePack	string	native metadata	Native rule pack name.
provider	string	native metadata	Provider or ecosystem that owns the rule.
documentationUrl	string	native metadata	Rule documentation URL.
validation	string[]	native metadata	Stable validation template identifiers supported by the rule.
revocation	string[]	native metadata	Stable revocation template identifiers supported by the rule.
deprecated	bool	native metadata	Marks a rule as deprecated while keeping it parseable for compatibility and migration workflows.
examples	string[]	native rule QA	Positive examples that must produce findings during `picket rules check`.
negativeExamples	string[]	native rule QA	Negative examples that must not produce findings during `picket rules check`.

[[allowlists]] and [allowlist]

Global allowlists suppress findings across rules. [[allowlists]] is the current plural form; [allowlist] is the deprecated Gitleaks-compatible singular form. The two forms cannot be mixed in the same config.

Field	TOML type	Applies to	Notes
description	string	strict + native	Human-readable allowlist description.
condition	string	strict + native	`OR`, `||`, `AND`, or `&&`. Empty means `OR`.
commits	string[]	strict + native	Commit SHA values to suppress.
paths	string[]	strict + native	Path regex patterns to suppress.
regexTarget	string	strict + native	`secret`, `match`, or `line`. Empty means `secret`.
regexes	string[]	strict + native	Regex patterns matched against the selected `regexTarget`.
stopwords	string[]	strict + native	Case-insensitive stopwords matched against the secret.
targetRules	string[]	strict + native	Restricts a global allowlist to the listed rule IDs.

[[rules.allowlists]] and [rules.allowlist]

Per-rule allowlists suppress findings only for the preceding [[rules]] entry. [[rules.allowlists]] is the current plural form; [rules.allowlist] is the deprecated Gitleaks-compatible singular form. The two forms cannot be mixed on the same rule.

Field	TOML type	Applies to	Notes
description	string	strict + native	Human-readable allowlist description.
condition	string	strict + native	`OR`, `||`, `AND`, or `&&`. Empty means `OR`.
commits	string[]	strict + native	Commit SHA values to suppress.
paths	string[]	strict + native	Path regex patterns to suppress.
regexTarget	string	strict + native	`secret`, `match`, or `line`. Empty means `secret`.
regexes	string[]	strict + native	Regex patterns matched against the selected `regexTarget`.
stopwords	string[]	strict + native	Case-insensitive stopwords matched against the secret.

[[rules.required]]

Required-rule entries make a rule conditional on another rule being present near the same evidence.

Field	TOML type	Applies to	Notes
id	string	native	Supporting rule ID required by the current rule.
withinLines	integer	native	Maximum line distance from the primary finding.
withinColumns	integer	native	Maximum column distance from the primary finding.

Validation Notes

• id is required for every rule.
• A rule must provide regex, path, or both.
• secretGroup, entropy, withinLines, and withinColumns must be non-negative.
• secretGroup must reference an existing capture group when regex is present.
• extend.path and extend.useDefault cannot both be set.
• extend.url is parsed and ignored in strict compatibility mode because the pinned local Gitleaks behavior does not load URL extends.
• Resolved configs are capped at 10,000 rules.
• targetRules is valid only on global allowlists and every target rule ID must exist after extend resolution.
• Each allowlist must include at least one of commits, paths, regexes, or stopwords.
• Every [[rules.required]] ID must refer to another configured rule.
• Picket-native picket-* rules require both examples and negativeExamples during picket rules check.