Configuration

Every entry point (scan, scanFiles, scanString, listRules, inspectRuleset) accepts the same grouped ScanOptions object. Keys are namespaced by concern — config, walk, rules, baseline — plus a few truly cross-cutting flags at the root.

Shape

export interface ScanOptions {
    baseline?: string;
    concurrency?: number;

    config?: {
        extendBundled?: boolean;
        heuristics?: {
            lockFile?: boolean;
            notAlphanumericString?: boolean;
            potentialUuid?: boolean;
            sequentialString?: boolean;
        };
        inline?: GitleaksConfig;
        minConfidence?: "low" | "medium" | "high";
        onlyVerified?: boolean;
        path?: string;
        validate?: boolean;
    };

    redact?: boolean;

    rules?: {
        enable?: string[];
        exclude?: string[];
        include?: string[];
    };

    verbose?: boolean;

    walk?: {
        excludeFromFiles?: string[];
        excludePatterns?: string[];
        gitignore?: boolean;
        includeHidden?: boolean;
        maxFileSize?: number;
    };
}

Root-level

config — rule source + validation

Precedence

1. config.inline wins when both inline and path are set.
2. The resulting user config layers on top of the bundled ruleset unless extendBundled: false.
3. Opt-in rule bundles (e.g. tag:preset:weak-passwords) ship disabled-by-default inside every ruleset; rules.include is the only gate.

minConfidence

Every rule may carry an optional confidence field ("low", "medium", "high"). Rules without an explicit label are treated as "low". Setting minConfidence drops rules below the floor:

Every bundled gitleaks rule ships unlabeled, so "medium" or "high" drops the entire stock ruleset. Use this flag against a curated config of your own, or when you opt into a preset that ships labels.

heuristics — post-detection false-positive filters

Four heuristics (ported from detect-secrets) run after rule detection and drop high-confidence placeholders before returning. All four default to on; set the individual key to false when you need the raw match set — typical only when scanning a curated fixture that legitimately contains UUID-shaped or all-dash values.

// Keep UUID-shaped findings when auditing a system that uses UUIDs as API keys.
const findings = await scan([process.cwd()], {
    config: { heuristics: { potentialUuid: false } },
});

The filters are intentionally conservative: every entry has to be wrong in a very specific way before it drops. If you hit a false negative you suspect a heuristic caused, toggle the one you suspect off and compare.

For help detecting secrets that span multiple lines in YAML (where the raw scan never sees the full value), see the complementary transformYamlBlockScalars helper — it's opt-in because it requires reading files in JS rather than through the Rust walker.

validate and onlyVerified

validate turns on live verification — every finding whose rule declares an HTTP validator is checked against the provider's own API after detection. Cost: one HTTP request per finding (per-host concurrency capped at 4, global at 8). Default false, so scans stay offline-safe.

Supported today: Kingfisher-style HTTP validators with StatusMatch / WordMatch response matchers. Other kinds (gRPC, multi-step HTTP, checksum) surface as validation: "skipped" on the finding and pass through unfiltered. Non-HTTP validators (AWS STS, MongoDB, MySQL / Postgres, …) require optional peer-deps — call listRequiredValidators() (or vis secrets --list-validators) to see which the current ruleset references.

onlyVerified: true then filters the emitted set down to findings whose validation === "verified" — useful for CI gating where a suspect match that can't be verified is not a blocker.

Warning: validate: true sends the candidate secret to the provider. Some providers page their security team on failed auth attempts. Only enable on repos you own or have explicit authorisation to test.

walk — filesystem traversal

Only scan() runs the walker. scanFiles() takes a fixed list and bypasses it; there the JS wrapper applies excludePatterns / excludeFromFiles via the ignore npm package so the two code paths behave the same.

rules — id + tag filters

tag:<name> entries expand to every rule carrying that tag at config-load time. An unknown tag throws with a list of known tags — catches typos at the boundary. Common tags: tag:preset:weak-passwords, tag:preset:password-manager.

Pick the right knob:

• "enable the weak-passwords rules alongside my normal scan" → rules.enable: ["tag:preset:weak-passwords"]
• "scan only for password-manager exports" → rules.include: ["tag:preset:password-manager"]
• "keep defaults but mute generic-api-key" → rules.exclude: ["generic-api-key"]

baseline — fingerprint suppression

Set baseline to the path of a JSON array of Finding objects. Any finding whose content-hash fingerprint — SHA-256 over (secret, ruleId, file) truncated to 16 hex chars — already appears in the baseline is suppressed. Because the fingerprint hashes content rather than position, the entry survives line shifts inside the file; it only invalidates when the secret itself, the rule, or the file path changes.

Legacy gitleaks-style baselines using the <file>:<ruleID>:<startLine> form keep suppressing correctly on read, so migrating to the content-hash form can happen at your own pace via vis secrets --update-baseline.

A missing file is treated as an empty baseline; a malformed file is ignored with a stderr warning — scans never fail because of a broken baseline.

Gitleaks-compatible schema extensions

The config shape mirrors gitleaks' TOML schema. A few fields are ours (safe additions):