Pii Scan

pii-scan

Agent workflow

This is an executable audit, not a checklist. When a usable file is available, run the bundled scanner instead of only explaining how someone could scan it.

1. Identify the export the user wants checked. If several files are plausible and the choice changes the audit, ask which one; otherwise use the clearly relevant file.
2. Resolve scripts/scan.py relative to this SKILL.md and run it with an available Python 3 interpreter. In Claude Code, ${CLAUDE_SKILL_DIR} is this skill directory; in other hosts use the skill path supplied by the host. Quote every path.
3. Let column auto-detection run first. Add --column NAME only when the user named a column or the report shows that the wrong one was selected. Use --json only when the user wants machine-readable output.
4. Interpret exit codes exactly: 0 means the supplied export produced no findings, 1 means findings were produced, and 2 means the input could not support a trustworthy scan. On 2, relay the actionable error and ask for the smallest correction; never describe the file as clean.
5. Summarize the highest-severity verified findings first, preserve the distinction between ! verified values and ? name-only signals, and give the first remediation step. Do not reveal, reconstruct, or repeat an unredacted personal value.

Never modify the source export, upload it, or invent findings beyond the scanner's output. If the user needs help preparing an export, read references/input-guide.md.

When to use this

Reach for it when someone asks any of these:

• "Are we sending PII to Google Analytics?"
• "We got a privacy complaint / a DPA question about our tracking."
• "We're about to switch on server-side tagging" — check what is already in the URLs first.
• "Audit our GA4 setup" — configuration audits do not read values, so they never find this.
• Before a migration, a new consent tool, or handing an analytics property to an agency.

Why it matters

Google's terms prohibit sending personally identifiable information to Google Analytics. A violation can require data deletion and can put continued access to the service at risk. It rarely happens deliberately. It happens because a form submits over GET, or a tag-manager variable captures the whole field, or a confirmation page puts the customer's name in the path. Nobody checks, because checking means reading thousands of URLs by hand.

How to run it

python skills/pii-scan/scripts/scan.py <export> [--column NAME] [--json] [--fail-on critical|high|medium]

It accepts whatever the user actually has:

The column is auto-detected from the header. Pass --column when the file has an unusual name for it, and --json when the output feeds something else.

Reading the output

Every finding carries a signal marker, and the distinction matters:

• ! value verified — the value itself is personal data. The email parses, the card passes Luhn, the IBAN checksum is correct. This is not a guess.
• ? parameter name only — the parameter is called email or fname, and the value was not independently verifiable. Worth investigating, not worth an incident report.

Severities: critical is verified personal data or a credential. high is a strong name signal or a documented test card. medium is an uncorroborated pattern, or a PII-named parameter that is currently empty — which still means the plumbing exists and will carry a real value the first time someone fills that field in.

What to tell the user afterwards

Lead with the fix, not the count. The scanner prints remediation for each kind it found; the ordering of those steps is the important part and it is always the same:

1. Stop it at the source. A form that submits over GET, a variable that captures too much, a redirect that carries a parameter through. Until that is fixed, everything else is cleanup.
2. Then configure the platform. GA4's Redact data setting for email and phone, and the URL query parameter exclusion list. Both are second lines of defence — they only catch what they recognise.
3. Then decide about the data already collected. Card numbers, IBANs and credentials are an incident, not a settings change: the value has also reached server logs, any CDN in front of them, and the browser history of the person who typed it.

What it will not do

• It does not read your GA4 property. It reads a file. That is deliberate — the whole point is that it needs no access grant, no OAuth, and no vendor subscription.
• It does not print unredacted values, in the table, the locations, or the JSON.
• It does not claim a finding is confirmed when only the parameter name looked suspicious.
• It cannot tell you the scan is complete. It tells you what is in the export you supplied. A one-month export answers a one-month question.
• It does not recognise national identity number formats, because verifying them properly is country-specific and a guess here would produce false alarms about salaries, invoice numbers and order references.

Tests

python tests/test_pii_scan.py

The fixture carries twelve planted defects and the test asserts the scanner finds exactly those and invents nothing. It also asserts that no personal value from the fixture appears in full anywhere in the report — that test failed on first run and caught the scanner reprinting a card number that sat in a URL path.