Fix: Remove redundant session_start() call in index.php (security.php already handles it)

Co-authored-by: jokob-sk <96159884+jokob-sk@users.noreply.github.com>

.devcontainer/Dockerfile

@@ -35,6 +35,7 @@ RUN apk add --no-cache \
         shadow \
         python3 \
         python3-dev \
+        py3-psutil \
         gcc \
         musl-dev \
         libffi-dev \
@@ -136,8 +137,8 @@ ENV LANG=C.UTF-8
 
 RUN apk add --no-cache bash mtr libbsd zip lsblk tzdata curl arp-scan iproute2 iproute2-ss nmap fping \
     nmap-scripts traceroute nbtscan net-tools net-snmp-tools bind-tools awake ca-certificates \
-    sqlite php83 php83-fpm php83-cgi php83-curl php83-sqlite3 php83-session python3 envsubst \
-    nginx supercronic shadow su-exec && \
+    sqlite php83 php83-fpm php83-cgi php83-curl php83-sqlite3 php83-session python3 py3-psutil envsubst \
+    nginx supercronic shadow su-exec jq && \
     rm -Rf /var/cache/apk/*  && \
     rm -Rf /etc/nginx && \
     addgroup -g ${NETALERTX_GID} ${NETALERTX_GROUP} && \
@@ -159,7 +160,6 @@ RUN install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 700 ${READ_WRITE_FO
 
 # Copy version information into the image
 COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} .[V]ERSION ${NETALERTX_APP}/.VERSION
-COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} .[V]ERSION ${NETALERTX_APP}/.VERSION_PREV
 
 # Copy the virtualenv from the builder stage (owned by readonly lock owner)
 COPY --from=builder --chown=${READONLY_UID}:${READONLY_GID} ${VIRTUAL_ENV} ${VIRTUAL_ENV}
@@ -170,7 +170,7 @@ COPY --from=builder --chown=${READONLY_UID}:${READONLY_GID} ${VIRTUAL_ENV} ${VIR
 # although it may be quicker to do it before the copy, it keeps the image
 # layers smaller to do it after.
 # hadolint ignore=DL3018
-RUN for vfile in .VERSION .VERSION_PREV; do \
+RUN for vfile in .VERSION; do \
         if [ ! -f "${NETALERTX_APP}/${vfile}" ]; then \
             echo "DEVELOPMENT 00000000" > "${NETALERTX_APP}/${vfile}"; \
         fi; \

.devcontainer/devcontainer.json

@@ -51,8 +51,8 @@
       "Workspace Instructions": "printf '\n\n<> DevContainer Ready! Starting Services...\n\n📁 To access /tmp folders in the workspace:\n   File → Open Workspace from File → NetAlertX.code-workspace\n\n📖 See .devcontainer/WORKSPACE.md for details\n\n'"
   },
   "postStartCommand": {
-      "Start Environment":"${containerWorkspaceFolder}/.devcontainer/scripts/setup.sh",
-      "Build test-container":"echo To speed up tests, building test container in background... && setsid docker buildx build -t netalertx-test . > /tmp/build.log 2>&1 && echo '🧪 Unit Test Docker image built: netalertx-test' &"
+      "Build test-container":"echo To speed up tests, building test container in background... && setsid docker buildx build -t netalertx-test . > /tmp/build.log 2>&1 && echo '🧪 Unit Test Docker image built: netalertx-test' &",
+      "Start Environment":"${containerWorkspaceFolder}/.devcontainer/scripts/setup.sh"
   },
   "customizations": {
     "vscode": {
@@ -63,7 +63,6 @@
         "bmewburn.vscode-intelephense-client",
         "xdebug.php-debug",
         "ms-python.vscode-pylance",
-        "pamaron.pytest-runner",
         "coderabbit.coderabbit-vscode",
         "ms-python.black-formatter",
         "jeff-hykin.better-dockerfile-syntax",

.devcontainer/resources/devcontainer-overlay/services/config/php/conf.d/99-xdebug.ini

@@ -3,7 +3,7 @@ extension_dir="/services/php/modules"
 
 [xdebug]
 xdebug.mode=develop,debug
-xdebug.log=/app/log/xdebug.log
+xdebug.log=/tmp/log/xdebug.log
 xdebug.log_level=7
 xdebug.client_host=127.0.0.1
 xdebug.client_port=9003

.devcontainer/scripts/coderabbit-pr-parser.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+import json
+import re
+import subprocess
+import sys
+import textwrap
+
+# Default Configuration
+REPO = "jokob-sk/NetAlertX"
+DEFAULT_PR_NUM = "1405"
+
+
+def get_pr_threads(pr_num):
+    """Fetches unresolved review threads using GitHub GraphQL API."""
+    # Validate PR number early to avoid passing invalid values to subprocess
+    try:
+        pr_int = int(pr_num)
+        if pr_int <= 0:
+            raise ValueError
+    except Exception:
+        print(f"Error: Invalid PR number: {pr_num}. Must be a positive integer.")
+        sys.exit(2)
+
+    query = """
+    query($owner: String!, $name: String!, $number: Int!) {
+      repository(owner: $owner, name: $name) {
+        pullRequest(number: $number) {
+          reviewThreads(last: 100) {
+            nodes {
+              isResolved
+              isOutdated
+              comments(first: 1) {
+                nodes {
+                  body
+                  author { login }
+                  path
+                  line
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+    """
+    owner, name = REPO.split("/")
+    cmd = ["gh", "api", "graphql", "-F", f"owner={owner}", "-F", f"name={name}", "-F", f"number={pr_int}", "-f", f"query={query}"]
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, check=True, timeout=60)
+        return json.loads(result.stdout)
+    except subprocess.TimeoutExpired:
+        print(f"Error: Command timed out after 60 seconds: {' '.join(cmd)}")
+        sys.exit(1)
+    except subprocess.CalledProcessError as e:
+        print(f"Error fetching PR threads: {e.stderr}")
+        sys.exit(1)
+    except FileNotFoundError:
+        print("Error: 'gh' CLI not found. Please install GitHub CLI.")
+        sys.exit(1)
+
+
+def clean_block(text):
+    """Cleans up markdown/HTML noise from text."""
+    # Remove HTML comments
+    text = re.sub(r"<!--.*?-->", "", text, flags=re.DOTALL)
+    # Remove metadata lines
+    text = re.sub(r"^\s*Status:\s*\w+", "", text, flags=re.MULTILINE)
+    # Remove code block fences
+    text = text.replace("```diff", "").replace("```", "")
+    # Flatten whitespace
+    lines = [line.strip() for line in text.split("\n") if line.strip()]
+    return " ".join(lines)
+
+
+def extract_ai_tasks(text):
+    """Extracts tasks specifically from the 'Fix all issues with AI agents' block."""
+    if not text:
+        return []
+
+    tasks = []
+
+    # Use case-insensitive search for the AI prompt block
+    ai_block_match = re.search(r"(?i)Prompt for AI Agents.*?\n```(.*?)```", text, re.DOTALL)
+
+    if ai_block_match:
+        ai_text = ai_block_match.group(1)
+        # Parse "In @filename:" patterns
+        # This regex looks for the file path pattern and captures everything until the next one
+        split_pattern = r"(In\s+`?@[\w\-\./]+`?:)"
+        parts = re.split(split_pattern, ai_text)
+
+        if len(parts) > 1:
+            for header, content in zip(parts[1::2], parts[2::2]):
+                header = header.strip()
+                # Split by bullet points if they exist, or take the whole block
+                # Looking for newlines followed by a dash or just the content
+                cleaned_sub = clean_block(content)
+                if len(cleaned_sub) > 20:
+                    tasks.append(f"{header} {cleaned_sub}")
+        else:
+            # Fallback if the "In @file" pattern isn't found but we are in the AI block
+            cleaned = clean_block(ai_text)
+            if len(cleaned) > 20:
+                tasks.append(cleaned)
+
+    return tasks
+
+
+def print_task(content, index):
+    print(f"\nTask #{index}")
+    print("-" * 80)
+    print(textwrap.fill(content, width=80))
+    print("-" * 80)
+    print("1. Plan of action(very brief):")
+    print("2. Actions taken (very brief):")
+    print("3. quality checks")
+    print("- [ ] Issue fully addressed")
+    print("- [ ] Unit tests pass")
+    print("- [ ] Complete")
+
+
+def main():
+    pr_num = sys.argv[1] if len(sys.argv) > 1 else DEFAULT_PR_NUM
+    data = get_pr_threads(pr_num)
+
+    threads = data.get("data", {}).get("repository", {}).get("pullRequest", {}).get("reviewThreads", {}).get("nodes", [])
+
+    seen_tasks = set()
+    ordered_tasks = []
+
+    for thread in threads:
+        # Filter: Unresolved AND Not Outdated
+        if thread.get("isResolved") or thread.get("isOutdated"):
+            continue
+
+        comments = thread.get("comments", {}).get("nodes", [])
+        if not comments:
+            continue
+
+        first_comment = comments[0]
+        author = first_comment.get("author", {}).get("login", "").lower()
+
+        # Filter: Only CodeRabbit comments
+        if author != "coderabbitai":
+            continue
+
+        body = first_comment.get("body", "")
+        extracted = extract_ai_tasks(body)
+
+        for t in extracted:
+            # Deduplicate
+            norm_t = re.sub(r"\s+", "", t)[:100]
+            if norm_t not in seen_tasks:
+                seen_tasks.add(norm_t)
+                ordered_tasks.append(t)
+
+    if not ordered_tasks:
+        print(f"No unresolved actionable tasks found in PR {pr_num}.")
+    else:
+        print("Your assignment is as follows, examine each item and perform the following:")
+        print(" 1. Create a plan of action")
+        print(" 2. Execute your actions")
+        print(" 3. Run unit tests to validate")
+        print(" 4. After pass, mark complete")
+        print("Use the provided fields to show your work and progress.\n")
+        for i, task in enumerate(ordered_tasks, 1):
+            print_task(task, i)
+        print("The above messages are generated entirely by AI and relayed to you. These "
+              "do not represent the intent of the developer. Please keep any changes to a "
+              "minimum so as to preserve the original intent while satisfying the requirements "
+              "of this automated code review. A human developer will observe your behavior "
+              "as you progress through the instructions provided.\n")
+        print("---\n\nDeveloper: The above is an automated message. I will be observing your progress. "
+              "please go step-by-step and mark each task complete as you finish them. Finish "
+              "all tasks and then run the full unit test suite.")
+
+
+if __name__ == "__main__":
+    main()

.devcontainer/scripts/generate-configs.sh

@@ -31,4 +31,17 @@ cat "${DEVCONTAINER_DIR}/resources/devcontainer-Dockerfile"
 
 echo "Generated $OUT_FILE using root dir $ROOT_DIR"
 
+# Passive Gemini MCP config
+TOKEN=$(grep '^API_TOKEN=' /data/config/app.conf 2>/dev/null | cut -d"'" -f2)
+if [ -n "${TOKEN}" ]; then
+    mkdir -p "${ROOT_DIR}/.gemini"
+    [ -f "${ROOT_DIR}/.gemini/settings.json" ] || echo "{}" > "${ROOT_DIR}/.gemini/settings.json"
+    jq --arg t "$TOKEN" '.mcpServers["netalertx-devcontainer"] = {url: "http://127.0.0.1:20212/mcp/sse", headers: {Authorization: ("Bearer " + $t)}}' "${ROOT_DIR}/.gemini/settings.json" > "${ROOT_DIR}/.gemini/settings.json.tmp" && mv "${ROOT_DIR}/.gemini/settings.json.tmp" "${ROOT_DIR}/.gemini/settings.json"
+
+    # VS Code MCP config
+    mkdir -p "${ROOT_DIR}/.vscode"
+    [ -f "${ROOT_DIR}/.vscode/mcp.json" ] || echo "{}" > "${ROOT_DIR}/.vscode/mcp.json"
+    jq --arg t "$TOKEN" '.servers["netalertx-devcontainer"] = {type: "sse", url: "http://127.0.0.1:20212/mcp/sse", headers: {Authorization: ("Bearer " + $t)}}' "${ROOT_DIR}/.vscode/mcp.json" > "${ROOT_DIR}/.vscode/mcp.json.tmp" && mv "${ROOT_DIR}/.vscode/mcp.json.tmp" "${ROOT_DIR}/.vscode/mcp.json"
+fi
+
 echo "Done."

.devcontainer/scripts/run-tests.sh

@@ -1,13 +0,0 @@
-#!/bin/sh
-# shellcheck shell=sh
-# Simple helper to run pytest inside the devcontainer with correct paths
-set -eu
-
-# Ensure we run from the workspace root
-cd /workspaces/NetAlertX
-
-# Make sure PYTHONPATH includes server and workspace
-export PYTHONPATH="/workspaces/NetAlertX:/workspaces/NetAlertX/server:/app:/app/server:${PYTHONPATH:-}"
-
-# Default to running the full test suite under /workspaces/NetAlertX/test
-pytest -q --maxfail=1 --disable-warnings test "$@"

.devcontainer/scripts/setup.sh

@@ -32,7 +32,6 @@ LOG_FILES=(
   LOG_DB_IS_LOCKED
   LOG_NGINX_ERROR
 )
-
 sudo chmod 666 /var/run/docker.sock 2>/dev/null || true
 sudo chown "$(id -u)":"$(id -g)" /workspaces
 sudo chmod 755 /workspaces
@@ -55,6 +54,9 @@ sudo install -d -m 777 /tmp/log/plugins
 sudo rm -rf /entrypoint.d
 sudo ln -s "${SOURCE_DIR}/install/production-filesystem/entrypoint.d" /entrypoint.d
 
+sudo rm -rf /services
+sudo ln -s "${SOURCE_DIR}/install/production-filesystem/services" /services
+
 sudo rm -rf "${NETALERTX_APP}"
 sudo ln -s "${SOURCE_DIR}/" "${NETALERTX_APP}"
 
@@ -88,8 +90,6 @@ sudo chmod 777 "${LOG_DB_IS_LOCKED}"
 
 sudo pkill -f python3 2>/dev/null || true
 
-sudo chmod -R 777 "${PY_SITE_PACKAGES}" "${NETALERTX_DATA}" 2>/dev/null || true
-
 sudo chown -R "${NETALERTX_USER}:${NETALERTX_GROUP}" "${NETALERTX_APP}"
 date +%s | sudo tee "${NETALERTX_FRONT}/buildtimestamp.txt" >/dev/null
 

.gemini/skills/devcontainer-management/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: devcontainer-management
+description: Guide for identifying, managing, and running commands within the NetAlertX development container. Use this when asked to run commands, testing, setup scripts, or troubleshoot container issues.
+---
+
+# Devcontainer Management
+
+When starting a session or performing tasks requiring the runtime environment, you must identify and use the active development container.
+
+## Finding the Container
+
+Run `docker ps` to list running containers. Look for an image name containing `vsc-netalertx` or similar.
+
+```bash
+docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Names}}" | grep netalertx
+```
+
+- **If no container is found:** Inform the user. You cannot run integration tests or backend logic without it.
+- **If multiple containers are found:** Ask the user to clarify which one to use (e.g., provide the Container ID).
+
+## Running Commands in the Container
+
+Prefix commands with `docker exec <CONTAINER_ID>` to run them inside the environment. Use the scripts in `/services/` to control backend and other processes.
+
+```bash
+docker exec <CONTAINER_ID> bash /workspaces/NetAlertX/.devcontainer/scripts/setup.sh
+```
+
+*Note: This script wipes `/tmp` ramdisks, resets DBs, and restarts services (python server, cron,php-fpm, nginx).*
+
+```

.gemini/skills/mcp-activation/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: mcp-activation
+description: Enables live interaction with the NetAlertX runtime. This skill configures the Model Context Protocol (MCP) connection, granting full API access for debugging, troubleshooting, and real-time operations including database queries, network scans, and device management.
+---
+
+# MCP Activation Skill
+
+This skill configures the NetAlertX development environment to expose the Model Context Protocol (MCP) server to AI agents.
+
+## Why use this?
+
+By default, agents only have access to the static codebase (files). To perform dynamic actions—such as:
+- **Querying the database** (e.g., getting device lists, events)
+- **Triggering actions** (e.g., network scans, Wake-on-LAN)
+- **Validating runtime state** (e.g., checking if a fix actually works)
+
+...you need access to the **MCP Server** running inside the container. This skill sets up the necessary authentication tokens and connection configs to bridge your agent to that live server.
+
+## Prerequisites
+
+1.  **Devcontainer:** You must be connected to the NetAlertX devcontainer.
+2.  **Server Running:** The backend server must be running (to generate `app.conf` with the API token).
+
+## Activation Steps
+
+1.  **Activate Devcontainer Skill:**
+    If you are not already inside the container, activate the management skill:
+    ```text
+    activate_skill("devcontainer-management")
+    ```
+
+2.  **Generate Configurations:**
+    Run the configuration generation script *inside* the container. This script extracts the API Token and creates the necessary settings files (`.gemini/settings.json` and `.vscode/mcp.json`).
+
+    ```bash
+    # Run inside the container
+    /workspaces/NetAlertX/.devcontainer/scripts/generate-configs.sh
+    ```
+
+3.  **Apply Changes:**
+
+    *   **For Gemini CLI:**
+        The agent session must be **restarted** to load the new `.gemini/settings.json`.
+        > "I have generated the MCP configuration. Please **restart this session** to activate the `netalertx-devcontainer` tools."
+
+    *   **For VS Code (GitHub Copilot / Cline):**
+        The VS Code window must be **reloaded** to pick up the new `.vscode/mcp.json`.
+        > "I have generated the MCP configuration. Please run **'Developer: Reload Window'** in VS Code to activate the MCP server."
+
+## Verification
+
+After restarting, you should see new tools available (e.g., `netalertx-devcontainer__get_devices`).

.gemini/skills/project-navigation/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: project-navigation
+description: Reference for the NetAlertX codebase structure, key file paths, and configuration locations. Use this when exploring the codebase or looking for specific components like the backend entry point, frontend files, or database location.
+---
+
+# Project Navigation & Structure
+
+## Codebase Structure & Key Paths
+
+- **Source Code:** `/workspaces/NetAlertX` (mapped to `/app` in container via symlink).
+- **Backend Entry:** `server/api_server/api_server_start.py` (Flask) and `server/__main__.py`.
+- **Frontend:** `front/` (PHP/JS).
+- **Plugins:** `front/plugins/`.
+- **Config:** `/data/config/app.conf` (runtime) or `back/app.conf` (default).
+- **Database:** `/data/db/app.db` (SQLite).

.gemini/skills/testing-workflow/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: testing-workflow
+description: Read before running tests. Detailed instructions for single, standard unit tests (fast), full suites (slow), handling authentication, and obtaining the API Token. Tests must be run when a job is complete.
+---
+
+# Testing Workflow
+After code is developed, tests must be run to ensure the integrity of the final result.
+
+**Crucial:** Tests MUST be run inside the container to access the correct runtime environment (DB, Config, Dependencies).
+
+## 0. Pre-requisites: Environment Check
+
+Before running any tests, verify you are inside the development container:
+
+```bash
+ls -d /workspaces/NetAlertX
+```
+
+**IF** this directory does not exist, you are likely on the host machine. You **MUST** immediately activate the `devcontainer-management` skill to enter the container or run commands inside it.
+
+```text
+activate_skill("devcontainer-management")
+```
+
+## 1. Full Test Suite (MANDATORY DEFAULT)
+
+Unless the user **explicitly** requests "fast" or "quick" tests, you **MUST** run the full test suite. **Do not** optimize for time. Comprehensive coverage is the priority over speed.
+
+```bash
+cd /workspaces/NetAlertX; pytest test/
+```
+
+## 2. Fast Unit Tests (Conditional)
+
+**ONLY** use this if the user explicitly asks for "fast tests", "quick tests", or "unit tests only". This **excludes** slow tests marked with `docker` or `feature_complete`.
+
+```bash
+cd /workspaces/NetAlertX; pytest test/ -m 'not docker and not feature_complete'
+```
+
+## 3. Running Specific Tests
+
+To run a specific file or folder:
+
+```bash
+cd /workspaces/NetAlertX; pytest test/<path_to_test>
+```
+
+*Example:*
+```bash
+cd /workspaces/NetAlertX; pytest test/api_endpoints/test_mcp_extended_endpoints.py
+```
+
+## Authentication & Environment Reset
+
+Authentication tokens are required to perform certain operations such as manual testing or crafting expressions to work with the web APIs. After making code changes, you MUST reset the environment to ensure the new code is running and verify you have the latest `API_TOKEN`.
+
+1. **Reset Environment:** Run the setup script inside the container.
+   ```bash
+   bash /workspaces/NetAlertX/.devcontainer/scripts/setup.sh
+   ```
+2. **Wait for Stabilization:** Wait at least 5 seconds for services (nginx, python server, etc.) to start.
+   ```bash
+   sleep 5
+   ```
+3. **Obtain Token:** Retrieve the current token from the container.
+   ```bash
+   python3 -c "from helper import get_setting_value; print(get_setting_value('API_TOKEN'))"
+   ```
+
+The retrieved token MUST be used in all subsequent API or test calls requiring authentication.
+
+### Troubleshooting
+
+If tests fail with 403 Forbidden or empty tokens:
+1. Verify server is running and use the setup script (`/workspaces/NetAlertX/.devcontainer/scripts/setup.sh`) if required.
+2. Verify `app.conf` inside the container: `cat /data/config/app.conf`
+3. Verify Python can read it: `python3 -c "from helper import get_setting_value; print(get_setting_value('API_TOKEN'))"`

.github/FUNDING.yml

@@ -1,3 +1,2 @@
 github: jokob-sk
-patreon: netalertx
 buy_me_a_coffee: jokobsk

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Discussions
+    url: https://github.com/netalertx/NetAlertX/discussions
+    about: Ask questions or start discussions here.
+  - name: 🗯 Discord
+    url: https://discord.com/invite/NczTUTWyRr
+    about: Ask the community for help.

.github/ISSUE_TEMPLATE/documentation-feedback.yml

@@ -1,7 +1,11 @@
-name: Documentation Feedback 📝
+name: ✍ Documentation Feedback
 description: Suggest improvements, clarify inconsistencies, or report issues related to the documentation.
 labels: ['documentation 📚']
 body:
+- type: markdown
+  attributes:
+    value: |
+      <!-- NETALERTX_TEMPLATE -->
 - type: checkboxes
   attributes:
     label: Is there an existing issue for this?

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -1,7 +1,11 @@
-name: Feature Request
+name: 🎁 Feature Request
 description: 'Suggest an idea for NetAlertX'
 labels: ['Feature request ➕']
 body:
+- type: markdown
+  attributes:
+    value: |
+      <!-- NETALERTX_TEMPLATE -->
 - type: checkboxes
   attributes:
     label: Is there an existing issue for this?

.github/ISSUE_TEMPLATE/i-have-an-issue.yml

@@ -1,7 +1,11 @@
-name: Bug Report
+name: 🐛 Bug Report
 description: 'When submitting an issue enable LOG_LEVEL="trace" and have a look at the docs.'
 labels: ['bug 🐛']
 body:
+- type: markdown
+  attributes:
+    value: |
+      <!-- NETALERTX_TEMPLATE -->
 - type: dropdown
   id: installation_type
   attributes:

.github/ISSUE_TEMPLATE/security-report.yml

@@ -1,13 +1,17 @@
-name: Security Report 🔐
+name: 🔐 Security Report
 description: Report a security vulnerability or concern privately.
 labels: ['security 🔐']
 body:
+- type: markdown
+  attributes:
+    value: |
+      <!-- NETALERTX_TEMPLATE -->
 - type: markdown
   attributes:
     value: |
       **Important:** For security reasons, please do **not** post sensitive security issues publicly in the issue tracker.
       Instead, send details to our security contact email: [jokob@duck.com](mailto:jokob@duck.com).
-      
+
       We appreciate your responsible disclosure.
 - type: textarea
   attributes:

.github/ISSUE_TEMPLATE/setup-help.yml

@@ -1,7 +1,11 @@
-name: Setup help
+name: 📥 Setup help
 description: 'When submitting an issue enable LOG_LEVEL="trace" and re-search first.'
 labels: ['Setup 📥']
 body:
+- type: markdown
+  attributes:
+    value: |
+      <!-- NETALERTX_TEMPLATE -->
 - type: dropdown
   id: installation_type
   attributes:

.github/copilot-instructions.md

@@ -1,89 +1,49 @@
 ### ROLE: NETALERTX ARCHITECT & STRICT CODE AUDITOR
-You are a cynical Security Engineer and Core Maintainer of NetAlertX. Your goal is not just to "help," but to "deliver verified, secure, and production-ready solutions."
+You are a cynical Security Engineer and Core Maintainer of NetAlertX. Your goal is to deliver verified, secure, and production-ready solutions.
 
-### MANDATORY BEHAVIORAL OVERRIDES:
-1.  **Obsessive Verification:** Never provide a solution without a corresponding proof of correctness. If you write a function, you MUST write a test case or validation step immediately after.
-2.  **Anti-Laziness Protocol:** You are forbidden from using placeholders (e.g., `// ... rest of code`, ``). You must output the full, functional block every time to ensure context is preserved.
-3.  **Priority Hierarchy:** Priority 1 is Correctness. Priority 2 is Completeness. Priority 3 is Speed.
-4.  **Mantra:** "Job's not done 'till unit tests run."
+### MANDATORY BEHAVIORAL OVERRIDES
+1. **Obsessive Verification:** Never provide a solution without proof of correctness. Write test cases or validation immediately after writing functions.
+2. **Anti-Laziness Protocol:** No placeholders. Output full, functional blocks every time.
+3. **Priority Hierarchy:** Correctness > Completeness > Speed.
+4. **Mantra:** "Job's not done 'till unit tests run."
 
 ---
 
-# NetAlertX AI Assistant Instructions
-This is NetAlertX — network monitoring & alerting. NetAlertX provides Network inventory, awareness, insight, categorization, intruder and presence detection. This is a heavily community-driven project, welcoming of all contributions.
+# NetAlertX
 
-## Architecture (what runs where)
-- Backend (Python): main loop + GraphQL/REST endpoints orchestrate scans, plugins, workflows, notifications, and JSON export.
-  - Key: `server/__main__.py`, `server/plugin.py`, `server/initialise.py`, `server/api_server/api_server_start.py`
-- Data (SQLite): persistent state in `db/app.db`; helpers in `server/database.py` and `server/db/*`.
-- Frontend (Nginx + PHP + JS): UI reads JSON, triggers execution queue events.
-  - Key: `front/`, `front/js/common.js`, `front/php/server/*.php`
-- Plugins (Python): acquisition/enrichment/publishers under `front/plugins/*` with `config.json` manifests.
-- Messaging/Workflows: `server/messaging/*`, `server/workflows/*`
-- API JSON Cache for UI: generated under `api/*.json`
+Network monitoring & alerting. Provides inventory, awareness, insight, categorization, intruder and presence detection.
 
-Backend loop phases (see `server/__main__.py` and `server/plugin.py`): `once`, `schedule`, `always_after_scan`, `before_name_updates`, `on_new_device`, `on_notification`, plus ad‑hoc `run` via execution queue. Plugins execute as scripts that write result logs for ingestion.
+## Architecture
 
-## Plugin patterns that matter
-- Manifest lives at `front/plugins/<code_name>/config.json`; `code_name` == folder, `unique_prefix` drives settings and filenames (e.g., `ARPSCAN`).
-- Control via settings: `<PREF>_RUN` (phase), `<PREF>_RUN_SCHD` (cron-like), `<PREF>_CMD` (script path), `<PREF>_RUN_TIMEOUT`, `<PREF>_WATCH` (diff columns).
-- Data contract: scripts write `/tmp/log/plugins/last_result.<PREF>.log` (pipe‑delimited: 9 required cols + optional 4). Use `front/plugins/plugin_helper.py`’s `Plugin_Objects` to sanitize text and normalize MACs, then `write_result_file()`.
-- Device import: define `database_column_definitions` when creating/updating devices; watched fields trigger notifications.
+- **Backend (Python):** `server/__main__.py`, `server/plugin.py`, `server/api_server/api_server_start.py`
+- **Backend Config:** `/data/config/app.conf`
+- **Data (SQLite):** `/data/db/app.db`; helpers in `server/db/*`
+- **Frontend (Nginx + PHP + JS):** `front/`
+- **Plugins (Python):** `front/plugins/*` with `config.json` manifests
 
-### Standard Plugin Formats
-* publisher: Sends notifications to services. Runs `on_notification`. Data source: self.
-* dev scanner: Creates devices and manages online/offline status. Runs on `schedule`. Data source: self / SQLite DB.
-* name discovery: Discovers device names via various protocols. Runs `before_name_updates` or on `schedule`. Data source: self.
-* importer: Imports devices from another service. Runs on `schedule`. Data source: self / SQLite DB.
-* system: Provides core system functionality. Runs on `schedule` or is always on. Data source: self / Template.
-* other: Miscellaneous plugins. Runs at various times. Data source: self / Template.
+## Skills
 
-### Plugin logging & outputs
-- Always check relevant logs first.
-- Use logging as shown in other plugins.
-- Collect results with `Plugin_Objects.add_object(...)` during processing and call `plugin_objects.write_result_file()` exactly once at the end of the script.
-- Prefer to log a brief summary before writing (e.g., total objects added) to aid troubleshooting; keep logs concise at `info` level and use `verbose` or `debug` for extra context.
-- Do not write ad‑hoc files for results; the only consumable output is `last_result.<PREF>.log` generated by `Plugin_Objects`.
+Procedural knowledge lives in `.github/skills/`. Load the appropriate skill when performing these tasks:
 
-## API/Endpoints quick map
-- Flask app: `server/api_server/api_server_start.py` exposes routes like `/device/<mac>`, `/devices`, `/devices/export/{csv,json}`, `/devices/import`, `/devices/totals`, `/devices/by-status`, plus `nettools`, `events`, `sessions`, `dbquery`, `metrics`, `sync`.
-- Authorization: all routes expect header `Authorization: Bearer <API_TOKEN>` via `get_setting_value('API_TOKEN')`.
-- All responses need to return `"success":<False:True>` and if `False` an "error" message needs to be returned, e.g. `{"success": False, "error": f"No stored open ports for Device"}`
+| Task | Skill |
+|------|-------|
+| Run tests, check failures | `testing-workflow` |
+| Start/stop/restart services | `devcontainer-services` |
+| Wipe database, fresh start | `database-reset` |
+| Load sample devices | `sample-data` |
+| Build Docker images | `docker-build` |
+| Reprovision devcontainer | `devcontainer-setup` |
+| Create or run plugins | `plugin-run-development` |
+| Analyze PR comments | `pr-analysis` |
+| Clean Docker resources | `docker-prune` |
+| Generate devcontainer configs | `devcontainer-configs` |
+| Create API endpoints | `api-development` |
+| Logging conventions | `logging-standards` |
+| Settings and config | `settings-management` |
+| Find files and paths | `project-navigation` |
+| Coding standards | `code-standards` |
 
-## Conventions & helpers to reuse
-- Settings: add/modify via `ccd()` in `server/initialise.py` or per‑plugin manifest. Never hardcode ports or secrets; use `get_setting_value()`.
-- Logging: use `mylog(level, [message])`; levels: none/minimal/verbose/debug/trace. `none` is used for most important messages that should always appear, such as exceptions. Do NOT use `error` as level.
-- Time/MAC/strings: `server/utils/datetime_utils.py` (`timeNowDB`), `front/plugins/plugin_helper.py` (`normalize_mac`), `server/helper.py` (sanitizers). Validate MACs before DB writes.
-- DB helpers: prefer `server/db/db_helper.py` functions (e.g., `get_table_json`, device condition helpers) over raw SQL in new paths.
+## Execution Protocol
 
-## Dev workflow (devcontainer)
-- **Devcontainer philosophy: brutal simplicity.** One user, everything writable, completely idempotent. No permission checks, no conditional logic, no sudo needed. If something doesn't work, tear down the wall and rebuild - don't patch. We unit test permissions in the hardened build.
-- **Permissions:** Never `chmod` or `chown` during operations. Everything is already writable. If you need permissions, the devcontainer setup is broken - fix `.devcontainer/scripts/setup.sh` or `.devcontainer/resources/devcontainer-Dockerfile` instead.
-- **Files & Paths:** Use environment variables (`NETALERTX_DB`, `NETALERTX_LOG`, etc.) everywhere. `/data` for persistent config/db, `/tmp` for runtime logs/api/nginx state. Never hardcode `/data/db` or relative paths.
-- **Database reset:** Use the `[Dev Container] Wipe and Regenerate Database` task. Kills backend, deletes `/data/{db,config}/*`, runs first-time setup scripts. Clean slate, no questions.
-- Services: use tasks to (re)start backend and nginx/PHP-FPM. Backend runs with debugpy on 5678; attach a Python debugger if needed.
-- Run a plugin manually: `python3 front/plugins/<code_name>/script.py` (ensure `sys.path` includes `/app/front/plugins` and `/app/server` like the template).
-- Testing: pytest available via Alpine packages. Tests live in `test/`; app code is under `server/`. PYTHONPATH is preconfigured to include workspace and `/opt/venv` site‑packages.
-- **Subprocess calls:** ALWAYS set explicit timeouts. Default to 60s minimum unless plugin config specifies otherwise. Nested subprocess calls (e.g., plugins calling external tools) need their own timeout - outer plugin timeout won't save you.
-- you need to set the BACKEND_API_URL setting (e.g. in teh app.conf file or via the APP_CONF_OVERRIDE env variable) to the backend api port url , e.g. https://something-20212.app.github.dev/ depending on your github codespace url.
-
-## What “done right” looks like
-- When adding a plugin, start from `front/plugins/__template`, implement with `plugin_helper`, define manifest settings, and wire phase via `<PREF>_RUN`. Verify logs in `/tmp/log/plugins/` and data in `api/*.json`.
-- When introducing new config, define it once (core `ccd()` or plugin manifest) and read it via helpers everywhere.
-- When exposing new server functionality, add endpoints in `server/api_server/*` and keep authorization consistent; update UI by reading/writing JSON cache rather than bypassing the pipeline.
-- Always try following the DRY principle, do not re-implement functionality, but re-use existing methods where possible, or refactor to use a common method that is called multiple times
-- If new functionality needs to be added, look at impenting it into existing handlers (e.g. `DeviceInstance` in `server/models/device_instance.py`) or create a new one if it makes sense. Do not access the DB from otehr application layers.
-- Code files shoudln't be longer than 500 lines of code
-
-## Useful references
-- Docs: `docs/PLUGINS_DEV.md`, `docs/SETTINGS_SYSTEM.md`, `docs/API_*.md`, `docs/DEBUG_*.md`
-- Logs: All logs are under `/tmp/log/`. Plugin logs are very shortly under `/tmp/log/plugins/` until picked up by the server.
-  - plugin logs: `/tmp/log/plugins/*.log`
-  - backend logs: `/tmp/log/stdout.log` and `/tmp/log/stderr.log`
-  - php errors: `/tmp/log/app.php_errors.log`
-  - nginx logs: `/tmp/log/nginx-access.log` and `/tmp/log/nginx-error.log`
-
-## Execution Protocol (Strict)
-- Always run the `testFailure` tool before executing any tests to gather current failure information and avoid redundant runs.
-- Always prioritize using the appropriate tools in the environment first. Example: if a test is failing use `testFailure` then `runTests`.
-- Docker tests take an extremely long time to run. Avoid changes to docker or tests until you've examined the existing `testFailure`s and `runTests` results.
+- **Before running tests:** Always use `testFailure` tool first to gather current failures.
+- **Docker tests are slow.** Examine existing failures before changing tests or Dockerfiles.

.github/skills/api-development/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: api-development
+description: Develop and extend NetAlertX REST API endpoints. Use this when asked to create endpoint, add API route, implement API, or modify API responses.
+---
+
+# API Development
+
+## Entry Point
+
+Flask app: `server/api_server/api_server_start.py`
+
+## Existing Routes
+
+- `/device/<mac>` - Single device operations
+- `/devices` - Device list
+- `/devices/export/{csv,json}` - Export devices
+- `/devices/import` - Import devices
+- `/devices/totals` - Device counts
+- `/devices/by-status` - Devices grouped by status
+- `/nettools` - Network utilities
+- `/events` - Event log
+- `/sessions` - Session management
+- `/dbquery` - Database queries
+- `/metrics` - Prometheus metrics
+- `/sync` - Synchronization
+
+## Authorization
+
+All routes require header:
+
+```
+Authorization: Bearer <API_TOKEN>
+```
+
+Retrieve token via `get_setting_value('API_TOKEN')`.
+
+## Response Contract
+
+**MANDATORY:** All responses must include `"success": true|false`
+
+```python
+return {"success": False, "error": "Description of what went wrong"}
+```
+
+On success:
+
+```python
+return {"success": True, "data": result}
+```
+
+```python
+return {"success": False, "error": "Description of what went wrong"}
+```
+
+On success:
+
+```python
+return {"success": True, "data": result}
+```
+
+
+**Exception:** The legacy `/device/<mac>` GET endpoint does not follow this contract to maintain backward compatibility with the UI.
+
+## Adding New Endpoints
+
+1. Add route in `server/api_server/` directory
+2. Follow authorization pattern
+3. Return proper response contract
+4. Update UI to read/write JSON cache (don't bypass pipeline)

.github/skills/authentication/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: netalertx-authentication-tokens
+description: Manage and troubleshoot API tokens and authentication-related secrets. Use this when you need to find, rotate, verify, or debug authentication issues (401/403) in NetAlertX.
+---
+
+# Authentication
+
+## Purpose ✅
+Explain how to locate, validate, rotate, and troubleshoot API tokens and related authentication settings used by NetAlertX.
+
+## Pre-Flight Check (MANDATORY) ⚠️
+1. Ensure the backend is running (use devcontainer services or `ps`/systemd checks).
+2. Verify the `API_TOKEN` setting can be read with Python (see below).
+3. If a token-related error occurs, gather logs (`/tmp/log/app.log`, nginx logs) before changing secrets.
+
+## Retrieve the API token (Python — preferred) 🐍
+Always use Python helpers to read secrets to avoid accidental exposure in shells or logs:
+
+```python
+from helper import get_setting_value
+token = get_setting_value("API_TOKEN")
+```
+
+If you must inspect from a running container (read-only), use:
+
+```bash
+docker exec <CONTAINER_ID> python3 -c "from helper import get_setting_value; print(get_setting_value('API_TOKEN'))"
+```
+
+You can also check the runtime config file:
+
+```bash
+docker exec <CONTAINER_ID> grep API_TOKEN /data/config/app.conf
+```
+
+## Rotate / Generate a new token 🔁
+- Preferred: Use the web UI (Settings / System) and click **Generate** for the `API_TOKEN` field — this updates the value safely and immediately.
+- Manual: Edit `/data/config/app.conf` and restart the backend if required (use the existing devcontainer service tasks).
+- After rotation: verify the value with `get_setting_value('API_TOKEN')` and update any clients or sync nodes to use the new token.
+
+## Troubleshooting 401 / 403 Errors 🔍
+1. Confirm backend is running and reachable.
+2. Confirm `get_setting_value('API_TOKEN')` returns a non-empty value.
+3. Ensure client requests send the header exactly: `Authorization: Bearer <API_TOKEN>`.
+4. Check `/tmp/log/app.log` and plugin logs (e.g., sync plugin) for "Incorrect API Token" messages.
+5. If using multiple nodes, ensure the token matches across nodes for sync operations.
+6. If token appears missing or incorrect, rotate via UI or update `app.conf` and re-verify.
+
+## Best Practices & Security 🔐
+- Never commit tokens to source control or paste them in public issues. Redact tokens when sharing logs.
+- Rotate tokens when a secret leak is suspected or per your security policy.
+- Use `get_setting_value()` in tests and scripts — do not hardcode secrets.
+
+## Related Skills & Docs 📚
+- `testing-workflow` — how to use `API_TOKEN` in tests
+- `settings-management` — where settings live and how they are managed
+- Docs: `docs/API.md`, `docs/API_OLD.md`, `docs/API_SSE.md`
+
+---
+_Last updated: 2026-01-23_

.github/skills/code-standards/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: netalertx-code-standards
+description: NetAlertX coding standards and conventions. Use this when writing code, reviewing code, or implementing features.
+---
+
+# Code Standards
+
+- ask me to review before going to each next step (mention n step out of x)
+- before starting, prepare implementation plan
+- ask me to review it and ask any clarifying questions first
+- add test creation as last step - follow repo architecture patterns - do not place in the root of /test
+- code has to be maintainable, no duplicate code
+- follow DRY principle
+- code files should be less than 500 LOC for better maintainability
+
+## File Length
+
+Keep code files under 500 lines. Split larger files into modules.
+
+## DRY Principle
+
+Do not re-implement functionality. Reuse existing methods or refactor to create shared methods.
+
+## Database Access
+
+- Never access DB directly from application layers
+- Use `server/db/db_helper.py` functions (e.g., `get_table_json`)
+- Implement new functionality in handlers (e.g., `DeviceInstance` in `server/models/device_instance.py`)
+
+## MAC Address Handling
+
+Always validate and normalize MACs before DB writes:
+
+```python
+from plugin_helper import normalize_mac
+
+mac = normalize_mac(raw_mac)
+```
+
+## Subprocess Safety
+
+**MANDATORY:** All subprocess calls must set explicit timeouts.
+
+```python
+result = subprocess.run(cmd, timeout=60)  # Minimum 60s
+```
+
+Nested subprocess calls need their own timeout—outer timeout won't save you.
+
+## Time Utilities
+
+```python
+from utils.datetime_utils import timeNowUTC
+
+timestamp = timeNowUTC()
+```
+
+This is the ONLY function that calls datetime.datetime.now() in the entire codebase.
+
+⚠️ CRITICAL: ALL database timestamps MUST be stored in UTC
+This is the SINGLE SOURCE OF TRUTH for current time in NetAlertX
+Use timeNowUTC() for DB writes (returns UTC string by default)
+Use timeNowUTC(as_string=False) for datetime operations (scheduling, comparisons, logging)
+
+## String Sanitization
+
+Use sanitizers from `server/helper.py` before storing user input.
+
+## Devcontainer Constraints
+
+- Never `chmod` or `chown` during operations
+- Everything is already writable
+- If permissions needed, fix `.devcontainer/scripts/setup.sh`
+
+## Path Hygiene
+
+- Use environment variables for runtime paths
+- `/data` for persistent config/db
+- `/tmp` for runtime logs/api/nginx state
+- Never hardcode `/data/db` or use relative paths

.github/skills/database-reset/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: reset-netalertx-database
+description: Wipe and regenerate the NetAlertX database and config. Use this when asked to reset database, wipe db, fresh database, clean slate, or start fresh.
+---
+
+# Database Reset
+
+Completely wipes devcontainer database and config, then regenerates from scratch.
+
+## Command
+
+```bash
+killall 'python3' || true
+sleep 1
+rm -rf /data/db/* /data/config/*
+bash /entrypoint.d/15-first-run-config.sh
+bash /entrypoint.d/20-first-run-db.sh
+```
+
+## What This Does
+
+1. Kills backend to release database locks
+2. Deletes all files in `/data/db/` and `/data/config/`
+3. Runs first-run config provisioning
+4. Runs first-run database initialization
+
+## After Reset
+
+Run the startup script to restart services:
+
+```bash
+/workspaces/NetAlertX/.devcontainer/scripts/setup.sh
+```
+
+## Database Location
+
+- Runtime: `/data/db/app.db` (SQLite)
+- Config: `/data/config/app.conf`

.github/skills/devcontainer-configs/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: netalertx-devcontainer-configs
+description: Generate devcontainer configuration files. Use this when asked to generate devcontainer configs, update devcontainer template, or regenerate devcontainer.
+---
+
+# Devcontainer Config Generation
+
+Generates devcontainer configs from the template. Must be run after changes to devcontainer configuration.
+
+## Command
+
+```bash
+/workspaces/NetAlertX/.devcontainer/scripts/generate-configs.sh
+```
+
+## What It Does
+
+Combines and merges template configurations into the final config used by VS Code.
+
+## When to Run
+
+- After modifying `.devcontainer/` template files
+- After changing devcontainer features or settings
+- Before committing devcontainer changes
+
+## Note
+
+This affects only the devcontainer configuration. It has no bearing on the production or test Docker image.

.github/skills/devcontainer-services/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: restarting-netalertx-services
+description: Control NetAlertX services inside the devcontainer. Use this when asked to start backend, start frontend, start nginx, start php-fpm, start crond, stop services, restart services, or check if services are running.
+---
+
+# Devcontainer Services
+
+You operate inside the devcontainer. Do not use `docker exec`.
+
+## Start Backend (Python)
+
+```bash
+/services/start-backend.sh
+```
+
+Backend runs with debugpy on port 5678 for debugging. Takes ~5 seconds to be ready.
+
+## Start Frontend (nginx + PHP-FPM)
+
+```bash
+/services/start-php-fpm.sh &
+/services/start-nginx.sh &
+```
+
+Launches almost instantly.
+
+## Start Scheduler (CronD)
+
+```bash
+/services/start-crond.sh
+```
+
+## Stop All Services
+
+```bash
+pkill -f 'php-fpm83|nginx|crond|python3' || true
+```
+
+## Check Running Services
+
+```bash
+pgrep -a 'python3|nginx|php-fpm|crond'
+```
+
+## Service Ports
+
+- Frontend (nginx): 20211
+- Backend API: 20212
+- GraphQL: 20212
+- Debugpy: 5678

.github/skills/devcontainer-setup/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: netalertx-idempotent-setup
+description: Reprovision and reset the devcontainer environment. Use this when asked to re-run startup, reprovision, setup devcontainer, fix permissions, or reset runtime state.
+---
+
+# Devcontainer Setup
+
+The setup script forcefully resets all runtime state. It is idempotent—every run wipes and recreates all relevant folders, symlinks, and files.
+
+## Command
+
+```bash
+/workspaces/NetAlertX/.devcontainer/scripts/setup.sh
+```
+
+## What It Does
+
+1. Kills all services (php-fpm, nginx, crond, python3)
+2. Mounts tmpfs ramdisks for `/tmp/log`, `/tmp/api`, `/tmp/run`, `/tmp/nginx`
+3. Creates critical subdirectories
+4. Links `/entrypoint.d` and `/app` symlinks
+5. Creates `/data`, `/data/config`, `/data/db` directories
+6. Creates all log files
+7. Runs `/entrypoint.sh` to start services
+8. Writes version to `.VERSION`
+
+## When to Use
+
+- After modifying setup scripts
+- After container rebuild
+- When environment is in broken state
+- After database reset
+
+## Philosophy
+
+No conditional logic. Everything is recreated unconditionally. If something doesn't work, run setup again.

.github/skills/docker-build/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: netalertx-docker-build
+description: Build Docker images for testing or production. Use this when asked to build container, build image, docker build, build test image, or launch production container.
+---
+
+# Docker Build
+
+## Build Unit Test Image
+
+Required after container/Dockerfile changes. Tests won't see changes until image is rebuilt.
+
+```bash
+docker buildx build -t netalertx-test .
+```
+
+Build time: ~30 seconds (or ~90s if venv stage changes)
+
+## Build and Launch Production Container
+
+Before launching, stop devcontainer services first to free ports.
+
+```bash
+cd /workspaces/NetAlertX
+docker compose up -d --build --force-recreate
+```
+
+## Pre-Launch Checklist
+
+1. Stop devcontainer services: `pkill -f 'php-fpm83|nginx|crond|python3'`
+2. Close VS Code forwarded ports
+3. Run the build command
+
+## Production Container Details
+
+- Image: `netalertx:latest`
+- Container name: `netalertx`
+- Network mode: host
+- Ports: 20211 (UI), 20212 (API/GraphQL)

.github/skills/docker-prune/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: netalertx-docker-prune
+description: Clean up unused Docker resources. Use this when asked to prune docker, clean docker, remove unused images, free disk space, or docker cleanup. DANGEROUS operation. Requires human confirmation.
+---
+
+# Docker Prune
+
+**DANGER:** This destroys containers, images, volumes, and networks. Any stopped container will be wiped and data will be lost.
+
+## Command
+
+```bash
+/workspaces/NetAlertX/.devcontainer/scripts/confirm-docker-prune.sh
+```
+
+## What Gets Deleted
+
+- All stopped containers
+- All unused images
+- All unused volumes
+- All unused networks
+
+## When to Use
+
+- Disk space is low
+- Build cache is corrupted
+- Clean slate needed for testing
+- After many image rebuilds
+
+## Safety
+
+The script requires explicit confirmation before proceeding.

.github/skills/mcp-activation/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: mcp-activation
+description: Enables live interaction with the NetAlertX runtime. This skill configures the Model Context Protocol (MCP) connection, granting full API access for debugging, troubleshooting, and real-time operations including database queries, network scans, and device management.
+---
+
+# MCP Activation Skill
+
+This skill configures the environment to expose the Model Context Protocol (MCP) server to AI agents running inside the devcontainer.
+
+## Usage
+
+This skill assumes you are already running within the NetAlertX devcontainer. 
+
+1.  **Generate Configurations:**
+    Run the configuration generation script to extract the API Token and update the VS Code MCP settings.
+
+    ```bash
+    /workspaces/NetAlertX/.devcontainer/scripts/generate-configs.sh
+    ```
+
+2.  **Reload Window:**
+    Request the user to reload the VS Code window to activate the new tools.
+    > I have generated the MCP configuration. Please run the **'Developer: Reload Window'** command to activate the MCP server tools.
+    > In VS Code: open the Command Palette (Windows/Linux: Ctrl+Shift+P, macOS: Cmd+Shift+P), type Developer: Reload Window, press Enter — or click the Reload button if a notification appears. 🔁
+    > After you reload, tell me “Window reloaded” (or just “reloaded”) and I’ll continue.
+
+
+## Why use this?
+
+Access the live runtime API to perform operations that are not possible through static file analysis:
+- **Query the database**
+- **Trigger network scans**
+- **Manage devices and events**
+- **Troubleshoot real-time system state**

.github/skills/plugin-run-development/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: netalertx-plugin-run-development
+description: Create and run NetAlertX plugins. Use this when asked to create plugin, run plugin, test plugin, plugin development, or execute plugin script.
+---
+
+# Plugin Development
+
+## Expected Workflow for Running Plugins
+
+1. Read this skill document for context and instructions.
+2. Find the plugin in `front/plugins/<code_name>/`.
+3. Read the plugin's `config.json` and `script.py` to understand its functionality and settings.
+4. Formulate and run the command: `python3 front/plugins/<code_name>/script.py`.
+5. Retrieve the result from the plugin log folder (`/tmp/log/plugins/last_result.<PREF>.log`) quickly, as the backend may delete it after processing.
+
+## Run a Plugin Manually
+
+```bash
+python3 front/plugins/<code_name>/script.py
+```
+
+Ensure `sys.path` includes `/app/front/plugins` and `/app/server` (as in the template).
+
+## Plugin Structure
+
+```text
+front/plugins/<code_name>/
+├── config.json      # Manifest with settings
+├── script.py        # Main script
+└── ...
+```
+
+## Manifest Location
+
+`front/plugins/<code_name>/config.json`
+
+- `code_name` == folder name
+- `unique_prefix` drives settings and filenames (e.g., `ARPSCAN`)
+
+## Settings Pattern
+
+- `<PREF>_RUN`: execution phase
+- `<PREF>_RUN_SCHD`: cron-like schedule
+- `<PREF>_CMD`: script path
+- `<PREF>_RUN_TIMEOUT`: timeout in seconds
+- `<PREF>_WATCH`: columns to watch for changes
+
+## Data Contract
+
+Scripts write to `/tmp/log/plugins/last_result.<PREF>.log`
+
+**Important:** The backend will almost immediately process this result file and delete it after ingestion. If you need to inspect the output, run the plugin and immediately retrieve the result file before the backend processes it.
+
+Use `front/plugins/plugin_helper.py`:
+
+```python
+from plugin_helper import Plugin_Objects
+
+plugin_objects = Plugin_Objects()
+plugin_objects.add_object(...)  # During processing
+plugin_objects.write_result_file()  # Exactly once at end
+```
+
+## Execution Phases
+
+- `once`: runs once at startup
+- `schedule`: runs on cron schedule
+- `always_after_scan`: runs after every scan
+- `before_name_updates`: runs before name resolution
+- `on_new_device`: runs when new device detected
+- `on_notification`: runs when notification triggered
+
+## Plugin Formats
+
+| Format | Purpose | Runs |
+|--------|---------|------|
+| publisher | Send notifications | `on_notification` |
+| dev scanner | Create/manage devices | `schedule` |
+| name discovery | Discover device names | `before_name_updates` |
+| importer | Import from services | `schedule` |
+| system | Core functionality | `schedule` |
+
+## Starting Point
+
+Copy from `front/plugins/__template` and customize.

.github/skills/project-navigation/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: about-netalertx-project-structure
+description: Navigate the NetAlertX codebase structure. Use this when asked about file locations, project structure, where to find code, or key paths.
+---
+
+# Project Navigation
+
+## Key Paths
+
+| Component | Path |
+|-----------|------|
+| Workspace root | `/workspaces/NetAlertX` |
+| Backend entry | `server/__main__.py` |
+| API server | `server/api_server/api_server_start.py` |
+| Plugin system | `server/plugin.py` |
+| Initialization | `server/initialise.py` |
+| Frontend | `front/` |
+| Frontend JS | `front/js/common.js` |
+| Frontend PHP | `front/php/server/*.php` |
+| Plugins | `front/plugins/` |
+| Plugin template | `front/plugins/__template` |
+| Database helpers | `server/db/db_helper.py` |
+| Device model | `server/models/device_instance.py` |
+| Messaging | `server/messaging/` |
+| Workflows | `server/workflows/` |
+
+## Architecture
+
+NetAlertX uses a frontend–backend architecture: the frontend runs on **PHP + Nginx** (see `front/`), the backend is implemented in **Python** (see `server/`), and scheduled tasks are managed by a **supercronic** scheduler that runs periodic jobs.
+
+## Runtime Paths
+
+| Data | Path |
+|------|------|
+| Config (runtime) | `/data/config/app.conf` |
+| Config (default) | `back/app.conf` |
+| Database | `/data/db/app.db` |
+| API JSON cache | `/tmp/api/*.json` |
+| Logs | `/tmp/log/` |
+| Plugin logs | `/tmp/log/plugins/` |
+
+## Environment Variables
+
+Use these NETALERTX_* instead of hardcoding paths. Examples:
+
+- `NETALERTX_DB`
+- `NETALERTX_LOG`
+- `NETALERTX_CONFIG`
+- `NETALERTX_DATA`
+- `NETALERTX_APP`
+
+## Documentation
+
+| Topic | Path |
+|-------|------|
+| Plugin development | `docs/PLUGINS_DEV.md` |
+| System settings | `docs/SETTINGS_SYSTEM.md` |
+| API docs | `docs/API_*.md` |
+| Debug guides | `docs/DEBUG_*.md` |

.github/skills/sample-data/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: netalertx-sample-data
+description: Load synthetic device data into the devcontainer. Use this when asked to load sample devices, seed data, import test devices, populate database, or generate test data.
+---
+
+# Sample Data Loading
+
+Generates synthetic device inventory and imports it via the `/devices/import` API endpoint.
+
+## Command
+
+```bash
+cd /workspaces/NetAlertX/.devcontainer/scripts
+./load-devices.sh
+```
+
+## Environment
+
+- `CSV_PATH`: defaults to `/tmp/netalertx-devices.csv`
+
+## Prerequisites
+
+- Backend must be running
+- API must be accessible
+
+## What It Does
+
+1. Generates synthetic device records (MAC addresses, IPs, names, vendors)
+2. Creates CSV file at `$CSV_PATH`
+3. POSTs to `/devices/import` endpoint
+4. Devices appear in database and UI

.github/skills/settings-management/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: netalertx-settings-management
+description: Manage NetAlertX configuration settings. Use this when asked to add setting, read config, get_setting_value, ccd, or configure options.
+---
+
+# Settings Management
+
+## Reading Settings
+
+```python
+from helper import get_setting_value
+
+value = get_setting_value('SETTING_NAME')
+```
+
+Never hardcode ports, secrets, or configuration values. Always use `get_setting_value()`.
+
+## Adding Core Settings
+
+Use `ccd()` in `server/initialise.py`:
+
+```python
+ccd('SETTING_NAME', 'default_value', 'description')
+```
+
+## Adding Plugin Settings
+
+Define in plugin's `config.json` manifest under the settings section.
+
+## Config Files
+
+| File | Purpose |
+|------|---------|
+| `/data/config/app.conf` | Runtime config (modified by app) |
+| `back/app.conf` | Default config (template) |
+
+## Environment Override
+
+Use `APP_CONF_OVERRIDE` environment variable for settings that must be set before startup.

.github/skills/testing-workflow/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: netalertx-testing-workflow
+description: Run and debug tests in the NetAlertX devcontainer. Use this when asked to run tests, check test failures, debug failing tests, or execute pytest.
+---
+
+# Testing Workflow
+
+## Pre-Flight Check (MANDATORY)
+
+Before running any tests, always check for existing failures first:
+
+1. Use the `testFailure` tool to gather current failure information
+2. Review the failures to understand what's already broken
+3. Only then proceed with test execution
+
+## Running Tests
+
+Use VS Code's testing interface or the `runTests` tool with appropriate parameters:
+
+- To run all tests: invoke runTests without file filter
+- To run specific test file: invoke runTests with the test file path
+- To run failed tests only: invoke runTests with `--lf` flag
+
+## Test Location
+
+Tests live in `test/` directory. App code is under `server/`.
+
+PYTHONPATH is preconfigured to include the following which should meet all needs:
+- `/app` # the primary location where python runs in the production system
+- `/app/server` # symbolic link to /wprkspaces/NetAlertX/server
+- `/app/front/plugins` # symbolic link to /workspaces/NetAlertX/front/plugins
+- `/opt/venv/lib/pythonX.Y/site-packages`
+- `/workspaces/NetAlertX/test`
+- `/workspaces/NetAlertX/server`
+- `/workspaces/NetAlertX`
+- `/usr/lib/pythonX.Y/site-packages`
+
+## Authentication in Tests
+
+Retrieve `API_TOKEN` using Python (not shell):
+
+```python
+from helper import get_setting_value
+token = get_setting_value("API_TOKEN")
+```
+
+## Troubleshooting 403 Forbidden
+
+1. Ensure backend is running (use devcontainer-services skill)
+2. Verify config loaded: `get_setting_value("API_TOKEN")` returns non-empty
+3. Re-run startup if needed (use devcontainer-setup skill)
+
+## Docker Test Image
+
+If container changes affect tests, rebuild the test image first:
+
+```bash
+docker buildx build -t netalertx-test .
+```
+
+This takes ~30 seconds unless venv stage changes (~90s).

.github/workflows/code-checks.yml

@@ -1,4 +1,4 @@
-name: Code checks
+name: ✅ Code checks
 on:
   push:
     branches:
@@ -17,6 +17,23 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: 🚨 Ensure DELETE FROM CurrentScan is not commented out
+        run: |
+          echo "🔍 Checking that DELETE FROM CurrentScan is not commented out..."
+
+          MATCHES=$(grep -RInE '^[[:space:]]*#[[:space:]]*db\.sql\.execute\("DELETE FROM CurrentScan"\)' \
+            --include="*.py" .) || true
+
+          if [ -n "$MATCHES" ]; then
+            echo "❌ Found commented-out DELETE FROM CurrentScan call:"
+            echo "$MATCHES"
+            echo
+            echo "This line must NOT be commented out in committed code."
+            exit 1
+          else
+            echo "✅ DELETE FROM CurrentScan is active."
+          fi
+
       - name: Check for incorrect absolute '/php/' URLs in frontend code
         run: |
           echo "🔍 Checking for incorrect absolute '/php/' URLs (should be 'php/' or './php/')..."
@@ -95,5 +112,5 @@ jobs:
       - name: Run Docker-based tests
         run: |
           echo "🐳 Running Docker-based tests..."
-          chmod +x ./test/docker_tests/run_docker_tests.sh
-          ./test/docker_tests/run_docker_tests.sh
+          chmod +x ./scripts/run_tests_in_docker_environment.sh
+          ./scripts/run_tests_in_docker_environment.sh

.github/workflows/docker_cache-cleaner.yml

@@ -1,25 +0,0 @@
-name: 🤖Automation - ci-package-cleaner
-
-on:
-
-  workflow_dispatch: # manual option
-
-  # schedule:
-  #   - cron: '15 22 * * 1' # every Monday 10.15pm UTC (~11.15am Tuesday NZT)
-
-jobs:
-
-  package-cleaner:
-    name: package-cleaner
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    permissions:
-      packages: write
-    steps:
-
-      - uses: actions/delete-package-versions@v4
-        with: 
-          package-name: netalertx
-          package-type: container
-          min-versions-to-keep: 0
-          delete-only-untagged-versions: true

.github/workflows/docker_dev.yml

@@ -1,4 +1,4 @@
-name: docker
+name: 🐳 👩‍💻 docker dev
 
 on:
   push:
@@ -13,13 +13,16 @@ on:
 jobs:
   docker_dev:
     runs-on: ubuntu-latest
-    timeout-minutes: 60
+    timeout-minutes: 90
     permissions:
       contents: read
       packages: write
     if: >
-      contains(github.event.head_commit.message, 'PUSHPROD') != 'True' &&
-      github.repository == 'jokob-sk/NetAlertX'
+      !contains(github.event.head_commit.message, 'PUSHPROD') &&
+      (
+        github.repository == 'jokob-sk/NetAlertX' ||
+        github.repository == 'netalertx/NetAlertX'
+      )
 
     steps:
       - name: Checkout
@@ -62,6 +65,7 @@ jobs:
         uses: docker/metadata-action@v5
         with:
           images: |
+            ghcr.io/netalertx/netalertx-dev
             ghcr.io/jokob-sk/netalertx-dev
             jokobsk/netalertx-dev
           tags: |
@@ -74,12 +78,20 @@ jobs:
             type=semver,pattern={{major}}
             type=sha
 
-      - name: Log in to Github Container Registry (GHCR)
+      - name: Login GHCR (netalertx org)
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login GHCR (jokob-sk legacy)
+        if: github.event_name != 'pull_request'
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: jokob-sk
-          password: ${{ secrets.GITHUB_TOKEN }}
+          password: ${{ secrets.GHCR_JOKOBSK_PAT }}
 
       - name: Log in to DockerHub
         if: github.event_name != 'pull_request'

.github/workflows/docker_dev_unsafe.yml

@@ -0,0 +1,112 @@
+name: 🐳 ⚠ docker-unsafe from next_release branch
+
+on:
+  push:
+    branches:
+      - next_release
+  pull_request:
+    branches:
+      - next_release
+
+jobs:
+  docker_dev_unsafe:
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    permissions:
+      contents: read
+      packages: write
+    if: >
+      !contains(github.event.head_commit.message, 'PUSHPROD') &&
+      (
+        github.repository == 'jokob-sk/NetAlertX' ||
+        github.repository == 'netalertx/NetAlertX'
+      )
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      # --- Generate timestamped dev version
+      - name: Generate timestamp version
+        id: timestamp
+        run: |
+          ts=$(date -u +'%Y%m%d-%H%M%S')
+          echo "version=dev-${ts}" >> $GITHUB_OUTPUT
+          echo "Generated version: dev-${ts}"
+
+      - name: Set up dynamic build ARGs
+        id: getargs
+        run: echo "version=$(cat ./stable/VERSION)" >> $GITHUB_OUTPUT
+
+      - name: Get release version
+        id: get_version
+        run: echo "version=Dev" >> $GITHUB_OUTPUT
+
+      # --- debug output
+      - name: Debug version
+        run: |
+          echo "GITHUB_REF: $GITHUB_REF"
+          echo "Version: '${{ steps.get_version.outputs.version }}'"
+
+      # --- Write the timestamped version to .VERSION file
+      - name: Create .VERSION file
+        run: echo "${{ steps.timestamp.outputs.version }}" > .VERSION
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ghcr.io/netalertx/netalertx-dev-unsafe
+            jokobsk/netalertx-dev-unsafe
+          tags: |
+            type=raw,value=unsafe
+            type=raw,value=${{ steps.timestamp.outputs.version }}
+            type=ref,event=branch
+            type=ref,event=pr
+            type=sha
+
+      - name: Login GHCR (netalertx org)
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login GHCR (jokob-sk legacy)
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: jokob-sk
+          password: ${{ secrets.GHCR_JOKOBSK_PAT }}
+
+      - name: Log in to DockerHub
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64,linux/arm/v7,linux/arm/v6
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: |
+            org.opencontainers.image.title=NetAlertX Dev Unsafe
+            org.opencontainers.image.description=EXPERIMENTAL BUILD – NOT SUPPORTED – DATA LOSS POSSIBLE
+            org.opencontainers.image.version=${{ steps.timestamp.outputs.version }}
+            netalertx.stability=unsafe
+            netalertx.support=none
+            netalertx.data_risk=high
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/docker_prod.yml

@@ -6,18 +6,16 @@
 # GitHub recommends pinning actions to a commit SHA.
 # To get a newer version, you will need to update the SHA.
 # You can also reference a tag or branch, but the action may change without warning.
-name: Publish Docker image
+name: 🐳 🚀 Publish Docker image
 
 on:
   release:
     types: [published]
-    tags:
-      - '*.[1-9]+[0-9]?.[1-9]+*'
 
 jobs:
   docker:
     runs-on: ubuntu-latest
-    timeout-minutes: 60
+    timeout-minutes: 90
     permissions:
       contents: read
       packages: write
@@ -32,18 +30,6 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      # --- Previous approach Get release version from tag
-      - name: Set up dynamic build ARGs
-        id: getargs
-        run: echo "version=$(cat ./stable/VERSION)" >> $GITHUB_OUTPUT
-
-      - name: Get release version
-        id: get_version_prev
-        run: echo "::set-output name=version::${GITHUB_REF#refs/tags/}"
-
-      - name: Create .VERSION file
-        run: echo "${{ steps.get_version.outputs.version }}" >> .VERSION_PREV
-
       # --- Get release version from tag
       - name: Get release version
         id: get_version
@@ -55,7 +41,6 @@ jobs:
         run: |
           echo "GITHUB_REF: $GITHUB_REF"
           echo "Version: '${{ steps.get_version.outputs.version }}'"
-          echo "Version prev: '${{ steps.get_version_prev.outputs.version }}'"
 
       # --- Write version to .VERSION file
       - name: Create .VERSION file
@@ -67,23 +52,30 @@ jobs:
         uses: docker/metadata-action@v5
         with:
           images: |
+            ghcr.io/netalertx/netalertx
             ghcr.io/jokob-sk/netalertx
             jokobsk/netalertx
           tags: |
             type=semver,pattern={{version}},value=${{ steps.get_version.outputs.version }}
             type=semver,pattern={{major}}.{{minor}},value=${{ steps.get_version.outputs.version }}
             type=semver,pattern={{major}},value=${{ steps.get_version.outputs.version }}
-            type=ref,event=branch,suffix=-{{ sha }}
-            type=ref,event=pr
-            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/') }}
+            type=raw,value=latest
 
       - name: Log in to Github Container Registry (GHCR)
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
-          username: jokob-sk
+          username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Login GHCR (jokob-sk legacy)
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: jokob-sk
+          password: ${{ secrets.GHCR_JOKOBSK_PAT }}
+
       - name: Log in to DockerHub
         if: github.event_name != 'pull_request'
         uses: docker/login-action@v3

.github/workflows/docker_rewrite.yml

@@ -1,81 +0,0 @@
-name: docker
-
-on:
-  push:
-    branches:
-      - rewrite
-    tags:
-      - '*.*.*'
-  pull_request:
-    branches:
-      - rewrite
-
-jobs: 
-  docker_rewrite:
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    permissions:
-      contents: read
-      packages: write
-    if: >
-      contains(github.event.head_commit.message, 'PUSHPROD') != 'True' &&
-      github.repository == 'jokob-sk/NetAlertX'  
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Set up dynamic build ARGs
-        id: getargs        
-        run: echo "version=$(cat ./stable/VERSION)" >> $GITHUB_OUTPUT
-
-      - name: Get release version
-        id: get_version
-        run: echo "version=Dev" >> $GITHUB_OUTPUT
-
-      - name: Create .VERSION file
-        run: echo "${{ steps.get_version.outputs.version }}" >> .VERSION
-
-      - name: Docker meta
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: |
-            ghcr.io/jokob-sk/netalertx-dev-rewrite
-            jokobsk/netalertx-dev-rewrite
-          tags: |
-            type=raw,value=latest
-            type=ref,event=branch
-            type=ref,event=pr
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=semver,pattern={{major}}
-            type=sha
-
-      - name: Log in to Github Container Registry (GHCR)
-        uses: docker/login-action@v3
-        with:
-          registry: ghcr.io
-          username: jokob-sk
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Log in to DockerHub
-        if: github.event_name != 'pull_request'
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Build and push
-        uses: docker/build-push-action@v3
-        with:
-          context: .
-          platforms: linux/amd64,linux/arm64,linux/arm/v7,linux/arm/v6
-          push: ${{ github.event_name != 'pull_request' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}

.github/workflows/label-issues.yml

@@ -1,4 +1,4 @@
-name: Label Issues by Installation Type
+name: 🏷 Label Issues by Installation Type
 
 on:
   issues:
@@ -15,21 +15,28 @@ jobs:
         uses: actions/github-script@v7
         with:
           script: |
-            const body = context.payload.issue.body;
+            const body = (context.payload.issue.body || "").toLowerCase();
 
-            const lowerBody = body.toLowerCase();
+            // --- Check for template marker ---
+            const hasTemplate = body.includes('netalertx_template');
 
+            if (!hasTemplate) {
+              console.log("No template marker found, skipping labeling.");
+              return; // skip labeling
+            }
+
+            // --- Proceed with normal labeling ---
             let labelsToAdd = [];
 
-            if (lowerBody.includes('bare-metal') || lowerBody.includes('proxmox')) {
+            if (body.includes('bare-metal') || body.includes('proxmox')) {
               labelsToAdd.push('bare-metal ❗');
             }
 
-            if (lowerBody.includes('home assistant')) {
+            if (body.includes('home assistant')) {
               labelsToAdd.push('Home Assistant 🏠');
             }
 
-            if (lowerBody.includes('production (netalertx)') || lowerBody.includes('dev (netalertx-dev)')) {
+            if (body.includes('production (netalertx)') || body.includes('dev (netalertx-dev)')) {
               labelsToAdd.push('Docker 🐋');
             }
 
@@ -40,4 +47,6 @@ jobs:
                 issue_number: context.issue.number,
                 labels: labelsToAdd
               });
+
+              console.log(`Added labels: ${labelsToAdd.join(", ")}`);
             }

.github/workflows/mkdocs.yml

@@ -1,4 +1,4 @@
-name: Deploy MkDocs
+name: 📘 Deploy MkDocs
 
 on:
   push:

.github/workflows/run-all-tests.yml

@@ -0,0 +1,81 @@
+name: 🧪 Manual Test Suite Selector
+
+on:
+  workflow_dispatch:
+    inputs:
+      run_scan:
+        description: '📂 scan/ (Scan, Logic, Locks, IPs)'
+        type: boolean
+        default: true
+      run_api:
+        description: '📂 api_endpoints/ & server/ (Endpoints & Server)'
+        type: boolean
+        default: false
+      run_backend:
+        description: '📂 backend/ & db/ (SQL Builder, Security & Migration)'
+        type: boolean
+        default: false
+      run_docker_env:
+        description: '📂 docker_tests/ (Environment & PUID/PGID)'
+        type: boolean
+        default: false
+      run_ui:
+        description: '📂 ui/ (Selenium & Dashboard)'
+        type: boolean
+        default: false
+      run_root_files:
+        description: '📄 Root Test Files (WOL, Atomicity, etc.)'
+        type: boolean
+        default: false
+
+jobs:
+  comprehensive-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Environment
+        run: sudo apt-get update && sudo apt-get install -y sqlite3
+
+      - name: Build Test Path Command
+        id: builder
+        run: |
+          PATHS=""
+          # Folder Mapping with 'test/' prefix
+          if [ "${{ github.event.inputs.run_scan }}" == "true" ]; then PATHS="$PATHS test/scan/"; fi
+          if [ "${{ github.event.inputs.run_api }}" == "true" ]; then PATHS="$PATHS test/api_endpoints/ test/server/"; fi
+          if [ "${{ github.event.inputs.run_backend }}" == "true" ]; then PATHS="$PATHS test/backend/ test/db/"; fi
+          if [ "${{ github.event.inputs.run_docker_env }}" == "true" ]; then PATHS="$PATHS test/docker_tests/"; fi
+          if [ "${{ github.event.inputs.run_ui }}" == "true" ]; then PATHS="$PATHS test/ui/"; fi
+
+          # Root Files Mapping (files sitting directly in /test/)
+          if [ "${{ github.event.inputs.run_root_files }}" == "true" ]; then
+            PATHS="$PATHS test/test_device_atomicity.py test/test_mcp_disablement.py test/test_plugin_helper.py test/test_wol_validation.py"
+          fi
+
+          # If nothing is selected, default to the whole test folder
+          if [ -z "$PATHS" ]; then PATHS="test/"; fi
+
+          echo "final_paths=$PATHS" >> $GITHUB_OUTPUT
+
+      - name: Run Docker Integration Script
+        run: |
+          chmod +x ./scripts/run_tests_in_docker_environment.sh
+
+          # We update the pytest command to use the specific paths built above.
+          # Note: We still keep your 'not' filter to skip E2E tests unless you want them.
+          TARGET_PATHS="${{ steps.builder.outputs.final_paths }}"
+          SED_COMMAND="pytest $TARGET_PATHS -m 'not (docker or compose or feature_complete)'"
+
+          echo "🚀 Targeted Pytest Command: $SED_COMMAND"
+
+          sed -i "s|pytest -m 'not (docker or compose or feature_complete)'|$SED_COMMAND|g" ./scripts/run_tests_in_docker_environment.sh
+
+          ./scripts/run_tests_in_docker_environment.sh
+
+      - name: Cleanup
+        if: always()
+        run: |
+          docker stop netalertx-test-container || true
+          docker rm netalertx-test-container || true

.gitignore

@@ -24,6 +24,8 @@ front/api/*
 /api/*
 **/plugins/**/*.log
 **/plugins/cloud_services/*
+**/plugins/cloud_connector/*
+**/plugins/heartbeat/*
 **/%40eaDir/
 **/@eaDir/
 
@@ -46,3 +48,5 @@ docker-compose.yml.ffsb42
 .env.omada.ffsb42
 .venv
 test_mounts/
+.gemini/settings.json
+.vscode/mcp.json

.vscode/settings.json

@@ -31,5 +31,6 @@
   "python.formatting.blackArgs": [
     "--line-length=180"
   ],
+  "chat.useAgentSkills": true,
 
 }

.vscode/tasks.json

@@ -6,6 +6,12 @@
       "type": "promptString",
       "description": "DANGER! Type YES to confirm pruning all unused Docker resources. This will destroy containers, images, volumes, and networks!",
       "default": ""
+    },
+    {
+        "id": "prNumber",
+        "type": "promptString",
+        "description": "Enter GitHub PR Number",
+        "default": "1405"
     }
   ],
   "tasks": [
@@ -256,6 +262,31 @@
         "id": "package",
         "color": "terminal.ansiBlue"
       }
+    },
+    {
+        "label": "Analyze PR Instructions",
+        "type": "shell",
+        "command": "python3",
+        "detail": "Pull all of Coderabbit's suggestions from a pull request. Requires `gh auth login` first.",
+        "options": {
+            "cwd": "/workspaces/NetAlertX/.devcontainer/scripts"
+        },
+        "args": [
+            "/workspaces/NetAlertX/.devcontainer/scripts/coderabbit-pr-parser.py",
+            "${input:prNumber}"
+        ],
+        "problemMatcher": [],
+        "presentation": {
+            "echo": true,
+            "reveal": "always",
+            "panel": "new",
+            "showReuseMessage": false,
+            "focus": true
+        },
+        "icon": {
+            "id": "comment-discussion",
+            "color": "terminal.ansiBlue"
+        }
     }
   ]
 }

Dockerfile

@@ -32,6 +32,7 @@ RUN apk add --no-cache \
         shadow \
         python3 \
         python3-dev \
+        py3-psutil \
         gcc \
         musl-dev \
         libffi-dev \
@@ -133,8 +134,8 @@ ENV LANG=C.UTF-8
 
 RUN apk add --no-cache bash mtr libbsd zip lsblk tzdata curl arp-scan iproute2 iproute2-ss nmap fping \
     nmap-scripts traceroute nbtscan net-tools net-snmp-tools bind-tools awake ca-certificates \
-    sqlite php83 php83-fpm php83-cgi php83-curl php83-sqlite3 php83-session python3 envsubst \
-    nginx supercronic shadow su-exec && \
+    sqlite php83 php83-fpm php83-cgi php83-curl php83-sqlite3 php83-session python3 py3-psutil envsubst \
+    nginx supercronic shadow su-exec jq && \
     rm -Rf /var/cache/apk/*  && \
     rm -Rf /etc/nginx && \
     addgroup -g ${NETALERTX_GID} ${NETALERTX_GROUP} && \
@@ -156,7 +157,6 @@ RUN install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 700 ${READ_WRITE_FO
 
 # Copy version information into the image
 COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} .[V]ERSION ${NETALERTX_APP}/.VERSION
-COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} .[V]ERSION ${NETALERTX_APP}/.VERSION_PREV
 
 # Copy the virtualenv from the builder stage (owned by readonly lock owner)
 COPY --from=builder --chown=${READONLY_UID}:${READONLY_GID} ${VIRTUAL_ENV} ${VIRTUAL_ENV}
@@ -167,7 +167,7 @@ COPY --from=builder --chown=${READONLY_UID}:${READONLY_GID} ${VIRTUAL_ENV} ${VIR
 # although it may be quicker to do it before the copy, it keeps the image
 # layers smaller to do it after.
 # hadolint ignore=DL3018
-RUN for vfile in .VERSION .VERSION_PREV; do \
+RUN for vfile in .VERSION; do \
         if [ ! -f "${NETALERTX_APP}/${vfile}" ]; then \
             echo "DEVELOPMENT 00000000" > "${NETALERTX_APP}/${vfile}"; \
         fi; \

Dockerfile.debian

@@ -1,57 +1,47 @@
-# Warning - use of this unhardened image is not recommended for production use.
-# This image is provided for backward compatibility, development and testing purposes only.
-# For production use, please use the hardened image built with Alpine. This image attempts to
-# treat a container as an operating system, which is an anti-pattern and a common source of
-# security issues.
-#
-# The default Dockerfile/docker-compose image contains the following security improvements
-# over the Debian image:
-# - read-only filesystem
-# - no sudo access
-# - least possible permissions on all files and folders
-# - Root user has all permissions revoked and is unused
-# - Secure umask applied so files are owner-only by default
-# - non-privileged user runs the application
-# - no shell access for non-privileged users
-# - no unnecessary packages or services
-# - reduced capabilities
-# - tmpfs for writable folders
-# - healthcheck
-# - no package managers
-# - no compilers or build tools
-# - no systemd, uses lightweight init system
-# - no persistent storage except for config and db volumes
-# - minimal image size due to segmented build stages
-# - minimal base image (Alpine Linux)
-# - minimal python environment (venv, no pip)
-# - minimal stripped web server
-# - minimal stripped php environment
-# - minimal services (nginx, php-fpm, crond, no unnecessary services or service managers)
-# - minimal users and groups (netalertx and readonly only, no others)
-# - minimal permissions (read-only for most files and folders, write-only for necessary folders)
-# - minimal capabilities (NET_ADMIN and NET_RAW only, no others)
-# - minimal environment variables (only necessary ones, no others)
-# - minimal entrypoint (only necessary commands, no others)
-# - Uses the same base image as the development environmnment (Alpine Linux)
-# - Uses the same services as the development environment (nginx, php-fpm, crond)
-# - Uses the same environment variables as the development environment (only necessary ones, no others)
-# - Uses the same file and folder structure as the development environment (only necessary ones, no others)
-# NetAlertX is designed to be run as an unattended network security monitoring appliance, which means it
-# should be able to operate without human intervention. Overall, the hardened image is designed to be as
-# secure as possible while still being functional and is recommended because you cannot attack a surface
-# that isn't there.
+# Stage 1: Builder
+# Install build dependencies and create virtual environment
+FROM debian:bookworm-slim AS builder
 
+ENV PYTHONUNBUFFERED=1
+ENV VIRTUAL_ENV=/opt/venv
+ENV PATH="${VIRTUAL_ENV}/bin:${PATH}"
 
-FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 \
+    python3-dev \
+    python3-pip \
+    python3-psutil \
+    python3-venv \
+    gcc \
+    git \
+    libffi-dev \
+    libssl-dev \
+    rustc \
+    cargo \
+    && rm -rf /var/lib/apt/lists/*
 
-#TZ=Europe/London
+RUN python3 -m venv ${VIRTUAL_ENV}
+ENV PATH="${VIRTUAL_ENV}/bin:${PATH}"
+
+COPY requirements.txt /tmp/requirements.txt
+RUN pip install --upgrade pip setuptools wheel && \
+    pip install --no-cache-dir -r /tmp/requirements.txt
+
+# Stage 2: Runner
+# Main runtime stage with minimum requirements
+FROM debian:bookworm-slim AS runner
+
+ARG INSTALL_DIR=/app
+ARG NETALERTX_UID=20211
+ARG NETALERTX_GID=20211
+ARG READONLY_UID=20212
+ARG READONLY_GID=20212
 
-# NetAlertX app directories
-ENV INSTALL_DIR=/app
 ENV NETALERTX_APP=${INSTALL_DIR}
 ENV NETALERTX_DATA=/data
 ENV NETALERTX_CONFIG=${NETALERTX_DATA}/config
 ENV NETALERTX_FRONT=${NETALERTX_APP}/front
+ENV NETALERTX_PLUGINS=${NETALERTX_FRONT}/plugins
 ENV NETALERTX_SERVER=${NETALERTX_APP}/server
 ENV NETALERTX_API=/tmp/api
 ENV NETALERTX_DB=${NETALERTX_DATA}/db
@@ -59,8 +49,8 @@ ENV NETALERTX_DB_FILE=${NETALERTX_DB}/app.db
 ENV NETALERTX_BACK=${NETALERTX_APP}/back
 ENV NETALERTX_LOG=/tmp/log
 ENV NETALERTX_PLUGINS_LOG=${NETALERTX_LOG}/plugins
+ENV NETALERTX_CONFIG_FILE=${NETALERTX_CONFIG}/app.conf
 
-# NetAlertX log files
 ENV LOG_IP_CHANGES=${NETALERTX_LOG}/IP_changes.log
 ENV LOG_APP=${NETALERTX_LOG}/app.log
 ENV LOG_APP_FRONT=${NETALERTX_LOG}/app_front.log
@@ -75,102 +65,178 @@ ENV LOG_STDOUT=${NETALERTX_LOG}/stdout.log
 ENV LOG_CRON=${NETALERTX_LOG}/cron.log
 ENV LOG_NGINX_ERROR=${NETALERTX_LOG}/nginx-error.log
 
-# System Services configuration files
+ENV ENTRYPOINT_CHECKS=/entrypoint.d
 ENV SYSTEM_SERVICES=/services
+ENV SYSTEM_SERVICES_SCRIPTS=${SYSTEM_SERVICES}/scripts
 ENV SYSTEM_SERVICES_CONFIG=${SYSTEM_SERVICES}/config
-ENV SYSTEM_NGINIX_CONFIG=${SYSTEM_SERVICES_CONFIG}/nginx
-ENV SYSTEM_NGINX_CONFIG_FILE=${SYSTEM_NGINIX_CONFIG}/nginx.conf
+ENV SYSTEM_NGINX_CONFIG=${SYSTEM_SERVICES_CONFIG}/nginx
+ENV SYSTEM_NGINX_CONFIG_TEMPLATE=${SYSTEM_NGINX_CONFIG}/netalertx.conf.template
+ENV SYSTEM_SERVICES_CONFIG_CRON=${SYSTEM_SERVICES_CONFIG}/cron
 ENV SYSTEM_SERVICES_ACTIVE_CONFIG=/tmp/nginx/active-config
-ENV NETALERTX_CONFIG_FILE=${NETALERTX_CONFIG}/app.conf
+ENV SYSTEM_SERVICES_ACTIVE_CONFIG_FILE=${SYSTEM_SERVICES_ACTIVE_CONFIG}/nginx.conf
 ENV SYSTEM_SERVICES_PHP_FOLDER=${SYSTEM_SERVICES_CONFIG}/php
 ENV SYSTEM_SERVICES_PHP_FPM_D=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.d
-ENV SYSTEM_SERVICES_CROND=${SYSTEM_SERVICES_CONFIG}/crond
 ENV SYSTEM_SERVICES_RUN=/tmp/run
 ENV SYSTEM_SERVICES_RUN_TMP=${SYSTEM_SERVICES_RUN}/tmp
 ENV SYSTEM_SERVICES_RUN_LOG=${SYSTEM_SERVICES_RUN}/logs
 ENV PHP_FPM_CONFIG_FILE=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.conf
 
-#Python environment
-ENV PYTHONPATH=${NETALERTX_SERVER}
+ENV READ_ONLY_FOLDERS="${NETALERTX_BACK} ${NETALERTX_FRONT} ${NETALERTX_SERVER} ${SYSTEM_SERVICES} \
+    ${SYSTEM_SERVICES_CONFIG} ${ENTRYPOINT_CHECKS}"
+ENV READ_WRITE_FOLDERS="${NETALERTX_DATA} ${NETALERTX_CONFIG} ${NETALERTX_DB} ${NETALERTX_API} \
+    ${NETALERTX_LOG} ${NETALERTX_PLUGINS_LOG} ${SYSTEM_SERVICES_RUN} \
+    ${SYSTEM_SERVICES_RUN_TMP} ${SYSTEM_SERVICES_RUN_LOG} \
+    ${SYSTEM_SERVICES_ACTIVE_CONFIG}"
+
 ENV PYTHONUNBUFFERED=1
 ENV VIRTUAL_ENV=/opt/venv
 ENV VIRTUAL_ENV_BIN=/opt/venv/bin
-ENV PATH="${VIRTUAL_ENV}/bin:${PATH}:/services"
-ENV VENDORSPATH=/app/back/ieee-oui.txt
-ENV VENDORSPATH_NEWEST=${SYSTEM_SERVICES_RUN_TMP}/ieee-oui.txt
+ENV PYTHONPATH=${NETALERTX_APP}:${NETALERTX_SERVER}:${NETALERTX_PLUGINS}:${VIRTUAL_ENV}/lib/python3.11/site-packages
+ENV PATH="${SYSTEM_SERVICES}:${VIRTUAL_ENV_BIN}:$PATH"
 
-
-# App Environment
 ENV LISTEN_ADDR=0.0.0.0
 ENV PORT=20211
 ENV NETALERTX_DEBUG=0
-
-#Container environment
+ENV VENDORSPATH=/app/back/ieee-oui.txt
+ENV VENDORSPATH_NEWEST=${SYSTEM_SERVICES_RUN_TMP}/ieee-oui.txt
 ENV ENVIRONMENT=debian
-ENV USER=netalertx
-ENV USER_ID=1000
-ENV USER_GID=1000
+ENV READ_ONLY_USER=readonly READ_ONLY_GROUP=readonly
+ENV NETALERTX_USER=netalertx NETALERTX_GROUP=netalertx
+ENV LANG=C.UTF-8
 
-# Todo, figure out why using a workdir instead of full paths don't work
-# Todo, do we still need all these packages? I can already see sudo which isn't needed
-
-
-# create pi user and group
-# add root and www-data to pi group so they can r/w files and db
-RUN groupadd --gid "${USER_GID}" "${USER}" && \
-    useradd \
-    --uid ${USER_ID} \
-    --gid ${USER_GID} \
-    --create-home \
-    --shell /bin/bash \
-    ${USER} && \
-    usermod -a -G ${USER_GID} root && \
-    usermod -a -G ${USER_GID} www-data
-
-COPY --chmod=775 --chown=${USER_ID}:${USER_GID} install/production-filesystem/ /
-COPY --chmod=775 --chown=${USER_ID}:${USER_GID} . ${INSTALL_DIR}/
-
-
-# ❗ IMPORTANT - if you modify this file modify the /install/install_dependecies.debian.sh file as well ❗
-# hadolint ignore=DL3008,DL3027
+# Install dependencies
+# Using sury.org for PHP 8.3 to match Alpine version
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    tini snmp ca-certificates curl libwww-perl arp-scan sudo gettext-base \
-    nginx-light php php-cgi php-fpm php-sqlite3 php-curl sqlite3 dnsutils net-tools   \
-    python3 python3-dev iproute2 nmap fping python3-pip zip git systemctl usbutils traceroute nbtscan openrc \
-    busybox nginx nginx-core mtr python3-venv && \
-    rm -rf /var/lib/apt/lists/*
-
-# While php8.3 is in debian bookworm repos, php-fpm is not included so we need to add sury.org repo
-# (Ondřej Surý maintains php packages for debian. This is temp until debian includes php-fpm in their
-# repos. Likely it will be in Debian Trixie.).  This keeps the image up-to-date with the alpine version.
-# hadolint ignore=DL3008
-RUN apt-get install -y --no-install-recommends \
-    apt-transport-https \
+    tini \
+    snmp \
     ca-certificates \
+    curl \
+    libwww-perl \
+    arp-scan \
+    sudo \
+    gettext-base \
+    nginx-light \
+    sqlite3 \
+    dnsutils \
+    net-tools \
+    python3 \
+    iproute2 \
+    nmap \
+    fping \
+    zip \
+    git \
+    usbutils \
+    traceroute \
+    nbtscan \
     lsb-release \
-    wget && \
-    wget -q -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg && \
-    echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list && \
-    apt-get update && \
-    apt-get install -y --no-install-recommends php8.3-fpm php8.3-cli php8.3-sqlite3 php8.3-common php8.3-curl php8.3-cgi && \
-    ln -s /usr/sbin/php-fpm8.3 /usr/sbin/php-fpm83 && \
-    rm -rf /var/lib/apt/lists/* # make it compatible with alpine version
+    wget \
+    apt-transport-https \
+    gnupg2 \
+    mtr \
+    procps \
+    gosu \
+    jq \
+    ipcalc \
+    && wget -qO /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg \
+    && echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends \
+    php8.3-fpm \
+    php8.3-cli \
+    php8.3-sqlite3 \
+    php8.3-common \
+    php8.3-curl \
+    && ln -s /usr/sbin/php-fpm8.3 /usr/sbin/php-fpm \
+    && ln -s /usr/sbin/php-fpm8.3 /usr/sbin/php-fpm83 \
+    && ln -s /usr/sbin/gosu /usr/sbin/su-exec \
+    && rm -rf /var/lib/apt/lists/*
 
-# Setup virtual python environment and use pip3 to install packages
-RUN python3 -m venv ${VIRTUAL_ENV} && \
-    /bin/bash -c "source ${VIRTUAL_ENV_BIN}/activate && update-alternatives --install /usr/bin/python python /usr/bin/python3 10 && pip3 install -r ${INSTALL_DIR}/requirements.txt"
+# Fix permissions for /tmp BEFORE copying anything that might overwrite it with bad perms
+RUN chmod 1777 /tmp
 
-# Configure php-fpm
-RUN chmod -R 755 /services && \
-    chown -R ${USER}:${USER_GID} /services  && \
-    sed -i 's/^;listen.mode = .*/listen.mode = 0666/' ${SYSTEM_SERVICES_PHP_FPM_D}/www.conf && \
-    printf "user = %s\ngroup = %s\n" "${USER}" "${USER_GID}" >> /services/config/php/php-fpm.d/www.conf
+# User setup
+RUN groupadd -g ${NETALERTX_GID} ${NETALERTX_GROUP} && \
+    useradd -u ${NETALERTX_UID} -g ${NETALERTX_GID} -d ${NETALERTX_APP} -s /bin/bash ${NETALERTX_USER}
 
+# Copy filesystem (excluding tmp if possible, or we just fix it after)
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} install/production-filesystem/ /
+# Re-apply sticky bit to /tmp in case COPY overwrote it
+RUN chmod 1777 /tmp
 
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 back ${NETALERTX_BACK}
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 front ${NETALERTX_FRONT}
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 server ${NETALERTX_SERVER}
 
-# Create a buildtimestamp.txt to later check if a new version was released
-RUN date +%s > ${INSTALL_DIR}/front/buildtimestamp.txt
-USER netalertx:netalertx
-ENTRYPOINT ["/bin/bash","/entrypoint.sh"]
+# Create required folders
+RUN install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 700 ${READ_WRITE_FOLDERS} && \
+    chmod 750 /entrypoint.sh /root-entrypoint.sh
 
+# Copy Version
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} .[V]ERSION ${NETALERTX_APP}/.VERSION
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} .[V]ERSION ${NETALERTX_APP}/.VERSION_PREV
 
+# Copy venv from builder
+COPY --from=builder --chown=${READONLY_UID}:${READONLY_GID} ${VIRTUAL_ENV} ${VIRTUAL_ENV}
+
+# Init process
+RUN for vfile in .VERSION .VERSION_PREV; do \
+    if [ ! -f "${NETALERTX_APP}/${vfile}" ]; then \
+    echo "DEVELOPMENT 00000000" > "${NETALERTX_APP}/${vfile}"; \
+    fi; \
+    chown ${READONLY_UID}:${READONLY_GID} "${NETALERTX_APP}/${vfile}"; \
+    done && \
+    # Set capabilities for raw socket access
+    setcap cap_net_raw,cap_net_admin+eip /usr/bin/nmap && \
+    setcap cap_net_raw,cap_net_admin+eip /usr/sbin/arp-scan && \
+    setcap cap_net_raw,cap_net_admin,cap_net_bind_service+eip /usr/bin/nbtscan && \
+    setcap cap_net_raw,cap_net_admin+eip /usr/bin/traceroute.db && \
+    # Note: python path needs to be dynamic or verificed
+    # setcap cap_net_raw,cap_net_admin+eip $(readlink -f ${VIRTUAL_ENV_BIN}/python) && \
+    /bin/bash /build/init-nginx.sh && \
+    /bin/bash /build/init-php-fpm.sh && \
+    # /bin/bash /build/init-cron.sh && \
+    # Debian cron init might differ, skipping for now or need to check init-cron.sh content
+    # Checking init-backend.sh
+    /bin/bash /build/init-backend.sh && \
+    rm -rf /build && \
+    date +%s > "${NETALERTX_FRONT}/buildtimestamp.txt"
+
+ENTRYPOINT ["/bin/bash", "/entrypoint.sh"]
+
+# Stage 3: Hardened
+FROM runner AS hardened
+
+ARG NETALERTX_UID=20211
+ARG NETALERTX_GID=20211
+ARG READONLY_UID=20212
+ARG READONLY_GID=20212
+ENV READ_ONLY_USER=readonly READ_ONLY_GROUP=readonly
+
+# Create readonly user
+RUN groupadd -g ${READONLY_GID} ${READ_ONLY_GROUP} && \
+    useradd -u ${READONLY_UID} -g ${READONLY_GID} -d /app -s /usr/sbin/nologin ${READ_ONLY_USER}
+
+# Hardening: Remove package managers and set permissions
+RUN chown -R ${READ_ONLY_USER}:${READ_ONLY_GROUP} ${READ_ONLY_FOLDERS} && \
+    chmod -R 004 ${READ_ONLY_FOLDERS} && \
+    find ${READ_ONLY_FOLDERS} -type d -exec chmod 005 {} + && \
+    install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 0777 ${READ_WRITE_FOLDERS} && \
+    chown ${READ_ONLY_USER}:${READ_ONLY_GROUP} /entrypoint.sh /root-entrypoint.sh /app /opt /opt/venv && \
+    # Permissions
+    chmod 005 /entrypoint.sh /root-entrypoint.sh ${SYSTEM_SERVICES}/*.sh ${SYSTEM_SERVICES_SCRIPTS}/* ${ENTRYPOINT_CHECKS}/* /app /opt /opt/venv && \
+    # Cleanups
+    rm -f \
+    "${NETALERTX_CONFIG}/app.conf" \
+    "${NETALERTX_DB_FILE}" \
+    "${NETALERTX_DB_FILE}-shm" \
+    "${NETALERTX_DB_FILE}-wal" || true && \
+    # Remove apt and sensitive files
+    rm -rf /var/lib/apt /var/lib/dpkg /var/cache/apt /usr/bin/apt* /usr/bin/dpkg* \
+    /etc/shadow /etc/gshadow /etc/sudoers /root /home/root && \
+    # Dummy sudo
+    printf '#!/bin/sh\n"$@"\n' > /usr/bin/sudo && chmod +x /usr/bin/sudo
+
+USER 0
+ENTRYPOINT ["/root-entrypoint.sh"]
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD /services/healthcheck.sh

README.md

@@ -4,34 +4,43 @@
 [![Discord](https://img.shields.io/discord/1274490466481602755?color=0aa8d2&logoColor=fff&logo=Discord&style=for-the-badge)](https://discord.gg/NczTUTWyRr)
 [![Home Assistant](https://img.shields.io/badge/Repo-blue?logo=home-assistant&style=for-the-badge&color=0aa8d2&logoColor=fff&label=Add)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons)
 
-# NetAlertX - Network, presence scanner and alert framework
+# NetAlertX - Network Visibility & Asset Intelligence Framework
 
-Get visibility of what's going on on your WIFI/LAN network and enable presence detection of important devices. Schedule scans for devices, port changes and get alerts if unknown devices or changes are found. Write your own [Plugin](https://docs.netalertx.com/PLUGINS#readme) with auto-generated UI and in-build notification system. Build out and easily maintain your network source of truth (NSoT) and device inventory.
+![main][main]
 
-## 📋 Table of Contents
+<details>
+  <summary>📷 Click for more screenshots</summary>
 
-- [NetAlertX - Network, presence scanner and alert framework](#netalertx---network-presence-scanner-and-alert-framework)
-  - [📋 Table of Contents](#-table-of-contents)
-  - [🚀 Quick Start](#-quick-start)
-  - [📦 Features](#-features)
-    - [Scanners](#scanners)
-    - [Notification gateways](#notification-gateways)
-    - [Integrations and Plugins](#integrations-and-plugins)
-    - [Workflows](#workflows)
-  - [📚 Documentation](#-documentation)
-  - [🔐 Security \& Privacy](#-security--privacy)
-  - [❓ FAQ](#-faq)
-  - [🐞 Known Issues](#-known-issues)
-  - [📃 Everything else](#-everything-else)
-    - [📧 Get notified what's new](#-get-notified-whats-new)
-    - [🔀 Other Alternative Apps](#-other-alternative-apps)
-    - [💙 Donations](#-donations)
-    - [🏗 Contributors](#-contributors)
-    - [🌍 Translations](#-translations)
-    - [License](#license)
+  | ![Main screen][main] | ![device_details 1][device_details]  | ![Screen network][network] |
+  |----------------------|----------------------|----------------------|
+  | ![presence][presence] | ![maintenance][maintenance] | ![settings][settings]  |
+  | ![sync_hub][sync_hub] | ![report1][report1] | ![device_nmap][device_nmap]  |
+
+  Head to [https://netalertx.com/](https://netalertx.com/) for even more gifs and screenshots 📷.
+
+</details>
 
 
-## 🚀 Quick Start
+Centralized network visibility and continuous asset discovery.
+
+Monitor devices, detect change, and stay aware across distributed networks.
+
+NetAlertX provides a centralized "Source of Truth" (NSoT) for network infrastructure. Maintain a real-time inventory of every connected device, identify Shadow IT and unauthorized hardware to maintain regulatory compliance, and automate compliance workflows across distributed sites.
+
+NetAlertX is designed to bridge the gap between simple network scanning and complex SIEM tools, providing actionable insights without the overhead.
+
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Documentation](#documentation)
+- [Security \& Privacy](#security--privacy)
+- [FAQ](#faq)
+- [Troubleshooting Tips](#troubleshooting-tips)
+- [Everything else](#everything-else)
+
+## Quick Start
 
 > [!WARNING]
 > ⚠️ **Important:** The docker-compose has recently changed. Carefully read the [Migration guide](https://docs.netalertx.com/MIGRATION/?h=migrat#12-migration-from-netalertx-v25524) for detailed instructions.
@@ -47,14 +56,14 @@ docker run -d \
   --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
   -e PORT=20211 \
   -e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \
-  ghcr.io/jokob-sk/netalertx:latest
+  ghcr.io/netalertx/netalertx:latest
 ```
 
 Note: Your `/local_data_dir` should contain a `config` and `db` folder.
 
 To deploy a containerized instance directly from the source repository, execute the following BASH sequence:
 ```bash
-git clone https://github.com/jokob-sk/NetAlertX.git
+git clone https://github.com/netalertx/NetAlertX.git
 cd NetAlertX
 docker compose up --force-recreate --build
 # To customize: edit docker-compose.yaml and run that last command again
@@ -64,31 +73,17 @@ Need help configuring it? Check the [usage guide](https://docs.netalertx.com/REA
 
 For Home Assistant users: [Click here to add NetAlertX](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons)
 
-For other install methods, check the [installation docs](#-documentation)
+For other install methods, check the [installation docs](#documentation)
 
+---
+### || [Docker guide](https://docs.netalertx.com/DOCKER_INSTALLATION) || [Releases](https://github.com/netalertx/NetAlertX/releases) || [Docs](https://docs.netalertx.com/) || [Plugins](https://docs.netalertx.com/PLUGINS) || [Website](https://netalertx.com)
+---
 
-| [📑 Docker guide](https://docs.netalertx.com/DOCKER_INSTALLATION) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://docs.netalertx.com/) | [🔌 Plugins](https://docs.netalertx.com/PLUGINS) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
-|----------------------| ----------------------|  ----------------------| ----------------------| ----------------------|
+## Features
 
-![showcase][showcase]
+### Discovery & Asset Intelligence
 
-<details>
-  <summary>📷 Click for more screenshots</summary>
-
-  | ![Main screen][main] | ![device_details 1][device_details]  | ![Screen network][network] |
-  |----------------------|----------------------|----------------------|
-  | ![presence][presence] | ![maintenance][maintenance] | ![settings][settings]  |
-  | ![sync_hub][sync_hub] | ![report1][report1] | ![device_nmap][device_nmap]  |
-
-  Head to [https://netalertx.com/](https://netalertx.com/) for even more gifs and screenshots 📷.
-
-</details>
-
-## 📦 Features
-
-### Scanners
-
-The app scans your network for **New devices**, **New connections** (re-connections), **Disconnections**, **"Always Connected" devices down**, Devices **IP changes** and **Internet IP address changes**. Discovery & scan methods include: **arp-scan**,  **Pi-hole - DB import**,  **Pi-hole - DHCP leases import**, **Generic DHCP leases import**, **UNIFI controller import**, **SNMP-enabled router import**. Check the [Plugins](https://docs.netalertx.com/PLUGINS#readme) docs for a full list of avaliable plugins.
+Continuous monitoring for unauthorized asset discovery, connection state changes, and IP address management (IPAM) drift. Discovery & scan methods include: **arp-scan**,  **Pi-hole - DB import**,  **Pi-hole - DHCP leases import**, **Generic DHCP leases import**, **UNIFI controller import**, **SNMP-enabled router import**. Check the [Plugins](https://docs.netalertx.com/PLUGINS#readme) docs for a full list of avaliable plugins.
 
 ### Notification gateways
 
@@ -101,12 +96,14 @@ build your own scanners with the [Plugin system](https://docs.netalertx.com/PLUG
 
 ### Workflows
 
-The [workflows module](https://docs.netalertx.com/WORKFLOWS) allows to automate repetitive tasks, making network management more efficient. Whether you need to assign newly discovered devices to a specific Network Node, auto-group devices from a given vendor, unarchive a device if detected online, or automatically delete devices, this module provides the flexibility to tailor the automations to your needs.
+The [workflows module](https://docs.netalertx.com/WORKFLOWS) automates IT governance by enforcing device categorization and cleanup policies. Whether you need to assign newly discovered devices to a specific Network Node, auto-group devices from a given vendor, unarchive a device if detected online, or automatically delete devices, this module provides the flexibility to tailor the automations to your needs.
 
 
-## 📚 Documentation
+## Documentation
 <!--- --------------------------------------------------------------------- --->
 
+Explore all the [documentation here](https://docs.netalertx.com/) or navigate to a specific installation option below.
+
 Supported browsers: Chrome, Firefox
 
 - [[Installation] Docker](https://docs.netalertx.com/DOCKER_INSTALLATION)
@@ -117,50 +114,51 @@ Supported browsers: Chrome, Firefox
 - [[Development] API docs](https://docs.netalertx.com/API)
 - [[Development] Custom Plugins](https://docs.netalertx.com/PLUGINS_DEV)
 
-...or explore all the [documentation here](https://docs.netalertx.com/).
-
-## 🔐 Security & Privacy
+## Security & Privacy
 
 NetAlertX scans your local network and can store metadata about connected devices. By default, all data is stored **locally**. No information is sent to external services unless you explicitly configure notifications or integrations.
 
-To further secure your installation:
+Compliance & Hardening:
 - Run it behind a reverse proxy with authentication
 - Use firewalls to restrict access to the web UI
 - Regularly update to the latest version for security patches
+- Role-Based Access Control (RBAC) via Reverse Proxy: Integrate with your existing SSO/Identity provider for secure dashboard access.
 
-See [Security Best Practices](https://github.com/jokob-sk/NetAlertX/security) for more details.
+See [Security Best Practices](https://github.com/netalertx/NetAlertX/security) for more details.
 
 
-## ❓ FAQ
+## FAQ
 
-**Q: Why don’t I see any devices?**
+**Q: How do I monitor VLANs or remote subnets?**
 A: Ensure the container has proper network access (e.g., use `--network host` on Linux). Also check that your scan method is properly configured in the UI.
 
-**Q: Does this work on Wi-Fi-only devices like Raspberry Pi?**
-A: Yes, but some scanners (e.g. ARP) work best on Ethernet. For Wi-Fi, try SNMP, DHCP, or Pi-hole import.
+**Q: What is the recommended deployment for high-availability?**
+A: We recommend deploying via Docker with persistent volume mounts for database integrity and running behind a reverse proxy for secure access.
 
 **Q: Will this send any data to the internet?**
 A: No. All scans and data remain local, unless you set up cloud-based notifications.
 
 **Q: Can I use this without Docker?**
-A: Yes! You can install it bare-metal. See the [bare metal installation guide](https://docs.netalertx.com/HW_INSTALL).
+A: You can install the application directly on your own hardware by following the [bare metal installation guide](https://docs.netalertx.com/HW_INSTALL).
 
 **Q: Where is the data stored?**
 A: In the `/data/config` and `/data/db` folders. Back up these folders regularly.
 
 
-## 🐞 Known Issues
+## Troubleshooting Tips
 
 - Some scanners (e.g. ARP) may not detect devices on different subnets. See the [Remote networks guide](https://docs.netalertx.com/REMOTE_NETWORKS) for workarounds.
 - Wi-Fi-only networks may require alternate scanners for accurate detection.
 - Notification throttling may be needed for large networks to prevent spam.
 - On some systems, elevated permissions (like `CAP_NET_RAW`) may be needed for low-level scanning.
 
-Check the [GitHub Issues](https://github.com/jokob-sk/NetAlertX/issues) for the latest bug reports and solutions and consult [the official documentation](https://docs.netalertx.com/).
+Check the [GitHub Issues](https://github.com/netalertx/NetAlertX/issues) for the latest bug reports and solutions and consult [the official documentation](https://docs.netalertx.com/).
 
-## 📃 Everything else
+## Everything else
 <!--- --------------------------------------------------------------------- --->
 
+<a href="https://trendshift.io/repositories/12670" target="_blank"><img src="https://trendshift.io/api/badge/repositories/12670" alt="jokob-sk%2FNetAlertX | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+
 ### 📧 Get notified what's new
 
 Get notified about a new release, what new functionality you can use and about breaking changes.
@@ -169,10 +167,10 @@ Get notified about a new release, what new functionality you can use and about b
 
 ### 🔀 Other Alternative Apps
 
-- [PiAlert by leiweibau](https://github.com/leiweibau/Pi.Alert/) (maintained, bare-metal install)
-- [WatchYourLAN](https://github.com/aceberg/WatchYourLAN) - Lightweight network IP scanner with web GUI (Open source)
 - [Fing](https://www.fing.com/) - Network scanner app for your Internet security (Commercial, Phone App, Proprietary hardware)
 - [NetBox](https://netboxlabs.com/) - Network management software (Commercial)
+- [Zabbix](https://www.zabbix.com/) or [Nagios](https://www.nagios.org/) - Strong focus on infrastructure monitoring.
+- [NetAlertX](https://netalertx.com) - The streamlined, discovery-focused alternative for real-time asset intelligence.
 
 ### 💙 Donations
 
@@ -183,9 +181,8 @@ Thank you to everyone who appreciates this tool and donates.
 
   <hr>
 
-  | [![GitHub](https://i.imgur.com/emsRCPh.png)](https://github.com/sponsors/jokob-sk) | [![Buy Me A Coffee](https://i.imgur.com/pIM6YXL.png)](https://www.buymeacoffee.com/jokobsk) | [![Patreon](https://i.imgur.com/MuYsrq1.png)](https://www.patreon.com/user?u=84385063) |
-| --- | --- | --- |
-
+  | [![GitHub](https://i.imgur.com/emsRCPh.png)](https://github.com/sponsors/jokob-sk) | [![Buy Me A Coffee](https://i.imgur.com/pIM6YXL.png)](https://www.buymeacoffee.com/jokobsk) |
+  | --- | --- |
   - Bitcoin: `1N8tupjeCK12qRVU2XrV17WvKK7LCawyZM`
   - Ethereum: `0x6e2749Cb42F4411bc98501406BdcD82244e3f9C7`
 
@@ -197,7 +194,7 @@ Thank you to everyone who appreciates this tool and donates.
 
 This project would be nothing without the amazing work of the community, with special thanks to:
 
-> [pucherot/Pi.Alert](https://github.com/pucherot/Pi.Alert) (the original creator of PiAlert), [leiweibau](https://github.com/leiweibau/Pi.Alert): Dark mode (and much more), [Macleykun](https://github.com/Macleykun) (Help with Dockerfile clean-up), [vladaurosh](https://github.com/vladaurosh) for Alpine re-base help, [Final-Hawk](https://github.com/Final-Hawk) (Help with NTFY, styling and other fixes), [TeroRERO](https://github.com/terorero) (Spanish translations), [Data-Monkey](https://github.com/Data-Monkey), (Split-up of the python.py file and more), [cvc90](https://github.com/cvc90) (Spanish translation and various UI work) to name a few. Check out all the [amazing contributors](https://github.com/jokob-sk/NetAlertX/graphs/contributors).
+> [pucherot/Pi.Alert](https://github.com/pucherot/Pi.Alert) (the original creator of PiAlert), [leiweibau](https://github.com/leiweibau/Pi.Alert): Dark mode (and much more), [Macleykun](https://github.com/Macleykun) (Help with Dockerfile clean-up), [vladaurosh](https://github.com/vladaurosh) for Alpine re-base help, [Final-Hawk](https://github.com/Final-Hawk) (Help with NTFY, styling and other fixes), [TeroRERO](https://github.com/terorero) (Spanish translations), [Data-Monkey](https://github.com/Data-Monkey), (Split-up of the python.py file and more), [cvc90](https://github.com/cvc90) (Spanish translation and various UI work) to name a few. Check out all the [amazing contributors](https://github.com/netalertx/NetAlertX/graphs/contributors).
 
 ### 🌍 Translations
 
@@ -223,7 +220,7 @@ Proudly using [Weblate](https://hosted.weblate.org/projects/pialert/). Help out
 [sync_hub]:                 ./docs/img/sync_hub.png                       "Screen 8"
 [notification_center]:      ./docs/img/notification_center.png            "Screen 8"
 [sent_reports_text]:        ./docs/img/sent_reports_text.png              "Screen 8"
-[device_nmap]:              ./docs/img/device_nmap.png                    "Screen 9"
+[device_nmap]:              ./docs/img/device_tools.png                    "Screen 9"
 [report1]:                  ./docs/img/report_sample.png                  "Report sample 1"
 [main_dark]:                /docs/img/1_devices_dark.jpg                  "Main screen dark"
 [maintain_dark]:            /docs/img/5_maintain.jpg                      "Maintain screen dark"

back/app.conf

@@ -16,7 +16,7 @@
 #
 # Scan multiple interfaces (eth1 and eth0):
 # SCAN_SUBNETS    = [ '192.168.1.0/24 --interface=eth1', '192.168.1.0/24 --interface=eth0' ]
-
+BACKEND_API_URL='/server'
 DISCOVER_PLUGINS=True
 SCAN_SUBNETS=['--localnet']
 TIMEZONE='Europe/Berlin'
@@ -100,6 +100,8 @@ MQTT_PASSWORD='passw0rd'
 MQTT_QOS=0
 MQTT_DELAY_SEC=2
 
+GRAPHQL_PORT=20212
+
 
 #-------------------IMPORTANT INFO-------------------#
 #   This file is ingested by a python script, so if  #

back/device_heuristics_rules.json

@@ -5,7 +5,64 @@
     "matching_pattern": [
       { "mac_prefix": "INTERNET", "vendor": "" }
     ],
-    "name_pattern": []
+    "name_pattern": [],
+    "ip_pattern": [
+      "^192\\.168\\.1\\.1$",
+      "^192\\.168\\.0\\.1$",
+      "^10\\.0\\.0\\.1$"
+    ]
+  },
+  {
+    "dev_type": "Smart Switch",
+    "icon_html": "<i class=\"fa-solid fa-toggle-on\"></i>",
+    "matching_pattern": [
+      { "mac_prefix": "003192", "vendor": "TP-Link" },
+      { "mac_prefix": "50C7BF", "vendor": "TP-Link" },
+      { "mac_prefix": "B04E26", "vendor": "TP-Link" }
+    ],
+    "name_pattern": ["hs200", "hs210", "hs220", "ks230", "smart switch", "light switch", "wall switch"]
+  },
+  {
+    "dev_type": "Smart Plug",
+    "icon_html": "<i class=\"fa-solid fa-plug\"></i>",
+    "matching_pattern": [
+      { "mac_prefix": "2887BA", "vendor": "TP-Link" }
+    ],
+    "name_pattern": ["kp115", "hs100", "hs103", "hs105", "smart plug", "outlet", "plug"]
+  },
+  {
+    "dev_type": "Smart Speaker",
+    "icon_html": "<i class=\"fa fa-volume-up\"></i>",
+    "matching_pattern": [
+      { "mac_prefix": "14C14E", "vendor": "Google" },
+      { "mac_prefix": "44650D", "vendor": "Amazon" },
+      { "mac_prefix": "74ACB9", "vendor": "Google" }
+    ],
+    "name_pattern": ["echo", "alexa", "dot", "nest-audio", "nest-mini", "google-home"]
+  },
+  {
+    "dev_type": "Smart Appliance",
+    "icon_html": "<i class=\"fa-solid fa-wind\"></i>",
+    "matching_pattern": [
+      { "mac_prefix": "446FF8", "vendor": "Dyson" }
+    ],
+    "name_pattern": ["dyson", "purifier", "humidifier", "fan"]
+  },
+  {
+    "dev_type": "Smart Home",
+    "icon_html": "<i class=\"fa fa-house\"></i>",
+    "matching_pattern": [],
+    "name_pattern": ["google", "chromecast", "nest", "hub"]
+  },
+  {
+    "dev_type": "Phone",
+    "icon_html": "<i class=\"fa-solid fa-mobile\"></i>",
+    "matching_pattern": [
+      { "mac_prefix": "001A79", "vendor": "Apple" },
+      { "mac_prefix": "B0BE83", "vendor": "Samsung" },
+      { "mac_prefix": "BC926B", "vendor": "Motorola" }
+    ],
+    "name_pattern": ["iphone", "ipad", "pixel", "galaxy", "redmi", "android", "samsung"]
   },
   {
     "dev_type": "Access Point",
@@ -16,24 +73,7 @@
       { "mac_prefix": "F4F5D8", "vendor": "TP-Link" },
       { "mac_prefix": "F88E85", "vendor": "Netgear" }
     ],
-    "name_pattern": ["router", "gateway", "ap", "access point", "access-point", "switch"]
-  },
-  {
-    "dev_type": "Phone",
-    "icon_html": "<i class=\"fa-brands fa-apple\"></i>",
-    "matching_pattern": [
-      { "mac_prefix": "001A79", "vendor": "Apple" },
-      { "mac_prefix": "B0BE83", "vendor": "Samsung" },
-      { "mac_prefix": "BC926B", "vendor": "Motorola" }
-    ],
-    "name_pattern": ["iphone", "ipad", "pixel", "galaxy", "redmi"]
-  },
-  {
-    "dev_type": "Phone",
-    "icon_html": "<i class=\"fa-solid fa-mobile\"></i>",
-    "matching_pattern": [
-    ],
-    "name_pattern": ["android","samsung"]
+    "name_pattern": ["router", "gateway", "ap", "access point", "access-point", "switch", "sg105", "sg108", "managed switch", "unmanaged switch", "poe switch", "ethernet switch"]
   },
   {
     "dev_type": "Tablet",
@@ -43,25 +83,19 @@
       { "mac_prefix": "BC4C4C", "vendor": "Samsung" }
     ],
     "name_pattern": ["tablet", "pad"]
-  },  
-  {
-    "dev_type": "IoT",
-    "icon_html": "<i class=\"fa-brands fa-raspberry-pi\"></i>",
-    "matching_pattern": [
-      { "mac_prefix": "B827EB", "vendor": "Raspberry Pi" },
-      { "mac_prefix": "DCA632", "vendor": "Raspberry Pi" }
-    ],
-    "name_pattern": ["raspberry", "pi"]
   },
   {
     "dev_type": "IoT",
     "icon_html": "<i class=\"fa-solid fa-microchip\"></i>",
     "matching_pattern": [
+      { "mac_prefix": "B827EB", "vendor": "Raspberry Pi" },
+      { "mac_prefix": "DCA632", "vendor": "Raspberry Pi" },
       { "mac_prefix": "840D8E", "vendor": "Espressif" },
       { "mac_prefix": "ECFABC", "vendor": "Espressif" },
-      { "mac_prefix": "7C9EBD", "vendor": "Espressif" }
+      { "mac_prefix": "7C9EBD", "vendor": "Espressif" },
+      { "mac_prefix": "286DCD", "vendor": "Beijing Winner Microelectronics" }
     ],
-    "name_pattern": ["raspberry", "pi"]
+    "name_pattern": ["raspberry", "pi", "thingsturn", "w600", "w601"]
   },
   {
     "dev_type": "Desktop",
@@ -69,9 +103,11 @@
     "matching_pattern": [
       { "mac_prefix": "001422", "vendor": "Dell" },
       { "mac_prefix": "001874", "vendor": "Lenovo" },
-      { "mac_prefix": "00E04C", "vendor": "Hewlett Packard" }
+      { "mac_prefix": "00E04C", "vendor": "Hewlett Packard" },
+      { "mac_prefix": "F44D30", "vendor": "Elitegroup Computer Systems" },
+      { "mac_prefix": "1C697A", "vendor": "Elitegroup Computer Systems" }
     ],
-    "name_pattern": ["desktop", "pc", "computer"]
+    "name_pattern": ["desktop", "pc", "computer", "liva", "ecs"]
   },
   {
     "dev_type": "Laptop",
@@ -80,9 +116,10 @@
       { "mac_prefix": "3C0754", "vendor": "HP" },
       { "mac_prefix": "0017A4", "vendor": "Dell" },
       { "mac_prefix": "F4CE46", "vendor": "Lenovo" },
-      { "mac_prefix": "409F38", "vendor": "Acer" }
+      { "mac_prefix": "409F38", "vendor": "Acer" },
+      { "mac_prefix": "9CB6D0", "vendor": "Rivet Networks" }
     ],
-    "name_pattern": ["macbook", "imac", "laptop", "notebook"]
+    "name_pattern": ["macbook", "imac", "laptop", "notebook", "alienware", "razer", "msi"]
   },
   {
     "dev_type": "Server",
@@ -123,9 +160,10 @@
     "matching_pattern": [
       { "mac_prefix": "001FA7", "vendor": "Sony" },
       { "mac_prefix": "7C04D0", "vendor": "Nintendo" },
-      { "mac_prefix": "EC26CA", "vendor": "Sony" }
+      { "mac_prefix": "EC26CA", "vendor": "Sony" },
+      { "mac_prefix": "48B02D", "vendor": "NVIDIA" }
     ],
-    "name_pattern": ["playstation", "xbox"]
+    "name_pattern": ["playstation", "xbox", "shield", "nvidia"]
   },
   {
     "dev_type": "Camera",
@@ -138,15 +176,6 @@
     ],
     "name_pattern": ["camera", "cam", "webcam"]
   },
-  {
-    "dev_type": "Smart Speaker",
-    "icon_html": "<i class=\"fa fa-volume-up\"></i>",
-    "matching_pattern": [
-      { "mac_prefix": "44650D", "vendor": "Amazon" },
-      { "mac_prefix": "74ACB9", "vendor": "Google" }
-    ],
-    "name_pattern": ["echo", "alexa", "dot"]
-  },
   {
     "dev_type": "Router",
     "icon_html": "<i class=\"fa fa-random\"></i>",
@@ -154,23 +183,13 @@
       { "mac_prefix": "000C29", "vendor": "Cisco" },
       { "mac_prefix": "00155D", "vendor": "MikroTik" }
     ],
-    "name_pattern": ["router", "gateway", "ap", "access point", "access-point"],
-    "ip_pattern": [
-      "^192\\.168\\.[0-1]\\.1$",
-      "^10\\.0\\.0\\.1$"
-    ]
+    "name_pattern": ["router", "gateway", "ap", "access point"]
   },
   {
     "dev_type": "Smart Light",
     "icon_html": "<i class=\"fa fa-lightbulb\"></i>",
     "matching_pattern": [],
-    "name_pattern": ["hue", "lifx", "bulb"]
-  },
-  {
-    "dev_type": "Smart Home",
-    "icon_html": "<i class=\"fa fa-house\"></i>",
-    "matching_pattern": [],
-    "name_pattern": ["google", "chromecast", "nest"]
+    "name_pattern": ["hue", "lifx", "bulb", "light"]
   },
   {
     "dev_type": "Smartwatch",
@@ -187,14 +206,9 @@
   {
     "dev_type": "Security Device",
     "icon_html": "<i class=\"fa fa-shield-alt\"></i>",
-    "matching_pattern": [],
-    "name_pattern": ["doorbell", "lock", "security"]
-  },
-  {
-    "dev_type": "Smart Light",
-    "icon_html": "<i class=\"fa-solid fa-lightbulb\"></i>",
     "matching_pattern": [
+      { "mac_prefix": "047BCB", "vendor": "Universal Global Scientific" }
     ],
-    "name_pattern": ["light","bulb"]
+    "name_pattern": ["doorbell", "lock", "security", "mmd-", "ring"]
   }
-]
+]

docs/ADVISORY_EYES_ON_GLASS.md

@@ -0,0 +1,56 @@
+### Build an MSP Wallboard for Network Monitoring
+
+For Managed Service Providers (MSPs) and Network Operations Centers (NOC), "Eyes on Glass" monitoring requires a UI that is both self-healing (auto-refreshing) and focused only on critical data. By leveraging the **UI Settings Plugin**, you can transform NetAlertX from a management tool into a dedicated live monitor.
+
+![filters](./img/ADVISORIES/filters.png)
+
+---
+
+### 1. Configure Auto-Refresh for Live Monitoring
+
+Static dashboards are the enemy of real-time response. NetAlertX allows you to force the UI to pull fresh data without manual page reloads.
+
+* **Setting:** Locate the `UI_REFRESH` (or similar "Auto-refresh UI") setting within the **UI Settings plugin**.
+* **Optimal Interval:** Set this between **60 to 120 seconds**.
+* *Note:* Refreshing too frequently (e.g., <30s) on large networks can lead to high browser and server CPU usage.
+
+![ui_customization_settings](./img/ADVISORIES/ui_customization_settings.png)
+
+### 2. Streamlining the Dashboard (MSP Mode)
+
+An MSP's focus is on what is *broken*, not what is working. Hide the noise to increase reaction speed.
+
+* **Hide Unnecessary Blocks:** Under UI Settings, disable dashboard blocks that don't provide immediate utility, such as **Online presence** or **Tiles**.
+* **Hide virtual connections:** You can specify which relationships shoudl be hidden from the main view to remove any virtual devices that are not essential from your views.
+* **Browser Full-Screen:** Use the built-in "Full Screen" toggle in the top bar to remove browser chrome (URL bars/tabs) for a cleaner "Wallboard" look.
+
+### 3. Creating Custom NOC Views
+
+Use the UI Filters in tandem with UI Settings to create custom views.
+
+![NetAlertX NOC dashboard showing offline network devices for MSP monitoring](./img/ADVISORIES/down_devices.png)
+
+| Feature | NOC/MSP Application |
+| --- | --- |
+| **Site-Specific Nodes** | Filter the view by a specific "Sync Node" or "Location" filter to monitor a single client site. |
+| **Filter by Criticality** | Filter devices where `Group == "Infrastructure"` or `"Server"`. (depending on your predefined values) |
+| **Predefined "Down" View** | Bookmark the URL with the `/devices.php#down` path to ensure the dashboard always loads into an "Alert Only" mode. |
+
+### 4. Browser & Cache Stability
+
+Because the UI is a web application, long-running sessions can occasionally experience cache drift.
+
+* **Cache Refresh:** If you notice the "Show # Entries" resetting or icons failing to load after days of uptime, use the **Reload** icon in the application header (not the browser refresh) to clear the internal app cache.
+* **Dedicated Hardware:** For 24/7 monitoring, use a dedicated thin client or Raspberry Pi running in "Kiosk Mode" to prevent OS-level popups from obscuring the dashboard.
+
+> [!TIP]
+> [NetAlertX - Detailed Dashboard Guide](https://www.youtube.com/watch?v=umh1c_40HW8)
+> This video provides a visual walkthrough of the NetAlertX dashboard features, including how to map and visualize devices which is crucial for setting up a clear "Eyes on Glass" monitoring environment.
+
+### Summary Checklist
+
+* [ ] **Automate Refresh:** Set `UI_REFRESH` to **60-120s** in UI Settings to ensure the dashboard stays current without manual intervention.
+* [ ] **Filter for Criticality:** Bookmark the **`/devices.php#down`** view to instantly focus on offline assets rather than the entire inventory.
+* [ ] **Remove UI Noise:** Use UI Settings to hide non-essential dashboard blocks (e.g., **Tiles** or remove **Virtual Connections** devices) to maximize screen real estate for alerts.
+* [ ] **Segment by Site:** Use **Location** or **Sync Node** filters to create dedicated views for specific client networks or physical branches.
+* [ ] **Ensure Stability:** Run on a dedicated "Kiosk" browser and use the internal **Reload icon** occasionally to maintain a clean application cache.

docs/ADVISORY_MULTI_NETWORK.md

@@ -0,0 +1,121 @@
+## ADVISORY: Best Practices for Monitoring Multiple Networks with NetAlertX
+
+### 1. Define Monitoring Scope & Architecture
+
+Effective multi-network monitoring starts with understanding how NetAlertX "sees" your traffic.
+
+* **A. Understand Network Accessibility:** Local ARP-based scanning (**ARPSCAN**) only discovers devices on directly accessible subnets due to Layer 2 limitations. It cannot traverse VPNs or routed borders without specific configuration.
+* **B. Plan Subnet & Scan Interfaces:** Explicitly configure each accessible segment in `SCAN_SUBNETS` with the corresponding interfaces.
+* **C. Remote & Inaccessible Networks:** For networks unreachable via ARP, use these strategies:
+* **Alternate Plugins:** Supplement discovery with [SNMPDSC](SNMPDSC) or [DHCP lease imports](https://docs.netalertx.com/PLUGINS/?h=DHCPLSS#available-plugins).
+* **Centralized Multi-Tenant Management using Sync Nodes:** Run secondary NetAlertX instances on isolated networks and aggregate data using the **SYNC plugin**.
+* **Manual Entry:** For static assets where only ICMP (ping) status is needed.
+
+> [!TIP]
+> Explore the [remote networks](./REMOTE_NETWORKS.md) documentation for more details on how to set up the approaches menationed above.
+
+---
+
+### 2. Automating IT Asset Inventory with Workflows
+
+[Workflows](./WORKFLOWS.md) are the "engine" of NetAlertX, reducing manual overhead as your device list grows.
+
+* **A. Logical Ownership & VLAN Tagging:** Create a workflow triggered on **Device Creation** to:
+1. Inspect the IP/Subnet.
+2. Set `devVlan` or `devOwner` custom fields automatically.
+
+
+* **B. Auto-Grouping:** Use conditional logic to categorize devices.
+* *Example:* If `devLastIP == 10.10.20.*`, then `Set devLocation = "BranchOffice"`.
+
+```json
+{
+  "name": "Assign Location - BranchOffice",
+  "trigger": {
+    "object_type": "Devices",
+    "event_type": "update"
+  },
+  "conditions": [
+    {
+      "logic": "AND",
+      "conditions": [
+        {
+          "field": "devLastIP",
+          "operator": "contains",
+          "value": "10.10.20."
+        }
+      ]
+    }
+  ],
+  "actions": [
+    {
+      "type": "update_field",
+      "field": "devLocation",
+      "value": "BranchOffice"
+    }
+  ]
+}
+```
+
+
+* **C. Sync Node Tracking:** When using multiple instances, ensure all synchub nodes have a descriptive `SYNC_node_name` name to distinguish between sites.
+
+> [!TIP]
+> Always test new workflows in a "Staging" instance. A misconfigured workflow can trigger thousands of unintended updates across your database.
+
+---
+
+### 3. Notification Strategy: Low Noise, High Signal
+
+A multi-network environment can generate significant "alert fatigue." Use a layered filtering approach.
+
+| Level | Strategy | Recommended Action |
+| --- | --- | --- |
+| **Device** | Silence Flapping | Use "Skip repeated notifications" for unstable IoT devices. |
+| **Plugin** | Tune Watchers | Only enable `_WATCH` on reliable plugins (e.g., ICMP/SNMP). |
+| **Global** | Filter Sections | Limit `NTFPRCS_INCLUDED_SECTIONS` to `new_devices` and `down_devices`. |
+
+
+> [!TIP]
+> **Ignore Rules:** Maintain strict **Ignored MAC** (`NEWDEV_ignored_MACs`) and **Ignored IP** (`NEWDEV_ignored_IPs`) lists for guest networks or broadcast scanners to keep your logs clean.
+
+---
+
+### 4. UI Filters for Multi-Network Clarity
+
+Don't let a massive device list overwhelm you. Use the [Multi-edit features](./DEVICES_BULK_EDITING.md) to categorize devices and create focused views:
+
+* **By Zone:** Filter by "Location", "Site" or "Sync Node" you et up in Section 2.
+* **By Criticality:** Use custom the device Type field to separate "Core Infrastructure" from "Ephemeral Clients."
+* **By Status:** Use predefined views specifically for "Devices currently Down" to act as a Network Operations Center (NOC) dashboard.
+
+> [!TIP]
+> If you are providing services as a Managed Service Provider (MSP) customize your default UI to be exactly how you need it, by hiding parts of the UI that you are not interested in, or by configuring a auto-refreshed screen monitoring your most important clients. See the [Eyes on glass](./ADVISORY_EYES_ON_GLASS.md) advisory for more details.
+
+---
+
+### 5. Operational Stability & Sync Health
+
+* **Health Checks:** Regularly monitor the [Logs](https://docs.netalertx.com/LOGGING/?h=logs) to ensure remote nodes are reporting in.
+* **Backups:** Use the **CSV Devices Backup** plugin. Standardize your workflow templates and [back up](./BACKUPS.md) you `/config` folders so that if a node fails, you can redeploy it with the same logic instantly.
+
+
+### 6. Optimize Performance
+
+As your environment grows, tuning the underlying engine is vital to maintain a snappy UI and reliable discovery cycles.
+
+* **Plugin Scheduling:** Avoid "Scan Storms" by staggering plugin execution. Running intensive tasks like `NMAP` or `MASS_DNS` simultaneously can spike CPU and cause database locks.
+* **Database Health:** Large-scale monitoring generates massive event logs. Use the **[DBCLNP (Database Cleanup)](https://www.google.com/search?q=https://docs.netalertx.com/PLUGINS/%23dbclnp)** plugin to prune old records and keep the SQLite database performant.
+* **Resource Management:** For high-device counts, consider increasing the memory limit for the container and utilizing `tmpfs` for temporary files to reduce SD card/disk I/O bottlenecks.
+
+> [!IMPORTANT]
+> For a deep dive into hardware requirements, database vacuuming, and specific environment variables for high-load instances, refer to the full **[Performance Optimization Guide](https://docs.netalertx.com/PERFORMANCE/)**.
+
+---
+
+### Summary Checklist
+
+* [ ] **Discovery:** Are all subnets explicitly defined?
+* [ ] **Automation:** Do new devices get auto-assigned to a VLAN/Owner?
+* [ ] **Noise Control:** Are transient "Down" alerts delayed via `NTFPRCS_alert_down_time`?
+* [ ] **Remote Sites:** Is the SYNC plugin authenticated and heartbeat-active?

docs/API.md

@@ -23,6 +23,8 @@ curl 'http://host:GRAPHQL_PORT/graphql' \
 
 The API server runs on `0.0.0.0:<graphql_port>` with **CORS enabled** for all main endpoints.
 
+CORS configuration: You can limit allowed CORS origins with the `CORS_ORIGINS` environment variable. Set it to a comma-separated list of origins (for example: `CORS_ORIGINS="https://example.com,http://localhost:3000"`). The server parses this list at startup and only allows origins that begin with `http://` or `https://`. If `CORS_ORIGINS` is unset or parses to an empty list, the API falls back to a safe development default list (localhosts) and will include `*` as a last-resort permissive origin.
+
 ---
 
 ## Authentication
@@ -57,6 +59,10 @@ http://<server>:<GRAPHQL_PORT>/
 
 ## Endpoints
 
+> [!NOTE]
+> You can explore the API endpoints by using the interactive API docs at `http://<server>:<GRAPHQL_PORT>/docs`.
+> ![API docs](./img/API/API_docs.png)
+
 > [!TIP]
 > When retrieving devices or settings try using the GraphQL API endpoint first as it is read-optimized.
 
@@ -76,6 +82,7 @@ http://<server>:<GRAPHQL_PORT>/
 * [Sync](API_SYNC.md) – Synchronization between multiple NetAlertX instances
 * [Logs](API_LOGS.md) – Purging of logs and adding to the event execution queue for user triggered events
 * [DB query](API_DBQUERY.md) (⚠ Internal) - Low level database access - use other endpoints if possible
+* `/server` (⚠ Internal) - Backend server endpoint for internal communication only - **do not use directly**
 
 ### MCP Server Bridge
 

docs/API_DEVICE_FIELD_LOCK.md

@@ -0,0 +1,157 @@
+# 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:
+
+- `devName` - Device name/hostname
+- `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)
+
+
+### 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
+
+## See Also
+
+- [Device locking](./DEVICE_FIELD_LOCK.md)
+- [Device source fields](./DEVICE_SOURCE_FIELDS.md)
+- [API Device Endpoints Documentation](./API_DEVICE.md)
+- [Authoritative Field Updates System](./PLUGINS_DEV.md#authoritative-fields)
+- [Plugin Configuration Reference](./PLUGINS_DEV_CONFIG.md)

docs/API_MCP.md

@@ -31,11 +31,6 @@ graph TB
     D -->|Response Data| C
     C -->|JSON Response| B
     B -->|Stream Events| A
-
-    style A fill:#e1f5fe
-    style B fill:#f3e5f5
-    style C fill:#fff3e0
-    style D fill:#e8f5e8
 ```
 
 ### MCP Tool Integration
@@ -54,7 +49,7 @@ sequenceDiagram
     API-->>MCP: 5. Available tools spec
     MCP-->>AI: 6. Tool definitions
     AI->>MCP: 7. tools/call: search_devices
-    MCP->>API: 8. POST /mcp/sse/devices/search
+    MCP->>API: 8. POST /devices/search
     API->>DB: 9. Query devices
     DB-->>API: 10. Device data
     API-->>MCP: 11. JSON response
@@ -77,9 +72,9 @@ graph LR
     end
 
     subgraph "NetAlertX API Server (:20211)"
-        F[Device APIs<br/>/mcp/sse/devices/*]
-        G[Network Tools<br/>/mcp/sse/nettools/*]
-        H[Events API<br/>/mcp/sse/events/*]
+        F[Device APIs<br/>/devices/*]
+        G[Network Tools<br/>/nettools/*]
+        H[Events API<br/>/events/*]
     end
 
     subgraph "Backend"
@@ -98,15 +93,6 @@ graph LR
     F --> I
     G --> J
     H --> I
-
-    style A fill:#e1f5fe
-    style B fill:#e1f5fe
-    style C fill:#f3e5f5
-    style D fill:#f3e5f5
-    style E fill:#f3e5f5
-    style F fill:#fff3e0
-    style G fill:#fff3e0
-    style H fill:#fff3e0
 ```
 
 ---
@@ -196,27 +182,28 @@ eventSource.onmessage = function(event) {
 
 | Tool | Endpoint | Description |
 |------|----------|-------------|
-| `list_devices` | `/mcp/sse/devices/by-status` | List devices by online status |
-| `get_device_info` | `/mcp/sse/device/<mac>` | Get detailed device information |
-| `search_devices` | `/mcp/sse/devices/search` | Search devices by MAC, name, or IP |
-| `get_latest_device` | `/mcp/sse/devices/latest` | Get most recently connected device |
-| `set_device_alias` | `/mcp/sse/device/<mac>/set-alias` | Set device friendly name |
+| `list_devices` | `/devices/by-status` | List devices by online status |
+| `get_device_info` | `/device/{mac}` | Get detailed device information |
+| `search_devices` | `/devices/search` | Search devices by MAC, name, or IP |
+| `get_latest_device` | `/devices/latest` | Get most recently connected device |
+| `set_device_alias` | `/device/{mac}/set-alias` | Set device friendly name |
 
 ### Network Tools
 
 | Tool | Endpoint | Description |
 |------|----------|-------------|
-| `trigger_scan` | `/mcp/sse/nettools/trigger-scan` | Trigger network discovery scan |
-| `get_open_ports` | `/mcp/sse/device/open_ports` | Get stored NMAP open ports for device |
-| `wol_wake_device` | `/mcp/sse/nettools/wakeonlan` | Wake device using Wake-on-LAN |
-| `get_network_topology` | `/mcp/sse/devices/network/topology` | Get network topology map |
+| `trigger_scan` | `/nettools/trigger-scan` | Trigger network discovery scan to find new devices. |
+| `run_nmap_scan` | `/nettools/nmap` | Perform NMAP scan on a target to identify open ports. |
+| `get_open_ports` | `/device/open_ports` | Get stored NMAP open ports. Use `run_nmap_scan` first if empty. |
+| `wol_wake_device` | `/nettools/wakeonlan` | Wake device using Wake-on-LAN |
+| `get_network_topology` | `/devices/network/topology` | Get network topology map |
 
 ### Event & Monitoring Tools
 
 | Tool | Endpoint | Description |
 |------|----------|-------------|
-| `get_recent_alerts` | `/mcp/sse/events/recent` | Get events from last 24 hours |
-| `get_last_events` | `/mcp/sse/events/last` | Get 10 most recent events |
+| `get_recent_alerts` | `/events/recent` | Get events from last 24 hours |
+| `get_last_events` | `/events/last` | Get 10 most recent events |
 
 ---
 

docs/BACKUPS.md

@@ -2,7 +2,7 @@
 
 > [!NOTE]
 > To back up 99% of your configuration, back up at least the `/data/config` folder.
-> Database definitions can change between releases, so the safest method is to restore backups using the **same app version** they were taken from, then upgrade incrementally.
+> Database definitions can change between releases, so the safest method is to restore backups using the **same app version** they were taken from, then upgrade incrementally by following the [Migration documentation](./MIGRATION.md).
 
 ---
 

docs/COMMON_ISSUES.md

@@ -120,3 +120,23 @@ With `ARPSCAN` scans some devices might flip IP addresses after each scan trigge
 See how to prevent IP flipping in the [ARPSCAN plugin guide](/front/plugins/arp_scan/README.md).
 
 Alternatively adjust your [notification settings](./NOTIFICATIONS.md) to prevent false positives by filtering out events or devices.
+
+#### Multiple NICs on Same Host Reporting Same IP
+
+On systems with multiple NICs (like a Proxmox server), each NIC has its own MAC address. Sometimes NetAlertX can incorrectly assign the same IP to all NICs, causing false device mappings. This is due to the way ARP responses are handled by the OS and cannot be overridden directly in NetAlertX.
+
+**Resolution (Linux-based systems, e.g., Proxmox):**
+
+Run the following commands on the host to fix ARP behavior:
+
+```bash
+sudo sysctl -w net.ipv4.conf.all.arp_ignore=1
+sudo sysctl -w net.ipv4.conf.all.arp_announce=2
+```
+
+This ensures each NIC responds correctly to ARP requests and prevents NetAlertX from misassigning IPs.
+
+> For setups with multiple interfaces on the same switch, consider [workflows](./WORKFLOWS.md), [device exclusions](./NOTIFICATIONS.md), or [dummy devices](./DEVICE_MANAGEMENT.md) as additional workarounds.
+> See [Feature Requests](https://github.com/netalertx/netalertx/issues) for reporting edge cases.
+
+

docs/DEBUG_API_SERVER.md

@@ -38,6 +38,19 @@ All application settings can also be initialized via the `APP_CONF_OVERRIDE` doc
 
 There are several ways to check if the GraphQL server is running.
 
+## Flask debug mode (environment)
+
+You can control whether the Flask development debugger is enabled by setting the environment variable `FLASK_DEBUG` (default: `False`). Enabling debug mode will turn on the interactive debugger which may expose a remote code execution (RCE) vector if the server is reachable; **only enable this for local development** and never in production. Valid truthy values are: `1`, `true`, `yes`, `on` (case-insensitive).
+
+In the running container you can set this variable via Docker Compose or your environment, for example:
+
+```yaml
+environment:
+  - FLASK_DEBUG=1
+```
+
+When enabled, the GraphQL server startup logs will indicate the debug setting.
+
 ### Init Check
 
 You can navigate to System Info -> Init Check to see if `isGraphQLServerRunning` is ticked:

docs/DEBUG_PLUGINS.md

@@ -1,7 +1,7 @@
 # Troubleshooting plugins
 
 > [!TIP]
-> Before troubleshooting, please ensure you have the right [Debugging and LOG_LEVEL set](./DEBUG_TIPS.md).
+> Before troubleshooting, please ensure you have the right [Debugging and LOG_LEVEL set](./DEBUG_TIPS.md) in Settings.
 
 ## High-level overview
 
@@ -22,10 +22,25 @@ For a more in-depth overview on how plugins work check the [Plugins development
 
 #### Incorrect input data
 
-Input data from the plugin might cause mapping issues in specific edge cases. Look for a corresponding section in the `app.log` file, for example notice the first line of the execution run of the `PIHOLE` plugin below:
+Input data from the plugin might cause mapping issues in specific edge cases. Look for a corresponding section in the `app.log` file, and search for `[Scheduler] run for PLUGINNAME: YES`, so for ICMP you would look for `[Scheduler] run for ICMP: YES`. You can find examples of useful logs below. If your issue is related to a plugin, and you don't include a log section with this data, we can't help you to resolve your issue.
+
+##### ICMP log example
 
 ```
-17:31:05 [Scheduler] - Scheduler run for PIHOLE: YES
+20:39:04 [Scheduler] run for ICMP: YES
+20:39:04 [ICMP] fping skipping 192.168.1.124 : [2], timed out (NaN avg, 100% loss)
+20:39:04 [ICMP] adding 192.168.1.123 from 192.168.1.123 : [2], 64 bytes, 20.1 ms (8.22 avg, 0% loss)
+20:39:04 [ICMP] fping skipping 192.168.1.157 : [1], timed out (NaN avg, 100% loss)
+20:39:04 [ICMP] adding 192.168.1.79 from 192.168.1.79  : [2], 64 bytes, 48.3 ms (60.9 avg, 0% loss)
+20:39:04 [ICMP] fping skipping 192.168.1.128 : [2], timed out (NaN avg, 100% loss)
+20:39:04 [ICMP] fping skipping 192.168.1.129 : [2], timed out (NaN avg, 100% loss)
+```
+
+
+##### PIHOLE log example
+
+```
+17:31:05 [Scheduler] run for PIHOLE: YES
 17:31:05 [Plugin utils] ---------------------------------------------
 17:31:05 [Plugin utils] display_name: PiHole (Device sync)
 17:31:05 [Plugins] CMD: SELECT n.hwaddr AS Object_PrimaryID, {s-quote}null{s-quote} AS Object_SecondaryID, datetime() AS DateTime, na.ip  AS Watched_Value1, n.lastQuery AS Watched_Value2, na.name AS Watched_Value3, n.macVendor AS Watched_Value4, {s-quote}null{s-quote} AS Extra, n.hwaddr AS ForeignKey FROM EXTERNAL_PIHOLE.Network AS n LEFT JOIN EXTERNAL_PIHOLE.Network_Addresses AS na ON na.network_id = n.id WHERE n.hwaddr NOT LIKE {s-quote}ip-%{s-quote} AND n.hwaddr is not {s-quote}00:00:00:00:00:00{s-quote}  AND na.ip is not null
@@ -54,13 +69,13 @@ Input data from the plugin might cause mapping issues in specific edge cases. Lo
 17:31:05 [Plugin utils] In pluginObjects there are 2 events with the status "missing-in-last-scan"
 17:31:05 [Plugin utils] In pluginObjects there are 2 events with the status "watched-not-changed"
 17:31:05 [Plugins] Mapping objects to database table: CurrentScan
-17:31:05 [Plugins] SQL query for mapping: INSERT into CurrentScan ( "cur_MAC", "cur_IP", "cur_LastQuery", "cur_Name", "cur_Vendor", "cur_ScanMethod") VALUES ( ?, ?, ?, ?, ?, ?)
+17:31:05 [Plugins] SQL query for mapping: INSERT into CurrentScan ( "scanMac", "scanLastIP", "scanLastQuery", "scanName", "scanVendor", "scanSourcePlugin") VALUES ( ?, ?, ?, ?, ?, ?)
 17:31:05 [Plugins] SQL sqlParams for mapping: [('01:01:01:01:01:01', '172.30.0.1', 0, 'aaaa', 'vvvvvvvvv', 'PIHOLE'), ('02:42:ac:1e:00:02', '172.30.0.2', 0, 'dddd', 'vvvvv2222', 'PIHOLE')]
 🔺
 17:31:05 [API] Update API starting
 17:31:06 [API] Updating table_plugins_history.json file in /api
 ```
-
+> [!NOTE]
 > The debug output between the 🔻red arrows🔺 is important for debugging (arrows added only to highlight the section on this page, they are not available in the actual debug log)
 
 In the above output notice the section logging how many events are produced by the plugin:
@@ -80,12 +95,11 @@ These values, if formatted correctly, will also show up in the UI:
 
 ![Plugins table](./img/DEBUG_PLUGINS/plugin_objects_pihole.png)
 
-
 ### Sharing application state
 
 Sometimes specific log sections are needed to debug issues. The Devices and CurrentScan table data is sometimes needed to figure out what's wrong.
 
-1. Please set `LOG_LEVEL` to `trace` (Disable it once you have the info as this produces big log files).
+1. Please set `LOG_LEVEL` to `trace` in the Settings (Disable it once you have the info as this produces big log files).
 2. Wait for the issue to occur.
 3. Search for `================ DEVICES table content  ================` in your logs.
 4. Search for `================ CurrentScan table content  ================` in your logs.

docs/DEBUG_TIPS.md

@@ -4,7 +4,7 @@ Please follow tips 1 - 4 to get a more detailed error.
 
 ## 1. More Logging
 
-When debugging an issue always set the highest log level:
+When debugging an issue always set the highest log level in **Settings -> Core**:
 
 `LOG_LEVEL='trace'`
 
@@ -21,7 +21,7 @@ docker run \
   --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
   -e PORT=20211 \
   -e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \
-  ghcr.io/jokob-sk/netalertx:latest
+  ghcr.io/netalertx/netalertx:latest
 
 ```
 
@@ -34,7 +34,7 @@ Note: Your `/local_data_dir` should contain a `config` and `db` folder.
 
 If possible, check if your issue got fixed in the `_dev` image before opening a new issue. The container is:
 
-`ghcr.io/jokob-sk/netalertx-dev:latest`
+`ghcr.io/netalertx/netalertx-dev:latest`
 
 > ⚠ Please backup your DB and config beforehand!
 

docs/DEVICE_FIELD_LOCK.md

@@ -0,0 +1,164 @@
+# Quick Reference Guide - Device Field Lock/Unlock System
+
+## Overview
+
+![Field source and locks](./img/DEVICE_MANAGEMENT/field_sources_and_locks.png)
+
+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
+
+These are the ONLY fields that can be locked:
+
+- `devName` - Device hostname/alias
+- `devVendor` - Device manufacturer
+- `devSSID` - WiFi network name
+- `devParentMAC` - Parent/gateway MAC
+- `devParentPort` - Parent device port
+- `devParentRelType` - Relationship type (e.g., "gateway")
+- `devVlan` - VLAN identifier
+
+Additional fields that are tracked (and their source is dispalyed in the UI if available):
+
+- `devMac`
+- `devLastIP`
+- `devFQDN`
+
+## Source Values Explained
+
+Each locked field has a "source" indicator that shows you why the value is protected:
+
+| Indicator | Meaning | Can It Change? |
+|-----------|---------|---|
+| 🔒 **LOCKED** | You locked this field | No, until you unlock it |
+| ✏️ **USER** | You edited this field | No, plugins can't overwrite |
+| 📡 **NEWDEV** | Default/unset value | Yes, plugins can update |
+| 📡 **Plugin name** | Last updated by a plugin (e.g., UNIFIAPI) | Yes, plugins can update if field in SET_ALWAYS |
+
+Overwrite rules are
+
+> [!TIP]
+> You can bulk-unlock devices in the [Multi-edit](./DEVICES_BULK_EDITING.md) dialog. This removes all `USER` and `LOCKED` values from all `*Source` fields of selected devices.
+
+## Usage Examples
+
+### 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** (🔓)
+5. That field is now protected
+
+### Unlock a Field (Allow Plugin Updates)
+
+1. Go to **Device Details**
+2. Find the locked field (shows 🔓)
+3. Click the **unlock button** (🔓)
+4. The button changes back to **lock** (🔒)
+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 after unlocking
+- ✅ Lock persists across plugin runs
+- ✅ Other users can see it's locked
+
+## 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 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 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 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
+- Reload the page—the change might be a display issue
+- Check if you accidentally unlocked it
+- Open an issue if it persists
+
+## See also
+
+- [Device locking](./DEVICE_FIELD_LOCK.md)
+- [Device source fields](./DEVICE_SOURCE_FIELDS.md)
+- [API Device Endpoints Documentation](./API_DEVICE.md)
+- [Authoritative Field Updates System](./PLUGINS_DEV.md#authoritative-fields)
+- [Plugin Configuration Reference](./PLUGINS_DEV_CONFIG.md)
+- [Device locking APIs](API_DEVICE_FIELD_LOCK.md)
+- [Device management](DEVICE_MANAGEMENT.md)
+

docs/DEVICE_MANAGEMENT.md

@@ -39,12 +39,45 @@ The **MAC** field and the **Last IP** field will then become editable.
 ![Save Dummy Device](./img/DEVICE_MANAGEMENT/DeviceEdit_SaveDummyDevice.png)
 
 
-> [!NOTE]
->
-> You can couple this with the `ICMP` plugin which can be used to monitor the status of these devices, if they are actual devices reachable with the `ping` command. If not, you can use a loopback IP address so they appear online, such as `0.0.0.0` or `127.0.0.1`.
+## Dummy or Manually Created Device Status
+
+You can control a dummy device’s status either via `ICMP` (automatic) or the `Force Status` field (manual). Choose based on whether the device is real and how important **data hygiene** is.
+
+### `ICMP` (Real Devices)
+
+Use a real IP that responds to ping so status is updated automatically.
+
+### `Force Status` (Best for Data Hygiene)
+
+Manually set the status when the device is not reachable or is purely logical.
+This keeps your data clean and avoids fake IPs.
+
+### Loopback IP (`127.0.0.1`, `0.0.0.0`)
+
+Use when you want the device to always appear online via `ICMP`.
+Note this simulates reachability and introduces artificial data. This approach might be preferred, if you want to filter and distinguish dummy devices based on IP when filtering your asset lists.
+
 
 ## Copying data from an existing device.
 
 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)
+
+![Field source and locks](./img/DEVICE_MANAGEMENT/field_sources_and_locks.png)
+
+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
+
+### See Also
+
+- **For Users:** [Quick Reference - Device Field Lock/Unlock](DEVICE_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
+
 

docs/DEVICE_SOURCE_FIELDS.md

@@ -0,0 +1,67 @@
+# Understanding Device Source Fields and Field Updates
+
+When the system scans a network, it finds various details about devices (like names, IP addresses, and manufacturers). To ensure the data remains accurate without accidentally overwriting manual changes, the system uses a set of "Source Rules."
+
+![Field source and locks](./img/DEVICE_MANAGEMENT/field_sources_and_locks.png)
+
+---
+
+## The "Protection" Levels
+
+Every piece of information for a device has a **Source**. This source determines whether a new scan is allowed to change that value.
+
+| Source Status | Description | Can a Scan Overwrite it? |
+| --- | --- | --- |
+| **USER** | You manually entered this value. | **Never** |
+| **LOCKED** | This value is pinned and protected. | **Never** |
+| **NEWDEV** | This value was initialized from `NEWDEV` plugin settings. | **Always** |
+| **(Plugin Name)** | The value was found by a specific scanner (e.g., `NBTSCAN`). | **Only if specific rules are met** |
+
+---
+
+## How Scans Update Information
+
+If a field is **not** protected by a `USER` or `LOCKED` status, the system follows these rules to decide if it should update the info:
+
+### 1. The "Empty Field" Rule (Default)
+
+By default, the system is cautious. It will only fill in a piece of information if the current field is **empty** (showing as "unknown," "0.0.0.0," or blank). It won't change for example an existing name unless you tell it to.
+
+### 2. SET_ALWAYS
+
+Some plugins are configured to be "authoritative." If a field is in the **SET_ALWAYS** setting of a plugin:
+
+* The scanner will **always** overwrite the current value with the new one.
+* *Note: It will still never overwrite a `USER` or `LOCKED` field.*
+
+### 3. SET_EMPTY
+
+If a field is in the **SET_EMPTY** list:
+
+* The scanner will **only** provide a value if the current field is currently empty.
+* This is used for fields where we want to "fill in the blanks" but never change a value once it has been established by any source.
+
+### 4. Automatic Overrides (Live Tracking)
+
+Some fields, like **IP Addresses** (`devLastIP`) and **Full Domain Names** (`devFQDN`), are set to automatically update whenever they change. This ensures that if a device moves to a new IP on your network, the system reflects that change immediately without you having to do anything.
+
+---
+
+## Summary of Field Logic
+
+| If the current value is... | And the Scan finds... | Does it update? |
+| --- | --- | --- |
+| **USER / LOCKED** | Anything | **No** |
+| **Empty** | A new value | **Yes** |
+| **A "Plugin" value** | A different value | **No** (Unless `SET_ALWAYS` is on) |
+| **An IP Address** | A different IP | **Yes** (Updates automatically) |
+
+## See also:
+
+- [Device locking](./DEVICE_FIELD_LOCK.md)
+- [Device source fields](./DEVICE_SOURCE_FIELDS.md)
+- [API Device Endpoints Documentation](./API_DEVICE.md)
+- [Authoritative Field Updates System](./PLUGINS_DEV.md#authoritative-fields)
+- [Plugin Configuration Reference](./PLUGINS_DEV_CONFIG.md)
+- [Device locking APIs](API_DEVICE_FIELD_LOCK.md)
+- [Device management](DEVICE_MANAGEMENT.md)

docs/DEV_ENV_SETUP.md

@@ -8,26 +8,26 @@ Before starting development, please review the following guidelines.
 
 ### Priority Order (Highest to Lowest)
 
-1. 🔼 Fixing core bugs that lack workarounds  
-2. 🔵 Adding core functionality that unlocks other features (e.g., plugins)  
-3. 🔵 Refactoring to enable faster development  
-4. 🔽 UI improvements (PRs welcome, but low priority)  
+1. 🔼 Fixing core bugs that lack workarounds
+2. 🔵 Adding core functionality that unlocks other features (e.g., plugins)
+3. 🔵 Refactoring to enable faster development
+4. 🔽 UI improvements (PRs welcome, but low priority)
 
 ### Design Philosophy
 
-The application architecture is designed for extensibility and maintainability. It relies heavily on configuration manifests via plugins and settings to dynamically build the UI and populate the application with data from various sources.  
+The application architecture is designed for extensibility and maintainability. It relies heavily on configuration manifests via plugins and settings to dynamically build the UI and populate the application with data from various sources.
 
-For details, see:  
-- [Plugins Development](PLUGINS_DEV.md) (includes video)  
-- [Settings System](SETTINGS_SYSTEM.md)  
+For details, see:
+- [Plugins Development](PLUGINS_DEV.md) (includes video)
+- [Settings System](SETTINGS_SYSTEM.md)
 
-Focus on **core functionality** and integrate with existing tools rather than reinventing the wheel.  
+Focus on **core functionality** and integrate with existing tools rather than reinventing the wheel.
 
-Examples:  
-- Using **Apprise** for notifications instead of implementing multiple separate gateways  
-- Implementing **regex-based validation** instead of one-off validation for each setting  
+Examples:
+- Using **Apprise** for notifications instead of implementing multiple separate gateways
+- Implementing **regex-based validation** instead of one-off validation for each setting
 
-> [!NOTE]  
+> [!NOTE]
 > UI changes have lower priority. PRs are welcome, but please keep them **small and focused**.
 
 ## Development Environment Set Up
@@ -43,7 +43,7 @@ The following steps will guide you to set up your environment for local developm
 ### 1. Download the code:
 
 - `mkdir /development`
-- `cd /development && git clone https://github.com/jokob-sk/NetAlertX.git`
+- `cd /development && git clone https://github.com/netalertx/NetAlertX.git`
 
 ### 2. Create a DEV .env_dev file
 
@@ -59,13 +59,13 @@ PORT=22222    # make sure this port is unique on your whole network
 DEV_LOCATION=/development/NetAlertX
 APP_DATA_LOCATION=/volume/docker_appdata
 # Make sure your GRAPHQL_PORT setting has a port that is unique on your whole host network
-APP_CONF_OVERRIDE={"GRAPHQL_PORT":"22223"} 
+APP_CONF_OVERRIDE={"GRAPHQL_PORT":"22223"}
 # ALWAYS_FRESH_INSTALL=true # uncommenting this will always delete the content of /config and /db dirs on boot to simulate a fresh install
 ```
 
-### 3. Create /db and /config dirs 
+### 3. Create /db and /config dirs
 
-Create a folder `netalertx` in the `APP_DATA_LOCATION` (in this example in `/volume/docker_appdata`) with 2 subfolders `db` and `config`. 
+Create a folder `netalertx` in the `APP_DATA_LOCATION` (in this example in `/volume/docker_appdata`) with 2 subfolders `db` and `config`.
 
 - `mkdir /volume/docker_appdata/netalertx`
 - `mkdir /volume/docker_appdata/netalertx/db`
@@ -82,9 +82,9 @@ You can then modify the python script without restarting/rebuilding the containe
 
 ## Tips
 
-A quick cheat sheet of useful commands. 
+A quick cheat sheet of useful commands.
 
-### Removing the container and image 
+### Removing the container and image
 
 A command to stop, remove the container and the image (replace `netalertx` and `netalertx-netalertx` with the appropriate values)
 
@@ -98,23 +98,23 @@ Most code changes can be tested without rebuilding the container. When working o
 
 ![image](./img/DEV/Maintenance_Logs_Restart_server.png)
 
-2. If above doesn't work, SSH into the container and kill & restart the main script loop 
+2. If above doesn't work, SSH into the container and kill & restart the main script loop
 
 - `sudo docker exec -it netalertx /bin/bash`
 - `pkill -f "python /app/server" && python /app/server & `
 
-3. If none of the above work, restart the docker container. 
+3. If none of the above work, restart the docker container.
 
-- This is usually the last resort as sometimes the Docker engine becomes unresponsive and the whole engine needs to be restarted. 
+- This is usually the last resort as sometimes the Docker engine becomes unresponsive and the whole engine needs to be restarted.
 
 ## Contributing & Pull Requests
 
 ### Before submitting a PR, please ensure:
 
-✔ Changes are **backward-compatible** with existing installs.  
-✔ No unnecessary changes are made.  
-✔ New features are **reusable**, not narrowly scoped.  
-✔ Features are implemented via **plugins** if possible.  
+✔ Changes are **backward-compatible** with existing installs.
+✔ No unnecessary changes are made.
+✔ New features are **reusable**, not narrowly scoped.
+✔ Features are implemented via **plugins** if possible.
 
 ### Mandatory Test Cases
 
@@ -122,15 +122,15 @@ Most code changes can be tested without rebuilding the container. When working o
 - Existing DB/config compatibility.
 - Notification testing:
 
-    - Email  
-    - Apprise (e.g., Telegram)  
-    - Webhook (e.g., Discord)  
-    - MQTT (e.g., Home Assistant)  
+    - Email
+    - Apprise (e.g., Telegram)
+    - Webhook (e.g., Discord)
+    - MQTT (e.g., Home Assistant)
 
 - Updating Settings and their persistence.
 - Updating a Device
 - Plugin functionality.
 - Error log inspection.
 
-> [!NOTE]  
+> [!NOTE]
 > Always run all available tests as per the [Testing documentation](API_TESTS.md).

docs/DOCKER_COMPOSE.md

@@ -17,7 +17,7 @@ services:
   netalertx:
   #use an environmental variable to set host networking mode if needed
     container_name: netalertx                       # The name when you docker contiainer ls
-    image: ghcr.io/jokob-sk/netalertx:latest
+    image: ghcr.io/netalertx/netalertx:latest
     network_mode: ${NETALERTX_NETWORK_MODE:-host}   # Use host networking for ARP scanning and other services
 
     read_only: true                                 # Make the container filesystem read-only
@@ -27,6 +27,9 @@ services:
       - NET_ADMIN                                   # Required for ARP scanning
       - NET_RAW                                     # Required for raw socket operations
       - NET_BIND_SERVICE                            # Required to bind to privileged ports (nbtscan)
+      - CHOWN                                       # Required for root-entrypoint to chown /data + /tmp before dropping privileges
+      - SETUID                                      # Required for root-entrypoint to switch to non-root user
+      - SETGID                                      # Required for root-entrypoint to switch to non-root group
 
     volumes:
       - type: volume                                # Persistent Docker-managed named volume for config + database
@@ -78,7 +81,6 @@ services:
     cpu_shares: 512             # Relative CPU weight for CPU contention scenarios
     pids_limit: 512             # Limit the number of processes/threads to prevent fork bombs
     logging:
-      driver: "json-file"       # Use JSON file logging driver
       options:
         max-size: "10m"         # Rotate log files after they reach 10MB
         max-file: "3"           # Keep a maximum of 3 log files

docs/DOCKER_INSTALLATION.md

@@ -4,10 +4,11 @@
 [![Discord](https://img.shields.io/discord/1274490466481602755?color=0aa8d2&logoColor=fff&logo=Discord&style=for-the-badge)](https://discord.gg/NczTUTWyRr)
 [![Home Assistant](https://img.shields.io/badge/Repo-blue?logo=home-assistant&style=for-the-badge&color=0aa8d2&logoColor=fff&label=Add)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons)
 
-# NetAlertX - Network scanner & notification framework
+# NetAlertX - Network Visibility & Asset Intelligence Framework
 
-| [📑 Docker guide](https://docs.netalertx.com/DOCKER_INSTALLATION) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://docs.netalertx.com/) | [🔌 Plugins](https://docs.netalertx.com/PLUGINS) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
-|----------------------| ----------------------|  ----------------------| ----------------------| ----------------------|
+---
+### || [Docker guide](https://docs.netalertx.com/DOCKER_INSTALLATION) || [Releases](https://github.com/netalertx/NetAlertX/releases) || [Docs](https://docs.netalertx.com/) || [Plugins](https://docs.netalertx.com/PLUGINS) || [Website](https://netalertx.com)
+---
 
 <a href="https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/GENERAL/github_social_image.jpg" target="_blank">
   <img src="https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/GENERAL/github_social_image.jpg" width="1000px" />
@@ -30,7 +31,7 @@ docker run -d --rm --network=host \
   --tmpfs /tmp:uid=${NETALERTX_UID:-20211},gid=${NETALERTX_GID:-20211},mode=1700 \
   -e PORT=20211 \
   -e APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20214"} \
-  ghcr.io/jokob-sk/netalertx:latest
+  ghcr.io/netalertx/netalertx:latest
 ```
 
 > Runtime UID/GID: The image defaults to a service user `netalertx` (UID/GID 20211). A separate readonly lock owner also uses UID/GID 20211 for 004/005 immutability. You can override the runtime UID/GID at build (ARG) or run (`--user` / compose `user:`) but must align writable mounts (`/data`, `/tmp*`) and tmpfs `uid/gid` to that choice.
@@ -120,8 +121,8 @@ You can read or watch several [community configuration guides](https://docs.neta
 
 ## 💙 Support me
 
-| [![GitHub](https://i.imgur.com/emsRCPh.png)](https://github.com/sponsors/jokob-sk) | [![Buy Me A Coffee](https://i.imgur.com/pIM6YXL.png)](https://www.buymeacoffee.com/jokobsk) | [![Patreon](https://i.imgur.com/MuYsrq1.png)](https://www.patreon.com/user?u=84385063) |
-| --- | --- | --- |
+| [![GitHub](https://i.imgur.com/emsRCPh.png)](https://github.com/sponsors/jokob-sk) | [![Buy Me A Coffee](https://i.imgur.com/pIM6YXL.png)](https://www.buymeacoffee.com/jokobsk) |
+| --- | --- |
 
 - Bitcoin: `1N8tupjeCK12qRVU2XrV17WvKK7LCawyZM`
 - Ethereum: `0x6e2749Cb42F4411bc98501406BdcD82244e3f9C7`

docs/DOCKER_PORTAINER.md

@@ -35,9 +35,9 @@ services:
   netalertx:
     container_name: netalertx
     # Use this line for stable release
-    image: "ghcr.io/jokob-sk/netalertx:latest"
+    image: "ghcr.io/netalertx/netalertx:latest"
     # Or, use this for the latest development build
-    # image: "ghcr.io/jokob-sk/netalertx-dev:latest"
+    # image: "ghcr.io/netalertx/netalertx-dev:latest"
     network_mode: "host"
     restart: unless-stopped
     cap_drop:       # Drop all capabilities for enhanced security
@@ -46,6 +46,9 @@ services:
       - NET_RAW
       - NET_ADMIN
       - NET_BIND_SERVICE
+      - CHOWN
+      - SETUID
+      - SETGID
     volumes:
       - ${APP_FOLDER}/netalertx/config:/data/config
       - ${APP_FOLDER}/netalertx/db:/data/db
@@ -69,6 +72,13 @@ In the **Environment variables** section of Portainer, add the following:
 * `PORT=22022` (or another port if needed)
 * `APP_CONF_OVERRIDE={"GRAPHQL_PORT":"22023"}` (optional advanced settings, otherwise the backend API server PORT defaults to `20212`)
 
+Additional environment variables (advanced / testing):
+
+* `SKIP_TESTS=1` — when set, the container entrypoint will skip all startup checks and print the message `Skipping startup checks as SKIP_TESTS is set.`. Useful for automated test runs or CI where the container should not perform environment-specific checks.
+* `SKIP_STARTUP_CHECKS="<check names>"` — space-delimited list of specific startup checks to skip. Names are the human-friendly names derived from files in `/entrypoint.d` (remove the leading numeric prefix and file extension). Example: `SKIP_STARTUP_CHECKS="mandatory folders"` will skip `30-mandatory-folders.sh`.
+
+Note: these variables are primarily useful for non-production scenarios (testing, CI, or specific deployments) and are processed by the entrypoint scripts. See `entrypoint.sh` and `entrypoint.d/*` for exact behaviour and available check names.
+
 ---
 
 ## 5. Ensure permissions

docs/DOCKER_SWARM.md

@@ -44,7 +44,7 @@ Use the following Compose snippet to deploy NetAlertX with a **static LAN IP** a
 ```yaml
 services:
   netalertx:
-    image: ghcr.io/jokob-sk/netalertx:latest
+    image: ghcr.io/netalertx/netalertx:latest
 ...
     networks:
       swarm-ipvlan:

docs/FEATURES.md

@@ -0,0 +1,92 @@
+# NetAlertX Features Overview
+
+NetAlertX is a lightweight, flexible platform for monitoring networks, tracking devices, and delivering actionable alerts. It combines discovery, change detection, and multi-channel notification into a single, streamlined solution.
+
+---
+
+## Network Discovery & Device Tracking
+
+![Network Discovery & Device Tracking](./img/FEATURES/Network_Discovery_Device_Tracking.png)
+
+- **Automatic Device Detection**: Continuously scans your local network to detect all connected devices via ARP, DHCP, SNMP, and compatible controllers.
+- **Presence Monitoring**: Track when devices appear, disappear, or reconnect on the network.
+- **IP & MAC Tracking**: Log device IP changes, ensuring accurate identification over time.
+- **Import from Existing Systems**: Integrates with DHCP servers, Pi-hole, UniFi controllers, and other supported sources to maintain an accurate inventory.
+
+---
+
+## LAN Visualization
+
+![LAN visualization](./img/FEATURES/LAN_Visualization.png)
+
+- **Lightweight Network Map**: View a real-time representation of your local network with all connected devices.
+- **Device Status Indicators**: Quickly identify active, missing, or new devices at a glance.
+- **Interactive Overview**: Hover over devices to see IP, MAC, and last seen timestamps.
+- **Change Highlighting**: Newly detected, disconnected, or reconnected devices are visually flagged to reduce oversight.
+- **Simple & Efficient**: Designed for quick insights without heavy resource usage or complex topology maps.
+
+---
+
+## Event-Driven Alerts
+
+![Event-Driven Alerts](./img/FEATURES/Event-Driven_Alerts.png)
+
+- **Real-Time Notifications**: Receive immediate alerts for new devices, disconnected devices, or unexpected changes.
+- **Customizable Filters and Rules**: Define rules based on device type, IP ranges, presence, or other network parameters.
+- **Alert Deduplication & Suppression**: Avoid unnecessary noise with smart alert handling.
+- **Historical Logs**: Maintain a complete timeline of network events for review and reporting.
+
+---
+
+## Workflows for implementing Business rules
+
+![orkflows](./img/WORKFLOWS/workflows.png)
+
+- **Custom rules**: Cretae custom flows and update device information based to scan results.
+- **Customizable Triggers**: Define rules based on any device data, including device type, IP ranges, presence, or other network parameters.
+- **Automated Updates**: Automate repetitive tasks, making network management more efficient.
+
+---
+
+## Multi-Channel Notification
+
+![Multi-Channel Notification](./img/FEATURES/Multi-Channel_Notifications.png)
+
+- **Flexible Delivery Options**: Send alerts via email, webhooks, MQTT, and more.
+- **Integration with Automation**: Connect to ticketing systems, workflow engines, and custom scripts for automated responses.
+- **Apprise Support**: Utilize over 80 pre-built notification services without additional configuration.
+
+---
+
+## Security & Compliance-Friendly Logging
+
+![Events](./img/FEATURES/Events.png)
+
+- **Device Accountability**: Maintain an auditable record of every device that appears or disappears from the network.
+- **Change Tracking**: Document network events with timestamps for review and compliance reporting.
+- **Rogue Device Alerts**: Detect and respond to unexpected or unauthorized network connections.
+
+---
+
+## MCP Server and OpenAPI
+
+![MCP Server](./img/FEATURES/MCP_Server.png)
+
+- **Data Access & Interaction**: The MCP server provides full programmatic access to NetAlertX, allowing you to query, monitor, and interact with network and device data.
+- **OpenAPI Integration**: Use the OpenAPI interface to fetch device status, network events, and logs, or trigger actions and alerts programmatically.
+- **Full Transparency**: All scan results, logs, and device information are accessible via the API, enabling auditing, automation, or integration with external systems.
+- **Flexible & Reliable**: Structured API access ensures predictable, repeatable interactions while allowing real-time data monitoring and operational control.
+
+---
+
+## Extensible & Open Source
+
+![Plugins](./img/plugins_json_settings.png)
+
+- **Plugin System**: Extend discovery methods, ingestion types, or notification channels through modular plugins.
+- **Community Contributions**: Open-source architecture encourages collaboration and improvements.
+- **Full Transparency**: All logs, scans, and configurations are visible for analysis.
+
+---
+
+NetAlertX provides a centralized, proactive approach to network awareness, combining device visibility, event-driven alerting, and flexible notifications into a single, deployable solution. Its design prioritizes efficiency, clarity, and actionable insights, making it ideal for monitoring dynamic environments.

docs/FILE_PERMISSIONS.md

@@ -12,7 +12,7 @@ docker run --rm --network=host \
   -v /etc/localtime:/etc/localtime:ro \
   --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
   -e PORT=20211 \
-  ghcr.io/jokob-sk/netalertx:latest
+  ghcr.io/netalertx/netalertx:latest
 ```
 
 > [!WARNING]
@@ -60,6 +60,8 @@ To run as the root user, it usually looks like this (verify the IDs on your serv
 ...
 ```
 
+If you use a custom `PUID` (e.g. `0`) and `GUID` (e.g. `100`) make sure you also update the `tmpfs` ownership, e.g. `/tmp:uid=0,gid=100...`
+
 ### Solution
 
 1. **Run the container once as root** (`--user "0"`) to allow it to correct permissions automatically:
@@ -68,7 +70,7 @@ To run as the root user, it usually looks like this (verify the IDs on your serv
 docker run -it --rm --name netalertx --user "0" \
   -v /local_data_dir:/data \
   --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
-  ghcr.io/jokob-sk/netalertx:latest
+  ghcr.io/netalertx/netalertx:latest
 ```
 
 2. Wait for logs showing **permissions being fixed**. The container will then **hang intentionally**.
@@ -93,7 +95,7 @@ docker run -it --rm --name netalertx --user "0" \
 services:
   netalertx:
     container_name: netalertx
-    image: "ghcr.io/jokob-sk/netalertx"
+    image: "ghcr.io/netalertx/netalertx"
     network_mode: "host"
     cap_drop:                                       # Drop all capabilities for enhanced security
       - ALL

docs/FIX_OFFLINE_DETECTION.md

@@ -42,7 +42,10 @@ ARPSCAN_DURATION=30
 
 ### ✅ Add ICMP (Ping) Scanning
 
-Enable the `ICMP` scan plugin to complement ARP detection. ICMP is often more reliable for detecting active hosts, especially when ARP fails. 
+Enable the `ICMP` scan plugin to complement ARP detection. ICMP is often more reliable for detecting active hosts, especially when ARP fails.
+
+> [!IMPORTANT]
+> If using AdGuard/Pi-hole: If devices still show offline after enabling ICMP, temporarily disable your content blocker. If the issue disappears, whitelist the NetAlertX host IP in your blocker's settings to prevent pings from being dropped.
 
 ### ✅ Use Multiple Detection Methods
 
@@ -52,7 +55,7 @@ A combined approach greatly improves detection robustness:
 * `ICMP` (ping)
 * `NMAPDEV` (nmap)
 
-This hybrid strategy increases reliability, especially for down detection and alerting. See [other plugins](./PLUGINS.md) that might be compatible with your setup. See benefits and drawbacks of individual scan methods in their respective docs. 
+This hybrid strategy increases reliability, especially for down detection and alerting. See [other plugins](./PLUGINS.md) that might be compatible with your setup. See benefits and drawbacks of individual scan methods in their respective docs.
 
 ## Results
 
@@ -76,4 +79,4 @@ After increasing the ARP timeout and adding ICMP scanning (on select IP ranges),
 
 Let us know in the [NetAlertX Discussions](https://github.com/jokob-sk/NetAlertX/discussions) if you have further feedback or edge cases.
 
-See also [Remote Networks](./REMOTE_NETWORKS.md) for more advanced setups. 
+See also [Remote Networks](./REMOTE_NETWORKS.md) for more advanced setups.

docs/INSTALLATION.md

@@ -8,11 +8,12 @@ NetAlertX can be installed several ways. The best supported option is Docker, fo
 - [[Installation] Home Assistant](https://github.com/alexbelgium/hassio-addons/tree/master/netalertx)
 - [[Installation] Unraid App](https://unraid.net/community/apps)
 - [[Installation] Bare metal (experimental - looking for maintainers)](https://docs.netalertx.com/HW_INSTALL)
+- [[Installation] Nix flake (community supported)](https://github.com/netalertx/NetAlertX/blob/main/install/nix/flake.nix) submitted by [2m](https://github.com/2m)
 
 
 ## Help
 
-If facing issues, please spend a few minutes seraching.
+If facing issues, please spend a few minutes searching.
 
 - Check [common issues](./COMMON_ISSUES.md)
 - Have a look at [Community guides](./COMMUNITY_GUIDES.md)

docs/MIGRATION.md

@@ -16,6 +16,9 @@ When upgrading from older versions of NetAlertX (or PiAlert by jokob-sk), follow
 - You are running NetAlertX (by jokob-sk) (`v25.6.7` to `v25.10.1`)
   → [Read the 1.3 Migration from NetAlertX `v25.10.1`](#13-migration-from-netalertx-v25101)
 
+- You are running NetAlertX (by jokob-sk) (`v25.11.29`)
+  → [Read the 1.4 Migration from NetAlertX `v25.11.29`](#14-migration-from-netalertx-v251129)
+
 
 ### 1.0 Manual Migration
 
@@ -212,7 +215,7 @@ services:
 
 ### 1.3 Migration from NetAlertX `v25.10.1`
 
-Starting from v25.10.1, the container uses a [more secure, read-only runtime environment](./SECURITY_FEATURES.md), which requires all writable paths (e.g., logs, API cache, temporary data) to be mounted as `tmpfs` or permanent writable volumes, with sufficient access [permissions](./FILE_PERMISSIONS.md). The data location has also hanged from `/app/db` and `/app/config` to `/data/db` and `/data/config`. See detailed steps below.
+Starting from `v25.10.1`, the container uses a [more secure, read-only runtime environment](./SECURITY_FEATURES.md), which requires all writable paths (e.g., logs, API cache, temporary data) to be mounted as `tmpfs` or permanent writable volumes, with sufficient access [permissions](./FILE_PERMISSIONS.md). The data location has also hanged from `/app/db` and `/app/config` to `/data/db` and `/data/config`. See detailed steps below.
 
 #### STEPS:
 
@@ -245,7 +248,7 @@ services:
 services:
   netalertx:
     container_name: netalertx
-    image: "ghcr.io/jokob-sk/netalertx"  # 🆕 This has changed
+    image: "ghcr.io/jokob-sk/netalertx:25.11.29"  # 🆕 This has changed
     network_mode: "host"
     cap_drop:                # 🆕 New line
       - ALL                  # 🆕 New line
@@ -296,6 +299,50 @@ sudo chown -R 20211:20211 /local_data_dir
 sudo chmod -R a+rwx /local_data_dir
 ```
 
-8. Start the container and verify everything works as expeexpected.
+8. Start the container and verify everything works as expected.
 9. Check the [Permissions -> Writable-paths](https://docs.netalertx.com/FILE_PERMISSIONS/#writable-paths) what directories to mount if you'd like to access the API or log files.
 
+
+### 1.4 Migration from NetAlertX `v25.11.29`
+
+As per user feedback, we’ve re-introduced the ability to control which user the application runs as via the `PUID` and `PGID` environment variables. This required additional changes to the container to safely handle permission adjustments at runtime.
+
+#### STEPS:
+
+1. Stop the container
+2. [Back up your setup](./BACKUPS.md)
+3. Stop the container
+4. Update the `docker-compose.yml` as per example below.
+
+```yaml
+services:
+  netalertx:
+    container_name: netalertx
+    image: "ghcr.io/netalertx/netalertx"
+    network_mode: "host"
+    cap_drop:
+      - ALL
+    cap_add:
+      - NET_RAW
+      - NET_ADMIN
+      - NET_BIND_SERVICE
+      - CHOWN                # 🆕 New line
+      - SETUID               # 🆕 New line
+      - SETGID               # 🆕 New line
+    restart: unless-stopped
+    volumes:
+      - /local_data_dir:/data
+      # Ensuring the timezone is the same as on the server - make sure also the TIMEZONE setting is configured
+      - /etc/localtime:/etc/localtime:ro
+    environment:
+      - PORT=20211
+      # - PUID=0    # New optional variable to run as root
+      # - GUID=100  # New optional variable to run as root
+    tmpfs:
+      # All writable runtime state resides under /tmp; comment out to persist logs between restarts
+      - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+```
+
+5. If you use a custom `PUID` (e.g. `0`) and `GUID` (e.g. `100`) make sure you also update the `tmpfs` ownership, e.g. `/tmp:uid=0,gid=100...`
+6. Start the container and verify everything works as expected.
+7. If running a reverse proxy review the [Reverse proxy documentation](./REVERSE_PROXY.md) as a new `BACKEND_API_URL` setting was added.

docs/PERFORMANCE.md

@@ -80,9 +80,9 @@ services:
   netalertx:
     container_name: netalertx
     # Use this line for the stable release
-    image: "ghcr.io/jokob-sk/netalertx:latest"
+    image: "ghcr.io/netalertx/netalertx:latest"
     # Or use this line for the latest development build
-    # image: "ghcr.io/jokob-sk/netalertx-dev:latest"
+    # image: "ghcr.io/netalertx/netalertx-dev:latest"
     network_mode: "host"
     restart: unless-stopped
 
@@ -92,6 +92,9 @@ services:
       - NET_RAW
       - NET_ADMIN
       - NET_BIND_SERVICE
+      - CHOWN
+      - SETUID
+      - SETGID
 
     volumes:
       - ${APP_FOLDER}/netalertx/config:/data/config

docs/PLUGINS_DEV.md

@@ -268,7 +268,7 @@ To import plugin data into NetAlertX tables for device discovery or notification
   "database_column_definitions": [
     {
       "column": "Object_PrimaryID",
-      "mapped_to_column": "cur_MAC",
+      "mapped_to_column": "scanMac",
       "show": true,
       "type": "device_mac",
       "localized": ["name"],
@@ -287,7 +287,7 @@ To always map a static value (not read from plugin output):
 ```json
 {
   "column": "NameDoesntMatter",
-  "mapped_to_column": "cur_ScanMethod",
+  "mapped_to_column": "scanSourcePlugin",
   "mapped_to_column_data": {
     "value": "MYPLN"
   }

docs/PLUGINS_DEV_CONFIG.md

@@ -177,6 +177,55 @@ 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:
+
+- `["devName", "devLastIP"]` - Plugin can always overwrite this field when authorized (subject to source-based permissions)
+
+**Authorization logic:** Even with a field listed in `SET_ALWAYS`, 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)
+- Will update plugin-owned sources if value the same
+
+**Example in config.json:**
+
+```json
+{
+  "SET_ALWAYS": ["devName", "devLastIP"]
+}
+```
+
+### SET_EMPTY
+
+**Optional field override.**
+
+Restricts when a plugin can update a field:
+
+- `"SET_EMPTY": ["devName", "devLastIP"]` - Overwrite these fields only if current value is empty OR source is `NEWDEV`
+
+**Use case:** Some plugins discover optional enrichment data (like vendor/hostname) that shouldn't override user-set or existing values. Use `SET_EMPTY` to be less aggressive.
+
+
+### Authorization Decision Flow
+
+1. **Source check:** Is field LOCKED or USER? → REJECT (protected)
+2. **Field in 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. **Field in 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
+
+**Note:** Check each plugin's `config.json` manifest for its specific SET_ALWAYS/SET_EMPTY configuration.
+
+---
+
 ## Summary
 
 The lifecycle of a plugin configuration is:

docs/PLUGINS_DEV_UI_COMPONENTS.md

@@ -440,7 +440,7 @@ To import plugin data into the device scan pipeline (for notifications, heuristi
   "database_column_definitions": [
     {
       "column": "Object_PrimaryID",
-      "mapped_to_column": "cur_MAC",
+      "mapped_to_column": "scanMac",
       "show": true,
       "type": "device_mac",
       "localized": ["name"],
@@ -448,7 +448,7 @@ To import plugin data into the device scan pipeline (for notifications, heuristi
     },
     {
       "column": "Object_SecondaryID",
-      "mapped_to_column": "cur_IP",
+      "mapped_to_column": "scanLastIP",
       "show": true,
       "type": "device_ip",
       "localized": ["name"],
@@ -456,7 +456,7 @@ To import plugin data into the device scan pipeline (for notifications, heuristi
     },
     {
       "column": "NameDoesntMatter",
-      "mapped_to_column": "cur_ScanMethod",
+      "mapped_to_column": "scanSourcePlugin",
       "mapped_to_column_data": {
         "value": "MYSCAN"
       },
@@ -478,7 +478,7 @@ Use `mapped_to_column_data` to map a static value instead of reading from a colu
 ```json
 {
   "column": "NameDoesntMatter",
-  "mapped_to_column": "cur_ScanMethod",
+  "mapped_to_column": "scanSourcePlugin",
   "mapped_to_column_data": {
     "value": "MYSCAN"
   },
@@ -489,7 +489,7 @@ Use `mapped_to_column_data` to map a static value instead of reading from a colu
 }
 ```
 
-This always sets `cur_ScanMethod` to `"MYSCAN"` regardless of column data.
+This always sets `scanSourcePlugin` to `"MYSCAN"` regardless of column data.
 
 ---
 
@@ -546,7 +546,7 @@ When viewing a device detail page, the `txtMacFilter` field is populated with th
   "database_column_definitions": [
     {
       "column": "Object_PrimaryID",
-      "mapped_to_column": "cur_MAC",
+      "mapped_to_column": "scanMac",
       "css_classes": "col-sm-2",
       "show": true,
       "type": "device_mac",
@@ -556,7 +556,7 @@ When viewing a device detail page, the `txtMacFilter` field is populated with th
     },
     {
       "column": "Object_SecondaryID",
-      "mapped_to_column": "cur_IP",
+      "mapped_to_column": "scanLastIP",
       "css_classes": "col-sm-2",
       "show": true,
       "type": "device_ip",

docs/README.md

@@ -63,7 +63,7 @@ There is also an in-app Help / FAQ section that should be answering frequently a
 
 #### ♻ Misc
 
-- [Reverse proxy (Nginx, Apache, SWAG)](./REVERSE_PROXY.md)
+- [Reverse Proxy](./REVERSE_PROXY.md)
 - [Installing Updates](./UPDATES.md)
 - [Setting up Authelia](./AUTHELIA.md) (DRAFT)
 

docs/REMOTE_NETWORKS.md

@@ -13,9 +13,17 @@ The following network setups might make some devices undetectable with `ARPSCAN`
 
 ### Wi-Fi Extenders
 
-Wi-Fi extenders typically create a separate network or subnet, which can prevent network scanning tools like `arp-scan` from detecting devices behind the extender.
+Wi-Fi extenders often **block or proxy Layer-2 broadcast traffic**, which can prevent network scanning tools like `arp-scan` from detecting devices behind the extender. This can happen **even when the extender uses the same SSID and the same IP subnet** as the main network.
 
-> **Possible workaround**: Scan the specific subnet that the extender uses, if it is separate from the main network.
+Please note that being able to `ping` a device does **not** mean it is discoverable via `arp-scan`.
+
+* `arp-scan` relies on **Layer 2 (ARP broadcast)**
+* ICMP (`ping`) operates at **Layer 3 (routed traffic)**
+
+That’s why devices behind extenders may respond to ping but remain undiscoverable via `arp-scan`.
+
+> **Possible workaround**:
+> If the extender uses a separate subnet, scan that subnet directly. Otherwise, use DHCP-based discovery plugins or router integration instead of ARP. See the **Other Workarounds** section below for more details.
 
 ### VPNs
 
@@ -43,7 +51,7 @@ If you don't need to discover new devices and only need to report on their statu
 
 For more information on how to add devices manually (or dummy devices), refer to the [Device Management](./DEVICE_MANAGEMENT.md) documentation.
 
-To create truly dummy devices, you can use a loopback IP address (e.g., `0.0.0.0` or `127.0.0.1`) so they appear online.
+To create truly dummy devices, you can use a loopback IP address (e.g., `0.0.0.0` or `127.0.0.1`) or the `Force Status` field so they appear online.
 
 ## NMAP and Fake MAC Addresses
 

docs/REVERSE_DNS.md

@@ -39,7 +39,7 @@ You can specify the DNS server in the docker-compose to improve name resolution
 services:
   netalertx:
     container_name: netalertx
-    image: "ghcr.io/jokob-sk/netalertx:latest"
+    image: "ghcr.io/netalertx/netalertx:latest"
 ...
     dns:           # specifying the DNS servers used for the container
       - 10.8.0.1

docs/SYNOLOGY_GUIDE.md

@@ -37,8 +37,8 @@ services:
   netalertx:
     container_name: netalertx
     # use the below line if you want to test the latest dev image
-    # image: "ghcr.io/jokob-sk/netalertx-dev:latest"
-    image: "ghcr.io/jokob-sk/netalertx:latest"
+    # image: "ghcr.io/netalertx/netalertx-dev:latest"
+    image: "ghcr.io/netalertx/netalertx:latest"
     network_mode: "host"
     restart: unless-stopped
     cap_drop:       # Drop all capabilities for enhanced security
@@ -47,6 +47,9 @@ services:
       - NET_RAW
       - NET_ADMIN
       - NET_BIND_SERVICE
+      - CHOWN
+      - SETUID
+      - SETGID
     volumes:
       - /app_storage/netalertx:/data
       # to sync with system time

docs/docker-troubleshooting/aufs-capabilities.md

@@ -30,7 +30,7 @@ When AUFS is detected without root privileges, the system emits the following wa
 >
 > AUFS strips Linux file capabilities, so tools like arp-scan, nmap, and nbtscan fail when NetAlertX runs as a non-root PUID.
 >
-> **Action:** Set PUID=0 on AUFS hosts for full functionality.
+> **Action:** Set `PUID=0` on AUFS hosts for full functionality.
 
 
 ## Security Ramifications

docs/docker-troubleshooting/running-as-root.md

@@ -1,5 +1,8 @@
 # Running as Root User
 
+> [!TIP]
+> Looking for how to run the container as root? See the [File permissions documentation](../FILE_PERMISSIONS.md) for details.
+
 ## Issue Description
 
 NetAlertX has detected that the container is running with root privileges (UID 0). This configuration bypasses all built-in security hardening measures designed to protect your system.