26.5 · May 4 Try it free →
Guides

Scan an SMB Network Share

Last updated April 2026

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.

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 with AES-256-GCM under a 32-byte data-encryption key (DEK). The DEK never sits on disk in plaintext. It's wrapped under a key-encryption key derived (via Argon2id) from a credential password you choose. Someone who steals just the SQLite database 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 DEK then stays in memory 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 once unlocked. It will be reused for future scans of the same share.

Headless deployments (server, watch mode, CI)

Set PIICRAWLER_CRED_PASSWORD in the environment to unlock credentials automatically the first time they're used. If your pipeline already manages its own raw key, set PIICRAWLER_CRED_KEY_BASE64 instead. That injects a 32-byte base64 DEK directly and skips the password prompt entirely, which is handy for CI tests against an isolated database.

The web UI also exposes the unlock flow over HTTP for orchestration:

  • GET /api/cred/status returns {is_set, is_unlocked}.
  • POST /api/cred/unlock {password} unlocks the running server.
  • POST /api/cred/lock drops the cached DEK without restarting.
  • POST /api/cred/password {password} (first-time set) or {current_password, password} (change).

These endpoints sit behind the regular web-login session. Once you're logged into the web UI you can call them.

Changing the credential password

Use the web UI (POST /api/cred/password with both current_password and password). The change re-wraps the DEK under your new password without re-encrypting any saved credentials, so it's instant no matter how many credentials you have stored.

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.
  3. Press Alt+C to cycle through saved credentials, or leave it on None (anonymous) for guest shares.
  4. Tune the throttle row if you need to (see Throttling below).
  5. Press Enter to start.

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.

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.

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.

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

Troubleshooting

Connection failed with a logon error: 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.

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.

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.

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.

Was this page helpful?