NAME

Text::Redact::Secrets - find secrets in text by gitleaks' rules, and redact them

SYNOPSIS

use Text::Redact::Secrets qw(find redact);

# The text with each secret in it replaced by *REDACTED*.
print {$log} redact($text);

# Each secret in the text, with the rule that found it.
for my $found (find($text)) {
    say "$found->{rule} at $found->{offset}";
}

DESCRIPTION

Text that might hold a secret, such as a dump written to a log, should be safe to write. Text::Redact::Secrets finds the secrets in a string by gitleaks' rules: a maintained set of regexes, keywords, entropies and allowlists, carried over from gitleaks with their meaning unchanged. redact puts *REDACTED* in place of each, and find reports each, with the rule that found it.

gitleaks' rules are in Text::Redact::Secrets::Rules::Gitleaks, which names the gitleaks tag and commit they came from. gitleaks is https://github.com/gitleaks/gitleaks, copyright (c) 2019 Zachary Rice, under the MIT licence.

Beside gitleaks' rules are some of the module's own, for secrets gitleaks has no rule for, such as a password in a URL, in Text::Redact::Secrets::Rules::Dist, which says what each finds.

Nothing is exported unless asked for.

FUNCTIONS

redact

my $safe = redact($text);

Returns a copy of $text with each secret found in it replaced by *REDACTED*. $text itself is left as it was. Where two rules find secrets that overlap, the text they cover between them is replaced once.

find

my @found = find($text);

Returns each secret found in $text, in the order it appears, as a hash reference:

rule

The id of the rule that found it: one of gitleaks', such as aws-access-token, or one of the module's own, such as url-userinfo-password.

secret

The secret, as the rule picks it out of what it matched.

offset

Where the secret starts in $text, counting from 0.

Returns an empty list if there are none.

Two rules can find secrets that overlap, and each is reported.

WHAT IT WON'T FIND

It finds what its rules describe, and nothing else, so redacted text can still hold a secret. Most rules find a kind of secret by its shape, such as an AWS access key id or a private key. The rest, most of all generic-api-key, find a value given to a name such as password or api_key, but only one long enough and random enough: a short or ordinary password, or one with a word in it, isn't found.

gitleaks' command line also decodes base64, hex and percent-encoded text, and looks for secrets in what it decodes. This module looks only at the text as it is, so it doesn't find a secret that's been encoded. Nor does it use gitleaks' rules that look at a file's name, as it sees only text.

It takes time in step with the text for nearly every rule: about 8 milliseconds for a dump of a few hundred rows, on a laptop. A few rules take longer on a long run of letters and digits with no space in it, tens of thousands of characters, such as a long hex string, if the text also holds the rule's keyword: up to about a fifth of a second for 40,000 characters, on a laptop.

KEEPING THE RULES CURRENT

gitleaks' rules come from one of its releases, which Text::Redact::Secrets::Rules::Gitleaks names. To see which:

perl -MText::Redact::Secrets::Rules::Gitleaks \
    -E 'say Text::Redact::Secrets::Rules::Gitleaks::gitleaks_tag()'

The rules can't be updated where the module is installed. Each set is carried over from a gitleaks release by the distribution's maintainer, tested, and released as a new version of the module, so that what's installed is always a set that was tested together. A version that brings new rules moves the middle number, as from v1.0.0 to v1.1.0; a fix moves the last; and a change to what redact or find take or return moves the first. To have the newest rules, install the module again, which brings the newest version:

cpanm Text::Redact::Secrets

DIAGNOSTICS

Expected a string to redact

redact was given undef or a reference.

find was given undef or a reference.

SEE ALSO

gitleaks, whose rules these are, and Text::Redact::Secrets::Rules::Dist, the module's own.

AUTHOR

Iain Campbell <cpanic@cpan.org>

LICENSE

Copyright (c) 2026 by Iain Campbell.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself, except for gitleaks' rules, in Text::Redact::Secrets::Rules::Gitleaks, which are under gitleaks' MIT licence, in LICENSE-gitleaks.