Please report vulnerabilities privately through GitHub security advisories. Do not open a public issue, and do not include real personal data in reports.
You can expect an acknowledgment within a few business days.
pii-scan reads data that is sensitive by definition. These are the guarantees it is built around; a violation of any of them is a security bug.
- Values stay out of output. Console output, reports (text, JSON, JSONL, CSV, SARIF),
GitHub annotations, the job summary, the cache, and baselines contain typed placeholders and
keyed fingerprints, never matched values.
--show-valuesis the only exception; it is refused in CI and never uses the cache. - Fail closed. A file that was not fully analyzed is never reported clean and never written to a masked output tree.
- Reports are private. Files written with
--report, the cache, baselines, and masked copies are created with mode0600; directories created for masked output use0700. On Windows they get a protected ACL for the current user and SYSTEM only, before any data is written. One exception: SQLite creates the cache's-waland-shmside files itself, with the permissions of their folder, and pii-scan restricts them right after it opens the cache. Keep the cache in a folder only you can read (one pii-scan creates is private). - Masking is non-destructive. Masked copies go to a separate directory that must not overlap the scanned tree. Writes are atomic and never follow a symlink. Originals are never modified.
- Untrusted files are handled defensively. Symlinks (and on Windows junctions), FIFOs, sockets, and devices are skipped
without being opened; reads are bounded by
max_file_size, and each opened file is verified to still be under the scan root (so a parent directory swapped for a symlink or junction mid-scan is refused). That check needs the real path of an open file, which pii-scan gets on Linux (from/proc), macOS, and Windows; elsewhere (for example the BSDs, or Linux without/proc) it is skipped, and only the final path component is protected against links. Cloud placeholders (OneDrive online-only files, iCloud Drive dataless files) are reported as not scanned rather than downloaded. Built-in regex rules avoid catastrophic backtracking. A file where one rule exceeds the match cap is reported as not scanned rather than partially reported or masked. - Git is invoked defensively.
core.fsmonitor, hooks, and external diff drivers are disabled, git runs only in changed-files mode, and repositories whose own git config (.git/configor a worktree'sconfig.worktree) sets filters, includes, or diff commands are refused unless--trust-repois given. Submodules are never examined, so their own config can't run anything; git never fetches or uses any transport, so a partial clone can't trigger a download; and git is run by absolute path fromPATH, never from the scanned directory. - Untrusted configuration can't loosen policy. With
--restricted-config(always on in the GitHub Action), a configuration or custom rules file from the scanned tree can only add rules or raise severities, and custom rules must compile as linear-time RE2 and live under the working directory. - Spending is bounded on request.
--aws-max-charsstops the run once a character budget has been sent to AWS. - AWS endpoints are pinned.
AWS_ENDPOINT_URL*environment variables are ignored unless an endpoint is set explicitly in configuration, so a planted environment cannot redirect scanned content. Credentials come from the standard AWS credential chain; pii-scan never stores them.
The regex layer runs locally and sends nothing anywhere. The contains, detect, and
guardrails layers send file text to Amazon Comprehend or Amazon Bedrock in the region you
choose. Before enabling them:
- Confirm that sending the data to AWS is allowed by your data-handling policy.
- Review the Amazon Comprehend FAQ on how inputs may be used, and consider an AWS Organizations AI services opt-out policy.
- Pin a region deliberately (
--regionoraws.region) and, if required, use a VPC interface endpoint (aws.endpoint_url). - Grant the scanning role only the actions it needs (see docs/github-action.md).
In scope: this repository's code, the GitHub Action, and default configuration. Out of scope: detection accuracy of AWS services, and findings that require an attacker to already control the pii-scan configuration file or command line.