spanguard¶
Detect and redact PII/PHI in text and streaming transcripts — and get a leak-free audit record for every redaction, automatically.
spanguard finds personally identifiable information and protected health
information (PII/PHI) in plain text or in a live, chunked stream, and rewrites
it according to a Policy you control. Every result carries an AuditRecord
that proves what was redacted without ever repeating the sensitive value
itself — so the audit trail can never become a second place where the data
leaks out.
The leak-free-audit promise
Every call to Redactor.redact() returns a RedactionResult whose
audit field (an AuditRecord) contains only entity-type counts, a
policy hash, and a timestamp — never the raw matched values.
result = redactor.redact("mail jane@x.com")
result.audit.counts # {"EMAIL": 1} -- never "jane@x.com"
The same guarantee holds for the CLI's --audit-json output and for
StreamRedactor, which redacts chunked text (e.g. a live transcript)
while guaranteeing that the concatenation of its streamed output equals
what a single one-shot redact() call would have produced.
Why spanguard¶
-
Four redaction modes
mask,placeholder,hash, and reversibletokenize— one mode perPolicy. -
Built-in entity coverage
Regex/checksum recognizers for
EMAIL,PHONE,SSN,MRN,DOB,CREDIT_CARD(Luhn-validated), andAPI_KEY— plus an opt-in spaCy NER recognizer forPERSON/LOCATION. -
Leak-free audit records
AuditRecordcarries entity counts, a policy hash, and a timestamp — never the raw matched text — so logging it is always safe. -
Streaming-safe
StreamRedactorredacts chunked text (e.g. a live call transcript) without ever leaking a partial match across a chunk boundary. -
A real CLI
spanguard scanandspanguard redactcover ad-hoc and pipeline use without writing a line of Python. -
Pluggable by design
Ship your own detector by implementing the
Recognizerprotocol — combine it with, or fully replace, the built-ins.
Install¶
For the optional NER (PERSON/LOCATION) recognizer:
What it detects out of the box¶
Built-in regex/checksum recognizers cover EMAIL, PHONE, SSN, MRN,
DOB, CREDIT_CARD (Luhn-validated), and API_KEY. An opt-in spaCy-based
recognizer adds PERSON/LOCATION detection when you pass it to Redactor. See Recognizers
for the full entity table and how to plug in your own detector.
Where to go next¶
- Quickstart — mask, placeholder, hash, and tokenize+reveal in a few lines.
- Recognizers — the entity table and how to write a custom
Recognizer. - Streaming — redacting text that arrives in chunks.
- CLI — the
spanguard scan/spanguard redactcommands. - API reference — full generated reference for all public symbols.
- Known limitations — honest gaps and edge cases.