agent-sanitizer (Python client)
A thin Python bridge to the agent-sanitizer
Node.js CLI. The sanitization logic has a single source of truth — the
JavaScript in src/ — so this package shells out to the CLI rather than
re-implementing it, giving a Python pipeline byte-identical verdicts with no
second implementation to keep in sync.
Requirements
- Node.js (>= 22) on
PATH. The sanitizer is JavaScript; something has to run it. There is deliberately no pure-Python fallback.
That's it — pip install agent-sanitizer and, with Node available, you're
ready to go. The wheel ships a self-contained, single-file build of the CLI
(the src/ logic and its npm dependencies bundled into one .mjs at release
time), so there is no separate JavaScript checkout to clone and no environment
variable to set. The bundle is a versioned build artifact from src/, not a
hand-maintained port, so it can't drift from the JS.
Optional: point at your own JS checkout
Set AGENT_SANITIZER_CLI to a checkout's bin/sanitize-cli.mjs to override the
bundled CLI (e.g. to run against unreleased src/ changes). When the module is
imported directly from a repo checkout, the source CLI is found automatically.
Usage
from agent_sanitizer import sanitize
result = sanitize("untrusted text", html=True)
print(result.cleaned, result.found, result.warnings)
See the package docstring for the full set of entry points (sanitize_text,
classify_prompt, scan_instruction_files, clean_file, and the long-lived
Sanitizer worker).
Secret redaction ([secrets] extra)
The base install is dependency-free. The optional secrets extra adds a
pure-Python secret-redaction engine under agent_sanitizer.secrets —
detect-secrets plus custom detectors, benign-value skipping, cross-line
reassembly, PEM collapse, and exact-match redaction of caller-supplied env-var
values. Unlike the sanitizer above it needs no Node.js; its only dependency
is detect-secrets, pulled in by the extra:
pip install "agent-sanitizer[secrets]"
Every detect-secrets import lives inside this subpackage, so a plain
import agent_sanitizer never touches it. The engine shares the parent
package's invisible-character SSOT (agent_sanitizer.invisible) rather
than forking it — a fork would be a silent security regression.
In-process
from agent_sanitizer.secrets import RedactorConfig, redact, redact_map
redacted, found = redact("aws_key = AKIAIOSFODNN7EXAMPLE")
# -> ("aws_key = [REDACTED: AWS Access Key]", ["AWS Access Key"])
# Pass provider/host secret values in — config is supplied, never discovered.
cfg = RedactorConfig(host_cred_vars={"GH_TOKEN": "ghp_realtokenvalue123"})
redact("tok=ghp_realtokenvalue123", cfg) # -> ("tok=[REDACTED: GH_TOKEN]", ["GH_TOKEN"])
The rehydration map contract
redact_map(text, config) returns a lossless, two-way view:
{"text": "<redacted>",
"pairs": [{"placeholder": "[REDACTED: …]", "original": "<secret>", "start": <int>}],
"found": ["<type>", ...]}
Substituting each pair["original"] at its start reconstructs the input
byte-for-byte. start is a Unicode code-point offset into text (the field
is start, not start_offset). U+E000 / U+E001 are reserved placeholder
sentinels: input already containing either is refused with
{"unmappable": "input contains reserved sentinel characters"} (fail closed)
rather than producing an ambiguous map.
Daemon vs. one-shot
detect-secrets caches a process-global secret_type → plugin mapping, so a fresh
one-shot call must re-register the plugin set every time — slow under load. Two
console scripts (installed with the extra) cover both modes:
agent-secret-redactor— one-shot: reads text on stdin, writes the redaction result as JSON on stdout. Re-registers plugins per call.agent-secret-redactor-daemon <socket-path>— long-lived Unix-socket server that configures the plugin set once at startup (a warm-up scan primes the cache before it binds, so a bound socket means ready). Wire protocol both directions: a 4-byte big-endian length prefix then that many bytes of UTF-8 JSON, specified field by field inagent_sanitizer/secrets/data/redactor-protocol.json. Every request field (text,map,web_ingress,env_secrets) is required; the response is the one-shot result, JSONnullwhen nothing is redacted, or{"error": …}for a malformed request or a scan failure. The daemon logs failures todaemon.logbeside the socket.
Both console scripts import the engine on startup, so they fail loud if the
[secrets] extra (hence detect-secrets) is not installed — fail closed, never
a silent no-op.
Versioning
This package is versioned in lockstep with the npm
agent-sanitizer:
each release publishes both at the same version from the same commit, and the
wheel bundles src/ at exactly that version. So pip install agent-sanitizer==X.Y.Z and npm i agent-sanitizer@X.Y.Z are the
same underlying logic.
1 maintainer
Metadata
1 maintainer
Release files for agent-sanitizer 2.60.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| agent_sanitizer-2.60.0.tar.gz | 373.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agent_sanitizer-2.60.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 762.3 kB
Release files / agent_sanitizer-2.60.0.tar.gz
| Download URL | agent_sanitizer-2.60.0.tar.gz |
|---|---|
| Size | 373.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9cb5a3f14468ed814bba5dfe24ced97b27739cd685cca95f0de68346a1946af5
|
|
BLAKE2b-256 checksum How to use checksums |
3e73602e4cc2482622b67dbcb8f48c000cd0d9b0f9c32b2ca1a804cc5977948d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.
Transparency logRelease files / agent_sanitizer-2.60.0-py3-none-any.whl
| Download URL | agent_sanitizer-2.60.0-py3-none-any.whl |
|---|---|
| Size | 388.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b19bda414fb7a197ddeb4be6dac8a3b9833037228d99884f27d40746be5593db
|
|
BLAKE2b-256 checksum How to use checksums |
0c51bff27d04ab780b47d390aa304fe88601d84033c7bd09cd512622295208c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.
Transparency log
