Integrate local Tailscale status output with NetAlertX

[Pichatu]

Hi,

I’d like to integrate my local Tailscale network information with NetAlertX using the command:

tailscale status --json | jq -r ' (["devMac","devName","devOwner","devType","devVendor","devFavorite","devGroup","devComments","devFirstConnection","devLastConnection","devLastIP","devStaticIP","devScan","devLogEvents","devAlertEvents","devAlertDown","devSkipRepeated","devLastNotification","devPresentLastScan","devIsNew","devLocation","devIsArchived","devParentMAC","devParentPort","devIcon","devGUID","devSite","devSSID","devSyncHubNode","devSourcePlugin","devCustomProps","devFQDN","devParentRelType","devReqNicsOnline"] | @csv), (.Peer | to_entries[] | [ "", .value.HostName, (.value.User // "unknown"), (.value.OS // "unknown OS"), "Tailscale","","","","", (.value.LastSeen // ""), (.value.TailscaleIPs[0] // ""), "","1","1","0","0","0","","1","0","Tailscale Network","0","","", (if .value.OS == "windows" then "mdi:monitor" elif .value.OS == "android" then "mdi:cellphone" else "mdi:laptop" end), (.key // "nodekey:unknown"),"","","","TAILSCALE","",(.value.DNSName // .value.HostName),"","1" ] | @csv)'

This command generates a CSV file matching the NetAlertX device structure, ready to import.

I’d like some help understanding the best way to use this with NetAlertX.
Is there a native or simple method to import this kind of data (from tailscale status --json) into the device list without creating duplicates, since the same hosts also exist locally (same MACs or hostnames)?

Any advice or example from someone who has done something similar would be really appreciated.

Thanks a lot for your help and for all the work on this project.

My setup: Ubuntu Server (host mode, running NetAlertX in Portainer).

(I’m using ChatGPT to translate my message because I don’t speak English well enough for technical topics like this.)

[jokob-sk]

Thinking of a few ways how to implement this:

1. A universal plugin loading in a CSV into the app, skipping duplicates

Pros: Easy maintenance, Universal entry point for custom scripts, Easy mapping
Cons: More difficult to configure, maintenance of scripts on the user, script is run on the server (pro?), Adding new fields to teh Devices table might break custom scripts

2. A universal plugin loading in data as per plugin format https://jokob-sk.github.io/NetAlertX/PLUGINS_DEV/?h=plugin#column-order-and-values-plugins-interface-contract

Pros: Easy maintenance, Universal entry point for custom scripts, Adding new fields to the Devices table will NOT break custom scripts as only a subset is used
Cons: More difficult to configure, might be confusing to map, maintenance of scripts on the user, script is run on the server (pro?), mapping of fields needs updating if fields are added

3. A bespoke tailscale plugin

Pros: Easy config
Cons: More things to install in the main image, maybe unnecessary bloat, potentially maintenance issues down the line

Let me hear your thoughts

[Pichatu]

Well… I’ve spent the whole day trying to make a Tailscale plugin. It partially worked — I managed to extract the data I wanted — but I just can’t get it to show up properly inside the NAX interface.

At this point I’ve completely fried my last remaining brain cell. I’m not a developer, and ChatGPT has been driving me in circles.

The goal was simple: just pull the Tailscale peers and either merge them with existing devices or create a new virtual entry like PC_xxx - Tailscale, ideally grouped under a main Tailscale gateway. But I can’t get it to behave.

I’m also running into hostname resolution issues on my local network, so I’ll set up Technitium DNS Server tomorrow. That should at least give me consistent hostnames — then I’ll see if I can either inject the Tailscale IPs into existing devices or link them to the virtual “- Tailscale” ones.

[jokob-sk]

Feel free to share your config.json and .py script and I can have a look

[Pichatu]

I finally managed to get something working, but I’m still running into a few issues:

Accurate vendor / OS / version
Right now every peer shows up with a generic “Windows” vendor.
I would like to expose the same details shown in the Tailscale console, for example:
1.90.6 Windows 11 23H2
Ideally:

vendor = "Tailscale - "

OS and version extracted from tailscale status --json

client version also exposed (e.g. 1.90.6)

Tailscale node visibility in the Network view
In network.php, the Tailscale node does not appear next to the WAN link.
It seems to be considered a child of the Freebox gateway, which makes it show as “offline” or not appear at all.
For a VPN entry point, it should really appear as an independent gateway.

Rename the network node
The generated node is currently labeled “Network Node”.
I’d like it to show up as Tailscale Gateway instead.

Real last-seen timestamp
I’d like to use the actual last connection timestamp reported by tailscale status (LastSeen field).

config.json

plugin.py

[jokob-sk]

Nice, getting closer!

I'd recommend against creating synthetic MACs (if possible, supply the real MAC, if not, generate a synthetic MAC without the TS- prefix) as MAC validation happens in the main app in a few places.

If you need to pass more information to the main app you can use the helper1-4 (helpVal1-4) fields. See the UNFIMP plugin for an example.

Unfortunately, network.php can have only one root node currently. You can create a fake root internet node and connect everything to it. For that you have to specify the parentMac.

I don't think you need to include Tailscale in the device name - there is already a Source plugin field you can select in the devices view.