Skip to main content

PII Catcher


piicatcher PyPI image image image

PII Catcher for Databases and Data Warehouses


PIICatcher is a scanner for PII and PHI information. It finds PII data in your databases and file systems and tracks critical data. PIICatcher uses two techniques to detect PII:

  • Match regular expressions with column names
  • Match regular expressions and using NLP libraries to match sample data in columns.

Read more in the blog post on both these strategies.

PIICatcher is batteries-included with a growing set of plugins to scan column metadata as well as metadata. For example, piicatcher_spacy uses Spacy to detect PII in column data.

PIICatcher supports incremental scans and will only scan new or not-yet scanned columns. Incremental scans allow easy scheduling of scans. It also provides powerful options to include or exclude schema and tables to manage compute resources.

There are ingestion functions for both Datahub and Amundsen which will tag columns and tables with PII and the type of PII tags.

PIIcatcher Screencast


Quick Start

PIICatcher is available as a docker image or command-line application.



alias piicatcher='docker run -v ${HOME}/.config/tokern:/config -v /tmp:/.config -u $(id -u ${USER}):$(id -g ${USER}) -it --add-host=host.docker.internal:host-gateway tokern/piicatcher:latest'


# Install development libraries for compiling dependencies.
# On Amazon Linux
sudo yum install mysql-devel gcc gcc-devel python-devel

python3 -m venv .env
source .env/bin/activate
pip install piicatcher

# Install Spacy plugin
pip install piicatcher_spacy

Command Line Usage

# add a sqlite source
piicatcher catalog add_sqlite --name sqldb --path '/db/sqldb'

# run piicatcher on a sqlite db and print report to console
piicatcher detect --source-name sqldb
โ”‚ schema โ”‚ table โ”‚ column โ”‚ has_pii โ”‚
โ”‚ main โ”‚ full_pii โ”‚ a โ”‚ 1 โ”‚
โ”‚ main โ”‚ full_pii โ”‚ b โ”‚ 1 โ”‚
โ”‚ main โ”‚ no_pii โ”‚ a โ”‚ 0 โ”‚
โ”‚ main โ”‚ no_pii โ”‚ b โ”‚ 0 โ”‚
โ”‚ main โ”‚ partial_pii โ”‚ a โ”‚ 1 โ”‚
โ”‚ main โ”‚ partial_pii โ”‚ b โ”‚ 0 โ”‚

API Usage

from dbcat.api import open_catalog, add_postgresql_source
from piicatcher.api import scan_database

# PIICatcher uses a catalog to store its state.
# The easiest option is to use a sqlite memory database.
# For production usage check,
catalog = open_catalog(app_dir='/tmp/.config/piicatcher', path=':memory:', secret='my_secret')

with catalog.managed_session:
# Add a postgresql source
source = add_postgresql_source(catalog=catalog, name="pg_db", uri="", username="piiuser",
password="p11secret", database="piidb")
output = scan_database(catalog=catalog, source=source)


# Example Output
[['public', 'sample', 'gender', 'PiiTypes.GENDER'],
['public', 'sample', 'maiden_name', 'PiiTypes.PERSON'],
['public', 'sample', 'lname', 'PiiTypes.PERSON'],
['public', 'sample', 'fname', 'PiiTypes.PERSON'],
['public', 'sample', 'address', 'PiiTypes.ADDRESS'],
['public', 'sample', 'city', 'PiiTypes.ADDRESS'],
['public', 'sample', 'state', 'PiiTypes.ADDRESS'],
['public', 'sample', 'email', 'PiiTypes.EMAIL']]


PIICatcher can be extended by creating new detectors. PIICatcher supports two scanning techniques:

  • Metadata
  • Data

Plugins can be created for either of these two techniques. Plugins are then registered using an API or using Python Entry Points.

To create a new detector, simply create a new class that inherits from MetadataDetector or DatumDetector.

In the new class, define a function detect that will return a PIIType If you are detecting a new PII type, then you can define a new class that inherits from PIIType.

For detailed documentation, check piicatcher plugin docs.

Supported Databases

PIICatcher supports the following databases:

  1. Sqlite3 v3.24.0 or greater
  2. MySQL 5.6 or greater
  3. PostgreSQL 9.4 or greater
  4. AWS Redshift
  5. AWS Athena
  6. Snowflake


Please take this survey if you are a user or considering using PIICatcher. The responses will help to prioritize improvements to the project.


For Contribution guidelines, PIICatcher Developer documentation.