The complete ProtoScan guide

What you need to install ProtoScan

ProtoScan runs as a lightweight service on a single Linux host. There is nothing to install on the devices it scans — discovery happens entirely over the network using the protocols your equipment already speaks.

Host requirements

Installed automatically

You don't need to prepare any of this yourself — the installer pulls everything in for you:

• System packages: python3, python3-venv, python3-pip, nmap, sqlite3, libcap2-bin, and snmp.
• Python dependencies (in an isolated virtual environment): Flask, Gunicorn, bcrypt, the cryptography library (for the encrypted credential vault), pysnmp, pyotp/qrcode for two-factor auth, and more.
• Raw-socket capability on nmap (cap_net_raw) so scans run without the app itself needing root at runtime.

How to install

Installation is a single command. The installer downloads the release, verifies its SHA-256 checksum, and runs the on-host setup script. Run everything as root (with sudo).

Step 1 — Run the installer

Download and execute the installer in one line:

curl -fsSL https://protoscannetwork.com/releases/install.sh | sudo bash

Prefer to inspect it first? Download, read, then run it — always a good habit for any script piped to a shell:

wget https://protoscannetwork.com/releases/install.sh
less install.sh          # review it
sudo bash install.sh

Step 2 — What the installer does

Behind the scenes the installer performs a complete, repeatable setup:

• Installs the required system packages.
• Creates a dedicated, unprivileged protoscan service user.
• Lays the app down in /opt/protoscan with config in /etc/protoscan.
• Builds a Python virtual environment and installs all dependencies.
• Grants nmap the cap_net_raw capability for scanning.
• Generates a random first-run admin password and registers a systemd service (served by Gunicorn).
• Enables and starts the service, then prints a summary.

Step 3 — Log in

When the installer finishes it prints the access URL and a temporary admin password. Open the app in a browser:

# ProtoScan is installed and running
  URL:      http://<your-server-ip>:8000
  Username: admin
  Password: <generated at install>
  Config:   /etc/protoscan
  Database: /opt/protoscan/protoscan.db

1. Browse to http://<your-server-ip>:8000.
2. Sign in as admin with the password from the summary.
3. You'll be prompted to set a new password on first login. Choose a strong one.
4. Head to Subnets and add your first range — see Subnet scans.

Managing the service

ProtoScan runs as a standard systemd service, so the usual commands apply:

sudo systemctl status protoscan     # is it running?
sudo systemctl restart protoscan    # restart
sudo journalctl -u protoscan -f     # follow logs

Updating & uninstalling

ProtoScan checks for new releases and surfaces an update badge in Settings when one is available. To update, simply re-run the installer — your configuration and database are preserved. To remove ProtoScan completely:

sudo bash /opt/protoscan/uninstall.sh

What each menu does

The navigation bar runs across the top of the app. Here's what every menu is for and what you can do inside it.

How to set up subnet scans

A subnet scan is how ProtoScan discovers and fingerprints devices. You point it at a CIDR range and it sweeps the range, identifies what's there, and feeds the results into Inventory and Topology.

Add a subnet

1. Open the Subnets menu and click Add Subnet.
2. Enter the range in CIDR notation, e.g. 192.168.1.0/24 or 10.0.20.0/24.
3. Give it an optional label and description so it's easy to recognise later (e.g. "HQ — Servers VLAN").
4. Save. The subnet now appears in the list, ready to scan.

Run a scan

Click Scan on a subnet to start discovery immediately. ProtoScan will:

• Sweep the range to find live hosts (ICMP / ARP / nmap).
• Fingerprint each host — OS detection, open ports and services.
• Pull deeper detail over SNMP where credentials are configured (make, model, serial, interfaces, neighbour tables).
• Correlate LLDP/CDP/ARP into topology links.

Watch it happen live in the Logs menu, or check the Overview counters as they climb.

Schedule recurring scans

Manual scans are fine to start, but a network changes constantly. Enable a scheduled scan on a subnet so ProtoScan re-discovers it periodically, keeping inventory and topology continuously fresh and feeding the monitoring loop. Set the cadence that fits the subnet — busy access networks benefit from more frequent sweeps than a stable server VLAN.

Configuring vendors & API keys

Beyond generic SNMP discovery, ProtoScan integrates directly with vendor controllers and firewalls for richer, first-class data. You configure these under Settings → Vendor Configuration.

Supported integrations

Add a vendor configuration

1. Go to Settings → Vendor Configuration and start a new configuration.
2. Give it a Configuration Name you'll recognise.
3. Pick the Vendor (UniFi, Cisco Meraki or Palo Alto). The form adapts to show only the fields that vendor needs.
4. Enter the Controller URL / Firewall Host and the API Key (and organization/site for Meraki, or username/password where applicable).
5. Save. ProtoScan validates the connection and begins enriching matching devices on the next scan.

Credential management

ProtoScan keeps two kinds of secrets, both encrypted at rest with Fernet symmetric encryption: SNMP credentials used for discovery, and a general-purpose credential vault used by the web terminal and device connections.

SNMP configuration

Under Settings → SNMP Configuration, add the SNMP credentials ProtoScan uses to read device detail and neighbour tables (MAC tables, LLDP, CDP). You can store more than one for networks with mixed SNMP setups.

The credential vault

Under Settings → Credentials, click Add Credential to store login secrets that ProtoScan uses when you connect to a device (for example via the in-browser web terminal). Each entry has:

• Label — a friendly name for the credential.
• Protocol — SSH, Telnet, SFTP, FTP, RDP, VNC, WinRM, Domain (AD) or Other.
• Username and Password / Secret.
• Notes — optional context.

When you open Connect on a device, ProtoScan uses a matching vault credential to establish the SSH or Telnet session — so you don't retype passwords, and they're never exposed in the browser.

Settings, end to end

The Settings menu is where everything is configured. Here's the full map of what lives there.

Account & security

• Change Your Password — update the password for your own account at any time.
• Two-Factor Authentication — enable TOTP. Scan the QR code with an authenticator app (Google Authenticator, Authy, 1Password, etc.) and verify a code to turn it on. Strongly recommended for admin accounts.

Users & roles

• Add User — create additional logins.
• Roles — Admin (full access) or Viewer (read-only). Give day-to-day staff Viewer access and reserve Admin for those who manage configuration.
• Users can be disabled without deleting them, and you can force a password change.

Discovery & integrations

• SNMP Configuration — credentials for device discovery (see section 6).
• Vendor Configuration — UniFi, Meraki and Palo Alto integrations (see section 5).
• Credentials — the vault for SSH/Telnet/RDP and more (see section 6).

Notifications

• Notification Profiles — define where alerts are delivered. Supported channels include Email (SMTP host, port, security via TLS/STARTTLS, and credentials), Slack incoming webhooks, and Discord webhooks.
• Alert rules in the Alerts menu point at these profiles, so you can route different alerts to different places.

Appearance

• Theme — ProtoScan ships with several built-in themes (including glass, aurora, cyber and phosphor styles) plus light and dark variants. Pick whatever suits your control room or NOC display.

System & updates

• Software updates — ProtoScan checks for new releases and shows an update badge on the Settings menu when one is available. Re-run the installer to update in place.
• Binding & access — the host and port the app listens on (default 0.0.0.0:8000), rate limiting, and trusted-proxy count are defined in /etc/protoscan/security_config.json for advanced deployments behind a reverse proxy.