Glossary

Project-specific terms used throughout the codebase and this wiki.

Allowlist

A set of conditions (commits, paths, regexes, stopwords) that suppress a finding. Allowlists exist at two scopes: global (top-level [[allowlists]] in the config) and rule-level ([[rules.allowlists]]). Defined in config/allowlist.go as the Allowlist struct. See features/allowlists.

In v8.21.0 the singular [rules.allowlist] was renamed to [[rules.allowlists]]; in v8.25.0 the same happened for the global [allowlist] → [[allowlists]]. The old names are still accepted for backwards compatibility.

Aho-Corasick prefilter

A multi-string matcher built from every keyword in every rule, used to skip running a rule's regex when none of its keywords appear in the fragment. Implemented with BobuSumisu/aho-corasick. See prefilter in detect/detect.go.

Auxiliary / required rule

The "second part" of a composite rule. When a primary rule has [[rules.required]] entries, each referenced rule is an auxiliary rule whose match must occur within withinLines / withinColumns of the primary match. Findings from auxiliary rules are attached to the primary Finding as RequiredFindings (report/finding.go).

Baseline

A previously generated JSON report passed via --baseline-path. Findings present in the baseline are filtered out so only new leaks are reported. Loaded by LoadBaseline in detect/baseline.go.

Composite rule

A rule that requires one or more auxiliary findings to be present in the same fragment (or within a configured proximity) before the primary finding is reported. Introduced in v8.28.0. Implemented by processRequiredRules in detect/detect.go. See features/composite-rules.

Decoder

Component that recognizes encoded substrings (base64, hex, percent) within a fragment, decodes them, and replaces them in place so rules can match the decoded value. Lives in detect/codec/. The recursion limit is --max-decode-depth (default 5). See features/decoding.

Detector

The struct that orchestrates a scan. Holds the compiled Config, the keyword prefilter, the concurrency semaphore, and accumulates findings. Defined in detect/detect.go.

Encoded segment

The metadata attached to a region of decoded text so that line/column information from the decoded copy can be mapped back to the original encoded location. Defined in detect/codec/segment.go.

Entropy

Shannon entropy of the captured secret string, computed in shannonEntropy (detect/utils.go). Used both as a per-rule threshold (entropy = 3.5) and for diagnostic output. Higher entropy ≈ more random ≈ more likely to be a real secret.

Finding

The output of a successful match. Contains rule ID, file, line/column range, the matched text, the captured secret, commit metadata, and a fingerprint. Defined in report/finding.go.

Fingerprint

A stable identifier for a finding, used by .gitleaksignore and baselines. Format:

• Without commit: file:rule-id:start-line
• With commit: commit:file:rule-id:start-line

Computed in Detector.AddFinding (detect/detect.go).

Fragment

A chunk of content fed to the detector. Carries the raw bytes/string, the file path, optional commit metadata, and the starting line number. Defined in sources/fragment.go.

gitleaks:allow

An inline comment marker. If a finding's matched line contains this string, the finding is suppressed. Disabled by --ignore-gitleaks-allow. The constant lives in detect/detect.go as gitleaksAllowSignature.

.gitleaksignore

A newline-delimited file of fingerprints to ignore. Loaded by Detector.AddGitleaksIgnore. The repo's own .gitleaksignore is huge (~944 lines) because most testdata files are intentional secrets used by rule unit tests.

Keyword

A string used as a pre-regex filter. A rule with non-empty Keywords will only run its regex if at least one keyword appears in the fragment (case-insensitive). Defined per-rule in config.Rule.

Path-only rule

A rule whose path regex is set but whose regex is not. It fires whenever a file path matches, with no content inspection. Used for sensitive filenames (e.g., .pem, .env).

Reporter

A report.Reporter implementation that writes the slice of findings to an io.Writer in a specific format. The five built-ins are JSON, CSV, JUnit, SARIF, and template. See report/.

Rule

The fundamental unit of detection. Combines a regex, optional path regex, optional entropy threshold, optional secret-group index, keywords, tags, and allowlists. Defined as config.Rule in config/rule.go.

SCM platform

Used to render finding Link URLs that point back to the offending commit on the hosting platform. Supports GitHub, GitLab, Azure DevOps, Gitea, and Bitbucket. Defined in cmd/scm/scm.go; URL construction in createScmLink (detect/utils.go).

Secret group

The capture-group index from which the actual secret is extracted (when the regex captures more than the secret itself). Configured per rule via secretGroup. If unset, the first non-empty capture group is used. See detectRule in detect/detect.go.

Source

A producer of fragments. Implementations: sources.Git, sources.Files, sources.File. Interface in sources/source.go.

Stopword

A substring that, if found inside an extracted secret, suppresses the finding. Used in allowlists. Examples: client, endpoint, example. Matched via Aho-Corasick in config/allowlist.go.