# Secrets

> How every Keryn scan finds committed credentials with the gitleaks rule set, keeps the value out of every report, weighs test and documentation files, and how to silence a false positive.

Source: https://keryn.dev/docs/guides/secrets/

## Goal

Find API keys, tokens, private keys and passwords committed to a repository, without the report itself becoming a place where the secret leaks.

> **Caution: Release availability**
> The secrets pass runs in every `keryn scan` on main and in the current Keryn Web build. Keryn 0.5.2, the latest installed release, predates it; there, import a gitleaks report with [`keryn import`](https://keryn.dev/docs/guides/import/).

## Before you start

- The Keryn CLI ([install](https://keryn.dev/docs/start/install/)), or [Keryn Web](https://keryn.dev/docs/guides/web-app/).
- Nothing to configure for the default rules: there is no flag to turn the pass on, and none to turn it off. Your own token formats and an existing gitleaks setup are optional; see [your own rules](#your-own-rules-and-an-existing-gitleaks-setup).

## What runs

The secrets engine is a port of gitleaks 8.30.1 (MIT licensed; the licence text ships with Keryn) with its 222 default rules, including entropy checks, keywords, allowlists and decoding. Keryn's changelog records that it returned identical findings to gitleaks on all 6,896 findings of gitleaks' own rule samples. It runs inside the scan, on your machine; nothing is uploaded.

- **The value is never in the report.** It is redacted inside the engine, and only a SHA-256 of it is kept, so a SARIF file or a result JSON does not carry the secret.
- **A line the pattern rules already report is not repeated.**
- **Context sets the weight.** A key in a test, example, template, research or documentation file is kept but reported as a warning, because a real key is still a real key. Anything in vendored code is set aside (counted, not gated).
- **Size.** The engine skips files over 2 MiB; in the CLI the scan's `--max-file-size` (1,000,000 bytes by default) applies first.

## Silence a false positive

Put `gitleaks:allow` at the end of the secret's line. Keryn Web's finding view has a **Copy gitleaks:allow** button. A `nosemgrep` comment does not apply to this engine. From the next release, the secret is still reported as suppressed (with the reason `gitleaks:allow`), and a pull request checked under an enforced policy base ignores the comment ([reference](https://keryn.dev/docs/reference/suppressions/#inline-nosemgrep-and-gitleaksallow)). To record a decision instead of editing the file, see [suppressions](https://keryn.dev/docs/guides/suppressions/).

## Your own rules and an existing gitleaks setup

On main, not in Keryn 0.5.2. A team usually has token formats no public rule describes, and often a gitleaks configuration it already maintains. The scan reads both.

- **A gitleaks TOML config.** Name it with `--secrets-config <file>` on `keryn scan` or `keryn ci`, or with `secrets.config` in `.keryn.yml` (a path relative to that file, never outside its directory). When neither is set, a `.gitleaks.toml` at the scanned root is used. Keryn Web uses a `.gitleaks.toml` at the root of the folder you scan.
- **Keep the defaults.** Start the file with `[extend]` and `useDefault = true`, then add `[[rules]]` tables. Without it only your rules run. `[extend] path` is refused: no second file is read and no URL is fetched.
- **Check it without scanning.** `keryn rules lint <file.toml>` loads the config in the secrets engine and prints the custom rule count. A config that cannot be read, parsed or run as a whole (one rule the engine cannot run is enough) is a usage error, exit 2: a scan never runs quietly without the rules you asked for. Custom regular expressions go through the same time budget and guard as the default ones.
- **`.gitleaksignore`.** A file of that name at the scanned root is read: one gitleaks fingerprint per line, `file:rule:line` (`commit:file:rule:line` for a finding from `--secrets-history`), `#` for comments. A listed finding is still found, then reported as suppressed with the reason `gitleaksignore`, in the same places as `gitleaks:allow`.
- **The report says what was used.** Coverage names the config, the number of custom rules and how many findings the ignore file set aside.
- **Under an enforced policy base** (a pull request checked against the base branch's policy) the ignore file does not suppress, and the default detectors run beside the repository's config, so an allowlist or a disabled rule in it hides nothing. Custom rules still add findings.

```toml
# .gitleaks.toml
[extend]
useDefault = true

[[rules]]
id = "acme-deploy-token"
description = "Acme deploy token"
regex = '''acme_dt_[a-z0-9]{24}'''
keywords = ["acme_dt_"]
```

## What you just proved

A scan finds the credentials the gitleaks rules describe, and its outputs can be shared without leaking them.

## Secrets in git history

By default a scan reads the working tree. A credential that was committed and later deleted is still in the repository's history, and still works until it is revoked. Add `--secrets-history` to `keryn scan` or `keryn ci` to also scan the lines each commit added, for every commit reachable from `HEAD`.

- `--secrets-since <ref|date>` reads only commits after a ref or date; `--secrets-max-commits <n>` caps how many commits are read (default 10,000, newest first).
- A secret that appears in several commits is one finding: the first commit that introduced it, its date and how many commits carry it. One that is gone from the working tree says so, and says it must still be revoked, because removing it from history does not make it safe.
- A secret still in the working tree is reported once, marked as also in history.
- A shallow clone, the commit cap or a missing `git` makes the secrets coverage incomplete and the scan exits 3 (`--allow-incomplete` accepts that). Fetch full history in CI before scanning.
- The report holds the commit, its date and the path, never the secret value.

## Limits

- A secret in a form no default rule and none of your own rules describes is not found.
- Without `--secrets-history` the engine reads the working tree only: a secret removed in a later commit is not reported.
- Only a `.gitleaksignore` at the scanned root is read, and `[extend] path` in a config is refused.
- Keryn does not check whether a found secret is still valid, and does not revoke it.

## Next

- Gate it in the pipeline: [Add Keryn to CI](https://keryn.dev/docs/guides/ci/).
- Third-party packages: [software composition analysis](https://keryn.dev/docs/guides/sca/).
- Files that instruct coding agents: [agent skill and instruction files](https://keryn.dev/docs/guides/agent-skills/).
