Merge branch 'main' of https://github.com/jokob-sk/NetAlertX

Signed-off-by: jokob-sk <jokob.sk@gmail.com>

.coderabbit.yaml

@@ -0,0 +1,9 @@
+reviews:
+  profile: "chill"
+  estimate_code_review_effort: false
+  auto_review:
+    enabled: true
+  high_level_summary: true
+issue_enrichment:
+  auto_enrich:
+    enabled: false

.devcontainer/Dockerfile

@@ -4,16 +4,16 @@
 # The NetAlertX Dockerfile has 3 stages:
 #
 # Stage 1. Builder - NetAlertX Requires special tools and packages to build our virtual environment, but
-# which are not needed in future stages.  We build the builder and extract the venv for runner to use as 
+# which are not needed in future stages.  We build the builder and extract the venv for runner to use as
 # a base.
 #
 # Stage 2. Runner builds the bare minimum requirements to create an operational NetAlertX. The primary
 # reason for breaking at this stage is it leaves the system in a proper state for devcontainer operation
-# This image also provides a break-out point for uses who wish to execute the anti-pattern of using a 
+# This image also provides a break-out point for uses who wish to execute the anti-pattern of using a
 # docker container as a VM for experimentation and various development patterns.
 #
 # Stage 3. Hardened removes root, sudoers, folders, permissions, and locks the system down into a read-only
-# compatible image. While NetAlertX does require some read-write operations, this image can guarantee the 
+# compatible image. While NetAlertX does require some read-write operations, this image can guarantee the
 # code pushed out by the project is the only code which will run on the system after each container restart.
 # It reduces the chance of system hijacking and operates with all modern security protocols in place as is
 # expected from a security appliance.
@@ -29,13 +29,25 @@ ENV PATH="/opt/venv/bin:$PATH"
 
 # Install build dependencies
 COPY requirements.txt /tmp/requirements.txt
-RUN apk add --no-cache bash shadow python3 python3-dev gcc musl-dev libffi-dev openssl-dev git \
+# hadolint ignore=DL3018
+RUN apk add --no-cache \
+        bash \
+        shadow \
+        python3 \
+        python3-dev \
+        gcc \
+        musl-dev \
+        libffi-dev \
+        openssl-dev \
+        git \
+        rust \
+        cargo \
     && python -m venv /opt/venv
 
-# Create virtual environment owned by root, but readable by everyone else. This makes it easy to copy 
-# into hardened stage without worrying about permissions and keeps image size small. Keeping the commands
-# together makes for a slightly smaller image size.
-RUN pip install --no-cache-dir -r /tmp/requirements.txt && \
+# Upgrade pip/wheel/setuptools and install Python packages
+# hadolint ignore=DL3013, DL3042
+RUN python -m pip install --upgrade pip setuptools wheel && \
+    pip install --prefer-binary --no-cache-dir -r /tmp/requirements.txt && \
     chmod -R u-rwx,g-rwx /opt
 
 # second stage is the main runtime stage with just the minimum required to run the application
@@ -43,6 +55,12 @@ RUN pip install --no-cache-dir -r /tmp/requirements.txt && \
 FROM alpine:3.22 AS runner
 
 ARG INSTALL_DIR=/app
+# Runtime service account (override at build; container user can still be overridden at run time)
+ARG NETALERTX_UID=20211
+ARG NETALERTX_GID=20211
+# Read-only lock owner (separate from service account to avoid UID/GID collisions)
+ARG READONLY_UID=20212
+ARG READONLY_GID=20212
 
 # NetAlertX app directories
 ENV NETALERTX_APP=${INSTALL_DIR}
@@ -98,11 +116,11 @@ ENV READ_WRITE_FOLDERS="${NETALERTX_DATA} ${NETALERTX_CONFIG} ${NETALERTX_DB} ${
                        ${SYSTEM_SERVICES_ACTIVE_CONFIG}"
 
 #Python environment
-ENV PYTHONUNBUFFERED=1 
+ENV PYTHONUNBUFFERED=1
 ENV VIRTUAL_ENV=/opt/venv
 ENV VIRTUAL_ENV_BIN=/opt/venv/bin
 ENV PYTHONPATH=${NETALERTX_APP}:${NETALERTX_SERVER}:${NETALERTX_PLUGINS}:${VIRTUAL_ENV}/lib/python3.12/site-packages
-ENV PATH="${SYSTEM_SERVICES}:${VIRTUAL_ENV_BIN}:$PATH" 
+ENV PATH="${SYSTEM_SERVICES}:${VIRTUAL_ENV_BIN}:$PATH"
 
 # App Environment
 ENV LISTEN_ADDR=0.0.0.0
@@ -113,17 +131,17 @@ ENV VENDORSPATH_NEWEST=${SYSTEM_SERVICES_RUN_TMP}/ieee-oui.txt
 ENV ENVIRONMENT=alpine
 ENV READ_ONLY_USER=readonly READ_ONLY_GROUP=readonly
 ENV NETALERTX_USER=netalertx NETALERTX_GROUP=netalertx
-ENV LANG=C.UTF-8 
+ENV LANG=C.UTF-8
 
 
-RUN apk add --no-cache bash mtr libbsd zip lsblk tzdata curl arp-scan iproute2 iproute2-ss nmap \
+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 && \
+    nginx supercronic shadow su-exec && \
     rm -Rf /var/cache/apk/*  && \
     rm -Rf /etc/nginx && \
-    addgroup -g 20211 ${NETALERTX_GROUP} && \
-    adduser -u 20211 -D -h ${NETALERTX_APP} -G ${NETALERTX_GROUP} ${NETALERTX_USER} && \
+    addgroup -g ${NETALERTX_GID} ${NETALERTX_GROUP} && \
+    adduser -u ${NETALERTX_UID} -D -h ${NETALERTX_APP} -G ${NETALERTX_GROUP} ${NETALERTX_USER} && \
     apk del shadow
 
 
@@ -141,23 +159,24 @@ 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
-COPY --from=builder --chown=20212:20212 ${VIRTUAL_ENV} ${VIRTUAL_ENV}
+# Copy the virtualenv from the builder stage (owned by readonly lock owner)
+COPY --from=builder --chown=${READONLY_UID}:${READONLY_GID} ${VIRTUAL_ENV} ${VIRTUAL_ENV}
 
 
 # Initialize each service with the dockerfiles/init-*.sh scripts, once.
 # This is done after the copy of the venv to ensure the venv is in place
 # although it may be quicker to do it before the copy, it keeps the image
 # layers smaller to do it after.
-RUN if [ -f '.VERSION' ]; then \
-        cp '.VERSION' "${NETALERTX_APP}/.VERSION"; \
-    else \
-        echo "DEVELOPMENT 00000000" > "${NETALERTX_APP}/.VERSION"; \
-    fi && \
-    chown 20212:20212 "${NETALERTX_APP}/.VERSION" && \
+# hadolint ignore=DL3018
+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 && \
     apk add --no-cache libcap && \
-    setcap cap_net_raw+ep /bin/busybox && \
     setcap cap_net_raw,cap_net_admin+eip /usr/bin/nmap && \
     setcap cap_net_raw,cap_net_admin+eip /usr/bin/arp-scan && \
     setcap cap_net_raw,cap_net_admin,cap_net_bind_service+eip /usr/bin/nbtscan && \
@@ -172,22 +191,28 @@ RUN if [ -f '.VERSION' ]; then \
     date +%s > "${NETALERTX_FRONT}/buildtimestamp.txt"
 
 
-ENTRYPOINT ["/bin/sh","/entrypoint.sh"]
+ENTRYPOINT ["/bin/bash","/entrypoint.sh"]
 
 # Final hardened stage to improve security by setting least possible permissions and removing sudo access.
 # When complete, if the image is compromised, there's not much that can be done with it.
 # This stage is separate from Runner stage so that devcontainer can use the Runner stage.
 FROM runner AS hardened
 
+# Re-declare UID/GID args for this stage
+ARG NETALERTX_UID=20211
+ARG NETALERTX_GID=20211
+ARG READONLY_UID=20212
+ARG READONLY_GID=20212
+
 ENV UMASK=0077
 
 # Create readonly user and group with no shell access.
 # Readonly user marks folders that are created by NetAlertX, but should not be modified.
-# AI may claim this is stupid, but it's actually least possible permissions as 
+# AI may claim this is stupid, but it's actually least possible permissions as
 # read-only user cannot login, cannot sudo, has no write permission, and cannot even
 # read the files it owns. The read-only user is ownership-as-a-lock hardening pattern.
-RUN addgroup -g 20212 "${READ_ONLY_GROUP}" && \
-    adduser -u 20212 -G "${READ_ONLY_GROUP}" -D -h /app "${READ_ONLY_USER}"
+RUN addgroup -g ${READONLY_GID} "${READ_ONLY_GROUP}" && \
+    adduser -u ${READONLY_UID} -G "${READ_ONLY_GROUP}" -D -h /app "${READ_ONLY_USER}"
 
 
 # reduce permissions to minimum necessary for all NetAlertX files and folders
@@ -198,24 +223,27 @@ RUN addgroup -g 20212 "${READ_ONLY_GROUP}" && \
 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 700 ${READ_WRITE_FOLDERS} && \
-    chown -R ${NETALERTX_USER}:${NETALERTX_GROUP} ${READ_WRITE_FOLDERS} && \
-    chmod -R 600 ${READ_WRITE_FOLDERS} && \
-    find ${READ_WRITE_FOLDERS} -type d -exec chmod 700 {} + && \
-    chown ${READ_ONLY_USER}:${READ_ONLY_GROUP} /entrypoint.sh /opt /opt/venv && \
-    chmod 005 /entrypoint.sh ${SYSTEM_SERVICES}/*.sh ${SYSTEM_SERVICES_SCRIPTS}/* ${ENTRYPOINT_CHECKS}/* /app /opt /opt/venv && \
-    for dir in ${READ_WRITE_FOLDERS}; do \
-        install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 700 "$dir"; \
-    done && \
+    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 /opt /opt/venv && \
+    chmod 005 /entrypoint.sh /root-entrypoint.sh ${SYSTEM_SERVICES}/*.sh ${SYSTEM_SERVICES_SCRIPTS}/* ${ENTRYPOINT_CHECKS}/* /app /opt /opt/venv && \
+    # Do not bake first-run artifacts into the image. If present, Docker volume copy-up
+    # will persist restrictive ownership/modes into fresh named volumes, breaking
+    # arbitrary non-root UID/GID runs.
+    rm -f \
+      "${NETALERTX_CONFIG}/app.conf" \
+      "${NETALERTX_DB_FILE}" \
+      "${NETALERTX_DB_FILE}-shm" \
+      "${NETALERTX_DB_FILE}-wal" || true && \
     apk del apk-tools && \
     rm -Rf /var /etc/sudoers.d/* /etc/shadow /etc/gshadow /etc/sudoers \
     /lib/apk /lib/firmware /lib/modules-load.d /lib/sysctl.d /mnt /home/ /root \
     /srv /media && \
-    sed -i "/^\(${READ_ONLY_USER}\|${NETALERTX_USER}\):/!d" /etc/passwd && \
-    sed -i "/^\(${READ_ONLY_GROUP}\|${NETALERTX_GROUP}\):/!d" /etc/group && \
+    # Preserve root and system identities so hardened entrypoint never needs to patch /etc/passwd or /etc/group at runtime.
     printf '#!/bin/sh\n"$@"\n' > /usr/bin/sudo && chmod +x /usr/bin/sudo
+USER "0"
 
-USER netalertx
+# Call root-entrypoint.sh which drops priviliges to run entrypoint.sh.
+ENTRYPOINT ["/root-entrypoint.sh"]
 
 HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
     CMD /services/healthcheck.sh
@@ -247,9 +275,13 @@ COPY .devcontainer/resources/devcontainer-overlay/ /
 USER root
 # Install common tools, create user, and set up sudo
 
+# Ensure entrypoint scripts stay executable in the devcontainer (avoids 126 errors)
+RUN chmod +x /entrypoint.sh /root-entrypoint.sh /entrypoint.d/*.sh && \
+    chmod +x /entrypoint.d/35-apply-conf-override.sh
+
 RUN apk add --no-cache git nano vim jq php83-pecl-xdebug py3-pip nodejs sudo gpgconf pytest \
     pytest-cov zsh alpine-zsh-config shfmt github-cli py3-yaml py3-docker-py docker-cli docker-cli-buildx \
-    docker-cli-compose shellcheck
+    docker-cli-compose shellcheck py3-psutil chromium chromium-chromedriver
 
 # Install hadolint (Dockerfile linter)
 RUN curl -L https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64 -o /usr/local/bin/hadolint && \
@@ -275,6 +307,6 @@ RUN mkdir -p /workspaces && \
     chown netalertx:netalertx /home/netalertx && \
     sed -i -e 's#/app:#/workspaces:#' /etc/passwd && \
     find /opt/venv -type d -exec chmod o+rwx {} \;
-    
+
 USER netalertx
 ENTRYPOINT ["/bin/sh","-c","sleep infinity"]

.devcontainer/devcontainer.json

@@ -12,7 +12,8 @@
   "capAdd": [
     "SYS_ADMIN", // For mounting ramdisks
     "NET_ADMIN", // For network interface configuration
-    "NET_RAW" // For raw packet manipulation
+    "NET_RAW", // For raw packet manipulation
+    "NET_BIND_SERVICE" // For privileged port binding (e.g., UDP 137)
   ],
   "runArgs": [
     "--security-opt",
@@ -25,7 +26,7 @@
     // even within this container and connect to them as needed.
     // "--network=host",
   ],
-  "mounts": [ 
+  "mounts": [
     "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind" //used for testing various conditions in docker
   ],
   // ATTENTION: If running with --network=host, COMMENT `forwardPorts` OR ELSE THERE WILL BE NO WEBUI!
@@ -46,12 +47,12 @@
   },
 
   "postCreateCommand": {
-      "Install Pip Requirements": "/opt/venv/bin/pip3 install pytest docker debugpy",
-      "Workspace Instructions": "printf '\n\n<> DevContainer Ready!\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'"
+      "Install Pip Requirements": "/opt/venv/bin/pip3 install pytest docker debugpy selenium",
+      "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 building netalertx-test container in background. check /tmp/build.log for progress. && setsid docker buildx build -t netalertx-test . > /tmp/build.log 2>&1 &"
+      "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' &"
   },
   "customizations": {
     "vscode": {
@@ -88,7 +89,7 @@
           }
         },
         "terminal.integrated.defaultProfile.linux": "zsh",
-        
+
         // Python testing configuration
         "python.testing.pytestEnabled": true,
         "python.testing.unittestEnabled": false,

.devcontainer/resources/devcontainer-Dockerfile

@@ -22,9 +22,13 @@ COPY .devcontainer/resources/devcontainer-overlay/ /
 USER root
 # Install common tools, create user, and set up sudo
 
+# Ensure entrypoint scripts stay executable in the devcontainer (avoids 126 errors)
+RUN chmod +x /entrypoint.sh /root-entrypoint.sh /entrypoint.d/*.sh && \
+    chmod +x /entrypoint.d/35-apply-conf-override.sh
+
 RUN apk add --no-cache git nano vim jq php83-pecl-xdebug py3-pip nodejs sudo gpgconf pytest \
     pytest-cov zsh alpine-zsh-config shfmt github-cli py3-yaml py3-docker-py docker-cli docker-cli-buildx \
-    docker-cli-compose shellcheck
+    docker-cli-compose shellcheck py3-psutil chromium chromium-chromedriver
 
 # Install hadolint (Dockerfile linter)
 RUN curl -L https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64 -o /usr/local/bin/hadolint && \
@@ -50,6 +54,6 @@ RUN mkdir -p /workspaces && \
     chown netalertx:netalertx /home/netalertx && \
     sed -i -e 's#/app:#/workspaces:#' /etc/passwd && \
     find /opt/venv -type d -exec chmod o+rwx {} \;
-    
+
 USER netalertx
 ENTRYPOINT ["/bin/sh","-c","sleep infinity"]

.devcontainer/scripts/load-devices.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+if [ -n "${CSV_PATH:-}" ]; then
+  : # user provided CSV_PATH
+else
+  # Portable mktemp fallback: try GNU coreutils first, then busybox-style
+  if mktemp --version >/dev/null 2>&1; then
+    CSV_PATH="$(mktemp --tmpdir netalertx-devices-XXXXXX.csv 2>/dev/null || mktemp /tmp/netalertx-devices-XXXXXX.csv)"
+  else
+    CSV_PATH="$(mktemp -t netalertx-devices.XXXXXX 2>/dev/null || mktemp /tmp/netalertx-devices-XXXXXX.csv)"
+  fi
+fi
+DEVICE_COUNT="${DEVICE_COUNT:-255}"
+SEED="${SEED:-20211}"
+NETWORK_CIDR="${NETWORK_CIDR:-192.168.50.0/22}"
+DB_DIR="${NETALERTX_DB:-/data/db}"
+DB_FILE="${DB_DIR%/}/app.db"
+
+# Ensure we are inside the devcontainer
+"${SCRIPT_DIR}/isDevContainer.sh" >/dev/null
+
+if [ ! -f "${DB_FILE}" ]; then
+  echo "[load-devices] Database not found at ${DB_FILE}. Is the devcontainer initialized?" >&2
+  exit 1
+fi
+
+if ! command -v sqlite3 >/dev/null 2>&1; then
+  echo "[load-devices] sqlite3 is required but not installed." >&2
+  exit 1
+fi
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "[load-devices] python3 is required but not installed." >&2
+  exit 1
+fi
+if ! command -v curl >/dev/null 2>&1; then
+  echo "[load-devices] curl is required but not installed." >&2
+  exit 1
+fi
+
+# Generate synthetic device inventory CSV
+python3 "${REPO_ROOT}/scripts/generate-device-inventory.py" \
+  --output "${CSV_PATH}" \
+  --devices "${DEVICE_COUNT}" \
+  --seed "${SEED}" \
+  --network "${NETWORK_CIDR}" >/dev/null
+
+echo "[load-devices] CSV generated at ${CSV_PATH} (devices=${DEVICE_COUNT}, seed=${SEED})"
+
+API_TOKEN="$(sqlite3 "${DB_FILE}" "SELECT setValue FROM Settings WHERE setKey='API_TOKEN';")"
+GRAPHQL_PORT="$(sqlite3 "${DB_FILE}" "SELECT setValue FROM Settings WHERE setKey='GRAPHQL_PORT';")"
+
+if [ -z "${API_TOKEN}" ] || [ -z "${GRAPHQL_PORT}" ]; then
+  echo "[load-devices] Failed to read API_TOKEN or GRAPHQL_PORT from ${DB_FILE}" >&2
+  exit 1
+fi
+
+IMPORT_URL="http://localhost:${GRAPHQL_PORT}/devices/import"
+
+HTTP_CODE=$(curl -sS -o /tmp/load-devices-response.json -w "%{http_code}" \
+  -X POST "${IMPORT_URL}" \
+  -H "Authorization: Bearer ${API_TOKEN}" \
+  -F "file=@${CSV_PATH}")
+
+if [ "${HTTP_CODE}" != "200" ]; then
+  echo "[load-devices] Import failed with HTTP ${HTTP_CODE}. Response:" >&2
+  cat /tmp/load-devices-response.json >&2
+  exit 1
+fi
+
+# Fetch totals for a quick sanity check
+TOTALS=$(curl -sS -H "Authorization: Bearer ${API_TOKEN}" "http://localhost:${GRAPHQL_PORT}/devices/totals" || true)
+
+echo "[load-devices] Import succeeded (HTTP ${HTTP_CODE})."
+echo "[load-devices] Devices totals: ${TOTALS}"
+echo "[load-devices] Done. CSV kept at ${CSV_PATH}"

.devcontainer/scripts/setup.sh

@@ -47,6 +47,9 @@ sudo mount -t tmpfs -o size=50m,mode=0777 tmpfs /tmp/nginx 2>/dev/null || true
 
 sudo chmod 777 /tmp/log /tmp/api /tmp/run /tmp/nginx
 
+# Create critical subdirectories immediately after tmpfs mount
+sudo install -d -m 777 /tmp/run/tmp
+sudo install -d -m 777 /tmp/log/plugins
 
 
 sudo rm -rf /entrypoint.d
@@ -85,9 +88,7 @@ sudo chmod 777 "${LOG_DB_IS_LOCKED}"
 
 sudo pkill -f python3 2>/dev/null || true
 
-sudo chmod 777 "${PY_SITE_PACKAGES}" "${NETALERTX_DATA}" "${NETALERTX_DATA}"/* 2>/dev/null || true
-
-sudo chmod 005 "${PY_SITE_PACKAGES}" 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

.github/ISSUE_TEMPLATE/documentation-feedback.yml

@@ -14,7 +14,7 @@ body:
     label: What document or section does this relate to?
     description: |
       Please include a link to the file and section, if applicable. Be specific about what part of the documentation you are referencing.
-    placeholder: e.g. https://github.com/jokob-sk/NetAlertX/blob/main/docs/FRONTEND_DEVELOPMENT.md
+    placeholder: e.g. https://docs.netalertx.com/FRONTEND_DEVELOPMENT
   validations:
     required: true
 - type: textarea
@@ -49,7 +49,7 @@ body:
     required: false
 - type: checkboxes
   attributes:
-    label: Can I help implement this? 👩‍💻👨‍💻 
+    label: Can I help implement this? 👩‍💻👨‍💻
     description: The maintainer can provide guidance and review your changes.
     options:
       - label: "Yes, I’d like to help implement the improvement"

.github/ISSUE_TEMPLATE/enhancement-request.yml

@@ -1,33 +0,0 @@
-name: Enhancement Request
-description: Propose an improvement to an existing feature or UX behavior.
-labels: ['enhancement ♻️']
-body:
-- type: checkboxes
-  attributes:
-    label: Is there an existing issue for this?
-    options:
-      - label: I have searched existing open and closed issues
-        required: true
-- type: textarea
-  attributes:
-    label: What is the enhancement?
-    description: Describe the change or optimization you’d like to see to an existing feature.
-    placeholder: e.g. Make scan intervals configurable from UI instead of just `app.conf`
-    required: true
-- type: textarea
-  attributes:
-    label: What problem does this solve or improve?
-    description: Describe why this change would improve user experience or project maintainability.
-    required: true
-- type: textarea
-  attributes:
-    label: Additional context or examples
-    description: |
-      Screenshots? Comparisons? Reference repos?
-    required: false
-- type: checkboxes
-  attributes:
-    label: Are you willing to help implement this?
-    options:
-      - label: "Yes"
-      - label: "No"

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -5,7 +5,7 @@ body:
 - type: checkboxes
   attributes:
     label: Is there an existing issue for this?
-    description: Please search to see if an open or closed issue already exists for the feature you are requesting. 
+    description: Please search to see if an open or closed issue already exists for the feature you are requesting.
     options:
     - label: I have searched the existing open and closed issues
       required: true
@@ -32,21 +32,21 @@ body:
     label: Anything else?
     description: |
       Links? References? Mockups? Anything that will give us more context about the feature you are encountering!
-      
+
       Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in.
   validations:
     required: true
 - type: checkboxes
   attributes:
     label: Am I willing to test this? 🧪
-    description: I rely on the community to test unreleased features. If you are requesting a feature, please be willing to test it within 48h of test request. Otherwise, the feature might be pulled from the code base. 
+    description: I rely on the community to test unreleased features. If you are requesting a feature, please be willing to test it within 48h of test request. Otherwise, the feature might be pulled from the code base.
     options:
     - label: I will do my best to test this feature on the `netlertx-dev` image when requested within 48h and report bugs to help deliver a great user experience for everyone and not to break existing installations.
       required: true
 - type: checkboxes
   attributes:
-    label: Can I help implement this? 👩‍💻👨‍💻 
-    description: The maintainer will provide guidance and help. The implementer will read the PR guidelines https://jokob-sk.github.io/NetAlertX/DEV_ENV_SETUP/
+    label: Can I help implement this? 👩‍💻👨‍💻
+    description: The maintainer will provide guidance and help. The implementer will read the PR guidelines https://docs.netalertx.com/DEV_ENV_SETUP/
     options:
     - label: "Yes"
     - label: "No"

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

@@ -2,17 +2,31 @@ name: Bug Report
 description: 'When submitting an issue enable LOG_LEVEL="trace" and have a look at the docs.'
 labels: ['bug 🐛']
 body:
+- type: dropdown
+  id: installation_type
+  attributes:
+    label: What installation are you running?
+    options:
+      - Production (netalertx) 📦
+      - Dev (netalertx-dev) 👩‍💻
+      - Home Assistant (addon) 🏠
+      - Home Assistant fa (full-access addon) 🏠
+      - Bare-metal (community only support - Check Discord) ❗
+      - Proxmox (community only support - Check Discord) ❗
+      - Unraid (community only support - Check Discord) ❗
+  validations:
+    required: true
 - type: checkboxes
   attributes:
     label: Is there an existing issue for this?
     description: Please search to see if an open or closed issue already exists for the bug you encountered.
     options:
-    - label: I have searched the existing open and closed issues and I checked the docs https://jokob-sk.github.io/NetAlertX/
+    - label: I have searched the existing open and closed issues and I checked the docs https://docs.netalertx.com/
       required: true
 - type: checkboxes
   attributes:
     label: The issue occurs in the following browsers. Select at least 2.
-    description: This step helps me understand if this is a cache or browser-specific issue. 
+    description: This step helps me understand if this is a cache or browser-specific issue.
     options:
     - label: "Firefox"
     - label: "Chrome"
@@ -44,9 +58,9 @@ body:
     required: false
 - type: textarea
   attributes:
-    label: Relevant `app.conf` settings 
+    label: Relevant `app.conf` settings
     description: |
-      Paste relevant `app.conf`settings (remove sensitive info)    
+      Paste relevant `app.conf`settings (remove sensitive info)
     render: python
   validations:
     required: false
@@ -54,22 +68,10 @@ body:
   attributes:
     label: docker-compose.yml
     description: |
-      Paste your `docker-compose.yml`    
+      Paste your `docker-compose.yml`
     render: yaml
   validations:
     required: false
-- type: dropdown
-  id: installation_type
-  attributes:
-    label: What installation are you running?
-    options:
-      - Production (netalertx)
-      - Dev (netalertx-dev)
-      - Home Assistant (addon)
-      - Home Assistant fa (full-access addon)
-      - Bare-metal (community only support - Check Discord)
-  validations:
-    required: true
 - type: checkboxes
   attributes:
     label: Debug or Trace enabled
@@ -82,10 +84,10 @@ body:
     label: Relevant `app.log` section
     value: |
         ```
-          PASTE LOG HERE. Using the triple backticks preserves format. 
+          PASTE LOG HERE. Using the triple backticks preserves format.
         ```
     description: |
-      Logs with debug enabled (https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md) ⚠
+      Logs with debug enabled (https://docs.netalertx.com/DEBUG_TIPS) ⚠
       ***Generally speaking, all bug reports should have logs provided.***
       Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in.
       Additionally, any additional info? Screenshots? References? Anything that will give us more context about the issue you are encountering!
@@ -99,7 +101,7 @@ body:
      You can retrieve the logs from Portainer -> Containers -> your NetAlertX container -> Logs or by running `sudo docker logs netalertx`.
     value: |
         ```
-          PASTE DOCKER LOG HERE. Using the triple backticks preserves format. 
+          PASTE DOCKER LOG HERE. Using the triple backticks preserves format.
         ```
   validations:
     required: true

.github/ISSUE_TEMPLATE/refactor-codequality-request.yml

@@ -1,37 +0,0 @@
-name: Refactor / Code Quality Request ♻️
-description: Suggest improvements to code structure, style, or maintainability.
-labels: ['enhancement ♻️']
-body:
-- type: checkboxes
-  attributes:
-    label: Is there an existing issue for this?
-    description: Please check if a similar request already exists.
-    options:
-      - label: I have searched the existing open and closed issues
-        required: true
-- type: textarea
-  attributes:
-    label: What part of the code needs refactoring or improvement?
-    description: Specify files, modules, or components.
-    required: true
-- type: textarea
-  attributes:
-    label: Describe the proposed changes
-    description: Explain the refactoring or quality improvements you suggest.
-    required: true
-- type: textarea
-  attributes:
-    label: Why is this improvement needed?
-    description: Benefits such as maintainability, readability, performance, or scalability.
-    required: true
-- type: textarea
-  attributes:
-    label: Additional context or examples
-    description: Any relevant links, references, or related issues.
-    required: false
-- type: checkboxes
-  attributes:
-    label: Can you help implement this change?
-    options:
-      - label: Yes
-      - label: No

.github/ISSUE_TEMPLATE/setup-help.yml

@@ -2,21 +2,35 @@ name: Setup help
 description: 'When submitting an issue enable LOG_LEVEL="trace" and re-search first.'
 labels: ['Setup 📥']
 body:
+- type: dropdown
+  id: installation_type
+  attributes:
+    label: What installation are you running?
+    options:
+      - Production (netalertx) 📦
+      - Dev (netalertx-dev) 👩‍💻
+      - Home Assistant (addon) 🏠
+      - Home Assistant fa (full-access addon) 🏠
+      - Bare-metal (community only support - Check Discord) ❗
+      - Proxmox (community only support - Check Discord) ❗
+      - Unraid (community only support - Check Discord) ❗
+  validations:
+    required: true
 - type: checkboxes
   attributes:
     label: Did I research?
     description: Please confirm you checked the usual places before opening a setup support request.
     options:
-    - label: I have searched the docs https://jokob-sk.github.io/NetAlertX/
+    - label: I have searched the docs https://docs.netalertx.com/
       required: true
     - label: I have searched the existing open and closed issues
       required: true
-    - label: I confirm my SCAN_SUBNETS is configured and tested as per https://github.com/jokob-sk/NetAlertX/blob/main/docs/SUBNETS.md
+    - label: I confirm my SCAN_SUBNETS is configured and tested as per https://docs.netalertx.com/SUBNETS
       required: true
 - type: checkboxes
   attributes:
     label: The issue occurs in the following browsers. Select at least 2.
-    description: This step helps me understand if this is a cache or browser-specific issue. 
+    description: This step helps me understand if this is a cache or browser-specific issue.
     options:
     - label: "Firefox"
     - label: "Chrome"
@@ -32,38 +46,26 @@ body:
   attributes:
     label: Relevant settings you changed
     description: |
-      Paste a screenshot or setting values of the settings you changed. 
+      Paste a screenshot or setting values of the settings you changed.
   validations:
     required: false
 - type: textarea
   attributes:
     label: docker-compose.yml
     description: |
-      Paste your `docker-compose.yml`    
+      Paste your `docker-compose.yml`
     render: python
   validations:
     required: false
-- type: dropdown
-  id: installation_type
-  attributes:
-    label: What installation are you running?
-    options:
-      - Production (netalertx)
-      - Dev (netalertx-dev)
-      - Home Assistant (addon)
-      - Home Assistant fa (full-access addon)
-      - Bare-metal (community only support - Check Discord)
-  validations:
-    required: true
 - type: textarea
   attributes:
     label: app.log
     description: |
-      Logs with debug enabled (https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md) ⚠
+      Logs with debug enabled (https://docs.netalertx.com/DEBUG_TIPS) ⚠
       ***Generally speaking, all bug reports should have logs provided.***
       Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in.
       Additionally, any additional info? Screenshots? References? Anything that will give us more context about the issue you are encountering!
-      You can use `tail -100 /app/log/app.log` in the container if you have trouble getting to the log files. 
+      You can use `tail -100 /app/log/app.log` in the container if you have trouble getting to the log files.
   validations:
     required: false
 - type: checkboxes

.github/ISSUE_TEMPLATE/translation-request.yml

@@ -1,36 +0,0 @@
-name: Translation / Localization Request 🌐
-description: Suggest adding or improving translations or localization support.
-labels: ['enhancement 🌐']
-body:
-- type: checkboxes
-  attributes:
-    label: Have you checked for existing translation efforts or related issues?
-    options:
-      - label: I have searched existing open and closed issues
-        required: true
-- type: textarea
-  attributes:
-    label: Language(s) involved
-    description: Specify the language(s) this request pertains to.
-    required: true
-- type: textarea
-  attributes:
-    label: Describe the translation or localization improvement
-    description: Examples include adding new language support, fixing translation errors, or improving formatting.
-    required: true
-- type: textarea
-  attributes:
-    label: Why is this important for the project or users?
-    description: Describe the benefits or target audience.
-    required: false
-- type: textarea
-  attributes:
-    label: Additional context or references
-    description: Link to files, previous translation PRs, or external resources.
-    required: false
-- type: checkboxes
-  attributes:
-    label: Can you help with translation or review?
-    options:
-      - label: Yes
-      - label: No

.github/copilot-instructions.md

@@ -1,14 +1,23 @@
+### 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."
+
+### 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."
+
+---
+
 # 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.
 
-You are expected to be concise, opinionated, and biased toward security and simplicity.
-
 ## 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`
+  - 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`
+  - 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`
@@ -34,16 +43,17 @@ Backend loop phases (see `server/__main__.py` and `server/plugin.py`): `once`, `
 - 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`.
+
 ## 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"}`
 
 ## 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 `logger.mylog(level, [message])`; levels: none/minimal/verbose/debug/trace.
-- Time/MAC/strings: `helper.py` (`timeNowDB`, `normalize_mac`, sanitizers). Validate MACs before DB writes.
+- 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.
 
 ## Dev workflow (devcontainer)
@@ -55,37 +65,25 @@ Backend loop phases (see `server/__main__.py` and `server/plugin.py`): `once`, `
 - 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/app.log`
-	- backend logs: `/tmp/log/stdout.log` and `/tmp/log/stderr.log`
-	- frontend commands logs: `/tmp/log/app_front.log`
-	- php errors: `/tmp/log/app.php_errors.log`
-	- nginx logs: `/tmp/log/nginx-access.log` and `/tmp/log/nginx-error.log`
-
-## Assistant expectations:
-- Be concise, opinionated, and biased toward security and simplicity.
-- Reference concrete files/paths/environmental variables.
-- Use existing helpers/settings.
-- Offer a quick validation step (log line, API hit, or JSON export) for anything you add.
-- Be blunt about risks and when you offer suggestions ensure they're also blunt,
-- Ask for confirmation before making changes that run code or change multiple files.
-- Make statements actionable and specific; propose exact edits.
-- Request confirmation before applying changes that affect more than a single, clearly scoped line or file.
-- Ask the user to debug something for an actionable value if you're unsure.
-- Be sure to offer choices when appropriate.
-- Always understand the intent of the user's request and undo/redo as needed.
-- Above all, use the simplest possible code that meets the need so it can be easily audited and maintained.
-- Always leave logging enabled. If there is a possiblity it will be difficult to debug with current logging, add more logging.
-- 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. As an example if a test is failing use `testFailure` then `runTests`. Never `runTests` first. 
-- Docker tests take an extremely long time to run.  Avoid changes to docker or tests until you've examined the exisiting testFailures and runTests results.
-- Environment tools are designed specifically for your use in this project and running them in this order will give you the best results. 
+  - 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.

.github/workflows/docker_dev.yml

@@ -13,7 +13,7 @@ on:
 jobs:
   docker_dev:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 60
     permissions:
       contents: read
       packages: write
@@ -96,3 +96,5 @@ jobs:
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/docker_prod.yml

@@ -17,7 +17,7 @@ on:
 jobs:
   docker:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 60
     permissions:
       contents: read
       packages: write

.github/workflows/label-issues.yml

@@ -21,7 +21,7 @@ jobs:
 
             let labelsToAdd = [];
 
-            if (lowerBody.includes('bare-metal')) {
+            if (lowerBody.includes('bare-metal') || lowerBody.includes('proxmox')) {
               labelsToAdd.push('bare-metal ❗');
             }
 

.github/workflows/mkdocs.yml

@@ -3,7 +3,10 @@ name: Deploy MkDocs
 on:
   push:
     branches:
-      - main  # Change if your default branch is different
+      - main
+
+permissions:
+  contents: write
 
 jobs:
   deploy:
@@ -19,7 +22,15 @@ jobs:
 
       - name: Install MkDocs
         run: |
-          pip install mkdocs mkdocs-material && pip install mkdocs-github-admonitions-plugin 
+          pip install mkdocs mkdocs-material
+          pip install mkdocs-github-admonitions-plugin
+
+      - name: Build MkDocs
+        run: mkdocs build
+
+      - name: Add CNAME
+        run: |
+          echo "docs.netalertx.com" > site/CNAME
 
       - name: Deploy MkDocs
         run: mkdocs gh-deploy --force

.github/workflows/social_post_on_release.yml

@@ -7,8 +7,8 @@ jobs:
   post-discord:
     runs-on: ubuntu-latest
     steps:
-      - name: Wait for 15 minutes
-        run: sleep 900  # 15 minutes delay
+      - name: Wait for 60 minutes
+        run: sleep 3600  # 60 minutes delay
 
       - name: Post to Discord
         run: |

.gitignore

@@ -44,3 +44,5 @@ front/css/cloud_services.css
 
 docker-compose.yml.ffsb42
 .env.omada.ffsb42
+.venv
+test_mounts/

.vscode/settings.json

@@ -4,10 +4,12 @@
     "python.testing.pytestEnabled": true,
     "python.testing.unittestEnabled": false,
     "python.testing.pytestArgs": [
-        "test"
+      "test"
     ],
-    // Ensure VS Code uses the devcontainer virtualenv
+    // NetAlertX devcontainer uses /opt/venv; this ensures pip/pytest are available for discovery.
     "python.defaultInterpreterPath": "/opt/venv/bin/python",
+    "python.testing.cwd": "${workspaceFolder}",
+    "python.testing.autoTestDiscoverOnSaveEnabled": true,
     // Let the Python extension invoke pytest via the interpreter; avoid hardcoded paths
     // Removed python.testing.pytestPath and legacy pytest.command overrides
     
@@ -16,8 +18,7 @@
       "zsh": {
         "path": "/bin/zsh"
       }
-    }
-    ,
+    },
     // Fallback for older VS Code versions or schema validators that don't accept custom profiles
     "terminal.integrated.shell.linux": "/usr/bin/zsh"
   ,
@@ -29,5 +30,6 @@
   "python.formatting.provider": "black",
   "python.formatting.blackArgs": [
     "--line-length=180"
-  ]
+  ],
+
 }

.vscode/tasks.json

@@ -21,7 +21,6 @@
         "showReuseMessage": false,
         "group": "POSIX Tasks"
       },
-      
       "problemMatcher": [],
       "group": {
         "kind": "build",
@@ -59,6 +58,31 @@
         "color": "terminal.ansiRed"
       }
     },
+    {
+      "label": "[Dev Container] Load Sample Devices",
+      "type": "shell",
+      "command": "./isDevContainer.sh || exit 1; ./load-devices.sh",
+      "detail": "Generates a synthetic device inventory and imports it into the devcontainer database via /devices/import.",
+      "options": {
+        "cwd": "/workspaces/NetAlertX/.devcontainer/scripts",
+        "env": {
+          "CSV_PATH": "/tmp/netalertx-devices.csv"
+        }
+      },
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false,
+        "clear": false,
+        "group": "Devcontainer"
+      },
+      "problemMatcher": [],
+      "icon": {
+        "id": "cloud-upload",
+        "color": "terminal.ansiYellow"
+      }
+    },
     {
       "label": "[Dev Container] Re-Run Startup Script",
       "type": "shell",
@@ -73,7 +97,6 @@
         "panel": "shared",
         "showReuseMessage": false
       },
-
       "problemMatcher": [],
       "icon": {
         "id": "beaker",

CONTRIBUTING.md

@@ -12,7 +12,7 @@ Please use the [GitHub Issue Tracker](https://github.com/jokob-sk/NetAlertX/issu
 - Documentation feedback 📖
 
 Before opening a new issue:
-- 🛑 [Check Common Issues & Debug Tips](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md#common-issues)
+- 🛑 [Check Common Issues & Debug Tips](https://docs.netalertx.com/DEBUG_TIPS#common-issues)
 - 🔍 [Search Closed Issues](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed)
 
 ---
@@ -27,7 +27,7 @@ Please:
 - Follow existing **code style and structure**
 - Provide a clear title and description for your PR
 - If relevant, add or update tests and documentation
-- For plugins, refer to the [Plugin Dev Guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS_DEV.md)
+- For plugins, refer to the [Plugin Dev Guide](https://docs.netalertx.com/PLUGINS_DEV)
 
 ---
 
@@ -47,7 +47,7 @@ By participating, you agree to follow our [Code of Conduct](./CODE_OF_CONDUCT.md
 
 ## 📬 Contact
 
-If you have more in-depth questions or want to discuss contributing in other ways, feel free to reach out at:  
+If you have more in-depth questions or want to discuss contributing in other ways, feel free to reach out at:
 📧 [jokob@duck.com](mailto:jokob@duck.com?subject=NetAlertX%20Contribution)
 
 We appreciate every contribution, big or small! 💙

Dockerfile

@@ -26,13 +26,25 @@ ENV PATH="/opt/venv/bin:$PATH"
 
 # Install build dependencies
 COPY requirements.txt /tmp/requirements.txt
-RUN apk add --no-cache bash shadow python3 python3-dev gcc musl-dev libffi-dev openssl-dev git \
+# hadolint ignore=DL3018
+RUN apk add --no-cache \
+        bash \
+        shadow \
+        python3 \
+        python3-dev \
+        gcc \
+        musl-dev \
+        libffi-dev \
+        openssl-dev \
+        git \
+        rust \
+        cargo \
     && python -m venv /opt/venv
 
-# Create virtual environment owned by root, but readable by everyone else. This makes it easy to copy
-# into hardened stage without worrying about permissions and keeps image size small. Keeping the commands
-# together makes for a slightly smaller image size.
-RUN pip install --no-cache-dir -r /tmp/requirements.txt && \
+# Upgrade pip/wheel/setuptools and install Python packages
+# hadolint ignore=DL3013, DL3042
+RUN python -m pip install --upgrade pip setuptools wheel && \
+    pip install --prefer-binary --no-cache-dir -r /tmp/requirements.txt && \
     chmod -R u-rwx,g-rwx /opt
 
 # second stage is the main runtime stage with just the minimum required to run the application
@@ -40,6 +52,12 @@ RUN pip install --no-cache-dir -r /tmp/requirements.txt && \
 FROM alpine:3.22 AS runner
 
 ARG INSTALL_DIR=/app
+# Runtime service account (override at build; container user can still be overridden at run time)
+ARG NETALERTX_UID=20211
+ARG NETALERTX_GID=20211
+# Read-only lock owner (separate from service account to avoid UID/GID collisions)
+ARG READONLY_UID=20212
+ARG READONLY_GID=20212
 
 # NetAlertX app directories
 ENV NETALERTX_APP=${INSTALL_DIR}
@@ -113,14 +131,14 @@ ENV NETALERTX_USER=netalertx NETALERTX_GROUP=netalertx
 ENV LANG=C.UTF-8
 
 
-RUN apk add --no-cache bash mtr libbsd zip lsblk tzdata curl arp-scan iproute2 iproute2-ss nmap \
+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 && \
+    nginx supercronic shadow su-exec && \
     rm -Rf /var/cache/apk/*  && \
     rm -Rf /etc/nginx && \
-    addgroup -g 20211 ${NETALERTX_GROUP} && \
-    adduser -u 20211 -D -h ${NETALERTX_APP} -G ${NETALERTX_GROUP} ${NETALERTX_USER} && \
+    addgroup -g ${NETALERTX_GID} ${NETALERTX_GROUP} && \
+    adduser -u ${NETALERTX_UID} -D -h ${NETALERTX_APP} -G ${NETALERTX_GROUP} ${NETALERTX_USER} && \
     apk del shadow
 
 
@@ -140,22 +158,22 @@ RUN install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 700 ${READ_WRITE_FO
 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
-COPY --from=builder --chown=20212:20212 ${VIRTUAL_ENV} ${VIRTUAL_ENV}
+# Copy the virtualenv from the builder stage (owned by readonly lock owner)
+COPY --from=builder --chown=${READONLY_UID}:${READONLY_GID} ${VIRTUAL_ENV} ${VIRTUAL_ENV}
 
 
 # Initialize each service with the dockerfiles/init-*.sh scripts, once.
 # This is done after the copy of the venv to ensure the venv is in place
 # 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 \
         if [ ! -f "${NETALERTX_APP}/${vfile}" ]; then \
             echo "DEVELOPMENT 00000000" > "${NETALERTX_APP}/${vfile}"; \
         fi; \
-        chown 20212:20212 "${NETALERTX_APP}/${vfile}"; \
+        chown ${READONLY_UID}:${READONLY_GID} "${NETALERTX_APP}/${vfile}"; \
     done && \
     apk add --no-cache libcap && \
-    setcap cap_net_raw+ep /bin/busybox && \
     setcap cap_net_raw,cap_net_admin+eip /usr/bin/nmap && \
     setcap cap_net_raw,cap_net_admin+eip /usr/bin/arp-scan && \
     setcap cap_net_raw,cap_net_admin,cap_net_bind_service+eip /usr/bin/nbtscan && \
@@ -170,13 +188,19 @@ RUN for vfile in .VERSION .VERSION_PREV; do \
     date +%s > "${NETALERTX_FRONT}/buildtimestamp.txt"
 
 
-ENTRYPOINT ["/bin/sh","/entrypoint.sh"]
+ENTRYPOINT ["/bin/bash","/entrypoint.sh"]
 
 # Final hardened stage to improve security by setting least possible permissions and removing sudo access.
 # When complete, if the image is compromised, there's not much that can be done with it.
 # This stage is separate from Runner stage so that devcontainer can use the Runner stage.
 FROM runner AS hardened
 
+# Re-declare UID/GID args for this stage
+ARG NETALERTX_UID=20211
+ARG NETALERTX_GID=20211
+ARG READONLY_UID=20212
+ARG READONLY_GID=20212
+
 ENV UMASK=0077
 
 # Create readonly user and group with no shell access.
@@ -184,8 +208,8 @@ ENV UMASK=0077
 # AI may claim this is stupid, but it's actually least possible permissions as
 # read-only user cannot login, cannot sudo, has no write permission, and cannot even
 # read the files it owns. The read-only user is ownership-as-a-lock hardening pattern.
-RUN addgroup -g 20212 "${READ_ONLY_GROUP}" && \
-    adduser -u 20212 -G "${READ_ONLY_GROUP}" -D -h /app "${READ_ONLY_USER}"
+RUN addgroup -g ${READONLY_GID} "${READ_ONLY_GROUP}" && \
+    adduser -u ${READONLY_UID} -G "${READ_ONLY_GROUP}" -D -h /app "${READ_ONLY_USER}"
 
 
 # reduce permissions to minimum necessary for all NetAlertX files and folders
@@ -196,24 +220,27 @@ RUN addgroup -g 20212 "${READ_ONLY_GROUP}" && \
 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 700 ${READ_WRITE_FOLDERS} && \
-    chown -R ${NETALERTX_USER}:${NETALERTX_GROUP} ${READ_WRITE_FOLDERS} && \
-    chmod -R 600 ${READ_WRITE_FOLDERS} && \
-    find ${READ_WRITE_FOLDERS} -type d -exec chmod 700 {} + && \
-    chown ${READ_ONLY_USER}:${READ_ONLY_GROUP} /entrypoint.sh /opt /opt/venv && \
-    chmod 005 /entrypoint.sh ${SYSTEM_SERVICES}/*.sh ${SYSTEM_SERVICES_SCRIPTS}/* ${ENTRYPOINT_CHECKS}/* /app /opt /opt/venv && \
-    for dir in ${READ_WRITE_FOLDERS}; do \
-        install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 700 "$dir"; \
-    done && \
+    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 /opt /opt/venv && \
+    chmod 005 /entrypoint.sh /root-entrypoint.sh ${SYSTEM_SERVICES}/*.sh ${SYSTEM_SERVICES_SCRIPTS}/* ${ENTRYPOINT_CHECKS}/* /app /opt /opt/venv && \
+    # Do not bake first-run artifacts into the image. If present, Docker volume copy-up
+    # will persist restrictive ownership/modes into fresh named volumes, breaking
+    # arbitrary non-root UID/GID runs.
+    rm -f \
+      "${NETALERTX_CONFIG}/app.conf" \
+      "${NETALERTX_DB_FILE}" \
+      "${NETALERTX_DB_FILE}-shm" \
+      "${NETALERTX_DB_FILE}-wal" || true && \
     apk del apk-tools && \
     rm -Rf /var /etc/sudoers.d/* /etc/shadow /etc/gshadow /etc/sudoers \
     /lib/apk /lib/firmware /lib/modules-load.d /lib/sysctl.d /mnt /home/ /root \
     /srv /media && \
-    sed -i "/^\(${READ_ONLY_USER}\|${NETALERTX_USER}\):/!d" /etc/passwd && \
-    sed -i "/^\(${READ_ONLY_GROUP}\|${NETALERTX_GROUP}\):/!d" /etc/group && \
+    # Preserve root and system identities so hardened entrypoint never needs to patch /etc/passwd or /etc/group at runtime.
     printf '#!/bin/sh\n"$@"\n' > /usr/bin/sudo && chmod +x /usr/bin/sudo
+USER "0"
 
-USER netalertx
+# Call root-entrypoint.sh which drops priviliges to run entrypoint.sh.
+ENTRYPOINT ["/root-entrypoint.sh"]
 
 HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
     CMD /services/healthcheck.sh

Dockerfile.debian

@@ -4,7 +4,7 @@
 # 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 
+# The default Dockerfile/docker-compose image contains the following security improvements
 # over the Debian image:
 # - read-only filesystem
 # - no sudo access
@@ -25,7 +25,7 @@
 # - minimal base image (Alpine Linux)
 # - minimal python environment (venv, no pip)
 # - minimal stripped web server
-# - minimal stripped php environment 
+# - 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)
@@ -36,8 +36,8 @@
 # - 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 
+# 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.
 
@@ -92,7 +92,7 @@ ENV PHP_FPM_CONFIG_FILE=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.conf
 
 #Python environment
 ENV PYTHONPATH=${NETALERTX_SERVER}
-ENV PYTHONUNBUFFERED=1 
+ENV PYTHONUNBUFFERED=1
 ENV VIRTUAL_ENV=/opt/venv
 ENV VIRTUAL_ENV_BIN=/opt/venv/bin
 ENV PATH="${VIRTUAL_ENV}/bin:${PATH}:/services"
@@ -107,9 +107,9 @@ ENV NETALERTX_DEBUG=0
 
 #Container environment
 ENV ENVIRONMENT=debian
-ENV USER=netalertx 
+ENV USER=netalertx
 ENV USER_ID=1000
-ENV USER_GID=1000 
+ENV USER_GID=1000
 
 # 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
@@ -127,16 +127,16 @@ RUN groupadd --gid "${USER_GID}" "${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/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 ❗ 
+# ❗ IMPORTANT - if you modify this file modify the /install/install_dependecies.debian.sh file as well ❗
 # hadolint ignore=DL3008,DL3027
 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 python3-pip zip git systemctl usbutils traceroute nbtscan openrc \
+    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/*
 

README.md

@@ -6,7 +6,7 @@
 
 # NetAlertX - Network, presence scanner and alert 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://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md#readme) with auto-generated UI and in-build notification system. Build out and easily maintain your network source of truth (NSoT) and device inventory.
+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.
 
 ## 📋 Table of Contents
 
@@ -34,7 +34,7 @@ Get visibility of what's going on on your WIFI/LAN network and enable presence d
 ## 🚀 Quick Start
 
 > [!WARNING]
-> ⚠️ **Important:** The docker-compose has recently changed. Carefully read the [Migration guide](https://jokob-sk.github.io/NetAlertX/MIGRATION/?h=migrat#12-migration-from-netalertx-v25524) for detailed instructions.
+> ⚠️ **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.
 
 Start NetAlertX in seconds with Docker:
 
@@ -60,14 +60,14 @@ docker compose up --force-recreate --build
 # To customize: edit docker-compose.yaml and run that last command again
 ```
 
-Need help configuring it? Check the [usage guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/README.md) or [full documentation](https://jokob-sk.github.io/NetAlertX/).
+Need help configuring it? Check the [usage guide](https://docs.netalertx.com/README) or [full documentation](https://docs.netalertx.com/).
 
 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)
 
 
-| [📑 Docker guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_INSTALLATION.md) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://jokob-sk.github.io/NetAlertX/) | [🔌 Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
+| [📑 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)
 |----------------------| ----------------------|  ----------------------| ----------------------| ----------------------|
 
 ![showcase][showcase]
@@ -88,7 +88,7 @@ For other install methods, check the [installation docs](#-documentation)
 
 ### 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://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md#readme) docs for a full list of avaliable plugins.
+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.
 
 ### Notification gateways
 
@@ -96,12 +96,12 @@ Send notifications to more than 80+ services, including Telegram via [Apprise](h
 
 ### Integrations and Plugins
 
-Feed your data and device changes into [Home Assistant](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HOME_ASSISTANT.md), read [API endpoints](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md), or use [Webhooks](https://github.com/jokob-sk/NetAlertX/blob/main/docs/WEBHOOK_N8N.md) to setup custom automation flows. You can also
-build your own scanners with the [Plugin system](https://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md#readme) in as little as [15 minutes](https://www.youtube.com/watch?v=cdbxlwiWhv8).
+Feed your data and device changes into [Home Assistant](https://docs.netalertx.com/HOME_ASSISTANT), read [API endpoints](https://docs.netalertx.com/API), or use [Webhooks](https://docs.netalertx.com/WEBHOOK_N8N) to setup custom automation flows. You can also
+build your own scanners with the [Plugin system](https://docs.netalertx.com/PLUGINS#readme) in as little as [15 minutes](https://www.youtube.com/watch?v=cdbxlwiWhv8).
 
 ### Workflows
 
-The [workflows module](https://github.com/jokob-sk/NetAlertX/blob/main/docs/WORKFLOWS.md) 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) 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.
 
 
 ## 📚 Documentation
@@ -109,15 +109,15 @@ The [workflows module](https://github.com/jokob-sk/NetAlertX/blob/main/docs/WORK
 
 Supported browsers: Chrome, Firefox
 
-- [[Installation] Docker](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_INSTALLATION.md)
+- [[Installation] Docker](https://docs.netalertx.com/DOCKER_INSTALLATION)
 - [[Installation] Home Assistant](https://github.com/alexbelgium/hassio-addons/tree/master/netalertx)
-- [[Installation] Bare metal](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md)
+- [[Installation] Bare metal](https://docs.netalertx.com/HW_INSTALL)
 - [[Installation] Unraid App](https://unraid.net/community/apps)
-- [[Setup] Usage and Configuration](https://github.com/jokob-sk/NetAlertX/blob/main/docs/README.md)
-- [[Development] API docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md)
-- [[Development] Custom Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS_DEV.md)
+- [[Setup] Usage and Configuration](https://docs.netalertx.com/README)
+- [[Development] API docs](https://docs.netalertx.com/API)
+- [[Development] Custom Plugins](https://docs.netalertx.com/PLUGINS_DEV)
 
-...or explore all the [documentation here](https://jokob-sk.github.io/NetAlertX/).
+...or explore all the [documentation here](https://docs.netalertx.com/).
 
 ## 🔐 Security & Privacy
 
@@ -143,7 +143,7 @@ A: Yes, but some scanners (e.g. ARP) work best on Ethernet. For Wi-Fi, try SNMP,
 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://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md).
+A: Yes! You can install it bare-metal. See 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.
@@ -151,12 +151,12 @@ A: In the `/data/config` and `/data/db` folders. Back up these folders regularly
 
 ## 🐞 Known Issues
 
-- Some scanners (e.g. ARP) may not detect devices on different subnets. See the [Remote networks guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/REMOTE_NETWORKS.md) for workarounds.
+- 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://jokob-sk.github.io/NetAlertX/).
+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/).
 
 ## 📃 Everything else
 <!--- --------------------------------------------------------------------- --->

back/app.conf

@@ -33,7 +33,7 @@ NSLOOKUP_RUN='before_name_updates'
 AVAHISCAN_RUN='before_name_updates'
 NBTSCAN_RUN='before_name_updates'
 
-# Email 
+# Email
 #-------------------------------------
 # (add SMTP to LOADED_PLUGINS to load)
 #-------------------------------------
@@ -48,20 +48,19 @@ SMTP_PASS='password'
 SMTP_SKIP_TLS=False
 
 
-# Webhook 
+# Webhook
 #-------------------------------------
 # (add WEBHOOK to LOADED_PLUGINS to load)
 #-------------------------------------
 WEBHOOK_RUN='disabled'  # use 'on_notification' to enable
 WEBHOOK_URL='http://n8n.local:5555/webhook-test/aaaaaaaa-aaaa-aaaa-aaaaa-aaaaaaaaaaaa'
-WEBHOOK_PAYLOAD='json'                 # webhook payload data format for the "body > attachements > text" attribute 
-                                       # in https://github.com/jokob-sk/NetAlertX/blob/main/docs/webhook_json_sample.json 
+WEBHOOK_PAYLOAD='json'                 # webhook payload data format for the "body > attachements > text" attribute
                                        #   supported values: 'json', 'html' or 'text'
                                        #   e.g.: for discord use 'html'
 WEBHOOK_REQUEST_METHOD='GET'
 
 
-# Apprise 
+# Apprise
 #-------------------------------------
 # (add APPRISE to LOADED_PLUGINS to load)
 #-------------------------------------
@@ -71,7 +70,7 @@ APPRISE_URL='mailto://smtp-relay.sendinblue.com:587?from=user@gmail.com&name=app
 
 
 # NTFY
-#------------------------------------- 
+#-------------------------------------
 # (add NTFY to LOADED_PLUGINS to load)
 #-------------------------------------
 NTFY_RUN='disabled'  # use 'on_notification' to enable
@@ -81,7 +80,7 @@ NTFY_USER='user'
 NTFY_PASSWORD='passw0rd'
 
 
-# PUSHSAFER 
+# PUSHSAFER
 #-------------------------------------
 # (add PUSHSAFER to LOADED_PLUGINS to load)
 #-------------------------------------
@@ -89,7 +88,7 @@ PUSHSAFER_RUN='disabled'  # use 'on_notification' to enable
 PUSHSAFER_TOKEN='ApiKey'
 
 
-# MQTT 
+# MQTT
 #-------------------------------------
 # (add MQTT to LOADED_PLUGINS to load)
 #-------------------------------------

docker-compose.yml

@@ -1,20 +1,24 @@
 services:
   netalertx:
-  #use an environmental variable to set host networking mode if needed
-    network_mode: ${NETALERTX_NETWORK_MODE:-host}   # Use host networking for ARP scanning and other services
+    network_mode: host   # Use host networking for ARP scanning and other services
     build:
       context: .                                    # Build context is the current directory
       dockerfile: Dockerfile                        # Specify the Dockerfile to use
     image: netalertx:latest
     container_name: netalertx                       # The name when you docker contiainer ls
     read_only: true                                 # Make the container filesystem read-only
+    
+    # It is most secure to start with user 20211, but then we lose provisioning capabilities.
+    # user: "${NETALERTX_UID:-20211}:${NETALERTX_GID:-20211}"
     cap_drop:                                       # Drop all capabilities for enhanced security
       - ALL
     cap_add:                                        # Add only the necessary capabilities
-      - NET_ADMIN                                   # Required for ARP scanning
-      - NET_RAW                                     # Required for raw socket operations
-      - NET_BIND_SERVICE                            # Required to bind to privileged ports (nbtscan)
-
+      - NET_ADMIN                                   # Required for scanning with arp-scan, nmap, nbtscan, traceroute, and zero-conf
+      - NET_RAW                                     # Required for raw socket operations with arp-scan, nmap, nbtscan, traceroute and zero-conf
+      - NET_BIND_SERVICE                            # Required to bind to privileged ports with 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 storage
@@ -35,22 +39,23 @@ services:
         target: /etc/localtime
         read_only: true
 
-  # Use a custom Enterprise-configured nginx config for ldap or other settings
-  # - /custom-enterprise.conf:/tmp/nginx/active-config/netalertx.conf:ro
+    # Use a custom Enterprise-configured nginx config for ldap or other settings
+    # - /custom-enterprise.conf:/tmp/nginx/active-config/netalertx.conf:ro
 
-      # Test your plugin on the production container
-      # - /path/on/host:/app/front/plugins/custom
+    # Test your plugin on the production container
+    # - /path/on/host:/app/front/plugins/custom
 
-  # Retain logs - comment out tmpfs /tmp/log if you want to retain logs between container restarts
-  # - /path/on/host/log:/tmp/log
+    # Retain logs - comment out tmpfs /tmp/log if you want to retain logs between container restarts
+    # - /path/on/host/log:/tmp/log
 
     # tmpfs mounts for writable directories in a read-only container and improve system performance
     # All writes now live under /tmp/* subdirectories which are created dynamically by entrypoint.d scripts
-    # uid=20211 and gid=20211 is the netalertx user inside the container
-    # mode=1700 gives rwx------ permissions to the netalertx user only
+    # mode=1700 gives rwx------ permissions; ownership is set by /root-entrypoint.sh
     tmpfs:
-      - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+      - "/tmp:mode=1700,uid=0,gid=0,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
     environment:
+      PUID: ${NETALERTX_UID:-20211}                             # Runtime UID after priming (Synology/no-copy-up safe)
+      PGID: ${NETALERTX_GID:-20211}                             # Runtime GID after priming (Synology/no-copy-up safe)
       LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0}                      # Listen for connections on all interfaces
       PORT: ${PORT:-20211}                                      # Application port
       GRAPHQL_PORT: ${GRAPHQL_PORT:-20212}                      # GraphQL API port
@@ -63,7 +68,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

docker_build.log

@@ -1,534 +1,74 @@
 #0 building with "default" instance using docker driver
 
 #1 [internal] load build definition from Dockerfile
-#1 transferring dockerfile: 5.29kB done
+#1 DONE 0.0s
+
+#1 [internal] load build definition from Dockerfile
+#1 transferring dockerfile: 11.45kB done
 #1 DONE 0.1s
 
-#2 [auth] library/alpine:pull token for registry-1.docker.io
+#2 [internal] load metadata for docker.io/library/alpine:3.22
 #2 DONE 0.0s
 
-#3 [internal] load metadata for docker.io/library/alpine:3.22
-#3 DONE 0.4s
+#3 [internal] load .dockerignore
+#3 transferring context:
+#3 transferring context: 222B done
+#3 DONE 0.1s
 
-#4 [internal] load .dockerignore
-#4 transferring context: 216B done
-#4 DONE 0.1s
+#4 [builder 1/4] FROM docker.io/library/alpine:3.22
+#4 DONE 0.0s
 
-#5 [builder  1/15] FROM docker.io/library/alpine:3.22@sha256:4bcff63911fcb4448bd4fdacec207030997caf25e9bea4045fa6c8c44de311d1
-#5 CACHED
+#5 [internal] load build context
+#5 transferring context: 46.63kB 0.1s done
+#5 DONE 0.2s
 
-#6 [internal] load build context
-#6 transferring context: 36.76kB 0.0s done
-#6 DONE 0.1s
+#6 [builder 3/4] RUN apk add --no-cache         bash         shadow         python3         python3-dev         gcc         musl-dev         libffi-dev         openssl-dev         git         rust         cargo     && python -m venv /opt/venv
+#6 CACHED
 
-#7 [builder  2/15] RUN apk add --no-cache bash shadow python3 python3-dev gcc musl-dev libffi-dev openssl-dev git     && python -m venv /opt/venv
-#7 0.443 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/main/x86_64/APKINDEX.tar.gz
-#7 0.688 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/community/x86_64/APKINDEX.tar.gz
-#7 1.107 (1/52) Upgrading libcrypto3 (3.5.1-r0 -> 3.5.3-r0)
-#7 1.358 (2/52) Upgrading libssl3 (3.5.1-r0 -> 3.5.3-r0)
-#7 1.400 (3/52) Installing ncurses-terminfo-base (6.5_p20250503-r0)
-#7 1.413 (4/52) Installing libncursesw (6.5_p20250503-r0)
-#7 1.444 (5/52) Installing readline (8.2.13-r1)
-#7 1.471 (6/52) Installing bash (5.2.37-r0)
-#7 1.570 Executing bash-5.2.37-r0.post-install
-#7 1.593 (7/52) Installing libgcc (14.2.0-r6)
-#7 1.605 (8/52) Installing jansson (2.14.1-r0)
-#7 1.613 (9/52) Installing libstdc++ (14.2.0-r6)
-#7 1.705 (10/52) Installing zstd-libs (1.5.7-r0)
-#7 1.751 (11/52) Installing binutils (2.44-r3)
-#7 2.041 (12/52) Installing libgomp (14.2.0-r6)
-#7 2.064 (13/52) Installing libatomic (14.2.0-r6)
-#7 2.071 (14/52) Installing gmp (6.3.0-r3)
-#7 2.097 (15/52) Installing isl26 (0.26-r1)
-#7 2.183 (16/52) Installing mpfr4 (4.2.1_p1-r0)
-#7 2.219 (17/52) Installing mpc1 (1.3.1-r1)
-#7 2.231 (18/52) Installing gcc (14.2.0-r6)
-#7 6.782 (19/52) Installing brotli-libs (1.1.0-r2)
-#7 6.828 (20/52) Installing c-ares (1.34.5-r0)
-#7 6.846 (21/52) Installing libunistring (1.3-r0)
-#7 6.919 (22/52) Installing libidn2 (2.3.7-r0)
-#7 6.937 (23/52) Installing nghttp2-libs (1.65.0-r0)
-#7 6.950 (24/52) Installing libpsl (0.21.5-r3)
-#7 6.960 (25/52) Installing libcurl (8.14.1-r1)
-#7 7.015 (26/52) Installing libexpat (2.7.2-r0)
-#7 7.029 (27/52) Installing pcre2 (10.43-r1)
-#7 7.069 (28/52) Installing git (2.49.1-r0)
-#7 7.397 (29/52) Installing git-init-template (2.49.1-r0)
-#7 7.404 (30/52) Installing linux-headers (6.14.2-r0)
-#7 7.572 (31/52) Installing libffi (3.4.8-r0)
-#7 7.578 (32/52) Installing pkgconf (2.4.3-r0)
-#7 7.593 (33/52) Installing libffi-dev (3.4.8-r0)
-#7 7.607 (34/52) Installing musl-dev (1.2.5-r10)
-#7 7.961 (35/52) Installing openssl-dev (3.5.3-r0)
-#7 8.021 (36/52) Installing libbz2 (1.0.8-r6)
-#7 8.045 (37/52) Installing gdbm (1.24-r0)
-#7 8.055 (38/52) Installing xz-libs (5.8.1-r0)
-#7 8.071 (39/52) Installing mpdecimal (4.0.1-r0)
-#7 8.090 (40/52) Installing libpanelw (6.5_p20250503-r0)
-#7 8.098 (41/52) Installing sqlite-libs (3.49.2-r1)
-#7 8.185 (42/52) Installing python3 (3.12.11-r0)
-#7 8.904 (43/52) Installing python3-pycache-pyc0 (3.12.11-r0)
-#7 9.292 (44/52) Installing pyc (3.12.11-r0)
-#7 9.292 (45/52) Installing python3-pyc (3.12.11-r0)
-#7 9.292 (46/52) Installing python3-dev (3.12.11-r0)
-#7 10.71 (47/52) Installing libmd (1.1.0-r0)
-#7 10.72 (48/52) Installing libbsd (0.12.2-r0)
-#7 10.73 (49/52) Installing skalibs-libs (2.14.4.0-r0)
-#7 10.75 (50/52) Installing utmps-libs (0.1.3.1-r0)
-#7 10.76 (51/52) Installing linux-pam (1.7.0-r4)
-#7 10.82 (52/52) Installing shadow (4.17.3-r0)
-#7 10.88 Executing busybox-1.37.0-r18.trigger
-#7 10.90 OK: 274 MiB in 66 packages
-#7 DONE 14.4s
+#7 [runner  6/11] COPY --chown=netalertx:netalertx --chmod=755 server /app/server
+#7 CACHED
 
-#8 [builder  3/15] RUN mkdir -p /app
-#8 DONE 0.5s
+#8 [runner  5/11] COPY --chown=netalertx:netalertx --chmod=755 front /app/front
+#8 CACHED
 
-#9 [builder  4/15] COPY api /app/api
-#9 DONE 0.3s
+#9 [runner  2/11] RUN apk add --no-cache bash mtr libbsd zip lsblk tzdata curl arp-scan iproute2 iproute2-ss nmap     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 &&     rm -Rf /var/cache/apk/*  &&     rm -Rf /etc/nginx &&     addgroup -g 20211 netalertx &&     adduser -u 20211 -D -h /app -G netalertx netalertx &&     apk del shadow
+#9 CACHED
 
-#10 [builder  5/15] COPY back /app/back
-#10 DONE 0.3s
+#10 [runner  4/11] COPY --chown=netalertx:netalertx --chmod=755 back /app/back
+#10 CACHED
 
-#11 [builder  6/15] COPY config /app/config
-#11 DONE 0.3s
+#11 [builder 2/4] COPY requirements.txt /tmp/requirements.txt
+#11 CACHED
 
-#12 [builder  7/15] COPY db /app/db
-#12 DONE 0.3s
+#12 [runner  7/11] RUN install -d -o netalertx -g netalertx -m 700 /data /data/config /data/db /tmp/api                        /tmp/log /tmp/log/plugins /tmp/run                        /tmp/run/tmp /tmp/run/logs                        /tmp/nginx/active-config &&     sh -c "find /app -type f \( -name '*.sh' -o -name 'speedtest-cli' \)     -exec chmod 750 {} \;"
+#12 CACHED
 
-#13 [builder  8/15] COPY dockerfiles /app/dockerfiles
-#13 DONE 0.3s
+#13 [hardened 1/2] RUN addgroup -g 20212 "readonly" &&     adduser -u 20212 -G "readonly" -D -h /app "readonly"
+#13 CACHED
 
-#14 [builder  9/15] COPY front /app/front
-#14 DONE 0.4s
+#14 [runner  8/11] COPY --chown=netalertx:netalertx .[V]ERSION /app/.VERSION
+#14 CACHED
 
-#15 [builder 10/15] COPY server /app/server
-#15 DONE 0.3s
+#15 [runner  9/11] COPY --chown=netalertx:netalertx .[V]ERSION /app/.VERSION_PREV
+#15 CACHED
 
-#16 [builder 11/15] COPY install/crontab /etc/crontabs/root
-#16 DONE 0.3s
+#16 [runner 11/11] RUN for vfile in .VERSION .VERSION_PREV; do         if [ ! -f "/app/${vfile}" ]; then             echo "DEVELOPMENT 00000000" > "/app/${vfile}";         fi;         chown 20212:20212 "/app/${vfile}";     done &&     apk add --no-cache libcap &&     setcap cap_net_raw,cap_net_admin+eip /usr/bin/nmap &&     setcap cap_net_raw,cap_net_admin+eip /usr/bin/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 &&     setcap cap_net_raw,cap_net_admin+eip "$(readlink -f /opt/venv/bin/python)" &&     /bin/sh /build/init-nginx.sh &&     /bin/sh /build/init-php-fpm.sh &&     /bin/sh /build/init-cron.sh &&     /bin/sh /build/init-backend.sh &&     rm -rf /build &&     apk del libcap &&     date +%s > "/app/front/buildtimestamp.txt"
+#16 CACHED
 
-#17 [builder 12/15] COPY dockerfiles/start* /start*.sh
-#17 DONE 0.3s
+#17 [builder 4/4] RUN python -m pip install --no-cache-dir --upgrade pip setuptools wheel &&     pip install --prefer-binary --no-cache-dir -r /tmp/requirements.txt &&     chmod -R u-rwx,g-rwx /opt
+#17 CACHED
 
-#18 [builder 13/15] RUN pip install openwrt-luci-rpc asusrouter asyncio aiohttp graphene flask flask-cors unifi-sm-api tplink-omada-client wakeonlan pycryptodome requests paho-mqtt scapy cron-converter pytz json2table dhcp-leases pyunifi speedtest-cli chardet python-nmap dnspython librouteros yattag git+https://github.com/foreign-sub/aiofreepybox.git
-#18 0.737 Collecting git+https://github.com/foreign-sub/aiofreepybox.git
-#18 0.737   Cloning https://github.com/foreign-sub/aiofreepybox.git to /tmp/pip-req-build-waf5_npl
-#18 0.738   Running command git clone --filter=blob:none --quiet https://github.com/foreign-sub/aiofreepybox.git /tmp/pip-req-build-waf5_npl
-#18 1.617   Resolved https://github.com/foreign-sub/aiofreepybox.git to commit 4ee18ea0f3e76edc839c48eb8df1da59c1baee3d
-#18 1.620   Installing build dependencies: started
-#18 3.337   Installing build dependencies: finished with status 'done'
-#18 3.337   Getting requirements to build wheel: started
-#18 3.491   Getting requirements to build wheel: finished with status 'done'
-#18 3.492   Preparing metadata (pyproject.toml): started
-#18 3.650   Preparing metadata (pyproject.toml): finished with status 'done'
-#18 3.724 Collecting openwrt-luci-rpc
-#18 3.753   Downloading openwrt_luci_rpc-1.1.17-py2.py3-none-any.whl.metadata (4.9 kB)
-#18 3.892 Collecting asusrouter
-#18 3.900   Downloading asusrouter-1.21.0-py3-none-any.whl.metadata (33 kB)
-#18 3.999 Collecting asyncio
-#18 4.007   Downloading asyncio-4.0.0-py3-none-any.whl.metadata (994 bytes)
-#18 4.576 Collecting aiohttp
-#18 4.582   Downloading aiohttp-3.12.15-cp312-cp312-musllinux_1_2_x86_64.whl.metadata (7.7 kB)
-#18 4.729 Collecting graphene
-#18 4.735   Downloading graphene-3.4.3-py2.py3-none-any.whl.metadata (6.9 kB)
-#18 4.858 Collecting flask
-#18 4.866   Downloading flask-3.1.2-py3-none-any.whl.metadata (3.2 kB)
-#18 4.963 Collecting flask-cors
-#18 4.972   Downloading flask_cors-6.0.1-py3-none-any.whl.metadata (5.3 kB)
-#18 5.055 Collecting unifi-sm-api
-#18 5.065   Downloading unifi_sm_api-0.2.1-py3-none-any.whl.metadata (2.3 kB)
-#18 5.155 Collecting tplink-omada-client
-#18 5.166   Downloading tplink_omada_client-1.4.4-py3-none-any.whl.metadata (3.5 kB)
-#18 5.262 Collecting wakeonlan
-#18 5.274   Downloading wakeonlan-3.1.0-py3-none-any.whl.metadata (4.3 kB)
-#18 5.500 Collecting pycryptodome
-#18 5.505   Downloading pycryptodome-3.23.0-cp37-abi3-musllinux_1_2_x86_64.whl.metadata (3.4 kB)
-#18 5.653 Collecting requests
-#18 5.660   Downloading requests-2.32.5-py3-none-any.whl.metadata (4.9 kB)
-#18 5.764 Collecting paho-mqtt
-#18 5.775   Downloading paho_mqtt-2.1.0-py3-none-any.whl.metadata (23 kB)
-#18 5.890 Collecting scapy
-#18 5.902   Downloading scapy-2.6.1-py3-none-any.whl.metadata (5.6 kB)
-#18 6.002 Collecting cron-converter
-#18 6.013   Downloading cron_converter-1.2.2-py3-none-any.whl.metadata (8.1 kB)
-#18 6.187 Collecting pytz
-#18 6.193   Downloading pytz-2025.2-py2.py3-none-any.whl.metadata (22 kB)
-#18 6.285 Collecting json2table
-#18 6.294   Downloading json2table-1.1.5-py2.py3-none-any.whl.metadata (6.0 kB)
-#18 6.381 Collecting dhcp-leases
-#18 6.387   Downloading dhcp_leases-0.1.6-py3-none-any.whl.metadata (5.9 kB)
-#18 6.461 Collecting pyunifi
-#18 6.471   Downloading pyunifi-2.21-py3-none-any.whl.metadata (274 bytes)
-#18 6.582 Collecting speedtest-cli
-#18 6.596   Downloading speedtest_cli-2.1.3-py2.py3-none-any.whl.metadata (6.8 kB)
-#18 6.767 Collecting chardet
-#18 6.780   Downloading chardet-5.2.0-py3-none-any.whl.metadata (3.4 kB)
-#18 6.878 Collecting python-nmap
-#18 6.886   Downloading python-nmap-0.7.1.tar.gz (44 kB)
-#18 6.937   Installing build dependencies: started
-#18 8.245   Installing build dependencies: finished with status 'done'
-#18 8.246   Getting requirements to build wheel: started
-#18 8.411   Getting requirements to build wheel: finished with status 'done'
-#18 8.412   Preparing metadata (pyproject.toml): started
-#18 8.575   Preparing metadata (pyproject.toml): finished with status 'done'
-#18 8.648 Collecting dnspython
-#18 8.654   Downloading dnspython-2.8.0-py3-none-any.whl.metadata (5.7 kB)
-#18 8.741 Collecting librouteros
-#18 8.752   Downloading librouteros-3.4.1-py3-none-any.whl.metadata (1.6 kB)
-#18 8.869 Collecting yattag
-#18 8.881   Downloading yattag-1.16.1.tar.gz (29 kB)
-#18 8.925   Installing build dependencies: started
-#18 10.23   Installing build dependencies: finished with status 'done'
-#18 10.23   Getting requirements to build wheel: started
-#18 10.38   Getting requirements to build wheel: finished with status 'done'
-#18 10.39   Preparing metadata (pyproject.toml): started
-#18 10.55   Preparing metadata (pyproject.toml): finished with status 'done'
-#18 10.60 Collecting Click>=6.0 (from openwrt-luci-rpc)
-#18 10.60   Downloading click-8.3.0-py3-none-any.whl.metadata (2.6 kB)
-#18 10.70 Collecting packaging>=19.1 (from openwrt-luci-rpc)
-#18 10.71   Downloading packaging-25.0-py3-none-any.whl.metadata (3.3 kB)
-#18 10.87 Collecting urllib3>=1.26.14 (from asusrouter)
-#18 10.88   Downloading urllib3-2.5.0-py3-none-any.whl.metadata (6.5 kB)
-#18 10.98 Collecting xmltodict>=0.12.0 (from asusrouter)
-#18 10.98   Downloading xmltodict-1.0.2-py3-none-any.whl.metadata (15 kB)
-#18 11.09 Collecting aiohappyeyeballs>=2.5.0 (from aiohttp)
-#18 11.10   Downloading aiohappyeyeballs-2.6.1-py3-none-any.whl.metadata (5.9 kB)
-#18 11.19 Collecting aiosignal>=1.4.0 (from aiohttp)
-#18 11.20   Downloading aiosignal-1.4.0-py3-none-any.whl.metadata (3.7 kB)
-#18 11.32 Collecting attrs>=17.3.0 (from aiohttp)
-#18 11.33   Downloading attrs-25.3.0-py3-none-any.whl.metadata (10 kB)
-#18 11.47 Collecting frozenlist>=1.1.1 (from aiohttp)
-#18 11.47   Downloading frozenlist-1.7.0-cp312-cp312-musllinux_1_2_x86_64.whl.metadata (18 kB)
-#18 11.76 Collecting multidict<7.0,>=4.5 (from aiohttp)
-#18 11.77   Downloading multidict-6.6.4-cp312-cp312-musllinux_1_2_x86_64.whl.metadata (5.3 kB)
-#18 11.87 Collecting propcache>=0.2.0 (from aiohttp)
-#18 11.88   Downloading propcache-0.3.2-cp312-cp312-musllinux_1_2_x86_64.whl.metadata (12 kB)
-#18 12.19 Collecting yarl<2.0,>=1.17.0 (from aiohttp)
-#18 12.20   Downloading yarl-1.20.1-cp312-cp312-musllinux_1_2_x86_64.whl.metadata (73 kB)
-#18 12.31 Collecting graphql-core<3.3,>=3.1 (from graphene)
-#18 12.32   Downloading graphql_core-3.2.6-py3-none-any.whl.metadata (11 kB)
-#18 12.41 Collecting graphql-relay<3.3,>=3.1 (from graphene)
-#18 12.42   Downloading graphql_relay-3.2.0-py3-none-any.whl.metadata (12 kB)
-#18 12.50 Collecting python-dateutil<3,>=2.7.0 (from graphene)
-#18 12.51   Downloading python_dateutil-2.9.0.post0-py2.py3-none-any.whl.metadata (8.4 kB)
-#18 12.61 Collecting typing-extensions<5,>=4.7.1 (from graphene)
-#18 12.61   Downloading typing_extensions-4.15.0-py3-none-any.whl.metadata (3.3 kB)
-#18 12.71 Collecting blinker>=1.9.0 (from flask)
-#18 12.72   Downloading blinker-1.9.0-py3-none-any.whl.metadata (1.6 kB)
-#18 12.84 Collecting itsdangerous>=2.2.0 (from flask)
-#18 12.85   Downloading itsdangerous-2.2.0-py3-none-any.whl.metadata (1.9 kB)
-#18 12.97 Collecting jinja2>=3.1.2 (from flask)
-#18 12.98   Downloading jinja2-3.1.6-py3-none-any.whl.metadata (2.9 kB)
-#18 13.15 Collecting markupsafe>=2.1.1 (from flask)
-#18 13.15   Downloading MarkupSafe-3.0.2-cp312-cp312-musllinux_1_2_x86_64.whl.metadata (4.0 kB)
-#18 13.28 Collecting werkzeug>=3.1.0 (from flask)
-#18 13.29   Downloading werkzeug-3.1.3-py3-none-any.whl.metadata (3.7 kB)
-#18 13.42 Collecting awesomeversion>=22.9.0 (from tplink-omada-client)
-#18 13.42   Downloading awesomeversion-25.8.0-py3-none-any.whl.metadata (9.8 kB)
-#18 13.59 Collecting charset_normalizer<4,>=2 (from requests)
-#18 13.59   Downloading charset_normalizer-3.4.3-cp312-cp312-musllinux_1_2_x86_64.whl.metadata (36 kB)
-#18 13.77 Collecting idna<4,>=2.5 (from requests)
-#18 13.78   Downloading idna-3.10-py3-none-any.whl.metadata (10 kB)
-#18 13.94 Collecting certifi>=2017.4.17 (from requests)
-#18 13.94   Downloading certifi-2025.8.3-py3-none-any.whl.metadata (2.4 kB)
-#18 14.06 Collecting toml<0.11.0,>=0.10.2 (from librouteros)
-#18 14.07   Downloading toml-0.10.2-py2.py3-none-any.whl.metadata (7.1 kB)
-#18 14.25 Collecting six>=1.5 (from python-dateutil<3,>=2.7.0->graphene)
-#18 14.26   Downloading six-1.17.0-py2.py3-none-any.whl.metadata (1.7 kB)
-#18 14.33 Downloading openwrt_luci_rpc-1.1.17-py2.py3-none-any.whl (9.5 kB)
-#18 14.37 Downloading asusrouter-1.21.0-py3-none-any.whl (131 kB)
-#18 14.43 Downloading asyncio-4.0.0-py3-none-any.whl (5.6 kB)
-#18 14.47 Downloading aiohttp-3.12.15-cp312-cp312-musllinux_1_2_x86_64.whl (1.7 MB)
-#18 14.67    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.7/1.7 MB 8.3 MB/s eta 0:00:00
-#18 14.68 Downloading graphene-3.4.3-py2.py3-none-any.whl (114 kB)
-#18 14.73 Downloading flask-3.1.2-py3-none-any.whl (103 kB)
-#18 14.78 Downloading flask_cors-6.0.1-py3-none-any.whl (13 kB)
-#18 14.84 Downloading unifi_sm_api-0.2.1-py3-none-any.whl (16 kB)
-#18 14.88 Downloading tplink_omada_client-1.4.4-py3-none-any.whl (46 kB)
-#18 14.93 Downloading wakeonlan-3.1.0-py3-none-any.whl (5.0 kB)
-#18 14.99 Downloading pycryptodome-3.23.0-cp37-abi3-musllinux_1_2_x86_64.whl (2.3 MB)
-#18 15.23    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.3/2.3 MB 8.9 MB/s eta 0:00:00
-#18 15.24 Downloading requests-2.32.5-py3-none-any.whl (64 kB)
-#18 15.30 Downloading paho_mqtt-2.1.0-py3-none-any.whl (67 kB)
-#18 15.34 Downloading scapy-2.6.1-py3-none-any.whl (2.4 MB)
-#18 15.62    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.4/2.4 MB 8.5 MB/s eta 0:00:00
-#18 15.63 Downloading cron_converter-1.2.2-py3-none-any.whl (13 kB)
-#18 15.67 Downloading pytz-2025.2-py2.py3-none-any.whl (509 kB)
-#18 15.76 Downloading json2table-1.1.5-py2.py3-none-any.whl (8.7 kB)
-#18 15.81 Downloading dhcp_leases-0.1.6-py3-none-any.whl (11 kB)
-#18 15.86 Downloading pyunifi-2.21-py3-none-any.whl (11 kB)
-#18 15.90 Downloading speedtest_cli-2.1.3-py2.py3-none-any.whl (23 kB)
-#18 15.95 Downloading chardet-5.2.0-py3-none-any.whl (199 kB)
-#18 16.01 Downloading dnspython-2.8.0-py3-none-any.whl (331 kB)
-#18 16.10 Downloading librouteros-3.4.1-py3-none-any.whl (16 kB)
-#18 16.14 Downloading aiohappyeyeballs-2.6.1-py3-none-any.whl (15 kB)
-#18 16.20 Downloading aiosignal-1.4.0-py3-none-any.whl (7.5 kB)
-#18 16.24 Downloading attrs-25.3.0-py3-none-any.whl (63 kB)
-#18 16.30 Downloading awesomeversion-25.8.0-py3-none-any.whl (15 kB)
-#18 16.34 Downloading blinker-1.9.0-py3-none-any.whl (8.5 kB)
-#18 16.39 Downloading certifi-2025.8.3-py3-none-any.whl (161 kB)
-#18 16.45 Downloading charset_normalizer-3.4.3-cp312-cp312-musllinux_1_2_x86_64.whl (153 kB)
-#18 16.50 Downloading click-8.3.0-py3-none-any.whl (107 kB)
-#18 16.55 Downloading frozenlist-1.7.0-cp312-cp312-musllinux_1_2_x86_64.whl (237 kB)
-#18 16.62 Downloading graphql_core-3.2.6-py3-none-any.whl (203 kB)
-#18 16.69 Downloading graphql_relay-3.2.0-py3-none-any.whl (16 kB)
-#18 16.73 Downloading idna-3.10-py3-none-any.whl (70 kB)
-#18 16.79 Downloading itsdangerous-2.2.0-py3-none-any.whl (16 kB)
-#18 16.84 Downloading jinja2-3.1.6-py3-none-any.whl (134 kB)
-#18 16.96 Downloading MarkupSafe-3.0.2-cp312-cp312-musllinux_1_2_x86_64.whl (23 kB)
-#18 17.02 Downloading multidict-6.6.4-cp312-cp312-musllinux_1_2_x86_64.whl (251 kB)
-#18 17.09 Downloading packaging-25.0-py3-none-any.whl (66 kB)
-#18 17.14 Downloading propcache-0.3.2-cp312-cp312-musllinux_1_2_x86_64.whl (222 kB)
-#18 17.21 Downloading python_dateutil-2.9.0.post0-py2.py3-none-any.whl (229 kB)
-#18 17.28 Downloading toml-0.10.2-py2.py3-none-any.whl (16 kB)
-#18 17.33 Downloading typing_extensions-4.15.0-py3-none-any.whl (44 kB)
-#18 17.39 Downloading urllib3-2.5.0-py3-none-any.whl (129 kB)
-#18 17.44 Downloading werkzeug-3.1.3-py3-none-any.whl (224 kB)
-#18 17.51 Downloading xmltodict-1.0.2-py3-none-any.whl (13 kB)
-#18 17.56 Downloading yarl-1.20.1-cp312-cp312-musllinux_1_2_x86_64.whl (374 kB)
-#18 17.65 Downloading six-1.17.0-py2.py3-none-any.whl (11 kB)
-#18 17.77 Building wheels for collected packages: python-nmap, yattag, aiofreepybox
-#18 17.77   Building wheel for python-nmap (pyproject.toml): started
-#18 17.95   Building wheel for python-nmap (pyproject.toml): finished with status 'done'
-#18 17.96   Created wheel for python-nmap: filename=python_nmap-0.7.1-py2.py3-none-any.whl size=20679 sha256=ecd9b14109651cfaa5bf035f90076b9442985cc254fa5f8a49868fc896e86edb
-#18 17.96   Stored in directory: /root/.cache/pip/wheels/06/fc/d4/0957e1d9942e696188208772ea0abf909fe6eb3d9dff6e5a9e
-#18 17.96   Building wheel for yattag (pyproject.toml): started
-#18 18.14   Building wheel for yattag (pyproject.toml): finished with status 'done'
-#18 18.14   Created wheel for yattag: filename=yattag-1.16.1-py3-none-any.whl size=15930 sha256=2135fc2034a3847c81eb6a0d7b85608e8272339fa5c1961f87b02dfe6d74d0ad
-#18 18.14   Stored in directory: /root/.cache/pip/wheels/d2/2f/52/049ff4f7c8c9c932b2ece7ec800d7facf2a141ac5ab0ce7e51
-#18 18.15   Building wheel for aiofreepybox (pyproject.toml): started
-#18 18.36   Building wheel for aiofreepybox (pyproject.toml): finished with status 'done'
-#18 18.36   Created wheel for aiofreepybox: filename=aiofreepybox-6.0.0-py3-none-any.whl size=60051 sha256=dbdee5350b10b6550ede50bc779381b7f39f1e5d5da889f2ee98cb5a869d3425
-#18 18.36   Stored in directory: /tmp/pip-ephem-wheel-cache-93bgc4e2/wheels/3c/d3/ae/fb97a84a29a5fbe8517de58d67e66586505440af35981e0dd3
-#18 18.36 Successfully built python-nmap yattag aiofreepybox
-#18 18.45 Installing collected packages: yattag, speedtest-cli, pytz, python-nmap, json2table, dhcp-leases, xmltodict, wakeonlan, urllib3, typing-extensions, toml, six, scapy, pycryptodome, propcache, paho-mqtt, packaging, multidict, markupsafe, itsdangerous, idna, graphql-core, frozenlist, dnspython, Click, charset_normalizer, chardet, certifi, blinker, awesomeversion, attrs, asyncio, aiohappyeyeballs, yarl, werkzeug, requests, python-dateutil, librouteros, jinja2, graphql-relay, aiosignal, unifi-sm-api, pyunifi, openwrt-luci-rpc, graphene, flask, cron-converter, aiohttp, tplink-omada-client, flask-cors, asusrouter, aiofreepybox
-#18 24.35 Successfully installed Click-8.3.0 aiofreepybox-6.0.0 aiohappyeyeballs-2.6.1 aiohttp-3.12.15 aiosignal-1.4.0 asusrouter-1.21.0 asyncio-4.0.0 attrs-25.3.0 awesomeversion-25.8.0 blinker-1.9.0 certifi-2025.8.3 chardet-5.2.0 charset_normalizer-3.4.3 cron-converter-1.2.2 dhcp-leases-0.1.6 dnspython-2.8.0 flask-3.1.2 flask-cors-6.0.1 frozenlist-1.7.0 graphene-3.4.3 graphql-core-3.2.6 graphql-relay-3.2.0 idna-3.10 itsdangerous-2.2.0 jinja2-3.1.6 json2table-1.1.5 librouteros-3.4.1 markupsafe-3.0.2 multidict-6.6.4 openwrt-luci-rpc-1.1.17 packaging-25.0 paho-mqtt-2.1.0 propcache-0.3.2 pycryptodome-3.23.0 python-dateutil-2.9.0.post0 python-nmap-0.7.1 pytz-2025.2 pyunifi-2.21 requests-2.32.5 scapy-2.6.1 six-1.17.0 speedtest-cli-2.1.3 toml-0.10.2 tplink-omada-client-1.4.4 typing-extensions-4.15.0 unifi-sm-api-0.2.1 urllib3-2.5.0 wakeonlan-3.1.0 werkzeug-3.1.3 xmltodict-1.0.2 yarl-1.20.1 yattag-1.16.1
-#18 24.47 
-#18 24.47 [notice] A new release of pip is available: 25.0.1 -> 25.2
-#18 24.47 [notice] To update, run: pip install --upgrade pip
-#18 DONE 25.1s
+#18 [runner 10/11] COPY --from=builder --chown=20212:20212 /opt/venv /opt/venv
+#18 CACHED
 
-#19 [builder 14/15] RUN bash -c "find /app -type d -exec chmod 750 {} \;"     && bash -c "find /app -type f -exec chmod 640 {} \;"     && bash -c "find /app -type f \( -name '*.sh' -o -name '*.py'  -o -name 'speedtest-cli' \) -exec chmod 750 {} \;"
-#19 DONE 11.9s
+#19 [runner  3/11] COPY --chown=netalertx:netalertx install/production-filesystem/ /
+#19 CACHED
 
-#20 [builder 15/15] COPY install/freebox_certificate.pem /opt/venv/lib/python3.12/site-packages/aiofreepybox/freebox_certificates.pem
-#20 DONE 0.4s
+#20 [hardened 2/2] RUN chown -R readonly:readonly /app/back /app/front /app/server /services                        /services/config /entrypoint.d &&     chmod -R 004 /app/back /app/front /app/server /services                        /services/config /entrypoint.d &&     find /app/back /app/front /app/server /services                        /services/config /entrypoint.d -type d -exec chmod 005 {} + &&     install -d -o netalertx -g netalertx -m 0777 /data /data/config /data/db /tmp/api                        /tmp/log /tmp/log/plugins /tmp/run                        /tmp/run/tmp /tmp/run/logs                        /tmp/nginx/active-config &&     chown readonly:readonly /entrypoint.sh /root-entrypoint.sh /opt /opt/venv &&     chmod 005 /entrypoint.sh /root-entrypoint.sh /services/*.sh /services/scripts/* /entrypoint.d/* /app /opt /opt/venv &&     rm -f       "/data/config/app.conf"       "/data/db/app.db"       "/data/db/app.db-shm"       "/data/db/app.db-wal" || true &&     apk del apk-tools &&     rm -Rf /var /etc/sudoers.d/* /etc/shadow /etc/gshadow /etc/sudoers     /lib/apk /lib/firmware /lib/modules-load.d /lib/sysctl.d /mnt /home/ /root     /srv /media &&     printf '#!/bin/sh\n"$@"\n' > /usr/bin/sudo && chmod +x /usr/bin/sudo
+#20 CACHED
 
-#21 [runner  2/14] COPY --from=builder /opt/venv /opt/venv
-#21 DONE 0.8s
-
-#22 [runner  3/14] COPY --from=builder /usr/sbin/usermod /usr/sbin/groupmod /usr/sbin/
-#22 DONE 0.4s
-
-#23 [runner  4/14] RUN apk update --no-cache     && apk add --no-cache bash libbsd zip lsblk gettext-envsubst sudo mtr tzdata s6-overlay     && apk add --no-cache curl arp-scan iproute2 iproute2-ss nmap nmap-scripts traceroute nbtscan avahi avahi-tools openrc dbus net-tools net-snmp-tools bind-tools awake ca-certificates     && apk add --no-cache sqlite php83 php83-fpm php83-cgi php83-curl php83-sqlite3 php83-session     && apk add --no-cache python3 nginx     && ln -s /usr/bin/awake /usr/bin/wakeonlan     && bash -c "install -d -m 750 -o nginx -g www-data /app /app"     && rm -f /etc/nginx/http.d/default.conf
-#23 0.487 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/main/x86_64/APKINDEX.tar.gz
-#23 0.696 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/community/x86_64/APKINDEX.tar.gz
-#23 1.156 v3.22.1-472-ga67443520d6 [https://dl-cdn.alpinelinux.org/alpine/v3.22/main]
-#23 1.156 v3.22.1-473-gcd551a4e006 [https://dl-cdn.alpinelinux.org/alpine/v3.22/community]
-#23 1.156 OK: 26326 distinct packages available
-#23 1.195 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/main/x86_64/APKINDEX.tar.gz
-#23 1.276 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/community/x86_64/APKINDEX.tar.gz
-#23 1.568 (1/38) Installing ncurses-terminfo-base (6.5_p20250503-r0)
-#23 1.580 (2/38) Installing libncursesw (6.5_p20250503-r0)
-#23 1.629 (3/38) Installing readline (8.2.13-r1)
-#23 1.659 (4/38) Installing bash (5.2.37-r0)
-#23 1.723 Executing bash-5.2.37-r0.post-install
-#23 1.740 (5/38) Installing libintl (0.24.1-r0)
-#23 1.749 (6/38) Installing gettext-envsubst (0.24.1-r0)
-#23 1.775 (7/38) Installing libmd (1.1.0-r0)
-#23 1.782 (8/38) Installing libbsd (0.12.2-r0)
-#23 1.807 (9/38) Installing libeconf (0.6.3-r0)
-#23 1.812 (10/38) Installing libblkid (2.41-r9)
-#23 1.831 (11/38) Installing libmount (2.41-r9)
-#23 1.857 (12/38) Installing libsmartcols (2.41-r9)
-#23 1.872 (13/38) Installing lsblk (2.41-r9)
-#23 1.886 (14/38) Installing libcap2 (2.76-r0)
-#23 1.897 (15/38) Installing jansson (2.14.1-r0)
-#23 1.910 (16/38) Installing mtr (0.96-r0)
-#23 1.948 (17/38) Installing skalibs-libs (2.14.4.0-r0)
-#23 1.966 (18/38) Installing execline-libs (2.9.7.0-r0)
-#23 1.974 (19/38) Installing execline (2.9.7.0-r0)
-#23 1.996 Executing execline-2.9.7.0-r0.post-install
-#23 2.004 (20/38) Installing s6-ipcserver (2.13.2.0-r0)
-#23 2.010 (21/38) Installing s6-libs (2.13.2.0-r0)
-#23 2.016 (22/38) Installing s6 (2.13.2.0-r0)
-#23 2.033 Executing s6-2.13.2.0-r0.pre-install
-#23 2.159 (23/38) Installing s6-rc-libs (0.5.6.0-r0)
-#23 2.164 (24/38) Installing s6-rc (0.5.6.0-r0)
-#23 2.175 (25/38) Installing s6-linux-init (1.1.3.0-r0)
-#23 2.185 (26/38) Installing s6-portable-utils (2.3.1.0-r0)
-#23 2.193 (27/38) Installing s6-linux-utils (2.6.3.0-r0)
-#23 2.200 (28/38) Installing s6-dns-libs (2.4.1.0-r0)
-#23 2.208 (29/38) Installing s6-dns (2.4.1.0-r0)
-#23 2.222 (30/38) Installing bearssl-libs (0.6_git20241009-r0)
-#23 2.254 (31/38) Installing s6-networking-libs (2.7.1.0-r0)
-#23 2.264 (32/38) Installing s6-networking (2.7.1.0-r0)
-#23 2.286 (33/38) Installing s6-overlay-helpers (0.1.2.0-r0)
-#23 2.355 (34/38) Installing s6-overlay (3.2.0.3-r0)
-#23 2.380 (35/38) Installing sudo (1.9.17_p2-r0)
-#23 2.511 (36/38) Installing tzdata (2025b-r0)
-#23 2.641 (37/38) Installing unzip (6.0-r15)
-#23 2.659 (38/38) Installing zip (3.0-r13)
-#23 2.694 Executing busybox-1.37.0-r18.trigger
-#23 2.725 OK: 16 MiB in 54 packages
-#23 2.778 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/main/x86_64/APKINDEX.tar.gz
-#23 2.918 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/community/x86_64/APKINDEX.tar.gz
-#23 3.218 (1/77) Installing libpcap (1.10.5-r1)
-#23 3.234 (2/77) Installing arp-scan (1.10.0-r2)
-#23 3.289 (3/77) Installing dbus-libs (1.16.2-r1)
-#23 3.307 (4/77) Installing avahi-libs (0.8-r21)
-#23 3.315 (5/77) Installing libdaemon (0.14-r6)
-#23 3.322 (6/77) Installing libevent (2.1.12-r8)
-#23 3.355 (7/77) Installing libexpat (2.7.2-r0)
-#23 3.368 (8/77) Installing avahi (0.8-r21)
-#23 3.387 Executing avahi-0.8-r21.pre-install
-#23 3.465 (9/77) Installing gdbm (1.24-r0)
-#23 3.477 (10/77) Installing avahi-tools (0.8-r21)
-#23 3.483 (11/77) Installing libbz2 (1.0.8-r6)
-#23 3.490 (12/77) Installing libffi (3.4.8-r0)
-#23 3.496 (13/77) Installing xz-libs (5.8.1-r0)
-#23 3.517 (14/77) Installing libgcc (14.2.0-r6)
-#23 3.529 (15/77) Installing libstdc++ (14.2.0-r6)
-#23 3.613 (16/77) Installing mpdecimal (4.0.1-r0)
-#23 3.628 (17/77) Installing libpanelw (6.5_p20250503-r0)
-#23 3.634 (18/77) Installing sqlite-libs (3.49.2-r1)
-#23 3.783 (19/77) Installing python3 (3.12.11-r0)
-#23 4.494 (20/77) Installing python3-pycache-pyc0 (3.12.11-r0)
-#23 4.915 (21/77) Installing pyc (3.12.11-r0)
-#23 4.915 (22/77) Installing py3-awake-pyc (1.0-r12)
-#23 4.922 (23/77) Installing python3-pyc (3.12.11-r0)
-#23 4.922 (24/77) Installing py3-awake (1.0-r12)
-#23 4.928 (25/77) Installing awake (1.0-r12)
-#23 4.932 (26/77) Installing fstrm (0.6.1-r4)
-#23 4.940 (27/77) Installing krb5-conf (1.0-r2)
-#23 5.017 (28/77) Installing libcom_err (1.47.2-r2)
-#23 5.026 (29/77) Installing keyutils-libs (1.6.3-r4)
-#23 5.033 (30/77) Installing libverto (0.3.2-r2)
-#23 5.039 (31/77) Installing krb5-libs (1.21.3-r0)
-#23 5.115 (32/77) Installing json-c (0.18-r1)
-#23 5.123 (33/77) Installing nghttp2-libs (1.65.0-r0)
-#23 5.136 (34/77) Installing protobuf-c (1.5.2-r0)
-#23 5.142 (35/77) Installing userspace-rcu (0.15.2-r0)
-#23 5.161 (36/77) Installing libuv (1.51.0-r0)
-#23 5.178 (37/77) Installing libxml2 (2.13.8-r0)
-#23 5.232 (38/77) Installing bind-libs (9.20.13-r0)
-#23 5.355 (39/77) Installing bind-tools (9.20.13-r0)
-#23 5.395 (40/77) Installing ca-certificates (20250619-r0)
-#23 5.518 (41/77) Installing brotli-libs (1.1.0-r2)
-#23 5.559 (42/77) Installing c-ares (1.34.5-r0)
-#23 5.573 (43/77) Installing libunistring (1.3-r0)
-#23 5.645 (44/77) Installing libidn2 (2.3.7-r0)
-#23 5.664 (45/77) Installing libpsl (0.21.5-r3)
-#23 5.676 (46/77) Installing zstd-libs (1.5.7-r0)
-#23 5.720 (47/77) Installing libcurl (8.14.1-r1)
-#23 5.753 (48/77) Installing curl (8.14.1-r1)
-#23 5.778 (49/77) Installing dbus (1.16.2-r1)
-#23 5.796 Executing dbus-1.16.2-r1.pre-install
-#23 5.869 Executing dbus-1.16.2-r1.post-install
-#23 5.887 (50/77) Installing dbus-daemon-launch-helper (1.16.2-r1)
-#23 5.896 (51/77) Installing libelf (0.193-r0)
-#23 5.908 (52/77) Installing libmnl (1.0.5-r2)
-#23 5.915 (53/77) Installing iproute2-minimal (6.15.0-r0)
-#23 5.954 (54/77) Installing libxtables (1.8.11-r1)
-#23 5.963 (55/77) Installing iproute2-tc (6.15.0-r0)
-#23 6.001 (56/77) Installing iproute2-ss (6.15.0-r0)
-#23 6.014 (57/77) Installing iproute2 (6.15.0-r0)
-#23 6.042 Executing iproute2-6.15.0-r0.post-install
-#23 6.047 (58/77) Installing nbtscan (1.7.2-r0)
-#23 6.053 (59/77) Installing net-snmp-libs (5.9.4-r1)
-#23 6.112 (60/77) Installing net-snmp-agent-libs (5.9.4-r1)
-#23 6.179 (61/77) Installing net-snmp-tools (5.9.4-r1)
-#23 6.205 (62/77) Installing mii-tool (2.10-r3)
-#23 6.211 (63/77) Installing net-tools (2.10-r3)
-#23 6.235 (64/77) Installing lua5.4-libs (5.4.7-r0)
-#23 6.258 (65/77) Installing libssh2 (1.11.1-r0)
-#23 6.279 (66/77) Installing nmap (7.97-r0)
-#23 6.524 (67/77) Installing nmap-nselibs (7.97-r0)
-#23 6.729 (68/77) Installing nmap-scripts (7.97-r0)
-#23 6.842 (69/77) Installing bridge (1.5-r5)
-#23 6.904 (70/77) Installing ifupdown-ng (0.12.1-r7)
-#23 6.915 (71/77) Installing ifupdown-ng-iproute2 (0.12.1-r7)
-#23 6.920 (72/77) Installing openrc-user (0.62.6-r0)
-#23 6.924 (73/77) Installing openrc (0.62.6-r0)
-#23 7.013 Executing openrc-0.62.6-r0.post-install
-#23 7.016 (74/77) Installing avahi-openrc (0.8-r21)
-#23 7.021 (75/77) Installing dbus-openrc (1.16.2-r1)
-#23 7.026 (76/77) Installing s6-openrc (2.13.2.0-r0)
-#23 7.032 (77/77) Installing traceroute (2.1.6-r0)
-#23 7.040 Executing busybox-1.37.0-r18.trigger
-#23 7.042 Executing ca-certificates-20250619-r0.trigger
-#23 7.101 Executing dbus-1.16.2-r1.trigger
-#23 7.104 OK: 102 MiB in 131 packages
-#23 7.156 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/main/x86_64/APKINDEX.tar.gz
-#23 7.243 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/community/x86_64/APKINDEX.tar.gz
-#23 7.543 (1/12) Installing php83-common (8.3.24-r0)
-#23 7.551 (2/12) Installing argon2-libs (20190702-r5)
-#23 7.557 (3/12) Installing libedit (20250104.3.1-r1)
-#23 7.568 (4/12) Installing pcre2 (10.43-r1)
-#23 7.600 (5/12) Installing php83 (8.3.24-r0)
-#23 7.777 (6/12) Installing php83-cgi (8.3.24-r0)
-#23 7.953 (7/12) Installing php83-curl (8.3.24-r0)
-#23 7.968 (8/12) Installing acl-libs (2.3.2-r1)
-#23 7.975 (9/12) Installing php83-fpm (8.3.24-r0)
-#23 8.193 (10/12) Installing php83-session (8.3.24-r0)
-#23 8.204 (11/12) Installing php83-sqlite3 (8.3.24-r0)
-#23 8.213 (12/12) Installing sqlite (3.49.2-r1)
-#23 8.309 Executing busybox-1.37.0-r18.trigger
-#23 8.317 OK: 129 MiB in 143 packages
-#23 8.369 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/main/x86_64/APKINDEX.tar.gz
-#23 8.449 fetch https://dl-cdn.alpinelinux.org/alpine/v3.22/community/x86_64/APKINDEX.tar.gz
-#23 8.747 (1/2) Installing nginx (1.28.0-r3)
-#23 8.766 Executing nginx-1.28.0-r3.pre-install
-#23 8.863 Executing nginx-1.28.0-r3.post-install
-#23 8.865 (2/2) Installing nginx-openrc (1.28.0-r3)
-#23 8.870 Executing busybox-1.37.0-r18.trigger
-#23 8.873 OK: 130 MiB in 145 packages
-#23 DONE 9.5s
-
-#24 [runner  5/14] COPY --from=builder --chown=nginx:www-data /app/ /app/
-#24 DONE 0.5s
-
-#25 [runner  6/14] RUN mkdir -p /app/config /app/db /app/log/plugins
-#25 DONE 0.5s
-
-#26 [runner  7/14] COPY --chmod=600 --chown=root:root install/crontab /etc/crontabs/root
-#26 DONE 0.3s
-
-#27 [runner  8/14] COPY --chmod=755 dockerfiles/healthcheck.sh /usr/local/bin/healthcheck.sh
-#27 DONE 0.3s
-
-#28 [runner  9/14] RUN touch /app/log/app.log     && touch /app/log/execution_queue.log     && touch /app/log/app_front.log     && touch /app/log/app.php_errors.log     && touch /app/log/stderr.log     && touch /app/log/stdout.log     && touch /app/log/db_is_locked.log     && touch /app/log/IP_changes.log     && touch /app/log/report_output.txt     && touch /app/log/report_output.html     && touch /app/log/report_output.json     && touch /app/api/user_notifications.json
-#28 DONE 0.6s
-
-#29 [runner 10/14] COPY dockerfiles /app/dockerfiles
-#29 DONE 0.3s
-
-#30 [runner 11/14] RUN chmod +x /app/dockerfiles/*.sh
-#30 DONE 0.8s
-
-#31 [runner 12/14] RUN /app/dockerfiles/init-nginx.sh     && /app/dockerfiles/init-php-fpm.sh     && /app/dockerfiles/init-crond.sh     && /app/dockerfiles/init-backend.sh
-#31 0.417 Initializing nginx...
-#31 0.417 Setting webserver to address (0.0.0.0) and port (20211)
-#31 0.418 /app/dockerfiles/init-nginx.sh: line 5: /app/install/netalertx.template.conf: No such file or directory
-#31 0.611 nginx initialized.
-#31 0.612 Initializing php-fpm...
-#31 0.654 php-fpm initialized.
-#31 0.655 Initializing crond...
-#31 0.689 crond initialized.
-#31 0.690 Initializing backend...
-#31 12.19 Backend initialized.
-#31 DONE 12.3s
-
-#32 [runner 13/14] RUN rm -rf /app/dockerfiles
-#32 DONE 0.6s
-
-#33 [runner 14/14] RUN date +%s > /app/front/buildtimestamp.txt
-#33 DONE 0.6s
-
-#34 exporting to image
-#34 exporting layers
-#34 exporting layers 2.4s done
-#34 writing image sha256:0afcbc41473de559eff0dd93250595494fe4d8ea620861e9e90d50a248fcefda 0.0s done
-#34 naming to docker.io/library/netalertx 0.0s done
-#34 DONE 2.5s
+#21 exporting to image
+#21 exporting layers done
+#21 writing image sha256:7aac94268b770de42da767c06b8e9fecaeabf7ce1277cec1c83092484debd4c3 0.0s done
+#21 naming to docker.io/library/netalertx-test 0.0s done
+#21 DONE 0.1s

docs/API.md

@@ -36,9 +36,15 @@ Authorization: Bearer <API_TOKEN>
 If the token is missing or invalid, the server will return:
 
 ```json
-{ "error": "Forbidden" }
+{
+  "success": false,
+  "message": "ERROR: Not authorized",
+  "error": "Forbidden"
+}
 ```
 
+HTTP Status: **403 Forbidden**
+
 ---
 
 ## Base URL
@@ -54,6 +60,8 @@ http://<server>:<GRAPHQL_PORT>/
 > [!TIP]
 > When retrieving devices or settings try using the GraphQL API endpoint first as it is read-optimized.
 
+### Standard REST Endpoints
+
 * [Device API Endpoints](API_DEVICE.md) – Manage individual devices
 * [Devices Collection](API_DEVICES.md) – Bulk operations on multiple devices
 * [Events](API_EVENTS.md) – Device event logging and management
@@ -69,6 +77,18 @@ http://<server>:<GRAPHQL_PORT>/
 * [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
 
+### MCP Server Bridge
+
+NetAlertX includes an **MCP (Model Context Protocol) Server Bridge** that provides AI assistants access to NetAlertX functionality through standardized tools. MCP endpoints are available at `/mcp/sse/*` paths and mirror the functionality of standard REST endpoints:
+
+* `/mcp/sse` - Server-Sent Events endpoint for MCP client connections
+* `/mcp/sse/openapi.json` - OpenAPI specification for available MCP tools
+* `/mcp/sse/device/*`, `/mcp/sse/devices/*`, `/mcp/sse/nettools/*`, `/mcp/sse/events/*` - MCP-enabled versions of REST endpoints
+
+MCP endpoints require the same Bearer token authentication as REST endpoints.
+
+**📖 See [MCP Server Bridge API](API_MCP.md) for complete documentation, tool specifications, and integration examples.**
+
 See [Testing](API_TESTS.md) for example requests and usage.
 
 ---

docs/API_DBQUERY.md

@@ -2,7 +2,7 @@
 
 The **Database Query API** provides direct, low-level access to the NetAlertX database. It allows **read, write, update, and delete** operations against tables, using **base64-encoded** SQL or structured parameters.
 
-> [!Warning] 
+> [!Warning]
 > This API is primarily used internally to generate and render the application UI. These endpoints are low-level and powerful, and should be used with caution. Wherever possible, prefer the [standard API endpoints](API.md). Invalid or unsafe queries can corrupt data.
 > If you need data in a specific format that is not already provided, please open an issue or pull request with a clear, broadly useful use case. This helps ensure new endpoints benefit the wider community rather than relying on raw database queries.
 
@@ -16,10 +16,14 @@ All `/dbquery/*` endpoints require an API token in the HTTP headers:
 Authorization: Bearer <API_TOKEN>
 ```
 
-If the token is missing or invalid:
+If the token is missing or invalid (HTTP 403):
 
 ```json
-{ "error": "Forbidden" }
+{
+  "success": false,
+  "message": "ERROR: Not authorized",
+  "error": "Forbidden"
+}
 ```
 
 ---

docs/API_DEVICE.md

@@ -41,6 +41,8 @@ Manage a **single device** by its MAC address. Operations include retrieval, upd
 * Device not found → HTTP 404
 * Unauthorized → HTTP 403
 
+**MCP Integration**: Available as `get_device_info` and `set_device_alias` tools. See [MCP Server Bridge API](API_MCP.md).
+
 ---
 
 ## 2. Update Device Fields

docs/API_DEVICES.md

@@ -170,7 +170,7 @@ The Devices Collection API provides operations to **retrieve, manage, import/exp
 **Response**:
 
 ```json
-[ 
+[
   120,    // Total devices
   85,     // Connected
   5,      // Favorites
@@ -207,6 +207,93 @@ The Devices Collection API provides operations to **retrieve, manage, import/exp
 
 ---
 
+### 9. Search Devices
+
+* **POST** `/devices/search`
+  Search for devices by MAC, name, or IP address.
+
+**Request Body** (JSON):
+
+```json
+{
+  "query": ".50"
+}
+```
+
+**Response**:
+
+```json
+{
+  "success": true,
+  "devices": [
+    {
+      "devName": "Test Device",
+      "devMac": "AA:BB:CC:DD:EE:FF",
+      "devLastIP": "192.168.1.50"
+    }
+  ]
+}
+```
+
+---
+
+### 10. Get Latest Device
+
+* **GET** `/devices/latest`
+  Get the most recently connected device.
+
+**Response**:
+
+```json
+[
+  {
+    "devName": "Latest Device",
+    "devMac": "AA:BB:CC:DD:EE:FF",
+    "devLastIP": "192.168.1.100",
+    "devFirstConnection": "2025-12-07 10:30:00"
+  }
+]
+```
+
+---
+
+### 11. Get Network Topology
+
+* **GET** `/devices/network/topology`
+  Get network topology showing device relationships.
+
+**Response**:
+
+```json
+{
+  "nodes": [
+    {
+      "id": "AA:AA:AA:AA:AA:AA",
+      "name": "Router",
+      "vendor": "VendorA"
+    }
+  ],
+  "links": [
+    {
+      "source": "AA:AA:AA:AA:AA:AA",
+      "target": "BB:BB:BB:BB:BB:BB",
+      "port": "eth1"
+    }
+  ]
+}
+```
+
+---
+
+## MCP Tools
+
+These endpoints are also available as **MCP Tools** for AI assistant integration:
+- `list_devices`, `search_devices`, `get_latest_device`, `get_network_topology`, `set_device_alias`
+
+📖 See [MCP Server Bridge API](API_MCP.md) for AI integration details.
+
+---
+
 ## Example `curl` Requests
 
 **Get All Devices**:
@@ -247,3 +334,26 @@ curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/devices/by-status?status=online"
   -H "Authorization: Bearer <API_TOKEN>"
 ```
 
+**Search Devices**:
+
+```sh
+curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/devices/search" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Content-Type: application/json" \
+  --data '{"query": "192.168.1"}'
+```
+
+**Get Latest Device**:
+
+```sh
+curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/devices/latest" \
+  -H "Authorization: Bearer <API_TOKEN>"
+```
+
+**Get Network Topology**:
+
+```sh
+curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/devices/network/topology" \
+  -H "Authorization: Bearer <API_TOKEN>"
+```
+

docs/API_EVENTS.md

@@ -88,7 +88,56 @@ The Events API provides access to **device event logs**, allowing creation, retr
 
 ---
 
-### 4. Event Totals Over a Period
+### 4. Get Recent Events
+
+* **GET** `/events/recent` → Get events from the last 24 hours
+* **GET** `/events/<hours>` → Get events from the last N hours
+
+**Response** (JSON):
+
+```json
+{
+  "success": true,
+  "hours": 24,
+  "count": 5,
+  "events": [
+    {
+      "eve_DateTime": "2025-12-07 12:00:00",
+      "eve_EventType": "New Device",
+      "eve_MAC": "AA:BB:CC:DD:EE:FF",
+      "eve_IP": "192.168.1.100",
+      "eve_AdditionalInfo": "Device detected"
+    }
+  ]
+}
+```
+
+---
+
+### 5. Get Latest Events
+
+* **GET** `/events/last`
+  Get the 10 most recent events.
+
+**Response** (JSON):
+
+```json
+{
+  "success": true,
+  "count": 10,
+  "events": [
+    {
+      "eve_DateTime": "2025-12-07 12:00:00",
+      "eve_EventType": "Device Down",
+      "eve_MAC": "AA:BB:CC:DD:EE:FF"
+    }
+  ]
+}
+```
+
+---
+
+### 6. Event Totals Over a Period
 
 * **GET** `/sessions/totals?period=<period>`
   Return event and session totals over a given period.
@@ -116,12 +165,25 @@ The Events API provides access to **device event logs**, allowing creation, retr
 
 ---
 
+## MCP Tools
+
+Event endpoints are available as **MCP Tools** for AI assistant integration:
+- `get_recent_alerts`, `get_last_events`
+
+📖 See [MCP Server Bridge API](API_MCP.md) for AI integration details.
+
+---
+
 ## Notes
 
-* All endpoints require **authorization** (Bearer token). Unauthorized requests return:
+* All endpoints require **authorization** (Bearer token). Unauthorized requests return HTTP 403:
 
 ```json
-{ "error": "Forbidden" }
+{
+  "success": false,
+  "message": "ERROR: Not authorized",
+  "error": "Forbidden"
+}
 ```
 
 * Events are stored in the **Events table** with the following fields:

docs/API_LOGS.md

@@ -18,7 +18,6 @@ Only specific, pre-approved log files can be purged for security and stability r
 
 ```
 app.log
-app_front.log
 IP_changes.log
 stdout.log
 stderr.log

docs/API_MCP.md

@@ -0,0 +1,418 @@
+# MCP Server Bridge API
+
+The **MCP (Model Context Protocol) Server Bridge** provides AI assistants with standardized access to NetAlertX functionality through tools and server-sent events. This enables AI systems to interact with your network monitoring data in real-time.
+
+---
+
+## Overview
+
+The MCP Server Bridge exposes NetAlertX functionality as **MCP Tools** that AI assistants can call to:
+
+- Search and retrieve device information
+- Trigger network scans
+- Get network topology and events
+- Wake devices via Wake-on-LAN
+- Access open port information
+- Set device aliases
+
+All MCP endpoints mirror the functionality of standard REST endpoints but are optimized for AI assistant integration.
+
+---
+
+## Architecture Overview
+
+### MCP Connection Flow
+
+```mermaid
+graph TB
+    A[AI Assistant<br/>Claude Desktop] -->|SSE Connection| B[NetAlertX MCP Server<br/>:20212/mcp/sse]
+    B -->|JSON-RPC Messages| C[MCP Bridge<br/>api_server_start.py]
+    C -->|Tool Calls| D[NetAlertX Tools<br/>Device/Network APIs]
+    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
+
+```mermaid
+sequenceDiagram
+    participant AI as AI Assistant
+    participant MCP as MCP Server (:20212)
+    participant API as NetAlertX API (:20211)
+    participant DB as SQLite Database
+
+    AI->>MCP: 1. Connect via SSE
+    MCP-->>AI: 2. Session established
+    AI->>MCP: 3. tools/list request
+    MCP->>API: 4. GET /mcp/sse/openapi.json
+    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
+    API->>DB: 9. Query devices
+    DB-->>API: 10. Device data
+    API-->>MCP: 11. JSON response
+    MCP-->>AI: 12. Tool result
+```
+
+### Component Architecture
+
+```mermaid
+graph LR
+    subgraph "AI Client"
+        A[Claude Desktop]
+        B[Custom MCP Client]
+    end
+
+    subgraph "NetAlertX MCP Server (:20212)"
+        C[SSE Endpoint<br/>/mcp/sse]
+        D[Message Handler<br/>/mcp/messages]
+        E[OpenAPI Spec<br/>/mcp/sse/openapi.json]
+    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/*]
+    end
+
+    subgraph "Backend"
+        I[SQLite Database]
+        J[Network Scanners]
+        K[Plugin System]
+    end
+
+    A -.->|Bearer Auth| C
+    B -.->|Bearer Auth| C
+    C --> D
+    C --> E
+    D --> F
+    D --> G
+    D --> H
+    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
+```
+
+---
+
+## Authentication
+
+MCP endpoints use the same **Bearer token authentication** as REST endpoints:
+
+```http
+Authorization: Bearer <API_TOKEN>
+```
+
+Unauthorized requests return HTTP 403:
+
+```json
+{
+  "success": false,
+  "message": "ERROR: Not authorized",
+  "error": "Forbidden"
+}
+```
+
+---
+
+## MCP Connection Endpoint
+
+### Server-Sent Events (SSE)
+
+* **GET/POST** `/mcp/sse`
+
+  Main MCP connection endpoint for AI clients. Establishes a persistent connection using Server-Sent Events for real-time communication between AI assistants and NetAlertX.
+
+**Connection Example**:
+
+```javascript
+const eventSource = new EventSource('/mcp/sse', {
+  headers: {
+    'Authorization': 'Bearer <API_TOKEN>'
+  }
+});
+
+eventSource.onmessage = function(event) {
+  const response = JSON.parse(event.data);
+  console.log('MCP Response:', response);
+};
+```
+
+---
+
+## OpenAPI Specification
+
+### Get MCP Tools Specification
+
+* **GET** `/mcp/sse/openapi.json`
+
+  Returns the OpenAPI specification for all available MCP tools, describing the parameters and schemas for each tool.
+
+**Response**:
+
+```json
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "NetAlertX Tools",
+    "version": "1.1.0"
+  },
+  "servers": [{"url": "/"}],
+  "paths": {
+    "/devices/by-status": {
+      "post": {"operationId": "list_devices"}
+    },
+    "/device/{mac}": {
+      "post": {"operationId": "get_device_info"}
+    },
+    "/devices/search": {
+      "post": {"operationId": "search_devices"}
+    }
+  }
+}
+```
+
+---
+
+## Available MCP Tools
+
+### Device Management Tools
+
+| 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 |
+
+### 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 |
+
+### 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 |
+
+---
+
+## Tool Usage Examples
+
+### Search Devices Tool
+
+**Tool Call**:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "method": "tools/call",
+  "params": {
+    "name": "search_devices",
+    "arguments": {
+      "query": "192.168.1"
+    }
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "{\n  \"success\": true,\n  \"devices\": [\n    {\n      \"devName\": \"Router\",\n      \"devMac\": \"AA:BB:CC:DD:EE:FF\",\n      \"devLastIP\": \"192.168.1.1\"\n    }\n  ]\n}"
+      }
+    ],
+    "isError": false
+  }
+}
+```
+
+### Trigger Network Scan Tool
+
+**Tool Call**:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "2",
+  "method": "tools/call",
+  "params": {
+    "name": "trigger_scan",
+    "arguments": {
+      "type": "ARPSCAN"
+    }
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "2",
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "{\n  \"success\": true,\n  \"message\": \"Scan triggered for type: ARPSCAN\"\n}"
+      }
+    ],
+    "isError": false
+  }
+}
+```
+
+### Wake-on-LAN Tool
+
+**Tool Call**:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "3",
+  "method": "tools/call",
+  "params": {
+    "name": "wol_wake_device",
+    "arguments": {
+      "devMac": "AA:BB:CC:DD:EE:FF"
+    }
+  }
+}
+```
+
+---
+
+## Integration with AI Assistants
+
+### Claude Desktop Integration
+
+Add to your Claude Desktop `mcp.json` configuration:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "netalertx": {
+        "command": "node",
+        "args": ["/path/to/mcp-client.js"],
+        "env": {
+          "NETALERTX_URL": "http://your-server:<GRAPHQL_PORT>",
+          "NETALERTX_TOKEN": "your-api-token"
+        }
+      }
+    }
+  }
+}
+```
+
+### Generic MCP Client
+
+```python
+import asyncio
+import json
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+async def main():
+    # Connect to NetAlertX MCP server
+    server_params = StdioServerParameters(
+        command="curl",
+        args=[
+            "-N", "-H", "Authorization: Bearer <API_TOKEN>",
+            "http://your-server:<GRAPHQL_PORT>/mcp/sse"
+        ]
+    )
+
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            # Initialize connection
+            await session.initialize()
+
+            # List available tools
+            tools = await session.list_tools()
+            print(f"Available tools: {[t.name for t in tools.tools]}")
+
+            # Call a tool
+            result = await session.call_tool("search_devices", {"query": "router"})
+            print(f"Search result: {result}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## Error Handling
+
+MCP tool calls return structured error information:
+
+**Error Response**:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "Error calling tool: Device not found"
+      }
+    ],
+    "isError": true
+  }
+}
+```
+
+**Common Error Types**:
+- `401/403` - Authentication failure
+- `400` - Invalid parameters or missing required fields
+- `404` - Resource not found (device, scan results, etc.)
+- `500` - Internal server error
+
+---
+
+## Notes
+
+* MCP endpoints require the same API token authentication as REST endpoints
+* All MCP tools return JSON responses wrapped in MCP protocol format
+* Server-Sent Events maintain persistent connections for real-time updates
+* Tool parameters match their REST endpoint equivalents
+* Error responses include both HTTP status codes and descriptive messages
+* MCP bridge automatically handles request/response serialization
+
+---
+
+## Related Documentation
+
+* [Main API Overview](API.md) - Core REST API documentation
+* [Device API](API_DEVICE.md) - Individual device management
+* [Devices Collection API](API_DEVICES.md) - Bulk device operations
+* [Network Tools API](API_NETTOOLS.md) - Wake-on-LAN, scans, network utilities
+* [Events API](API_EVENTS.md) - Event logging and monitoring

docs/API_NETTOOLS.md

@@ -1,6 +1,6 @@
 # Net Tools API Endpoints
 
-The Net Tools API provides **network diagnostic utilities**, including Wake-on-LAN, traceroute, speed testing, DNS resolution, nmap scanning, and internet connection information.
+The Net Tools API provides **network diagnostic utilities**, including Wake-on-LAN, traceroute, speed testing, DNS resolution, nmap scanning, internet connection information, and network interface info.
 
 All endpoints require **authorization** via Bearer token.
 
@@ -190,6 +190,51 @@ All endpoints require **authorization** via Bearer token.
 
 ---
 
+### 7. Network Interfaces
+
+* **GET** `/nettools/interfaces`
+  Fetches the list of network interfaces on the system, including IPv4/IPv6 addresses, MAC, MTU, state (up/down), and RX/TX byte counters.
+
+**Response** (success):
+
+```json
+{
+  "success": true,
+  "interfaces": {
+    "eth0": {
+      "name": "eth0",
+      "short": "eth0",
+      "type": "ethernet",
+      "state": "up",
+      "mtu": 1500,
+      "mac": "00:11:32:EF:A5:6B",
+      "ipv4": ["192.168.1.82/24"],
+      "ipv6": ["fe80::211:32ff:feef:a56c/64"],
+      "rx_bytes": 18488221,
+      "tx_bytes": 1443944
+    },
+    "lo": {
+      "name": "lo",
+      "short": "lo",
+      "type": "loopback",
+      "state": "up",
+      "mtu": 65536,
+      "mac": null,
+      "ipv4": ["127.0.0.1/8"],
+      "ipv6": ["::1/128"],
+      "rx_bytes": 123456,
+      "tx_bytes": 123456
+    }
+  }
+}
+```
+
+**Error Responses**:
+
+* Command failure or parsing error → HTTP 500
+
+---
+
 ## Example `curl` Requests
 
 **Wake-on-LAN**:
@@ -241,3 +286,21 @@ curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/nettools/nmap" \
 curl "http://<server_ip>:<GRAPHQL_PORT>/nettools/internetinfo" \
   -H "Authorization: Bearer <API_TOKEN>"
 ```
+
+**Network Interfaces**:
+
+```sh
+curl "http://<server_ip>:<GRAPHQL_PORT>/nettools/interfaces" \
+  -H "Authorization: Bearer <API_TOKEN>"
+```
+
+---
+
+## MCP Tools
+
+Network tools are available as **MCP Tools** for AI assistant integration:
+
+* `wol_wake_device`, `trigger_scan`, `get_open_ports`
+
+📖 See [MCP Server Bridge API](API_MCP.md) for AI integration details.
+

docs/API_OLD.md

@@ -1,7 +1,7 @@
 # [Deprecated] API endpoints
 
-> [!WARNING] 
-> Some of these endpoints will be deprecated soon. Please refere to the new [API](API.md) endpoints docs for details on the new API layer. 
+> [!WARNING]
+> Some of these endpoints will be deprecated soon. Please refere to the new [API](API.md) endpoints docs for details on the new API layer.
 
 NetAlertX comes with a couple of API endpoints. All requests need to be authorized (executed in a logged in browser session) or you have to pass the value of the `API_TOKEN` settings as authorization bearer, for example:
 
@@ -56,7 +56,7 @@ See also: [Debugging GraphQL issues](./DEBUG_API_SERVER.md)
 
 ### `curl` Command
 
-You can use the following `curl` command to execute the query. 
+You can use the following `curl` command to execute the query.
 
 ```sh
 curl 'http://host:GRAPHQL_PORT/graphql'   -X POST   -H 'Authorization: Bearer API_TOKEN'  -H 'Content-Type: application/json'   --data '{
@@ -127,9 +127,9 @@ The response will be in JSON format, similar to the following:
 }
 ```
 
-## API Endpoint: JSON files 
+## API Endpoint: JSON files
 
-This API endpoint retrieves static files, that are periodically updated. 
+This API endpoint retrieves static files, that are periodically updated.
 
 - Endpoint URL: `php/server/query_json.php?file=<file name>`
 - Host: `same as front end (web ui)`
@@ -147,18 +147,18 @@ In the container, these files are located under the API directory (default: `/tm
 
 You can access the following files:
 
-  | File name | Description | 
-  |----------------------|----------------------| 
+  | File name | Description |
+  |----------------------|----------------------|
   | `notification_json_final.json` | The json version of the last notification (e.g. used for webhooks - [sample JSON](https://github.com/jokob-sk/NetAlertX/blob/main/front/report_templates/webhook_json_sample.json)). |
-  | `table_devices.json` | All of the available Devices detected by the app. |  
+  | `table_devices.json` | All of the available Devices detected by the app. |
   | `table_plugins_events.json` | The list of the unprocessed (pending) notification events (plugins_events DB table). |
-  | `table_plugins_history.json` | The list of notification events history. |  
-  | `table_plugins_objects.json` | The content of the plugins_objects table. Find more info on the [Plugin system here](https://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md)|
-  | `language_strings.json` | The content of the language_strings table, which in turn is loaded from the plugins `config.json` definitions. |  
+  | `table_plugins_history.json` | The list of notification events history. |
+  | `table_plugins_objects.json` | The content of the plugins_objects table. Find more info on the [Plugin system here](https://docs.netalertx.com/PLUGINS)|
+  | `language_strings.json` | The content of the language_strings table, which in turn is loaded from the plugins `config.json` definitions. |
   | `table_custom_endpoint.json` | A custom endpoint generated by the SQL query specified by the `API_CUSTOM_SQL` setting. |
   | `table_settings.json` | The content of the settings table. |
   | `app_state.json` | Contains the current application state. |
-  
+
 
 ### JSON Data format
 
@@ -169,11 +169,11 @@ The endpoints starting with the `table_` prefix contain most, if not all, data c
   "data": [
         {
           "db_column_name": "data",
-          "db_column_name2": "data2"      
-        }, 
+          "db_column_name2": "data2"
+        },
         {
           "db_column_name": "data3",
-          "db_column_name2": "data4" 
+          "db_column_name2": "data4"
         }
     ]
 }
@@ -201,7 +201,7 @@ Example JSON of the `table_devices.json` endpoint with two Devices (database row
           "devParentMAC": "",
           "devParentPort": "",
           "devIcon": "globe"
-        }, 
+        },
         {
           "devMac": "a4:8f:ff:aa:ba:1f",
           "devName": "Net - USG",
@@ -332,7 +332,7 @@ Grafana template sample: [Download json](./samples/API/Grafana_Dashboard.json)
 
 ## API Endpoint: /log files
 
-This API endpoint retrieves files from the `/tmp/log` folder. 
+This API endpoint retrieves files from the `/tmp/log` folder.
 
 - Endpoint URL: `php/server/query_logs.php?file=<file name>`
 - Host: `same as front end (web ui)`
@@ -357,7 +357,7 @@ This API endpoint retrieves files from the `/tmp/log` folder.
 
 ## API Endpoint: /config files
 
-To retrieve files from the `/data/config` folder. 
+To retrieve files from the `/data/config` folder.
 
 - Endpoint URL: `php/server/query_config.php?file=<file name>`
 - Host: `same as front end (web ui)`

docs/API_SESSIONS.md

@@ -118,11 +118,14 @@ curl -X DELETE "http://<server_ip>:<GRAPHQL_PORT>/sessions/delete" \
   ```
 #### `curl` Example
 
+**get sessions for mac**
+
 ```bash
 curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/sessions/list?mac=AA:BB:CC:DD:EE:FF&start_date=2025-08-01&end_date=2025-08-21" \
   -H "Authorization: Bearer <API_TOKEN>" \
   -H "Accept: application/json"
 ```
+
 ---
 
 ### Calendar View of Sessions

docs/API_SSE.md

@@ -0,0 +1,78 @@
+# SSE (Server-Sent Events)
+
+Real-time app state updates via Server-Sent Events. Reduces server load ~95% vs polling.
+
+## Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/sse/state` | GET | Stream state updates (requires Bearer token) |
+| `/sse/stats` | GET | Debug: connected clients, queued events |
+
+## Usage
+
+### Connect to SSE Stream
+```bash
+curl -H "Authorization: Bearer YOUR_API_TOKEN" \
+  http://localhost:5000/sse/state
+```
+
+### Check Connection Stats
+```bash
+curl -H "Authorization: Bearer YOUR_API_TOKEN" \
+  http://localhost:5000/sse/stats
+```
+
+## Event Types
+
+- `state_update` - App state changed (e.g., "Scanning", "Processing")
+- `unread_notifications_count_update` - Number of unread notifications changed (count: int)
+
+## Backend Integration
+
+Broadcasts automatically triggered in `app_state.py` via `broadcast_state_update()`:
+
+```python
+from api_server.sse_broadcast import broadcast_state_update
+
+# Called on every state change - no additional code needed
+broadcast_state_update(current_state="Scanning", settings_imported=time.time())
+```
+
+## Frontend Integration
+
+Auto-enabled via `sse_manager.js`:
+
+```javascript
+// In browser console:
+netAlertXStateManager.getStats().then(stats => {
+  console.log("Connected clients:", stats.connected_clients);
+});
+```
+
+## Fallback Behavior
+
+- If SSE fails after 3 attempts, automatically switches to polling
+- Polling starts at 1s, backs off to 30s max
+- No user-visible difference in functionality
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `server/api_server/sse_endpoint.py` | SSE endpoints & event queue |
+| `server/api_server/sse_broadcast.py` | Broadcast helper functions |
+| `front/js/sse_manager.js` | Client-side SSE connection manager |
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Connection refused | Check backend running, API token correct |
+| No events received | Verify `broadcast_state_update()` is called on state changes |
+| High memory | Events not processed fast enough, check client logs |
+| Using polling instead of SSE | Normal fallback - check browser console for errors |
+
+---
+
+

docs/AUTHELIA.md

@@ -1,8 +1,8 @@
 ## Authelia support
 
-> [!WARNING] 
->
-> This is community contributed content and work in progress. Contributions are welcome. 
+> [!NOTE]
+> This is community-contributed. Due to environment, setup, or networking differences, results may vary. Please open a PR to improve it instead of creating an issue, as the maintainer is not actively maintaining it.
+
 
 ```yaml
 theme: dark
@@ -274,4 +274,4 @@ notifier:
     subject: "[Authelia] {title}"
     startup_check_address: postmaster@MYOTHERDOMAIN.LTD
 
-```
+```

docs/CNAME

@@ -0,0 +1 @@
+docs.netalertx.com

docs/COMMUNITY_GUIDES.md

@@ -1,15 +1,21 @@
 # Community Guides
 
-Use the official installation guides at first and use community content as supplementary material. Open an issue or PR if you'd like to add your link to the list 🙏 (Ordered by last update time)
+> [!NOTE]
+> This is community-contributed. Due to environment, setup, or networking differences, results may vary. Please open a PR to improve it instead of creating an issue, as the maintainer is not actively maintaining it.
+
+
+Use the official installation guides at first and use community content as supplementary material. (Ordered by last update time)
 
 - ▶ [Discover & Monitor Your Network with This Self-Hosted Open Source Tool - Lawrence Systems](https://www.youtube.com/watch?v=R3b5cxLZMpo) (June 2025)
 - ▶ [Home Lab Network Monitoring - Scotti-BYTE Enterprise Consulting Services](https://www.youtube.com/watch?v=0DryhzrQSJA) (July 2024)
 - 📄 [How to Install NetAlertX on Your Synology NAS - Marius hosting](https://mariushosting.com/how-to-install-pi-alert-on-your-synology-nas/) (Updated frequently)
 - 📄 [Using the PiAlert Network Security Scanner on a Raspberry Pi - PiMyLifeUp](https://pimylifeup.com/raspberry-pi-pialert/)
-- ▶ [How to Setup Pi.Alert on Your Synology NAS - Digital Aloha](https://www.youtube.com/watch?v=M4YhpuRFaUg) 
+- ▶ [How to Setup Pi.Alert on Your Synology NAS - Digital Aloha](https://www.youtube.com/watch?v=M4YhpuRFaUg)
 - 📄 [防蹭网神器，网络安全助手 | 极空间部署网络扫描和通知系统『NetAlertX』](https://blog.csdn.net/qq_63499861/article/details/141105273)
 - 📄 [시놀/헤놀에서 네트워크 스캐너 Pi.Alert Docker로 설치 및 사용하기](https://blog.dalso.org/article/%EC%8B%9C%EB%86%80-%ED%97%A4%EB%86%80%EC%97%90%EC%84%9C-%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC-%EC%8A%A4%EC%BA%90%EB%84%88-pi-alert-docker%EB%A1%9C-%EC%84%A4%EC%B9%98-%EB%B0%8F-%EC%82%AC%EC%9A%A9) (July 2023)
 - 📄 [网络入侵探测器Pi.Alert (Chinese)](https://codeantenna.com/a/VgUvIAjZ7J) (May 2023)
 - ▶ [Pi.Alert auf Synology & Docker by - Jürgen Barth](https://www.youtube.com/watch?v=-ouvA2UNu-A) (March 2023)
 - ▶ [Top Docker Container for Home Server Security - VirtualizationHowto](https://www.youtube.com/watch?v=tY-w-enLF6Q) (March 2023)
 - ▶ [Pi.Alert or WatchYourLAN can alert you to unknown devices appearing on your WiFi or LAN network - Danie van der Merwe](https://www.youtube.com/watch?v=v6an9QG2xF0) (November 2022)
+
+

docs/CUSTOM_PROPERTIES.md

@@ -13,31 +13,6 @@ This functionality allows you to define **custom properties** for devices, which
 
 ---
 
-## Defining Custom Properties
-
-Custom properties are structured as a list of objects, where each property includes the following fields:
-
-| Field             | Description                                                                 |
-|--------------------|-----------------------------------------------------------------------------|
-| `CUSTPROP_icon`    | The icon (Base64-encoded HTML) displayed for the property.                 |
-| `CUSTPROP_type`    | The action type (e.g., `show_notes`, `link`, `delete_dev`).                |
-| `CUSTPROP_name`    | A short name or title for the property.                                    |
-| `CUSTPROP_args`    | Arguments for the action (e.g., URL or modal text).                        |
-| `CUSTPROP_notes`   | Additional notes or details displayed when applicable.                    |
-| `CUSTPROP_show`    | A boolean to control visibility (`true` to show on the listing page).      |
-
----
-
-## Available Action Types
-
-- **Show Notes**: Displays a modal with a title and additional notes.
-  - **Example**: Show firmware details or custom messages.
-- **Link**: Redirects to a specified URL in the current browser tab. (**Arguments** Needs to contain the full URL.)
-- **Link (New Tab)**: Opens a specified URL in a new browser tab. (**Arguments** Needs to contain the full URL.)
-- **Delete Device**: Deletes the device using its MAC address.
-- **Run Plugin**: Placeholder for executing custom plugins (not implemented yet).
-
----
 
 ## Usage on the Device Listing Page
 
@@ -74,12 +49,39 @@ Visible properties (`CUSTPROP_show: true`) are displayed as interactive icons in
 3. **Device Removal**:
    - Enable device removal functionality using `CUSTPROP_type: delete_dev`.
 
+---
+
+## Defining Custom Properties
+
+Custom properties are structured as a list of objects, where each property includes the following fields:
+
+| Field             | Description                                                                 |
+|--------------------|-----------------------------------------------------------------------------|
+| `CUSTPROP_icon`    | The icon (Base64-encoded HTML) displayed for the property.                 |
+| `CUSTPROP_type`    | The action type (e.g., `show_notes`, `link`, `delete_dev`).                |
+| `CUSTPROP_name`    | A short name or title for the property.                                    |
+| `CUSTPROP_args`    | Arguments for the action (e.g., URL or modal text).                        |
+| `CUSTPROP_notes`   | Additional notes or details displayed when applicable.                    |
+| `CUSTPROP_show`    | A boolean to control visibility (`true` to show on the listing page).      |
+
+---
+
+## Available Action Types
+
+- **Show Notes**: Displays a modal with a title and additional notes.
+  - **Example**: Show firmware details or custom messages.
+- **Link**: Redirects to a specified URL in the current browser tab. (**Arguments** Needs to contain the full URL.)
+- **Link (New Tab)**: Opens a specified URL in a new browser tab. (**Arguments** Needs to contain the full URL.)
+- **Delete Device**: Deletes the device using its MAC address.
+- **Run Plugin**: Placeholder for executing custom plugins (not implemented yet).
+
+
 ---
 
 ## Notes
 
 - **Plugin Functionality**: The `run_plugin` action type is currently not implemented and will show an alert if used.
-- **Custom Icons (Experimental 🧪)**: Use Base64-encoded HTML to provide custom icons for each property. You can add your icons in Setttings via the `CUSTPROP_icon` settings 
+- **Custom Icons (Experimental 🧪)**: Use Base64-encoded HTML to provide custom icons for each property. You can add your icons in Setttings via the `CUSTPROP_icon` settings
 - **Visibility Control**: Only properties with `CUSTPROP_show: true` will appear on the listing page.
 
 This feature provides a flexible way to enhance device management and display with interactive elements tailored to your needs.

docs/DEBUG_API_SERVER.md

@@ -40,7 +40,7 @@ There are several ways to check if the GraphQL server is running.
 
 ### Init Check
 
-You can navigate to Maintenance -> Init Check to see if `isGraphQLServerRunning` is ticked:
+You can navigate to System Info -> Init Check to see if `isGraphQLServerRunning` is ticked:
 
 ![Init Check](./img/DEBUG_API_SERVER/Init_check.png)
 

docs/DEBUG_INVALID_JSON.md

@@ -9,7 +9,6 @@ Check the the HTTP response of the failing backend call by following these steps
 
 - Copy the URL causing the error and enter it in the address bar of your browser directly and hit enter. The copied URLs could look something like this (notice the query strings at the end):
   - `http://<server>:20211/api/table_devices.json?nocache=1704141103121`
-  - `http://<server>:20211/php/server/devices.php?action=getDevicesTotals`
 
 
 - Post the error response in the existing issue thread on GitHub or create a new issue and include the redacted response of the failing query.

docs/DEBUG_PLUGINS.md

@@ -7,7 +7,7 @@
 
 If a Plugin supplies data to the main app it's done either vie a SQL query or via a script that updates the `last_result.log` file in the plugin log folder (`app/log/plugins/`).
 
-For a more in-depth overview on how plugins work check the [Plugins development docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md).
+For a more in-depth overview on how plugins work check the [Plugins development docs](./PLUGINS_DEV.md).
 
 ### Prerequisites
 

docs/DEVICES_BULK_EDITING.md

@@ -26,7 +26,7 @@ The database and device structure may change with new releases. When using the C
 ![Maintenance > CSV Export](./img/DEVICES_BULK_EDITING/MAINTENANCE_CSV_EXPORT.png)
 
 > [!NOTE]
-> The file containing a list of Devices including the Network relationships between Network Nodes and connected devices. You can also trigger this by acessing this URL: `<server>:20211/php/server/devices.php?action=ExportCSV` or via the `CSV Backup` plugin. (💡 You can schedule this)
+> The file containing a list of Devices including the Network relationships between Network Nodes and connected devices. You can also trigger this with the `CSV Backup` plugin. (💡 You can schedule this)
 
 ![Settings > CSV Backup](./img/DEVICES_BULK_EDITING/CSV_BACKUP_SETTINGS.png)
 

docs/DEVICE_MANAGEMENT.md

@@ -13,7 +13,7 @@ The Main Info section is where most of the device identifiable information is st
 
   - **MAC**: MAC addres of the device. Not editable, unless creating a new dummy device.
   - **Last IP**: IP addres of the device. Not editable, unless creating a new dummy device.
-  - **Name**: Friendly device name. Autodetected via various 🆎 Name discovery [plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md). The app attaches `(IP match)` if the name is discovered via an IP match and not MAC match which could mean the name could be incorrect as IPs might change.
+  - **Name**: Friendly device name. Autodetected via various 🆎 Name discovery [plugins](https://docs.netalertx.com/PLUGINS). The app attaches `(IP match)` if the name is discovered via an IP match and not MAC match which could mean the name could be incorrect as IPs might change.
   - **Icon**: Partially autodetected. Select an existing or [add a custom icon](./ICONS.md). You can also auto-apply the same icon on all devices of the same type.
   - **Owner**: Device owner (The list is self-populated with existing owners and you can add custom values).
   - **Type**: Select a device type from the dropdown list (`Smartphone`, `Tablet`,

docs/DOCKER_COMPOSE.md

@@ -1,7 +1,7 @@
 # NetAlertX and Docker Compose
 
 > [!WARNING]
-> ⚠️ **Important:** The docker-compose has recently changed. Carefully read the [Migration guide](https://jokob-sk.github.io/NetAlertX/MIGRATION/?h=migrat#12-migration-from-netalertx-v25524) for detailed instructions.
+> ⚠️ **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.
 
 Great care is taken to ensure NetAlertX meets the needs of everyone while being flexible enough for anyone. This document outlines how you can configure your docker-compose. There are many settings, so we recommend using the Baseline Docker Compose as-is, or modifying it for your system.Good care is taken to ensure NetAlertX meets the needs of everyone while being flexible enough for anyone. This document outlines how you can configure your docker-compose. There are many settings, so we recommend using the Baseline Docker Compose as-is, or modifying it for your system.
 
@@ -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-dev:latest
+    image: ghcr.io/jokob-sk/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
@@ -51,24 +51,26 @@ services:
       # - path/on/host/to/dhcp.file:/resources/dhcp.file
 
     # tmpfs mount consolidates writable state for a read-only container and improves performance
-    # uid=20211 and gid=20211 is the netalertx user inside the container
-    # mode=1700 grants rwx------ permissions to the netalertx user only
+    # uid/gid default to the service user (NETALERTX_UID/GID, default 20211)
+    # mode=1700 grants rwx------ permissions to the runtime user only
     tmpfs:
       # Comment out to retain logs between container restarts - this has a server performance impact.
-      - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+      - "/tmp:uid=${NETALERTX_UID:-20211},gid=${NETALERTX_GID:-20211},mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
 
       # Retain logs - comment out tmpfs /tmp if you want to retain logs between container restarts
       # Please note if you remove the /tmp mount, you must create and maintain sub-folder mounts.
       # - /path/on/host/log:/tmp/log
-      # - "/tmp/api:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
-      # - "/tmp/nginx:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
-      # - "/tmp/run:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+      # - "/tmp/api:uid=${NETALERTX_UID:-20211},gid=${NETALERTX_GID:-20211},mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+      # - "/tmp/nginx:uid=${NETALERTX_UID:-20211},gid=${NETALERTX_GID:-20211},mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+      # - "/tmp/run:uid=${NETALERTX_UID:-20211},gid=${NETALERTX_GID:-20211},mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
 
     environment:
       LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0}                   # Listen for connections on all interfaces
       PORT: ${PORT:-20211}                                   # Application port
       GRAPHQL_PORT: ${GRAPHQL_PORT:-20212}                   # GraphQL API port (passed into APP_CONF_OVERRIDE at runtime)
   #    NETALERTX_DEBUG: ${NETALERTX_DEBUG:-0}                 # 0=kill all services and restart if any dies. 1 keeps running dead services.
+  #    PUID: 20211                             # Runtime PUID override, set to 0 to run as root
+  #    PGID: 20211                             # Runtime PGID override
 
     # Resource limits to prevent resource exhaustion
     mem_limit: 2048m            # Maximum memory usage
@@ -94,6 +96,9 @@ Run or re-run it:
 docker compose up --force-recreate
 ```
 
+> [!TIP]
+> Runtime UID/GID: The image ships with a service user `netalertx` (UID/GID 20211) and a readonly lock owner also at 20211 for 004/005 immutability. If you override the runtime user (compose `user:` or `NETALERTX_UID/GID` vars), ensure your `/data` volume and tmpfs mounts use matching `uid/gid` so startup checks and writable paths succeed.
+
 ### Customize with Environmental Variables
 
 You can override the default settings by passing environmental variables to the `docker compose up` command.
@@ -168,10 +173,6 @@ Now, any files created by NetAlertX in `/data/config` will appear in your `/loca
 
 This same method works for mounting other things, like custom plugins or enterprise NGINX files, as shown in the commented-out examples in the baseline file.
 
-## Example Configuration Summaries
-
-Here are the essential modifications for common alternative setups.
-
 ### Example 2: External `.env` File for Paths
 
 This method is useful for keeping your paths and other settings separate from your main compose file, making it more portable.

docs/DOCKER_INSTALLATION.md

@@ -6,7 +6,7 @@
 
 # NetAlertX - Network scanner & notification framework
 
-| [📑 Docker guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_INSTALLATION.md) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://jokob-sk.github.io/NetAlertX/) | [🔌 Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
+| [📑 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)
 |----------------------| ----------------------|  ----------------------| ----------------------| ----------------------|
 
 <a href="https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/GENERAL/github_social_image.jpg" target="_blank">
@@ -16,24 +16,26 @@
 Head to [https://netalertx.com/](https://netalertx.com/) for more gifs and screenshots 📷.
 
 > [!NOTE]
-> There is also an experimental 🧪 [bare-metal install](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) method available.
+> There is also an experimental 🧪 [bare-metal install](https://docs.netalertx.com/HW_INSTALL) method available.
 
 ## 📕 Basic Usage
 
 > [!WARNING]
-> You will have to run the container on the `host` network and specify `SCAN_SUBNETS` unless you use other [plugin scanners](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md). The initial scan can take a few minutes, so please wait 5-10 minutes for the initial discovery to finish.
+> You will have to run the container on the `host` network and specify `SCAN_SUBNETS` unless you use other [plugin scanners](https://docs.netalertx.com/PLUGINS). The initial scan can take a few minutes, so please wait 5-10 minutes for the initial discovery to finish.
 
 ```bash
 docker run -d --rm --network=host \
   -v /local_data_dir:/data \
   -v /etc/localtime:/etc/localtime \
-  --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
+  --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
 ```
 
-See alternative [docked-compose examples](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md).
+> 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.
+
+See alternative [docked-compose examples](https://docs.netalertx.com/DOCKER_COMPOSE).
 
 ### Default ports
 
@@ -44,11 +46,13 @@ See alternative [docked-compose examples](https://github.com/jokob-sk/NetAlertX/
 
 ### Docker environment variables
 
-| Variable | Description | Example Value |
+| Variable | Description | Example/Default Value |
 | :------------- |:------------------------| -----:|
+| `PUID`      |Runtime UID override, set to `0` to run as root. |  `20211` |
+| `PGID`      |Runtime GID override  |  `20211` |
 | `PORT`      |Port of the web interface  |  `20211` |
 | `LISTEN_ADDR`      |Set the specific IP Address for the listener address for the nginx webserver (web interface). This could be useful when using multiple subnets to hide the web interface from all untrusted networks. |  `0.0.0.0` |
-|`LOADED_PLUGINS` | Default [plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md) to load. Plugins cannot be loaded with `APP_CONF_OVERRIDE`, you need to use this variable instead and then specify the plugins settings with `APP_CONF_OVERRIDE`. |  `["PIHOLE","ASUSWRT"]` |
+|`LOADED_PLUGINS` | Default [plugins](https://docs.netalertx.com/PLUGINS) to load. Plugins cannot be loaded with `APP_CONF_OVERRIDE`, you need to use this variable instead and then specify the plugins settings with `APP_CONF_OVERRIDE`. |  `["PIHOLE","ASUSWRT"]` |
 |`APP_CONF_OVERRIDE` | JSON override for settings (except `LOADED_PLUGINS`).   |  `{"SCAN_SUBNETS":"['192.168.1.0/24 --interface=eth1']","GRAPHQL_PORT":"20212"}` |
 |`ALWAYS_FRESH_INSTALL` | ⚠ If `true` will delete the content of the `/db` & `/config` folders. For testing purposes. Can be coupled with [watchtower](https://github.com/containrrr/watchtower) to have an always freshly installed `netalertx`/`netalertx-dev` image.   |    `true` |
 
@@ -57,16 +61,16 @@ See alternative [docked-compose examples](https://github.com/jokob-sk/NetAlertX/
 ### Docker paths
 
 > [!NOTE]
-> See also [Backup strategies](https://github.com/jokob-sk/NetAlertX/blob/main/docs/BACKUPS.md).
+> See also [Backup strategies](https://docs.netalertx.com/BACKUPS).
 
 | Required | Path | Description |
 | :------------- | :------------- | :-------------|
 | ✅ | `:/data` | Folder which needs to contain a `/db` and `/config` sub-folders. |
 | ✅ | `/etc/localtime:/etc/localtime:ro` | Ensuring the timezone is the same as on the server.  |
 | | `:/tmp/log` |  Logs folder useful for debugging if you have issues setting up the container  |
-| | `:/tmp/api` |  The [API endpoint](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md) containing static (but regularly updated) json and other files. Path configurable via `NETALERTX_API` environment variable.   |
-| | `:/app/front/plugins/<plugin>/ignore_plugin` | Map a file `ignore_plugin` to ignore a plugin. Plugins can be soft-disabled via settings. More in the [Plugin docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md).  |
-| | `:/etc/resolv.conf` | Use a custom `resolv.conf` file for [better name resolution](https://github.com/jokob-sk/NetAlertX/blob/main/docs/REVERSE_DNS.md).  |
+| | `:/tmp/api` |  The [API endpoint](https://docs.netalertx.com/API) containing static (but regularly updated) json and other files. Path configurable via `NETALERTX_API` environment variable.   |
+| | `:/app/front/plugins/<plugin>/ignore_plugin` | Map a file `ignore_plugin` to ignore a plugin. Plugins can be soft-disabled via settings. More in the [Plugin docs](https://docs.netalertx.com/PLUGINS).  |
+| | `:/etc/resolv.conf` | Use a custom `resolv.conf` file for [better name resolution](https://docs.netalertx.com/REVERSE_DNS).  |
 
 ### Folder structure
 
@@ -83,7 +87,8 @@ data
 If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located).
 
 ```bash
-sudo chown -R 20211:20211 /local_data_dir
+# Use the runtime UID/GID you intend to run with (default 20211:20211)
+sudo chown -R ${NETALERTX_UID:-20211}:${NETALERTX_GID:-20211} /local_data_dir
 sudo chmod -R a+rwx /local_data_dir
 ```
 
@@ -95,23 +100,23 @@ sudo chmod -R a+rwx /local_data_dir
 
 #### Setting up scanners
 
-You have to specify which network(s) should be scanned. This is done by entering subnets that are accessible from the host. If you use the default `ARPSCAN` plugin, you have to specify at least one valid subnet and interface in the `SCAN_SUBNETS` setting. See the documentation on [How to set up multiple SUBNETS, VLANs and what are limitations](https://github.com/jokob-sk/NetAlertX/blob/main/docs/SUBNETS.md) for troubleshooting and more advanced scenarios.
+You have to specify which network(s) should be scanned. This is done by entering subnets that are accessible from the host. If you use the default `ARPSCAN` plugin, you have to specify at least one valid subnet and interface in the `SCAN_SUBNETS` setting. See the documentation on [How to set up multiple SUBNETS, VLANs and what are limitations](https://docs.netalertx.com/SUBNETS) for troubleshooting and more advanced scenarios.
 
-If you are running PiHole you can synchronize devices directly. Check the [PiHole configuration guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PIHOLE_GUIDE.md) for details.
+If you are running PiHole you can synchronize devices directly. Check the [PiHole configuration guide](https://docs.netalertx.com/PIHOLE_GUIDE) for details.
 
 > [!NOTE]
-> You can bulk-import devices via the [CSV import method](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md).
+> You can bulk-import devices via the [CSV import method](https://docs.netalertx.com/DEVICES_BULK_EDITING).
 
 #### Community guides
 
-You can read or watch several [community configuration guides](https://github.com/jokob-sk/NetAlertX/blob/main/docs/COMMUNITY_GUIDES.md) in Chinese, Korean, German, or French.
+You can read or watch several [community configuration guides](https://docs.netalertx.com/COMMUNITY_GUIDES) in Chinese, Korean, German, or French.
 
 > Please note these might be outdated. Rely on official documentation first.
 
 #### Common issues
 
 - Before creating a new issue, please check if a similar issue was [already resolved](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed).
-- Check also common issues and [debugging tips](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md).
+- Check also common issues and [debugging tips](https://docs.netalertx.com/DEBUG_TIPS).
 
 ## 💙 Support me
 

docs/DOCKER_MAINTENANCE.md

@@ -1,7 +1,7 @@
 # The NetAlertX Container Operator's Guide
 
 > [!WARNING]
-> ⚠️ **Important:** The docker-compose has recently changed. Carefully read the [Migration guide](https://jokob-sk.github.io/NetAlertX/MIGRATION/?h=migrat#12-migration-from-netalertx-v25524) for detailed instructions.
+> ⚠️ **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.
 
 This guide assumes you are starting with the official `docker-compose.yml` file provided with the project. We strongly recommend you start with or migrate to this file as your baseline and modify it to suit your specific needs (e.g., changing file paths). While there are many ways to configure NetAlertX, the default file is designed to meet the mandatory security baseline with layer-2 networking capabilities while operating securely and without startup warnings.
 

docs/DOCKER_SWARM.md

@@ -1,5 +1,9 @@
 # Docker Swarm Deployment Guide (IPvlan)
 
+> [!NOTE]
+> This is community-contributed. Due to environment, setup, or networking differences, results may vary. Please open a PR to improve it instead of creating an issue, as the maintainer is not actively maintaining it.
+
+
 This guide describes how to deploy **NetAlertX** in a **Docker Swarm** environment using an `ipvlan` network. This enables the container to receive a LAN IP address directly, which is ideal for network monitoring.
 
 ---
@@ -68,4 +72,3 @@ networks:
 * Make sure the assigned IP (`192.168.1.240` above) is not in use or managed by DHCP.
 * You may also use a node label constraint instead of `node.role == manager` for more control.
 
-

docs/FILE_PERMISSIONS.md

@@ -38,7 +38,27 @@ NetAlertX requires certain paths to be writable at runtime. These paths should b
 
 > All these paths will have **UID 20211 / GID 20211** inside the container. Files on the host will appear owned by `20211:20211`.
 
----
+## Running as `root`
+
+You can override the default PUID and PGID using environment variables:
+
+```yaml
+...
+  environment:
+      PUID: 20211                             # Runtime PUID override, set to 0 to run as root
+      PGID: 20211                             # Runtime PGID override
+...
+```
+
+To run as the root user, it usually looks like this (verify the IDs on your server first by executing `id root`):
+
+```yaml
+...
+  environment:
+      PUID: 0                             # Runtime PUID override, set to 0 to run as root
+      PGID: 100                           # Runtime PGID override
+...
+```
 
 ### Solution
 

docs/INSTALLATION.md

@@ -2,24 +2,24 @@
 
 ## Installation options
 
-NetAlertX can be installed several ways. The best supported option is Docker, followed by a supervised Home Assistant instance, as an Unraid app, and lastly, on bare metal. 
+NetAlertX can be installed several ways. The best supported option is Docker, followed by a supervised Home Assistant instance, as an Unraid app, and lastly, on bare metal.
 
-- [[Installation] Docker (recommended)](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_INSTALLATION.md) 
-- [[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://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) 
+- [[Installation] Docker (recommended)](https://docs.netalertx.com/DOCKER_INSTALLATION)
+- [[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)
 
 
 ## Help
 
-If facing issues, please spend a few minutes seraching. 
+If facing issues, please spend a few minutes seraching.
 
 - Check [common issues](./COMMON_ISSUES.md)
-- Have a look at [Community guides](./COMMUNITY_GUIDES.md) 
-- [Search closed or open issues or discussions](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue) 
+- Have a look at [Community guides](./COMMUNITY_GUIDES.md)
+- [Search closed or open issues or discussions](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue)
 - Check [Discord](https://discord.gg/NczTUTWyRr)
 
 > [!NOTE]
-> If you can't find a solution anywhere, ask in Discord if you think it's a quick question, otherwise open a new [issue](https://github.com/jokob-sk/NetAlertX/issues/new?template=setup-help.yml). Please fill in as much as possible to speed up the help process. 
+> If you can't find a solution anywhere, ask in Discord if you think it's a quick question, otherwise open a new [issue](https://github.com/jokob-sk/NetAlertX/issues/new?template=setup-help.yml). Please fill in as much as possible to speed up the help process.
 >
 

docs/MIGRATION.md

@@ -297,5 +297,5 @@ sudo chmod -R a+rwx /local_data_dir
 ```
 
 8. Start the container and verify everything works as expeexpected.
-9. Check the [Permissions -> Writable-paths](https://jokob-sk.github.io/NetAlertX/FILE_PERMISSIONS/#writable-paths) what directories to mount if you'd like to access the API or log files.
-   
+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.
+

docs/NETWORK_TREE.md

@@ -1,4 +1,4 @@
-## How to Set Up Your Network Page
+# How to Set Up Your Network Page
 
 The **Network** page lets you map how devices connect — visually and logically.
 It’s especially useful for planning infrastructure, assigning parent-child relationships, and spotting gaps.
@@ -99,6 +99,26 @@ You can confirm that `raspberrypi` now acts as a network device in two places:
 > This means devices with `devParentRelType` set to `nic` or `virtual` will not be shown.
 > All devices, regardless of relationship type, are always accessible in the **All devices** view.
 
+
+## Troubleshooting
+
+If the Network page doesn't load re-set your parent nodes. This can be done with [bulk-edit](./DEVICES_BULK_EDITING.md).
+
+1. [Backup your setup just in case](./BACKUPS.md)
+2. Navigate to **Maintenance -> Multi edit** ( (1), (2) )
+3. Add all devices (3) (clear the cache with the refresh button if you seem to be missing devices in the dropdown (4))
+4. Select None as parent node (5) and save (6)
+
+![Hover detail](./img/NETWORK_TREE/Network_tree_RESET.png)
+
+5. Find now your root Internet Node by searching for "Internet" in the My Devices view
+6. If not found, make sure the `INTRNT` plugin runs and creates the internet device
+7. If above fails, [create a manual device](./DEVICE_MANAGEMENT.md) with the MAC set to `Internet`
+
+![Hover detail](./img/NETWORK_TREE/Network_tree_MANUAL_INTERNET_NODE.png)
+
+7. You should be able to start again to configure your Network view.
+
 ---
 
 ## ✅ Summary

docs/PLUGINS_DEV_DATASOURCES.md

@@ -0,0 +1,378 @@
+# Plugin Data Sources
+
+Learn how to configure different data sources for your plugin.
+
+## Overview
+
+Data sources determine **where the plugin gets its data** and **what format it returns**. NetAlertX supports multiple data source types, each suited for different use cases.
+
+| Data Source | Type | Purpose | Returns | Example |
+|-------------|------|---------|---------|---------|
+| `script` | Code Execution | Execute Linux commands or Python scripts | Pipeline | Scan network, collect metrics, call APIs |
+| `app-db-query` | Database Query | Query the NetAlertX database | Result set | Show devices, open ports, recent events |
+| `sqlite-db-query` | External DB | Query external SQLite databases | Result set | PiHole database, external logs |
+| `template` | Template | Generate values from templates | Values | Initialize default settings |
+
+## Data Source: `script`
+
+Execute any Linux command or Python script and capture its output.
+
+### Configuration
+
+```json
+{
+  "data_source": "script",
+  "show_ui": true,
+  "mapped_to_table": "CurrentScan"
+}
+```
+
+### How It Works
+
+1. Command specified in `CMD` setting is executed
+2. Script writes results to `/tmp/log/plugins/last_result.<PREFIX>.log`
+3. Core reads file and parses pipe-delimited results
+4. Results inserted into database
+
+### Example: Simple Python Script
+
+```json
+{
+  "function": "CMD",
+  "type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
+  "default_value": "python3 /app/front/plugins/my_plugin/script.py",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Command"}]
+}
+```
+
+### Example: Bash Script
+
+```json
+{
+  "function": "CMD",
+  "default_value": "bash /app/front/plugins/my_plugin/script.sh",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Command"}]
+}
+```
+
+### Best Practices
+
+- **Always use absolute paths** (e.g., `/app/front/plugins/...`)
+- **Use `plugin_helper.py`** for output formatting
+- **Add timeouts** via `RUN_TIMEOUT` setting (default: 60s)
+- **Log errors** to `/tmp/log/plugins/<PREFIX>.log`
+- **Handle missing dependencies gracefully**
+
+### Output Format
+
+Must write to: `/tmp/log/plugins/last_result.<PREFIX>.log`
+
+Format: Pipe-delimited, 9 or 13 columns
+
+See [Plugin Data Contract](PLUGINS_DEV_DATA_CONTRACT.md) for exact format
+
+---
+
+## Data Source: `app-db-query`
+
+Query the NetAlertX SQLite database and display results.
+
+### Configuration
+
+```json
+{
+  "data_source": "app-db-query",
+  "show_ui": true,
+  "mapped_to_table": "CurrentScan"
+}
+```
+
+### How It Works
+
+1. SQL query specified in `CMD` setting is executed against `app.db`
+2. Results parsed according to column definitions
+3. Inserted into plugin display/database
+
+### SQL Query Requirements
+
+- Must return exactly **9 or 13 columns** matching the [data contract](PLUGINS_DEV_DATA_CONTRACT.md)
+- Column names must match (order matters!)
+- Must be **readable SQLite SQL** (not vendor-specific)
+
+### Example: Open Ports from Nmap
+
+```json
+{
+  "function": "CMD",
+  "type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
+  "default_value": "SELECT dv.devName as Object_PrimaryID, cast(dv.devLastIP as VARCHAR(100)) || ':' || cast(SUBSTR(ns.Port, 0, INSTR(ns.Port, '/')) as VARCHAR(100)) as Object_SecondaryID, datetime() as DateTime, ns.Service as Watched_Value1, ns.State as Watched_Value2, null as Watched_Value3, null as Watched_Value4, ns.Extra as Extra, dv.devMac as ForeignKey FROM (SELECT * FROM Nmap_Scan) ns LEFT JOIN (SELECT devName, devMac, devLastIP FROM Devices) dv ON ns.MAC = dv.devMac",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "SQL to run"}],
+  "description": [{"language_code": "en_us", "string": "This SQL query populates the plugin table"}]
+}
+```
+
+### Example: Recent Device Events
+
+```sql
+SELECT
+  e.EventValue as Object_PrimaryID,
+  d.devName as Object_SecondaryID,
+  e.EventDateTime as DateTime,
+  e.EventType as Watched_Value1,
+  d.devLastIP as Watched_Value2,
+  null as Watched_Value3,
+  null as Watched_Value4,
+  e.EventDetails as Extra,
+  d.devMac as ForeignKey
+FROM
+  Events e
+LEFT JOIN
+  Devices d ON e.DeviceMac = d.devMac
+WHERE
+  e.EventDateTime > datetime('now', '-24 hours')
+ORDER BY
+  e.EventDateTime DESC
+```
+
+See the [Database documentation](./DATABASE.md) for a list of common columns.
+
+---
+
+## Data Source: `sqlite-db-query`
+
+Query an **external SQLite database** mounted in the container.
+
+### Configuration
+
+First, define the database path in a setting:
+
+```json
+{
+  "function": "DB_PATH",
+  "type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
+  "default_value": "/etc/pihole/pihole-FTL.db",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Database path"}],
+  "description": [{"language_code": "en_us", "string": "Path to external SQLite database"}]
+}
+```
+
+Then set data source and query:
+
+```json
+{
+  "data_source": "sqlite-db-query",
+  "show_ui": true
+}
+```
+
+### How It Works
+
+1. External database file path specified in `DB_PATH` setting
+2. Database mounted at that path (e.g., via Docker volume)
+3. SQL query executed against external database using `EXTERNAL_<PREFIX>.` prefix
+4. Results returned in standard format
+
+### SQL Query Example: PiHole Data
+
+```json
+{
+  "function": "CMD",
+  "default_value": "SELECT hwaddr as Object_PrimaryID, cast('http://' || (SELECT ip FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1) as VARCHAR(100)) || ':' || cast(SUBSTR((SELECT name FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1), 0, INSTR((SELECT name FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1), '/')) as VARCHAR(100)) as Object_SecondaryID, datetime() as DateTime, macVendor as Watched_Value1, lastQuery as Watched_Value2, (SELECT name FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1) as Watched_Value3, null as Watched_Value4, '' as Extra, hwaddr as ForeignKey FROM EXTERNAL_PIHOLE.network WHERE hwaddr NOT LIKE 'ip-%' AND hwaddr <> '00:00:00:00:00:00'",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "SQL to run"}]
+}
+```
+
+### Key Points
+
+- **Prefix all external tables** with `EXTERNAL_<PREFIX>.`
+  - For PiHole (`PIHOLE` prefix): `EXTERNAL_PIHOLE.network`
+  - For custom database (`CUSTOM` prefix): `EXTERNAL_CUSTOM.my_table`
+- **Database must be valid SQLite**
+- **Path must be accessible** inside the container
+- **No columns beyond the data contract** required
+
+### Docker Volume Setup
+
+To mount external database in docker-compose:
+
+```yaml
+services:
+  netalertx:
+    volumes:
+      - /path/on/host/pihole-FTL.db:/etc/pihole/pihole-FTL.db:ro
+```
+
+---
+
+## Data Source: `template`
+
+Generate values from a template. Usually used for initialization and default settings.
+
+### Configuration
+
+```json
+{
+  "data_source": "template"
+}
+```
+
+### How It Works
+
+- **Not widely used** in standard plugins
+- Used internally for generating default values
+- Check `newdev_template` plugin for implementation example
+
+### Example: Default Device Template
+
+```json
+{
+  "function": "DEFAULT_DEVICE_PROPERTIES",
+  "type": {"dataType": "string", "elements": [{"elementType": "textarea", "elementOptions": [], "transformers": []}]},
+  "default_value": "type=Unknown|vendor=Unknown",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Default properties"}]
+}
+```
+
+---
+
+## Data Source: `plugin_type`
+
+Declare the plugin category. Controls where settings appear in the UI.
+
+### Configuration
+
+```json
+{
+  "data_source": "plugin_type",
+  "value": "scanner"
+}
+```
+
+### Supported Values
+
+| Value | Section | Purpose |
+|-------|---------|---------|
+| `scanner` | Device Scanners | Discovers devices on network |
+| `system` | System Plugins | Core system functionality |
+| `publisher` | Notification/Alert Plugins | Sends notifications/alerts |
+| `importer` | Data Importers | Imports devices from external sources |
+| `other` | Other Plugins | Miscellaneous functionality |
+
+### Example
+
+```json
+{
+  "settings": [
+    {
+      "function": "plugin_type",
+      "type": {"dataType": "string", "elements": []},
+      "default_value": "scanner",
+      "options": ["scanner"],
+      "data_source": "plugin_type",
+      "value": "scanner",
+      "localized": []
+    }
+  ]
+}
+```
+
+---
+
+## Execution Order
+
+Control plugin execution priority. Higher priority plugins run first.
+
+```json
+{
+  "execution_order": "Layer_0"
+}
+```
+
+### Levels (highest to lowest priority)
+
+- `Layer_0` - Highest priority (run first)
+- `Layer_1`
+- `Layer_2`
+- ...
+
+### Example: Device Discovery
+
+
+```json
+{
+  "code_name": "device_scanner",
+  "unique_prefix": "DEVSCAN",
+  "execution_order": "Layer_0",
+  "data_source": "script",
+  "mapped_to_table": "CurrentScan"
+}
+```
+
+---
+
+## Performance Considerations
+
+### Script Source
+- **Pros:** Flexible, can call external tools
+- **Cons:** Slower than database queries
+- **Optimization:** Add caching, use timeouts
+- **Default timeout:** 60 seconds (set `RUN_TIMEOUT`)
+
+### Database Query Source
+- **Pros:** Fast, native query optimization
+- **Cons:** Limited to SQL capabilities
+- **Optimization:** Use indexes, avoid complex joins
+- **Timeout:** Usually instant
+
+### External DB Query Source
+- **Pros:** Direct access to external data
+- **Cons:** Network latency, external availability
+- **Optimization:** Use indexes in external DB, selective queries
+- **Timeout:** Depends on DB response time
+
+---
+
+## Debugging Data Sources
+
+### Check Script Output
+
+```bash
+# Run script manually
+python3 /app/front/plugins/my_plugin/script.py
+
+# Check result file
+cat /tmp/log/plugins/last_result.MYPREFIX.log
+```
+
+### Test SQL Query
+
+```bash
+# Connect to app database
+sqlite3 /data/db/app.db
+
+# Run query
+sqlite> SELECT ... ;
+```
+
+### Monitor Execution
+
+```bash
+# Watch backend logs
+tail -f /tmp/log/stdout.log | grep -i "data_source\|MYPREFIX"
+```
+
+---
+
+## See Also
+
+- [Plugin Data Contract](PLUGINS_DEV_DATA_CONTRACT.md) - Output format specification
+- [Plugin Settings System](PLUGINS_DEV_SETTINGS.md) - How to define settings
+- [Quick Start Guide](PLUGINS_DEV_QUICK_START.md) - Create your first plugin
+- [Database Schema](DATABASE.md) - Available tables and columns
+- [Debugging Plugins](DEBUG_PLUGINS.md) - Troubleshooting data issues

docs/PLUGINS_DEV_DATA_CONTRACT.md

@@ -0,0 +1,253 @@
+# Plugin Data Contract
+
+This document specifies the exact interface between plugins and the NetAlertX core.
+
+> [!IMPORTANT]
+> Every plugin must output data in this exact format to be recognized and processed correctly.
+
+## Overview
+
+Plugins communicate with NetAlertX by writing results to a **pipe-delimited log file**. The core reads this file, parses the data, and processes it for notifications, device discovery, and data integration.
+
+**File Location:** `/tmp/log/plugins/last_result.<PREFIX>.log`
+
+**Format:** Pipe-delimited (`|`), one record per line
+
+**Required Columns:** 9 (mandatory) + up to 4 optional helper columns = 13 total
+
+## Column Specification
+
+> [!NOTE]
+> The order of columns is **FIXED** and cannot be changed. All 9 mandatory columns must be provided. If you use any optional column (`HelpVal1`), you must supply all optional columns (`HelpVal1` through `HelpVal4`).
+
+### Mandatory Columns (0–8)
+
+| Order | Column Name | Type | Required | Description |
+|-------|-------------|------|----------|-------------|
+| 0 | `Object_PrimaryID` | string | **YES** | The primary identifier for grouping. Examples: device MAC, hostname, service name, or any unique ID |
+| 1 | `Object_SecondaryID` | string | no | Secondary identifier for relationships (e.g., IP address, port, sub-ID). Use `null` if not needed |
+| 2 | `DateTime` | string | **YES** | Timestamp when the event/data was collected. Format: `YYYY-MM-DD HH:MM:SS` |
+| 3 | `Watched_Value1` | string | **YES** | Primary watched value. Changes trigger notifications. Examples: IP address, status, version |
+| 4 | `Watched_Value2` | string | no | Secondary watched value. Use `null` if not needed |
+| 5 | `Watched_Value3` | string | no | Tertiary watched value. Use `null` if not needed |
+| 6 | `Watched_Value4` | string | no | Quaternary watched value. Use `null` if not needed |
+| 7 | `Extra` | string | no | Any additional metadata to display in UI and notifications. Use `null` if not needed |
+| 8 | `ForeignKey` | string | no | Foreign key linking to parent object (usually MAC address for device relationship). Use `null` if not needed |
+
+### Optional Columns (9–12)
+
+| Order | Column Name | Type | Required | Description |
+|-------|-------------|------|----------|-------------|
+| 9 | `HelpVal1` | string | *conditional* | Helper value 1. If used, all help values must be supplied |
+| 10 | `HelpVal2` | string | *conditional* | Helper value 2. If used, all help values must be supplied |
+| 11 | `HelpVal3` | string | *conditional* | Helper value 3. If used, all help values must be supplied |
+| 12 | `HelpVal4` | string | *conditional* | Helper value 4. If used, all help values must be supplied |
+
+## Usage Guide
+
+### Empty/Null Values
+
+- Represent empty values as the literal string `null` (not Python `None`, SQL `NULL`, or empty string)
+- Example: `device_id|null|2023-01-02 15:56:30|status|null|null|null|null|null`
+
+### Watched Values
+
+**What are Watched Values?**
+
+Watched values are fields that the NetAlertX core monitors for **changes between scans**. When a watched value differs from the previous scan, it can trigger notifications.
+
+**How to use them:**
+
+- `Watched_Value1`: Always required; primary indicator of status/state
+- `Watched_Value2–4`: Optional; use for secondary/tertiary state information
+- Leave unused ones as `null`
+
+**Example:**
+
+- Device scanner: `Watched_Value1 = "online"` or `"offline"`
+- Port scanner: `Watched_Value1 = "80"` (port number), `Watched_Value2 = "open"` (state)
+- Service monitor: `Watched_Value1 = "200"` (HTTP status), `Watched_Value2 = "0.45"` (response time)
+
+### Foreign Key
+
+Use the `ForeignKey` column to link objects to a parent device by MAC address:
+
+```
+device_name|192.168.1.100|2023-01-02 15:56:30|online|null|null|null|Found on network|aa:bb:cc:dd:ee:ff
+                                                                                              ↑
+                                                                                        ForeignKey (MAC)
+```
+
+This allows NetAlertX to:
+
+- Display the object on the device details page
+- Send notifications when the parent device is involved
+- Link events across plugins
+
+## Examples
+
+### Valid Data (9 columns, minimal)
+
+```csv
+https://example.com|null|2023-01-02 15:56:30|200|null|null|null|null|null
+printer-hp-1|192.168.1.50|2023-01-02 15:56:30|online|50%|null|null|Last seen in office|aa:11:22:33:44:55
+gateway.local|null|2023-01-02 15:56:30|active|v2.1.5|null|null|Firmware version|null
+```
+
+### Valid Data (13 columns, with helpers)
+
+```csv
+service-api|192.168.1.100:8080|2023-01-02 15:56:30|200|45ms|true|null|Responding normally|aa:bb:cc:dd:ee:ff|extra1|extra2|extra3|extra4
+host-web-1|10.0.0.20|2023-01-02 15:56:30|active|256GB|online|ok|Production server|null|cpu:80|mem:92|disk:45|alerts:0
+```
+
+### Invalid Data (Common Errors)
+
+❌ **Missing required column** (only 8 separators instead of 8):
+```csv
+https://google.com|null|2023-01-02 15:56:30|200|0.7898||null|null
+                                                      ↑
+                                                  Missing pipe
+```
+
+❌ **Missing mandatory Watched_Value1** (column 3):
+```csv
+https://duckduckgo.com|192.168.1.1|2023-01-02 15:56:30|null|0.9898|null|null|Best|null
+                                                         ↑
+                                          Must not be null
+```
+
+❌ **Incomplete optional columns** (has HelpVal1 but missing HelpVal2–4):
+```csv
+device|null|2023-01-02 15:56:30|status|null|null|null|null|null|helper1
+                                                                    ↑
+                                                    Has helper but incomplete
+```
+
+✅ **Complete with helpers** (all 4 helpers provided):
+```csv
+device|null|2023-01-02 15:56:30|status|null|null|null|null|null|h1|h2|h3|h4
+```
+
+✅ **Complete without helpers** (9 columns exactly):
+```csv
+device|null|2023-01-02 15:56:30|status|null|null|null|null|null
+```
+
+## Using `plugin_helper.py`
+
+The easiest way to ensure correct output is to use the [`plugin_helper.py`](../front/plugins/plugin_helper.py) library:
+
+```python
+from plugin_helper import Plugin_Objects
+
+# Initialize with your plugin's prefix
+plugin_objects = Plugin_Objects("YOURPREFIX")
+
+# Add objects
+plugin_objects.add_object(
+    Object_PrimaryID="device_id",
+    Object_SecondaryID="192.168.1.1",
+    DateTime="2023-01-02 15:56:30",
+    Watched_Value1="online",
+    Watched_Value2=None,
+    Watched_Value3=None,
+    Watched_Value4=None,
+    Extra="Additional data",
+    ForeignKey="aa:bb:cc:dd:ee:ff",
+    HelpVal1=None,
+    HelpVal2=None,
+    HelpVal3=None,
+    HelpVal4=None
+)
+
+# Write results (handles formatting, sanitization, and file creation)
+plugin_objects.write_result_file()
+```
+
+The library automatically:
+
+- Validates data types
+- Sanitizes string values
+- Normalizes MAC addresses
+- Writes to the correct file location
+- Creates the file in `/tmp/log/plugins/last_result.<PREFIX>.log`
+
+## De-duplication
+
+The core runs **de-duplication once per hour** on the `Plugins_Objects` table:
+
+- **Duplicate Detection Key:** Combination of `Object_PrimaryID`, `Object_SecondaryID`, `Plugin` (auto-filled from `unique_prefix`), and `UserData`
+- **Resolution:** Oldest duplicate entries are removed, newest are kept
+- **Use Case:** Prevents duplicate notifications when the same object is detected multiple times
+
+## DateTime Format
+
+**Required Format:** `YYYY-MM-DD HH:MM:SS`
+
+**Examples:**
+- `2023-01-02 15:56:30` ✅
+- `2023-1-2 15:56:30` ❌ (missing leading zeros)
+- `2023-01-02T15:56:30` ❌ (wrong separator)
+- `15:56:30 2023-01-02` ❌ (wrong order)
+
+**Python Helper:**
+```python
+from datetime import datetime
+
+# Current time in correct format
+now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+# Output: "2023-01-02 15:56:30"
+```
+
+**Bash Helper:**
+```bash
+# Current time in correct format
+date '+%Y-%m-%d %H:%M:%S'
+# Output: 2023-01-02 15:56:30
+```
+
+## Validation Checklist
+
+Before writing your plugin's `script.py`, ensure:
+
+- [ ] **9 or 13 columns** in each output line (8 or 12 pipe separators)
+- [ ] **Mandatory columns filled:**
+  - Column 0: `Object_PrimaryID` (not null)
+  - Column 2: `DateTime` in `YYYY-MM-DD HH:MM:SS` format
+  - Column 3: `Watched_Value1` (not null)
+- [ ] **Null values as literal string** `null` (not empty string or special chars)
+- [ ] **No extra pipes or misaligned columns**
+- [ ] **If using optional helpers** (columns 9–12), all 4 must be present
+- [ ] **File written to** `/tmp/log/plugins/last_result.<PREFIX>.log`
+- [ ] **One record per line** (newline-delimited)
+- [ ] **No header row** (data only)
+
+## Debugging
+
+**View raw plugin output:**
+```bash
+cat /tmp/log/plugins/last_result.YOURPREFIX.log
+```
+
+**Check line count:**
+```bash
+wc -l /tmp/log/plugins/last_result.YOURPREFIX.log
+```
+
+**Validate column count (should be 8 or 12 pipes per line):**
+```bash
+cat /tmp/log/plugins/last_result.YOURPREFIX.log | awk -F'|' '{print NF}' | sort | uniq
+# Output: 9 (for minimal) or 13 (for with helpers)
+```
+
+**Check core processing in logs:**
+```bash
+tail -f /tmp/log/stdout.log | grep -i "YOURPREFIX\|Plugins_Objects"
+```
+
+## See Also
+
+- [Plugin Settings System](PLUGINS_DEV_SETTINGS.md) - How to accept user input
+- [Data Sources](PLUGINS_DEV_DATASOURCES.md) - Different data source types
+- [Debugging Plugins](DEBUG_PLUGINS.md) - Troubleshooting plugin issues

docs/PLUGINS_DEV_QUICK_START.md

@@ -0,0 +1,175 @@
+# Plugin Development Quick Start
+
+Get a working plugin up and running in 5 minutes.
+
+## Prerequisites
+
+- Read [Development Environment Setup Guide](./DEV_ENV_SETUP.md) to set up your local environment
+- Understand [Plugin Architecture Overview](PLUGINS_DEV.md)
+
+## Quick Start Steps
+
+### 1. Create Your Plugin Folder
+
+Start from the template to get the basic structure:
+
+```bash
+cd /workspaces/NetAlertX/front/plugins
+cp -r __template my_plugin
+cd my_plugin
+```
+
+### 2. Update `config.json` Identifiers
+
+Edit `my_plugin/config.json` and update these critical fields:
+
+```json
+{
+  "code_name": "my_plugin",
+  "unique_prefix": "MYPLN",
+  "display_name": [{"language_code": "en_us", "string": "My Plugin"}],
+  "description": [{"language_code": "en_us", "string": "My custom plugin"}]
+}
+```
+
+**Important:**
+- `code_name` must match the folder name
+- `unique_prefix` must be unique and uppercase (check existing plugins to avoid conflicts)
+- `unique_prefix` is used as a prefix for all generated settings (e.g., `MYPLN_RUN`, `MYPLN_CMD`)
+
+### 3. Implement Your Script
+
+Edit `my_plugin/script.py` and implement your data collection logic:
+
+```python
+#!/usr/bin/env python3
+
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../server'))
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../plugins'))
+
+from plugin_helper import Plugin_Objects, mylog
+from helper import get_setting_value
+from const import logPath
+
+pluginName = "MYPLN"
+
+LOG_PATH = logPath + "/plugins"
+LOG_FILE = os.path.join(LOG_PATH, f"script.{pluginName}.log")
+RESULT_FILE = os.path.join(LOG_PATH, f"last_result.{pluginName}.log")
+
+# Initialize
+plugin_objects = Plugin_Objects(RESULT_FILE)
+
+try:
+    # Your data collection logic here
+    # For example, scan something and collect results
+
+    # Add an object to results
+    plugin_objects.add_object(
+        Object_PrimaryID="example_id",
+        Object_SecondaryID=None,
+        DateTime="2023-01-02 15:56:30",
+        Watched_Value1="value1",
+        Watched_Value2=None,
+        Watched_Value3=None,
+        Watched_Value4=None,
+        Extra="additional_data",
+        ForeignKey=None
+    )
+
+    # Write results to the log file
+    plugin_objects.write_result_file()
+
+except Exception as e:
+    mylog("none", f"Error: {e}")
+    sys.exit(1)
+```
+
+### 4. Configure Execution
+
+Edit the `RUN` and `CMD` settings in `config.json`:
+
+```json
+{
+  "function": "RUN",
+  "type": {"dataType":"string", "elements": [{"elementType": "select", "elementOptions": [], "transformers": []}]},
+  "default_value": "disabled",
+  "options": ["disabled", "once", "schedule"],
+  "localized": ["name", "description"],
+  "name": [{"language_code":"en_us", "string": "When to run"}],
+  "description": [{"language_code":"en_us", "string": "Enable plugin execution"}]
+},
+{
+  "function": "CMD",
+  "type": {"dataType":"string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
+  "default_value": "python3 /app/front/plugins/my_plugin/script.py",
+  "localized": ["name", "description"],
+  "name": [{"language_code":"en_us", "string": "Command"}],
+  "description": [{"language_code":"en_us", "string": "Command to execute"}]
+}
+```
+
+### 5. Test Your Plugin
+
+#### In Dev Container
+
+```bash
+# Test the script directly
+python3 /workspaces/NetAlertX/front/plugins/my_plugin/script.py
+
+# Check the results
+cat /tmp/log/plugins/last_result.MYPLN.log
+```
+
+#### Via UI
+
+1. Restart backend: Run task `[Dev Container] Start Backend (Python)`
+2. Open Settings → Plugin Settings → My Plugin
+3. Set `My Plugin - When to run` to `once`
+4. Click Save
+5. Check `/tmp/log/plugins/last_result.MYPLN.log` for output
+
+### 6. Check Results
+
+Verify your plugin is working:
+
+```bash
+# Check if result file was generated
+ls -la /tmp/log/plugins/last_result.MYPLN.log
+
+# View contents
+cat /tmp/log/plugins/last_result.MYPLN.log
+
+# Check backend logs for errors
+tail -f /tmp/log/stdout.log | grep "my_plugin\|MYPLN"
+```
+
+## Next Steps
+
+Now that you have a working basic plugin:
+
+1. **Add Settings**: Customize behavior via user-configurable settings (see [PLUGINS_DEV_SETTINGS.md](PLUGINS_DEV_SETTINGS.md))
+2. **Implement Data Contract**: Structure your output correctly (see [PLUGINS_DEV_DATA_CONTRACT.md](PLUGINS_DEV_DATA_CONTRACT.md))
+3. **Configure UI**: Display plugin results in the web interface (see [PLUGINS_DEV_UI_COMPONENTS.md](PLUGINS_DEV_UI_COMPONENTS.md))
+4. **Map to Database**: Import data into NetAlertX tables like `CurrentScan` or `Devices`
+5. **Set Schedules**: Run your plugin on a schedule (see [PLUGINS_DEV_CONFIG.md](PLUGINS_DEV_CONFIG.md))
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "Module not found" errors | Ensure `sys.path` includes `/app/server` and `/app/front/plugins` |
+| Settings not appearing | Restart backend and clear browser cache |
+| Results not showing up | Check `/tmp/log/plugins/*.log` and `/tmp/log/stdout.log` for errors |
+| Permission denied | Plugin runs in container, use absolute paths like `/app/front/plugins/...` |
+
+## Resources
+
+- [Full Plugin Development Guide](PLUGINS_DEV.md)
+- [Plugin Data Contract](PLUGINS_DEV_DATA_CONTRACT.md)
+- [Plugin Settings System](PLUGINS_DEV_SETTINGS.md)
+- [Data Sources](PLUGINS_DEV_DATASOURCES.md)
+- [UI Components](PLUGINS_DEV_UI_COMPONENTS.md)
+- [Debugging Plugins](DEBUG_PLUGINS.md)

docs/PLUGINS_DEV_SETTINGS.md

@@ -0,0 +1,518 @@
+# Plugin Settings System
+
+Learn how to let users configure your plugin via the NetAlertX UI Settings page.
+
+> [!TIP]
+> For the higher-level settings flow and lifecycle, see [Settings System Documentation](./SETTINGS_SYSTEM.md).
+
+## Overview
+
+Plugin settings allow users to configure:
+
+- **Execution schedule** (when the plugin runs)
+- **Runtime parameters** (API keys, URLs, thresholds)
+- **Behavior options** (which features to enable/disable)
+- **Command overrides** (customize the executed script)
+
+All settings are defined in your plugin's `config.json` file under the `"settings"` array.
+
+## Setting Definition Structure
+
+Each setting is a JSON object with required and optional properties:
+
+```json
+{
+  "function": "UNIQUE_CODE",
+  "type": {
+    "dataType": "string",
+    "elements": [
+      {
+        "elementType": "input",
+        "elementOptions": [],
+        "transformers": []
+      }
+    ]
+  },
+  "default_value": "default_value_here",
+  "options": [],
+  "localized": ["name", "description"],
+  "name": [
+    {
+      "language_code": "en_us",
+      "string": "Display Name"
+    }
+  ],
+  "description": [
+    {
+      "language_code": "en_us",
+      "string": "Help text describing the setting"
+    }
+  ]
+}
+```
+
+## Required Properties
+
+| Property | Type | Description | Example |
+|----------|------|-------------|---------|
+| `function` | string | Unique identifier for the setting. Used in manifest and when reading values. See [Reserved Function Names](#reserved-function-names) for special values | `"MY_CUSTOM_SETTING"` |
+| `type` | object | Defines the UI component and data type | See [Component Types](#component-types) |
+| `default_value` | varies | Initial value shown in UI | `"https://example.com"` |
+| `localized` | array | Which properties have translations | `["name", "description"]` |
+| `name` | array | Display name in Settings UI (localized) | See [Localized Strings](#localized-strings) |
+| `description` | array | Help text in Settings UI (localized) | See [Localized Strings](#localized-strings) |
+
+## Optional Properties
+
+| Property | Type | Description | Example |
+|----------|------|-------------|---------|
+| `options` | array | Valid values for select/checkbox controls | `["option1", "option2"]` |
+| `events` | string | Trigger action button: `"test"` or `"run"` | `"test"` for notifications |
+| `maxLength` | number | Character limit for input fields | `100` |
+| `readonly` | boolean | Make field read-only | `true` |
+| `override_value` | object | Template-based value override (WIP) | Work in Progress |
+
+## Reserved Function Names
+
+These function names have special meaning and control core plugin behavior:
+
+### Core Execution Settings
+
+| Function | Purpose | Type | Required | Options |
+|----------|---------|------|----------|---------|
+| `RUN` | **When to execute the plugin** | select | **YES** | `"disabled"`, `"once"`, `"schedule"`, `"always_after_scan"`, `"before_name_updates"`, `"on_new_device"`, `"before_config_save"` |
+| `RUN_SCHD` | **Cron schedule** | input | If `RUN="schedule"` | Cron format: `"0 * * * *"` (hourly) |
+| `CMD` | **Command/script to execute** | input | **YES** | Linux command or path to script |
+| `RUN_TIMEOUT` | **Maximum execution time in seconds** | input | optional | Numeric: `"60"`, `"120"`, etc. |
+
+### Data & Filtering Settings
+
+| Function | Purpose | Type | Required | Options |
+|----------|---------|------|----------|---------|
+| `WATCH` | **Which columns to monitor for changes** | multi-select | optional | Column names from data contract |
+| `REPORT_ON` | **When to send notifications** | select | optional | `"new"`, `"watched-changed"`, `"watched-not-changed"`, `"missing-in-last-scan"` |
+| `DB_PATH` | **External database path** | input | If using SQLite plugin | File path: `"/etc/pihole/pihole-FTL.db"` |
+
+### API & Data Settings
+
+| Function | Purpose | Type | Required | Options |
+|----------|---------|------|----------|---------|
+| `API_SQL` | **Generate API JSON file** | (reserved) | Not implemented | — |
+
+## Component Types
+
+### Text Input
+
+Simple text field for API keys, URLs, thresholds, etc.
+
+```json
+{
+  "function": "URL",
+  "type": {
+    "dataType": "string",
+    "elements": [
+      {
+        "elementType": "input",
+        "elementOptions": [],
+        "transformers": []
+      }
+    ]
+  },
+  "default_value": "https://api.example.com",
+  "localized": ["name", "description"],
+  "name": [{"language_code": "en_us", "string": "API URL"}],
+  "description": [{"language_code": "en_us", "string": "The API endpoint to query"}]
+}
+```
+
+### Password Input
+
+Secure field with SHA256 hashing transformer.
+
+```json
+{
+  "function": "API_KEY",
+  "type": {
+    "dataType": "string",
+    "elements": [
+      {
+        "elementType": "input",
+        "elementOptions": [{"type": "password"}],
+        "transformers": ["sha256"]
+      }
+    ]
+  },
+  "default_value": "",
+  "localized": ["name", "description"],
+  "name": [{"language_code": "en_us", "string": "API Key"}],
+  "description": [{"language_code": "en_us", "string": "Stored securely with SHA256 hashing"}]
+}
+```
+
+### Dropdown/Select
+
+Choose from predefined options.
+
+```json
+{
+  "function": "RUN",
+  "type": {
+    "dataType": "string",
+    "elements": [
+      {
+        "elementType": "select",
+        "elementOptions": [],
+        "transformers": []
+      }
+    ]
+  },
+  "default_value": "disabled",
+  "options": ["disabled", "once", "schedule", "always_after_scan"],
+  "localized": ["name", "description"],
+  "name": [{"language_code": "en_us", "string": "When to run"}],
+  "description": [{"language_code": "en_us", "string": "Select execution trigger"}]
+}
+```
+
+### Multi-Select
+
+Select multiple values (returns array).
+
+```json
+{
+  "function": "WATCH",
+  "type": {
+    "dataType": "array",
+    "elements": [
+      {
+        "elementType": "select",
+        "elementOptions": [{"isMultiSelect": true}],
+        "transformers": []
+      }
+    ]
+  },
+  "default_value": [],
+  "options": ["Status", "IP_Address", "Response_Time"],
+  "localized": ["name", "description"],
+  "name": [{"language_code": "en_us", "string": "Watch columns"}],
+  "description": [{"language_code": "en_us", "string": "Which columns trigger notifications on change"}]
+}
+```
+
+### Checkbox
+
+Boolean toggle.
+
+```json
+{
+  "function": "ENABLED",
+  "type": {
+    "dataType": "boolean",
+    "elements": [
+      {
+        "elementType": "input",
+        "elementOptions": [{"type": "checkbox"}],
+        "transformers": []
+      }
+    ]
+  },
+  "default_value": false,
+  "localized": ["name", "description"],
+  "name": [{"language_code": "en_us", "string": "Enable feature"}],
+  "description": [{"language_code": "en_us", "string": "Toggle this feature on/off"}]
+}
+```
+
+### Textarea
+
+Multi-line text input.
+
+```json
+{
+  "function": "CUSTOM_CONFIG",
+  "type": {
+    "dataType": "string",
+    "elements": [
+      {
+        "elementType": "textarea",
+        "elementOptions": [],
+        "transformers": []
+      }
+    ]
+  },
+  "default_value": "",
+  "localized": ["name", "description"],
+  "name": [{"language_code": "en_us", "string": "Custom Configuration"}],
+  "description": [{"language_code": "en_us", "string": "Enter configuration (one per line)"}]
+}
+```
+
+### Read-Only Label
+
+Display information without user input.
+
+```json
+{
+  "function": "STATUS_DISPLAY",
+  "type": {
+    "dataType": "string",
+    "elements": [
+      {
+        "elementType": "input",
+        "elementOptions": [{"readonly": true}],
+        "transformers": []
+      }
+    ]
+  },
+  "default_value": "Ready",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Status"}]
+}
+```
+
+## Using Settings in Your Script
+
+### Method 1: Via `get_setting_value()` Helper
+
+**Recommended approach** — clean and simple:
+
+```python
+from helper import get_setting_value
+
+# Read the setting by function name with plugin prefix
+api_url = get_setting_value('MYPLN_API_URL')
+api_key = get_setting_value('MYPLN_API_KEY')
+watch_columns = get_setting_value('MYPLN_WATCH')  # Returns list if multi-select
+
+# Use in your script
+mylog("none", f"Connecting to {api_url} with key {api_key}")
+```
+
+### Method 2: Via Command Parameters
+
+For more complex scenarios where you need to **pass settings as command-line arguments**:
+
+Define `params` in your `config.json`:
+
+```json
+{
+  "params": [
+    {
+      "name": "api_url",
+      "type": "setting",
+      "value": "MYPLN_API_URL"
+    },
+    {
+      "name": "timeout",
+      "type": "setting",
+      "value": "MYPLN_RUN_TIMEOUT"
+    }
+  ]
+}
+```
+
+Update your `CMD` setting:
+
+```json
+{
+  "function": "CMD",
+  "default_value": "python3 /app/front/plugins/my_plugin/script.py --url={api_url} --timeout={timeout}"
+}
+```
+
+The framework will replace `{api_url}` and `{timeout}` with actual values before execution.
+
+### Method 3: Via Environment Variables (check with maintainer)
+
+Settings are also available as environment variables:
+
+```bash
+# Environment variable format: <PREFIX>_<FUNCTION>
+MY_PLUGIN_API_URL
+MY_PLUGIN_API_KEY
+MY_PLUGIN_RUN
+```
+
+In Python:
+```python
+import os
+
+api_url = os.environ.get('MYPLN_API_URL', 'default_value')
+```
+
+## Localized Strings
+
+Settings and UI text support multiple languages. Define translations in the `name` and `description` arrays:
+
+```json
+{
+  "localized": ["name", "description"],
+  "name": [
+    {
+      "language_code": "en_us",
+      "string": "API URL"
+    },
+    {
+      "language_code": "es_es",
+      "string": "URL de API"
+    },
+    {
+      "language_code": "de_de",
+      "string": "API-URL"
+    }
+  ],
+  "description": [
+    {
+      "language_code": "en_us",
+      "string": "Enter the API endpoint URL"
+    },
+    {
+      "language_code": "es_es",
+      "string": "Ingrese la URL del endpoint de API"
+    },
+    {
+      "language_code": "de_de",
+      "string": "Geben Sie die API-Endpunkt-URL ein"
+    }
+  ]
+}
+```
+
+- `en_us` - English (required)
+
+
+## Examples
+
+### Example 1: Website Monitor Plugin
+
+```json
+{
+  "settings": [
+    {
+      "function": "RUN",
+      "type": {"dataType": "string", "elements": [{"elementType": "select", "elementOptions": [], "transformers": []}]},
+      "default_value": "disabled",
+      "options": ["disabled", "once", "schedule"],
+      "localized": ["name", "description"],
+      "name": [{"language_code": "en_us", "string": "When to run"}],
+      "description": [{"language_code": "en_us", "string": "Enable website monitoring"}]
+    },
+    {
+      "function": "RUN_SCHD",
+      "type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
+      "default_value": "*/5 * * * *",
+      "localized": ["name", "description"],
+      "name": [{"language_code": "en_us", "string": "Schedule"}],
+      "description": [{"language_code": "en_us", "string": "Cron format (default: every 5 minutes)"}]
+    },
+    {
+      "function": "CMD",
+      "type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
+      "default_value": "python3 /app/front/plugins/website_monitor/script.py urls={urls}",
+      "localized": ["name", "description"],
+      "name": [{"language_code": "en_us", "string": "Command"}],
+      "description": [{"language_code": "en_us", "string": "Command to execute"}]
+    },
+    {
+      "function": "RUN_TIMEOUT",
+      "type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
+      "default_value": "60",
+      "localized": ["name", "description"],
+      "name": [{"language_code": "en_us", "string": "Timeout"}],
+      "description": [{"language_code": "en_us", "string": "Maximum execution time in seconds"}]
+    },
+    {
+      "function": "URLS",
+      "type": {"dataType": "array", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
+      "default_value": ["https://example.com"],
+      "maxLength": 200,
+      "localized": ["name", "description"],
+      "name": [{"language_code": "en_us", "string": "URLs to monitor"}],
+      "description": [{"language_code": "en_us", "string": "One URL per line"}]
+    },
+    {
+      "function": "WATCH",
+      "type": {"dataType": "array", "elements": [{"elementType": "select", "elementOptions": [{"isMultiSelect": true}], "transformers": []}]},
+      "default_value": ["Status_Code"],
+      "options": ["Status_Code", "Response_Time", "Certificate_Expiry"],
+      "localized": ["name", "description"],
+      "name": [{"language_code": "en_us", "string": "Watch columns"}],
+      "description": [{"language_code": "en_us", "string": "Which changes trigger notifications"}]
+    }
+  ]
+}
+```
+
+### Example 2: PiHole Integration Plugin
+
+```json
+{
+  "settings": [
+    {
+      "function": "RUN",
+      "type": {"dataType": "string", "elements": [{"elementType": "select", "elementOptions": [], "transformers": []}]},
+      "default_value": "disabled",
+      "options": ["disabled", "schedule"],
+      "localized": ["name", "description"],
+      "name": [{"language_code": "en_us", "string": "When to run"}],
+      "description": [{"language_code": "en_us", "string": "Enable PiHole integration"}]
+    },
+    {
+      "function": "DB_PATH",
+      "type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
+      "default_value": "/etc/pihole/pihole-FTL.db",
+      "localized": ["name", "description"],
+      "name": [{"language_code": "en_us", "string": "Database path"}],
+      "description": [{"language_code": "en_us", "string": "Path to pihole-FTL.db inside container"}]
+    },
+    {
+      "function": "API_KEY",
+      "type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [{"type": "password"}], "transformers": ["sha256"]}]},
+      "default_value": "",
+      "localized": ["name", "description"],
+      "name": [{"language_code": "en_us", "string": "API Key"}],
+      "description": [{"language_code": "en_us", "string": "PiHole API key (optional, stored securely)"}]
+    }
+  ]
+}
+```
+
+## Validation & Testing
+
+### Check Settings Are Recognized
+
+After saving your `config.json`:
+
+1. Restart the backend: Run task `[Dev Container] Start Backend (Python)`
+2. Open Settings page in UI
+3. Navigate to Plugin Settings
+4. Look for your plugin's settings
+
+### Read Setting Values in Script
+
+Test that values are accessible:
+
+```python
+from helper import get_setting_value
+
+# Try to read a setting
+value = get_setting_value('MYPLN_API_URL')
+mylog('none', f"Setting value: {value}")
+
+# Should print the user-configured value or default
+```
+
+### Debug Settings
+
+Check backend logs:
+
+```bash
+tail -f /tmp/log/stdout.log | grep -i "setting\|MYPLN"
+```
+
+## See Also
+
+- [Settings System Documentation](./SETTINGS_SYSTEM.md) - Full settings flow and lifecycle
+- [Quick Start Guide](PLUGINS_DEV_QUICK_START.md) - Get a working plugin quickly
+- [Plugin Data Contract](PLUGINS_DEV_DATA_CONTRACT.md) - Output data format
+- [UI Components](PLUGINS_DEV_UI_COMPONENTS.md) - Display plugin results

docs/PLUGINS_DEV_UI_COMPONENTS.md

@@ -0,0 +1,646 @@
+# Plugin UI Components
+
+Configure how your plugin's data is displayed in the NetAlertX web interface.
+
+## Overview
+
+Plugin results are displayed in the UI via the **Plugins page** and **Device details tabs**. You control the appearance and functionality of these displays by defining `database_column_definitions` in your plugin's `config.json`.
+
+Each column definition specifies:
+- Which data field to display
+- How to render it (label, link, color-coded badge, etc.)
+- What CSS classes to apply
+- What transformations to apply (regex, string replacement, etc.)
+
+## Column Definition Structure
+
+```json
+{
+  "column": "Object_PrimaryID",
+  "mapped_to_column": "devMac",
+  "mapped_to_column_data": null,
+  "css_classes": "col-sm-2",
+  "show": true,
+  "type": "device_mac",
+  "default_value": "",
+  "options": [],
+  "options_params": [],
+  "localized": ["name"],
+  "name": [
+    {
+      "language_code": "en_us",
+      "string": "MAC Address"
+    }
+  ]
+}
+```
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `column` | string | **YES** | Source column name from data contract (e.g., `Object_PrimaryID`, `Watched_Value1`) |
+| `mapped_to_column` | string | no | Target database column if mapping to a table like `CurrentScan` |
+| `mapped_to_column_data` | object | no | Static value to map instead of using column data |
+| `css_classes` | string | no | Bootstrap CSS classes for width/spacing (e.g., `"col-sm-2"`, `"col-sm-6"`) |
+| `show` | boolean | **YES** | Whether to display in UI (must be `true` to appear) |
+| `type` | string | **YES** | How to render the value (see [Render Types](#render-types)) |
+| `default_value` | varies | **YES** | Default if column is empty |
+| `options` | array | no | Options for `select`/`threshold`/`replace`/`regex` types |
+| `options_params` | array | no | Dynamic options from SQL or settings |
+| `localized` | array | **YES** | Which properties need translations (e.g., `["name", "description"]`) |
+| `name` | array | **YES** | Display name in UI (localized strings) |
+| `description` | array | no | Help text in UI (localized strings) |
+| `maxLength` | number | no | Character limit for input fields |
+
+## Render Types
+
+### Display-Only Types
+
+These render as read-only display elements:
+
+#### `label`
+Plain text display (read-only).
+
+```json
+{
+  "column": "Watched_Value1",
+  "show": true,
+  "type": "label",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Status"}]
+}
+```
+
+**Output:** `online`
+
+---
+
+#### `device_mac`
+Renders as a clickable link to the device with the given MAC address.
+
+```json
+{
+  "column": "ForeignKey",
+  "show": true,
+  "type": "device_mac",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Device"}]
+}
+```
+
+**Input:** `aa:bb:cc:dd:ee:ff`
+**Output:** Clickable link to device details page
+
+---
+
+#### `device_ip`
+Resolves an IP address to a MAC address and creates a device link.
+
+```json
+{
+  "column": "Object_SecondaryID",
+  "show": true,
+  "type": "device_ip",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Host"}]
+}
+```
+
+**Input:** `192.168.1.100`
+**Output:** Link to device with that IP (if known)
+
+---
+
+#### `device_name_mac`
+Creates a device link with the target device's name as the link label.
+
+```json
+{
+  "column": "Object_PrimaryID",
+  "show": true,
+  "type": "device_name_mac",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Device Name"}]
+}
+```
+
+**Input:** `aa:bb:cc:dd:ee:ff`
+**Output:** Device name (clickable link to device)
+
+---
+
+#### `url`
+Renders as a clickable HTTP/HTTPS link.
+
+```json
+{
+  "column": "Watched_Value1",
+  "show": true,
+  "type": "url",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Endpoint"}]
+}
+```
+
+**Input:** `https://example.com/api`
+**Output:** Clickable link
+
+---
+
+#### `url_http_https`
+Creates two links (HTTP and HTTPS) as lock icons for the given IP/hostname.
+
+```json
+{
+  "column": "Object_SecondaryID",
+  "show": true,
+  "type": "url_http_https",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Web Links"}]
+}
+```
+
+**Input:** `192.168.1.50`
+**Output:** 🔓 HTTP link | 🔒 HTTPS link
+
+---
+
+#### `textarea_readonly`
+Multi-line read-only display with newlines preserved.
+
+```json
+{
+  "column": "Extra",
+  "show": true,
+  "type": "textarea_readonly",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Details"}]
+}
+```
+
+---
+
+### Interactive Types
+
+#### `textbox_save`
+User-editable text box that persists changes to the database (typically `UserData` column).
+
+```json
+{
+  "column": "UserData",
+  "show": true,
+  "type": "textbox_save",
+  "default_value": "",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Notes"}]
+}
+```
+
+---
+
+### Styled/Transformed Types
+
+#### `label` with `threshold`
+
+Color-codes values based on ranges. Useful for status codes, latency, capacity percentages.
+
+```json
+{
+  "column": "Watched_Value1",
+  "show": true,
+  "type": "threshold",
+  "options": [
+    {
+      "maximum": 199,
+      "hexColor": "#792D86"  // Purple for <199
+    },
+    {
+      "maximum": 299,
+      "hexColor": "#5B862D"  // Green for 200-299
+    },
+    {
+      "maximum": 399,
+      "hexColor": "#7D862D"  // Orange for 300-399
+    },
+    {
+      "maximum": 499,
+      "hexColor": "#BF6440"  // Red-orange for 400-499
+    },
+    {
+      "maximum": 999,
+      "hexColor": "#D33115"  // Dark red for 500+
+    }
+  ],
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "HTTP Status"}]
+}
+```
+
+**How it works:**
+
+- Value `150` → Purple (≤199)
+- Value `250` → Green (≤299)
+- Value `350` → Orange (≤399)
+- Value `450` → Red-orange (≤499)
+- Value `550` → Dark red (>500)
+
+---
+
+#### `replace`
+Replaces specific values with display strings or HTML.
+
+```json
+{
+  "column": "Watched_Value2",
+  "show": true,
+  "type": "replace",
+  "options": [
+    {
+      "equals": "online",
+      "replacement": "<i class='fa-solid fa-circle' style='color: green;'></i> Online"
+    },
+    {
+      "equals": "offline",
+      "replacement": "<i class='fa-solid fa-circle' style='color: red;'></i> Offline"
+    },
+    {
+      "equals": "idle",
+      "replacement": "<i class='fa-solid fa-circle' style='color: yellow;'></i> Idle"
+    }
+  ],
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Status"}]
+}
+```
+
+**Output Examples:**
+- `"online"` → 🟢 Online
+- `"offline"` → 🔴 Offline
+- `"idle"` → 🟡 Idle
+
+---
+
+#### `regex`
+Applies a regular expression to extract/transform values.
+
+```json
+{
+  "column": "Watched_Value1",
+  "show": true,
+  "type": "regex",
+  "options": [
+    {
+      "type": "regex",
+      "param": "([0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3})"
+    }
+  ],
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "IP Address"}]
+}
+```
+
+- **Input:** `Host: 192.168.1.100 Port: 8080`
+- **Output:** `192.168.1.100`
+
+---
+
+#### `eval`
+Evaluates JavaScript code with access to the column value (use `${value}` or `{value}`).
+
+```json
+{
+  "column": "Watched_Value1",
+  "show": true,
+  "type": "eval",
+  "default_value": "",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Formatted Value"}]
+}
+```
+
+**Example with custom formatting:**
+```json
+{
+  "column": "Watched_Value1",
+  "show": true,
+  "type": "eval",
+  "options": [
+    {
+      "type": "eval",
+      "param": "`<b>${value}</b> units`"
+    }
+  ],
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Value with Units"}]
+}
+```
+
+- **Input:** `42`
+- **Output:** **42** units
+
+---
+
+### Chaining Types
+
+You can chain multiple transformations with dot notation:
+
+```json
+{
+  "column": "Watched_Value3",
+  "show": true,
+  "type": "regex.url_http_https",
+  "options": [
+    {
+      "type": "regex",
+      "param": "([\\d.:]+)"  // Extract IP/host
+    }
+  ],
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "HTTP/S Links"}]
+}
+```
+
+**Flow:**
+
+1. Apply regex to extract `192.168.1.50` from input
+2. Create HTTP/HTTPS links for that host
+
+---
+
+## Dynamic Options
+
+### SQL-Driven Select
+
+Use SQL query results to populate dropdown options:
+
+```json
+{
+  "column": "Watched_Value2",
+  "show": true,
+  "type": "select",
+  "options": ["{value}"],
+  "options_params": [
+    {
+      "name": "value",
+      "type": "sql",
+      "value": "SELECT devType as id, devType as name FROM Devices UNION SELECT 'Unknown' as id, 'Unknown' as name ORDER BY id"
+    }
+  ],
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Device Type"}]
+}
+```
+
+The SQL query must return exactly **2 columns:**
+
+- **First column (id):** Option value
+- **Second column (name):** Display label
+
+---
+
+### Setting-Driven Select
+
+Use plugin settings to populate options:
+
+```json
+{
+  "column": "Watched_Value1",
+  "show": true,
+  "type": "select",
+  "options": ["{value}"],
+  "options_params": [
+    {
+      "name": "value",
+      "type": "setting",
+      "value": "MYPLN_AVAILABLE_STATUSES"
+    }
+  ],
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Status"}]
+}
+```
+
+---
+
+## Mapping to Database Tables
+
+### Mapping to `CurrentScan`
+
+To import plugin data into the device scan pipeline (for notifications, heuristics, etc.):
+
+1. Add `"mapped_to_table": "CurrentScan"` at the root level of `config.json`
+2. Add `"mapped_to_column"` property to each column definition
+
+```json
+{
+  "code_name": "my_device_scanner",
+  "unique_prefix": "MYSCAN",
+  "mapped_to_table": "CurrentScan",
+  "database_column_definitions": [
+    {
+      "column": "Object_PrimaryID",
+      "mapped_to_column": "cur_MAC",
+      "show": true,
+      "type": "device_mac",
+      "localized": ["name"],
+      "name": [{"language_code": "en_us", "string": "MAC Address"}]
+    },
+    {
+      "column": "Object_SecondaryID",
+      "mapped_to_column": "cur_IP",
+      "show": true,
+      "type": "device_ip",
+      "localized": ["name"],
+      "name": [{"language_code": "en_us", "string": "IP Address"}]
+    },
+    {
+      "column": "NameDoesntMatter",
+      "mapped_to_column": "cur_ScanMethod",
+      "mapped_to_column_data": {
+        "value": "MYSCAN"
+      },
+      "show": true,
+      "type": "label",
+      "localized": ["name"],
+      "name": [{"language_code": "en_us", "string": "Scan Method"}]
+    }
+  ]
+}
+```
+
+---
+
+### Using Static Values
+
+Use `mapped_to_column_data` to map a static value instead of reading from a column:
+
+```json
+{
+  "column": "NameDoesntMatter",
+  "mapped_to_column": "cur_ScanMethod",
+  "mapped_to_column_data": {
+    "value": "MYSCAN"
+  },
+  "show": true,
+  "type": "label",
+  "localized": ["name"],
+  "name": [{"language_code": "en_us", "string": "Discovery Method"}]
+}
+```
+
+This always sets `cur_ScanMethod` to `"MYSCAN"` regardless of column data.
+
+---
+
+## Filters
+
+Control which rows are displayed based on filter conditions. Filters are applied on the client-side in JavaScript.
+
+```json
+{
+  "data_filters": [
+    {
+      "compare_column": "Object_PrimaryID",
+      "compare_operator": "==",
+      "compare_field_id": "txtMacFilter",
+      "compare_js_template": "'{value}'.toString()",
+      "compare_use_quotes": true
+    }
+  ]
+}
+```
+
+| Property | Description |
+|----------|-------------|
+| `compare_column` | The column from plugin results to compare (left side) |
+| `compare_operator` | JavaScript operator: `==`, `!=`, `<`, `>`, `<=`, `>=`, `includes`, `startsWith` |
+| `compare_field_id` | HTML input field ID containing the filter value (right side) |
+| `compare_js_template` | JavaScript template to transform values. Use `{value}` placeholder |
+| `compare_use_quotes` | If `true`, wrap result in quotes for string comparison |
+
+**Example: Filter by MAC address**
+
+```json
+{
+  "data_filters": [
+    {
+      "compare_column": "ForeignKey",
+      "compare_operator": "==",
+      "compare_field_id": "txtMacFilter",
+      "compare_js_template": "'{value}'.toString()",
+      "compare_use_quotes": true
+    }
+  ]
+}
+```
+
+When viewing a device detail page, the `txtMacFilter` field is populated with that device's MAC, and only rows where `ForeignKey == MAC` are shown.
+
+---
+
+## Example: Complete Column Definitions
+
+```json
+{
+  "database_column_definitions": [
+    {
+      "column": "Object_PrimaryID",
+      "mapped_to_column": "cur_MAC",
+      "css_classes": "col-sm-2",
+      "show": true,
+      "type": "device_mac",
+      "default_value": "",
+      "localized": ["name"],
+      "name": [{"language_code": "en_us", "string": "MAC Address"}]
+    },
+    {
+      "column": "Object_SecondaryID",
+      "mapped_to_column": "cur_IP",
+      "css_classes": "col-sm-2",
+      "show": true,
+      "type": "device_ip",
+      "default_value": "unknown",
+      "localized": ["name"],
+      "name": [{"language_code": "en_us", "string": "IP Address"}]
+    },
+    {
+      "column": "DateTime",
+      "css_classes": "col-sm-2",
+      "show": true,
+      "type": "label",
+      "default_value": "",
+      "localized": ["name"],
+      "name": [{"language_code": "en_us", "string": "Last Seen"}]
+    },
+    {
+      "column": "Watched_Value1",
+      "css_classes": "col-sm-2",
+      "show": true,
+      "type": "threshold",
+      "options": [
+        {"maximum": 199, "hexColor": "#792D86"},
+        {"maximum": 299, "hexColor": "#5B862D"},
+        {"maximum": 399, "hexColor": "#7D862D"},
+        {"maximum": 499, "hexColor": "#BF6440"},
+        {"maximum": 999, "hexColor": "#D33115"}
+      ],
+      "localized": ["name"],
+      "name": [{"language_code": "en_us", "string": "HTTP Status"}]
+    },
+    {
+      "column": "Watched_Value2",
+      "css_classes": "col-sm-1",
+      "show": true,
+      "type": "label",
+      "default_value": "",
+      "localized": ["name"],
+      "name": [{"language_code": "en_us", "string": "Response Time"}]
+    },
+    {
+      "column": "Extra",
+      "css_classes": "col-sm-3",
+      "show": true,
+      "type": "textarea_readonly",
+      "default_value": "",
+      "localized": ["name"],
+      "name": [{"language_code": "en_us", "string": "Additional Info"}]
+    }
+  ]
+}
+```
+
+---
+
+## CSS Classes
+
+Use Bootstrap grid classes to control column widths in tables:
+
+| Class | Width | Usage |
+|-------|-------|-------|
+| `col-sm-1` | ~8% | Very narrow (icons, status) |
+| `col-sm-2` | ~16% | Narrow (MACs, IPs) |
+| `col-sm-3` | ~25% | Medium (names, URLs) |
+| `col-sm-4` | ~33% | Medium-wide (descriptions) |
+| `col-sm-6` | ~50% | Wide (large content) |
+
+---
+
+## Validation Checklist
+
+- [ ] All columns have `"show": true` or `false`
+- [ ] Display columns with `"type"` specified from supported types
+- [ ] Localized strings include at least `en_us`
+- [ ] `mapped_to_column` matches target table schema (if using mapping)
+- [ ] Options/thresholds have correct structure
+- [ ] CSS classes are valid Bootstrap grid classes
+- [ ] Chaining types (e.g., `regex.url_http_https`) are supported combinations
+
+---
+
+## See Also
+
+- [Plugin Data Contract](PLUGINS_DEV_DATA_CONTRACT.md) - What data fields are available
+- [Plugin Settings System](PLUGINS_DEV_SETTINGS.md) - Configure user input
+- [Database Mapping](PLUGINS_DEV.md#-mapping-the-plugin-results-into-a-database-table) - Map data to core tables
+- [Debugging Plugins](DEBUG_PLUGINS.md) - Troubleshoot display issues

docs/PUID_PGID_SECURITY.md

@@ -0,0 +1,30 @@
+# PUID/PGID Security — Why the entrypoint requires numeric IDs
+
+## Purpose
+
+This short document explains the security rationale behind the root-priming entrypoint's validation of runtime user IDs (`PUID`) and group IDs (`PGID`). The validation is intentionally strict and is a safety measure to prevent environment-variable-based command injection when running as root during the initial priming stage.
+
+## Key points
+
+- The entrypoint accepts only values that are strictly numeric (digits only). Non-numeric values are treated as malformed and are a fatal error.
+- The fatal check exists to prevent *injection* or accidental shell interpretation of environment values while the container runs as root (e.g., `PUID="20211 && rm -rf /"`).
+- There is **no artificial upper bound** enforced by the validation — any numeric UID/GID is valid (for example, `100000` is acceptable).
+
+## Behavior on malformed input
+
+- If `PUID` or `PGID` cannot be parsed as numeric (digits-only), the entrypoint prints an explicit security message to stderr and exits with a non-zero status.
+- This is a deliberate, conservative safety measure — we prefer failing fast on potentially dangerous input rather than continuing with root-privileged operations.
+
+## Operator guidance
+
+- Always supply numeric values for `PUID` and `PGID` in your environment (via `docker-compose.yml`, `docker run -e`, or equivalent). Example: `PUID=20211`.
+- If you need to run with a high-numbered UID/GID (e.g., `100000`), that is fine — the entrypoint allows it as long as the value is numeric.
+- Don’t pass shell meta-characters, spaces, or compound commands in `PUID` or `PGID` — those will be rejected as malformed and cause the container to exit.
+
+## Related docs
+
+- See `docs/docker-troubleshooting/file-permissions.md` for general permission troubleshooting and guidance about setting `PUID`/`PGID`.
+
+---
+
+*Document created to clarify the security behavior of the root-priming entrypoint (PUID/PGID validation).*

docs/REVERSE_PROXY.md

@@ -1,5 +1,17 @@
 # Reverse Proxy Configuration
 
+> [!NOTE]
+> This is community-contributed. Due to environment, setup, or networking differences, results may vary. Please open a PR to improve it instead of creating an issue, as the maintainer is not actively maintaining it.
+
+
+> [!TIP]
+> You will need to specify the `BACKEND_API_URL` setting if you are running reverse proxies. This is the URL that points to the backend server url (including your `GRAPHQL_PORT`)
+>
+> ![BACKEND_API_URL setting](./img/REVERSE_PROXY/BACKEND_API_URL.png)
+> ![NPM set up](./img/REVERSE_PROXY/nginx_proxy_manager_npm.png)
+
+## NGINX HTTP Configuration (Direct Path)
+
 > Submitted by amazing [cvc90](https://github.com/cvc90) 🙏
 
 > [!NOTE]
@@ -10,8 +22,6 @@
 
 <br/>
 
-## NGINX HTTP Configuration (Direct Path)
-
 1. On your NGINX server, create a new file called /etc/nginx/sites-available/netalertx
 
 2. In this file, paste the following code:
@@ -502,3 +512,888 @@ Mapping the updated file (on the local filesystem at `/appl/docker/netalertx/def
     - /appl/docker/netalertx/default:/etc/nginx/sites-available/default
 ...
 ```
+
+## Caddy + Authentik Outpost Proxy SSO
+> Submitted by [luckylinux](https://github.com/luckylinux) 🙏.
+
+### Introduction
+This Setup assumes:
+1. Authentik Installation running on a separate Host at `https://authentik.MYDOMAIN.TLD`
+2. Container Management is done on Baremetal OR in a Virtual Machine (KVM/Xen/ESXi/..., no LXC Containers !):
+
+    i. Docker and Docker Compose configured locally running as Root (needed for `network_mode: host`) OR
+
+    ii. Podman (optionally `podman-compose`) configured locally running as Root (needed for `network_mode: host`)
+3. TLS Certificates are already pre-obtained and located at `/var/lib/containers/certificates/letsencrypt/MYDOMAIN.TLD`.
+
+   I use the `certbot/dns-cloudflare` Podman Container on a separate Host to obtain the Certificates which I then distribute internally.
+   This Container uses the Wildcard Top-Level Domain Certificate which is valid for `MYDOMAIN.TLD` and `*.MYDOMAIN.TLD`.
+4. Proxied Access
+
+    i. NetAlertX Web Interface is accessible via Caddy Reverse Proxy at `https://netalertx.MYDOMAIN.TLD` (default HTTPS Port 443: `https://netalertx.MYDOMAIN.TLD:443`) with `REPORT_DASHBOARD_URL=https://netalertx.MYDOMAIN.TLD`
+
+    ii. NetAlertX GraphQL Interface is accessible via Caddy Reverse Proxy at `https://netalertx.MYDOMAIN.TLD:20212` with `BACKEND_API_URL=https://netalertx.MYDOMAIN.TLD:20212`
+
+    iii. Authentik Proxy Outpost is accessible via Caddy Reverse Proxy at `https://netalertx.MYDOMAIN.TLD:9443`
+5. Internal Ports
+
+    i. NGINX Web Server is set to listen on internal Port 20211 set via `PORT=20211`
+
+    ii. Python Web Server is set to listen on internal Port `GRAPHQL_PORT=20219`
+
+    iii. Authentik Proxy Outpost is listening on internal Port `AUTHENTIK_LISTEN__HTTP=[::1]:6000` (unencrypted) and Port `AUTHENTIK_LISTEN__HTTPS=[::1]:6443` (encrypted)
+8. Some further Configuration for Caddy is performed in Terms of Logging, SSL Certificates, etc
+
+It's also possible to [let Caddy automatically request & keep TLS Certificates up-to-date](https://caddyserver.com/docs/automatic-https), although please keep in mind that:
+1. You risk enumerating your LAN. Every Domain/Subdomain for which Caddy requests a TLS Certificate for you will result in that Host to be listed on [List of Letsencrypt Certificates issued](https://crt.sh/).
+2. You need to either:
+
+    i. Open Port 80 for external Access ([HTTP challenge](https://caddyserver.com/docs/automatic-https#http-challenge)) in order for Letsencrypt to verify the Ownership of the Domain/Subdomain
+
+    ii. Open Port 443 for external Access ([TLS-ALPN challenge](https://caddyserver.com/docs/automatic-https#tls-alpn-challenge)) in order for Letsencrypt to verify the Ownership of the Domain/Subdomain
+
+    iii. Give Caddy the Credentials to update the DNS Records at your DNS Provider ([DNS challenge](https://caddyserver.com/docs/automatic-https#dns-challenge))
+
+You can also decide to deploy your own Certificates & Certification Authority, either manually with OpenSSL, or by using something like [mkcert](https://github.com/FiloSottile/mkcert).
+
+In Terms of IP Stack Used:
+- External: Caddy listens on both IPv4 and IPv6.
+- Internal:
+  - Authentik Outpost Proxy listens on IPv6 `[::1]`
+  - NetAlertX listens on IPv4 `0.0.0.0`
+
+### Flow
+The Traffic Flow will therefore be as follows:
+- Web GUI:
+
+   i. Client accesses `http://authentik.MYDOMAIN.TLD:80`: default (built-in Caddy) Redirect to `https://authentik.MYDOMAIN.TLD:443`
+
+   ii. Client accesses `https://authentik.MYDOMAIN.TLD:443` -> reverse Proxy to internal Port 20211 (NetAlertX Web GUI / NGINX - unencrypted)
+- GraphQL: Client accesses `https://authentik.MYDOMAIN.TLD:20212` -> reverse Proxy to internal Port 20219 (NetAlertX GraphQL - unencrypted)
+- Authentik Outpost: Client accesses `https://authentik.MYDOMAIN.TLD:9443` -> reverse Proxy to internal Port 6000 (Authentik Outpost Proxy - unencrypted)
+
+An Overview of the Flow is provided in the Picture below:
+
+![Reverse Proxy Traffic Flow with Authentik SSSO](./img/REVERSE_PROXY/reverse_proxy_flow.svg)
+
+### Security Considerations
+#### Caddy should be run rootless
+> [!WARNING]  
+> By default Caddy runs as `root` which is a Security Risk.
+> In order to solve this, it's recommended to create an unprivileged User `caddy` and Group `caddy` on the Host:
+> ```
+> groupadd --gid 980 caddy
+> useradd --shell /usr/sbin/nologin --gid 980 --uid 980 -c "Caddy web server" --base-dir /var/lib/caddy
+> ```
+
+At least using Quadlets with Usernames (NOT required with UID/GID), but possibly using Compose in certain Cases as well, a custom `/etc/passwd` and `/etc/group` might need to be bind-mounted inside the Container.
+`passwd`:
+```
+root:x:0:0:root:/root:/bin/sh
+bin:x:1:1:bin:/bin:/sbin/nologin
+daemon:x:2:2:daemon:/sbin:/sbin/nologin
+lp:x:4:7:lp:/var/spool/lpd:/sbin/nologin
+sync:x:5:0:sync:/sbin:/bin/sync
+shutdown:x:6:0:shutdown:/sbin:/sbin/shutdown
+halt:x:7:0:halt:/sbin:/sbin/halt
+mail:x:8:12:mail:/var/mail:/sbin/nologin
+news:x:9:13:news:/usr/lib/news:/sbin/nologin
+uucp:x:10:14:uucp:/var/spool/uucppublic:/sbin/nologin
+cron:x:16:16:cron:/var/spool/cron:/sbin/nologin
+ftp:x:21:21::/var/lib/ftp:/sbin/nologin
+sshd:x:22:22:sshd:/dev/null:/sbin/nologin
+games:x:35:35:games:/usr/games:/sbin/nologin
+ntp:x:123:123:NTP:/var/empty:/sbin/nologin
+guest:x:405:100:guest:/dev/null:/sbin/nologin
+nobody:x:65534:65534:nobody:/:/sbin/nologin
+caddy:x:980:980:caddy:/var/lib/caddy:/bin/sh
+```
+
+`group`:
+```
+root:x:0:root
+bin:x:1:root,bin,daemon
+daemon:x:2:root,bin,daemon
+sys:x:3:root,bin
+adm:x:4:root,daemon
+tty:x:5:
+disk:x:6:root
+lp:x:7:lp
+kmem:x:9:
+wheel:x:10:root
+floppy:x:11:root
+mail:x:12:mail
+news:x:13:news
+uucp:x:14:uucp
+cron:x:16:cron
+audio:x:18:
+cdrom:x:19:
+dialout:x:20:root
+ftp:x:21:
+sshd:x:22:
+input:x:23:
+tape:x:26:root
+video:x:27:root
+netdev:x:28:
+kvm:x:34:kvm
+games:x:35:
+shadow:x:42:
+www-data:x:82:
+users:x:100:games
+ntp:x:123:
+abuild:x:300:
+utmp:x:406:
+ping:x:999:
+nogroup:x:65533:
+nobody:x:65534:
+caddy:x:980:
+```
+
+#### Authentication of GraphQL Endpoint
+> [!WARNING]  
+> Currently the GraphQL Endpoint is NOT authenticated !
+
+### Environment Files
+Depending on the Preference of the User (Environment Variables defined in Compose/Quadlet or in external `.env` File[s]), it might be prefereable to place at least some Environment Variables in external `.env` and `.env.<application>` Files.
+
+The following is proposed:
+- `.env`: common Settings (empty by Default)
+- `.env.caddy`: Caddy Settings
+- `.env.server`: NetAlertX Server/Application Settings
+- `.env.outpost.proxy`: Authentik Proxy Outpost Settings
+
+The following Contents is assumed.
+
+`.env.caddy`:
+```
+# Define Application Hostname
+APPLICATION_HOSTNAME=netalertx.MYDOMAIN.TLD
+
+# Define Certificate Domain
+# In this case: use Wildcard Certificate
+APPLICATION_CERTIFICATE_DOMAIN=MYDOMAIN.TLD
+APPLICATION_CERTIFICATE_CERT_FILE=fullchain.pem
+APPLICATION_CERTIFICATE_KEY_FILE=privkey.pem
+
+# Define Outpost Hostname
+OUTPOST_HOSTNAME=netalertx.MYDOMAIN.TLD
+
+# Define Outpost External Port (TLS)
+OUTPOST_EXTERNAL_PORT=9443
+```
+
+`.env.server`:
+```
+PORT=20211
+PORT_SSL=443
+NETALERTX_NETWORK_MODE=host
+LISTEN_ADDR=0.0.0.0
+GRAPHQL_PORT=20219
+NETALERTX_DEBUG=1
+BACKEND_API_URL=https://netalertx.MYDOMAIN.TLD:20212
+```
+
+`.env.outpost.proxy`:
+```
+AUTHENTIK_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+AUTHENTIK_LISTEN__HTTP=[::1]:6000
+AUTHENTIK_LISTEN__HTTPS=[::1]:6443
+```
+
+### Compose Setup
+```
+version: "3.8"
+services:
+  netalertx-caddy:
+    container_name: netalertx-caddy
+
+    network_mode: host
+    image: docker.io/library/caddy:latest
+    pull: missing
+
+    env_file:
+      - .env
+      - .env.caddy
+
+    environment:
+      CADDY_DOCKER_CADDYFILE_PATH: "/etc/caddy/Caddyfile"
+
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro,z
+      - /var/lib/containers/data/netalertx/caddy:/data/caddy:rw,z
+      - /var/lib/containers/log/netalertx/caddy:/var/log:rw,z
+      - /var/lib/containers/config/netalertx/caddy:/config/caddy:rw,z
+      - /var/lib/containers/certificates/letsencrypt:/certificates:ro,z
+
+    # Set User
+    user: "caddy:caddy"
+
+    # Automatically restart Container
+    restart: unless-stopped
+
+  netalertx-server:
+    container_name: netalertx-server                # The name when you docker contiainer ls
+
+    network_mode: host                              # Use host networking for ARP scanning and other services
+
+    depends_on:
+      netalertx-caddy:
+        condition: service_started
+        restart: true
+      netalertx-outpost-proxy:
+        condition: service_started
+        restart: true
+
+    # Local built Image including latest Changes
+    image: localhost/netalertx-dev:dev-20260109-232454
+
+    read_only: true                                 # Make the container filesystem read-only
+
+    # It is most secure to start with user 20211, but then we lose provisioning capabilities.
+    # user: "${NETALERTX_UID:-20211}:${NETALERTX_GID:-20211}"
+    cap_drop:                                       # Drop all capabilities for enhanced security
+      - ALL
+    cap_add:                                        # Add only the necessary capabilities
+      - NET_ADMIN                                   # Required for scanning with arp-scan, nmap, nbtscan, traceroute, and zero-conf
+      - NET_RAW                                     # Required for raw socket operations with arp-scan, nmap, nbtscan, traceroute and zero-conf
+      - NET_BIND_SERVICE                            # Required to bind to privileged ports with 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:
+
+      # Override NGINX Configuration Template
+      - type: bind
+        source: /var/lib/containers/config/netalertx/server/nginx/netalertx.conf.template
+        target: /services/config/nginx/netalertx.conf.template
+        read_only: true
+        bind:
+          selinux: Z
+
+      # Letsencrypt Certificates
+      - type: bind
+        source: /var/lib/containers/certificates/letsencrypt/MYDOMAIN.TLD
+        target: /certificates
+        read_only: true
+        bind:
+          selinux: Z
+
+      # Data Storage for NetAlertX
+      - type: bind                                  # Persistent Docker-managed Named Volume for storage
+        source: /var/lib/containers/data/netalertx/server
+        target: /data                               # consolidated configuration and database storage
+        read_only: false                            # writable volume
+        bind:
+          selinux: Z
+
+      # Set the Timezone
+      - type: bind                           # Bind mount for timezone consistency
+        source: /etc/localtime
+        target: /etc/localtime
+        read_only: true
+        bind:
+          selinux: Z
+
+    # tmpfs mounts for writable directories in a read-only container and improve system performance
+    # All writes now live under /tmp/* subdirectories which are created dynamically by entrypoint.d scripts
+    # mode=1700 gives rwx------ permissions; ownership is set by /root-entrypoint.sh
+      - type: tmpfs
+        target: /tmp
+        tmpfs-mode: 1700
+        uid: 0
+        gid: 0
+        rw: true
+        noexec: true
+        nosuid: true
+        nodev: true
+        async: true
+        noatime: true
+        nodiratime: true
+        bind:
+          selinux: Z
+
+    env_file:
+      - .env
+      - .env.server
+
+    environment:
+      PUID: ${NETALERTX_UID:-20211}                             # Runtime UID after priming (Synology/no-copy-up safe)
+      PGID: ${NETALERTX_GID:-20211}                             # Runtime GID after priming (Synology/no-copy-up safe)
+      LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0}                      # Listen for connections on all interfaces
+      PORT: ${PORT:-20211}                                      # Application port
+      PORT_SSL: ${PORT_SSL:-443}
+      GRAPHQL_PORT: ${GRAPHQL_PORT:-20212}                      # GraphQL API port
+      ALWAYS_FRESH_INSTALL: ${ALWAYS_FRESH_INSTALL:-false}      # Set to true to reset your config and database on each container start
+      NETALERTX_DEBUG: ${NETALERTX_DEBUG:-0}                    # 0=kill all services and restart if any dies. 1 keeps running dead services.
+      BACKEND_API_URL: ${BACKEND_API_URL-"https://netalertx.MYDOMAIN.TLD:20212"}
+
+    # Resource limits to prevent resource exhaustion
+    mem_limit: 4096m            # Maximum memory usage
+    mem_reservation: 2048m      # Soft memory limit
+    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
+
+    # Always restart the container unless explicitly stopped
+    restart: unless-stopped
+
+  # To sign Out, you need to visit
+  # {$OUTPOST_HOSTNAME}:{$OUTPOST_EXTERNAL_PORT}/outpost.goauthentik.io/sign_out
+  netalertx-outpost-proxy:
+    container_name: netalertx-outpost-proxy
+
+    network_mode: host
+
+    depends_on:
+      netalertx-caddy:
+        condition: service_started
+        restart: true
+
+    restart: unless-stopped
+
+    image: ghcr.io/goauthentik/proxy:2025.10
+    pull: missing
+
+    env_file:
+      - .env
+      - .env.outpost.proxy
+
+    environment:
+      AUTHENTIK_HOST: "https://authentik.MYDOMAIN.TLD"
+      AUTHENTIK_INSECURE: false
+      AUTHENTIK_LISTEN__HTTP: "[::1]:6000"
+      AUTHENTIK_LISTEN__HTTPS: "[::1]:6443"
+```
+
+### Quadlet Setup
+`netalertx.pod`:
+```
+[Pod]
+# Name of the Pod
+PodName=netalertx
+
+# Network Mode Host is required for ARP to work
+Network=host
+
+# Automatically start Pod at Boot Time
+[Install]
+WantedBy=default.target
+```
+
+`netalertx-caddy.container`:
+```
+[Unit]
+Description=NetAlertX Caddy Container
+
+[Service]
+Restart=always
+
+[Container]
+ContainerName=netalertx-caddy
+
+Pod=netalertx.pod
+StartWithPod=true
+
+# Generic Environment Configuration
+EnvironmentFile=.env
+
+# Caddy Specific Environment Configuration
+EnvironmentFile=.env.caddy
+
+Environment=CADDY_DOCKER_CADDYFILE_PATH=/etc/caddy/Caddyfile
+
+Image=docker.io/library/caddy:latest
+Pull=missing
+
+# Run as rootless
+# Specifying User & Group by Name requires to mount a custom passwd & group File inside the Container
+# Otherwise an Error like the following will result: netalertx-caddy[593191]: Error: unable to find user caddy: no matching entries in passwd file
+# User=caddy
+# Group=caddy
+# Volume=/var/lib/containers/config/netalertx/caddy-rootless/passwd:/etc/passwd:ro,z
+# Volume=/var/lib/containers/config/netalertx/caddy-rootless/group:/etc/group:ro,z
+
+# Run as rootless
+# Specifying User & Group by UID/GID will NOT require a custom passwd / group File to be bind-mounted inside the Container
+User=980
+Group=980
+
+Volume=./Caddyfile:/etc/caddy/Caddyfile:ro,z
+Volume=/var/lib/containers/data/netalertx/caddy:/data/caddy:z
+Volume=/var/lib/containers/log/netalertx/caddy:/var/log:z
+Volume=/var/lib/containers/config/netalertx/caddy:/config/caddy:z
+Volume=/var/lib/containers/certificates/letsencrypt:/certificates:ro,z
+```
+
+`netalertx-server.container`:
+```
+[Unit]
+Description=NetAlertX Server Container
+Requires=netalertx-caddy.service netalertx-outpost-proxy.service 
+After=netalertx-caddy.service netalertx-outpost-proxy.service 
+
+[Service]
+Restart=always
+
+[Container]
+ContainerName=netalertx-server
+
+Pod=netalertx.pod
+StartWithPod=true
+
+# Local built Image including latest Changes
+Image=localhost/netalertx-dev:dev-20260109-232454
+Pull=missing
+
+# Make the container filesystem read-only
+ReadOnly=true
+
+# Drop all capabilities for enhanced security
+DropCapability=ALL
+
+# It is most secure to start with user 20211, but then we lose provisioning capabilities.
+# User=20211:20211
+
+# Required for scanning with arp-scan, nmap, nbtscan, traceroute, and zero-conf
+AddCapability=NET_ADMIN
+
+# Required for raw socket operations with arp-scan, nmap, nbtscan, traceroute and zero-conf
+AddCapability=NET_RAW
+
+# Required to bind to privileged ports with nbtscan
+AddCapability=NET_BIND_SERVICE
+
+# Required for root-entrypoint to chown /data + /tmp before dropping privileges
+AddCapability=CHOWN
+
+# Required for root-entrypoint to switch to non-root user
+AddCapability=SETUID
+
+# Required for root-entrypoint to switch to non-root group
+AddCapability=SETGID
+
+# Override the Configuration Template
+Volume=/var/lib/containers/config/netalertx/server/nginx/netalertx.conf.template:/services/config/nginx/netalertx.conf.template:ro,Z
+
+# Letsencrypt Certificates
+Volume=/var/lib/containers/certificates/letsencrypt/MYDOMAIN.TLD:/certificates:ro,Z
+
+# Data Storage for NetAlertX
+Volume=/var/lib/containers/data/netalertx/server:/data:rw,Z
+
+# Set the Timezone
+Volume=/etc/localtime:/etc/localtime:ro,Z
+
+# tmpfs mounts for writable directories in a read-only container and improve system performance
+# All writes now live under /tmp/* subdirectories which are created dynamically by entrypoint.d scripts
+# mode=1700 gives rwx------ permissions; ownership is set by /root-entrypoint.sh
+# Mount=type=tmpfs,destination=/tmp,tmpfs-mode=1700,uid=0,gid=0,rw=true,noexec=true,nosuid=true,nodev=true,async=true,noatime=true,nodiratime=true,relabel=private
+Mount=type=tmpfs,destination=/tmp,tmpfs-mode=1700,rw=true,noexec=true,nosuid=true,nodev=true
+
+# Environment Configuration
+EnvironmentFile=.env
+EnvironmentFile=.env.server
+
+# Runtime UID after priming (Synology/no-copy-up safe)
+Environment=PUID=20211
+
+# Runtime GID after priming (Synology/no-copy-up safe)
+Environment=PGID=20211
+
+# Listen for connections on all interfaces (IPv4)
+Environment=LISTEN_ADDR=0.0.0.0
+
+# Application port
+Environment=PORT=20211
+
+# SSL Port
+Environment=PORT_SSL=443
+
+# GraphQL API port
+Environment=GRAPHQL_PORT=20212
+
+# Set to true to reset your config and database on each container start
+Environment=ALWAYS_FRESH_INSTALL=false
+
+# 0=kill all services and restart if any dies. 1 keeps running dead services.
+Environment=NETALERTX_DEBUG=0
+
+# Set the GraphQL URL for external Access (via Caddy Reverse Proxy)
+Environment=BACKEND_API_URL=https://netalertx-fedora.MYDOMAIN.TLD:20212
+
+# Resource limits to prevent resource exhaustion
+# Maximum memory usage
+Memory=4g
+
+# Limit the number of processes/threads to prevent fork bombs
+PidsLimit=512
+
+# Relative CPU weight for CPU contention scenarios
+PodmanArgs=--cpus=2							
+PodmanArgs=--cpu-shares=512
+
+# Soft memory limit
+PodmanArgs=--memory-reservation=2g
+
+# !! The following Keys are unfortunately not [yet] supported !!
+
+# Relative CPU weight for CPU contention scenarios
+#CpuShares=512
+
+# Soft memory limit
+#MemoryReservation=2g
+```
+
+`netalertx-outpost-proxy.container`:
+```
+[Unit]
+Description=NetAlertX Authentik Proxy Outpost Container
+Requires=netalertx-caddy.service
+After=netalertx-caddy.service
+
+[Service]
+Restart=always
+
+[Container]
+ContainerName=netalertx-outpost-proxy
+
+Pod=netalertx.pod
+StartWithPod=true
+
+# General Configuration
+EnvironmentFile=.env
+
+# Authentik Outpost Proxy Specific Configuration
+EnvironmentFile=.env.outpost.proxy
+
+Environment=AUTHENTIK_HOST=https://authentik.MYDOMAIN.TLD
+Environment=AUTHENTIK_INSECURE=false
+
+# Overrides Value from .env.outpost.rac
+# Environment=AUTHENTIK_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+
+# Optional setting to be used when `authentik_host` for internal communication doesn't match the public URL
+# Environment=AUTHENTIK_HOST_BROWSER=https://authentik.MYDOMAIN.TLD
+
+# Container Image
+Image=ghcr.io/goauthentik/proxy:2025.10
+Pull=missing
+
+# Network Configuration
+Network=container:supermicro-ikvm-pve031-caddy
+
+# Security Configuration
+NoNewPrivileges=true
+```
+
+### Firewall Setup
+Depending on which GNU/Linux Distribution you are running, it might be required to open up some Firewall Ports in order to be able to access the Endpoints from outside the Host itself.
+
+This is for instance the Case for Fedora Linux, where I had to open:
+- Port 20212 for external GraphQL Access (both TCP & UDP are open, unsure if UDP is required)
+- Port 9443 for external Authentik Outpost Proxy Access (both TCP & UDP are open, unsure if UDP is required)
+
+![Fedora Firewall Configuration](./img/REVERSE_PROXY/fedora-firewall.png)
+
+### Authentik Setup
+In order to enable Single Sign On (SSO) with Authentik, you will need to create a Provider, an Application and an Outpost.
+
+![Authentik Left Sidebar](./img/REVERSE_PROXY/authentik-sidebar.png)
+
+First of all, using the Left Sidebar, navigate to `Applications` &#8594; `Providers`, click on `Create` (Blue Button at the Top of the Screen), select `Proxy Provider`, then click `Next`:
+![Authentik Provider Setup (Part 1)](./img/REVERSE_PROXY/authentik-provider-setup-01.png)
+
+Fill in the required Fields:
+- Name: choose a Name for the Provider (e.g. `netalertx`)
+- Authorization Flow: choose the Authorization Flow. I typically use `default-provider-authorization-implicit-consent (Authorize Application)`. If you select the `default-provider-authorization-explicit-consent (Authorize Application)` you will need to authorize Authentik every Time you want to log in NetAlertX, which can make the Experience less User-friendly
+- Type: Click on `Forward Auth (single application)`
+- External Host: set to `https://netalertx.MYDOMAIN.TLD`
+
+Click `Finish`.
+
+![Authentik Provider Setup (Part 2)](./img/REVERSE_PROXY/authentik-provider-setup-02.png)
+
+Now, using the Left Sidebar, navigate to `Applications` &#8594; `Applications`, click on `Create` (Blue Button at the Top of the Screen) and fill in the required Fields:
+- Name: choose a Name for the Application (e.g. `netalertx`)
+- Slug: choose a Slug for the Application (e.g. `netalertx`)
+- Group: optionally you can assign this Application to a Group of Applications of your Choosing (for grouping Purposes within Authentik User Interface)
+- Provider: select the Provider you created the the `Providers` Section previosly (e.g. `netalertx`)
+
+Then click `Create`.
+
+![Authentik Application Setup (Part 1)](./img/REVERSE_PROXY/authentik-application-setup-01.png)
+
+Now, using the Left Sidebar, navigate to `Applications` &#8594; `Outposts`, click on `Create` (Blue Button at the Top of the Screen) and fill in the required Fields:
+- Name: choose a Name for the Outpost (e.g. `netalertx`)
+- Type: `Proxy`
+- Integration: open the Dropdown and click on `---------`. Make sure it is NOT set to `Local Docker connection` !
+
+In the `Available Applications` Section, select the Application you created in the Previous Step, then click the right Arrow (approx. located in the Center of the Screen), so that it gets copied in the `Selected Applications` Section.
+
+Then click `Create`.
+
+![Authentik Outpost Setup (Part 1)](./img/REVERSE_PROXY/authentik-outpost-setup-01.png)
+
+Wait a few Seconds for the Outpost to be created. Once it appears in the List, click on `Deployment Info` on the Right Side of the relevant Line.
+
+![Authentik Outpost Setup (Part 2)](./img/REVERSE_PROXY/authentik-outpost-setup-02.png)
+
+Take note of that Token. You will need it for the Authentik Outpost Proxy Container, which will read it as the `AUTHENTIK_TOKEN` Environment Variable.
+
+### NGINX Configuration inside NetAlertX Container
+> [!NOTE]  
+> This is something that was implemented based on the previous Content of this Reverse Proxy Document.
+> Due to some Buffer Warnings/Errors in the Logs as well as some other Issues I was experiencing, I increased a lot the client_body_buffer_size and large_client_header_buffers Parameters, although these might not be required anymore.
+> Further Testing might be required.
+
+```
+# Set number of worker processes automatically based on number of CPU cores.
+worker_processes auto;
+
+# Enables the use of JIT for regular expressions to speed-up their processing.
+pcre_jit on;
+
+# Configures default error logger.
+error_log /tmp/log/nginx-error.log warn;
+
+pid /tmp/run/nginx.pid;
+
+events {
+	# The maximum number of simultaneous connections that can be opened by
+	# a worker process.
+	worker_connections 1024;
+}
+
+http {
+
+	# Mapping of temp paths for various nginx modules.
+  client_body_temp_path /tmp/nginx/client_body;
+  proxy_temp_path /tmp/nginx/proxy;
+	fastcgi_temp_path /tmp/nginx/fastcgi;
+	uwsgi_temp_path /tmp/nginx/uwsgi;
+	scgi_temp_path /tmp/nginx/scgi;
+	
+	# Includes mapping of file name extensions to MIME types of responses
+	# and defines the default type.
+	include /services/config/nginx/mime.types;
+	default_type application/octet-stream;
+
+	# Name servers used to resolve names of upstream servers into addresses.
+	# It's also needed when using tcpsocket and udpsocket in Lua modules.
+	#resolver 1.1.1.1 1.0.0.1 [2606:4700:4700::1111] [2606:4700:4700::1001];
+
+	# Don't tell nginx version to the clients. Default is 'on'.
+	server_tokens off;
+
+	# Specifies the maximum accepted body size of a client request, as
+	# indicated by the request header Content-Length. If the stated content
+	# length is greater than this size, then the client receives the HTTP
+	# error code 413. Set to 0 to disable. Default is '1m'.
+	client_max_body_size 1m;
+
+	# Sendfile copies data between one FD and other from within the kernel,
+	# which is more efficient than read() + write(). Default is off.
+	sendfile on;
+
+	# Causes nginx to attempt to send its HTTP response head in one packet,
+	# instead of using partial frames. Default is 'off'.
+	tcp_nopush on;
+
+
+	# Enables the specified protocols. Default is TLSv1 TLSv1.1 TLSv1.2.
+	# TIP: If you're not obligated to support ancient clients, remove TLSv1.1.
+	ssl_protocols TLSv1.2 TLSv1.3;
+
+	# Path of the file with Diffie-Hellman parameters for EDH ciphers.
+	# TIP: Generate with: `openssl dhparam -out /etc/ssl/nginx/dh2048.pem 2048`
+	#ssl_dhparam /etc/ssl/nginx/dh2048.pem;
+
+	# Specifies that our cipher suits should be preferred over client ciphers.
+	# Default is 'off'.
+	ssl_prefer_server_ciphers on;
+
+	# Enables a shared SSL cache with size that can hold around 8000 sessions.
+	# Default is 'none'.
+	ssl_session_cache shared:SSL:2m;
+
+	# Specifies a time during which a client may reuse the session parameters.
+	# Default is '5m'.
+	ssl_session_timeout 1h;
+
+	# Disable TLS session tickets (they are insecure). Default is 'on'.
+	ssl_session_tickets off;
+
+
+	# Enable gzipping of responses.
+	gzip on;
+
+	# Set the Vary HTTP header as defined in the RFC 2616. Default is 'off'.
+	gzip_vary on;
+
+
+    # Specifies the main log format.
+    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
+	    '$status $body_bytes_sent "$http_referer" '
+	    '"$http_user_agent" "$http_x_forwarded_for"';
+
+    # Sets the path, format, and configuration for a buffered log write.
+    access_log /tmp/log/nginx-access.log main;
+
+
+    # Virtual host config (unencrypted)
+    server {
+        listen ${LISTEN_ADDR}:${PORT} default_server;
+        root /app/front;
+        index index.php;
+        add_header X-Forwarded-Prefix "/app" always;
+
+        server_name netalertx-server;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        client_body_buffer_size 512k;
+	      large_client_header_buffers 64 128k;
+
+        location ~* \.php$ {
+            # Set Cache-Control header to prevent caching on the first load
+            add_header Cache-Control "no-store";
+			      fastcgi_pass unix:/tmp/run/php.sock;
+            include /services/config/nginx/fastcgi_params;
+			      fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
+			      fastcgi_param SCRIPT_NAME $fastcgi_script_name;
+            fastcgi_connect_timeout 75;
+            fastcgi_send_timeout 600;
+            fastcgi_read_timeout 600;
+        }
+    }
+}
+```
+
+### Caddyfile
+```
+# Example and Guide
+# https://caddyserver.com/docs/caddyfile/options
+
+# General Options
+{
+    # (Optional) Debug Mode
+    # debug
+
+    # (Optional ) Enable / Disable Admin API
+    admin off
+
+    # TLS Options
+    # (Optional) Disable Certificates Management (only if SSL/TLS Certificates are managed by certbot or other external Tools)
+    auto_https disable_certs
+}
+
+# (Optional Enable Admin API)
+# localhost {
+#	 reverse_proxy /api/* localhost:9001
+# }
+
+# NetAlertX Web GUI (HTTPS Port 443)
+# (Optional) Only if SSL/TLS Certificates are managed by certbot or other external Tools and Custom Logging is required
+{$APPLICATION_HOSTNAME}:443 {
+    tls /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_CERT_FILE:fullchain.pem} /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_KEY_FILE:privkey.pem}
+    
+    log {
+        output file /var/log/{$APPLICATION_HOSTNAME}/access_web.json {
+          roll_size 100MiB
+                roll_keep 5000
+                roll_keep_for 720h
+                roll_uncompressed
+        }
+    
+        format json
+    }
+
+    route {
+        # Always forward outpost path to actual outpost
+        reverse_proxy /outpost.goauthentik.io/* https://{$OUTPOST_HOSTNAME}:{$OUTPOST_EXTERNAL_PORT} {
+            header_up Host {http.reverse_proxy.upstream.hostport}
+        }
+
+        # Forward authentication to outpost
+        forward_auth https://{$OUTPOST_HOSTNAME}:{$OUTPOST_EXTERNAL_PORT} {
+            uri /outpost.goauthentik.io/auth/caddy
+
+            # Capitalization of the headers is important, otherwise they will be empty
+            copy_headers X-Authentik-Username X-Authentik-Groups X-Authentik-Email X-Authentik-Name X-Authentik-Uid X-Authentik-Jwt X-Authentik-Meta-Jwks X-Authentik-Meta-Outpost X-Authentik-Meta-Provider X-Authentik-Meta-App X-Authentik-Meta-Version
+
+            # (Optional)
+            # If not set, trust all private ranges, but for Security Reasons, this should be set to the outposts IP
+            trusted_proxies private_ranges
+        }
+    }
+
+    # IPv4 Reverse Proxy to NetAlertX Web GUI (internal unencrypted Host)
+    reverse_proxy http://0.0.0.0:20211
+
+    # IPv6 Reverse Proxy to NetAlertX Web GUI (internal unencrypted Host)
+    # reverse_proxy http://[::1]:20211
+}
+
+# NetAlertX GraphQL Endpoint (HTTPS Port 20212)
+# (Optional) Only if SSL/TLS Certificates are managed by certbot or other external Tools and Custom Logging is required
+{$APPLICATION_HOSTNAME}:20212 {
+    tls /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_CERT_FILE:fullchain.pem} /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_KEY_FILE:privkey.pem}
+
+    log {
+        output file /var/log/{$APPLICATION_HOSTNAME}/access_graphql.json {
+                roll_size 100MiB
+                roll_keep 5000
+                roll_keep_for 720h
+                roll_uncompressed
+        }
+
+        format json
+    }
+
+    # IPv4 Reverse Proxy to NetAlertX GraphQL Endpoint (internal unencrypted Host)
+    reverse_proxy http://0.0.0.0:20219
+
+    # IPv6 Reverse Proxy to NetAlertX GraphQL Endpoint (internal unencrypted Host)
+    # reverse_proxy http://[::1]:6000
+}
+
+# Authentik Outpost
+# (Optional) Only if SSL/TLS Certificates are managed by certbot or other external Tools and Custom Logging is required
+{$OUTPOST_HOSTNAME}:{$OUTPOST_EXTERNAL_PORT} {
+    tls /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_CERT_FILE:fullchain.pem} /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_KEY_FILE:privkey.pem}
+
+    log {
+        output file /var/log/outpost/{$OUTPOST_HOSTNAME}/access.json {
+                roll_size 100MiB
+                roll_keep 5000
+                roll_keep_for 720h
+                roll_uncompressed
+        }
+
+	      format json
+    }
+
+    # IPv4 Reverse Proxy to internal unencrypted Host
+    # reverse_proxy http://0.0.0.0:6000
+
+    # IPv6 Reverse Proxy to internal unencrypted Host
+    reverse_proxy http://[::1]:6000
+}
+```
+
+### Login
+Now try to login by visiting `https://netalertx.MYDOMAIN.TLD`.
+
+You should be greeted with a Login Screen by Authentik.
+
+If you are already logged in Authentik, log out first. You can do that by visiting `https://netalertx.MYDOMAIN.TLD/outpost.goauthentik.io/sign_out`, then click on `Log out of authentik` (2nd Button). Or you can just sign out from your Authentik Admin Panel at `https://authentik.MYDOMAIN.TLD`.
+
+If everything works as expected, then you can now set `SETPWD_enable_password=false` to disable double Authentication.
+
+![Authentik Login Screen](./img/REVERSE_PROXY/authentik-login.png)

docs/SETTINGS_SYSTEM.md

@@ -1,16 +1,16 @@
 ## ⚙ Setting system
 
-This is an explanation how settings are handled intended for anyone thinking about writing their own plugin or contributing to the project. 
+This is an explanation how settings are handled intended for anyone thinking about writing their own plugin or contributing to the project.
 
-If you are a user of the app, settings have a detailed description in the _Settings_ section of the app. Open an issue if you'd like to clarify any of the settings. 
+If you are a user of the app, settings have a detailed description in the _Settings_ section of the app. Open an issue if you'd like to clarify any of the settings.
 
 ### 🛢 Data storage
 
-The source of truth for user-defined values is the `app.conf` file. Editing the file makes the App overwrite values in the `Settings` database table and in the `table_settings.json` file. 
+The source of truth for user-defined values is the `app.conf` file. Editing the file makes the App overwrite values in the `Settings` database table and in the `table_settings.json` file.
 
 #### Settings database table
 
-The `Settings` database table contains settings for App run purposes. The table is recreated every time the App restarts. The settings are loaded from the source-of-truth, that is the `app.conf` file. A high-level overview on the database structure can be found in the [database documentation](./DATABASE.md). 
+The `Settings` database table contains settings for App run purposes. The table is recreated every time the App restarts. The settings are loaded from the source-of-truth, that is the `app.conf` file. A high-level overview on the database structure can be found in the [database documentation](./DATABASE.md).
 
 #### table_settings.json
 
@@ -22,23 +22,23 @@ The json file is also cached on the client-side local storage of the browser.
 
 #### app.conf
 
-> [!NOTE] 
+> [!NOTE]
 > This is the source of truth for settings. User-defined values in this files always override default values specified in the Plugin definition.
 
 The App generates two `app.conf` entries for every setting (Since version 23.8+). One entry is the setting value, the second is the `__metadata` associated with the setting. This `__metadata` entry contains the full setting definition in JSON format. Currently unused, but intended to be used in future to extend the Settings system.
 
 #### Plugin settings
 
-> [!NOTE] 
+> [!NOTE]
 > This is the preferred way adding settings going forward. I'll be likely migrating all app settings into plugin-based settings.
 
-Plugin settings are loaded dynamically from the `config.json` of individual plugins. If a setting isn't defined in the `app.conf` file, it is initialized via the `default_value` property of a setting from the `config.json` file. Check the [Plugins documentation](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md#-setting-object-structure), section `⚙ Setting object structure` for details on the structure of the setting.
+Plugin settings are loaded dynamically from the `config.json` of individual plugins. If a setting isn't defined in the `app.conf` file, it is initialized via the `default_value` property of a setting from the `config.json` file. Check the [Plugins documentation](https://docs.netalertx.com/PLUGINS#-setting-object-structure), section `⚙ Setting object structure` for details on the structure of the setting.
 
 ![Screen 1][screen1]
 
 ### Settings Process flow
 
-The process flow is mostly managed by the [initialise.py](/server/initialise.py) file. 
+The process flow is mostly managed by the [initialise.py](/server/initialise.py) file.
 
 The script is responsible for reading user-defined values from a configuration file (`app.conf`), initializing settings, and importing them into a database. It also handles plugins and their configurations.
 

docs/WEBHOOK_SECRET.md

@@ -1,7 +1,11 @@
 # Webhook Secrets
 
 > [!NOTE]
-> You need to enable the `WEBHOOK` plugin first in order to follow this guide. See the [Plugins guide](./PLUGINS.md) for details.  
+> This is community-contributed. Due to environment, setup, or networking differences, results may vary. Please open a PR to improve it instead of creating an issue, as the maintainer is not actively maintaining it.
+
+
+> [!NOTE]
+> You need to enable the `WEBHOOK` plugin first in order to follow this guide. See the [Plugins guide](./PLUGINS.md) for details.
 
 ## How does the signing work?
 
@@ -39,3 +43,5 @@ If your implementation is correct, the signature you generated should match the
 If you want to learn more about webhook security, take a look at [GitHub's webhook documentation](https://docs.github.com/en/webhooks/about-webhooks).
 
 You can find examples for validating a webhook delivery [here](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries#examples).
+
+

docs/docker-troubleshooting/PUID_PGID_SECURITY.md

@@ -0,0 +1,43 @@
+# PUID/PGID Security — Why the entrypoint requires numeric IDs
+
+## Purpose
+
+This short document explains the security rationale behind the root-priming entrypoint's validation of runtime user IDs (`PUID`) and group IDs (`PGID`). The validation is intentionally strict and is a safety measure to prevent environment-variable-based command injection when running as root during the initial priming stage.
+
+## Key points
+
+- The entrypoint accepts only values that are strictly numeric (digits only). Non-numeric values are treated as malformed and are a fatal error.
+- The fatal check exists to prevent *injection* or accidental shell interpretation of environment values while the container runs as root (e.g., `PUID="20211 && rm -rf /"`).
+- There is **no artificial upper bound** enforced by the validation — any numeric UID/GID is valid (for example, `100000` is acceptable).
+
+## Behavior on malformed input
+
+- If `PUID` or `PGID` cannot be parsed as numeric (digits-only), the entrypoint prints an explicit security message to stderr and exits with a non-zero status.
+- This is a deliberate, conservative safety measure — we prefer failing fast on potentially dangerous input rather than continuing with root-privileged operations.
+
+## Operator guidance
+
+- Always supply numeric values for `PUID` and `PGID` in your environment (via `docker-compose.yml`, `docker run -e`, or equivalent). Example: `PUID=20211`.
+- If you need to run with a high-numbered UID/GID (e.g., `100000`), that is fine — the entrypoint allows it as long as the value is numeric.
+- Don’t pass shell meta-characters, spaces, or compound commands in `PUID` or `PGID` — those will be rejected as malformed and cause the container to exit.
+
+## Required Capabilities for Privilege Drop
+
+If you are hardening your container by dropping capabilities (e.g., `cap_drop: [ALL]`), you **must** explicitly grant the `SETUID` and `SETGID` capabilities.
+
+- **Why?** The entrypoint runs as root to set permissions, then uses `su-exec` to switch to the user specified by `PUID`/`PGID`. This switch requires the kernel to allow the process to change its own UID/GID.
+- **Symptom:** If these capabilities are missing, the container will log a warning ("su-exec failed") and continue running as **root** (UID 0), defeating the purpose of setting `PUID`/`PGID`.
+- **Fix:** Add `SETUID` and `SETGID` to your `cap_add` list.
+
+```yaml
+cap_drop:
+  - ALL
+cap_add:
+  - SETUID
+  - SETGID
+  # ... other required caps like CHOWN, NET_ADMIN, etc.
+```
+
+---
+
+*Document created to clarify the security behavior of the root-priming entrypoint (PUID/PGID validation).*

docs/docker-troubleshooting/aufs-capabilities.md

@@ -0,0 +1,167 @@
+
+# AUFS Legacy Storage Driver Support
+
+## Issue Description
+
+NetAlertX automatically detects the legacy `aufs` storage driver, which is commonly found on older Synology NAS devices (DSM 6.x/7.0.x) or Linux systems where the underlying filesystem lacks `d_type` support. This occurs on older ext4 and other filesystems which did not support capabilites at time of last formatting.  While ext4 currently support capabilities and filesystem overlays, older variants of ext4 did not and require a reformat to enable the support.  Old variants result in docker choosing `aufs` and newer may use `overlayfs`.
+
+**The Technical Limitation:**
+AUFS (Another Union File System) does not support or preserve extended file attributes (`xattrs`) during Docker image extraction. NetAlertX relies on these attributes to grant granular privileges (`CAP_NET_RAW` and `CAP_NET_ADMIN`) to network scanning binaries like `arp-scan`, `nmap`, and `nbtscan`.
+
+**The Result:**
+When the container runs as a standard non-root user (default) on AUFS, these binaries are stripped of their capabilities. Consequently, layer-2 network discovery will fail silently, find zero devices, or exit with "Operation not permitted" errors.
+
+## Operational Logic
+
+The container is designed to inspect the runtime environment at startup (`/root-entrypoint.sh`). It respects user configuration first, falling back to safe defaults (with warnings) where necessary.
+
+**Behavior Matrix:**
+
+| Filesystem | PUID Config | Runtime User | Outcome |
+| :--- | :--- | :--- | :--- |
+| **Modern (Overlay2/Btrfs)** | Unset | `20211` | **Secure.** Full functionality via preserved `setcap`. |
+| **Legacy (AUFS)** | Unset | `20211` | **Degraded.** Logs warning. L2 scans fail due to missing perms. |
+| **Legacy (AUFS)** | `PUID=0` | `Root` | **Functional.** Root privileges bypass capability requirements. |
+| **Legacy (AUFS)** | `PUID=1000` | `1000` | **Degraded.** Logs warning. L2 scans fail due to missing perms. |
+
+### Warning Log
+When AUFS is detected without root privileges, the system emits the following warning during startup:
+> ⚠️  WARNING: Reduced functionality (AUFS + non-root user).
+>
+> 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.
+
+
+## Security Ramifications
+
+To mitigate the AUFS limitation, the recommended fix is to run the application as the **root** user (`PUID=0`).
+
+* **Least Privilege:** Even when running as root, NetAlertX applies `cap_drop: - ALL` and re-adds only the strictly necessary capabilities (`NET_RAW`, `NET_ADMIN`). This maintains a "least privilege" posture, though it is inherently less secure than running as a specific UID.
+* **Attack Surface:** Running as UID 0 increases the theoretical attack surface. If the container were compromised, the attacker would have root access *inside* the container (though still isolated from the host by the Docker runtime).
+* **Legacy Risks:** Reliance on the deprecated AUFS driver often indicates an older OS kernel or filesystem configuration, which may carry its own unpatched vulnerabilities compared to modern `overlay2` or `btrfs` setups.
+
+
+## How to Correct the Issue
+
+Choose the scenario that best matches your environment and security requirements.
+
+### Scenario A: Modern Systems (Recommended)
+**Context:** Systems using `overlay2`, `btrfs`, or `zfs`.
+**Action:** No action required. The system auto-configures `PUID=20211`.
+
+```yaml
+services:
+  netalertx:
+    image: netalertx/netalertx
+    # No PUID/PGID needed; defaults to secure non-root
+
+```
+
+### Scenario B: Legacy/Synology AUFS (The Fix)
+
+**Context:** Synology DSM 6.x/7.x or Linux hosts using AUFS.
+**Action:** Explicitly elevate to root. This bypasses the need for file capabilities because Root inherits runtime capabilities directly from Docker.
+
+```yaml
+services:
+  netalertx:
+    image: netalertx/netalertx
+    environment:
+      - PUID=0  # Required for arp-scan/nmap on AUFS
+      - PGID=0
+
+```
+
+### Scenario C: Forced Non-Root on AUFS
+
+**Context:** Strict security compliance requires non-root, even if it breaks functionality.
+**Action:** The warning will persist. The Web UI and Database will function, but network discovery (ARP/Nmap) will be severely limited.
+
+```yaml
+services:
+  netalertx:
+    image: netalertx/netalertx
+    environment:
+      - PUID=1000
+      - PGID=1000
+    # Note: cap_add is ineffective here due to AUFS stripping the binary's file caps
+
+```
+
+
+## Infrastructure Upgrades (Long-term Fix)
+
+To solve the root cause and run securely as non-root, you must migrate off the AUFS driver.
+
+### 1. Switch to Btrfs (Synology Recommended)
+
+If your NAS supports it, creating a new volume formatted as **Btrfs** allows Docker to use the native `btrfs` storage driver.
+
+* **Benefit:** This driver fully supports extended attributes and Copy-on-Write (CoW), creating the most robust environment for Docker.
+
+### 2. Reformat Ext4 with `d_type` Support
+
+If you must use `ext4`, the issue is likely that your volume lacks `d_type` support (common on older volumes created before DSM 6).
+
+* **Fix:** Back up your data and reformat the volume.
+* **Result:** Modern formatting usually enables `d_type` by default. This allows Docker to automatically select the modern **`overlay2`** driver instead of failing back to AUFS.
+
+
+## Technical Implementation
+
+### Detection Mechanism
+
+The logic resides in `_detect_storage_driver()` within `/root-entrypoint.sh`. It parses the root mount point (`/`) to identify the underlying driver.
+
+```bash
+# Modern (overlay2) - Pass
+overlay / overlay rw,relatime,lowerdir=...
+
+# Legacy (AUFS) - Triggers Warning
+none / aufs rw,relatime,si=...
+
+```
+
+### Verification & Troubleshooting
+
+**1. Confirm Storage Driver**
+If your host is using ext4 you might be defaulting to aufs:
+
+```bash
+docker info | grep "Storage Driver"
+# OR inside the container:
+docker exec netalertx grep " / " /proc/mounts
+
+```
+
+**2. Verify Capability Loss**
+If scans fail, check if the binary permissions were stripped.
+
+* **Modern FS:** Returns `cap_net_admin,cap_net_raw+eip`
+* **AUFS:** Returns empty output (stripped)
+
+```bash
+docker exec netalertx getcap /usr/sbin/arp-scan
+
+```
+
+**3. Simulating AUFS (Dev/Test)**
+Developers can force the AUFS logic path on a modern machine by mocking the mounts file. Note: Docker often restricts direct bind-mounts of host `/proc` paths, so the test suite uses an environment-variable injection instead (see `test_puid_pgid.py`).
+
+```bash
+# Create mock mounts content and encode it as base64
+echo "none / aufs rw,relatime 0 0" | base64
+
+# Run the container passing the encoded mounts via NETALERTX_PROC_MOUNTS_B64
+# (the entrypoint decodes this and uses it instead of reading /proc/mounts directly)
+docker run --rm -e NETALERTX_PROC_MOUNTS_B64="bm9uZSAvIGF1ZnMgcncs..." netalertx/netalertx
+```
+
+## Additional Resources
+
+* **Docker Storage Drivers:** [Use the OverlayFS storage driver](https://docs.docker.com/storage/storagedriver/overlayfs-driver/)
+* **Synology Docker Guide:** [Synology Docker Storage Drivers](https://www.google.com/search?q=https://kb.synology.com/en-global/DSM/tutorial/How_to_use_Docker_on_Synology_NAS)
+* **Configuration Guidance:** [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
+
+

docs/docker-troubleshooting/excessive-capabilities.md

@@ -29,4 +29,4 @@ Limit capabilities to only those required:
 
 Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
 
-For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)

docs/docker-troubleshooting/file-permissions.md

@@ -24,4 +24,4 @@ Fix permissions on the host system for the mounted directories:
 
 Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
 
-For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)

docs/docker-troubleshooting/incorrect-user.md

@@ -2,27 +2,30 @@
 
 ## Issue Description
 
-NetAlertX is running as UID:GID other than the expected 20211:20211. This bypasses hardened permissions, file ownership, and runtime isolation safeguards.
+NetAlertX is running as a UID:GID that does not match the runtime service user configured for this container (default 20211:20211). Hardened ownership on writable paths may block writes if the UID/GID do not align with mounted volumes and tmpfs settings.
 
 ## Security Ramifications
 
-The application is designed with security hardening that depends on running under a dedicated, non-privileged service account. Using a different user account can silently fail future upgrades and removes crucial isolation between the container and host system.
+The image uses a dedicated service user for writes and a readonly lock owner (UID 20211) for code/venv with 004/005 permissions. Running as an arbitrary UID is supported, but only when writable mounts (`/data`, `/tmp/*`) are owned by that UID. Misalignment can cause startup failures or unexpected permission escalation attempts.
 
 ## Why You're Seeing This Issue
 
-This occurs when you override the container's default user with custom `user:` directives in docker-compose.yml or `--user` flags in docker run commands. The container expects to run as the netalertx user for proper security isolation.
+- A `user:` override in docker-compose.yml or `--user` flag on `docker run` changes the runtime UID/GID without updating mount ownership.
+- Tmpfs mounts still use `uid=20211,gid=20211` while the container runs as another UID.
+- Host bind mounts (e.g., `/data`) are owned by a different UID.
 
 ## How to Correct the Issue
 
-Restore the container to the default user:
+Option A: Use defaults (recommended)
+- Remove custom `user:` overrides and `--user` flags.
+- Let the container run as the built-in service user (UID/GID 20211) and keep tmpfs at `uid=20211,gid=20211`.
 
-- Remove any `user:` overrides from docker-compose.yml
-- Avoid `--user` flags in docker run commands
-- Allow the container to run with its default UID:GID 20211:20211
-- Recreate the container so volume ownership is reset automatically
+Option B: Run with a custom UID/GID
+- Set `user:` (or `NETALERTX_UID/NETALERTX_GID`) to your desired UID/GID.
+- Align mounts: ensure `/data` (and any `/tmp/*` tmpfs) use the same `uid=`/`gid=` and that host bind mounts are chowned to that UID/GID.
+- Recreate the container so ownership is consistent.
 
 ## Additional Resources
 
-Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
-
-For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
+- Default compose and tmpfs guidance: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
+- General Docker install and runtime notes: [DOCKER_INSTALLATION.md](https://docs.netalertx.com/DOCKER_INSTALLATION)

docs/docker-troubleshooting/missing-capabilities.md

@@ -29,4 +29,22 @@ Add the required capabilities to your container:
 
 Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
 
-For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
+
+## CAP_CHOWN required when cap_drop: [ALL]
+
+When you start NetAlertX with `cap_drop: [ALL]`, the container loses `CAP_CHOWN`. The root priming step needs `CAP_CHOWN` to adjust ownership of `/data` and `/tmp` before dropping privileges to `PUID:PGID`. Without it, startup fails with a fatal `failed to chown` message and exits.
+
+To fix:
+- Add `CHOWN` back in `cap_add` when you also set `cap_drop: [ALL]`:
+
+  ```yaml
+  cap_drop:
+    - ALL
+  cap_add:
+    - CHOWN
+  ```
+
+- Or pre-chown the mounted host paths to your target `PUID:PGID` so the priming step does not need the capability.
+
+If you harden capabilities further, expect priming to fail until you restore the minimum set needed for ownership changes.

docs/docker-troubleshooting/mount-configuration-issues.md

@@ -33,4 +33,4 @@ volumes:
 
 Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
 
-For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)

docs/docker-troubleshooting/network-mode.md

@@ -24,4 +24,4 @@ Enable host networking mode:
 
 Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
 
-For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)

docs/docker-troubleshooting/nginx-configuration-mount.md

@@ -33,4 +33,4 @@ If you don't need a custom port, simply omit the PORT environment variable and t
 
 Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
 
-For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)

docs/docker-troubleshooting/port-conflicts.md

@@ -83,4 +83,4 @@ services:
 
 Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
 
-For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)

docs/docker-troubleshooting/read-only-filesystem.md

@@ -24,4 +24,4 @@ Enable read-only mode:
 
 Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
 
-For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)

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

@@ -26,4 +26,4 @@ After making these changes, restart the container. The application will automati
 
 Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
 
-For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)

docs/img/REVERSE_PROXY/reverse_proxy_flow.drawio

@@ -0,0 +1,202 @@
+<mxfile host="Electron" modified="2026-01-15T05:36:26.645Z" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/24.1.0 Chrome/120.0.6099.109 Electron/28.1.0 Safari/537.36" etag="OpSjRPjeNeyudFLZJ2fD" version="24.1.0" type="device">
+  <diagram name="Page-1" id="mulIpG3YQAhf4Klf7Njm">
+    <mxGraphModel dx="6733" dy="1168" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="4681" pageHeight="3300" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-1" value="" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="850" y="160" width="920" height="810" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-2" value="NetAlertX Pod" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=32;" vertex="1" parent="1">
+          <mxGeometry x="850" y="130" width="670" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-3" value="" style="image;html=1;image=img/lib/clip_art/computers/Laptop_128x128.png" vertex="1" parent="1">
+          <mxGeometry x="-50" y="395" width="140" height="140" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-4" value="" style="image;html=1;image=img/lib/clip_art/networking/Firewall_02_128x128.png" vertex="1" parent="1">
+          <mxGeometry x="488" y="344" width="80" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-5" value="" style="image;html=1;image=img/lib/clip_art/networking/Firewall_02_128x128.png" vertex="1" parent="1">
+          <mxGeometry x="488" y="555" width="80" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-8" value="Web UI&lt;br&gt;(NGINX + PHP)" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;" vertex="1" parent="1">
+          <mxGeometry x="230" y="320" width="200" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-9" value="API GraphQL&lt;br&gt;(Python)" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;" vertex="1" parent="1">
+          <mxGeometry x="230" y="555" width="200" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-10" value="" style="endArrow=classic;html=1;rounded=0;dashed=1;dashPattern=8 8;" edge="1" parent="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="240" y="390" as="sourcePoint" />
+            <mxPoint x="240" y="600" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-12" value="&lt;div&gt;443&lt;/div&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;fontColor=#FF0000;" vertex="1" parent="1">
+          <mxGeometry x="581" y="335" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-13" value="20212" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;fontColor=#FF0000;" vertex="1" parent="1">
+          <mxGeometry x="581" y="554" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-14" value="" style="image;html=1;image=img/lib/clip_art/networking/Firewall_02_128x128.png" vertex="1" parent="1">
+          <mxGeometry x="488" y="813" width="80" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-16" value="Authentik SSO for Web UI" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;" vertex="1" parent="1">
+          <mxGeometry x="230" y="793" width="200" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-17" value="9443" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;fontColor=#FF0000;" vertex="1" parent="1">
+          <mxGeometry x="580" y="803" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-18" value="" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="1470" y="250" width="288" height="440" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-19" value="NetAlertX" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;" vertex="1" parent="1">
+          <mxGeometry x="1470" y="210" width="288" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-21" value="" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="1260" y="751" width="500" height="199" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-22" value="Authentik Outpost Proxy" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;" vertex="1" parent="1">
+          <mxGeometry x="1280" y="711" width="480" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-23" value="" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="860" y="250" width="380" height="700" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-24" value="Caddy" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;" vertex="1" parent="1">
+          <mxGeometry x="860" y="210" width="390" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-25" value="" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="1498" y="319" width="220" height="130" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-26" value="" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="1498" y="530" width="220" height="150" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-27" value="Web UI&lt;div&gt;(NGINX + PHP)&lt;/div&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;" vertex="1" parent="1">
+          <mxGeometry x="1498" y="264" width="220" height="50" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-28" value="API GraphQL&lt;div&gt;(Python)&lt;/div&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;" vertex="1" parent="1">
+          <mxGeometry x="1498" y="475" width="220" height="50" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-6" value="" style="endArrow=classic;html=1;rounded=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="wwqsnaxs0Bt7SYwqQu8i-53" target="wwqsnaxs0Bt7SYwqQu8i-58">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="130" y="390" as="sourcePoint" />
+            <mxPoint x="1129" y="389.9999999999998" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-30" value="" style="endArrow=classic;html=1;rounded=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" source="wwqsnaxs0Bt7SYwqQu8i-59" target="wwqsnaxs0Bt7SYwqQu8i-31">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="1214" y="483" as="sourcePoint" />
+            <mxPoint x="1209" y="823" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-31" value="Authenticated &amp;amp; Authorized ?" style="rhombus;whiteSpace=wrap;html=1;fontSize=18;" vertex="1" parent="1">
+          <mxGeometry x="1294" y="773.5" width="170" height="160" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-35" value="20211" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;fontColor=#FF0000;" vertex="1" parent="1">
+          <mxGeometry x="1488" y="335" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-36" value="" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="1688" y="369" as="sourcePoint" />
+            <mxPoint x="1688" y="649" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-37" value="20219" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;fontColor=#FF0000;" vertex="1" parent="1">
+          <mxGeometry x="1498" y="535" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-38" value="HTTPS" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;fontColor=#66CC00;" vertex="1" parent="1">
+          <mxGeometry x="730" y="340" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-39" value="HTTPS" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;fontColor=#66CC00;" vertex="1" parent="1">
+          <mxGeometry x="730" y="803" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-40" value="HTTPS" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;fontColor=#66CC00;" vertex="1" parent="1">
+          <mxGeometry x="730" y="554" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-42" value="" style="endArrow=none;html=1;rounded=0;endFill=0;" edge="1" parent="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="1381" y="1071" as="sourcePoint" />
+            <mxPoint x="130" y="1071" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-43" value="" style="endArrow=classic;html=1;rounded=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" edge="1" parent="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="130.5" y="1070" as="sourcePoint" />
+            <mxPoint x="130" y="860" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-44" value="NO" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;" vertex="1" parent="1">
+          <mxGeometry x="1364" y="1000" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-45" value="YES" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;" vertex="1" parent="1">
+          <mxGeometry x="1294" y="680" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-47" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="1156.5" y="450" as="sourcePoint" />
+            <mxPoint x="1157" y="1070" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-48" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="wwqsnaxs0Bt7SYwqQu8i-56" target="wwqsnaxs0Bt7SYwqQu8i-26">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="1299" y="600" as="sourcePoint" />
+            <mxPoint x="1499" y="600" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-49" value="HTTP" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;fontColor=#FF0000;" vertex="1" parent="1">
+          <mxGeometry x="1379" y="340" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-50" value="HTTP" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=24;fontColor=#FF0000;" vertex="1" parent="1">
+          <mxGeometry x="1379" y="554" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-54" value="" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" target="wwqsnaxs0Bt7SYwqQu8i-53">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="130" y="390" as="sourcePoint" />
+            <mxPoint x="1129" y="390" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-53" value="TLS Termination" style="whiteSpace=wrap;html=1;aspect=fixed;fontSize=18;" vertex="1" parent="1">
+          <mxGeometry x="905" y="340" width="100" height="100" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-56" value="TLS Termination" style="whiteSpace=wrap;html=1;aspect=fixed;fontSize=18;" vertex="1" parent="1">
+          <mxGeometry x="902" y="554" width="100" height="100" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-7" value="" style="endArrow=classic;html=1;rounded=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" target="wwqsnaxs0Bt7SYwqQu8i-56">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="130" y="601" as="sourcePoint" />
+            <mxPoint x="850" y="601" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-58" value="Check Authentication" style="whiteSpace=wrap;html=1;aspect=fixed;fontSize=18;" vertex="1" parent="1">
+          <mxGeometry x="1097" y="330" width="120" height="120" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-59" value="TLS Termination" style="whiteSpace=wrap;html=1;aspect=fixed;fontSize=18;" vertex="1" parent="1">
+          <mxGeometry x="899" y="803" width="100" height="100" as="geometry" />
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-15" value="" style="endArrow=classic;html=1;rounded=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" target="wwqsnaxs0Bt7SYwqQu8i-59">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="30" y="853" as="sourcePoint" />
+            <mxPoint x="850" y="853" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-60" value="" style="endArrow=classic;html=1;rounded=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="1379" y="390" as="sourcePoint" />
+            <mxPoint x="1500" y="389.58" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-61" value="" style="endArrow=none;html=1;rounded=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;endFill=0;" edge="1" parent="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="1379" y="773" as="sourcePoint" />
+            <mxPoint x="1379" y="390" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="wwqsnaxs0Bt7SYwqQu8i-62" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="1380" y="933.5" as="sourcePoint" />
+            <mxPoint x="1379" y="1069" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

docs/index.md

@@ -1,3 +1,9 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
 # NetAlertX Documentation
 
 Welcome to the official NetAlertX documentation! NetAlertX is a powerful tool designed to simplify the management and monitoring of your network. Below, you will find guides and resources to help you set up, configure, and troubleshoot your NetAlertX instance.
@@ -15,7 +21,7 @@ NetAlertX provides contextual help within the application:
 
 ## Installation Guides
 
-The app can be installed different ways, with the best support of the docker-based deployments. This includes the Home Assistant and Unraid installation approaches. See details below. 
+The app can be installed different ways, with the best support of the docker-based deployments. This includes the Home Assistant and Unraid installation approaches. See details below.
 
 ### Docker (Fully Supported)
 
@@ -29,13 +35,13 @@ This guide will take you through the process of setting up NetAlertX using Docke
 
 You can install NetAlertX also as a Home Assistant addon [![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) via the [alexbelgium/hassio-addons](https://github.com/alexbelgium/hassio-addons/) repository. This is only possible if you run a supervised instance of Home Assistant. If not, you can still run NetAlertX in a separate Docker container and follow this guide to configure MQTT.
 
-- [[Installation] Home Assistant](https://github.com/alexbelgium/hassio-addons/tree/master/netalertx) 
+- [[Installation] Home Assistant](https://github.com/alexbelgium/hassio-addons/tree/master/netalertx)
 
 ### Unraid (Partial Support)
 
-The Unraid template was created by the community, so it's only partially supported. Alternatively, here is [another version of the Unraid template](https://github.com/jokob-sk/NetAlertX-unraid). 
+The Unraid template was created by the community, so it's only partially supported. Alternatively, here is [another version of the Unraid template](https://github.com/jokob-sk/NetAlertX-unraid).
 
-- [[Installation] Unraid App](https://unraid.net/community/apps) 
+- [[Installation] Unraid App](https://unraid.net/community/apps)
 
 ### Bare-Metal Installation (Experimental)
 
@@ -55,7 +61,7 @@ If you need help or run into issues, here are some resources to guide you:
   - [Check common issues](./DEBUG_TIPS.md#common-issues) to see if your problem has already been reported.
   - [Look at closed issues](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed) for possible solutions to past problems.
   - **Enable debugging** to gather more information: [Debug Guide](./DEBUG_TIPS.md).
-  
+
 **Need more help?** Join the community discussions or submit a support request:
 
   - Visit the [GitHub Discussions](https://github.com/jokob-sk/NetAlertX/discussions) for community support.

front/appEventsCore.php

@@ -1,5 +1,5 @@
-<span class="helpIcon"> 
-    <a target="_blank" href="https://github.com/jokob-sk/NetAlertX/blob/main/docs/WORKFLOWS_DEBUGGING.md">
+<span class="helpIcon">
+    <a target="_blank" href="https://docs.netalertx.com/WORKFLOWS_DEBUGGING">
       <i class="fa fa-circle-question"></i>
     </a>
   </span>
@@ -21,114 +21,170 @@
 // show loading dialog
 showSpinner()
 
-$(document).ready(function() {
+$(document).ready(function () {
 
-  // Load JSON data from the provided URL
-  $.getJSON('php/server/query_json.php?file=table_appevents.json', function(data) {
-    // Process the JSON data and generate UI dynamically    
-    processData(data)
+  const apiToken = getSetting("API_TOKEN");
+  const apiBase = getApiBase();
+  const graphqlUrl = `${apiBase}/graphql`;
 
-    // hide loading dialog
-    hideSpinner()
-  });
-});
-
-function processData(data) {
-  // Create an object to store unique ObjectType values as app event identifiers
-  var appEventIdentifiers = {};
-
-  // Array to accumulate data for DataTable
-  var allData = [];
-
-  // Iterate through the data and generate tabs and content dynamically
-  $.each(data.data, function(index, item) {
-    
-    // Accumulate data for DataTable
-    allData.push(item);
-    
-  });
-
-  console.log(allData);
-  
-
-  // Initialize DataTable for all app events
-  
   $('#appevents-table').DataTable({
-    data: allData,
+    processing: true,
+    serverSide: true,
     paging: true,
-    lengthChange: true,
-    lengthMenu: [[10, 25, 50, 100, 500, -1], [10, 25, 50, 100, 500, 'All']],
     searching: true,
     ordering: true,
-    info: true,
-    autoWidth: false,
-    pageLength: 25, // Set the default paging to 25
+    pageLength: 25,
+    lengthMenu: [[10, 25, 50, 100], [10, 25, 50, 100]],
+
+    ajax: function (dtRequest, callback) {
+
+      const page = Math.floor(dtRequest.start / dtRequest.length) + 1;
+      const limit = dtRequest.length;
+
+      // ---- SEARCH ----
+      const searchValue = dtRequest.search?.value || null;
+
+      // ---- SORTING ----
+      let sort = [];
+      if (dtRequest.order && dtRequest.order.length > 0) {
+        const order = dtRequest.order[0];
+        const columnName = dtRequest.columns[order.column].data;
+
+        sort.push({
+          field: columnName,
+          order: order.dir
+        });
+      }
+
+      const query = `
+        query AppEvents($options: PageQueryOptionsInput) {
+          appEvents(options: $options) {
+            count
+            appEvents {
+              DateTimeCreated
+              AppEventProcessed
+              AppEventType
+              ObjectType
+              ObjectPrimaryID
+              ObjectSecondaryID
+              ObjectStatus
+              ObjectPlugin
+              ObjectGUID
+              GUID
+            }
+          }
+        }
+      `;
+
+      const variables = {
+        options: {
+          page: page,
+          limit: limit,
+          search: searchValue,
+          sort: sort
+        }
+      };
+
+      $.ajax({
+        method: "POST",
+        url: graphqlUrl,
+        headers: {
+          "Authorization": "Bearer " + apiToken,
+          "Content-Type": "application/json"
+        },
+        data: JSON.stringify({
+          query: query,
+          variables: variables
+        }),
+        success: function (response) {
+          if (response.errors) {
+            console.error(response.errors);
+            callback({
+              data: [],
+              recordsTotal: 0,
+              recordsFiltered: 0
+            });
+            return;
+          }
+
+          const result = response.data.appEvents;
+
+          callback({
+            data: result.appEvents,
+            recordsTotal: result.count,
+            recordsFiltered: result.count
+          });
+
+          hideSpinner();
+        },
+        error: function () {
+          callback({
+            data: [],
+            recordsTotal: 0,
+            recordsFiltered: 0
+          });
+        }
+      });
+    },
+
     columns: [
       { data: 'DateTimeCreated', title: getString('AppEvents_DateTimeCreated') },
       { data: 'AppEventProcessed', title: getString('AppEvents_AppEventProcessed') },
-      { data: 'AppEventType', title: getString('AppEvents_Type') }, 
+      { data: 'AppEventType', title: getString('AppEvents_Type') },
       { data: 'ObjectType', title: getString('AppEvents_ObjectType') },
       { data: 'ObjectPrimaryID', title: getString('AppEvents_ObjectPrimaryID') },
       { data: 'ObjectSecondaryID', title: getString('AppEvents_ObjectSecondaryID') },
-      { data: 'ObjectStatus', title: getString('AppEvents_ObjectStatus') },            
-      { data: 'ObjectPlugin', title: getString('AppEvents_Plugin') },  
-      { data: 'ObjectGUID', title: "Object GUID" },  
-      { data: 'GUID', title: "Event GUID" },  
-      // Add other columns as needed
+      { data: 'ObjectStatus', title: getString('AppEvents_ObjectStatus') },
+      { data: 'ObjectPlugin', title: getString('AppEvents_Plugin') },
+      { data: 'ObjectGUID', title: 'Object GUID' },
+      { data: 'GUID', title: 'Event GUID' }
     ],
-    // Add column-specific configurations if needed
-    columnDefs: [
-      { className: 'text-center', targets: [4] },
-      { width: '80px', targets: [7] },
-      // ... Add other columnDefs as needed
-      // Full MAC    
-      {targets: [4, 5],
-      'createdCell': function (td, cellData, rowData, row, col) {
-        if (!emptyArr.includes(cellData)){
-          $(td).html (createDeviceLink(cellData));
-        } else {
-          $(td).html ('');
-        }
-      } },
-      // Processed 
-      {targets: [1],
-        'createdCell': function (td, cellData, rowData, row, col) {
-          // console.log(cellData);
-          $(td).html (cellData);          
-        } 
-      },
-      // Datetime
-      {targets: [0],
-        'createdCell': function (td, cellData, rowData, row, col) {
-          let timezone = $("#NAX_TZ").html(); // e.g., 'Europe/Berlin'
-          let utcDate = new Date(cellData + ' UTC'); // Adding ' UTC' makes it interpreted as UTC time
 
-          // Format the date in the desired timezone
+    columnDefs: [
+      { className: 'text-center', targets: [1, 4] },
+      { width: '90px', targets: [7] },
+
+      // Device links
+      {
+        targets: [4, 5],
+        createdCell: function (td, cellData) {
+          if (!emptyArr.includes(cellData)) {
+            $(td).html(createDeviceLink(cellData));
+          } else {
+            $(td).html('');
+          }
+        }
+      },
+
+      // Date formatting
+      {
+        targets: [0],
+        createdCell: function (td, cellData) {
+          let timezone = $("#NAX_TZ").html();
+          let utcDate = new Date(cellData + ' UTC');
+
           let options = {
-              year: 'numeric',
-              month: 'short',
-              day: '2-digit',
-              hour: '2-digit',
-              minute: '2-digit',
-              second: '2-digit',
-              hour12: false, // Use 24-hour format
-              timeZone: timezone // Use the specified timezone
+            year: 'numeric',
+            month: 'short',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+            hour12: false,
+            timeZone: timezone
           };
 
-          let localDate = new Intl.DateTimeFormat('en-GB', options).format(utcDate);
-
-          // Update the table cell
-          $(td).html(localDate);    
-        } 
-      },
+          $(td).html(
+            new Intl.DateTimeFormat('en-GB', options).format(utcDate)
+          );
+        }
+      }
     ]
   });
 
 
-  // Activate the first tab
-  $('#tabs-location li:first-child').addClass('active');
-  $('#tabs-content-location .tab-pane:first-child').addClass('active');
-}
+});
+
 
 </script>
 

front/css/app.css

@@ -664,7 +664,9 @@ body
     border-right: 5px solid #606060;
 }
 
-
+.fc-ltr .fc-time-grid .fc-event-container {
+  margin: 0 2.5% 0 0px !important;
+}
 
 /* -----------------------------------------------------------------------------
    Notification float banner

front/deviceDetails.php

@@ -1,7 +1,7 @@
 <!--
 #---------------------------------------------------------------------------------#
 #  NetAlertX                                                                       #
-#  Open Source Network Guard / WIFI & LAN intrusion detector                      #  
+#  Open Source Network Guard / WIFI & LAN intrusion detector                      #
 #                                                                                 #
 #  deviceDetails.php - Front module. Device management page                       #
 #---------------------------------------------------------------------------------#
@@ -34,8 +34,8 @@
       <div id="devicePageInfoPlc" class="card-body bg-light">
           <div class="small-box panel  rounded">
               <div class="inner text-center">
-                  
-              </div>                    
+
+              </div>
           </div>
       </div>
 
@@ -50,7 +50,7 @@
         </select>
       </span>
     </section>
-    
+
 <!-- Main content ---------------------------------------------------------- -->
     <section class="content">
 
@@ -62,51 +62,51 @@
         <!-- <div class="box-transparent"> -->
           <div id="navDevice" class="nav-tabs-custom">
             <ul class="nav nav-tabs" style="font-size:16px;">
-              <li> 
-                <a id="tabDetails"  href="#panDetails"  data-toggle="tab"> 
-                  <i class="fa fa-info-circle"></i> 
-                    <span class="dev-detail-tab-name"> 
-                      <?= lang('DevDetail_Tab_Details');?>  
+              <li>
+                <a id="tabDetails"  href="#panDetails"  data-toggle="tab">
+                  <i class="fa fa-info-circle"></i>
+                    <span class="dev-detail-tab-name">
+                      <?= lang('DevDetail_Tab_Details');?>
                     </span>
                 </a>
                 </li>
-                <li> 
-                <a id="tabTools"    href="#panTools"    data-toggle="tab"> 
-                  <i class="fa fa-screwdriver-wrench"></i> 
+                <li>
+                <a id="tabTools"    href="#panTools"    data-toggle="tab">
+                  <i class="fa fa-screwdriver-wrench"></i>
                     <span class="dev-detail-tab-name">
-                      <?= lang('DevDetail_Tab_Tools');?>    
+                      <?= lang('DevDetail_Tab_Tools');?>
                     </span>
                 </a>
                 </li>
-              <li> 
-                <a id="tabSessions" href="#panSessions" data-toggle="tab"> 
-                  <i class="fa fa-list-ol"></i> 
+              <li>
+                <a id="tabSessions" href="#panSessions" data-toggle="tab">
+                  <i class="fa fa-list-ol"></i>
                     <span class="dev-detail-tab-name">
-                      <?= lang('DevDetail_Tab_Sessions');?> 
+                      <?= lang('DevDetail_Tab_Sessions');?>
                     </span>
                 </a>
                 </li>
-              <li> 
-                <a id="tabPresence" href="#panPresence" data-toggle="tab"> 
-                  <i class="fa fa-calendar"></i> 
-                    <span class="dev-detail-tab-name"> 
-                      <?= lang('DevDetail_Tab_Presence');?> 
+              <li>
+                <a id="tabPresence" href="#panPresence" data-toggle="tab">
+                  <i class="fa fa-calendar"></i>
+                    <span class="dev-detail-tab-name">
+                      <?= lang('DevDetail_Tab_Presence');?>
                     </span>
                 </a>
                 </li>
-              <li> 
-                <a id="tabEvents"   href="#panEvents"   data-toggle="tab"> 
-                  <i class="fa fa-bolt"></i>  
+              <li>
+                <a id="tabEvents"   href="#panEvents"   data-toggle="tab">
+                  <i class="fa fa-bolt"></i>
                     <span class="dev-detail-tab-name">
-                      <?= lang('DevDetail_Tab_Events');?>   
+                      <?= lang('DevDetail_Tab_Events');?>
                     </span>
                 </a>
-                </li>              
-              <li> 
-                <a id="tabPlugins"  href="#panPlugins"  data-toggle="tab"> 
-                  <i class="fa fa-plug"></i> 
+                </li>
+              <li>
+                <a id="tabPlugins"  href="#panPlugins"  data-toggle="tab">
+                  <i class="fa fa-plug"></i>
                     <span class="dev-detail-tab-name">
-                      <?= lang('DevDetail_Tab_Plugins');?>  
+                      <?= lang('DevDetail_Tab_Plugins');?>
                     </span>
                 </a>
                 </li>
@@ -122,34 +122,34 @@
                   id="btnNext"     onclick="recordSwitch('next')"> <i class="fa fa-chevron-right"></i> </button>
               </div>
             </ul>
-            
+
             <div class="tab-content spinnerTarget" style="min-height: 430px;">
 
 <!-- tab page 1 ------------------------------------------------------------ -->
 
               <div class="tab-pane fade" id="panDetails">
-                <?php  
+                <?php
                   require 'deviceDetailsEdit.php';
                 ?>
-              </div>                                                                         
+              </div>
 
 <!-- tab page 2 ------------------------------------------------------------ -->
               <div class="tab-pane fade table-responsive" id="panSessions">
-              <?php  
+              <?php
                   require 'deviceDetailsSessions.php';
                 ?>
               </div>
-        
+
 <!-- tab page "Tools" ------------------------------------------------------------ -->
 
               <div class="tab-pane fade" id="panTools">
-                <?php  
+                <?php
                   require 'deviceDetailsTools.php';
-                ?>        	      
+                ?>
               </div>
 
 <!-- tab page 3 ------------------------------------------------------------ -->
-              <div class="tab-pane fade table-responsive" id="panPresence">                
+              <div class="tab-pane fade table-responsive" id="panPresence">
                 <?php
                   // Include the other page
                   include 'deviceDetailsPresence.php';
@@ -161,7 +161,7 @@
               <?php
                   // Include the other page
                   include 'deviceDetailsEvents.php';
-                ?>                
+                ?>
               </div>
 
 <!-- tab page 7 ------------------------------------------------------------ -->
@@ -194,7 +194,7 @@
   require 'php/templates/footer.php';
 ?>
 
-  
+
   <!-- ----------------------------------------------------------------------- -->
 
 <!-- Dark-Mode Patch -->
@@ -215,10 +215,10 @@ switch ($UI_THEME) {
 
   // ------------------------------------------------------------
 
-  mac                     = getMac()  // can also be rowID!! not only mac 
-  var devicesList         = [];   // this will contain a list the database row IDs of the devices ordered by the position displayed in the UI  
+  mac                     = getMac()  // can also be rowID!! not only mac
+  var devicesList         = [];   // this will contain a list the database row IDs of the devices ordered by the position displayed in the UI
 
-  var pos                 = -1;  
+  var pos                 = -1;
   var parPeriod           = 'Front_Details_Period';
 
   var tab                 = 'tabDetails'
@@ -250,16 +250,16 @@ function main () {
   period = '1 day';
   sessionsRows = 50;
   eventsRows = 50;
-  // $('#chkHideConnectionEvents')[0].checked = eval(eventsHide == 'true');  
+  // $('#chkHideConnectionEvents')[0].checked = eval(eventsHide == 'true');
 
   // Initialize components with parameters
-   	
+
 
   // Init tabs once DOM ready
   $( document ).ready(function() {
     initializeTabs();
   });
-         
+
 }
 
 
@@ -272,7 +272,7 @@ function periodChanged () {
 
 
 // -----------------------------------------------------------------------------
-// Left (prev) < > (next) Right toggles at the top right of device details to 
+// Left (prev) < > (next) Right toggles at the top right of device details to
 // cycle between devices
 function recordSwitch(direction) {
 
@@ -281,7 +281,7 @@ function recordSwitch(direction) {
     showModalDefaultStrParam ('Unsaved changes', 'Do you want to discard your changes?',
       '<?= lang('Gen_Cancel');?>', '<?= lang('Gen_Okay');?>', performSwitch, direction);
   } else
-  {    
+  {
     performSwitch(direction)
   }
 }
@@ -354,7 +354,7 @@ function performSwitch(direction)
   // Update the global position in the devices list variable 'pos'
   if (direction === "next") {
     console.log("direction:" + direction);
-    
+
     if (pos < devicesList.length) {
       pos++;
     }
@@ -377,13 +377,13 @@ function performSwitch(direction)
 
 // -----------------------------------------------------------------------------
 // Activate save & restore on any value change
-$(document).on('input', 'input:text', function() {  
+$(document).on('input', 'input:text', function() {
   settingsChanged();
 });
 
 // -----------------------------------------------------------------------------
 
-function initializeTabs () {  
+function initializeTabs () {
 
   key ="activeDevicesTab"
 
@@ -392,7 +392,7 @@ function initializeTabs () {
   {
     selectedTab = getCache(key);
   }
-  
+
   $('.nav-tabs a[id='+ selectedTab +']').tab('show');
 
   // When changed save new current tab
@@ -410,15 +410,28 @@ function initializeTabs () {
 //------------------------------------------------------------------------------
 //  Render the small boxes on top
 async function renderSmallBoxes() {
-    
+
     try {
         // Show loading dialog
         showSpinner();
 
         // Get data from the server
-        const response = await fetch(`php/server/devices.php?action=getServerDeviceData&mac=${getMac()}&period=${period}`);
+        const apiToken = getSetting("API_TOKEN");
+
+        const apiBaseUrl = getApiBase();
+        const url = `${apiBaseUrl}/device/${getMac()}?period=${encodeURIComponent(period)}`;
+
+        const response = await fetch(url, {
+          method: "GET",
+          headers: {
+            "Authorization": `Bearer ${apiToken}`,
+            "Content-Type": "application/json"
+          }
+        });
+
         if (!response.ok) {
-            throw new Error(`Error fetching device data: ${response.statusText}`);
+          const text = await response.text();
+          throw new Error(`Error fetching device data: ${response.status} ${text}`);
         }
 
         const deviceData = await response.json();
@@ -549,6 +562,7 @@ function updateDevicePageName(mac) {
 
 window.onload = function async()
 {
+  mac = getMac()
   // initializeTabs();
   updateChevrons(mac);
   updateDevicePageName(mac);