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).

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, or located inside a zip archive). 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.
• 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.
• 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.

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.

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 simply 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

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.
• 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.