Truman — secret detection cli and library written in Rust
Fast, extensible secret scanner and Rust library. Scan files and directories for AWS keys, Stripe keys, private keys, high-entropy strings, and 140 detectors in total.
- Adding new detector is ~10 lines impl.: implement one trait, register it, done.
- In library mode, findings are delivered via callback as workers complete. Libraries never wait for the whole scan.
- Discovered
secretslive only in memory for library use; only the SHA1hashed_secretis serialized or printed. - Pretty performant.
use PathBuf;
use ;
let = default_registry_with_config;
let findings = scan_paths_collect;
for f in &findings
Installation
Requirements: Rust 1.70+ (edition 2021), any OS.
# CLI binary `truman` (from crates.io, once published)
# or from source
# or run without installing
As a library, depend only on the facade crate:
[]
= "0.1"
# or from source: truman = { path = "path/to/truman/crates/truman" }
Full library guide (collect vs streaming, custom detectors, filters,
positions, redaction, JSON output): docs/LIBRARY_USAGE.md.
Quick start (CLI)
Pretty output (hash, never plaintext):
src/config.py:42:10-42: Stripe Access Key (StripeDetector) [9d8dd340…]
Exit codes (pre-commit-hook style): 0 = clean, 1 = findings, 2 = usage / I/O error.
Quick start (library)
For simplest possible scan — see
crates/truman/examples/quickstart.rs:
use PathBuf;
use ;
Need results during the scan (progress bars, early abort, huge repos)? Use the streaming form — callback per finding:
use PathBuf;
use ;
let = default_registry_with_config;
let paths = vec!;
let mut cb = ;
scan_paths_streaming;
More examples:
Detectors
Detector patterns informed by detect-secrets (python) and gitleaks (golang) projects (no code reused; output is Truman's own, not compatible)
140 inbuilt detectors, new ones can be added easily.
For full list, run truman --list-detectors.
Filters
- File — non-text extensions, lock files (
package-lock.json,Cargo.lock, …),*swagger*paths,--exclude-filesregexes, gitignore (unless--all-files). - Line —
pragma: allowlist secret/allowlist nextline secretcomments,--exclude-linesregexes, indirect references (secret = get_key()). - Secret — sequential strings, UUIDs, templated (
${…}/{…}),$-prefixed, non-alphanumeric, likely-ID prefixes,--exclude-secrets. - Verification —
--no-verify(default: keep everything asUnverified) vs--only-verified(currently yields nothing — see status note above).
Finding shape & positions
Finding
Span
span.snippet() returns exactly line_text[col_start..col_end]. Use
.redacted() to drop plaintext from memory before logging/forwarding
(serialization already omits it via #[serde(skip)]).
Streaming & parallelism
ScanEvent::{FileStart(PathBuf), Finding(Finding), FileDone(FileStats), Error(TrumanError)} is delivered to a single-threaded callback; the callback
returns true to continue or false to abort. Both the library
(scan_paths_streaming) and the CLI pretty-printer stream — output appears
before the scan finishes, making Truman suitable for huge repos, progress
UIs, and early exit on first hit.
Both engines scan files in parallel across all available cores by default
(ScanConfig::jobs = 0, honouring RAYON_NUM_THREADS; CLI -j/--jobs, e.g.
-j 1 for single-threaded). Per-file event order (FileStart → Finding* →
FileDone) is always preserved; across files, completion order is not
guaranteed when jobs != 1. The collect engine (scan_paths) returns findings
sorted by (file, line, columns, hash), so
final outputs stay deterministic regardless of completion order.
CLI reference
--list-detectors(top-level or underscan) prints detector names.--format jsonemits findings as JSON (hashes only, never plaintext) with a single trailing newline;--slimzeroes line/column numbers.-o/--output FILEwrites the same output to a file in addition to stdout.--all-filesalso scans gitignored files; hidden files are always included.-j/--jobs N: worker threads (0= all available cores, default, honouringRAYON_NUM_THREADS;1= single-threaded, deterministic file order). Applies to bothpretty(completion order) andjson(final output stays sorted).
Docs
docs/LIBRARY_USAGE.md— library usage guide: install, collect vs streaming, custom detectors, filters, positions, redaction, JSON output, error handling, and a cheat sheet.
Contributing
Issues and PRs welcome — especially new detectors.
A good detector PR: one file under crates/truman-detectors/src/, a
Detector impl returning exact col_start..col_end, registration in
lib.rs, and test vectors (true + false positives) asserting both secret and
columns. See stripe.rs as the reference.