Network Scan

Automate your infrastructure inventory with zero manual data entry.

Stop manually typing IP addresses. pharos-scan is the high-performance network discovery tool built for the Pharos ecosystem. It uses mDNS and intelligent TCP-based port fingerprinting to identify every node in your lab and provision them into your registry with a single keystroke.

How it Works

pharos-scan isn’t just a network ping. It implements a multi-stage discovery engine:

  1. mDNS Discovery: Instantly finds services like SSH, Proxmox, Home Assistant, and Plex.
  2. Port Fingerprinting: Probes common ports (22, 80, 443, 8006, 32400) to identify the role of unknown devices.
  3. Inventory Cross-Check: Queries your Pharos server to see if the device already exists, highlighting new or changed assets.

Interactive TUI Discovery

The best way to use the scanner is via its interactive Terminal User Interface (TUI).

# Start the discovery engine
./pharos-scan

The Workflow

  1. Scan: The tool lists all discovered nodes with their IP, hostname (if available), and detected services.
  2. Select: Use the arrow keys and Space to select the nodes you want to add to your Pharos registry.
  3. Provision: Press Enter to start the provisioning process.
  4. Metadata: The tool will prompt you for an alias and owner for each node.
  5. Commit: pharos-scan automatically calls the mdb client with your authorized SSH key to register the new assets.

Advanced Usage

Targeted Scans

When mDNS discovery isn’t enough (e.g. devices that don’t advertise mDNS services), scan a specific CIDR block directly by passing it as an argument:

# Scan the management VLAN directly
./pharos-scan 10.10.10.0/24

This probes every address in the subnet for common ports (22, 80, 443, 8006, 32400) instead of waiting for mDNS announcements — a host with none of those ports open won’t be detected this way.

Every live host found this way is automatically enriched, best-effort, with its MAC address (read from the OS’s ARP cache — no raw sockets or elevated privileges needed), manufacturer (resolved from the MAC’s OUI prefix), and hostname (reverse DNS) when available, alongside the same port-fingerprinting used for mDNS-discovered nodes.

Scripted Discovery (JSON Output)

For scripting, orchestration, or integration with external tools, pass the --json flag. This disables the interactive TUI prompt and writes the discovered nodes as a JSON array directly to stdout.

To keep the output stream clean and valid for JSON parsers like jq, all status updates and logging messages are automatically routed to stderr.

# Scan and print all discovered nodes as JSON
./pharos-scan --json

# Run a targeted subnet scan and output JSON
./pharos-scan --json 10.10.10.0/24

Because pharos-scan outputs clean JSON to stdout, you can easily pipe the results into jq for advanced filtering (for example, finding only newly discovered nodes that aren’t already registered in Pharos):

# Find all new nodes that do not exist in the Pharos registry yet
./pharos-scan --json | jq '.[] | select(.is_existing == false)'

Unattended Discovery

For a fully hands-off cycle — no TUI, no JSON to pipe anywhere, just discover-and-sync — run:

pharos-scan --auto

This runs one full cycle (ping sweep across every locally detected subnet, ARP cache read, OUI/reverse-DNS resolve, then sync to your Pharos server) and exits — intended to be run on a schedule, not left running. Before writing, it checks whether a record for that device already exists and who owns it: if another source (e.g. pharos-pulse) already has a record for that device, --auto skips it entirely rather than overwriting a higher-fidelity field with a MAC-OUI guess.

The Automated Installation Guide can set this up as a recurring systemd timer (every 10 minutes) with its own dedicated, minimally-privileged signing key:

curl -sSL https://raw.githubusercontent.com/iamrichardD/pharos/main/scripts/install.sh | bash -s -- scan-auto 192.168.1.5

Unlike hub/node, this is opt-in and not bundled into either — install it explicitly on whichever host you want doing the periodic scanning.

Next Steps

Monitor your newly discovered nodes in real-time using the Pharos Console — your lab’s Agent-Native Control Plane.