Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

UNFIMP does not populate devSSID for UniFi wireless clients

Closed
  • Is something wrong?
#1,832 4 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

A pull request for this has already been merged.

  • #1836 by @itwormz — merged

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
25/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Stale
Tech stack
json, python
Domain
backend, networking

Research direction

Read server/plugins/unifi_import/script.py and server/plugins/unifi_import/config.json to trace how the plugin extracts and maps SSID data. Check the linked pull request first, since it is merged; done means wireless clients have their SSID in devSSID and wired clients remain empty.

Written by the indexing model from the issue text.

Description

Feature request ➕ next release/in dev image 🚀 Waiting for reply⏳
What installation are you running?

Production (netalertx) 📦

Is there an existing issue for this?
The issue occurs in the following browsers. Select at least 2.
  • Firefox
  • Chrome
  • Edge
  • Safari (unsupported) - PRs welcome
  • N/A - This is an issue with the backend
Current Behavior

Bug description

The UNFIMP plugin successfully imports UniFi clients, including hostname, IP, vendor, and parent AP/switch information, but WiFi SSIDs are not populated in devSSID.

Environment
  • NetAlertX: v26.10.0
  • UniFi Network: 10.6.106
  • UniFi OS: 5.1.33
  • Controller type: UniFi Cloud Gateway
  • UNFIMP version setting: UDMP-unifiOS
  • Installation type: Production container

UNFIMP successfully connects to the UniFi controller and imports clients.

Current behavior

For a wireless client, the UniFi API data contains the actual WiFi SSID in essid.

Sanitized example:

{
  "is_wired": false,
  "hostname": "<REDACTED_HOSTNAME>",
  "last_connection_network_name": "<REDACTED_NETWORK_NAME>",
  "network": "<REDACTED_NETWORK_NAME>",
  "essid": "<REDACTED_SSID>",
  "last_uplink_name": "<REDACTED_AP_NAME>"
}

Another wireless client shows the same relevant fields:

{
  "is_wired": false,
  "hostname": "<REDACTED_HOSTNAME>",
  "last_connection_network_name": "<REDACTED_NETWORK_NAME>",
  "essid": "<REDACTED_SSID>"
}

The actual WiFi SSID is therefore available in the returned UniFi client data as:

essid

However, the current UNFIMP implementation in server/plugins/unifi_import/script.py uses:

extra=get_unifi_val(device, 'connection_network_name', ''),

In this environment, connection_network_name is not present in the returned wireless client objects, so extra remains empty.

There also appears to be a second issue in:

server/plugins/unifi_import/config.json

The UNFIMP extra column is defined without a mapped_to_column entry.

In particular, it does not contain:

"mapped_to_column": "scanSSID"

Other NetAlertX plugins that provide SSID information use this mapping. For example, the included WiFi Canary plugin defines its extra field using:

{
  "column": "extra",
  "mapped_to_column": "scanSSID"
}

At the same time, UNFIMP exposes devSSID in both its SET_ALWAYS and SET_EMPTY options, which suggests that the plugin is intended to populate devSSID.

Additional information

Parent topology import works correctly using the same UniFi client data.

Fields such as:

last_uplink_name
last_uplink_mac
last_uplink_remote_port
ap_mac

are available from UniFi and the corresponding parent AP/switch information is imported successfully by UNFIMP.

The issue therefore appears to be specific to SSID extraction and SSID-to-devSSID mapping.

No local patches have been applied. The behavior was observed with the unmodified NetAlertX v26.10.0 container.

Expected Behavior

Expected behavior

For wireless UniFi clients, UNFIMP should populate devSSID with the actual WiFi SSID reported by the UniFi controller.

For example:

devSSID = <REDACTED_SSID>

For wired clients, devSSID should remain empty.

Possible cause

There appear to be two related issues:

  1. script.py reads connection_network_name, while the UniFi client data returned in this environment provides the actual WiFi SSID in essid.

  2. The UNFIMP extra field is not mapped to scanSSID in config.json.

For comparison, the UniFi data may also contain:

last_connection_network_name

but this represents the UniFi network name, not necessarily the actual wireless SSID, so it should not be used as a substitute for essid.

Possible fix

The SSID extraction could use essid for wireless clients, for example:

ssid = (
    ''
    if device.get('is_wired') is True
    else get_unifi_val(device, 'essid', '')
)

and then:

extra=ssid,

The corresponding extra column in config.json could also be mapped to scanSSID:

{
  "column": "extra",
  "mapped_to_column": "scanSSID"
}

This would ensure that the SSID extracted from UniFi is propagated into NetAlertX's devSSID field.

Steps To Reproduce

  1. Run NetAlertX v26.10.0 with the UNFIMP plugin configured for a UniFi OS controller using UDMP-unifiOS.

  2. Allow UNFIMP to import clients from the UniFi controller.

  3. Verify that wireless clients are successfully imported and that other UniFi-derived information, such as hostname, vendor, and parent AP/switch data, is populated.

  4. Inspect the UniFi client data for a wireless client and confirm that it contains an essid value, for example:

{
  "is_wired": false,
  "essid": "<REDACTED_SSID>"
}

  1. Open the corresponding device in NetAlertX.

  2. Observe that devSSID is empty even though the UniFi client data contains the SSID in essid.

Relevant app.conf settings
docker-compose.yml
Dominant language
Python
Stars
7.2k
Forks
456
Avg merge
16h 25m
Merged PRs (30d)
30

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from netalertx/NetAlertX

All issues in netalertx/NetAlertX

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.