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](#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.

```sh
cargo install truman-cli   # binary: `truman`
truman scan . --format pretty
```

```rust
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.

```sh
# 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:

```toml
[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`](docs/LIBRARY_USAGE.md).

## Quick start (CLI)

```sh
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):

```text
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`](crates/truman/examples/quickstart.rs):

```sh
cargo run -p truman --example quickstart
```

```rust
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:

```rust
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:

```sh
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]https://github.com/Yelp/detect-secrets (python) and
[gitleaks]https://github.com/gitleaks/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

```rust
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

```sh
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`]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.

```sh
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](LICENSE)