NetAlertX/front/plugins/rest_import/README.md

Overview

Import devices from any REST API that returns JSON

Designed to replace small vendor-specific plugins for systems like OPNsense, RouterOS, asset management tools, and custom inventory APIs. Multiple endpoints can be configured independently in a single plugin instance.

Quick setup guide

Navigate to Settings > REST Import and click Add to create an import definition.

Field	Description
Name	Friendly label shown in logs (e.g. OPNsense DHCP)
URL	Full REST endpoint URL
Method	GET or POST
Verify SSL	Disable for self-signed certificates
Auth Type	none, basic, or bearer
Username / API Key	Used with basic auth
Password / API Secret	Used with basic auth
Bearer Token	Used with bearer auth
Custom Headers	Optional. One Key: Value per line
POST Body	Optional JSON body for POST requests
Device List Path	Dot-separated path to the array of records (e.g. rows, data.devices). Leave blank if the response is already an array

Field mapping

Map API response fields to NetAlertX scan fields. Leave a mapping blank to skip that field.

Popup field	Scan column
MAC Address	scanMac
IP Address	scanLastIP
Device Name	scanName
Vendor	scanVendor
SSID	scanSSID
Device Type	scanType
Parent MAC	scanParentMAC
Parent Port	scanParentPort
Site	scanSite
VLAN	scanVlan

Fake MAC generation

Enable Generate Fake MAC when the API does not expose MAC addresses (e.g. remote ICMP scans, IP-only inventory systems). A deterministic fake MAC is derived from the IP address using the fa:ce: prefix. Requires a valid IP mapping.

Warning

Fake MACs can cause inconsistencies if IP addresses change between scans. Static IPs are strongly recommended when using this feature.

Example: OPNsense Dnsmasq API

Response:

{
  "rows": [
    {
      "hwaddr": "94:18:65:de:22:01",
      "address": "192.168.1.2",
      "hostname": "Orbi-Base-Station",
      "mac_info": "NETGEAR"
    }
  ]
}

Configuration:

Name:              OPNsense DHCP
URL:               https://firewall/api/dnsmasq/leases/search
Method:            GET
Auth Type:         basic
Username:          admin
Device List Path:  rows
MAC Address:       hwaddr
IP Address:        address
Device Name:       hostname
Vendor:            mac_info

Notes

• Version: 1.0.0
• Author: jokob-sk
• Records with missing or invalid MAC addresses are skipped unless Generate Fake MAC is enabled
• Each import definition executes independently; failed imports do not block others