PDFRedactor

PDFRedactor is a Python tool for redacting sensitive information from PDF files. The script can detect and redact phone numbers, email addresses, links, IBANs, BICs, timestamps, dates, QR Codes, Barcodes and custom text patterns from PDF documents.

Features

• Phone Numbers: Redacts phone numbers.
• Email Addresses: Redacts email addresses.
• Links: Redacts links/urls/hyperlinks.
• IBANs: Redacts detected International Bank Account Numbers.
• BICs: Redacts detected Bank Identifier Codes.
• Timestamps: Redacts detected timestamps.
• Dates: Redacts detected dates in various formats.
• Custom Text Patterns: Redact any custom text pattern specified by the user.
• QRCodes and Barcodes
• PDF Internals: Removes document metadata, XMP metadata, embedded/attached files, annotations/comments, form fields, JavaScript, thumbnails, hidden text, and pending redaction annotations.

Installation

To install PDFRedactor, follow these steps:

1. Clone the repository:

   git clone https://github.com/ltillmann/pdf-redactor.git

2. cd into the cloned directory

3. Install system dependencies:

   For Debian/Ubuntu:

   sudo apt-get update && sudo apt-get install libzbar0

   For macOS:

   brew install zbar

   For other Linux distributions, install the zbar or libzbar package using your package manager.

4. Install the required Python dependencies using pip:

   pip3 install -r requirements.txt

   requirements.txt is the single authoritative dependency file for this project. This project currently targets PyMuPDF 1.27.2.

   QR code and barcode support also require the zbar shared library at runtime. On macOS, install it with:

   brew install zbar

5. Make the script executable or pass the script directly to python:

   chmod +x pdf_redactor.py

Quick start

You can run the executable script from the command line:

./pdf_redactor.py [-h] -i INPUT [-o OUTPUT] [-e] [-l] [-p] [-v] [-m MASK]
                  [-t TEXT] [-c {white,black,red,green,blue}]
                  [-C {white,black,red,green,blue}] [-d] [-f] [-s] [-b]
                  [-r] [-q] [--sanitize] [--document-metadata]
                  [--embedded-files] [--annotations] [--form-fields]
                  [-x COLOR_HEX] [-X TEXT_COLOR_HEX]
                  [--quiet] [--show-matches]

Below are the available options:

Options

• -h, --help: Show help message and exit.
• -i INPUT, --input INPUT: Filename or directory path to be processed.
• -o OUTPUT, --output OUTPUT: Filename or directory path to save redacted files to. For a single input file, this may be either a .pdf file path or a directory.
• -e, --email: Redact all email addresses.
• -l, --link: Redact all links.
• -p, --phonenumber: Redact all phone numbers.
• -v, --preview: Preview redacted areas before continuing.
• -g GEOGRAPHIC_CODE, --geographic-code GEOGRAPHIC_CODE: Geographic code for phone number detection (e.g. US, GB, FR) for better accuracy.
• -m MASK, --mask MASK: Custom word/phrase to search for and black out, e.g. "John Doe" (case insensitive). Repeat the flag for each term, e.g. -m "John" -m "Doe". This is the flag to use when you want to redact specific names or words.
• -t TEXT, --text TEXT: Label to display inside the black redaction box, e.g. [REDACTED]. Default: None (box is blank). This does not control what gets redacted — use -m for that.
• -c {white,black,red,green,blue}, --color {white,black,red,green,blue}: Fill Color of redacted areas. Default: "black".
• -C {white,black,red,green,blue}, --text_color {white,black,red,green,blue}: Fill Color of text over redacted areas. Default: "white".
• -d, --date: Redact all dates (dd./-mm./-yyyy).
• -f, --timestamp: Redact all timestamps.
• -s, --iban: Redact all IBANs (International Bank Account Numbers).
• -b, --bic: Redact all BICs (Bank Identifier Codes).
• -r, --barcode: Redact all barcodes.
• -q, --qrcode: Redact all QR Codes.
• --sanitize: Remove PDF internals including document metadata, XMP metadata, embedded/attached files, annotations/comments, form fields, JavaScript, thumbnails, hidden text, and pending redaction annotations.
• --document-metadata: Remove PDF document information and XMP metadata.
• --embedded-files: Remove embedded and attached files.
• --annotations: Remove annotations and comments.
• --form-fields: Remove interactive form fields and stored values.
• -x COLOR_HEX, --color-hex COLOR_HEX: Fill color of redacted areas in HEX ("#000000").
• -X, TEXT_COLOR_HEX, --text-color-hex TEXT_COLOR_HEX: Text color of redacted areas in HEX ("#FFFFFF").
• --quiet: Suppress routine output and progress bars.
• --show-matches: Print exact detected values in logs. By default, PDFRedactor prints counts only to avoid exposing sensitive data in terminal history or CI logs.

At least one redaction target is required, such as -e, -p, -m "SECRET", -q, or --sanitize.

Examples

1. Redact phone numbers from a single PDF file:

   ./pdf_redactor.py -i input_file.pdf -p

2. Redact phone numbers with geographic code for better accuracy:

   ./pdf_redactor.py -i input_file.pdf -p -g US

3. To redact email addresses and preview redacted areas:

   ./pdf_redactor.py -i input_file.pdf -e -v

4. Redact a custom text pattern, with a label shown inside the black box:

   ./pdf_redactor.py -i directory_path -m "CONFIDENTIAL" -t "[REDACTED]"

   -m specifies what to find and black out; -t sets the label printed inside the box. Omit -t for a plain black box.

5. Redact multiple custom text patterns:

   ./pdf_redactor.py -i input_file.pdf -m "texte1" -m "texte2" -m "texte3"

6. Save a redacted single PDF into an output directory:

   ./pdf_redactor.py -i input_file.pdf -o redacted/ -m "CONFIDENTIAL"

7. Remove PDF metadata and internal sensitive objects:

   ./pdf_redactor.py -i input_file.pdf --sanitize

Preview Redactions

When using the -v or --preview option, the script will display a preview of the pending redaction batch for a page and prompt you to continue with the redaction or abort.

Limitations

• Most detection features rely on regular expressions, which may not cover all possible formats or variations.
• QR code and barcode detection depend on pyzbar plus the system zbar shared library. If zbar is unavailable, the script will continue to work but disable QR/barcode detection.
• PDFRedactor still does not cover names, addresses, SSNs, tables, labels and other document structures outside the supported detectors above.
• Removing form fields deletes interactivity and stored field values. If you need to preserve the visible filled appearance while removing the live fields, use a separate form-flattening workflow.
• --sanitize keeps normal PDF links unless you also use -l or --link.

License

This project is licensed under the MIT License.

Acknowledgments

• This tool utilizes the PyMuPDF library for OCR and PDF processing PyMuPDF.
• To detect phone numbers, I used David Drysdales Python port of Google's libphonenumber python-phonenumbers.
• To detect QR/Barcodes, I utilized pyzbar library for the most consistent results pyzbar.

Contributing

Contributions are welcome! Please feel free to open a pull request or report an issue.