redact.py

A small, security-grade PDF redactor. It removes terms you supply from both the text layer and embedded images (screenshots) of a PDF — using true removal, not black-box overlays — so the result is safe to share or feed to an AI system.

Overlay tools draw a black rectangle on top of the text. The original characters still sit underneath and are trivially recovered by copy-paste, pdftotext, or by decompressing the file. This tool deletes the content instead, then verifies that nothing survived.

What it does

• Text layer — locates each term and deletes the underlying glyphs from the page content stream (PyMuPDF apply_redactions).
• Screenshots / embedded images — OCRs each embedded image (Tesseract), finds the term, and blacks out only the covered pixels of the stored bitmap (PDF_REDACT_IMAGE_PIXELS). The rest of the image is preserved.
• Metadata — scrubs document info and XMP metadata.
• Self-verify (mandatory) — reopens the output, re-extracts text and re-OCRs every image, and fails (exit 1) if any term still appears.
• Never modifies the input — works on a copy and writes a new file.
• Produces <name>_redacted.pdf and a <name>_redacted.txt text dump.

Matching is case-insensitive substring.

Install

python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt

System dependencies:

• Tesseract (for screenshot OCR): brew install tesseract (macOS) or apt install tesseract-ocr (Debian/Ubuntu).
• Tk (only for the optional GUI): on macOS with Homebrew Python you may need brew install python-tk@<version>.

Usage

# GUI (default in an interactive terminal): a window prompts for words
./.venv/bin/python redact.py report.pdf

# Terminal, terms from flags
./.venv/bin/python redact.py report.pdf --no-gui --term ACME --term 10.0.0.5 --yes

# Terms from a file (one per line, # for comments)
./.venv/bin/python redact.py report.pdf --terms terms.txt

Flags: -o OUT.pdf · --terms FILE · --term X (repeatable) · --no-ocr · --ocr-dpi 300 · --label "[REDACTED]" · --gui / --no-gui · --yes.

Exit codes: 0 verified clean · 1 a term survived verification · 2 usage error.

Limitations

• OCR accuracy is bounded by Tesseract; a badly-rendered word in a screenshot may be missed. The self-verify step re-OCRs the output, so such a case is reported as a leak rather than hidden.
• Multi-word terms split across a line break in the text layer may not match.
• Only the terms you supply are removed — review the document for other sensitive content (usernames, hostnames, paths) and add those terms too.

License

MIT — see LICENSE.