Home › Documentation › Tools › gnulte-scan

gnulte-scan(8) — the scanner

Applies to gnulte-scan v16.13 · last updated 2026-10-15

Sweep or read the neighbour table; each device comes back with its vendor (from the embedded OUI registry), mDNS .local names, reverse DNS, open ports, a device-type guess and an OS fingerprint. Root is optional: without it the sweep is ICMP-only, with it the in-process ARP sweep also catches hosts that block ping.

Requirements

  • Runs unprivileged. Root enables the ARP sweep (automatic) and catches devices that filter ICMP.
  • No arp-scan, arping or nmap: the sweep and the port scanner are in-process (since v16.6).

Synopsis

gnulte-scan [options]

Options

OptionDescription
-i, --interface IFACEnetwork interface (default: auto-detect)
-C, --cidr CIDRsubnet to scan (default: from interface)
-t, --threads Nparallel ping workers (default: 64)
-d, --deepdeep scan alive hosts with the in-Go port scanner (banner, TLS/SSH/SMB fingerprinting)
-T, --interactiveinteractive full-screen browser with Devices / Log / Summary tabs; r re-scans on demand, o opens the settings page
--watch Nre-scan every N seconds, marking ▲ NEW / ▼ GONE / ~ CHANGED hosts live; with --json it streams a JSON-lines delta feed (baseline + per-sweep changes)
--arp / --no-arpforce or disable the in-process ARP sweep (automatic when root)
-j, --jsonoutput JSON
-y, --yamloutput YAML
-c, --csvoutput CSV
-q, --quietresults only, no header/summary
--soundplay a tone per result
--report FILE / --no-reportwrite (default) or skip the HTML report
--oui-file FILEmerge an operator CSV vendor table (prefix,vendor) over the built-in OUI data
--settingsopen the settings editor and exit
--docsprint the safety documents and exit
--reset-safetyremove the acceptance record and exit
--versionprint version and exit
-h, --helpshow the built-in help

In the -T browser, devices the shared store already knows are marked * in the target picker, and you can select by keyword (Mobile, @hostname).

Examples

gnulte-scan --deep                        # sweep + port scan + OS fingerprint
gnulte-scan --watch 5                     # live re-scan: ▲ new ▼ gone ~ changed
gnulte-scan --watch 5 --json | jq 'select(.kind=="delta")'   # a motion sensor
gnulte-scan -C 192.168.1.0/24 -t 128 -q   # quiet CSV-free text results, more workers
gnulte-scan -T                            # the tabbed browser

Output

Per device: IP, MAC, vendor, hostname(s), device-type guess, open ports (deep mode) and an OS fingerprint with a confidence score (v12+). --watch output marks movement per sweep; --json turns that into one JSON object per sweep on stdout, with the narrative on stderr — so gnulte-scan --watch 5 --json | jq is a working motion sensor.

Installation

Part of the GNULTE suite. Build and install everything at once;

git clone https://github.com/notmicrosoft2000-cmd/gnulte-go.git
cd gnulte-go
./build.sh          # builds all eight binaries, runs go vet + go test ./...
sudo ./install.sh   # installs to /usr/local/bin + safety docs

installs gnulte-scan to /usr/local/bin/gnulte-scan. See installation for requirements.

Common errors

A host is missing from the sweep
Use --arp (automatic as root): devices that block ICMP but answer ARP are caught by the ARP sweep.
-T will not open
The interactive browser needs a real terminal; use plain output in scripts or pipes.
Vendor shows as unknown
Merge your own table with --oui-file (prefix,vendor CSV) over the built-in OUI data.

Related tools

  • gnulte-devices — the same inventory in one pass, no sweep
  • gnulte-lan — continuous watching instead of periodic sweeps
  • gnulte — turn a discovered host into a test target