Knowledge Base updated: 2026-11-16
Knowledge Base Index
Orientation
Gitleaks is a Go CLI secret scanner. Its highest-level flow is: a user invokes a Cobra command, configuration/rules are loaded, scan sources produce fragments, the detector finds secrets, and reporters render findings.
Main parts:
cmd/and main.go — CLI entrypoint, command wiring, scan/protect/diagnostics/generation commands.config/— rule, allowlist, and default configuration loading.sources/— file, directory, git, and fragment source abstractions.detect/— core detection pipeline, baseline handling, locations, git/file/reader scanning.detect/codec/— encoded-secret decoding support.report/andreport_templates/— finding models and output formats.logging/,regexp/,version/— cross-cutting runtime helpers.
Critical state is local and process-scoped: scan targets come from the filesystem, stdin, git history, or SCM inputs; rules come from config files/default embedded config; findings are emitted to stdout or report files. There is no database, cache, queue, or long-running server state in this repository.
Architecture diagrams
flowchart TD
User[User / CI] --> Main[main.go]
Main --> Cmd[cmd CLI commands]
subgraph CLI[cmd]
Cmd --> ScanCommands[detect/git/directory/stdin/protect]
Cmd --> Generate[cmd/generate]
Cmd --> Diagnostics[diagnostics/version/scm]
end
subgraph Inputs[scan inputs]
Files[filesystem]
Git[git repositories]
Stdin[stdin]
SCM[SCM integrations]
end
ScanCommands --> Config[config rules and allowlists]
ScanCommands --> Sources[sources fragments]
Files --> Sources
Git --> Sources
Stdin --> Sources
SCM --> Sources
Sources --> Detect[detect engine]
Config --> Detect
Codecs[detect/codec decoders] --> Detect
Regex[regexp backend] --> Detect
Detect --> Report[report formats]
Report --> Output[stdout / files / CI reports]
Logging[logging] --> Cmd
Version[version] --> Cmd
flowchart LR
Target[CLI scan target] --> Source[sources.Source]
Source --> Fragment[Fragment content + metadata]
Fragment --> Decoder[detect/codec optional decoding]
Decoder --> Rules[config.Rule matching]
Rules --> Allowlists[allowlist filtering]
Allowlists --> Finding[report.Finding]
Finding --> Baseline[baseline comparison]
Baseline --> Formatter[JSON/CSV/JUnit/SARIF/template]
flowchart TD
Dev[Developer] --> GenerateCmd[cmd/generate]
GenerateCmd --> ConfigGen[generate config/rules]
GenerateCmd --> SecretGen[generate secrets data]
ConfigGen --> ConfigFiles[config assets]
SecretGen --> TestData[test fixtures/data]
ConfigFiles --> RuntimeConfig[config package]
TestData --> Tests[repository tests]
Glossary
- Gitleaks — the CLI/tool implemented by this repo for detecting secrets in source code and git history.
- Rule — a configured secret-detection pattern with metadata and optional allowlist behavior, represented under
config/. - Finding — a detected secret occurrence that can be filtered, baselined, and rendered by
report/. - Fragment — a unit of source content plus metadata passed from
sources/into detection. - Baseline — prior findings used by
detect/to suppress already-known results.
Codebase-wide invariants
- The project is a single Go module rooted at
go.mod, with the executable entrypoint in main.go and first-level packages such ascmd/,config/,detect/,report/, andsources/. - User-facing command code is organized under
cmd/: top-level commands are in cmd/*.go, SCM-specific command support is incmd/scm/**, and developer generation commands are incmd/generate/**. - Core scanning is separated into source production and detection: scan inputs live under
sources/**, while matching, location, baseline, and reader/git/file detection code lives under detect/*.go. - Output formatting is centralized under
report/**, with bundled template assets underreport_templates/**. - Encoded-content handling is isolated from the main detector in
detect/codec/**, rather than being spread through detect/*.go.
Routing table
-
cmd/scm/**-> docs/cli-commands.md -
any change to CLI command flags, command routing, scan command behavior, protect mode, diagnostics, stdin/directory/git command entrypoints, or version command output -> docs/cli-commands.md
-
config/**-> docs/configuration.md -
any change to rule schemas, default config loading, allowlist semantics, or config validation -> docs/configuration.md
-
any change to finding detection, baseline comparison, file/git/reader scanning, location calculation, or detector utilities -> docs/detection-engine.md
-
detect/codec/**-> docs/decoding-codecs.md -
any change to encoded secret decoding, segment handling, or supported encoded text formats -> docs/decoding-codecs.md
-
sources/**-> docs/source-inputs.md -
any change to file, directory, git, or fragment source construction before detection -> docs/source-inputs.md
-
report/**-> docs/reporting.md -
report_templates/**-> docs/reporting.md -
any change to finding serialization, JSON/CSV/JUnit/SARIF/template output, or bundled report templates -> docs/reporting.md
-
logging/**-> docs/runtime-utilities.md -
regexp/**-> docs/runtime-utilities.md -
version/**-> docs/runtime-utilities.md -
any change to logging behavior, regex backend selection, or version metadata -> docs/runtime-utilities.md
-
cmd/generate/**-> docs/generation-tools.md -
any change to generated config/rule assets or generated secret/test data workflows -> docs/generation-tools.md
-
.github/**-> docs/repository-tooling.md -
scripts/**-> docs/repository-tooling.md -
Dockerfile-> docs/repository-tooling.md -
Makefile-> docs/repository-tooling.md -
.gitleaksignore-> docs/repository-tooling.md -
any change to CI, release packaging, Docker packaging, repository hooks, linting, or repository self-scan configuration -> docs/repository-tooling.md