Custom PII detection patterns

Teach Screenproof to find identifiers only your organization uses — employee IDs, case numbers, API keys, medical record numbers — with one regular expression per pattern. This page is everything a pattern author needs, whether you type patterns into Settings yourself or push them to a fleet.

On this page: how detection works · Suggested vs. Required · adding a pattern · regex crash course · copy-paste examples · the OCR reality · testing safely · troubleshooting · FAQ

How detection works

When you capture, Screenproof runs Apple's Vision OCR on the image, entirely on this Mac. Six built-in detectors — email, phone, ssn, card, iban, ipv4 — always run over the recognized text and flag findings for blur. Your custom patterns are simply more detectors: each one is a regular expression matched against the same OCR text, line by line. Nothing — not the image, not the text, not your patterns — ever leaves the machine.

Suggested vs. Required

Every pattern (built-in or custom) carries one of two actions. Both blur the finding immediately; they differ in what the reviewer may do before export:

Rule of thumb: individuals mostly want Suggested (detection as a safety net, human judgment last). Fleet admins enforcing policy want Required for the identifiers auditors care about — it removes the possibility of a wrong click.

Adding a pattern

In the app (individuals)

1. Open Settings → Privacy. Scroll to Custom Patterns.
2. Click Add Pattern…. An inline row appears with two fields: a Name (anything except the six built-in names) and the regular expression (ICU syntax — the flavor in the crash course below).
3. Pick Suggested or Required, then press Return or click Add. The Add button stays disabled — and shows Invalid expression — until the regex actually compiles, so you can't save a broken pattern.

Your patterns take effect on the next capture. Remove one anytime with the ✕ on its row.

For fleets (admins)

Deliver patterns in the PIIPatterns array of your managed-preferences profile (domain app.screenproof) — each entry a dict with Name, Regex (ICU), and Action (blurSuggested or blurMandatory). The Profile Creator builds this interactively (section "3 · PII detection") and validates each regex as you type; a working example ships in the repo as examples/test-managed-preferences.mobileconfig. Full key reference: schema.json.

The union rule, in one sentence: managed and user pattern lists merge — the profile wins for any name it defines, and users can always add their own patterns on top but can never remove, edit, or weaken a managed one.

Regex crash course (just what you need)

Screenproof uses ICU regular expressions (the macOS-native flavor). Writing a pattern for an identifier needs only these pieces:

That's the whole toolkit. Lookarounds, backreferences, and other advanced features work (it's full ICU) but no identifier pattern needs them — if you're reaching for one, simplify the pattern instead.

Worked examples (copy-paste ready)

Every regex below is tested against its sample with the exact engine Screenproof uses. Adjust the literal prefixes and digit counts to your own formats.

The OCR reality: you're matching what Vision read, not what the app rendered

Your pattern runs against OCR output, one recognized line at a time. That has practical consequences:

• Anchors (^ $) rarely help. A "line" is whatever Vision decided is one line — a table row can OCR as one long line containing labels, values, and the neighboring column. Anchoring to its start or end anchors to an accident of layout. Prefer \b word boundaries; skip anchors.
• Patterns never match across lines. An identifier that wraps onto a second line won't be caught as one match. Not usually a problem for short IDs; worth knowing for long tokens.
• Tolerate spaces where OCR inserts them. Kerning and column gaps make OCR occasionally read MRN-0084213 as MRN 0084213, or split grouped digits. Where your format has a separator, allow alternatives: [-\s]? instead of a hard -, or \s? between groups.
• Ultra-short patterns over-match. \d{3} matches ZIP fragments, ports, line numbers, and half of every dashboard. A pattern needs a distinctive literal prefix (EMP-, MRN, sk_live_) or a distinctive shape (\d{3}-\d{2}-\d{4}) to be useful.
• Start specific, widen carefully. Write the strictest regex that matches your real examples, test it on a capture, and only loosen (an optional space, a fuzzy digit class, a wider count) when you see a real miss. Widening first means drowning in false blurs and losing trust in the review screen.

Also expected: the blur box can extend slightly past the match — Screenproof pads it and grows it to word boundaries so edge glyphs are never left readable.

Testing your pattern safely

Never test detection against real customer data on your screen. The Screenproof repo ships fake-data demo pages under examples/ — crm-opportunity-test.html, hr-payroll-test.html, patient-chart-test.html, bank-dashboard-test.html, saas-support-console-test.html, db-client-query-test.html, law-firm-matter-test.html — every value on them fabricated and clearly marked TEST DATA.

1. Add your pattern in Settings → Privacy (or install your test profile).
2. Open a demo page in a browser — e.g. the CRM page, which contains OPP-006-88412 and ACC-001-30977, both caught by the case-ID pattern above. Or paste your own fake sample values into any text editor.
3. Capture the window with Screenproof and look at the review screen: your pattern's name appears on each finding it produced.
4. Missed something? Select the region in the editor and use Copy Text to see exactly what OCR read (spacing and misreads included), adjust the regex, and capture again.

Matches show up under the pattern's name, so run one pattern change at a time and you always know which edit did what.

Troubleshooting

FAQ

Do my patterns or the recognized text ever leave the device?

No. OCR is Apple's on-device Vision framework and the regex matching runs in the app. There is no cloud detection service and no telemetry of matches. The only things that ever leave the Mac are the exports you approve and, if your org configured one, audit events to your own webhook.

What's the performance cost of many patterns?

Modest. Each pattern is compiled once per capture and run over the recognized text lines — OCR itself dwarfs the regex work, so dozens of patterns are fine. The one way to hurt yourself is catastrophic backtracking: avoid nesting unbounded quantifiers like (\w+\s*)+. Every pattern on this page uses bounded, linear shapes — stay in that style.

Can I disable a built-in detector?

No. There is deliberately no "off" action — the only override is escalating a built-in from Suggested to Required. That guarantee is what makes the union rule safe: since no entry can turn detection off, a user's own patterns can only ever add protection, never weaken what a profile enforces. A built-in Suggested finding that's genuinely fine to show takes one click to release at review.