Network Scanner Extended (Lean) – Home Assistant Custom Integration

A lightweight network inventory integration for Home Assistant. It polls one or more providers (OPNsense, UniFi, AdGuard Home), merges devices into a single list (primarily by MAC), and exposes the results as entities.

---

What this integration creates

• Platforms: sensor, device_tracker
• Services:
  • network_scanner.rescan – refresh all Network Scanner entries
  • network_scanner.cleanup_entities – remove orphaned device_tracker entities

---

Entities

Sensor

The sensor platform exposes a summary view of the coordinator data. In the current build, you have a sensor that reports the number of merged devices and includes useful attributes (e.g. a table-ready flat list).

Coordinator payload keys (current)

• devices – merged list of devices (structured)
• count – integer device count
• last_refresh_utc – timestamp of last refresh
• flat – flattened list suitable for dashboards/templates
• index – lookup maps (MAC/IP → index)
• summary – counts grouped by vendor/VLAN

Device trackers

The device tracker platform creates one device_tracker per device from the current coordinator snapshot. Each tracker is registered into the device registry using the device MAC address (where available), so Home Assistant can group related entities on the same “device page”.

Important behavioural detail (current)

• Trackers are created from the current snapshot during platform setup.
• If completely new devices appear later, you may need to reload the config entry or restart Home Assistant to create new tracker entities.
• The cleanup service exists to remove trackers that no longer exist in the current coordinator device list.

---

Configuration

Configuration is done through the UI (config flow). Go to: Settings → Devices & Services → Add Integration → Network Scanner

Common options

• Providers (providers): choose any of opnsense, unifi, adguard
• Verify SSL (verify_ssl): whether to verify TLS certificates
• Interval (minutes) (interval_min): polling interval

OPNsense

• opnsense_url
• key
• secret

UniFi

• unifi_url
• token (optional)
• username / password (optional)
• site (default: default)

AdGuard Home

• adguard_url
• username / password

---

AdGuard Home – exact API behaviour (current)

The AdGuard provider uses these endpoints:

• /control/login (attempted; failures are tolerated)
• /control/dhcp/leases and /control/dhcp/status (DHCP information; some installs return 404 for one path)
• /control/clients (clients list)

Auth logic (current)

• It first attempts a login POST to /control/login using JSON payload {"name": "...", "password": "..."}.
• If login succeeds and returns a token, it sets Authorization: Bearer <token> on requests.
• Requests to DHCP/clients endpoints are made with HTTP Basic Auth (BasicAuth(username, password)) when credentials are provided. This supports setups where a reverse proxy requires Basic Auth.
• Login may return 403 on some setups (e.g. blocked by proxy). This does not prevent device collection if the GET endpoints work.

---

MAC directory overlay options

The integration UI includes the following options:

• mac_directory_json_url
• mac_directory_json_text

Current behaviour: these fields exist in options, but device tracker enrichment from this directory is not applied unless you have added the overlay logic into the coordinator/platforms. If you want name/description enrichment, implement it in the coordinator and have entities prefer the directory name over provider hostname.

---

Services

• network_scanner.rescan
  • Triggers async_request_refresh() on all Network Scanner coordinators.
• network_scanner.cleanup_entities
  • Removes device_tracker entities from the entity registry if they are no longer present in the coordinator device list.
  • Unique ID convention used by cleanup: <entry_id>:<uid>

---

Installation

HACS

1. Add this repository as a Custom Repository in HACS (category: Integration).
2. Install the integration.
3. Restart Home Assistant.
4. Add it via Settings → Devices & Services → Add Integration.

Manual

1. Copy custom_components/network_scanner into your Home Assistant config/custom_components directory.
2. Restart Home Assistant.
3. Add the integration via the UI.

---

Troubleshooting

• Sensor shows devices but no device_trackers: confirm network_scanner.device_tracker is loading and that entities are being created from the snapshot.
• AdGuard shows 401/403: usually an auth mismatch. The provider tolerates login failure; check that the GET endpoints are working and that Basic Auth credentials are set.
• AdGuard DHCP endpoint returns 404: common depending on AdGuard build/config; the provider also tries the alternative path.

Enable debug logging

logger:
  default: info
  logs:
    custom_components.network_scanner: debug
    custom_components.network_scanner.provider.adguard: debug

---

Security

• MAC/IP/hostnames are sensitive in many environments. Treat logs and exports accordingly.
• Prefer TLS with valid certificates where possible.
• Use least-privilege API credentials for OPNsense/UniFi.