Secret scanning

Secret scanning inspects each file's content for likely credentials before output. See the how-to for the task-oriented walk through; this page is the exhaustive surface.

Flags

Flag	Values	Effect
`--secret-scan`	`off`, `warn`, `redact`, `block`	What to do on a finding (default `warn`)
`--secret-scan-allow <FRAGMENT>`	path substring, repeatable	Skip files whose path contains the fragment

Policies

Policy	Content	Findings	Exit
`off`	unchanged	none (no scan)	0
`warn`	unchanged	reported on stderr	0
`redact`	secret → `[REDACTED: <rule>]`	reported on stderr	0
`block`	file dropped	reported in abort message	non-zero if any found

redact runs before token counting, so redaction shrinks the reported token total. Previews in reports show only the first few characters plus a length — the full secret is never printed or logged.

Detection rules

gnaw scans with the gitleaks ruleset (MIT-licensed), vendored into the binary so scanning is offline and reproducible — no network calls, no runtime download. Each rule is a regex plus, for most, a per-rule Shannon-entropy floor: a match below the floor (a low-entropy documentation example, say) is rejected, which is what keeps placeholder keys out of the report.

The ruleset is large — a few hundred rules — and covers the credential shapes you'd expect: cloud providers (AWS, GCP, Azure), source forges (GitHub, GitLab, Bitbucket), messaging and payments (Slack, Stripe, Twilio, SendGrid), AI vendors (OpenAI, Anthropic), package registries, PEM private-key blocks, JWTs, and a family of generic high-entropy assignment rules for key/secret/token/ password-named fields. Because it's the upstream gitleaks ruleset, any shape gitleaks detects, gnaw detects.

A rule fires only when its keyword appears in the file (a fast prefilter), then the regex and entropy gate confirm the match — so a file with no candidate keywords is skipped cheaply, and the full ruleset only runs against files that could plausibly contain a secret.

An allowlist suppresses known false positives — for example AWS's AKIAIOSFODNN7EXAMPLE documentation key — so those won't be reported or redacted. Rule-level allowlists from the gitleaks ruleset (stopwords like EXAMPLE/example, and per-rule path exceptions) are honored as well.

Path allowlist

--secret-scan-allow (and the secret_scan_allow_paths config key) hold substring fragments, not globs — tests/ skips any path containing that segment. When the list is empty, gnaw falls back to a built-in default set:

/tests/   /test/   /fixtures/   /testdata/   /__tests__/   _test.

Setting any fragment replaces the defaults entirely — you then own the full list. Allowlisted files are skipped completely, so a real secret inside one is not detected.

.gnawconfig keys

Key	Type	Default
`secret_scan`	`"off"` / `"warn"` / `"redact"` / `"block"`	`"warn"`
`secret_scan_allow_paths`	array of path-substring strings	built-in test set

secret_scan = "redact"
secret_scan_allow_paths = ["tests/", "fixtures/"]

Resolution order is CLI flag → .gnawconfig → built-in default.