truman 0.1.0

Truman secret scanner facade — Rust library re-exporting core and detectors with collect and streaming APIs
Documentation

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.

  1. Adding new detector is ~10 lines impl.: implement one trait, register it, done.
  2. In library mode, findings are delivered via callback as workers complete. Libraries never wait for the whole scan.
  3. Discovered secrets live only in memory for library use; only the SHA1 hashed_secret is serialized or printed.
  4. Pretty performant.
cargo install truman-cli   # binary: `truman`
truman scan . --format pretty
use std::path::PathBuf;
use truman::{default_registry_with_config, scan_paths_collect};

let (registry, config) = default_registry_with_config();
let findings = scan_paths_collect(&[PathBuf::from(".")], &config, &registry);
for f in &findings {
    println!("{}:{}: {}", f.location.file.display(), f.location.span.line, f.secret_type);
}

Installation

Requirements: Rust 1.70+ (edition 2021), any OS.

# CLI binary `truman` (from crates.io, once published)
cargo install truman-cli

# or from source
cargo install --path crates/truman-cli

# or run without installing
cargo run -p truman-cli -- scan . --format pretty

As a library, depend only on the facade crate:

[dependencies]
truman = "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)

truman --list-detectors            # All (140 as of now) names
truman scan . --format pretty      # parallel streaming across all cores
truman scan . -j 1 --format pretty # single-threaded, deterministic file order
truman scan src/ --format json > findings.json
truman scan . --exclude-files 'test.*' --disable-detector KeywordDetector

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:

cargo run -p truman --example quickstart
use std::path::PathBuf;
use truman::{default_registry_with_config, scan_paths_collect};

fn main() {
    let (registry, config) = default_registry_with_config();
    let findings = scan_paths_collect(&[PathBuf::from(".")], &config, &registry);
    for f in &findings {
        let s = &f.location.span;
        println!(
            "{}:{}:{}-{}: {} [{}]",
            f.location.file.display(), s.line, s.col_start, s.col_end,
            f.secret_type, f.hashed_secret,
        );
    }
}

Need results during the scan (progress bars, early abort, huge repos)? Use the streaming form — callback per finding:

use std::path::PathBuf;
use truman::{default_registry_with_config, scan_paths_streaming, ScanEvent};

let (registry, config) = default_registry_with_config();
let paths = vec![PathBuf::from(".")];
let mut cb = |ev: ScanEvent| -> bool {
    if let ScanEvent::Finding(f) = ev {
        println!("{}:{}: {}", f.location.file.display(), f.location.span.line, f.secret_type);
    }
    true // return false to abort the scan early
};
scan_paths_streaming(&paths, &config, &registry, &mut cb);

More examples:

cargo run -p truman --example streaming        # custom detector + streaming events
cargo run -p truman --example custom_detector  # custom detector + collect

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

  1. File — non-text extensions, lock files (package-lock.json, Cargo.lock, …), *swagger* paths, --exclude-files regexes, gitignore (unless --all-files).
  2. Line — pragma: allowlist secret / allowlist nextline secret comments, --exclude-lines regexes, indirect references (secret = get_key()).
  3. Secret — sequential strings, UUIDs, templated (${…} / {…}), $-prefixed, non-alphanumeric, likely-ID prefixes, --exclude-secrets.
  4. Verification — --no-verify (default: keep everything as Unverified) vs --only-verified (currently yields nothing — see status note above).

Finding shape & positions

Finding {
    detector: String,      // e.g. "StripeDetector"
    secret_type: String,   // e.g. "Stripe Access Key"
    secret: String,        // plaintext
    hashed_secret: String, // SHA1 hex - what JSON output carries
    location: Location { file: PathBuf, span: Span },
    verified: VerifiedResult, // Unverified (verification not implemented yet)
}
Span { line: u32 /* 1-indexed */, col_start: usize, col_end: usize /* bytes, end-exclusive */, line_text: String }

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

truman [OPTIONS] [COMMAND]
truman --list-detectors
truman scan [PATHS...] [--format json|pretty]
  [--exclude-files REGEX...] [--exclude-lines REGEX...] [--exclude-secrets REGEX...]
  [--disable-detector NAME...] [--list-detectors] [--all-files]
  [--only-verified] [--no-verify] [--slim] [-o OUTPUT] [-j JOBS]
  • --list-detectors (top-level or under scan) prints detector names.
  • --format json emits findings as JSON (hashes only, never plaintext) with a single trailing newline; --slim zeroes line/column numbers.
  • -o/--output FILE writes the same output to a file in addition to stdout.
  • --all-files also scans gitignored files; hidden files are always included.
  • -j/--jobs N: worker threads (0 = all available cores, default, honouring RAYON_NUM_THREADS; 1 = single-threaded, deterministic file order). Applies to both pretty (completion order) and json (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.

cargo fmt --all -- --check
cargo build --workspace
cargo test --workspace

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.

License

Apache-2.0