vh/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2026-04-02 16:22:20 -07:00
Code Issues Actions Packages Projects Releases Wiki Activity

ALL:Authoritative plugin fields

Browse Source
This commit is contained in:
Jokob @NetAlertX
2026-01-19 11:28:37 +00:00
parent 1e289e94e3
commit 3b203536b8
61 changed files with 5018 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files

225
docs/API_DEVICE_FIELD_LOCK.md Normal file
View File

@@ -0,0 +1,225 @@
# Device Field Lock/Unlock API
## Overview
The Device Field Lock/Unlock feature allows users to lock specific device fields to prevent plugin overwrites. This is part of the authoritative device field update system that ensures data integrity while maintaining flexibility for user customization.
## Concepts
### Tracked Fields
Only certain device fields support locking. These are the fields that can be modified by both plugins and users:
- `devMac` - Device MAC address
- `devName` - Device name/hostname
- `devLastIP` - Last known IP address
- `devVendor` - Device vendor/manufacturer
- `devFQDN` - Fully qualified domain name
- `devSSID` - Network SSID
- `devParentMAC` - Parent device MAC address
- `devParentPort` - Parent device port
- `devParentRelType` - Parent device relationship type
- `devVlan` - VLAN identifier
### Field Source Tracking
Every tracked field has an associated `*Source` field that indicates where the current value originated:
- `NEWDEV` - Created via the UI as a new device
- `USER` - Manually edited by a user
- `LOCKED` - Field is locked; prevents any plugin overwrites
- Plugin name (e.g., `UNIFIAPI`, `PIHOLE`) - Last updated by this plugin
### Locking Mechanism
When a field is **locked**, its source is set to `LOCKED`. This prevents plugin overwrites based on the authorization logic:
1. Plugin wants to update field
2. Authoritative handler checks field's `*Source` value
3. If `*Source` == `LOCKED`, plugin update is rejected
4. User can still manually unlock the field
When a field is **unlocked**, its source is set to `NEWDEV`, allowing plugins to resume updates.
## Endpoints
### Lock or Unlock a Field
```
POST /device/{mac}/field/lock
Authorization: Bearer {API_TOKEN}
Content-Type: application/json
{
"fieldName": "devName",
"lock": true
}
```
#### Parameters
- `mac` (path, required): Device MAC address (e.g., `AA:BB:CC:DD:EE:FF`)
- `fieldName` (body, required): Name of the field to lock/unlock. Must be one of the tracked fields listed above.
- `lock` (body, required): Boolean. `true` to lock, `false` to unlock.
#### Responses
**Success (200)**
```json
{
"success": true,
"message": "Field devName locked",
"fieldName": "devName",
"locked": true
}
```
**Bad Request (400)**
```json
{
"success": false,
"error": "fieldName is required"
}
```
```json
{
"success": false,
"error": "Field 'devInvalidField' cannot be locked"
}
```
**Unauthorized (403)**
```json
{
"success": false,
"error": "Unauthorized"
}
```
**Not Found (404)**
```json
{
"success": false,
"error": "Device not found"
}
```
## Examples
### Lock a Device Name
Prevent the device name from being overwritten by plugins:
```bash
curl -X POST https://your-netalertx.local/api/device/AA:BB:CC:DD:EE:FF/field/lock \
-H "Authorization: Bearer your-api-token" \
-H "Content-Type: application/json" \
-d '{
"fieldName": "devName",
"lock": true
}'
```
### Unlock a Field
Allow plugins to resume updating a field:
```bash
curl -X POST https://your-netalertx.local/api/device/AA:BB:CC:DD:EE:FF/field/lock \
-H "Authorization: Bearer your-api-token" \
-H "Content-Type: application/json" \
-d '{
"fieldName": "devName",
"lock": false
}'
```
## UI Integration
The Device Edit form displays lock/unlock buttons for all tracked fields:
1. **Lock Button** (🔒): Click to prevent plugin overwrites
2. **Unlock Button** (🔓): Click to allow plugin overwrites again
3. **Source Indicator**: Shows current field source (USER, LOCKED, NEWDEV, or plugin name)
### Source Indicator Colors
- Red (USER): Field was manually edited by a user
- Orange (LOCKED): Field is locked and protected from overwrites
- Gray (NEWDEV/Plugin): Field value came from automatic discovery
## UI Workflow
### Locking a Field via UI
1. Navigate to Device Details
2. Find the field you want to protect
3. Click the lock button (🔒) next to the field
4. Button changes to unlock (🔓) and source indicator turns red (LOCKED)
5. Field is now protected from plugin overwrites
### Unlocking a Field via UI
1. Find the locked field (button shows 🔓)
2. Click the unlock button
3. Button changes back to lock (🔒) and source resets to NEWDEV
4. Plugins can now update this field again
## Authorization
All lock/unlock operations require:
- Valid API token in `Authorization: Bearer {token}` header
- User must be authenticated to the NetAlertX instance
## Implementation Details
### Backend Logic
The lock/unlock feature is implemented in:
- **API Endpoint**: `/server/api_server/api_server_start.py` - `api_device_field_lock()`
- **Data Model**: `/server/models/device_instance.py` - Authorization checks in `setDeviceData()`
- **Database**: Devices table with `*Source` columns tracking field origins
### Frontend Logic
The lock/unlock UI is implemented in:
- **Device Edit Form**: `/front/deviceDetailsEdit.php`
- Form rendering with lock/unlock buttons
- JavaScript function `toggleFieldLock()` for API calls
- Source indicator display
- **Styling**: `/front/css/app.css` - Lock button and source indicator styles
### Authorization Handler
The authoritative field update logic prevents plugin overwrites:
1. Plugin provides new value for field via plugin config `SET_ALWAYS`/`SET_EMPTY`
2. Authoritative handler (in DeviceInstance) checks `{field}Source` value
3. If source is `LOCKED` or `USER`, plugin update is rejected
4. If source is `NEWDEV` or plugin name, plugin update is accepted
## Best Practices
### When to Lock Fields
- Device names that you've customized
- Static IP addresses or important identifiers
- Device vendor information you've corrected
- Fields prone to incorrect plugin updates
### When to Keep Unlocked
- Fields that plugins actively maintain (MAC, IP address)
- Fields you want auto-updated by discovery plugins
- Fields that may change frequently in your network
### Bulk Operations
The field lock/unlock feature is currently per-device. For bulk locking:
1. Use Multi-Edit to update device fields
2. Then use individual lock operations via API script
3. Or contact support for bulk lock endpoint
## Troubleshooting
### Lock Button Not Visible
- Device must be saved/created first (not "new" device)
- Field must be one of the 10 tracked fields
- Check browser console for JavaScript errors
### Lock Operation Failed
- Verify API token is valid
- Check device MAC address is correct
- Ensure device exists in database
### Field Still Updating After Lock
- Verify lock was successful (check API response)
- Reload device details page
- Check plugin logs to see if plugin is providing the field
- Look for authorization errors in NetAlertX logs
## See Also
- [API Device Endpoints Documentation](API_DEVICE.md)
- [Authoritative Field Updates System](../docs/PLUGINS_DEV.md#authoritative-fields)
- [Plugin Configuration Reference](../docs/PLUGINS_DEV_CONFIG.md)

21
docs/DEVICE_MANAGEMENT.md
View File

@@ -47,4 +47,25 @@ The **MAC** field and the **Last IP** field will then become editable.
To speed up device population you can also copy data from an existing device. This can be done from the **Tools** tab on the Device details.
## Field Locking (Preventing Plugin Overwrites)
NetAlertX allows you to "lock" specific device fields to prevent plugins from automatically overwriting your custom values. This is useful when you've manually corrected information that might be discovered differently by discovery plugins.
### Quick Start
1. Open a device for editing
2. Click the **lock button** (🔒) next to any tracked field
3. The field is now protected—plugins cannot change it until you unlock it
### Tracked Fields
The following 10 fields support locking:
- devMac, devName, devLastIP, devVendor, devFQDN, devSSID, devParentMAC, devParentPort, devParentRelType, devVlan
### See Also
- **For Users:** [Quick Reference - Device Field Lock/Unlock](QUICK_REFERENCE_FIELD_LOCK.md) - How to use field locking
- **For Developers:** [API Device Field Lock Documentation](API_DEVICE_FIELD_LOCK.md) - Technical API reference
- **For Plugin Developers:** [Plugin Field Configuration (SET_ALWAYS/SET_EMPTY)](PLUGINS_DEV_CONFIG.md) - Configure which fields plugins can update

81
docs/PLUGINS_DEV_CONFIG.md
View File

@@ -177,6 +177,87 @@ After persistence:
---
## Field Update Authorization (SET_ALWAYS / SET_EMPTY)
For tracked fields (devMac, devName, devLastIP, devVendor, devFQDN, devSSID, devParentMAC, devParentPort, devParentRelType, devVlan), plugins can configure how they interact with the authoritative field update system.
### SET_ALWAYS
**Mandatory when field is tracked.**
Controls whether a plugin field is enabled:
- `"1"` - Plugin can always overwrite this field when authorized (subject to source-based permissions)
- `"0"` - Plugin doesn't use this field
**Authorization logic:** Even with `SET_ALWAYS: "1"`, the plugin respects source-based permissions:
- Cannot overwrite `USER` source (user manually edited)
- Cannot overwrite `LOCKED` source (user locked field)
- Can overwrite `NEWDEV` or plugin-owned sources (if plugin has SET_ALWAYS enabled)
**Example in config.json:**
```json
{
"setKey": "NEWDEV_devName",
"displayName": "Device Name",
"SET_ALWAYS": "1"
}
```
### SET_EMPTY
**Optional field override.**
Restricts when a plugin can update a field:
- `"1"` - Overwrite only if current value is empty OR source is NEWDEV (conservative mode)
- `"0"` - No extra restriction; respect authorization logic (default)
**Use case:** Some plugins discover optional enrichment data (like vendor/hostname) that shouldn't override user-set or existing values. Use `SET_EMPTY: "1"` to be less aggressive.
**Example in config.json:**
```json
{
"setKey": "NEWDEV_devVendor",
"displayName": "Device Vendor",
"SET_ALWAYS": "1",
"SET_EMPTY": "1"
}
```
### Authorization Decision Flow
1. **Source check:** Is field LOCKED or USER? → REJECT (protected)
2. **SET_ALWAYS check:** Is SET_ALWAYS enabled for this plugin+field? → YES: ALLOW (can overwrite empty values, NEWDEV, plugin sources, etc.) | NO: Continue to step 3
3. **SET_EMPTY check:** Is SET_EMPTY enabled AND field non-empty+non-NEWDEV? → REJECT
4. **Default behavior:** Allow overwrite if field empty or NEWDEV source
### Plugin Field Mappings Reference
This table shows all device discovery and enrichment plugins and their tracked field configuration:
| Plugin | Tracked Fields | Behavior |
|--------|---|---|
| ARPSCAN | devMac, devLastIP | SET_ALWAYS for both |
| IPNEIGH | devMac, devLastIP | SET_ALWAYS for both |
| DHCPLSS | devMac, devLastIP | SET_ALWAYS for both |
| ASUSWRT | devMac, devLastIP | SET_ALWAYS for both |
| LUCIRPC | devMac, devLastIP | SET_ALWAYS for both |
| PIHOLE | devMac, devLastIP, devName, devVendor | SET_ALWAYS for MAC/IP |
| PIHOLEAPI | devMac, devLastIP, devName, devVendor | SET_ALWAYS for MAC/IP, SET_EMPTY for name/vendor |
| NBTSCAN | devName | SET_ALWAYS |
| DIGSCAN | devName, devFQDN | SET_ALWAYS |
| NSLOOKUP | devName, devFQDN | SET_ALWAYS |
| AVAHISCAN | devName | SET_ALWAYS |
| VNDRPDT | devMac, devVendor | SET_ALWAYS for both |
| SNMPDSC | devMac, devLastIP | SET_ALWAYS for both |
| UNIFIMP | devMac, devLastIP, devName, devVendor, devSSID, devParentMAC, devParentPort | SET_ALWAYS for MAC/IP |
| UNIFIAPI | devMac, devLastIP, devName, devParentMAC | SET_ALWAYS for MAC/IP |
**Note:** Check each plugin's `config.json` manifest for its specific SET_ALWAYS/SET_EMPTY configuration.
---
## Summary
The lifecycle of a plugin configuration is:

149
docs/QUICK_REFERENCE_FIELD_LOCK.md Normal file
View File

@@ -0,0 +1,149 @@
# Quick Reference Guide - Device Field Lock/Unlock System
## One-Minute Overview
The device field lock/unlock system allows you to protect specific device fields from being automatically overwritten by scanning plugins. When you lock a field, NetAlertX remembers your choice and prevents plugins from changing that value until you unlock it.
**Use case:** You've manually corrected a device name or port number and want to keep it that way, even when plugins discover different values.
## Tracked Fields (10 Total)
These are the ONLY fields that can be locked:
1. devMac - Device MAC address
2. devName - Device hostname/alias
3. devLastIP - Last known IP address
4. devVendor - Device manufacturer
5. devFQDN - Fully qualified domain name
6. devSSID - WiFi network name
7. devParentMAC - Parent/gateway MAC
8. devParentPort - Parent device port
9. devParentRelType - Relationship type (e.g., "gateway")
10. devVlan - VLAN identifier
## Source Values Explained
Each locked field has a "source" indicator that shows you why the value is protected:
| Indicator | Meaning | Can It Change? |
|-----------|---------|---|
| 🔒 **LOCKED** (red badge) | You locked this field | No, until you unlock it |
| ✏️ **USER** (orange badge) | You edited this field | No, plugins can't overwrite |
| 📡 **NEWDEV** (gray badge) | Default/unset value | Yes, plugins can update |
| 📡 **Plugin name** (gray badge) | Last updated by a plugin (e.g., UNIFIAPI) | Yes, plugins can update |
## How to Use
### Lock a Field (Prevent Plugin Changes)
1. Navigate to **Device Details** for the device
2. Find the field you want to protect (e.g., device name)
3. Click the **lock button** (🔒) next to the field
4. The button changes to **unlock** (🔓) and turns red
5. That field is now protected
### Unlock a Field (Allow Plugin Updates)
1. Go to **Device Details**
2. Find the locked field (shows 🔓 in red)
3. Click the **unlock button** (🔓)
4. The button changes back to **lock** (🔒) and turns gray
5. Plugins can now update that field again
## Common Scenarios
### Scenario 1: You've Named Your Device and Want to Keep the Name
1. You manually edit device name to "Living Room Smart TV"
2. A scanning plugin later discovers it as "Unknown Device" or "DEVICE-ABC123"
3. **Solution:** Lock the device name field
4. Your custom name is preserved even after future scans
### Scenario 2: You Lock a Field, But It Still Changes
**This means the field source is USER or LOCKED (protected).** Check:
- Is it showing the lock icon? (If yes, it's protected)
- Wait a moment—sometimes changes take a few seconds to display
- Try refreshing the page
### Scenario 3: You Want to Let Plugins Update Again
1. Find the device with locked fields
2. Click the unlock button (🔓) next to each field
3. Refresh the page
4. Next time a plugin runs, it can update that field
## What Happens When You Lock a Field
- ✅ Your custom value is kept
- ✅ Future plugin scans won't overwrite it
- ✅ You can still manually edit it anytime
- ✅ Lock persists across plugin runs
- ✅ Other users can see it's locked (red indicator)
## What Happens When You Unlock a Field
- ✅ Plugins can update it again on next scan
- ✅ If a plugin has a new value, it will be applied
- ✅ You can lock it again anytime
- ✅ Your manual edits are still saved in the database
## Error Messages & Solutions
| Message | What It Means | What to Do |
|---------|--------------|-----------|
| "Field cannot be locked" | You tried to lock a field that doesn't support locking | Only lock the 10 fields listed above |
| "Device not found" | The device MAC address doesn't exist | Verify the device hasn't been deleted |
| Lock button doesn't work | Network or permission issue | Refresh the page and try again |
| Unexpected field changed | Field might have been unlocked | Check if field shows unlock icon (🔓) |
## Quick Tips
- **Lock names and IPs you manually corrected** to keep them stable
- **Leave discovery fields (vendor, FQDN) unlocked** for automatic updates
- **Use locks sparingly**—they prevent automatic data enrichment
- **Check the source indicator** (colored badge) to understand field origin
- **Lock buttons only appear for devices that are saved** (not for new devices being created)
## When to Lock vs. When NOT to Lock
### ✅ **Good reasons to lock:**
- You've customized the device name and it's correct
- You've set a static IP and it shouldn't change
- You've configured VLAN information
- You know the parent device and don't want it auto-corrected
### ❌ **Bad reasons to lock:**
- The value seems wrong—edit it first, then lock
- You want to prevent data from another source—use field lock, not to hide problems
- You're trying to force a value the system disagrees with
## Troubleshooting
**Lock button not appearing:**
- Confirm the field is one of the 10 tracked fields (see list above)
- Confirm the device is already saved (new devices don't show lock buttons)
- Refresh the page
**Lock button is there but click doesn't work:**
- Check your internet connection
- Check you have permission to edit devices
- Look at browser console (F12 > Console tab) for error messages
- Try again in a few seconds
**Field still changes after locking:**
- Double-check the lock icon shows (red indicator)
- Reload the page—the change might be a display issue
- Check if you accidentally unlocked it
- Contact support if it persists
## For More Information
- **Technical details:** See [API_DEVICE_FIELD_LOCK.md](API_DEVICE_FIELD_LOCK.md)
- **Plugin configuration:** See [PLUGINS_DEV_CONFIG.md](PLUGINS_DEV_CONFIG.md)
- **Admin guide:** See [DEVICE_MANAGEMENT.md](DEVICE_MANAGEMENT.md)
---
**Quick Start:** Find a device field you want to protect → Click the lock icon → That's it! The field won't change until you unlock it.