Action Lists

Finding PII is only half the job. Once triage has confirmed which files genuinely contain sensitive data, something has to happen to them: stray exports get deleted, log files get scrubbed, old reports get cleaned up. Action lists are how PII Crawler turns scan results into that remediation step.

An action list is a named collection of files gathered from your scan results. You build the list as you review findings, then run one of three actions over the whole list at once:

• Delete removes the files from disk, permanently.
• Redact rewrites each file in place, replacing every confirmed PII value with mask characters of the same length. 123-45-6789 becomes ***-**-****, and the rest of the file is untouched.
• Quarantine moves the files into a holding folder instead of deleting them. The files keep their content, can no longer be reached at their original location, and can be restored later with one click.

Every action shows you a full preview of what will happen before you confirm anything.

Action lists work on local scan results and on network share scan results. Files found on an SMB share can be deleted and quarantined directly on the share; see Files on network shares below. Redaction works on local files only.

Building a list

Open a scan (local or network share) and go to its Files view. Use the checkboxes to select files (Shift-click selects a range, and a selection can span pages), then choose Add to list in the selection bar. Pick an existing list, or type a name to create one on the spot.

Lists are global, not per scan. The same list can collect files from several scans, so you can sweep your whole estate into one remediation pass. The same file can only appear in a list once, so adding an overlapping selection is safe; duplicates are skipped and reported.

You will find all your lists under Action Lists in the sidebar. A list can mix files from local and network scans; files from a share are always shown with their full network path (\\server\share\folder\file.csv) so there is never any doubt about what an action will touch.

Reviewing a list

The list page shows every entry with its file path, the scan it came from, how many live findings it has (findings you marked as false positives are not counted, and are never redacted), and its current status:

• redacted: a redact run rewrote this file; hover the badge to see how many findings were masked and when.
• restored: this file was brought back from quarantine; its PII is intact.
• error: the last run could not process this file; hover the badge for the exact error.
• file gone: the file no longer exists on disk. It will be skipped by any action.
• not a plain-text file: the file can be deleted, but not redacted (see below).
• a symlink: the entry is a symbolic link rather than a file. Every action skips it; see Symlinks below.
• recorded with a relative path: the scan that found this file recorded a path that only means something inside the folder that scan was started from. Every action skips it; see Paths recorded by older scans below.

Entries can be removed from the list at any time with the checkboxes and Remove from list. Removing an entry never touches the file itself, and deleting a whole list only deletes the list.

If you delete a scan, its entries disappear from your lists too, since they reference that scan's results. Records of past runs are kept.

Deleting files

Click Delete files… on the list page. PII Crawler first shows a preview: how many files will be deleted, and which ones will be skipped and why (already gone from disk, located inside a zip archive, or a symlink). Nothing has happened yet at this point.

To proceed, type DELETE into the confirmation box and click the button. The files are removed one by one, with live progress and a Stop button. When the run finishes you get a per-file report; any file that could not be deleted (for example due to permissions) is listed with the exact error.

A delete run also cleans up after itself: every file it confirms gone, whether it just deleted it or found it already missing, is removed from the list automatically. The list stays a to-do queue of files that still exist, and the run history below it keeps the permanent record of what was deleted and when.

Deletion is permanent. PII Crawler removes files with the operating system's normal delete, it does not move them to a trash folder. If you might need a file again, use Quarantine files… instead, or take a backup before running the action.

Redacting files

Redact files… works the same way: preview, type REDACT to confirm, progress, per-file results.

For each file, PII Crawler takes every finding that is not marked as a false positive and overwrites those exact characters with *, keeping punctuation so the shape of the value stays recognizable:

Before:  Customer SSN: 123-45-6789, contact: [email protected]
After:   Customer SSN: ***-**-****, contact: ****@*******.***

The file's length, encoding, and everything around the masked values are preserved. Files are rewritten atomically (a temporary file is written and then swapped in), so a crash or power loss mid-run never leaves a half-written file. File permissions are preserved.

A few safety rules apply:

• Plain-text files only. Text formats such as .txt, .csv, .log, .json, or source code can be masked precisely. PDFs, Office documents, images, and archives are skipped with a "not a plain-text file" status; redacting those formats in place is not currently supported.
• Contacts, calendar and directory exports are masked where the value lies. A .vcf, .ics or .ldif file wraps a long value across two lines and may store it encoded, so a national ID in a contact note can be half on one line and half on the next. Redaction masks both halves and leaves the line break and the leading space of the fold alone, so the file still parses as the export it was. Outlook's =2D escapes are masked through, and a base64 directory value is decoded, masked and re-encoded, which keeps the value valid base64 and the file exactly as long as it was.
• Local files only. Files from a network share scan are skipped; redacting files in place over the network is not currently supported. Use quarantine or delete for share files instead.
• The content is verified first. Before masking, PII Crawler checks that the recorded finding still matches the bytes in the file. If the file changed since the scan, it searches for the known PII values and masks every occurrence it finds; if they are gone entirely, the file is skipped as "content changed since the scan" and left untouched.
• Some findings name the document, not text in it. A detected tax form says "this file contains a 1040"; the evidence is the whole page, so there is no span to mask and the form's boilerplate is public IRS wording rather than anybody's PII. Those findings are left alone, and they are not counted in the "masked" tally. A file whose findings are all of that kind is skipped as "nothing to mask" — a distinct status from "content changed since the scan", which means the file really was edited.
• False positives survive. Anything you marked as a false positive during triage is left exactly as it was.

After redacting, re-scan the affected folders if you want fresh results; the old scan's findings still describe the file as it was before masking.

Quarantining files

Quarantine is the reversible alternative to delete, and it works on every file delete works on, including the PDFs, Office documents, and images that redaction cannot process. Quarantine files… follows the same flow: preview, type QUARANTINE to confirm, progress, per-file results.

Each file is moved into the quarantine folder under a subfolder named after the run, with its original folder structure preserved:

Original:    /home/anna/exports/customers.xlsx
Quarantined: ~/.piicrawler/quarantine/run-000012/home/anna/exports/customers.xlsx

Files from a network share are mirrored under their server and share name, so a mixed run stays just as readable:

Original:    \\fileserver\hr\exports\customers.xlsx
Quarantined: ~/.piicrawler/quarantine/run-000012/fileserver/hr/exports/customers.xlsx

Because the original path is mirrored, you can always tell where a quarantined file came from just by looking at it, even without PII Crawler. The default quarantine folder is ~/.piicrawler/quarantine, which scans skip automatically, so quarantined files do not show up again in future scan results. You can point a run at a different folder in the preview dialog (or with --dest on the command line). When the destination is on a different drive than the file, the move falls back to copy-then-delete, and the original is only removed after the copy is fully written.

Encrypted quarantine

A quarantine folder concentrates files you have confirmed to contain PII, so by default it is only as safe as the machine it sits on. Check Encrypt the copies with a passphrase in the quarantine dialog (or pass --encrypt on the command line) and the run encrypts every copy as it is written, so the PII is effectively removed: without the passphrase the quarantined files are unreadable. For files coming off a network share, the encryption happens during the download, so their plaintext never touches the local disk at all.

The mirror keeps the same layout; each file just gains an .age extension, and the run folder holds one extra file, the run's protected key:

~/.piicrawler/quarantine/run-000012/identity.txt.age
~/.piicrawler/quarantine/run-000012/fileserver/hr/exports/customers.xlsx.age

Encrypted runs show an encrypted badge in the run history, and restoring one asks for the passphrase. A wrong passphrase is rejected before anything moves. The passphrase is never stored anywhere, which is the point: if you lose it, the copies cannot be recovered, by anyone. Choose one you can retrieve later (a password manager entry, for example) and treat it like the key to the data it protects.

Everything on disk is in the standard age format, so an encrypted run stays recoverable even without PII Crawler. With the stock age (or rage) tool and the passphrase:

age -d run-000012/identity.txt.age > identity.txt    # asks for the passphrase
age -d -i identity.txt run-000012/fileserver/hr/exports/customers.xlsx.age > customers.xlsx

Note that file and folder names stay visible; only contents are encrypted. If the names themselves are sensitive, keep the quarantine folder somewhere access-controlled. The run's key file is written readable only by the account that made the run.

An encrypted copy also keeps the permissions and modification time of the file it was made from, and a restore puts them back, so a file that was readable only by its owner is still readable only by its owner after a round trip — including while the restore is writing it, which is when a large file spends most of its time. A file quarantined from a network share has no local permissions to keep, since a share's permissions belong to the server, so its copy is written readable only by the account that made the run, encrypted or not. On the command line, piicrawler lists runs marks encrypted runs in its ENCRYPTED column, and lists run-show --json reports the same thing as an encrypted field, so a script can tell which runs need a passphrase to restore.

Like delete, a quarantine run removes the moved files from the list (the list stays a to-do queue of files still in place), and the run history keeps the permanent record, including where every file went.

Restoring quarantined files

Each quarantine run in the list's Recent runs table has a Restore… button. The preview shows how many files can move back; files are skipped if their copy is no longer in the quarantine folder or if a new file now occupies the original location (a restore never overwrites anything). Confirming moves the files back to their original paths and resurfaces them in the list, since their PII is intact again.

Quarantined network files are uploaded back to their original location on the share. The upload uses the credentials saved for that server and share, so a restore keeps working even after the scan that found the file has been deleted.

Symlinks

A symbolic link is a name for a file that lives somewhere else, so acting on the link would not do what the action says. Deleting or quarantining it would remove or move the name and leave the file, with all of its PII, exactly where it was. Redacting it would mask a copy and leave the original untouched.

So every action skips an entry that is a symlink, with an "a symlink" status, and tells you nothing was touched. The single-file Delete from disk action in the Files view refuses one for the same reason. Scan the file the link points to and act on it under its own path.

Directory scans never produce these entries: the scanner does not follow symlinks, so a link only reaches a list if you scanned it by name (piicrawler scan /exports/latest.csv where latest.csv points into an archive folder, for example).

Paths recorded by older scans

A scan records the full path of every file it finds, so the path still names the same file later, from wherever PII Crawler happens to be running when you act on it — a list run from your home directory, the web UI from a service that starts in /, a scheduled job from somewhere else again.

Scans made with older versions could record the path exactly as it was typed. piicrawler scan reports --save, run from /home/dana/q3, recorded reports/customers.csv rather than /home/dana/q3/reports/customers.csv — and that name means a different file in every folder. So entries from those scans are skipped by every action, with a "recorded with a relative path" status, and the single-file Delete from disk action in the Files view and the TUI refuses them for the same reason.

To act on those files, re-scan the folder by its full path (piicrawler scan /home/dana/q3/reports --save) and build the list from the new scan. Scans made with this version and later always record full paths, whatever you type.

Files with more than one name

A hard link is different from a symlink: it is not a shortcut to a file, it is a second name for the file itself, with equal standing. Backup tools, deduplicating copies and some publishing scripts all create them, and nothing about the file looks unusual.

This matters for remediation, because deleting or quarantining a file only removes the name you pointed at. The file itself lives on under its other names, with all of its PII, and no scan of the folder you named would have shown you that. So actions still run on these files, and the preview and the run report both tell you when a file has other names:

/exports/customers.csv - this file has 1 other name; the content stays readable there

Treat that as a to-do: the content is still readable somewhere, and finding where means searching the wider filesystem for files sharing that one's identity (find / -samefile /exports/customers.csv on Linux and macOS). PII Crawler does not go looking on its own, because that search covers the whole disk rather than the folder you asked about.

Redaction is the exception. It masks the values inside the file rather than replacing it, so every name for that file shows the masked content, and the run says so. That means a redact run can change what someone sees at a path that was never in your list, which is the correct outcome here: it is one file, and its PII is gone from all of it.

Link counts are read on Linux and macOS. On Windows the notice does not appear, and hard-linked files are handled the way they always were.

Files on network shares

Delete and quarantine work directly on the results of an SMB network share scan, using the credentials saved with the scan. There is nothing extra to set up: collect share files into a list the same way and run the action.

A few things work differently for share files:

• One connection check per share. At the start of a run, PII Crawler connects once to each share involved. If a share cannot be reached (server offline, password changed), every file on that share is reported with the connection error and nothing on it is touched. Files on other shares, and local files in the same list, are processed normally.
• Quarantine copies before it removes. Each file is downloaded into the quarantine folder first, and the copy on the share is only removed after the local copy is fully written and verified. An interrupted run can leave a duplicate, but never lose the only copy.
• Existence is checked at run time. While you browse a list, PII Crawler does not contact the share for every file, so share entries do not show the "file gone" badge. A file that has already disappeared from the share is reported as skipped by the run.
• Redact is not available. Masking PII in place over the network is not currently supported; those entries are skipped with an "on a network share" note. Quarantine covers the same need reversibly.

From the command line

The same lists and actions are available for scripting:

piicrawler lists create cleanup
piicrawler lists add --list 1 --scan 2 --file 10 11 12
piicrawler lists show 1
piicrawler lists run --list 1 --action redact --dry-run   # preview only
piicrawler lists run --list 1 --action delete --yes       # no prompt
piicrawler lists run --list 1 --action quarantine --yes   # move to ~/.piicrawler/quarantine
piicrawler lists run --list 1 --action quarantine --dest /mnt/holding --yes
piicrawler lists run --list 1 --action quarantine --encrypt --yes   # encrypted copies
piicrawler lists restore 12 --dry-run                      # preview restoring run 12
piicrawler lists restore 12 --yes                          # move run 12's files back
piicrawler lists runs                                      # past runs
piicrawler lists run-show 3                                # one run's per-file outcomes

The examples above mix bare IDs (lists show 1) with flags (lists run --list 1) because that is how the commands read most naturally, but both spellings work everywhere: lists show --list 1 and lists run 1 --action redact are the same commands. See Naming a scan, a list, or a run by ID. The one exception is lists add, which names a list and a scan at once and so always labels them.

run without --yes asks for confirmation on a terminal and refuses in scripts, so an unattended pipeline can never delete files by accident. Every run, including dry runs, is recorded with per-file outcomes you can inspect later.

--encrypt prompts for the passphrase (twice, hidden); restoring an encrypted run prompts once. Scripts set the PIICRAWLER_PASSPHRASE environment variable instead of a prompt.

Limits

• Files on network shares can be deleted and quarantined, but not redacted; redaction works on local files only.
• Files inside zip archives cannot be deleted, redacted, or quarantined individually; act on the archive itself if needed.
• Symlinks are skipped by every action; act on the file the link points to.
• Entries whose path was recorded relative to an older scan's working directory are skipped by every action; re-scan the folder by its full path.
• One add operation can submit up to 50,000 files, and a list can hold up to 100,000 entries.
• Only one action can run per list at a time.