Add support for OPNsense Dnsmasq endpoint

[mikesalz]

Is there an existing issue for this?

• I have searched the existing open and closed issues

Is your feature request related to a problem? Please describe

OPNsense provides an endpoint [/api/dnsmasq/leases/search] to list Dnsmasq leases. Sample python code below will print some of the fields that are returned by this endpoint.

@jokob-sk In response to your comments in the other thread...

Thanks for the suggestion. Yes please open a separate issue. I am leaning toward a new plugin (maybe DNSMSQAPI or OPNSNSAPI) as the DNSLSS plugin operates by mapping dns leases files into the container and adding a conditional flow seems a bit off - anyhow - happy to hear other suggestions.

I agree that a new plugin makes sense. But OPNsense has several options for DHCP (for example KEA and now sunsetted ISC) so we might want to keep that in mind when naming it. I don't know if there is a character limit on plugin names, but maybe it can include both OPNsense and Dnsmasq in the name. Maybe OPNSNSDNSMSQ or OPNDNSMSQ? I know those are both pretty long!

I will also need help implementing this as I don't run OPNSense. If you could create a PR that would be ideal. You can probably check front/plugins/kea_api for inspiration.

If I am being candid, I had a lot of help from AI to put the code below together. I can try to cobble something together, but I might be of more help testing than developing!

Describe the solution you'd like

I would like to see an option to connect to OPNsense Dnsmasq to retrieve host names and other device info directly from the router.

Describe alternatives you've considered

The default scanning plugins

Anything else?

import json
import requests


OPNSENSE_URL = "https://192.168.1.1:8443"
API_KEY = "REDACTED"
API_SECRET = "REDACTED"

endpoint = f"{OPNSENSE_URL}/api/dnsmasq/leases/search"

response = requests.get(
    endpoint, 
    auth=(API_KEY, API_SECRET), 
    verify=False
)

if response.status_code == 200:
    data = response.json()

    devices = data.get("rows", [])
    
    print(f"Found {len(devices)} active Dnsmasq entries:\n")
    for device in devices:
        hostname = device.get("hostname", "Unknown")
        ip = device.get("address", "N/A")
        mac = device.get("hwaddr", "N/A")
        mac_info = device.get("mac_info", "N/A"),
        if_descr = device.get("if_descr", "N/A")

        print(f"Host: {hostname} | IP: {ip} | MAC: {mac} | MAC Info: {mac_info} | Interface: {if_descr}")
else:
    print(f"Failed to access Dnsmasq API. Status Code: {response.status_code}")

Am I willing to test this? 🧪

• I will do my best to test this feature on the netlertx-dev image when requested within 48h and report bugs to help deliver a great user experience for everyone and not to break existing installations.

Can I help implement this? 👩‍💻👨‍💻

• Yes
• No

[mikesalz]

@jokob-sk I know some python but not a lot. But I want to help as much as I can. If you can give me a list of exactly which fields you need for the plugin, I can experiment/modify my script to return them. Then maybe I can hand the script over to you and you can plug it in to the correct format you need for a plugin? Then I can test the plugin and provide feedback. Would that work? If you're too busy or not interested, I totally understand and will have no hard feelings!

[jokob-sk]

Hi @mikesalz ,

Thanks for the suggestion and offer to help.

I am thinking if it makes sense to change this request into a generic REST plugin which supports the output format and mapping of those fields returned by the opensense API. Can you post a sample response json? This way we might cover this and some other API endpoints. Trying to figure out how feasible and if I am not over-complicating things.

[mikesalz]

Here are some examples...

{
  "expire": 1781697545,
  "hwaddr": "94:18:65:de:22:01",
  "iaid": "",
  "address": "192.168.1.2",
  "hostname": "Orbi-Base-Station",
  "client_id": "01:94:18:65:de:22:01",
  "if": "ixl1",
  "if_descr": "LAN",
  "if_name": "lan",
  "mac_info": "NETGEAR",
  "is_reserved": [
    "hwaddr"
  ]
},
{
  "expire": 1781727998,
  "hwaddr": "94:18:65:dd:74:7d",
  "iaid": "",
  "address": "192.168.1.3",
  "hostname": "Orbi-Laundry-Room-Satellite",
  "client_id": "*",
  "if": "ixl1",
  "if_descr": "LAN",
  "if_name": "lan",
  "mac_info": "NETGEAR",
  "is_reserved": [
    "hwaddr"
  ]
},
{
  "expire": 1781728782,
  "hwaddr": "bc:24:11:c0:11:51",
  "iaid": "",
  "address": "192.168.1.5",
  "hostname": "unifi-os-server",
  "client_id": "*",
  "if": "ixl1",
  "if_descr": "LAN",
  "if_name": "lan",
  "mac_info": "Proxmox Server Solutions GmbH",
  "is_reserved": [
    "hwaddr"
  ]
},
{
  "expire": 1781698362,
  "hwaddr": "a8:9c:6c:b0:b3:b6",
  "iaid": "",
  "address": "192.168.1.6",
  "hostname": "USW-Pro-XG-10-PoE",
  "client_id": "01:a8:9c:6c:b0:b3:b6",
  "if": "ixl1",
  "if_descr": "LAN",
  "if_name": "lan",
  "mac_info": "Ubiquiti Inc",
  "is_reserved": [
    "client_id",
    "hwaddr"
  ]
},

[mikesalz]

Question - If some variation of this ends up being implemented, would/could/should this replace any of the name discovery and resolution scanners? I'm thinking an API call is much less burdensome on the network than multiple scanners. But maybe they would still be pulling in additional fields that the API does not provide?

[jokob-sk]

This should be available in the next release.

https://github.com/netalertx/NetAlertX/tree/next_release/front/plugins/rest_import

It would be great if you could test the ghcr.io/netalertx/netalertx-dev-unsafe Docker image in ~15 minutes (or once the latest GitHub Action finishes).

⚠️ Please back up everything first, or ideally spin up a separate container with its own DB and config (a copy of your current setup), as database changes may occur.

After updating:

• Click the 🔄 refresh button in the blue header at the top
• Hard refresh your browser cache (shift + reload) to force js and css files reload

👉 If I don’t receive confirmation that this works, I may revert the changes to avoid introducing bugs.

If you find NetAlertX useful, consider sharing the app on forums or socials, at your work, or share a quick review on Reddit or elsewhere to help support the project. See more ideas and how-to in the growth playbook.

Disclaimer: Running the dev container long-term may lead to data loss, as upgrade paths are not guaranteed.

Thanks in advance,
j

[jokob-sk]

Question - If some variation of this ends up being implemented, would/could/should this replace any of the name discovery and resolution scanners? I'm thinking an API call is much less burdensome on the network than multiple scanners. But maybe they would still be pulling in additional fields that the API does not provide?

It's completely up to you which plugins you enable or disable in your instance.

[mikesalz]

Thanks for the super fast turn-around! I spun up the new version this morning, but after adding the new RSTIMPRT plugin it seems to be stuck in an endless loop with a pop-up warning of "Importing settings and re-initializing…"

[mikesalz]

It's completely up to you which plugins you enable or disable in your instance.

Yeah, I guess I was really just looking for your opinion. If I am able to get host names straight from the router's API, are there other scanners you would recommend removing? Or do they all fill in different gaps?

[jokob-sk]

I am not able to reproduce your issue unfortunately. Could you please post a redacted screenshot of your REST import settings? Otherwise feel free to send the app.conf file to netalertx@gmail.com. I entered sample data and it seems to save and load correctly:

If one plugin provides all the data you need you can disable the rest. You can find an overview of what plugins are available and what they cover in this table: https://docs.netalertx.com/PLUGINS/?h=enabl#available-plugins

[mikesalz]

Could you please post a redacted screenshot of your REST import settings?

I coudn't even get that far. I only got as far as adding RSTIMPRT to the list of plugins (in the UI). I noticed that if I go into the conf file and manually remove it from the Loaded_Plugins list and restart, the error stops.

[jokob-sk]

Unfortunately I can't reproduce your issue.

Did you perform these steps after adding the plugin?

1. Click the 🔄 refresh button in the blue header at the top
2. Hard refresh your browser cache (shift + reload) to force js and css files reload

Can you try using an incognito window and a different browser?