LAN Discovery (nmap)¶

What this is¶

LAN Discovery is an opt-in Catalog integration that scans your configured CIDR(s) with nmap, auto-creates discovered device records, and feeds an end-to-end Hosts map of the whole LAN — without linking every device to a managed Server.

Devices are not managed fleet servers until you link or promote them. Naming, kind badges, and Hosts map chips are for orientation; promote only when you want SSH/backups/Docker management.

Where: Catalog → Integrations → add / open LAN Discovery (/integrations/{id}?tab=…).

Hosts map (whole network): Catalog → Network → Hosts map (/dns/physical) — fleet servers and unlinked discoveries together. See Network maps.

Why it exists¶

PiHerder already manages hosts you onboarded. Discovery answers: what else is on my LAN, and which of those do I want to manage? Scans never run silently: you configure CIDRs and start work manually or via schedules you enable.

Prerequisites¶

Without the worker, Overview shows scanner offline. Without the vuln pack, deep vuln scripts stay gated. Never add -Q nmap to the main celery-worker.

End-to-end: first discovery week¶

1. Build and start the nmap worker (commands above).
2. Catalog → Integrations → Add → LAN Discovery → set CIDR(s) (e.g. 192.168.1.0/24) and optional excludes.
3. Optional: enable vuln scripts on the integration when you want deep scans to use NSE vuln packs.
4. Overview → download / update vulnerability database if you plan deep vuln scans (Jobs page shows progress).
5. Run Discovery (who is up), then Inventory (ports — top N or all ports) so chips and kind heuristics have data.
6. Devices tab — List or Map view — click a host → edit modal: map name, fix device type, mark gateway if the row is your router, Mark known for reviewed noise.
7. Open Catalog → Network → Hosts map — fleet + discovered together (no per-device link required). Use the radar toggle for outer chips; 1:1 fits the window (tight when discovered is off).
8. Link or promote only hosts you want to manage.
9. Optional: Schedules — discovery daily / inventory weekly; leave disabled until manual runs look good.

Journey: Operator scenarios — Journey H.

Tabs¶

Alerts (v1.3)¶

New devices and offline (stale last-seen) can open Alerts inbox rows. Webhooks get a digest per scan for new devices, not one POST each. Mute LAN discovery under Settings → Alerts → Alert policy before the first large CIDR scan. Port churn is not an alert. See Alerts.

There are two maps:

Scan intensities¶

On-demand: Overview → Scan now opens a modal (intensity, targets, timing, port scope, UDP, script preset) — no free-form nmap flags. Queue scan enqueues a Job on the nmap worker.

Heavy scan confirm: for detailed or deep intensity, PiHerder shows an in-app confirm (not a browser popup). Cancel leaves the Scan now modal as-is — no “Queueing scan” wait overlay and no job. Only Queue scan on the confirm dialog starts the wait + POST.

Scan this device (deep) still uses the device edit path / curated deep actions where offered.

Deep script presets¶

Device detail classifies script rows: finding · clear · script error · info. Each finding shows the port/service it ran on (or was inferred for from CPE/product). Ports with issues are highlighted in the port table. Errors mean the probe failed (often irrelevant apps), not “unknown vulnerability”. Version/CPE matches still need human verification.

Timing (nmap -T)¶

Port scope (inventory / detailed / deep)¶

Detailed and deep default to all ports unless you pick top or custom.

Targets & excludes¶

• Scan now pre-fills configured LAN CIDR(s) so you do not re-type the subnet.
• Always exclude — every intensity (including discovery).
• Exclude from port/vuln scans — inventory / detailed / deep skip these hosts; discovery still finds them.
• Exclude from deep only — inventory can still map ports; deep/vuln skips them.

Excludes are passed as nmap --exclude so a single IP does not block scanning the rest of the CIDR.

Map identity (name, type, gateway)¶

Any discovered device (Pi, printer, IoT, router, TV…) can be labelled for the Hosts map — not only fleet-manageable hosts. You do not need to promote a Server just to name a chip.

Clear the name field and save to fall back to hostname/IP. Kind Auto returns to the heuristic.

Gateway / router role¶

Mark the device that is your LAN gateway (router IP). That:

1. Sets Network map → gateway IP to this device’s IP (if different).
2. Labels the Hosts map Router spine node with the map name (or hostname).
3. Hides that IP as a separate LAN discovery chip (avoids double-draw on the rim).

Only one device is gateway at a time. You can still set gateway IP manually under Catalog → Network map settings.

Device type (looks like + override)¶

PiHerder guesses a device kind from:

Shown as a kind badge on Devices list, edit modal, Map cards, Hosts map chips, and linked server soft-embed. Heuristic is advisory only — never auto-links or promotes.

When discovery is wrong (e.g. OUI says printer but the box is a Pi), set Device type in the edit modal. Override is sticky across rescans; the auto guess is still shown as “auto was …”. An asterisk on the kind badge means operator override.

Run inventory (or detailed/deep) so ports feed the classifier and Hosts map port expand; discovery alone often only yields MAC vendor when available.

Shipped (v1.1 map interactivity): canned kind icons on Hosts map chips; lock a device for open ports on the map (progressive callout). Sticky port roles via the edit table. Custom icon pack remains roadmap — map interactivity plan.

Edit modal (Devices List + Map)¶

Click a Map card or a List row to open a centered floating modal (same shell as jobs / wait modals — not a bottom sheet). Stays on Devices (same view); no full-page jump.

Where you land after close¶

Operators can mutate; viewers see read-only identity. Map view restores scroll after save so long subnet grids do not jump to the top.

Devices → Map view¶

• Hosts grouped by /24 (or IPv6 /64), with client-side search (map is not paged).
• List | Map toggle on the Devices toolbar (shared stats strip).
• Click a host card → edit modal (above). Stays on Map view.
• Show unlinked (default on): include unlinked hosts (new / known / stale). Uncheck to keep only linked devices. Preference is browser-local (separate from Hosts map radar).
• Toolbar shows counts (on map / subnets / open ports / new / linked).
• Port chips show the latest snapshot per host (from the last inventory/detailed/deep that recorded ports), not a merge of all historical scans.
• Card titles use map name when set.

Devices → List view¶

• Shared filter bar: All / New / Known / Linked / Hidden / Offline + counts + server-side search (q) and pager (10 / 20 / 50 / 100, same ph_per_page cookie as Servers). Search matches IP, hostname, display name, MAC, vendor, OS, notes, kind (ha / rpi aliases). Chip counts stay fleet-wide.
• Each row shows Last seen (relative; absolute in title) and state.
• Offline = not seen recently (stale after ~14 days without last_seen; warning colour). Devices are never auto-deleted.
• Hide (modal) = ignore — off Devices map and Hosts overlay; still in DB under Hidden (Unhide restores).
• Purge device (modal) permanently removes the row + findings; a later scan may re-discover it as new. Unlink first if linked.
• On the Offline filter, operators can Purge N offline… (bulk, confirm).
• Pin the integration with ★ next to the LAN Discovery name for the header pin menu.
• Click a row → same edit modal.
• Empty states when filters hide every host.

Hosts map (Catalog → Network)¶

Unlinked discoveries appear automatically on the end-to-end Hosts map:

Fleet server LAN chip + Network path row¶

On server detail:

Hosts map toolbar (what each control does)¶

One-line chrome at the top of the map (no horizontal scroll on typical phones):

Also: pinch / scroll-wheel zoom, drag to pan. Footer shows fleet · discovered counts and map legend (solid LAN, dashed WAN/NPM, dashed-border chips = discovered).

Ports on discovered chips: after inventory (or deeper) scans, lock a discovered device on the Hosts map to open the same progressive ports flow as fleet hosts — compact callout → tap for ports-only list (nmap open ports) → Edit sticky roles when needed. No Server link required. Details: Network maps — ports expand.

Full layout notes: Network maps — LAN discovery.

Devices & onboarding¶

Lifecycle states¶

Discovery ≠ fleet membership. Hostnames and MACs depend on scan privileges and host-network worker mode.

Identity & DHCP¶

Ignore/link/map name survive IP updates when identity is MAC-based.

Soft embed (fleet)¶

Linked discovery devices appear on:

• Servers list — LAN chip
• Server detail — hero LAN pill + always-open LAN discovery card next to Network path (inner rack: IP, ports, kind, scripts; header Edit device / Map view)

Schedules¶

• All schedules are off by default.
• Intensities: discovery · inventory · detailed · deep (deep may set vuln scripts and SYN override).
• Provide cron (5 fields, app timezone) or interval hours.
• Create and Edit (list → Edit → same form prefilled → Save).
• Options stored per schedule (options_json): script preset, timing, top-ports, UDP, port list, SYN vs inherit.
• Changes resync APScheduler; audit records configure/scan actions.

Runs¶

History of completed/failed scan jobs for this integration.

There is no run ID column — use the Job link for correlation. One dense list at all widths (not a separate mobile table markup). Optional Settings → Stale data cleanup can purge old run rows + XML.

Vulnerability pack¶

Jobs¶

Web only enqueues. Cancel and progress follow the fleet Jobs UI (finished jobs keep the modal open with a done banner instead of forcing a full page reload).

Security & ops notes¶

• RBAC: operator+ mutate; viewer read.
• Targets outside configured CIDRs are refused.
• SYN / raw scans need appropriate privileges in the nmap container (stock image runs as root with caps for reliable LAN + inventory). Connect-scan (-sT) is the fallback.
• Default install: no nmap worker, no vuln DB in image layers.
• Worker fence: PIHERDER_NMAP_WORKER is compose-owned (0 web / 1 nmap worker); worker_guard refuses misrouted tasks.
• Detailed/deep whole-LAN Scan now asks for an in-app confirm (blast-radius); Cancel does not queue a job.
• CI never live-scans real networks (fixtures / mock XML only).

Related¶

• Network maps (Hosts map + discovery overlay)
• Environment reference — nmap
• Integrations overview
• Add a server — promote path
• Jobs, audit & notifications
• Settings — Stale data cleanup — optional purge of old nmap runs
• Reports — live devices per day (hosts_up, carry-forward)
• Volumes