# https://github.com/gitleaks/gitleaks Project Manual Generated at: 2026-06-19 06:52:22 UTC ## Table of Contents - [Overview, Installation, and CLI Commands](#page-1) - [Configuration, Rules, and Allowlists](#page-2) - [Scanning Modes, Sources, and Detection Engine](#page-3) - [Reporting, Findings, and Output Formats](#page-4) ## Overview, Installation, and CLI Commands ### Related Pages Related topics: [Configuration, Rules, and Allowlists](#page-2), [Scanning Modes, Sources, and Detection Engine](#page-3)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/gitleaks/gitleaks/blob/main/README.md) - [main.go](https://github.com/gitleaks/gitleaks/blob/main/main.go) - [cmd/root.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/root.go) - [cmd/git.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/git.go) - [cmd/directory.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/directory.go) - [cmd/stdin.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/stdin.go) - [report_templates/README.md](https://github.com/gitleaks/gitleaks/blob/main/report_templates/README.md) - [cmd/generate/config/utils/generate.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/utils/generate.go) - [cmd/generate/config/utils/validate.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/utils/validate.go)
# Overview, Installation, and CLI Commands ## Purpose and Scope Gitleaks is a command-line tool for **detecting secrets** such as passwords, API keys, and tokens in git repositories, files, directories, and `stdin` streams. It is implemented in Go and is distributed as a single binary, a Docker image, a Homebrew formula, and a pre-commit hook. The project's stated purpose is summarized in [README.md](https://github.com/gitleaks/gitleaks/blob/main/README.md), which describes it as "a tool for detecting secrets like passwords, API keys, and tokens in git repos, files, and whatever else you wanna throw at it via stdin." The repository is organized around a small, focused feature set. According to the project README, "Gitleaks is feature complete. I'm not merging new features into Gitleaks. Future releases will be security patches only," with the maintainer's focus shifting to a successor project. This means the wiki documentation reflects a stable, finalized surface area rather than a rapidly evolving one. The program is invoked from a single entry point at [main.go](https://github.com/gitleaks/gitleaks/blob/main/main.go), which delegates to the command tree defined under [cmd/](https://github.com/gitleaks/gitleaks/blob/main/cmd). From there, [cmd/root.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/root.go) sets up global flags and shared state, while individual scan modes live in their own files. ## High-Level Architecture ```mermaid flowchart LR A[main.go] --> B[cmd/root.go
global flags & config] B --> C[cmd/git.go
git log -p scanning] B --> D[cmd/directory.go
dir/files scan] B --> E[cmd/stdin.go
stream scan] C --> F[detect package] D --> F E --> F F --> G[config/gitleaks.toml
rules + extend] F --> H[Reporters
json/csv/junit/sarif/template] ``` The CLI is split by scan source: each subcommand produces a stream of fragments (diff hunks, file contents, or stdin lines) that are fed into the shared `detect` engine, which in turn applies a rule set and emits findings to one of the supported report formats. ## Installation The README documents several installation paths so that users on macOS, Linux, and CI environments can adopt gitleaks without compiling it themselves: | Method | Command / Source | | --- | --- | | Homebrew (macOS) | `brew install gitleaks` | | Docker | `docker pull zricethezav/gitleaks:latest` | | GitHub Releases | Pre-built binaries in the [releases page](https://github.com/gitleaks/gitleaks/releases) | | Pre-commit hook | Configured via [Gitleaks-Action](https://github.com/gitleaks/gitleaks-action) or local `.pre-commit-config.yaml` | Source: [README.md](https://github.com/gitleaks/gitleaks/blob/main/README.md). The release artifacts and Docker tags are produced by the project's GoReleaser configuration. ## CLI Commands and Scan Modes Since v8.19.0, the older `detect` and `protect` subcommands were deprecated and hidden from the help menu; users are directed to a migration gist for translating old invocations. Source: [README.md](https://github.com/gitleaks/gitleaks/blob/main/README.md). The current surface exposes three primary scan modes, all of which share the same flag set and exit code behavior. ### `git` — Local Repository Scanning The `git` command is implemented in [cmd/git.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/git.go) and uses `git log -p` under the hood to inspect patches. The exact `git log` arguments are forwarded from the `--log-opts` flag, which makes features like commit ranges, branch filters, and `--all` available without code changes. The README gives the canonical example: ``` gitleaks git -v --log-opts="--all commitA..commitB" path_to_repo ``` If no positional path is supplied, gitleaks scans the current working directory as a git repository. Source: [README.md](https://github.com/gitleaks/gitleaks/blob/main/README.md). Community issue #1007 ("FTL error='flag accessed but not defined: log-opts'") demonstrated the importance of this flag being available in pre-commit hook versions, where missing plumbing caused scan failures in upgraded releases. ### `dir` — Directory and File Scanning The `dir` command (with aliases `files` and `directory`) is implemented in [cmd/directory.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/directory.go) and walks a target path looking at file contents directly, without consulting git history. This is the appropriate mode for scanning tarballs, vendored code, or non-git working copies. It supports `--max-target-megabytes` to skip oversized files and can recursively scan archives when `--max-archive-depth` is greater than zero. ### `stdin` — Stream Scanning `gitleaks stdin` reads a blob of text from standard input and runs the detector against it. This is useful for piping snippets, log files, or pre-commit hook payloads into gitleaks. Source: [README.md](https://github.com/gitleaks/gitleaks/blob/main/README.md). ## Global Flags, Output, and Exit Codes Beyond the scan-mode subcommands, [cmd/root.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/root.go) wires up the global flags listed in the README. The most commonly used ones include: - `--config` — path to a TOML rule file (defaults to the embedded configuration). - `--report-format` and `--report-path` — emit findings as `json`, `csv`, `junit`, `sarif`, or a custom Go `text/template`. - `--report-template` — used together with `--report-format=template` to render findings into a Go template, optionally leveraging the `Masterminds/sprig` library. Source: [report_templates/README.md](https://github.com/gitleaks/gitleaks/blob/main/report_templates/README.md). - `--redact` — redacts secrets from logs and stdout (0–100 percent). - `--max-decode-depth` — enables recursive decoding of percent, hex, and base64 blobs. Source: [README.md](https://github.com/gitleaks/gitleaks/blob/main/README.md). - `--log-level` and `--verbose` — control diagnostic verbosity. Exit codes are fixed: `0` for a clean scan, `1` when leaks or errors are encountered, and `126` for an unknown flag. This contract is convenient for CI gating, but it also explains why pre-commit hooks configured to treat any non-zero exit as a hard failure will block a commit on the first finding. Source: [README.md](https://github.com/gitleaks/gitleaks/blob/main/README.md). ## Configuration and Rule Generation The detector is driven by a TOML configuration. Users can either supply a complete config or extend the embedded default with `[extend]` blocks. Community issue #741 ("Ability to merge / extend / append the default config") reflects a recurring user need to override a few rules from the default set without copying the whole file; the `useDefault = true` and `path = "common_config.toml"` options in `[extend]` address this by inheriting rules from the built-in config (or another file) while letting local rules override by ID. Source: [README.md](https://github.com/gitleaks/gitleaks/blob/main/README.md). The repository also ships rule-generation helpers in [cmd/generate/config/utils/generate.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/utils/generate.go), which build the regex fragments used in the default config. The header comment explicitly warns: "These functions are used to generate Gitleaks's default config. You are free to use these in your own project, HOWEVER, no API stability is guaranteed." Companion tests in [cmd/generate/config/utils/generate_test.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/utils/generate_test.go) document the expected behavior of these helpers. Generated rules are then sanity-checked by [cmd/generate/config/utils/validate.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/utils/validate.go), which constructs a single-rule detector and verifies that known true positives match while known false positives do not. ## See Also - Configuration and Rules (deep dive into `[extend]`, `[[rules]]`, and allowlists) - Reporting Formats (JSON, SARIF, JUnit, and custom templates) - Pre-commit and CI Integration (hooks, Gitleaks-Action, and `.gitleaksignore`) - Issue #741: extending the default config - Issue #1007: missing `--log-opts` flag in pre-commit hook builds - Issue #1870: wildcard support in `.gitleaksignore` --- ## Configuration, Rules, and Allowlists ### Related Pages Related topics: [Overview, Installation, and CLI Commands](#page-1), [Scanning Modes, Sources, and Detection Engine](#page-3), [Reporting, Findings, and Output Formats](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/gitleaks/gitleaks/blob/main/README.md) - [config/config.go](https://github.com/gitleaks/gitleaks/blob/main/config/config.go) - [config/rule.go](https://github.com/gitleaks/gitleaks/blob/main/config/rule.go) - [config/allowlist.go](https://github.com/gitleaks/gitleaks/blob/main/config/allowlist.go) - [config/gitleaks.toml](https://github.com/gitleaks/gitleaks/blob/main/config/gitleaks.toml) - [cmd/generate/config/base/config.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/base/config.go) - [cmd/generate/config/utils/validate.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/utils/validate.go) - [cmd/generate/config/utils/generate.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/utils/generate.go) - [cmd/generate/config/utils/generate_test.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/utils/generate_test.go) - [report_templates/README.md](https://github.com/gitleaks/gitleaks/blob/main/report_templates/README.md)
# Configuration, Rules, and Allowlists Gitleaks ships with a TOML-based configuration system that governs how secrets are detected, suppressed, and reported. The configuration model has three principal building blocks: a top-level `[extend]` section for inheriting and overriding defaults, a `[[rules]]` array that defines detection patterns, and one or more `[[allowlists]]` tables that suppress findings. This page walks through the structure of these blocks, the runtime semantics the engine implements for each, and the mechanisms that have evolved to address common pain points reported by the community. ## Configuration Loading and Extension A Gitleaks configuration file can either stand alone or extend an existing one. The `[extend]` block controls this behavior. The `useDefault` flag merges the configuration that is compiled into the binary at build time (the latest version is published at `config/gitleaks.toml`), while the `path` key lets the file inherit from another on-disk TOML. When extending, extended rules take precedence over defaults, and allowlist arrays are appended (possibly with duplicates) rather than replaced. The `disabledRules` array under `[extend]` is the supported way to drop inherited rules without copying the entire file. Source: [README.md](https://github.com/gitleaks/gitleaks/blob/main/README.md) (Configuration section). This mechanism directly answers community request [#741](https://github.com/gitleaks/gitleaks/issues/741) ("Ability to merge / extend / append the default config"), which asked for the ability to override a few settings without forking the entire rule set. ```toml [extend] useDefault = true disabledRules = ["generic-api-key"] ``` ## Rule Structure Each detection rule is an entry in the `[[rules]]` array. The schema is defined in [config/rule.go](https://github.com/gitleaks/gitleaks/blob/main/config/rule.go) and instantiated in the default bundle at [config/gitleaks.toml](https://github.com/gitleaks/gitleaks/blob/main/config/gitleaks.toml). The most important fields are: | Field | Purpose | |---|---| | `id` | Stable, unique identifier used in reports, allowlists, and `.gitleaksignore` | | `description` | Human-readable explanation shown in verbose output | | `regex` | Go regular expression (no lookaheads) that locates the secret | | `secretGroup` | Capture group whose content is treated as the extracted secret | | `entropy` | Minimum Shannon entropy the extracted secret must reach | | `keywords` | Pre-filter substrings that short-circuit detection when absent | | `path` | Optional regex that gates detection to certain file paths | | `required` | Array of auxiliary rules for composite detection (see below) | The default configuration is generated by helpers in [cmd/generate/config/base/config.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/base/config.go) and [cmd/generate/config/utils/generate.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/utils/generate.go), which assemble semantically generic patterns such as `GenerateSemiGenericRegex` from identifiers, secret fragments, and case-sensitivity flags. These utilities are exposed to contributors but carry no API stability guarantee, as noted at the top of [cmd/generate/config/utils/validate.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/utils/validate.go). False-positive tuning is a recurring concern: issue [#1302](https://github.com/gitleaks/gitleaks/issues/1302) reports that the `hashicorp-tf-password` rule "seems to be too wide" and generates noise that other entropy-aware rules would normally suppress. Tuning this kind of behavior is done by raising the `entropy` threshold, adding `keywords`, or attaching a rule-scoped `[[rules.allowlists]]` block. ## Composite (Required) Rules Version 8.28.0 introduced composite rules, where a primary rule only fires if one or more auxiliary rules also match within a configurable proximity. A `[[rules.required]]` entry on a primary rule specifies the auxiliary `id` and optionally `withinLines` and `withinColumns` constraints that bound the search area. Omitting both proximity values performs fragment-level matching — the auxiliary may appear anywhere in the same chunk of content Gitleaks is scanning. ```mermaid flowchart LR A[Primary rule match
in fragment] --> B{Auxiliary
match within
proximity?} B -- yes --> C[Emit finding] B -- no --> D[Suppress] ``` The proximity field model is explained in the README. The README itself notes that composite rules are most useful for non-addition (filesystem/directory) scans, because the git-scan path only inspects additions in history. ## Allowlists and Inline Suppression The `[[allowlists]]` table — renamed from `[allowlist]` in v8.25.0 — is the primary mechanism for suppressing findings without changing rules. Each allowlist can scope itself with `targetRules` (an array of rule IDs), match against a finding by `regexTarget` set to `"match"` or `"line"`, exclude whole `commits` or `paths`, and reject secrets that contain any `stopwords` introduced in 8.8.0. Allowlists can be defined globally or nested under a specific rule as `[[rules.allowlists]]`. Source: [config/allowlist.go](https://github.com/gitleaks/gitleaks/blob/main/config/allowlist.go). Two further mechanisms operate outside the TOML file: - **`gitleaks:allow` comments** — appended to a line containing a known test secret; gitleaks will skip that line unless `--ignore-gitleaks-allow` is supplied. - **`.gitleaksignore`** — a root-level file listing finding fingerprints. The fingerprint format `commit:file:rule:line` was introduced in 8.10.0, as documented in the README. Issue [#1870](https://github.com/gitleaks/gitleaks/issues/1870) requests wildcards in `.gitleaksignore`, noting that codegen output shifts line numbers between runs and makes a pure line-anchored ignore list brittle. Until that lands, allowlists with `regexTarget = "line"` against a stable substring of the file content are the recommended workaround. ## Common Pitfalls A few failure modes surface repeatedly in the issue tracker and source code: - **Rule definition order matters for validation.** `Validate` and `ValidateWithPaths` in [cmd/generate/config/utils/validate.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/utils/validate.go) abort generation if a true-positive fixture fails to match or a false-positive fixture does match. Contributing a new default rule requires curated fixtures for both. - **Entropy vs. regex coverage.** The `GenerateSemiGenericRegex` test cases in [cmd/generate/config/utils/generate_test.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/utils/generate_test.go) document which identifier/secret surroundings are intentionally accepted (e.g. `api_key="don't do it!"`) and which are not (e.g. `api_key=[xxx]`); tuning entropy without revisiting the surrounding context is often the cause of complaint #1302. - **Reports are configurable separately.** Custom report formats use Go `text/template` files referenced via `--report-template`, and templates may pull in `sprig` helpers. The starter set lives under [report_templates/README.md](https://github.com/gitleaks/gitleaks/blob/main/report_templates/README.md). ## See Also - [README.md](https://github.com/gitleaks/gitleaks/blob/main/README.md) — installation, exit codes, and full configuration reference - [config/gitleaks.toml](https://github.com/gitleaks/gitleaks/blob/main/config/gitleaks.toml) — the canonical default ruleset - [CONTRIBUTING.md](https://github.com/gitleaks/gitleaks/blob/main/CONTRIBUTING.md) — guidance for proposing new default rules - [Gitleaks blog post on configuration](https://blog.gitleaks.io/stop-leaking-secrets-configuration-2-3-aeed293b1fbf) — advanced configuration walkthrough --- ## Scanning Modes, Sources, and Detection Engine ### Related Pages Related topics: [Overview, Installation, and CLI Commands](#page-1), [Configuration, Rules, and Allowlists](#page-2), [Reporting, Findings, and Output Formats](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/gitleaks/gitleaks/blob/main/README.md) - [detect/detect.go](https://github.com/gitleaks/gitleaks/blob/main/detect/detect.go) - [detect/files.go](https://github.com/gitleaks/gitleaks/blob/main/detect/files.go) - [detect/git.go](https://github.com/gitleaks/gitleaks/blob/main/detect/git.go) - [detect/reader.go](https://github.com/gitleaks/gitleaks/blob/main/detect/reader.go) - [detect/fragment.go](https://github.com/gitleaks/gitleaks/blob/main/detect/fragment.go) - [detect/baseline.go](https://github.com/gitleaks/gitleaks/blob/main/detect/baseline.go) - [cmd/generate/config/utils/validate.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/utils/validate.go) - [cmd/generate/config/utils/generate.go](https://github.com/gitleaks/gitleaks/blob/main/cmd/generate/config/utils/generate.go) - [report_templates/README.md](https://github.com/gitleaks/gitleaks/blob/main/report_templates/README.md)
# Scanning Modes, Sources, and Detection Engine Gitleaks is a secret-detection tool that consumes text from three distinct **scanning sources** and runs that text through a shared **detection engine**. This page explains how the three modes (`git`, `dir`, `stdin`) feed the engine, how the engine produces findings, and how configuration, baselines, decoding, and archive scanning interact with that flow. Source: [README.md:1-1]() ## 1. Scanning Modes (Sources) There are three scanning modes, all exposed as CLI subcommands. In v8.19.0 the legacy `detect` and `protect` commands were deprecated and hidden from `--help`, but the three core commands remain stable. Source: [README.md:1-1]() ### 1.1 Git Mode The `git` command scans local Git repositories. Internally it shells out to `git log -p` to retrieve patches, which means gitleaks primarily evaluates **added** lines. Users can tune which commits are scanned via the `--log-opts` flag, which is forwarded to `git log`. Example: `gitleaks git -v --log-opts="--all commitA..commitB" path_to_repo`. Source: [README.md:1-1]() If no positional target is provided, gitleaks treats the current working directory as a Git repository. The `git` mode is the only mode whose findings include a `Commit` field, a `Date`, an `Author`, and a `Email` because the underlying stream is patch metadata rather than raw file bytes. Source: [detect/git.go:1-1]() ### 1.2 Dir Mode The `dir` command (aliases: `files`, `directory`) walks a directory tree and scans each file as-is. This is the appropriate mode for non-Git content such as CI artifacts, container layers, or uncommitted local code. Source: [README.md:1-1]() ### 1.3 Stdin Mode `stdin` lets a caller pipe content into gitleaks, useful for editor integrations and ad-hoc checks. Any pipeline that produces text on standard input can be scanned without writing to disk first. Source: [detect/reader.go:1-1]() ```mermaid flowchart LR A[User input] --> B{Scan Mode} B -- "git" --> C["git log -p
(patches, additions)"] B -- "dir" --> D["Filesystem walk
(file bytes)"] B -- "stdin" --> E["os.Stdin reader"] C --> F[Fragmenter] D --> F E --> F F --> G[Detection Engine
apply rules + allowlists] G --> H[Findings + Report] ``` ## 2. The Detection Engine All three sources converge on a common pipeline implemented in the `detect` package. ### 2.1 Fragmenter [`detect/fragment.go`](https://github.com/gitleaks/gitleaks/blob/main/detect/fragment.go) breaks a stream into overlapping line-based fragments. Fragmentation exists so that secrets that span line boundaries (e.g., a token split across two lines) are still matched as a unit. Source: [detect/fragment.go:1-1]() ### 2.2 Detector [`detect/detect.go`](https://github.com/gitleaks/gitleaks/blob/main/detect/detect.go) holds the core `Detector` type. It iterates over fragments, performs an optional **keyword pre-filter** (rules declare `keywords` for a quick string compare before running the regex), evaluates each rule's `regex` against the fragment, and applies the rule's `[[rules.allowlists]]` to suppress or transform matches. Source: [detect/detect.go:1-1]() Each finding includes a deterministic `Fingerprint` (added in v8.10.0) that uniquely identifies the secret regardless of line shifts — a property relied on by the ignore mechanism described below. Source: [README.md:1-1]() ### 2.3 Source-Specific Readers - [`detect/git.go`](https://github.com/gitleaks/gitleaks/blob/main/detect/git.go) wraps the `git log -p` invocation and parses the unified diff into per-file fragments. Source: [detect/git.go:1-1]() - [`detect/files.go`](https://github.com/gitleaks/gitleaks/blob/main/detect/files.go) walks the directory and opens each file through the same fragmenter. Source: [detect/files.go:1-1]() - [`detect/reader.go`](https://github.com/gitleaks/gitleaks/blob/main/detect/reader.go) adapts any `io.Reader` (used by `stdin` and by archive extraction) into fragments. Source: [detect/reader.go:1-1]() ### 2.4 Validation The default rule set is generated and tested through `cmd/generate/config/utils/validate.go`, which asserts that a known set of **true positives** matches and that known **false positives** does not. This is how the maintainers keep regex drift in check. Source: [cmd/generate/config/utils/validate.go:1-1]() ## 3. Baselines, Ignoring, and Output ### 3.1 Baseline Files [`detect/baseline.go`](https://github.com/gitleaks/gitleaks/blob/main/detect/baseline.go) implements `--baseline-path`. A baseline is a previous report (typically JSON). On each new run, gitleaks diffs the current findings against the baseline and only emits **new** findings, so historical leaks do not fail a fresh scan. Source: [detect/baseline.go:1-1]() ### 3.2 Inline and File-Based Ignoring Two ignore mechanisms exist and are intentionally complementary: - `gitleaks:allow` — a comment placed on the same line as a known test secret, which the engine respects unless `--ignore-gitleaks-allow` is set. Source: [README.md:1-1]() - `.gitleaksignore` — a file at the repo root containing `Fingerprint` values, one per suppressed finding. Community request #1870 has highlighted the desire for wildcard support in this file. Source: [README.md:1-1]() ### 3.3 Reports The engine writes findings to stdout, a report file, or both. Built-in formats are `json`, `csv`, `junit`, and `sarif`. A `template` format is also available, which renders findings through a Go `text/template` file passed via `--report-template`. Sprig helper functions are available inside templates. Source: [report_templates/README.md:1-1]() ## 4. Advanced Sources: Decoding and Archives The detection engine is not limited to raw bytes. Two optional transforms can introduce additional source content into the same fragment pipeline: | Flag | Effect | Default | Source | | --- | --- | --- | --- | | `--max-decode-depth N` | Recursively decodes percent, hex (≥32 chars), and base64 (≥16 chars) segments | `0` (off) | [README.md:1-1]() | | `--max-archive-depth N` | Extracts and scans nested archives (zip, tar, tar.gz, zst) | `0` (off) | [README.md:1-1]() | When a finding is produced from a decoded or archive-extracted fragment, the engine annotates it with tags such as `decoded:base64` or `decode-depth:2`, and for archives the inner file path is appended with `!` separators, e.g. `nested.tar.gz!files/.env.prod`. Source: [README.md:1-1]() ## 5. Configuration Loading Precedence The configuration consumed by the engine follows a strict precedence, with no merging of TOML fragments beyond what an individual config file declares. Source: [README.md:1-1]() | # | Source | Example | | --- | --- | --- | | 1 | `--config` / `-c` flag | `gitleaks git --config /home/dev/customgitleaks.toml .` | | 2 | `GITLEAKS_CONFIG` environment variable (file path) | `export GITLEAKS_CONFIG="/home/dev/customgitleaks.toml"` | | 3 | `GITLEAKS_CONFIG_TOML` environment variable (inline TOML content) | `export GITLEAKS_CONFIG_TOML=$(cat customgitleaks.toml)` | | 4 | `.gitleaks.toml` file in the target path | `gitleaks git .` | | 5 | Built-in default | (no flag, no env, no local file) | Community issue #741 requests a richer *extend* model that does not require copying the entire default config. Today, extending is limited to the `[extend]` block (either `useDefault = true` or `path = "..."`), which merges with a depth of 2. Source: [README.md:1-1]() ## 6. Common Failure Modes - **`flag accessed but not defined: log-opts`** (issue #1007) — caused by passing flags through a wrapper that strips them, or by using an older config schema with a newer binary. Re-check the precedence table above. Source: [README.md:1-1]() - **High false-positive rate on a specific rule** (e.g., `hashicorp-tf-password` in issue #1302) — address with a targeted `[[rules.allowlists]]` rather than disabling the rule globally. Source: [README.md:1-1]() - **Line-number churn breaking ignore files** — use `Fingerprint` values in `.gitleaksignore` rather than line/column coordinates. Source: [README.md:1-1]() ## See Also - Configuration Reference — full schema for `[extend]`, `[rules]`, and `[[rules.allowlists]]`. Source: [README.md:1-1]() - Report Templates — Sprig-enabled Go templates for custom output. Source: [report_templates/README.md:1-1]() - Pre-commit and CI Integration — running gitleaks as a hook. Source: [README.md:1-1]() --- ## Reporting, Findings, and Output Formats ### Related Pages Related topics: [Overview, Installation, and CLI Commands](#page-1), [Scanning Modes, Sources, and Detection Engine](#page-3)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/gitleaks/gitleaks/blob/main/README.md) - [report_templates/README.md](https://github.com/gitleaks/gitleaks/blob/main/report_templates/README.md) - [testdata/expected/report/json_simple.json](https://github.com/gitleaks/gitleaks/blob/main/testdata/expected/report/json_simple.json) - [testdata/expected/report/csv_simple.csv](https://github.com/gitleaks/gitleaks/blob/main/testdata/expected/report/csv_simple.csv) - [testdata/expected/report/junit_simple.xml](https://github.com/gitleaks/gitleaks/blob/main/testdata/expected/report/junit_simple.xml) - [testdata/expected/report/sarif_simple.sarif](https://github.com/gitleaks/gitleaks/blob/main/testdata/expected/report/sarif_simple.sarif) - [.gitleaksignore](https://github.com/gitleaks/gitleaks/blob/main/.gitleaksignore)
# Reporting, Findings, and Output Formats Gitleaks is a secret-detection tool that scans git repositories, directories, archives, and stdin input. Once a scan finishes, its reporting layer is responsible for materializing the **findings** — the individual matches the detector produced — into formats that humans and downstream tooling can consume. This page documents that layer: the structure of a finding, the built-in output formats, the custom template engine, the suppression mechanisms (`.gitleaksignore` and `gitleaks:allow`), and the exit-code contract used by CI pipelines. ## The Finding Data Model Every leak gitleaks surfaces is represented as a `Finding` struct. The same struct is used regardless of the source being scanned (git, dir, stdin) and is what every report format renders. The fields exposed in the verbose console output — `Description`, `StartLine`, `EndLine`, `StartColumn`, `EndColumn`, `Line`, `Match`, `Secret`, `File`, `SymlinkFile` (when scanning archives), `Commit`, `Author`, `Email`, `Date`, `Fingerprint`, and `Link` — are the canonical set of attributes available to report writers. Source: [README.md:100-118](). A `Fingerprint` was added in v8.10.0 and uniquely identifies a secret; it is the recommended handle for suppression via `.gitleaksignore`. Source: [README.md:182-188](). For archive scans, the `File` field is rendered with `!` separators that describe the path *inside* the archive tree, and a `Link` field is produced pointing to the commit on the hosting provider. Source: [README.md:228-240](). For decoded findings (when `--max-decode-depth` is enabled), the `Match` and `Secret` carry the decoded value, the location points at the encoded text bounds, and two extra tags are attached: `decoded:` and `decode-depth:`. Source: [README.md:190-210](). ## Built-in Report Formats Gitleaks ships with five report formats selected via `--report-format` and written to the path in `--report-path`: | Format | Purpose | Reference Output | |--------|---------|------------------| | `json` | Machine-readable, used by baselines and integrations | [json_simple.json](https://github.com/gitleaks/gitleaks/blob/main/testdata/expected/report/json_simple.json) | | `csv` | Spreadsheet ingestion | [csv_simple.csv](https://github.com/gitleaks/gitleaks/blob/main/testdata/expected/report/csv_simple.csv) | | `junit` | CI test reporters | [junit_simple.xml](https://github.com/gitleaks/gitleaks/blob/main/testdata/expected/report/junit_simple.xml) | | `sarif` | Static Analysis Results Interchange Format for security dashboards | [sarif_simple.sarif](https://github.com/gitleaks/gitleaks/blob/main/testdata/expected/report/sarif_simple.sarif) | | `template` | User-defined Go `text/template` output | [report_templates/](https://github.com/gitleaks/gitleaks/blob/main/report_templates/) | The SARIF output is the format most often used to feed findings into code-scanning dashboards, while JSON is the format gitleaks itself consumes back when you want to establish a baseline. Source: [README.md:245-252](). A typical invocation that produces a JSON report and a SARIF report looks like: ```bash gitleaks git --report-path findings.json --report-format json gitleaks dir --report-path findings.sarif --report-format sarif ./src ``` ## Custom Report Templates When the built-in formats do not fit, gitleaks can render findings through a Go [`text/template`](https://www.pkg.go.dev/text/template) file. Extended functions from [`Masterminds/sprig`](https://masterminds.github.io/sprig/) are available, which adds helpers such as `quote`, `sub`, `len`, and string-manipulation functions. Source: [README.md:252-275](). The template is enabled with `--report-template=PATH`, which implicitly selects `--report-format=template`. The repository ships several ready-to-use templates in the `report_templates/` directory — `basic.tmpl` (light and dark), `windows98.tmpl`, and `windowsxp.tmpl` — that produce a self-contained HTML file you can open in a browser. Source: [report_templates/README.md:1-18](). A minimal custom template might look like: ```gotemplate {{ range . }} [{{ .RuleID }}] {{ .File }}:{{ .StartLine }} - {{ quote .Secret }} {{ end }} ``` Community feedback (issue #1870) about `.gitleaksignore` wildcards and the broader need for flexible CI integrations underscores why the templating layer matters: organizations want to reshape findings into formats their existing tooling understands. Source: [README.md:170-188](). ## Suppression, Redaction, and Exit Codes Two complementary mechanisms control how findings are reported: - **`gitleaks:allow` comments** — appended to a line that intentionally contains a test secret. Gitleaks suppresses that specific match. Disable with `--ignore-gitleaks-allow` if you want the auditor to see everything. Source: [README.md:160-168](). - **`.gitleaksignore`** — a file at the repo root listing `Fingerprint` values (one per line) for findings to skip. The format is currently experimental and subject to change. Source: [README.md:170-188](). The `--redact` flag controls how much of a secret is shown in logs and stdout; the default is 100% (fully redacted) and the value can be a percentage to leave a partial hint. Source: [README.md:308-310](). Exit codes are part of the reporting contract used by CI systems. The defaults are: `0` for a clean run, `1` for leaks detected or an error, and `126` for an unknown flag. The exit code can be overridden with `--exit-code`. Source: [README.md:65-71](). ```mermaid flowchart LR A[Scan: git / dir / stdin] --> B[Detector produces Findings] B --> C{Suppression?} C -- gitleaks:allow --> X[Skip] C -- .gitleaksignore match --> X C -- no match --> D[Redact via --redact] D --> E[Renderer] E --> F[json / csv / junit / sarif] E --> G[Go text/template] E --> H[Verbose console] F --> I[--exit-code] G --> I H --> I ``` ## Common Failure Modes Several community-reported issues map directly onto the reporting layer: - **Issue #1007** — `flag accessed but not defined: log-opts` after upgrading. This is a flag-availability mismatch between the v8 CLI and older pre-commit wrappers; it surfaces as a fatal log message and an exit code of 1, so CI runs that key off exit codes will fail. Source: [README.md:65-71](). - **Issue #1302** — `hashicorp-tf-password` producing wide false positives. False positives still flow through the entire reporting pipeline and end up in JSON/SARIF, inflating downstream noise. Suppression via `.gitleaksignore` fingerprints or an allowlist in the rule is the documented mitigation. Source: [README.md:170-188](). - **Issue #1624** — the unrelated `gitleaks.io` organization-license onboarding email bug. It does not affect the open-source binary, but it is mentioned frequently by users who consume gitleaks via the hosted dashboards that *do* consume its SARIF output. When integrating gitleaks into CI, the most robust pattern is to emit SARIF for the dashboard, keep JSON locally as a baseline file, and fail the build only on exit code `1` (or whatever custom code you set). This decouples the reporting layer from the gating decision. ## See Also - [Configuration](configuration.md) — how rules are defined and extended (relevant to issue #741 on extending the default config). - [Detection Engine](detection-engine.md) — how findings are produced before they reach the reporter. - [Pre-commit & CI Integration](pre-commit-and-ci.md) — practical exit-code and baseline workflows. --- --- ## Pitfall Log Project: gitleaks/gitleaks Summary: Found 13 structured pitfall item(s), including 3 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/gitleaks/gitleaks/issues/2165 ## 2. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/gitleaks/gitleaks/issues/2110 ## 3. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: packet_text.keyword_scan | https://github.com/gitleaks/gitleaks ## 4. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: runtime_trace - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Repro command: `docker run -v ${path_to_host_folder_to_scan}:/path zricethezav/gitleaks:latest [COMMAND] [OPTIONS] [SOURCE_PATH] # Docker (ghcr.io) docker pull ghcr.io/gitleaks/gitleaks:latest docker run -v ${path_to_host_folder_to_scan}:/path ghcr.io/gitleaks/gitleaks:latest` - Evidence: identity.distribution | https://github.com/gitleaks/gitleaks ## 5. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/gitleaks/gitleaks ## 6. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/gitleaks/gitleaks ## 7. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/gitleaks/gitleaks ## 8. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/gitleaks/gitleaks ## 9. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/gitleaks/gitleaks/issues/2158 ## 10. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/gitleaks/gitleaks/issues/2164 ## 11. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/gitleaks/gitleaks/issues/2170 ## 12. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/gitleaks/gitleaks ## 13. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/gitleaks/gitleaks