Censusby Steward IT

Documentation › Inventory

Remote scanners

A remote scanner scans the networks of another site (a branch office, a warehouse, a second building) for your Steward IT Census server. You install it on one always-on computer at that site. It runs the scans of that site's scan targets locally and sends the results to the server, where they appear like any other asset.

Remote scanners are included with your license: there is no extra charge per site. The devices they find count toward your license like any other asset.

How it works#

  • The scanner connects out to the server. Nothing at the site needs an open port.
  • It only collects. The server decides which credentials to use for which device, recognizes agents, applies MAC vendors and type rules, and stores the results, exactly as for its own scans.
  • Each scanner has its own identity: it creates a key pair when it's installed and signs every request with it. Only the public half is sent to the server. There is no shared password, and deleting the site on the server shuts the scanner out immediately.
  • A scanner only receives the credentials you allow for it (see Credentials).

Reaching the server#

The scanner must reach the server's address (the Server address in General settings):

  • Over your VPN or site-to-site link (most companies have one). Nothing is exposed to the internet.

  • Without a VPN, turn on the port for remote sites on the Remote scanners page (tick Open a separate port for Census agents and remote scanners, choose the port, default 9443, and Save). It starts right away and again after every restart. Then forward only that port from your internet router/firewall to the server. The same port also suits networks separated by a firewall or VLAN rules where you'd rather not allow the main port: allow only this one between them.

    That port serves only Census agents and remote scanners: no web interface, no login page, no administration. Restrict it on your firewall to the public addresses of your sites if you can. The server opens the port in its own firewall: a Windows Firewall rule on Windows, or a ufw / firewalld rule on Linux when one of them is active (it removes the rule again when you turn the port off). If the Linux server uses another firewall, the page tells you to open the port there. Install the scanner with that port in the server URL, using the address the scanner reaches the server on: the public address or name over the internet (https://census.example.com:9443), the server's LAN address or name when the site reaches it across VLANs, firewalled networks or a VPN (https://192.168.10.5:9443). A scanner that can reach the main port (8443) can keep using it. Census agents on laptops outside the office can use the same port.

    Keep the server updated while the port is on. The port serves only Census, so it's Census's own code that faces the internet, plus the operating system underneath it. The panel shows when the operating system was last updated (Linux: the package database; Windows: Windows Update). When the port is on and the operating system hasn't been updated for more than 60 days, administrators get a warning on the dashboard and other main pages until it's updated. Turn on automatic security updates (unattended-upgrades, dnf-automatic, Windows Update).

    Upgrade Census too when new versions come out: security fixes in Census and in the runtime it's built with reach your server only through Census updates. While the port is on, a newer release found by the daily version check (General settings › Updates) turns the notice into the same red warning.

    For scripted installs, census-server install -device-listen :9443 sets the port from the command line instead (it then can't be changed on the page).

    Scanner certificates on this port. Each scanner (version 0.32.0 or later) automatically gets its own client certificate from the server when it starts, and renews it before it expires (they're valid for a year). From then on, the server refuses that scanner's requests on the port for remote sites unless they come with that exact certificate, so someone who copied a scanner's keys still can't use them from elsewhere. The Remote scanners page shows each scanner's certificate (🔒 and its expiry date). Deleting a site, installing its scanner again or issuing a new certificate makes the old one stop working. The certificate authority that signs them (scanner-ca.crt / scanner-ca.key in the data folder) is included in backups. Census agents connect without a certificate, as before. The main port never asks for certificates, so browsers there aren't affected.

    If a scanner was off long enough for its certificate to expire, or the server was restored from a backup, the scanner gets a new certificate on its own. A site gets at most one new certificate an hour (unless its current one is about to expire).

    The page warns you when something is wrong:

    • Requests arrive without its certificate: something between the site and the server decrypts the connection, such as SSL inspection on a firewall or a reverse proxy in front of Census. Exclude Census's port from decryption there (most firewalls have an exception list for SSL inspection). The scanner can't work through it until then.
    • Requests arrive with an older certificate of this site: a copy of the scanner is probably running on another computer, for example a cloned virtual machine. Uninstall the copy. After a server restore, this message goes away by itself.

Adding a site#

  1. Scanning › Remote scanners › Add a site. Give it a name (e.g. Denver office).

  2. You get a one-time install command for Windows and Linux. The token in it works once and expires after 24 hours. It's shown only then; Install… creates a new one.

  3. On the scanner computer, download the matching census-scanner-* file (listed on the page; copy the files from the release into the server's agents data folder first) and run the command as administrator (Windows) or with sudo (Linux):

    census-scanner-windows-amd64.exe install -server https://census.example.com:8443 -token CSE1-… -fingerprint 4B0F…
sudo ./census-scanner-linux-amd64 install -server https://census.example.com:8443 -token CSE1-… -fingerprint 4B0F…

    It enrolls with the server, installs itself as the Census Remote Scanner service and shows up as online within a minute. The fingerprint pins the server's certificate.

  4. Under Scanning › Credentials, tick the site under Allowed on remote scanners on each credential it may use.

  5. Add the site's ranges as scan targets and choose the site under Scanned by.

Installing it with a deployment#

If Census already manages the scanner computer (a Census agent on it, or a working WinRM/SSH credential), skip the steps above: choose 🛰 Install Census Remote Scanner as the package under Deployment › New deployment (also Install remote scanner here on the computer's page, or the link on the Remote scanners page). Census creates the site, puts its one-time token into that computer's install command and runs it through the Census agent, or WinRM/SSH when the agent isn't online. Each computer becomes a site of its own, named after the computer (or the name you enter when it's one computer). Administrators only; Windows and Linux computers. Then continue with steps 4 and 5.

Use one scanner per site. A small always-on PC, a server or a Raspberry Pi-class Linux machine is enough. Builds are provided for Windows (Intel/AMD and ARM) and Linux (Intel/AMD, 64-bit ARM and 32-bit ARM).

Credentials#

A remote scanner never receives a credential unless you allowed it for that site: Scanning › Credentials › Edit › Allowed on remote scanners. That's true for global credentials too: a global credential is not sent to remote scanners until you tick the site.

When it is allowed, the server sends it:

  • only for the scan of a target assigned to that site, and only for devices that can use it (Windows logins only to devices with WinRM open, SSH logins only to devices with SSH open);
  • encrypted for that one scanner, on top of HTTPS: with X25519 + ML-KEM-768 (post-quantum, scanners 0.51.1 and later; shown as 🔒 post-quantum on the page), so recorded traffic stays secret even against a future quantum computer;
  • kept in memory only for the duration of the scan, never written to disk at the site.

Every credential sent is recorded in the site's audit log (Log on the Remote scanners page), with the scan it was for.

Use a scan account with rights at that site only, for example an account that is local administrator only on that site's computers (set by group policy), or LAPS-managed local administrator passwords. Never Domain Admin. A scanner has to use the real password to log in, so whoever fully controls the scanner computer could get it. A compromised branch machine must not expose your whole network.

Active Directory at a remote site#

If a site has its own domain controller that this server can't reach, its scanner can read it:

  1. Add an Active Directory (LDAP bind) credential (a read-only domain user is enough) and tick the site under Allowed on remote scanners.
  2. Scanning › Active Directory & Entra ID › Add Active Directory domain, and choose the site under Domain controller reached from.

At each sync, the server sends that credential, encrypted for the scanner, which reads users, groups and computers from the domain controller and sends them back. The audit log records each sync. With Also scan AD computers, those computers are scanned by the site's scanner too. The scanner needs version 0.32.0 or later and must be online.

Signing in to the help desk portal or to Census with accounts of such a domain isn't possible: the user's password would have to pass through the scanner.

Help desk at a remote site#

The help desk portal is part of the web interface, which the scanner never relays. People at a site that can't reach the server send requests by email instead: set up Email to ticket, and their messages become tickets like any other.

Sites reuse addresses#

Different offices often use the same private ranges (192.168.1.x). Census keeps them apart: a device found by a site's scanner belongs to that site (shown on the asset's Summary), and matching by IP address only looks within the same site. Devices with a serial number or MAC address are still recognized wherever they appear (for example a laptop that moved between offices). So is a computer whose Census agent reports to the server directly: a site's scan finds it by its name together with one of its addresses (the scanner's own computer, too), and doesn't move it into the site.

For the same reason, the server never logs in to a remote-site asset itself: that address could belong to a different machine on the server's own network. Rescan now on such an asset (or several) runs on that site's scanner, and management goes through the scanner or the Census agent (next section).

Managing the site's computers#

With Manage computers on for a site (the default; the switch is on the Remote scanners page and on Add a site), everything the server would otherwise do over WinRM/SSH runs through the site's scanner for computers without a connected Census agent:

  • deployments and scripts, including Install Census agent;
  • actions (remote commands), the Console, service start/stop, uninstalling software;
  • screenshots and the logged-on user / locked status on the asset page;
  • Wake-on-LAN: the packet is sent on the site's own network.

A computer with a connected Census agent always uses its agent. The scanner uses the same credentials it may use for scanning (Allowed on remote scanners on the credential), sealed for it and sent only for the task; each one is in the site's audit log.

Installers and scripts reach the computer through the scanner#

The site's computers don't need to reach the Census server, or even know its name. For each deployment, script or Console command, the scanner downloads the file from the server itself, checks it against its SHA-256, and hands it to the computer:

  • Linux and macOS (SSH): copied over the same SSH connection into a private temporary file;
  • Windows (WinRM), up to 1 MB (scripts, Console commands, small installers): copied in pieces over WinRM;
  • Windows, larger installers: the computer downloads it from the scanner over HTTPS, at a one-time address that only exists while that task runs. The scanner opens a firewall port for it on its own computer for that time (Windows Firewall, or ufw/firewalld on Linux when the scanner runs as root), so the computer must be able to reach the scanner's address on its network.

The computer checks the SHA-256 again before running anything, runs it as before, and the temporary copy is deleted afterwards. Scanners before version 0.54.0 instead let the computer download the file from the server address the scanner uses: update the scanner (Remote scanners › Update) if deployments at a site fail with "download failed".

Census agents at a site that can't reach the server (agent relay)#

A Census agent normally connects to the server itself. When a site's computers can't reach the server (another network or domain, a firewall that only lets the scanner out, a server name they can't resolve), turn on the site's Agent relay on the Remote scanners page:

  • The scanner listens on a port of its own computer (9443 unless you change it) and passes each agent connection on to the server unchanged. The connection stays encrypted end to end: agents still check the server's certificate, and the scanner can't read or alter what they send.
  • It forwards only to the server's port for remote sites (see Reaching the server), which serves agents and scanners and never the web interface or login page. That port must be on; the relay stays off until it is.
  • The scanner opens its relay port in its own firewall (Windows Firewall, or ufw/firewalld when it runs as root on Linux) and closes it when the relay is turned off.
  • Install Census agent for a computer at that site uses the scanner's address on that computer's network automatically. For manual installs, the relay window lists the addresses to use as the server address (https://<scanner address>:9443).
  • Agents installed earlier with another server address keep using it: reinstall them to switch.
  • Computers whose agents report through the relay belong to that site, so when their agent is offline, Census manages them through the scanner.
  • The Agents page shows the scanner's address as these agents' address, because their connections come from it.

The relay needs scanner version 0.55.0 or later.

Turn Manage computers off when the scanner runs on a computer you can't fully trust, for example a user's desktop at a small site without a server. Through the scanner, Census runs installers and commands with the site's credentials, so anyone with administrator access to that computer could intercept those credentials or misuse that access. With management off, the site's computers are managed only through the Census agent.

On an untrusted computer, also allow no credentials. Scanning sends the site's allowed credentials to the scanner as well. On a computer you don't trust, turn management off and don't tick the site on any credential. The scanner then only discovers devices (addresses, open ports, MAC vendors, web pages), and you manage the site's computers through the Census agent (USB installer or your software distribution).

Online / offline on the asset page and Ping / check ports are checked by the site's scanner on its own network (within a few seconds; no credentials are involved, so this works with Manage computers off too). When the scanner is offline, the status shows Status unknown: the server never checks a remote-site address itself.

Status, updates and alerts#

The Remote scanners page shows each site's status (online, offline with the last contact, or waiting for install), the scanner computer, its version and address, and how many scan targets use it.

  • Update appears when a newer census-scanner build for that scanner's system is in the server's agents folder. The scanner downloads it (checked by SHA-256) and restarts itself within a minute or two. The page follows it: updating to …, then updated to …, or a warning when it hasn't come back with the new version after 10 minutes (with Try again).
  • Move… creates a new install token to move the site to another computer: the current scanner keeps working until the new one enrolls with the token.
  • Delete shuts the scanner out. Move or delete the site's scan targets first, so they never fall back to scanning (and sending credentials) from somewhere unexpected. The audit log is kept.
  • Add an alert of type Remote scanner offline (Configuration › Alerts & scheduled reports) to get an email when a scanner stops reporting.

A scan queued while its scanner is offline waits up to 6 hours, then fails with the remote scanner did not pick up this scan.

Uninstalling a scanner#

On the scanner computer: Control Panel › Programs (Windows) or sudo census-scanner uninstall (Linux). This removes the service, the program and its keys. Then delete the site on the Remote scanners page if it's no longer needed.

Command reference#

census-scanner install -server URL -token TOKEN [-fingerprint FP]   enroll and install the service
census-scanner uninstall
census-scanner start | stop | status
census-scanner run        run in the foreground
census-scanner enroll -server URL -token TOKEN [-fingerprint FP]    only enroll (containers, testing)
census-scanner version

The configuration (server address and the scanner's private keys) is in C:\ProgramData\CensusScanner\scanner.json (folder readable by SYSTEM and Administrators only) or /etc/census-scanner.json (root only).