Choose a scanning workflow

Start with the source boundary you need. Then choose a detection policy and an execution route. These are separate decisions: a backend changes how KeyHog executes, while a preset changes what detection work it performs.

Choose in 30 seconds

Then make three independent choices:

1. Select the source boundary. This determines which bytes are eligible.
2. Keep the default detection policy unless you accept a documented fast, deep, or precision tradeoff.
3. Use calibrated automatic routing for normal scans. Select an explicit backend only for diagnosis, measurement, or a required-accelerator gate.

If any source reports incomplete coverage, preserve that status with the findings and report. A partial scan is not a clean scan.

Choose the source boundary

Read Your first scan for a local repository, CI secret scanning for direct CI jobs, and Mass repository and cloud scanning for inventory partitioning and coverage.

Choose a scan policy

The three presets are mutually exclusive bases. Compatible explicit options refine them; a precision confidence override may raise but never lower 0.85. Lockdown refuses fast and other completeness-reducing switches, and always runs in process. See Configuration and Hardening.

The default decode cap can hide an encoded credential

Decide this one before you trust a clean result on a repository with large files. A Base64-encoded credential in a chunk above --decode-size-limit is never decoded, so it is never reported. The scan exits 0:

file size    keyhog scan <file>                       with --deep
400K         1 finding, exit 1, status success        1 finding, exit 1
510K         1 finding, exit 1, status success        1 finding, exit 1
520K         0 findings, exit 0, status partial       1 finding, exit 1
600K         0 findings, exit 0, status partial       1 finding, exit 1

The miss is reported, but only in the envelope. coverage_gap_summary carries scanner decode-through declined by --decode-size-limit, and scan_status becomes partial. The exit code stays 0, so a CI gate that branches on the exit code alone passes over a real credential. Gate on the gap reason, not the exit code.

Position in the file governs this, not size. The cap applies per chunk, and a file is read in 1 MiB windows, so only the short tail window of a large file can fall under the 512K limit. An encoded credential in the interior of any file above about 1 MiB is never decoded, at any file size:

2000K file, payload at end of file       1 finding, exit 1
2000K file, payload in the middle        0 findings, exit 0
3000K file, payload at end of file       1 finding, exit 1
3000K file, payload in the middle        0 findings, exit 0

That is also why the size table above looks erratic: planting at the end of the file tests the one position that can still succeed, and the tail window’s size rises and falls as the file grows. Do not infer a safe file size from a fixture that passed, and do not build a regression fixture that plants at the end.

Either preset choice restores it. --deep raises the ceiling as part of its policy, and --decode-size-limit 4M raises it without changing anything else:

keyhog scan . --decode-size-limit 4M

Choose an execution route

Normal scans use auto. An explicit backend is a diagnostic or benchmark contract, not a recommendation for routine routing.

Use keyhog --version --full to inspect compiled capability, keyhog backend --self-test --json to prove backend health, and keyhog backend --autoroute --json to inspect the measured route. These commands answer different questions: discovery, correctness, and comparative selection.

Choose a detector corpus mode

--detectors <DIR> selects a custom detector directory. Choose how it participates in the corpus:

The selected corpus owns matching, validation, entropy, suppression, ML, and declared decode-transform policy. Replace mode does not inherit detector-local policy from the embedded corpus. See Detectors.

What KeyHog can scan

The default and official release builds support the sources below. Reduced source builds can omit feature-gated Git, web, cloud, container, and verifier support. Every enabled source feeds the same compiled detector pipeline.

How KeyHog decides what is real

Precision is the product. A finding survives several independent stages before it reaches your terminal.

How KeyHog stays fast

The generated scaling matrix measures these controls instead of prescribing a fixed thread count. Run make -C benchmarks readme-scaling on the target host. The result binds the binary, detector corpus, exact workload bytes, effective CPU limit, filesystem identity, page-cache policy, raw trials, and process exit status.

What KeyHog emits

How KeyHog protects the secrets it reads

A scanner holds credentials in memory by design, so KeyHog hardens the process that does it.

Every subcommand

The full flag surface for every command is in the CLI reference.

Update or repair with cargo install --locked --force keyhog, then run keyhog doctor to verify the replacement.