Scan an SMB Network Share

PII Crawler can scan an SMB / CIFS file share (a Windows shared folder, a Samba server, or a NAS) over the network. Files are read in over SMB2/3, scanned in memory, and discarded right after. The share is never mounted, so you don't need root or fstab edits.

This guide covers doing it from the TUI and the web UI. SMB scanning isn't available as a piicrawler scan CLI command yet, so use the TUI or web UI to set it up.

What you'll need

SMB support is built into the PII Crawler binary. You don't need to install smbclient or Samba on Linux, macOS, or Windows. The same binary works the same way on all three.

You'll need:

• The server hostname or IP (for example fileserver01 or 10.0.0.42).
• The share name (for example Public, Finance, home$). PII Crawler doesn't enumerate shares on a server, so you'll need to know the name ahead of time or ask whoever administers the server.
• Credentials: a username and password, plus a Windows domain or workgroup if the share requires one. NTLM authentication is used; Kerberos isn't supported yet.

Save a credential (recommended)

Saving credentials once means you don't re-enter them every time you re-scan, and the password never goes into your shell history.

How credentials are protected

SMB credential passwords are encrypted at rest with AES-256-GCM, under a key protected by a credential password you choose (strengthened with Argon2id). Someone who steals just the database file can't read any stored secrets without your credential password.

The credential password is separate from the web-login password. They protect different things. You can use the same string for both if you want, but nothing forces it.

There is no recovery. If you forget the credential password, every saved SMB credential becomes unreadable. Pick something you'll remember (or store it in a password manager) before you save your first credential.

The first time you open the SMB Credentials screen (TUI) or the Settings → Network Share Credentials section (web UI), you'll be prompted to set the credential password. On later app launches you'll be prompted to unlock with the same password the first time anything in the session touches stored credentials. The store then stays unlocked until the app exits.

Credential scope

You can scope a credential two ways:

• Share-specific: set the share name when creating the credential. Used only when scanning that exact share.
• Server-level: leave the share name blank. Used as a fallback for any share on that server when no share-specific credential exists.

TUI

1. From the scan list, press c to open SMB Credentials.
2. If this is your first time, you'll be prompted to set a credential password. Type it twice and press Enter. On later launches you'll be prompted to unlock with the same password instead.
3. Press n to add a new credential.
4. Fill in Server, Share (blank for server-level), Domain (optional), Username, Password. Tab moves between fields.
5. Press Enter to save. d deletes the selected credential.

Web UI

Open Settings → Network Share Credentials. Your first visit shows the Set credential password form. After that, you'll see the Unlock credentials form. Enter your password to access the credential add form and the saved-credentials table.

You can also save a credential inline from the new-scan form. If you haven't set the credential password yet, or the session is locked, the new-scan form pops up the same set-password or unlock dialog before saving, so you do not need to detour through the Settings page first.

Headless deployments (server, watch mode, CI)

Set PIICRAWLER_CRED_PASSWORD in the environment to unlock credentials automatically the first time they're used.

See CLI Reference → Environment variables for the full list of variables PII Crawler reads. A running server can also be unlocked over HTTP, which suits orchestration tools; see Credential store HTTP endpoints.

Changing the credential password

There is no form for this in the UI yet; change it through the running server's credential store HTTP endpoint, passing your current and new passwords. The change is instant no matter how many credentials you have stored, and none of them need re-saving.

Start a network scan

TUI

1. From the scan list, press N (capital N) to open New Network Share Scan.
2. Fill in:
   • Server: hostname or IP.
   • Share Name: the share to scan.
   • Subfolder (optional): restrict the scan to a path inside the share, for example Departments\Finance\2024. Use backslashes; forward slashes are accepted and converted.
   • Scan Name (optional): defaults to \\server\share\subfolder if left blank.
   • Exclude Patterns (optional): comma-separated exclusion patterns matched against the path inside the share.
   • Extensions Filter (optional): comma-separated list, for example csv, pdf. Blank scans every supported type.
   • Max File Size MB (optional): blank means no limit. A bare number is megabytes; a smaller or larger ceiling can be written with its own unit, as 500KB or 2GB.
3. Press Alt+C to cycle through saved credentials, or leave it on None (anonymous) for guest shares.
4. Pick the data types to look for in the PII Types panel on the right: Up/Down moves the cursor, Alt+Space turns the type under it on or off. It starts on the default set.
5. Tune the throttle row if you need to (see Throttling below).
6. Press Enter to start.

On a short window the form shows the fields it has room for and scrolls to the one you are typing into, and its bottom border says which part of the list you are looking at (fields 1-5 of 8). Alt+C scrolls to the credential selector as it cycles it.

The filter fields and the PII-type selection belong to this form: they are what the scan runs with and what is recorded on it, so the scan page reports them and a resume repeats them. A pattern that is not a valid regular expression, or a size the field cannot read, is refused while the form is still up.

The status bar shows two phases: enumerating (walking the share recursively) and then scanning (downloading and analyzing each file). Press s to stop a running scan, and R to resume it later. A resumed scan picks up where it stopped, reading the rest of the files from the same share and with the same settings it was started with.

Web UI

1. Click Create New Scan, then choose the Network share (SMB) scan type.
2. Enter the server hostname/IP and the share name you want to scan. If you don't know what share names exist on the server, ask whoever administers it. PII Crawler does not enumerate them.
3. Either pick a saved credential, or type a username, password, and (optionally) domain.
4. Click Test to verify the server, share, and credentials all work together. A green banner confirms success; a red banner shows the SMB error verbatim.
5. Optionally use the subfolder browser to drill into a specific path inside the share, set a scan name, and start the scan.

Command line

For servers, containers, and CI where no browser or interactive terminal is available, the smb subcommand runs the same scan headlessly:

piicrawler smb fileserver Finance -u alice --subfolder HR/2025 --quiet

The connection is tested up front, so a bad host or credential fails fast with no scan record left behind. The results are saved to the local database like any other scan, and the new scan ID is printed to stdout for use with report and findings. The password comes from -p/--password or the PIICRAWLER_SMB_PASSWORD environment variable. With a username and neither of those, the connection sends a blank password, which is what a guest share takes, and the scan prints a note saying so. A password or a domain with no username is refused instead: there is no account to authenticate as. Unlike the TUI and web UI, the CLI does not persist the credential to the database. See the smb command reference for the full flag list and throttle controls.

Throttling network scans

Network scans have three throttle controls that local-disk scans don't need. The defaults are conservative. Raise them if your link and the file server can handle it.

Setting	What it does
Max Concurrent	Number of files downloaded and scanned in parallel. Higher is faster, but opens more SMB sessions.
Delay (ms)	Pause between starting each file read. Useful on shared links or older NAS hardware.
BW Limit (MB/s)	Soft cap on aggregate download bandwidth. PII Crawler tracks bytes pulled and waits when you're over budget.

A reasonable starting point for a LAN file server: 4 concurrent, 0 ms delay, no bandwidth cap. For a slow VPN to a remote office, try 2 concurrent, 100 ms delay, 5 MB/s.

The web UI's New Scan form also sets how many times a failed read is retried and how fast the wait between retries grows. The defaults are 3 attempts and a multiplier of 2, which means a second try after half a second and a third after one second.

These settings are saved with the scan, along with the worker count. Stopping a scan and resuming it later reads at the same rate you set up, and so does re-running it from a different place: a scan you deliberately slowed down for a VPN link will not come back at LAN speed because it was resumed from the TUI instead of the web UI. The scan page shows what a scan reads with under Scan Configuration.

What gets scanned

• The walker recurses through every directory under the chosen subfolder.
• Files larger than the configured max file size are skipped, as are extensions that aren't in the allowed list and any path that matches an exclusion pattern. Leave the size blank for no limit. The scan page reports how many files each filter skipped on the last run.
• Each remaining file is read into memory over SMB, run through the same extraction and detection pipeline as a local scan, and dropped right after.
• Findings reference the file with its UNC path (\\server\share\path\to\file.pdf) so you can locate the source from any SMB-aware tool.

Acting on the results

Once triage has confirmed which share files genuinely contain PII, collect them into an action list from the scan's Files view. Delete and quarantine run directly against the share with the same saved credential; quarantine pulls the files into a local holding folder and can restore them to the share later. See Files on network shares for the details.

Folders you can't access

A network scan walks the share with whatever permissions the scanning account has. When it reaches a folder that account can't read, it does not stop the scan. The folder is recorded as an entry with an error status and a "permission denied" reason, and the walk continues with the rest of the share.

This is what you want when you are auditing what a given account can actually reach. Run the scan as a standard user and the protected folders show up in the results as inaccessible, while everything that account can open is scanned normally. To see them, open View Files and filter by the error status, or read the error breakdown on the scan report, which tallies a "permission denied" count.

One exception: if the share itself can't be reached at all (server down, wrong share name, or the account has no access to the share root), the scan fails up front rather than reporting an empty result. Only folders inside a reachable share are recorded-and-skipped this way.

Troubleshooting

Every failed connection says why it failed, after the share it could not reach: Could not connect to \\fileserver\Finance: the server rejected the username or password (STATUS_LOGON_FAILURE). The entries below are the reasons you are most likely to see.

The server rejected the username or password (STATUS_LOGON_FAILURE): wrong username, password, or domain. If the share belongs to an Active Directory domain, the Domain field has to match. For a workgroup share, leave it blank. Kerberos-only realms aren't supported yet, so the account needs to accept NTLM. From the command line, check that PIICRAWLER_SMB_PASSWORD is set in the shell you are actually running in: sudo and most cron setups drop it. When it was not set, the message says so itself, and adds The password sent was blank, because --password was not given and PIICRAWLER_SMB_PASSWORD was empty or unset.

The server has no share by that name (STATUS_BAD_NETWORK_NAME): the share name is wrong, or the user doesn't have access to it. Double-check the share name (case sensitivity varies by server) and verify the credential has read access to that share.

The account is not allowed to open this share (STATUS_ACCESS_DENIED): the credentials were accepted, so this is a permission problem on the share itself rather than a bad password. Check the share permissions for that account.

Connection refused, or the name does not resolve: nothing answered on port 445, so the server was never reached. Check the hostname or address, that the file server is up, and that the network between you and it allows SMB.

Scan is very slow: most of the time on a network scan is spent reading bytes. Increase Max Concurrent and remove any bandwidth cap if your link can handle it. If the file server itself is the bottleneck, lowering concurrency may actually help by avoiding queueing. To pinpoint specific files that are dragging the scan down, open the scan in the Web UI's View Files page and click the Duration column header. Files sort by per-file scan time, slowest first.

Files keep failing with Download failed: transient SMB errors are retried automatically, but a persistent failure usually means a permission problem on a specific file. Check the Logs view (press l from the TUI scan list) for the underlying error.

Scan finishes with fewer results than expected: folders the scanning account can't read are skipped and recorded as error entries rather than scanned (see Folders you can't access). Filter View Files by the error status to see exactly which paths were inaccessible. If you expected to reach them, re-run with an account that has read access to those folders.