How Secret Redact IO works

What it does for you

Agents need to read files, run commands and fetch pages, and raw output can carry credentials into logs and model context. Secret Redact IO wraps those calls: what comes back is redacted, a guarded write stores the redacted text, and each call leaves a receipt of hashes, byte counts and rule counts that never archives the secret itself.

Redacted before it returnsFile reads, writes, fetches and subprocess output all pass through the same seven rules.
A dry run firstA guarded write can show its redacted text and receipt before anything reaches disk.
Receipts without the secretInput and output are recorded as SHA-256 digests and byte counts, with a count per rule that fired.
Stdlib onlyA small Python SDK and CLI with no dependencies.

Source: README.md at e6503f0 (version 0.1.0)

Watch

No concept film fits this tool closely yet. The walkthrough below covers it in text, with real commands and output.

Video walkthrough: coming with the next release.

How it works, one step at a time

Scroll, or use the step buttons. The inputs are the fake tokens from the repository's own examples/demo.py, such as ghp_ followed by 36 copies of b. Every line is output from secret-redact-io at commit e6503f0.

01
Seven shapes, and no more

The default policy has seven rules. Each matches a shape: a PEM block, a key with a known prefix, a JWT, a bearer header, or a value written beside a word like password or token. A match is replaced with a label naming the rule.

Source: src/secret_redact_io/redaction.py, GuardrailPolicy.default
02
Redact text in memory

redact_text runs the rules over a string. A GitHub token and a password field both go, and the result counts each rule that fired.

Source: examples/demo.py, redact_text
03
Guarded reads, writes and commands

The same rules guard real IO. A file holding an OpenAI-shaped key reads back redacted. A dry-run write shows the redacted text it would store and writes nothing. A subprocess that prints a token returns redacted stdout. Pick each call in the panel.

Source: src/secret_redact_io/file_io.py, src/secret_redact_io/exec_io.py
04
A receipt with no secret in it

The receipt for the subprocess call records the operation, the program name with its arguments dropped, the SHA-256 and length of the raw output and of the redacted output, and how many times each rule fired. The token itself appears nowhere.

One field, metadata, holds what the caller passed in, and nothing redacts it.

Source: src/secret_redact_io/receipts.py; README.md, "What a receipt records"
05
What has no shape survives

The rules match shapes. A secret written as ordinary prose has none, so it passes through untouched and no rule fires. That is why the receipt reports which rules fired; it never claims the text is clean. Pick each input in the panel.

Source: README.md, "Boundary"

Walkthrough

Install it, run it once, then use the main feature. Each command below is real, and so is its output.

Install

Install the pinned release from GitHub. Python 3.10 or newer; it is not on PyPI.

$ python -m pip install "secret-redact-io @ git+https://github.com/HarperZ9/secret-redact-io.git@v0.1.0"

First run: redact text

In Python, redact a token and a password before the text goes anywhere.

>>> policy.redact_text("token=ghp_bbbb...b\npassword=hunter2")
token=[REDACTED:github_token] | password=[REDACTED:credential_field]
counts: {'github_token': 1, 'credential_field': 1}
total:  2

Guard a write

A guarded write in dry-run mode shows what it would write, redacted, and writes nothing.

>>> write_text_guarded(target, "api_key: ...", dry_run=True)
text:     api_key: [REDACTED:credential_field]
operation: write.dry_run
written:  False
file exists on disk: False

Guard a command's output

A guarded run redacts what the command prints.

>>> run_guarded(["python", "-c", "print('token=ghp_bbbb...b')"])
returncode: 0
stdout:     token=[REDACTED:github_token]
redactions: {'github_token': 1}

Output from examples/demo.py and the policy at e6503f0 on Windows with Python 3.12.

What it does not do

Seven patterns, matched by shape. A credential that reads as ordinary prose survives.
The caller-supplied metadata field is stored as given and is not redacted.
A redacted write stores the redacted text, so the original value is gone from that file by design.
It is a guardrail for IO an agent performs. It does not scan a repository or rotate a leaked key.

Source: README.md at e6503f0, "What a receipt records" and "Boundary"

Check what stuck

Answer each one in your head before you open it.

What does a guarded dry-run write do on disk?

Nothing. It returns the redacted text and a receipt, and the file is not created.

Which receipt field can still hold sensitive text?

metadata, because it holds what the caller passed in and nothing redacts it.

Why does a combination written in words pass through?

The rules match shapes, and plain prose has no shape to match.

What it does for you

Watch

How it works, one step at a time

Seven shapes, and no more

Redact text in memory

Guarded reads, writes and commands

A receipt with no secret in it

What has no shape survives