Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Secrets

    View as Markdown

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

    • The Keryn CLI (install), or Keryn Web.
    • 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.

    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.

    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). To record a decision instead of editing the file, see suppressions.

    Your own rules and an existing gitleaks setup

    Section titled “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.
    .gitleaks.toml
    [extend]
    useDefault = true
    [[rules]]
    id = "acme-deploy-token"
    description = "Acme deploy token"
    regex = '''acme_dt_[a-z0-9]{24}'''
    keywords = ["acme_dt_"]

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

    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.
    • 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.