Skip to main content

Crate secretshape

Crate secretshape 

Source
Expand description

secretshape — does this string look like a secret?

A small library for detecting credential-shaped text: vendor token prefixes (ghp_, sk-ant-, AKIA…), structural formats (JWTs, PEM blocks, DSNs with embedded passwords) and, for the opaque rest, character-class + Shannon-entropy heuristics. Built for clipboard managers, log scrubbers, LLM-prompt sanitizers and CI checks — anywhere the question is “should this text be kept / shown / sent?”, not “is this repository clean?”.

§Two tiers, opposite error budgets

TierCostDepsErrs towardUse
is_probably_secret~µsnoneflagging (a kept API key is worse than a forgotten hash)drop/keep decisions
scan / redact (feature rules)one regex passregexsilence (a finding pages a human)reporting, redaction, dashboards

The tiers are calibrated against each other on purpose — don’t expect them to agree. The bool says “drop it” far more often than the rule engine says “alert”.

§Tier 1 — the dependency-free bool

// A clipboard manager deciding keep-or-drop:
assert!(secretshape::is_probably_secret("ghp_16C7e42F292c6912E7710c838347Ae178B4a"));
assert!(secretshape::is_probably_secret("Xk7pQm2Rv9Ls4Tz8Wn3Yb6Hd")); // opaque, high entropy

// …without forgetting the things people copy all day:
assert!(!secretshape::is_probably_secret("https://github.com/klappstuhlpy/funke/releases/tag/v0.3.1"));
assert!(!secretshape::is_probably_secret("cargo clippy --workspace -- -D warnings"));

§Tier 2 — structured findings and redaction (feature rules, on by default)

// A log line on its way to a sink nobody fully controls:
let line = "auth retry with ghp_16C7e42F292c6912E7710c838347Ae178B4a failed twice";

let findings = secretshape::scan(line);
assert_eq!(findings[0].rule, "GitHub Token");
assert_eq!(findings[0].severity, secretshape::Severity::Critical);
// Findings carry byte spans, not the secret itself — slice if you accept the risk.
assert_eq!(&line[findings[0].span.clone()], "ghp_16C7e42F292c6912E7710c838347Ae178B4a");

assert_eq!(
    secretshape::redact(line),
    "auth retry with [REDACTED:GitHub Token] failed twice"
);

See Scanner for custom rules, rule removal, the opt-in entropy pass and input caps; the full rule table lives in the rules module docs.

§What this cannot catch — honestly

  • Short human passwords. Sommer2024! is a word with a number on the end; nothing about its shape distinguishes it from prose. If you manage passwords, exclude them upstream (clipboard exclusion markers, vault hygiene) — shape analysis will not save you.
  • Novel token formats. A provider that launches tomorrow with an unprefixed 32-char token is invisible to the rule tier until a rule lands (the entropy heuristic may still catch it, at Tier-1 precision).
  • Secrets split across lines. Both tiers judge the text they are given; a key pasted as two halves is two innocent-looking strings.
  • Truth. This crate judges shape, never validity — it does not (and will not) call provider APIs to verify a match is live.

§Features

With --no-default-features the crate is dependency-free and exposes just is_probably_secret — small enough for the hot path of a clipboard hook.

Re-exports§

pub use rules::builtin_rules;
pub use rules::Rule;
pub use rules::Severity;

Modules§

rules
Tier 2 — severity-tagged provider rules (feature rules).

Structs§

Finding
One detected secret-shaped region of the input.
InvalidPattern
A custom rule pattern failed to compile. Wraps the regex error message without exposing regex’s error type in the public API (that would tie this crate’s semver to regex’s).
RedactOptions
Options for redact_with. The default masks the whole match.
Scanner
A configurable scanner: the built-in rules, plus/minus caller adjustments.

Functions§

is_probably_secret
Is this text shaped like a credential? See the module docs for what that buys — and, as importantly, what it cannot: a short human-chosen password (Sommer2024!) is a word with a number on the end, and nothing about its shape gives it away.
redact
Replace every finding of the default Scanner with [REDACTED:<rule>].
redact_with
redact, but with a caller-configured scanner and options.
scan
Scan with the unmodified default Scanner — the one-liner for the common case.