Unknown-device detection
An unknown-device rule raises a problem for every Wi-Fi or wired client on the network now that is neither a registered device nor on the rule’s allow list. You choose where it looks: a building-systems SSID, a VLAN, or switch ports you tag. Each device is its own problem, keyed by its MAC, and the problem recovers on its own when the device leaves or becomes known.
You create the rule by asking Claude, which uses alerts.create_rule with
kind: unknown_device, as for any alert rule.
A dry run lists what the rule would raise right now before anything is saved.
Saving or changing a rule needs the engineer role or above.
Where does the rule look?
Section titled “Where does the rule look?”At least one of select, ssids, ssidsFrom or vlans is required; a
rule with none is rejected with “an unknown_device rule needs where to look”.
| Field | Scope |
|---|---|
select | An inventory selector for the clients themselves, of type client (Wi-Fi) or wired_client. Tags and within reach a client through its AP, switch port, switch or zone, so { type: 'wired_client', tags: { facility: 'yes' } } means wired clients on anything tagged facility: yes. Without a type, both kinds are checked |
ssids | SSIDs to watch, compared ignoring case |
ssidsFrom | An inventory selector whose WLANs’ SSIDs are watched, e.g. { type: 'wlan', tags: { facility: 'yes' } } |
vlans | VLAN ids, 1 to 4094 |
When a rule gives both SSIDs and VLANs, a client on either is in scope. Your own APs and switches never count as clients. Wired clients learned on a port that links to another managed switch or an AP (an uplink) are not counted either: the device isn’t really on that port.
- name: unknown-on-bms kind: unknown_device ssids: [BMS-Sensors] vlans: [40] state: WARNINGHow do I approve a device?
Section titled “How do I approve a device?”Register it. A device you register with inventory.add_device (by MAC,
with a name, tags and a location) counts as known to every unknown-device rule,
and its problem recovers on the next check. Ask Claude: “Register
AC:DE:48:00:11:22 as the Hall B badge reader.” Registering needs the engineer
role or above.
For a whole class of devices, add an allow list to the rule instead.
What can the allow list match?
Section titled “What can the allow list match?”allow names what else counts as known, besides registered devices. A
device that matches any entry is OK.
| Key | Matches | Example |
|---|---|---|
macs | Whole MACs, or prefixes of at least 3 octets (an OUI), in any notation | ['00:0E:8C', 'AC:DE:48:00:11:22'] |
vendors | The MAC’s registered IEEE vendor | ['Johnson Controls*'] |
hostnames | The device’s host name | ['ahu-*'] |
os | The controller’s fingerprint: OS type, device type or OS vendor | ['Printer', 'Linux*'] |
vendors, hostnames and os are globs: * matches any run of characters
and ? one character, over the whole value, ignoring case. A randomised
(locally administered) MAC has no vendor, so only macs, hostnames or os
can allow it.
There is no allow-list form on the dashboard. Change the list by asking
Claude (alerts.update_rule), or edit the rule’s YAML and import it under
Rules as code on the Alerts page’s Rules tab.
Where does the client data come from?
Section titled “Where does the client data come from?”On the hosted service, from the controller’s API, because Northbound streaming is not available on the hosted service yet. Two jobs read clients:
| Source | When | Reads |
|---|---|---|
| Inventory sync | Hourly, after the first sync | Up to 5,000 Wi-Fi clients by default (inventory.sync({ maxClients }) takes up to 20,000) and up to 10,000 wired clients from the switches’ MAC tables |
| API polling | Every 5 minutes while an unknown-device or presence rule is enabled, otherwise every 15 minutes | The same two lists |
API polling is off until an admin turns it on. Without it, the client lists come only from the hourly inventory sync. Wired clients on an AP’s LAN ports are reported only by streaming, so a rule can’t see them on the hosted service.
A rule looks at up to 50,000 clients per run, and tracks up to 5,000 problems. Past that, the rule stops with the error “the rule has 5000 problem instances; narrow it”.
What do the starter rules watch?
Section titled “What do the starter rules watch?”Two starter rules
watch facility networks, and both are quiet until you tag something
facility: yes.
| Rule | Watches | State |
|---|---|---|
unknown-device-facility-ssid | Clients on a WLAN tagged facility: yes | WARNING |
unknown-device-facility-port | Wired clients on a port, switch or switch group tagged facility: yes (a tag on a switch covers its ports) | WARNING |
Ask Claude: “Tag the BMS-Sensors WLAN and the IDF-3 switch as facility.”
What does a notification say?
Section titled “What does a notification say?”It names the device and where it is, in this form:
unknown device <MAC> (<vendor>, "<host name>", <fingerprint>, <IP>) on "<SSID>" VLAN <id> at <AP or switch port>, first seen <ISO time>The parts are the vendor (or randomised MAC, or unregistered OUI), the
host name, the fingerprint and the IP, then the SSID (or wired), the VLAN, the
AP or switch port it is on, and when it was first seen. Each part appears only
when it is known. The problem’s instance is mac:<MAC>, and the notification
carries mac, vendor, ssid, vlan and name labels when known.
Unknown-device rules go HARD on the first check (maxCheckAttempts defaults to
- and raise CRITICAL unless
statesays WARNING. A problem recovers with “no longer on the network” when the device leaves, or with “is known” and the reason (for exampleregistered device "Hall B badge reader"orallowed vendor Siemens*) when you approve it.