Home › Documentation › Tools › gnulte-scan
gnulte-scan(8) — the scanner
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,arpingornmap: the sweep and the port scanner are in-process (since v16.6).
Synopsis
gnulte-scan [options]
Options
| Option | Description |
|---|---|
-i, --interface IFACE | network interface (default: auto-detect) |
-C, --cidr CIDR | subnet to scan (default: from interface) |
-t, --threads N | parallel ping workers (default: 64) |
-d, --deep | deep scan alive hosts with the in-Go port scanner (banner, TLS/SSH/SMB fingerprinting) |
-T, --interactive | interactive full-screen browser with Devices / Log / Summary tabs; r re-scans on demand, o opens the settings page |
--watch N | re-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-arp | force or disable the in-process ARP sweep (automatic when root) |
-j, --json | output JSON |
-y, --yaml | output YAML |
-c, --csv | output CSV |
-q, --quiet | results only, no header/summary |
--sound | play a tone per result |
--report FILE / --no-report | write (default) or skip the HTML report |
--oui-file FILE | merge an operator CSV vendor table (prefix,vendor) over the built-in OUI data |
--settings | open the settings editor and exit |
--docs | print the safety documents and exit |
--reset-safety | remove the acceptance record and exit |
--version | print version and exit |
-h, --help | show 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. -Twill 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,vendorCSV) 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