vh/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2025-12-07 09:36:05 -08:00
Code Issues Actions Packages Projects Releases Wiki Activity

New plugin for Omada SDN import using OpenAPI

Browse Source
This commit is contained in:
xfilo
2025-02-24 00:51:44 +01:00
parent 500129c440
commit 4d77ff3ff1
4 changed files with 1233 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
front/plugins/omada_sdn_openapi_import/README.md Executable file
View File

@@ -0,0 +1,75 @@
## 🔍 Overview
- This plugin imports online devices and clients from the Omada SDN (Omada Controller) through the provided OpenAPI.
### ✨ Features
1. Import online devices (gateways, switches, and access points) compatible with Omada SDN and send them to NetAlertX.
2. Import online clients (e.g., computers and smartphones) and send them to NetAlertX.
### 📌 Requirements
- Omada Controller with Open API support.
#### ✅ Officially supported controllers - [Source](https://community.tp-link.com/en/business/forum/topic/590430)
- All Omada Pro versions support Open API
- Omada Software/Hardware Controller support Open API since Controller v5.12
### ⚙️ Setup guide & settings
1. Login to your **Omada Controller**.
2. In the **Global Dashboard**, navigate to **Settings**, select **Platform Integration**, then click on **Open API**.
3. Create new credentials by clicking **Add New App**.
- The `App Name` can be anything.
- Set the `Mode` to `Client`.
- Set the `Role` to `Viewer` or `Administrator`.
- For `Site Privileges`, choose `All (Including all new-created sites)` or select specific site(s).
- Click `Apply` to create the application.
4. From the created application, you will need the following fields.
- `Omada ID` - visible by clicking the **eye** icon next to the **edit** and **delete** buttons.
- `Client ID`
- `Client Secret`
5. Open **NetAlertX's Settings**, head to **Omada SDN using OpenAPI** `(OMDSDNOPENAPI)` and configure the plugin.
- `OMDSDNOPENAPI_RUN` - When the scan should run, good option is `schedule`.
- `OMDSDNOPENAPI_host` - Specify the host URL of your **Omada Controller**, including the protocol, e.g., `https://example.com:1234`.
- `OMDSDNOPENAPI_omada_id` - Enter the **Omada ID** obtained in the previous step.
- `OMDSDNOPENAPI_client_id` - Enter the **Client ID** obtained in the previous step.
- `OMDSDNOPENAPI_client_secret` - Enter the **Client Secret** obtained in the previous step.
- `OMDSDNOPENAPI_sites` (optional) - You can enter either the **site name** or **site ID**. If an invalid value is provided or neither is specified, the plugin will default to the first accessible site using the supplied credentials.
- `OMDSDNOPENAPI_verify_ssl` - Check this option to enable SSL verification for requests to your Omada Controller's OpenAPI. If unchecked, SSL verification will be disabled.
### 📋 Data populated by the plugin
- This table outlines the data fields populated by the plugin, their conditions, descriptions, and where they are visible.
| 🔹 Field | 🔄 Population Condition | 📖 Description | 👀 Visibility |
|---|---|---|---|
| **MAC** | Always populated | The device's unique MAC address | Device details |
| **Last IP** | Always populated | The device's assigned IP address | Device details |
| **Name** | Always populated | The device name retrieved from Omada | Device details |
| **Parent Node** | Only if available | MAC address of the parent device (switch, AP, or gateway) | Device details |
| **Parent Node Port** | Only if available | The port number used to connect to the parent device | Device details |
| **SSID** | Only if available | The SSID through which the device is connected | Device details |
| **Device Type** | Only if available | Detected device type (e.g., iPhone, PC, Android) | Device details |
| **Last Seen** | Always populated | Last recorded time the device was active on the network | Plugin details |
| **Omada Site** | Always populated | Omada site to which the device is assigned | Device details |
| **VLAN ID** | Only if available | VLAN ID assigned to the device | Plugin details |
### ⚠️ Limitations and warnings
- The plugin can fetch up to 1000 devices and 1000 clients from the Omada Controller.
- Using non-Omada SDN compatible devices (e.g., switches, APs) may result in incomplete or inaccurate data.
### 🖼️ Examples
- Settings:
- ![settings_example](/front/plugins/omada_sdn_openapi_import/omada_sdn_openapi_import_settings.png)
### ℹ️ Other info
- Version: 1.0
- Author : [xfilo](https://github.com/xfilo)
- Release Date: 24-February-2025
- Omada Open API documentation: https://use1-omada-northbound.tplinkcloud.com/doc.html#/home (may take a moment to load)