uk-bank-statement-anonymiser

Anonymise UK bank statement PDFs by scrambling personal data while preserving layout.

Why?

You need to share bank statements with your accountant, solicitor, or lender — but the PDF contains sensitive data: account numbers, sort codes, IBANs, card numbers, and transaction details.

This tool scrambles that data while keeping the PDF looking like a real bank statement. Your financial data never leaves your machine.

Quick start

pip install uk-bank-statement-anonymiser

from bank_statement_anonymiser import anonymise_pdf

anonymise_pdf("statement.pdf", "anonymised.pdf")

One function. One command. Done.

Important: check before you share

This tool handles known patterns but cannot guarantee that all personally identifiable information has been removed. Bank statement PDFs may contain data in places this tool does not currently scan (e.g. embedded metadata, images, or unusual formatting).

• You must review every anonymised PDF yourself before sharing it with any third party. Verify that no account numbers, names, addresses, balances, or other sensitive data remain visible.
• Do not attach PDFs — anonymised or otherwise — to GitHub issues, PRs, or discussion threads. If anonymisation is failing, the statement will not be properly anonymised. Use text excerpts or screenshots with sensitive data redacted instead.
• Do not paste log output, debug output, or console transcripts without checking them for PII. These may contain account numbers, names, addresses, or other sensitive data. Redact any sensitive content before sharing.

What gets anonymised

Supported banks

• HSBC UK (current & savings)
• Natwest
• TSB (Spend & Save & credit card)
• Halifax

More banks can be added — see Contributing.

Why these banks? Each bank uses a different PDF encoding strategy. HSBC uses Latin-1, Natwest uses Identity-H CID fonts, and TSB uses custom ToUnicode CMaps. Other UK bank PDFs may work if they use one of the same approaches.

Custom rules

By default, the library handles common patterns automatically. You can supplement with your own rules:

anonymise_pdf(
    "statement.pdf",
    "output.pdf",
    always_anonymise_path="my_replacements.toml",
    never_anonymise_path="my_protected_phrases.toml",
)

• always_anonymise.toml — Force specific strings to known replacements:

  "40-37-28" = "00-00-00"
  "Jason Farrar" = "John Doe"
  

• never_anonymise.toml — Protect phrases from being scrambled:

  exclude = ["My Employer Ltd", "Salary Payment"]
  

User config files override system config on clashes. Both system and user never_anonymise lists are combined.

Do not commit user config files to source control — they may contain real account numbers or names.

API reference

def anonymise_pdf(
    input_path: str | Path,
    output_path: str | Path | None = None,
    always_anonymise_path: str | Path | None = None,
    never_anonymise_path: str | Path | None = None,
    debug: bool = False,
) -> Path

How it works

1. Identify sensitive data — Detects sort codes, account numbers, IBANs, card numbers, and other patterns. Each gets a deterministic fake replacement so the same data is always replaced consistently across pages.

2. Protect structural text — Dates, payment type codes, bank URLs, and configured protected phrases are left unchanged.

3. Scramble remaining text — All other letters are replaced with random alternatives; digits and symbols stay intact. The PDF's layout, fonts, images, and line breaks are preserved.

All processing happens locally via pikepdf. No network requests, no accounts, no data collection.

Customisation

The anonymiser is designed to be extended for other bank formats (e.g. US, EU) or non-bank PDFs. Three areas control what gets anonymised:

1. Pattern detection — Regex patterns identify sort codes, account numbers, IBANs, card numbers, dates, amounts, and URLs. Add or modify patterns in the source to support new formats.

2. System configs — Default replacement rules (always_anonymise_system.toml) and protected phrases (never_anonymise_system.toml) ship with the package.

3. User configs — Optional TOML files passed via --always-anonymise / --never-anonymise to add custom rules. User replacements override system defaults; protected phrases are merged (union).

Regenerating diagrams: Diagrams are authored in Mermaid (.mmd files in docs/diagrams/). To regenerate SVG/PNG, install mermaid-cli (uv add --group dev mermaid-cli) and run mmdc -i <input>.mmd -o <output>.svg.

CLI usage

pip install uk-bank-statement-anonymiser
anonymise-pdf statement.pdf

anonymise-pdf statement.pdf -o output.pdf
anonymise-pdf statement.pdf --always-anonymise rules.toml --never-anonymise protected.toml

Related projects

This library is used by other projects in the boscorat ecosystem:

• openstan — Free, offline UK bank statement analyser. Parse, analyse, and export your statements to Excel, CSV, or JSON. Uses uk-bank-statement-anonymiser to redact statements for safe sharing. Website: openstan.org

• bank_statement_parser — Parse bank statement PDFs, extract structured transaction data, and persist results to Parquet or SQLite. Includes optional PDF anonymisation via uk-bank-statement-anonymiser.

Contributing

The most valuable contribution is testing the anonymiser against real bank statements from your own accounts. Your PDFs never leave your machine — you only submit a review report.

See CONTRIBUTING.md for the full workflow.

Development

git clone https://github.com/boscorat/uk-bank-statement-anonymiser.git
cd uk-bank-statement-anonymiser
uv sync
uv run pytest

License

MIT — see LICENSE.