TEST: scan processing - de;eted

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

@@ -1,112 +1,311 @@
-# DO NOT MODIFY THIS FILE DIRECTLY. IT IS AUTO-GENERATED BY .devcontainer/scripts/generate-dockerfile.sh
+# DO NOT MODIFY THIS FILE DIRECTLY. IT IS AUTO-GENERATED BY .devcontainer/scripts/generate-configs.sh
 
 # ---/Dockerfile---
+# 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
+# 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
+# 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
+# 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.
+#
+# This file can be built with `docker-compose -f docker-compose.yml up --build --force-recreate`
+
 FROM alpine:3.22 AS builder
 
 ARG INSTALL_DIR=/app
 
 ENV PYTHONUNBUFFERED=1
-
-# Install build dependencies
-RUN apk add --no-cache bash shadow python3 python3-dev gcc musl-dev libffi-dev openssl-dev git \
-    && python -m venv /opt/venv
-
-# Enable venv
 ENV PATH="/opt/venv/bin:$PATH"
 
+# Install build dependencies
+COPY requirements.txt /tmp/requirements.txt
+# 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
 
-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 zeroconf git+https://github.com/foreign-sub/aiofreepybox.git
+# 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
 
-# Append Iliadbox certificate to aiofreepybox
-
-# second stage
+# second stage is the main runtime stage with just the minimum required to run the application
+# The runner is used for both devcontainer, and as a base for the hardened stage.
 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
 
-COPY --from=builder /opt/venv /opt/venv
-COPY --from=builder /usr/sbin/usermod /usr/sbin/groupmod /usr/sbin/
+# NetAlertX app directories
+ENV NETALERTX_APP=${INSTALL_DIR}
+ENV NETALERTX_DATA=/data
+ENV NETALERTX_CONFIG=${NETALERTX_DATA}/config
+ENV NETALERTX_FRONT=${NETALERTX_APP}/front
+ENV NETALERTX_PLUGINS=${NETALERTX_FRONT}/plugins
+ENV NETALERTX_SERVER=${NETALERTX_APP}/server
+ENV NETALERTX_API=/tmp/api
+ENV NETALERTX_DB=${NETALERTX_DATA}/db
+ENV NETALERTX_DB_FILE=${NETALERTX_DB}/app.db
+ENV NETALERTX_BACK=${NETALERTX_APP}/back
+ENV NETALERTX_LOG=/tmp/log
+ENV NETALERTX_PLUGINS_LOG=${NETALERTX_LOG}/plugins
+ENV NETALERTX_CONFIG_FILE=${NETALERTX_CONFIG}/app.conf
 
-# Enable venv
-ENV PATH="/opt/venv/bin:$PATH" 
+# NetAlertX log files
+ENV LOG_IP_CHANGES=${NETALERTX_LOG}/IP_changes.log
+ENV LOG_APP=${NETALERTX_LOG}/app.log
+ENV LOG_APP_FRONT=${NETALERTX_LOG}/app_front.log
+ENV LOG_REPORT_OUTPUT_TXT=${NETALERTX_LOG}/report_output.txt
+ENV LOG_DB_IS_LOCKED=${NETALERTX_LOG}/db_is_locked.log
+ENV LOG_REPORT_OUTPUT_HTML=${NETALERTX_LOG}/report_output.html
+ENV LOG_STDERR=${NETALERTX_LOG}/stderr.log
+ENV LOG_APP_PHP_ERRORS=${NETALERTX_LOG}/app.php_errors.log
+ENV LOG_EXECUTION_QUEUE=${NETALERTX_LOG}/execution_queue.log
+ENV LOG_REPORT_OUTPUT_JSON=${NETALERTX_LOG}/report_output.json
+ENV LOG_STDOUT=${NETALERTX_LOG}/stdout.log
+ENV LOG_CRON=${NETALERTX_LOG}/cron.log
+ENV LOG_NGINX_ERROR=${NETALERTX_LOG}/nginx-error.log
 
-# default port and listen address
-ENV PORT=20211 LISTEN_ADDR=0.0.0.0 
+# System Services configuration files
+ENV ENTRYPOINT_CHECKS=/entrypoint.d
+ENV SYSTEM_SERVICES=/services
+ENV SYSTEM_SERVICES_SCRIPTS=${SYSTEM_SERVICES}/scripts
+ENV SYSTEM_SERVICES_CONFIG=${SYSTEM_SERVICES}/config
+ENV SYSTEM_NGINX_CONFIG=${SYSTEM_SERVICES_CONFIG}/nginx
+ENV SYSTEM_NGINX_CONFIG_TEMPLATE=${SYSTEM_NGINX_CONFIG}/netalertx.conf.template
+ENV SYSTEM_SERVICES_CONFIG_CRON=${SYSTEM_SERVICES_CONFIG}/cron
+ENV SYSTEM_SERVICES_ACTIVE_CONFIG=/tmp/nginx/active-config
+ENV SYSTEM_SERVICES_ACTIVE_CONFIG_FILE=${SYSTEM_SERVICES_ACTIVE_CONFIG}/nginx.conf
+ENV SYSTEM_SERVICES_PHP_FOLDER=${SYSTEM_SERVICES_CONFIG}/php
+ENV SYSTEM_SERVICES_PHP_FPM_D=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.d
+ENV SYSTEM_SERVICES_RUN=/tmp/run
+ENV SYSTEM_SERVICES_RUN_TMP=${SYSTEM_SERVICES_RUN}/tmp
+ENV SYSTEM_SERVICES_RUN_LOG=${SYSTEM_SERVICES_RUN}/logs
+ENV PHP_FPM_CONFIG_FILE=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.conf
+ENV READ_ONLY_FOLDERS="${NETALERTX_BACK} ${NETALERTX_FRONT} ${NETALERTX_SERVER} ${SYSTEM_SERVICES} \
+                       ${SYSTEM_SERVICES_CONFIG} ${ENTRYPOINT_CHECKS}"
+ENV READ_WRITE_FOLDERS="${NETALERTX_DATA} ${NETALERTX_CONFIG} ${NETALERTX_DB} ${NETALERTX_API} \
+                       ${NETALERTX_LOG} ${NETALERTX_PLUGINS_LOG} ${SYSTEM_SERVICES_RUN} \
+                       ${SYSTEM_SERVICES_RUN_TMP} ${SYSTEM_SERVICES_RUN_LOG} \
+                       ${SYSTEM_SERVICES_ACTIVE_CONFIG}"
 
-# needed for s6-overlay
-ENV S6_CMD_WAIT_FOR_SERVICES_MAXTIME=0
+#Python environment
+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"
 
-# ❗ IMPORTANT - if you modify this file modify the /install/install_dependecies.sh file as well ❗ 
-
-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 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 \
-    && rm -f /etc/nginx/http.d/default.conf
+# App Environment
+ENV LISTEN_ADDR=0.0.0.0
+ENV PORT=20211
+ENV NETALERTX_DEBUG=0
+ENV VENDORSPATH=/app/back/ieee-oui.txt
+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
 
 
-# Add crontab file
-COPY --chmod=600 --chown=root:root install/crontab /etc/crontabs/root
+RUN apk add --no-cache bash mtr libbsd zip lsblk tzdata curl arp-scan iproute2 iproute2-ss nmap fping \
+    nmap-scripts traceroute nbtscan net-tools net-snmp-tools bind-tools awake ca-certificates \
+    sqlite php83 php83-fpm php83-cgi php83-curl php83-sqlite3 php83-session python3 envsubst \
+    nginx supercronic shadow su-exec jq && \
+    rm -Rf /var/cache/apk/*  && \
+    rm -Rf /etc/nginx && \
+    addgroup -g ${NETALERTX_GID} ${NETALERTX_GROUP} && \
+    adduser -u ${NETALERTX_UID} -D -h ${NETALERTX_APP} -G ${NETALERTX_GROUP} ${NETALERTX_USER} && \
+    apk del shadow
 
-# Start all required services
 
-HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=2 \
-    CMD curl -sf -o /dev/null ${LISTEN_ADDR}:${PORT}/php/server/query_json.php?file=app_state.json
 
-ENTRYPOINT ["/init"]
+# Install application, copy files, set permissions
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} install/production-filesystem/ /
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 back ${NETALERTX_BACK}
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 front ${NETALERTX_FRONT}
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 server ${NETALERTX_SERVER}
+
+# Create required folders with correct ownership and permissions
+RUN install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 700 ${READ_WRITE_FOLDERS} && \
+    sh -c "find ${NETALERTX_APP} -type f \( -name '*.sh' -o -name 'speedtest-cli' \) \
+    -exec chmod 750 {} \;"
+
+# Copy version information into the image
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} .[V]ERSION ${NETALERTX_APP}/.VERSION
+
+# 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; 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,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 ${VIRTUAL_ENV_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 > "${NETALERTX_FRONT}/buildtimestamp.txt"
+
+
+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
+# 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 ${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
+# Permissions 005 and 004 are not typos, they enable read-only. Everyone can
+# read the read-only files, and nobody can write to them, even the readonly user.
+
+# hadolint ignore=SC2114
+RUN chown -R ${READ_ONLY_USER}:${READ_ONLY_GROUP} ${READ_ONLY_FOLDERS} && \
+    chmod -R 004 ${READ_ONLY_FOLDERS} && \
+    find ${READ_ONLY_FOLDERS} -type d -exec chmod 005 {} + && \
+    install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 0777 ${READ_WRITE_FOLDERS} && \
+    chown ${READ_ONLY_USER}:${READ_ONLY_GROUP} /entrypoint.sh /root-entrypoint.sh /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 && \
+    # 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"
+
+# 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
+
 
 # ---/resources/devcontainer-Dockerfile---
 
 # Devcontainer build stage (do not build directly)
 # This file is combined with the root /Dockerfile by
-#   .devcontainer/scripts/generate-dockerfile.sh
+#   .devcontainer/scripts/generate-configs.sh
 # The generator appends this stage to produce .devcontainer/Dockerfile.
 # Prefer to place dev-only setup here; use setup.sh only for runtime fixes.
+# Permissions in devcontainer should be of a brutalist nature. They will be
+# Open and wide to avoid permission issues during development allowing max
+# flexibility.
 
-FROM runner AS devcontainer
-ENV INSTALL_DIR=/app 
-ENV PYTHONPATH=/workspaces/NetAlertX/test:/workspaces/NetAlertX/server:/app:/app/server:/opt/venv/lib/python3.12/site-packages
+# hadolint ignore=DL3006
+FROM runner AS netalertx-devcontainer
+ENV INSTALL_DIR=/app
 
+ENV PYTHONPATH=${PYTHONPATH}:/workspaces/NetAlertX/test:/workspaces/NetAlertX/server:/usr/lib/python3.12/site-packages
+ENV PATH=/services:${PATH}
+ENV PHP_INI_SCAN_DIR=/services/config/php/conf.d:/etc/php83/conf.d
+ENV LISTEN_ADDR=0.0.0.0
+ENV PORT=20211
+ENV NETALERTX_DEBUG=1
+ENV PYDEVD_DISABLE_FILE_VALIDATION=1
+COPY .devcontainer/resources/devcontainer-overlay/ /
+USER root
 # Install common tools, create user, and set up sudo
-RUN apk add --no-cache git nano vim jq php83-pecl-xdebug py3-pip nodejs sudo gpgconf pytest pytest-cov && \
-    adduser -D -s /bin/sh netalertx && \
-    addgroup netalertx nginx && \
-    addgroup netalertx www-data && \
-    echo "netalertx ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/90-netalertx && \
-    chmod 440 /etc/sudoers.d/90-netalertx
-# Install debugpy in the virtualenv if present, otherwise into system python3
-RUN /bin/sh -c '(/opt/venv/bin/python3 -m pip install --no-cache-dir debugpy) || (python3 -m pip install --no-cache-dir debugpy) || true'
-# setup nginx
-COPY .devcontainer/resources/netalertx-devcontainer.conf /etc/nginx/http.d/netalert-frontend.conf
-RUN set -e; \
-    chown netalertx:nginx /etc/nginx/http.d/netalert-frontend.conf; \
-    install -d -o netalertx -g www-data -m 775 /app; \
-    install -d -o netalertx -g www-data -m 755 /run/nginx; \
-    install -d -o netalertx -g www-data -m 755 /var/lib/nginx/logs; \
-    rm -f /var/lib/nginx/logs/* || true; \
-    for f in error access; do : > /var/lib/nginx/logs/$f.log; done; \
-    install -d -o netalertx -g www-data -m 777 /run/php; \
-    install -d -o netalertx -g www-data -m 775 /var/log/php; \
-    chown -R netalertx:www-data /etc/nginx/http.d; \
-    chmod -R 775 /etc/nginx/http.d; \
-    chown -R netalertx:www-data /var/lib/nginx; \
-    chmod -R 755 /var/lib/nginx && \
-    chown -R netalertx:www-data /var/log/nginx/ && \
-    sed -i '/^user /d' /etc/nginx/nginx.conf; \
-    sed -i 's|^error_log .*|error_log /dev/stderr warn;|' /etc/nginx/nginx.conf; \
-    sed -i 's|^access_log .*|access_log /dev/stdout main;|' /etc/nginx/nginx.conf; \
-    sed -i 's|error_log .*|error_log /dev/stderr warn;|g' /etc/nginx/http.d/*.conf 2>/dev/null || true; \
-    sed -i 's|access_log .*|access_log /dev/stdout main;|g' /etc/nginx/http.d/*.conf 2>/dev/null || true; \
-    mkdir -p /run/openrc; \
-    chown netalertx:nginx /run/openrc/; \
-    rm -Rf /run/openrc/*;
 
-# setup pytest
-RUN sudo /opt/venv/bin/python -m pip install -U pytest pytest-cov
+# 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
 
-WORKDIR /workspaces/NetAlertX
+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 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 && \
+    chmod +x /usr/local/bin/hadolint
 
-ENTRYPOINT ["/bin/sh","-c","sleep infinity"]
+RUN install -d -o netalertx -g netalertx -m 755 /services/php/modules && \
+    cp -a /usr/lib/php83/modules/. /services/php/modules/ && \
+    echo "${NETALERTX_USER} ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+ENV SHELL=/bin/zsh
+
+RUN mkdir -p /workspaces && \
+    install -d -m 777 /data /data/config /data/db && \
+    install -d -m 777 /tmp/log /tmp/log/plugins /tmp/api /tmp/run /tmp/nginx && \
+    install -d -m 777 /tmp/nginx/active-config /tmp/nginx/client_body /tmp/nginx/config && \
+    install -d -m 777 /tmp/nginx/fastcgi /tmp/nginx/proxy /tmp/nginx/scgi /tmp/nginx/uwsgi && \
+    install -d -m 777 /tmp/run/tmp /tmp/run/logs && \
+    chmod 777 /workspaces && \
+    chown -R netalertx:netalertx /data && \
+    chmod 666 /data/config/app.conf /data/db/app.db && \
+    chmod 1777 /tmp && \
+    install -d -o root -g root -m 1777 /tmp/.X11-unix && \
+    mkdir -p /home/netalertx && \
+    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/NetAlertX.code-workspace

@@ -0,0 +1,37 @@
+{
+	"folders": [
+		{
+			"name": "NetAlertX Source",
+			"path": "/workspaces/NetAlertX"
+		},
+		{
+			"name": "💾 NetAlertX Data",
+			"path": "/data"
+		},
+		{
+			"name": "🔍 Active NetAlertX log",
+			"path": "/tmp/log"
+		},
+		{
+			"name": "🌐 Active NetAlertX nginx",
+			"path": "/tmp/nginx"
+		},
+		{
+			"name": "📊 Active NetAlertX api",
+			"path": "/tmp/api"
+		},
+		{
+			"name": "⚙️ Active NetAlertX run",
+			"path": "/tmp/run"
+		}
+	],
+	"settings": {
+		"terminal.integrated.suggest.enabled": true,
+		"terminal.integrated.defaultProfile.linux": "zsh",
+		"terminal.integrated.profiles.linux": {
+			"zsh": {
+				"path": "/usr/bin/fish"
+			}
+		}
+	}
+}

.devcontainer/README.md

@@ -19,6 +19,17 @@ Common workflows (F1->Tasks: Run Task)
   - Backend (GraphQL/Flask): `.devcontainer/scripts/restart-backend.sh` starts it under debugpy and logs to `/app/log/app.log`
   - Frontend (nginx + PHP-FPM): Started via setup.sh; can be restarted by the task "Start Frontend (nginx and PHP-FPM)".
 
+Production Container Evaulation
+1. F1 → Tasks: Shutdown services ([Dev Container] Stop Frontend & Backend Services)
+2. F1 → Tasks: Docker system and build prune ([Any] Docker system and build Prune)
+3. F1 → Remote: Close Unused Forwarded Ports (VS Code command)
+4. F1 → Tasks: Build & Launch Production (Build & Launch Prodcution Docker 
+5. visit http://localhost:20211
+
+Unit tests
+1. F1 → Tasks: Rebuild test container ([Any] Build Unit Test Docker image)
+2. F1 → Test: Run all tests
+
 Testing
 - pytest is installed via Alpine packages (py3-pytest, py3-pytest-cov).
 - PYTHONPATH includes workspace and venv site-packages so tests can import `server/*` modules and third-party libs.

.devcontainer/WORKSPACE.md

@@ -0,0 +1,26 @@
+# NetAlertX Multi-Folder Workspace
+
+This repository uses a multi-folder workspace configuration to provide easy access to runtime directories.
+
+## Opening the Multi-Folder Workspace
+
+After the devcontainer builds, open the workspace file to access all folders:
+
+1. **File** → **Open Workspace from File**
+2. Select `NetAlertX.code-workspace`
+
+Or use Command Palette (Ctrl+Shift+P / Cmd+Shift+P):
+- Type: `Workspaces: Open Workspace from File`
+- Select `NetAlertX.code-workspace`
+
+## Workspace Folders
+
+The workspace includes:
+- **NetAlertX** - Main source code
+- **/tmp** - Runtime temporary files
+- **/tmp/api** - API response cache (JSON files)
+- **/tmp/log** - Application and plugin logs
+
+## Testing Configuration
+
+Pytest is configured to only discover tests in the main `test/` directory, not in `/tmp` folders.

.devcontainer/devcontainer.json

@@ -1,27 +1,59 @@
 {
   "name": "NetAlertX DevContainer",
   "remoteUser": "netalertx",
-  "build": {
-    "dockerfile": "Dockerfile",
-    "context": "..",
-    "target": "devcontainer"
-  },
   "workspaceFolder": "/workspaces/NetAlertX",
-  "runArgs": [
-    "--add-host=host.docker.internal:host-gateway",
-    "--security-opt", "apparmor=unconfined" // for alowing ramdisk mounts
-  ],
-
+  "workspaceMount": "source=${localWorkspaceFolder},target=/workspaces/NetAlertX,type=bind,consistency=cached",
+  "onCreateCommand": "mkdir -p /tmp/api /tmp/log",
+  "build": {
+    "dockerfile": "./Dockerfile", // Dockerfile generated by script
+    "context": "../", // Context is the root of the repository
+    "target": "netalertx-devcontainer"
+  },
   "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)
   ],
-  
-  
-  
-  "postStartCommand": "${containerWorkspaceFolder}/.devcontainer/scripts/setup.sh",
-  
+  "runArgs": [
+    "--security-opt",
+    "apparmor=unconfined", // for allowing ramdisk mounts
+    "--add-host=host.docker.internal:host-gateway"
+
+    // Uncomment --network=host to run full NetAlertX scanning capabilities of network scanning in
+    // container. This runs too slowly in a large network to be practical for development purposes.
+    // You can start services such as avahi on the host, in other containers within the network, or
+    // even within this container and connect to them as needed.
+    // "--network=host",
+  ],
+  "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!
+  "forwardPorts": [20211, 20212, 5678],
+  "portsAttributes": { // the ports we care about
+    "20211": {
+      "label": "Frontend:Nginx+PHP"
+    },
+    "20212": {
+      "label": "Backend:GraphQL"
+    },
+    "9003": {
+      "label": "PHP Debug:Xdebug"
+    },
+    "5678": {
+      "label": "Python Debug:debugpy"
+    }
+  },
+
+  "postCreateCommand": {
+      "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": {
+      "Build test-container":"echo To speed up tests, building test container in background... && setsid docker buildx build -t netalertx-test . > /tmp/build.log 2>&1 && echo '🧪 Unit Test Docker image built: netalertx-test' &",
+      "Start Environment":"${containerWorkspaceFolder}/.devcontainer/scripts/setup.sh"
+  },
   "customizations": {
     "vscode": {
       "extensions": [
@@ -31,19 +63,37 @@
         "bmewburn.vscode-intelephense-client",
         "xdebug.php-debug",
         "ms-python.vscode-pylance",
-        "pamaron.pytest-runner",
         "coderabbit.coderabbit-vscode",
-        "ms-python.black-formatter"
-      ]
-      ,
+        "ms-python.black-formatter",
+        "jeff-hykin.better-dockerfile-syntax",
+        "GitHub.codespaces",
+        "ms-azuretools.vscode-containers",
+        "ms-python.vscode-python-envs",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "eamodio.gitlens",
+        "alexcvzz.vscode-sqlite",
+        "mkhl.shfmt",
+        "charliermarsh.ruff",
+        "ms-python.flake8",
+        "exiasr.hadolint",
+        "timonwong.shellcheck"
+      ],
       "settings": {
         "terminal.integrated.cwd": "${containerWorkspaceFolder}",
+        "terminal.integrated.profiles.linux": {
+          "zsh": {
+            "path": "/bin/zsh",
+            "args": ["-l"]
+          }
+        },
+        "terminal.integrated.defaultProfile.linux": "zsh",
+
         // Python testing configuration
         "python.testing.pytestEnabled": true,
         "python.testing.unittestEnabled": false,
-        "python.testing.pytestArgs": [
-          "test"
-        ],
+        "python.testing.pytestArgs": ["test"],
+        "python.testing.cwd": "${containerWorkspaceFolder}",
         // Make sure we discover tests and import server correctly
         "python.analysis.extraPaths": [
           "/workspaces/NetAlertX",
@@ -54,26 +104,6 @@
       }
     }
   },
-  "forwardPorts": [5678, 9000, 9003, 20211, 20212],
 
-  "portsAttributes": {
-    "20211": {
-      "label": "Frontend:Nginx+PHP"
-    },
-    "20212": {
-      "label": "Backend:GraphQL"
-    },
-    "9003": {
-      "label": "PHP Debug:Xdebug"
-    },
-    "9000": {
-      "label": "PHP-FPM:FastCGI"
-    },
-    "5678": {
-      "label": "Python Debug:debugpy"
-    }
-  },
-
-  // Optional: ensures compose services are stopped when you close the window
-  "shutdownAction": "stopContainer"
-}
+  "shutdownAction": "stopContainer" // stop container when VSCode is closed
+}

.devcontainer/resources/99-xdebug.ini

@@ -1,8 +0,0 @@
-zend_extension="xdebug.so"
-[xdebug]
-xdebug.mode=develop,debug
-xdebug.log_level=0
-xdebug.client_host=host.docker.internal
-xdebug.client_port=9003
-xdebug.start_with_request=yes
-xdebug.discover_client_host=1

.devcontainer/resources/devcontainer-Dockerfile

@@ -1,51 +1,59 @@
 # Devcontainer build stage (do not build directly)
 # This file is combined with the root /Dockerfile by
-#   .devcontainer/scripts/generate-dockerfile.sh
+#   .devcontainer/scripts/generate-configs.sh
 # The generator appends this stage to produce .devcontainer/Dockerfile.
 # Prefer to place dev-only setup here; use setup.sh only for runtime fixes.
+# Permissions in devcontainer should be of a brutalist nature. They will be
+# Open and wide to avoid permission issues during development allowing max
+# flexibility.
 
-FROM runner AS devcontainer
-ENV INSTALL_DIR=/app 
-ENV PYTHONPATH=/workspaces/NetAlertX/test:/workspaces/NetAlertX/server:/app:/app/server:/opt/venv/lib/python3.12/site-packages
+# hadolint ignore=DL3006
+FROM runner AS netalertx-devcontainer
+ENV INSTALL_DIR=/app
 
+ENV PYTHONPATH=${PYTHONPATH}:/workspaces/NetAlertX/test:/workspaces/NetAlertX/server:/usr/lib/python3.12/site-packages
+ENV PATH=/services:${PATH}
+ENV PHP_INI_SCAN_DIR=/services/config/php/conf.d:/etc/php83/conf.d
+ENV LISTEN_ADDR=0.0.0.0
+ENV PORT=20211
+ENV NETALERTX_DEBUG=1
+ENV PYDEVD_DISABLE_FILE_VALIDATION=1
+COPY .devcontainer/resources/devcontainer-overlay/ /
+USER root
 # Install common tools, create user, and set up sudo
-RUN apk add --no-cache git nano vim jq php83-pecl-xdebug py3-pip nodejs sudo gpgconf pytest pytest-cov && \
-    adduser -D -s /bin/sh netalertx && \
-    addgroup netalertx nginx && \
-    addgroup netalertx www-data && \
-    echo "netalertx ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/90-netalertx && \
-    chmod 440 /etc/sudoers.d/90-netalertx
-# Install debugpy in the virtualenv if present, otherwise into system python3
-RUN /bin/sh -c '(/opt/venv/bin/python3 -m pip install --no-cache-dir debugpy) || (python3 -m pip install --no-cache-dir debugpy) || true'
-# setup nginx
-COPY .devcontainer/resources/netalertx-devcontainer.conf /etc/nginx/http.d/netalert-frontend.conf
-RUN set -e; \
-    chown netalertx:nginx /etc/nginx/http.d/netalert-frontend.conf; \
-    install -d -o netalertx -g www-data -m 775 /app; \
-    install -d -o netalertx -g www-data -m 755 /run/nginx; \
-    install -d -o netalertx -g www-data -m 755 /var/lib/nginx/logs; \
-    rm -f /var/lib/nginx/logs/* || true; \
-    for f in error access; do : > /var/lib/nginx/logs/$f.log; done; \
-    install -d -o netalertx -g www-data -m 777 /run/php; \
-    install -d -o netalertx -g www-data -m 775 /var/log/php; \
-    chown -R netalertx:www-data /etc/nginx/http.d; \
-    chmod -R 775 /etc/nginx/http.d; \
-    chown -R netalertx:www-data /var/lib/nginx; \
-    chmod -R 755 /var/lib/nginx && \
-    chown -R netalertx:www-data /var/log/nginx/ && \
-    sed -i '/^user /d' /etc/nginx/nginx.conf; \
-    sed -i 's|^error_log .*|error_log /dev/stderr warn;|' /etc/nginx/nginx.conf; \
-    sed -i 's|^access_log .*|access_log /dev/stdout main;|' /etc/nginx/nginx.conf; \
-    sed -i 's|error_log .*|error_log /dev/stderr warn;|g' /etc/nginx/http.d/*.conf 2>/dev/null || true; \
-    sed -i 's|access_log .*|access_log /dev/stdout main;|g' /etc/nginx/http.d/*.conf 2>/dev/null || true; \
-    mkdir -p /run/openrc; \
-    chown netalertx:nginx /run/openrc/; \
-    rm -Rf /run/openrc/*;
 
-# setup pytest
-RUN sudo /opt/venv/bin/python -m pip install -U pytest pytest-cov
+# 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
 
-WORKDIR /workspaces/NetAlertX
+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 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 && \
+    chmod +x /usr/local/bin/hadolint
 
-ENTRYPOINT ["/bin/sh","-c","sleep infinity"]
+RUN install -d -o netalertx -g netalertx -m 755 /services/php/modules && \
+    cp -a /usr/lib/php83/modules/. /services/php/modules/ && \
+    echo "${NETALERTX_USER} ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+ENV SHELL=/bin/zsh
+
+RUN mkdir -p /workspaces && \
+    install -d -m 777 /data /data/config /data/db && \
+    install -d -m 777 /tmp/log /tmp/log/plugins /tmp/api /tmp/run /tmp/nginx && \
+    install -d -m 777 /tmp/nginx/active-config /tmp/nginx/client_body /tmp/nginx/config && \
+    install -d -m 777 /tmp/nginx/fastcgi /tmp/nginx/proxy /tmp/nginx/scgi /tmp/nginx/uwsgi && \
+    install -d -m 777 /tmp/run/tmp /tmp/run/logs && \
+    chmod 777 /workspaces && \
+    chown -R netalertx:netalertx /data && \
+    chmod 666 /data/config/app.conf /data/db/app.db && \
+    chmod 1777 /tmp && \
+    install -d -o root -g root -m 1777 /tmp/.X11-unix && \
+    mkdir -p /home/netalertx && \
+    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/resources/devcontainer-overlay/services/config/php/conf.d/99-xdebug.ini

@@ -0,0 +1,11 @@
+zend_extension="/services/php/modules/xdebug.so"
+extension_dir="/services/php/modules"
+
+[xdebug]
+xdebug.mode=develop,debug
+xdebug.log=/tmp/log/xdebug.log
+xdebug.log_level=7
+xdebug.client_host=127.0.0.1
+xdebug.client_port=9003
+xdebug.start_with_request=yes
+xdebug.discover_client_host=0

.devcontainer/resources/devcontainer-overlay/services/config/python/backend-extra-launch-parameters

@@ -0,0 +1 @@
+-m debugpy --listen 0.0.0.0:5678 

.devcontainer/resources/devcontainer-overlay/workspaces/.zshrc

@@ -0,0 +1,47 @@
+# NetAlertX devcontainer zsh configuration
+# Keep this lightweight and deterministic so shells behave consistently.
+
+export PATH="$HOME/.local/bin:$PATH"
+export EDITOR=vim
+export SHELL=/bin/zsh
+
+# Start inside the workspace if it exists
+if [ -d "/workspaces/NetAlertX" ]; then
+  cd /workspaces/NetAlertX
+fi
+
+# Enable basic completion and prompt helpers
+autoload -Uz compinit promptinit colors
+colors
+compinit -u
+promptinit
+
+# Friendly prompt with virtualenv awareness
+setopt PROMPT_SUBST
+
+_venv_segment() {
+  if [ -n "$VIRTUAL_ENV" ]; then
+    printf '(%s) ' "${VIRTUAL_ENV:t}"
+  fi
+}
+
+PROMPT='%F{green}$(_venv_segment)%f%F{cyan}%n@%m%f %F{yellow}%~%f %# '
+RPROMPT='%F{magenta}$(git rev-parse --abbrev-ref HEAD 2>/dev/null)%f'
+
+# Sensible defaults
+setopt autocd
+setopt correct
+setopt extendedglob
+HISTFILE="$HOME/.zsh_history"
+HISTSIZE=5000
+SAVEHIST=5000
+
+alias ll='ls -alF'
+alias la='ls -A'
+alias gs='git status -sb'
+alias gp='git pull --ff-only'
+
+# Ensure pyenv/virtualenv activate hooks adjust the prompt cleanly
+if [ -f "$HOME/.zshrc.local" ]; then
+  source "$HOME/.zshrc.local"
+fi

.devcontainer/resources/netalertx-devcontainer.conf

@@ -1,26 +0,0 @@
-log_format netalertx '$remote_addr - $remote_user [$time_local] "$request" '
-                     '$status $body_bytes_sent "$http_referer" '
-                     '"$http_user_agent" "$http_x_forwarded_for"';
-access_log /var/log/nginx/access.log netalertx flush=1s;
-error_log  /var/log/nginx/error.log  warn;
-
-server {
-    listen 20211 default_server;
-    root /app/front;
-    index index.php;
-
-    add_header X-Forwarded-Prefix "/netalertx" always;
-    proxy_set_header X-Forwarded-Prefix "/netalertx";
-
-    location ~* \.php$ {
-        add_header Cache-Control "no-store";
-        fastcgi_pass 127.0.0.1:9000;
-        include         fastcgi_params;
-        fastcgi_param   SCRIPT_FILENAME    $document_root$fastcgi_script_name;
-        fastcgi_param   SCRIPT_NAME        $fastcgi_script_name;
-        fastcgi_param   PHP_VALUE "xdebug.remote_enable=1";
-        fastcgi_connect_timeout 75;
-        fastcgi_send_timeout 600;
-        fastcgi_read_timeout 600;
-    }
-}

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

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

.devcontainer/scripts/confirm-docker-prune.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+set -euo pipefail
+
+if [[ -n "${CONFIRM_PRUNE:-}" && "${CONFIRM_PRUNE}" == "YES" ]]; then
+  reply="YES"
+else
+  read -r -p "Are you sure you want to destroy your host docker containers and images? Type YES to continue: " reply
+fi
+
+if [[ "${reply}" == "YES" ]]; then
+  docker system prune -af
+  docker builder prune -af
+else
+  echo "Aborted."
+  exit 1
+fi
+
+echo "Done."

.devcontainer/scripts/generate-configs.sh

@@ -0,0 +1,47 @@
+#!/bin/sh
+
+# Generator for .devcontainer/Dockerfile
+# Combines the root /Dockerfile (with some COPY lines removed) and
+# the dev-only stage in .devcontainer/resources/devcontainer-Dockerfile.
+# Run this script after modifying the resource Dockerfile to refresh
+# the final .devcontainer/Dockerfile used by the devcontainer.
+
+echo "Generating .devcontainer/Dockerfile"
+SCRIPT_PATH=$(set -- "$0"; dirname -- "$1")
+SCRIPT_DIR=$(cd "$SCRIPT_PATH" && pwd -P)
+DEVCONTAINER_DIR="${SCRIPT_DIR%/scripts}"
+ROOT_DIR="${DEVCONTAINER_DIR%/.devcontainer}"
+
+OUT_FILE="${DEVCONTAINER_DIR}/Dockerfile"
+
+echo "Adding base Dockerfile from $ROOT_DIR and merging to devcontainer-Dockerfile" 
+{
+
+echo "# DO NOT MODIFY THIS FILE DIRECTLY. IT IS AUTO-GENERATED BY .devcontainer/scripts/generate-configs.sh"
+echo ""
+echo "# ---/Dockerfile---" 
+
+cat "${ROOT_DIR}/Dockerfile" 
+
+echo ""
+echo "# ---/resources/devcontainer-Dockerfile---"
+echo ""
+cat "${DEVCONTAINER_DIR}/resources/devcontainer-Dockerfile"
+} > "$OUT_FILE"
+
+echo "Generated $OUT_FILE using root dir $ROOT_DIR"
+
+# Passive Gemini MCP config
+TOKEN=$(grep '^API_TOKEN=' /data/config/app.conf 2>/dev/null | cut -d"'" -f2)
+if [ -n "${TOKEN}" ]; then
+    mkdir -p "${ROOT_DIR}/.gemini"
+    [ -f "${ROOT_DIR}/.gemini/settings.json" ] || echo "{}" > "${ROOT_DIR}/.gemini/settings.json"
+    jq --arg t "$TOKEN" '.mcpServers["netalertx-devcontainer"] = {url: "http://127.0.0.1:20212/mcp/sse", headers: {Authorization: ("Bearer " + $t)}}' "${ROOT_DIR}/.gemini/settings.json" > "${ROOT_DIR}/.gemini/settings.json.tmp" && mv "${ROOT_DIR}/.gemini/settings.json.tmp" "${ROOT_DIR}/.gemini/settings.json"
+
+    # VS Code MCP config
+    mkdir -p "${ROOT_DIR}/.vscode"
+    [ -f "${ROOT_DIR}/.vscode/mcp.json" ] || echo "{}" > "${ROOT_DIR}/.vscode/mcp.json"
+    jq --arg t "$TOKEN" '.servers["netalertx-devcontainer"] = {type: "sse", url: "http://127.0.0.1:20212/mcp/sse", headers: {Authorization: ("Bearer " + $t)}}' "${ROOT_DIR}/.vscode/mcp.json" > "${ROOT_DIR}/.vscode/mcp.json.tmp" && mv "${ROOT_DIR}/.vscode/mcp.json.tmp" "${ROOT_DIR}/.vscode/mcp.json"
+fi
+
+echo "Done."

.devcontainer/scripts/generate-dockerfile.sh

@@ -1,38 +0,0 @@
-#!/bin/sh
-
-# Generator for .devcontainer/Dockerfile
-# Combines the root /Dockerfile (with some COPY lines removed) and
-# the dev-only stage in .devcontainer/resources/devcontainer-Dockerfile.
-# Run this script after modifying the resource Dockerfile to refresh
-# the final .devcontainer/Dockerfile used by the devcontainer.
-
-# Make a copy of the original Dockerfile to the .devcontainer folder
-# but remove the COPY . ${INSTALL_DIR}/ command from it. This avoids
-# overwriting /app (which uses symlinks to the workspace) and preserves
-# debugging capabilities inside the devcontainer.
-
-SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
-DEVCONTAINER_DIR="${SCRIPT_DIR%/scripts}"
-ROOT_DIR="${DEVCONTAINER_DIR%/.devcontainer}"
-
-OUT_FILE="${DEVCONTAINER_DIR}/Dockerfile"
-
-echo "# DO NOT MODIFY THIS FILE DIRECTLY. IT IS AUTO-GENERATED BY .devcontainer/scripts/generate-dockerfile.sh" > "$OUT_FILE"
-echo "" >> "$OUT_FILE"
-echo "# ---/Dockerfile---" >> "$OUT_FILE"
-
-sed '/${INSTALL_DIR}/d' "${ROOT_DIR}/Dockerfile" >> "$OUT_FILE"
-
-# sed the line https://github.com/foreign-sub/aiofreepybox.git \\ to remove trailing backslash
-sed -i '/aiofreepybox.git/ s/ \\$//' "$OUT_FILE"
-
-# don't cat the file, just copy it in because it doesn't exist at build time
-sed -i 's|^ RUN cat ${INSTALL_DIR}/install/freebox_certificate.pem >> /opt/venv/lib/python3.12/site-packages/aiofreepybox/freebox_certificates.pem$| COPY install/freebox_certificate.pem /opt/venv/lib/python3.12/site-packages/aiofreepybox/freebox_certificates.pem |' "$OUT_FILE"
-
-echo "" >> "$OUT_FILE"
-echo "# ---/resources/devcontainer-Dockerfile---" >> "$OUT_FILE"
-echo "" >> "$OUT_FILE"
-
-cat "${DEVCONTAINER_DIR}/resources/devcontainer-Dockerfile" >> "$OUT_FILE"
-
-echo "Generated $OUT_FILE using root dir $ROOT_DIR" >&2

.devcontainer/scripts/isDevContainer.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+if [ ! -d /workspaces/NetAlertX/.devcontainer ]; then 
+    echo ---------------------------------------------------
+    echo "This script may only be run inside a devcontainer."
+    echo "Not in a devcontainer, exiting..."
+    echo ---------------------------------------------------
+    exit 255
+fi

.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/restart-backend.sh

@@ -1,26 +0,0 @@
-#!/bin/sh
-# Start (or restart) the NetAlertX Python backend under debugpy in background.
-# This script is invoked by the VS Code task "Restart GraphQL".
-# It exists to avoid complex inline command chains that were being mangled by the task runner.
-
-set -e
-
-LOG_DIR=/app/log
-APP_DIR=/app/server
-PY=python3
-PORT_DEBUG=5678
-
-# Kill any prior debug/run instances
-sudo killall python3 2>/dev/null || true
-sleep 2
-
-echo ''|tee $LOG_DIR/stdout.log $LOG_DIR/stderr.log $LOG_DIR/app.log
-
-cd "$APP_DIR"
-
-# Launch using absolute module path for clarity; rely on cwd for local imports
-setsid nohup "${PY}" -m debugpy --listen "0.0.0.0:${PORT_DEBUG}" /app/server/__main__.py \
-  1>>"$LOG_DIR/stdout.log" \
-  2>>"$LOG_DIR/stderr.log" &
-PID=$!
-sleep 2

.devcontainer/scripts/run-tests.sh

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

.devcontainer/scripts/setup.sh

@@ -1,200 +1,105 @@
-#! /bin/bash
-# Runtime setup for devcontainer (executed after container starts).
-# Prefer building setup into resources/devcontainer-Dockerfile when possible.
-# Use this script for runtime-only adjustments (permissions, sockets, ownership,
-# and services managed without init) that are difficult at build time.
-id
-
-# Define variables (paths, ports, environment)
-
-export APP_DIR="/app"
-export APP_COMMAND="/workspaces/NetAlertX/.devcontainer/scripts/restart-backend.sh"
-export PHP_FPM_BIN="/usr/sbin/php-fpm83"
-export NGINX_BIN="/usr/sbin/nginx"
-export CROND_BIN="/usr/sbin/crond -f"
-
-
-export ALWAYS_FRESH_INSTALL=false
-export INSTALL_DIR=/app
-export APP_DATA_LOCATION=/app/config
-export APP_CONFIG_LOCATION=/app/config
-export LOGS_LOCATION=/app/logs
-export CONF_FILE="app.conf"
-export NGINX_CONF_FILE=netalertx.conf
-export DB_FILE="app.db"
-export FULL_FILEDB_PATH="${INSTALL_DIR}/db/${DB_FILE}"
-export NGINX_CONFIG_FILE="/etc/nginx/http.d/${NGINX_CONF_FILE}"
-export OUI_FILE="/usr/share/arp-scan/ieee-oui.txt" # Define the path to ieee-oui.txt and ieee-iab.txt
-export TZ=Europe/Paris
-export PORT=20211
-export SOURCE_DIR="/workspaces/NetAlertX"
-
-
- 
-main() {
-    echo "=== NetAlertX Development Container Setup ==="
-    echo "Setting up ${SOURCE_DIR}..."
-    configure_source
-    
-    echo "--- Starting Development Services ---"
-    configure_php
-
-
-    start_services
-}
-
-# safe_link: create a symlink from source to target, removing existing target if necessary
-# bypassing the default behavior of symlinking the directory into the target directory if it is a directory
-safe_link() {
-    # usage: safe_link <source> <target>
-    local src="$1"
-    local dst="$2"
-
-    # Ensure parent directory exists
-    install -d -m 775 "$(dirname "$dst")" >/dev/null 2>&1 || true
-
-    # If target exists, remove it without dereferencing symlinks
-    if [ -L "$dst" ] || [ -e "$dst" ]; then
-        rm -rf "$dst"
-    fi
-
-    # Create link; -n prevents deref, -f replaces if somehow still exists
-    ln -sfn "$src" "$dst"
-}
-
-# Setup source directory
-configure_source() {
-    echo "[1/3] Configuring Source..."
-    echo "  -> Linking source to ${INSTALL_DIR}"
-    echo "Dev">${INSTALL_DIR}/.VERSION
-
-    echo "  -> Mounting ramdisks for /log and /api"
-    sudo mount -t tmpfs -o size=256M tmpfs "${SOURCE_DIR}/log"
-    sudo mount -t tmpfs -o size=512M tmpfs "${SOURCE_DIR}/api"
-    safe_link ${SOURCE_DIR}/api           ${INSTALL_DIR}/api
-    safe_link ${SOURCE_DIR}/back          ${INSTALL_DIR}/back
-    safe_link "${SOURCE_DIR}/config"     "${INSTALL_DIR}/config"
-    safe_link "${SOURCE_DIR}/db"         "${INSTALL_DIR}/db"
-    if [ ! -f "${SOURCE_DIR}/config/app.conf" ]; then
-        cp ${SOURCE_DIR}/back/app.conf ${INSTALL_DIR}/config/
-        cp ${SOURCE_DIR}/back/app.db ${INSTALL_DIR}/db/
-    fi
-
-    safe_link "${SOURCE_DIR}/docs"       "${INSTALL_DIR}/docs"
-    safe_link "${SOURCE_DIR}/front"      "${INSTALL_DIR}/front"
-    safe_link "${SOURCE_DIR}/install"    "${INSTALL_DIR}/install"
-    safe_link "${SOURCE_DIR}/scripts"    "${INSTALL_DIR}/scripts"
-    safe_link "${SOURCE_DIR}/server"     "${INSTALL_DIR}/server"
-    safe_link "${SOURCE_DIR}/test"       "${INSTALL_DIR}/test"
-    safe_link "${SOURCE_DIR}/log"       "${INSTALL_DIR}/log"
-    safe_link "${SOURCE_DIR}/mkdocs.yml" "${INSTALL_DIR}/mkdocs.yml"
-
-    echo "  -> Copying static files to ${INSTALL_DIR}"
-    cp -R ${SOURCE_DIR}/CODE_OF_CONDUCT.md ${INSTALL_DIR}/
-    cp -R ${SOURCE_DIR}/dockerfiles ${INSTALL_DIR}/dockerfiles
-    sudo cp -na "${INSTALL_DIR}/back/${CONF_FILE}" "${INSTALL_DIR}/config/${CONF_FILE}"
-    sudo cp -na "${INSTALL_DIR}/back/${DB_FILE}" "${FULL_FILEDB_PATH}"
-    if [ -e "${INSTALL_DIR}/api/user_notifications.json" ]; then
-        echo "  -> Removing existing user_notifications.json"
-        sudo rm "${INSTALL_DIR}"/api/user_notifications.json
-    fi
-
-
-    
-    echo "  -> Setting ownership and permissions"
-    sudo find ${INSTALL_DIR}/ -type d -exec chmod 775 {} \;
-    sudo find ${INSTALL_DIR}/ -type f -exec chmod 664 {} \;
-    sudo date +%s > "${INSTALL_DIR}/front/buildtimestamp.txt"
-    sudo chmod 640 "${INSTALL_DIR}/config/${CONF_FILE}" || true
-
-
-
-    echo "  -> Setting up log directory"
-    install -d -o netalertx -g www-data -m 777 ${INSTALL_DIR}/log/plugins
-
-    echo "  -> Empty log"|tee ${INSTALL_DIR}/log/app.log \
-        ${INSTALL_DIR}/log/app_front.log \
-        ${INSTALL_DIR}/log/stdout.log
-    touch ${INSTALL_DIR}/log/stderr.log \
-    ${INSTALL_DIR}/log/execution_queue.log
-    echo 0>${INSTALL_DIR}/log/db_is_locked.log
-
-    date +%s > /app/front/buildtimestamp.txt
-
-    killall python &>/dev/null
-    sleep 1
-}
-
+#!/bin/bash
+# NetAlertX Devcontainer Setup Script
 #
+# This script forcefully resets all runtime state for a single-user devcontainer.
+# It is intentionally idempotent: every run wipes and recreates all relevant folders,
+# symlinks, and files, so the environment is always fresh and predictable.
+#
+# - No conditional logic: everything is (re)created, overwritten, or reset unconditionally.
+# - No security hardening: this is for disposable, local dev use only.
+# - No checks for existing files, mounts, or processes—just do the work.
+#
+# If you add new runtime files or folders, add them to the creation/reset section below.
+#
+# Do not add if-then logic or error handling for missing/existing files. Simplicity is the goal.
 
-# start_services: start crond, PHP-FPM, nginx and the application
-start_services() {
-    echo "[3/3] Starting services..."
 
-    killall nohup &>/dev/null || true
+SOURCE_DIR=${SOURCE_DIR:-/workspaces/NetAlertX}
+PY_SITE_PACKAGES="${VIRTUAL_ENV:-/opt/venv}/lib/python3.12/site-packages"
 
-    killall php-fpm83 &>/dev/null || true
-    killall crond &>/dev/null || true
-    # Give the OS a moment to release the php-fpm socket
-    sleep 0.3
-    echo "      -> Starting CronD"
-    setsid nohup $CROND_BIN &>/dev/null &
+LOG_FILES=(
+  LOG_APP
+  LOG_APP_FRONT
+  LOG_STDOUT
+  LOG_STDERR
+  LOG_EXECUTION_QUEUE
+  LOG_APP_PHP_ERRORS
+  LOG_IP_CHANGES
+  LOG_CRON
+  LOG_REPORT_OUTPUT_TXT
+  LOG_REPORT_OUTPUT_HTML
+  LOG_REPORT_OUTPUT_JSON
+  LOG_DB_IS_LOCKED
+  LOG_NGINX_ERROR
+)
+sudo chmod 666 /var/run/docker.sock 2>/dev/null || true
+sudo chown "$(id -u)":"$(id -g)" /workspaces
+sudo chmod 755 /workspaces
 
-    echo "      -> Starting PHP-FPM"
-    setsid nohup $PHP_FPM_BIN &>/dev/null &
+killall php-fpm83 nginx crond python3 2>/dev/null || true
 
-    sudo killall nginx &>/dev/null || true
-    # Wait for the previous nginx processes to exit and for the port to free up
-    tries=0
-    while ss -ltn | grep -q ":${PORT}[[:space:]]" && [ $tries -lt 10 ]; do
-        echo "  -> Waiting for port ${PORT} to free..."
-        sleep 0.2
-        tries=$((tries+1))
-    done
-    sleep 0.2
-    echo "      -> Starting Nginx"
-    setsid nohup $NGINX_BIN &>/dev/null &
-    echo "      -> Starting Backend ${APP_DIR}/server..."
-    $APP_COMMAND 
-    sleep 2
-}
+# Mount ramdisks for volatile data
+sudo mount -t tmpfs -o size=100m,mode=0777 tmpfs /tmp/log 2>/dev/null || true
+sudo mount -t tmpfs -o size=50m,mode=0777 tmpfs /tmp/api 2>/dev/null || true
+sudo mount -t tmpfs -o size=50m,mode=0777 tmpfs /tmp/run 2>/dev/null || true
+sudo mount -t tmpfs -o size=50m,mode=0777 tmpfs /tmp/nginx 2>/dev/null || true
 
-# configure_php: configure PHP-FPM and enable dev debug options
-configure_php() {
-    echo "[2/3] Configuring PHP-FPM..."
-    sudo killall php-fpm83 &>/dev/null || true
-    install -d -o nginx -g www-data /run/php/ &>/dev/null
-    sudo sed -i "/^;pid/c\pid = /run/php/php8.3-fpm.pid" /etc/php83/php-fpm.conf
-    sudo sed -i 's|^listen = .*|listen = 127.0.0.1:9000|' /etc/php83/php-fpm.d/www.conf
-    sudo sed -i 's|fastcgi_pass .*|fastcgi_pass 127.0.0.1:9000;|' /etc/nginx/http.d/*.conf
+sudo chmod 777 /tmp/log /tmp/api /tmp/run /tmp/nginx
 
-    #increase max child process count to 10
-    sudo sed -i -e 's/pm.max_children = 5/pm.max_children = 10/' /etc/php83/php-fpm.d/www.conf 
+# Create critical subdirectories immediately after tmpfs mount
+sudo install -d -m 777 /tmp/run/tmp
+sudo install -d -m 777 /tmp/log/plugins
 
-    # find any line in php-fmp that starts with either ;error_log or error_log = and replace it with error_log = /app/log/app.php_errors.log
-    sudo sed -i '/^;*error_log\s*=/c\error_log = /app/log/app.php_errors.log' /etc/php83/php-fpm.conf
-    # If the line was not found, append it to the end of the file
-    if ! grep -q '^error_log\s*=' /etc/php83/php-fpm.conf; then
-        echo 'error_log = /app/log/app.php_errors.log' | sudo tee -a /etc/php83/php-fpm.conf
-    fi
 
-    sudo mkdir -p /etc/php83/conf.d
-    sudo cp /workspaces/NetAlertX/.devcontainer/resources/99-xdebug.ini /etc/php83/conf.d/99-xdebug.ini
+sudo rm -rf /entrypoint.d
+sudo ln -s "${SOURCE_DIR}/install/production-filesystem/entrypoint.d" /entrypoint.d
 
-    sudo rm -R /var/log/php83 &>/dev/null || true
-    install -d -o netalertx -g www-data -m 755 var/log/php83;
+sudo rm -rf /services
+sudo ln -s "${SOURCE_DIR}/install/production-filesystem/services" /services
 
-    sudo chmod 644 /etc/php83/conf.d/99-xdebug.ini || true
+sudo rm -rf "${NETALERTX_APP}"
+sudo ln -s "${SOURCE_DIR}/" "${NETALERTX_APP}"
 
-}
+for dir in "${NETALERTX_DATA}" "${NETALERTX_CONFIG}" "${NETALERTX_DB}"; do
+  sudo install -d -m 777 "${dir}"
+done
 
-# (duplicate start_services removed)
-
-
-
-echo "$(git rev-parse --short=8 HEAD)">/app/.VERSION
-# Run the main function
-main
+for dir in \
+  "${SYSTEM_SERVICES_RUN_LOG}" \
+  "${SYSTEM_SERVICES_ACTIVE_CONFIG}" \
+  "${NETALERTX_PLUGINS_LOG}" \
+  "${SYSTEM_SERVICES_RUN_TMP}" \
+  "/tmp/nginx/client_body" \
+  "/tmp/nginx/proxy" \
+  "/tmp/nginx/fastcgi" \
+  "/tmp/nginx/uwsgi" \
+  "/tmp/nginx/scgi"; do
+  sudo install -d -m 777 "${dir}"
+done
+
+
+for var in "${LOG_FILES[@]}"; do
+  path=${!var}
+  dir=$(dirname "${path}")
+  sudo install -d -m 777 "${dir}"
+  touch "${path}"
+done
+
+printf '0\n' | sudo tee "${LOG_DB_IS_LOCKED}" >/dev/null
+sudo chmod 777 "${LOG_DB_IS_LOCKED}"
+
+sudo pkill -f python3 2>/dev/null || true
+
+sudo chown -R "${NETALERTX_USER}:${NETALERTX_GROUP}" "${NETALERTX_APP}"
+date +%s | sudo tee "${NETALERTX_FRONT}/buildtimestamp.txt" >/dev/null
+
+sudo chmod 755 "${NETALERTX_APP}"
+
+sudo chmod +x /entrypoint.sh
+setsid bash /entrypoint.sh &
+sleep 1
+
+echo "Development $(git rev-parse --short=8 HEAD)" | sudo tee "${NETALERTX_APP}/.VERSION" >/dev/null
 
 
 

.devcontainer/scripts/stream-logs.sh

@@ -1,40 +0,0 @@
-#!/bin/sh
-# Stream NetAlertX logs to stdout so the Dev Containers output channel shows them.
-# This script waits briefly for the files to appear and then tails them with -F.
-
-LOG_FILES="/app/log/app.log  /app/log/db_is_locked.log /app/log/execution_queue.log /app/log/app_front.log /app/log/app.php_errors.log /app/log/IP_changes.log /app/stderr.log /app/stdout.log"
-
-wait_for_files() {
-  # Wait up to ~10s for at least one of the files to exist
-  attempts=0
-  while [ $attempts -lt 20 ]; do
-    for f in $LOG_FILES; do
-      if [ -f "$f" ]; then
-        return 0
-      fi
-    done
-    attempts=$((attempts+1))
-    sleep 0.5
-  done
-  return 1
-}
-
-if wait_for_files; then
-  echo "Starting log stream for:"
-  for f in $LOG_FILES; do
-    [ -f "$f" ] && echo "  $f"
-  done
-
-  # Use tail -F where available. If tail -F isn't supported, tail -f is used as fallback.
-  # Some minimal images may have busybox tail without -F; this handles both.
-  if tail --version >/dev/null 2>&1; then
-    # GNU tail supports -F
-    tail -n +1 -F $LOG_FILES
-  else
-    # Fallback to -f for busybox; will exit if files rotate or do not exist initially
-    tail -n +1 -f $LOG_FILES
-  fi
-else
-  echo "No log files appeared after wait; exiting stream script."
-  exit 0
-fi

.devcontainer/xdebug-trigger.ini

@@ -1,11 +0,0 @@
-zend_extension=xdebug.so
-xdebug.mode=debug
-xdebug.start_with_request=trigger
-xdebug.trigger_value=VSCODE
-xdebug.client_host=host.docker.internal
-xdebug.client_port=9003
-xdebug.log=/var/log/xdebug.log
-xdebug.log_level=7
-xdebug.idekey=VSCODE
-xdebug.discover_client_host=true
-xdebug.max_nesting_level=512

.dockerignore

@@ -1,8 +1,8 @@
 .dockerignore
+**/.dockerignore
 .env
 .git
 .github
-.gitignore
 docker-compose.yml
 Dockerfile
 Dockerfile.debian

.flake8

@@ -0,0 +1,3 @@
+[flake8]
+max-line-length = 180
+ignore = E221,E222,E251,E203

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

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

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

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

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

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

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

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

.github/FUNDING.yml

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

.github/ISSUE_TEMPLATE/config.yml

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

.github/ISSUE_TEMPLATE/documentation-feedback.yml

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

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

@@ -1,18 +1,36 @@
-name: Bug Report
+name: 🐛 Bug Report
 description: 'When submitting an issue enable LOG_LEVEL="trace" and have a look at the docs.'
 labels: ['bug 🐛']
 body:
+- type: markdown
+  attributes:
+    value: |
+      <!-- NETALERTX_TEMPLATE -->
+- type: dropdown
+  id: installation_type
+  attributes:
+    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 +62,9 @@ body:
     required: false
 - type: textarea
   attributes:
-    label: app.conf
+    label: Relevant `app.conf` settings
     description: |
-      Paste your `app.conf` (remove personal info)    
+      Paste relevant `app.conf`settings (remove sensitive info)
     render: python
   validations:
     required: false
@@ -54,37 +72,41 @@ body:
   attributes:
     label: docker-compose.yml
     description: |
-      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) ⚠
-      ***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. 
+      Paste your `docker-compose.yml`
+    render: yaml
   validations:
     required: false
 - type: checkboxes
   attributes:
-    label: Debug enabled
-    description: I confirm I enabled `debug`
+    label: Debug or Trace enabled
+    description: I confirm I set `LOG_LEVEL` to `debug` or `trace`
     options:
     - label: I have read and followed the steps in the wiki link above and provided the required debug logs and the log section covers the time when the issue occurs.
       required: true
+- type: textarea
+  attributes:
+    label: Relevant `app.log` section
+    value: |
+        ```
+          PASTE LOG HERE. Using the triple backticks preserves format.
+        ```
+    description: |
+      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 or send them to netalertx@gmail.com with the issue number.
+  validations:
+    required: false
+- type: textarea
+  attributes:
+    label: Docker Logs
+    description: |
+     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.
+        ```
+  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/security-report.yml

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

.github/ISSUE_TEMPLATE/setup-help.yml

@@ -1,22 +1,40 @@
-name: Setup help
+name: 📥 Setup help
 description: 'When submitting an issue enable LOG_LEVEL="trace" and re-search first.'
 labels: ['Setup 📥']
 body:
+- type: markdown
+  attributes:
+    value: |
+      <!-- NETALERTX_TEMPLATE -->
+- type: dropdown
+  id: installation_type
+  attributes:
+    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 +50,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,62 +1,49 @@
-This is NetAlertX — network monitoring & alerting.
+### ROLE: NETALERTX ARCHITECT & STRICT CODE AUDITOR
+You are a cynical Security Engineer and Core Maintainer of NetAlertX. Your goal is to deliver verified, secure, and production-ready solutions.
 
-Purpose: Guide AI assistants to follow NetAlertX architecture, conventions, and safety practices. Be concise, opinionated, and prefer existing helpers/settings over new code or hardcoded values.
+### MANDATORY BEHAVIORAL OVERRIDES
+1. **Obsessive Verification:** Never provide a solution without proof of correctness. Write test cases or validation immediately after writing functions.
+2. **Anti-Laziness Protocol:** No placeholders. Output full, functional blocks every time.
+3. **Priority Hierarchy:** Correctness > Completeness > Speed.
+4. **Mantra:** "Job's not done 'till unit tests run."
 
-## Architecture (what runs where)
-- Backend (Python): main loop + GraphQL/REST endpoints orchestrate scans, plugins, workflows, notifications, and JSON export.
-	- Key: `server/__main__.py`, `server/plugin.py`, `server/initialise.py`, `server/api_server/api_server_start.py`
-- Data (SQLite): persistent state in `db/app.db`; helpers in `server/database.py` and `server/db/*`.
-- Frontend (Nginx + PHP + JS): UI reads JSON, triggers execution queue events.
-	- Key: `front/`, `front/js/common.js`, `front/php/server/*.php`
-- Plugins (Python): acquisition/enrichment/publishers under `front/plugins/*` with `config.json` manifests.
-- Messaging/Workflows: `server/messaging/*`, `server/workflows/*`
-- API JSON Cache for UI: generated under `api/*.json`
+---
 
-Backend loop phases (see `server/__main__.py` and `server/plugin.py`): `once`, `schedule`, `always_after_scan`, `before_name_updates`, `on_new_device`, `on_notification`, plus ad‑hoc `run` via execution queue. Plugins execute as scripts that write result logs for ingestion.
+# NetAlertX
 
-## Plugin patterns that matter
-- Manifest lives at `front/plugins/<code_name>/config.json`; `code_name` == folder, `unique_prefix` drives settings and filenames (e.g., `ARPSCAN`).
-- Control via settings: `<PREF>_RUN` (phase), `<PREF>_RUN_SCHD` (cron-like), `<PREF>_CMD` (script path), `<PREF>_RUN_TIMEOUT`, `<PREF>_WATCH` (diff columns).
-- Data contract: scripts write `/app/log/plugins/last_result.<PREF>.log` (pipe‑delimited: 9 required cols + optional 4). Use `front/plugins/plugin_helper.py`’s `Plugin_Objects` to sanitize text and normalize MACs, then `write_result_file()`.
-- Device import: define `database_column_definitions` when creating/updating devices; watched fields trigger notifications.
+Network monitoring & alerting. Provides inventory, awareness, insight, categorization, intruder and presence detection.
 
-### Standard Plugin Formats
-* publisher: Sends notifications to services. Runs `on_notification`. Data source: self.
-* dev scanner: Creates devices and manages online/offline status. Runs on `schedule`. Data source: self / SQLite DB.
-* name discovery: Discovers device names via various protocols. Runs `before_name_updates` or on `schedule`. Data source: self.
-* importer: Imports devices from another service. Runs on `schedule`. Data source: self / SQLite DB.
-* system: Provides core system functionality. Runs on `schedule` or is always on. Data source: self / Template.
-* other: Miscellaneous plugins. Runs at various times. Data source: self / Template.
+## Architecture
 
-### Plugin logging & outputs
-- Always log via `mylog()` like other plugins do (no `print()`). Example: `mylog('verbose', [f'[{pluginName}] In script'])`.
-- 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 `verbose` level unless debugging.
+- **Backend (Python):** `server/__main__.py`, `server/plugin.py`, `server/api_server/api_server_start.py`
+- **Backend Config:** `/data/config/app.conf`
+- **Data (SQLite):** `/data/db/app.db`; helpers in `server/db/*`
+- **Frontend (Nginx + PHP + JS):** `front/`
+- **Plugins (Python):** `front/plugins/*` with `config.json` manifests
 
-- 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')`.
+## Skills
 
-## 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` (`timeNowTZ`, `normalize_mac`, 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.
+Procedural knowledge lives in `.github/skills/`. Load the appropriate skill when performing these tasks:
 
-## Dev workflow (devcontainer)
-- Services: use tasks to (re)start backend and nginx/PHP-FPM. Backend runs with debugpy on 5678; attach a Python debugger if needed.
-- Run a plugin manually: `python3 front/plugins/<code_name>/script.py` (ensure `sys.path` includes `/app/front/plugins` and `/app/server` like the template).
-- Testing: pytest available via Alpine packages. Tests live in `test/`; app code is under `server/`. PYTHONPATH is preconfigured to include workspace and `/opt/venv` site‑packages.
+| Task | Skill |
+|------|-------|
+| Run tests, check failures | `testing-workflow` |
+| Start/stop/restart services | `devcontainer-services` |
+| Wipe database, fresh start | `database-reset` |
+| Load sample devices | `sample-data` |
+| Build Docker images | `docker-build` |
+| Reprovision devcontainer | `devcontainer-setup` |
+| Create or run plugins | `plugin-run-development` |
+| Analyze PR comments | `pr-analysis` |
+| Clean Docker resources | `docker-prune` |
+| Generate devcontainer configs | `devcontainer-configs` |
+| Create API endpoints | `api-development` |
+| Logging conventions | `logging-standards` |
+| Settings and config | `settings-management` |
+| Find files and paths | `project-navigation` |
+| Coding standards | `code-standards` |
 
-## 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 `/app/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.
+## Execution Protocol
 
-## Useful references
-- Docs: `docs/PLUGINS_DEV.md`, `docs/SETTINGS_SYSTEM.md`, `docs/API_*.md`, `docs/DEBUG_*.md`
-- Logs: backend `/app/log/app.log`, plugin logs under `/app/log/plugins/`, nginx/php logs under `/var/log/*`
-
-Assistant expectations
-- Reference concrete files/paths. Use existing helpers/settings. Keep changes idempotent and safe. Offer a quick validation step (log line, API hit, or JSON export) for anything you add.
+- **Before running tests:** Always use `testFailure` tool first to gather current failures.
+- **Docker tests are slow.** Examine existing failures before changing tests or Dockerfiles.

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

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

.github/skills/authentication/SKILL.md

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

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

@@ -0,0 +1,65 @@
+---
+name: netalertx-code-standards
+description: NetAlertX coding standards and conventions. Use this when writing code, reviewing code, or implementing features.
+---
+
+# Code Standards
+
+## File Length
+
+Keep code files under 500 lines. Split larger files into modules.
+
+## DRY Principle
+
+Do not re-implement functionality. Reuse existing methods or refactor to create shared methods.
+
+## Database Access
+
+- Never access DB directly from application layers
+- Use `server/db/db_helper.py` functions (e.g., `get_table_json`)
+- Implement new functionality in handlers (e.g., `DeviceInstance` in `server/models/device_instance.py`)
+
+## MAC Address Handling
+
+Always validate and normalize MACs before DB writes:
+
+```python
+from plugin_helper import normalize_mac
+
+mac = normalize_mac(raw_mac)
+```
+
+## Subprocess Safety
+
+**MANDATORY:** All subprocess calls must set explicit timeouts.
+
+```python
+result = subprocess.run(cmd, timeout=60)  # Minimum 60s
+```
+
+Nested subprocess calls need their own timeout—outer timeout won't save you.
+
+## Time Utilities
+
+```python
+from utils.datetime_utils import timeNowDB
+
+timestamp = timeNowDB()
+```
+
+## String Sanitization
+
+Use sanitizers from `server/helper.py` before storing user input.
+
+## Devcontainer Constraints
+
+- Never `chmod` or `chown` during operations
+- Everything is already writable
+- If permissions needed, fix `.devcontainer/scripts/setup.sh`
+
+## Path Hygiene
+
+- Use environment variables for runtime paths
+- `/data` for persistent config/db
+- `/tmp` for runtime logs/api/nginx state
+- Never hardcode `/data/db` or use relative paths

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

.github/workflows/code-checks.yml

@@ -0,0 +1,116 @@
+name: ✅ Code checks
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - '*.*.*'
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  check-url-paths:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: 🚨 Ensure DELETE FROM CurrentScan is not commented out
+        run: |
+          echo "🔍 Checking that DELETE FROM CurrentScan is not commented out..."
+
+          MATCHES=$(grep -RInE '^[[:space:]]*#[[:space:]]*db\.sql\.execute\("DELETE FROM CurrentScan"\)' \
+            --include="*.py" .) || true
+
+          if [ -n "$MATCHES" ]; then
+            echo "❌ Found commented-out DELETE FROM CurrentScan call:"
+            echo "$MATCHES"
+            echo
+            echo "This line must NOT be commented out in committed code."
+            exit 1
+          else
+            echo "✅ DELETE FROM CurrentScan is active."
+          fi
+
+      - name: Check for incorrect absolute '/php/' URLs in frontend code
+        run: |
+          echo "🔍 Checking for incorrect absolute '/php/' URLs (should be 'php/' or './php/')..."
+
+          MATCHES=$(grep -rE "['\"]/php/" --include=\*.{js,php,html} ./front \
+            | grep -E "\.get|\.post|\.ajax|fetch|url\s*:") || true
+
+          if [ -n "$MATCHES" ]; then
+            echo "$MATCHES"
+            echo "❌ Found incorrectly absolute '/php/' URLs. Use 'php/' or './php/' for relative paths."
+            exit 1
+          else
+            echo "✅ No bad '/php/' URLs found."
+          fi
+
+
+
+      - name: Check Python syntax
+        run: |
+          set -e
+          echo "🔍 Checking Python syntax..."
+          find . -name "*.py" -print0 | xargs -0 -n1 python3 -m py_compile
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install linting tools
+        run: |
+          # Python linting
+          pip install flake8
+          # Docker linting
+          wget -O /tmp/hadolint https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64
+          chmod +x /tmp/hadolint
+          # PHP and shellcheck for syntax checking
+          sudo apt-get update && sudo apt-get install -y php-cli shellcheck
+
+      - name: Shell check
+        continue-on-error: true
+        run: |
+          echo "🔍 Checking shell scripts..."
+          find . -name "*.sh" -exec shellcheck {} \;
+
+      - name: Python lint
+        continue-on-error: true
+        run: |
+          echo "🔍 Linting Python code..."
+          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+
+      - name: PHP check
+        continue-on-error: true
+        run: |
+          echo "🔍 Checking PHP syntax..."
+          find . -name "*.php" -exec php -l {} \;
+
+      - name: Docker lint
+        continue-on-error: true
+        run: |
+          echo "🔍 Linting Dockerfiles..."
+          /tmp/hadolint --config .hadolint.yaml Dockerfile* || true
+
+  docker-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run Docker-based tests
+        run: |
+          echo "🐳 Running Docker-based tests..."
+          chmod +x ./scripts/run_tests_in_docker_environment.sh
+          ./scripts/run_tests_in_docker_environment.sh

.github/workflows/code_checks.yml

@@ -1,41 +0,0 @@
-name: Code checks
-on:
-  push:
-    branches:
-      - main
-    tags:
-      - '*.*.*'
-  pull_request:
-    branches:
-      - main
-
-jobs:
-  check-url-paths:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Check for incorrect absolute '/php/' URLs in frontend code
-        run: |
-          echo "🔍 Checking for incorrect absolute '/php/' URLs (should be 'php/' or './php/')..."
-
-          MATCHES=$(grep -rE "['\"]\/php\/" --include=\*.{js,php,html} ./front | grep -E "\.get|\.post|\.ajax|fetch|url\s*:") || true
-
-          if [ -n "$MATCHES" ]; then
-            echo "$MATCHES"
-            echo "❌ Found incorrectly absolute '/php/' URLs. Use 'php/' or './php/' for relative paths."
-            exit 1
-          else
-            echo "✅ No bad '/php/' URLs found."
-          fi
-
-
-
-      - name: Check Python syntax
-        run: |
-          set -e
-          echo "🔍 Checking Python syntax..."
-          find . -name "*.py" -print0 | xargs -0 -n1 python3 -m py_compile
-

.github/workflows/docker_cache-cleaner.yml

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

.github/workflows/docker_dev.yml

@@ -1,4 +1,4 @@
-name: docker
+name: 🐳 👩‍💻 docker dev
 
 on:
   push:
@@ -10,16 +10,20 @@ on:
     branches:
       - main
 
-jobs: 
+jobs:
   docker_dev:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 90
     permissions:
       contents: read
       packages: write
     if: >
-      contains(github.event.head_commit.message, 'PUSHPROD') != 'True' &&
-      github.repository == 'jokob-sk/NetAlertX'  
+      !contains(github.event.head_commit.message, 'PUSHPROD') &&
+      (
+        github.repository == 'jokob-sk/NetAlertX' ||
+        github.repository == 'netalertx/NetAlertX'
+      )
+
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -30,26 +34,43 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
+      # --- Generate timestamped dev version
+      - name: Generate timestamp version
+        id: timestamp
+        run: |
+          ts=$(date -u +'%Y%m%d-%H%M%S')
+          echo "version=dev-${ts}" >> $GITHUB_OUTPUT
+          echo "Generated version: dev-${ts}"
+
       - name: Set up dynamic build ARGs
-        id: getargs        
+        id: getargs
         run: echo "version=$(cat ./stable/VERSION)" >> $GITHUB_OUTPUT
 
       - name: Get release version
         id: get_version
         run: echo "version=Dev" >> $GITHUB_OUTPUT
 
+      # --- debug output
+      - name: Debug version
+        run: |
+          echo "GITHUB_REF: $GITHUB_REF"
+          echo "Version: '${{ steps.get_version.outputs.version }}'"
+
+      # --- Write the timestamped version to .VERSION file
       - name: Create .VERSION file
-        run: echo "${{ steps.get_version.outputs.version }}" >> .VERSION
+        run: echo "${{ steps.timestamp.outputs.version }}" > .VERSION
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@v4
+        uses: docker/metadata-action@v5
         with:
           images: |
+            ghcr.io/netalertx/netalertx-dev
             ghcr.io/jokob-sk/netalertx-dev
             jokobsk/netalertx-dev
           tags: |
             type=raw,value=latest
+            type=raw,value=${{ steps.timestamp.outputs.version }}
             type=ref,event=branch
             type=ref,event=pr
             type=semver,pattern={{version}}
@@ -57,12 +78,20 @@ jobs:
             type=semver,pattern={{major}}
             type=sha
 
-      - name: Log in to Github Container Registry (GHCR)
+      - name: Login GHCR (netalertx org)
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login GHCR (jokob-sk legacy)
+        if: github.event_name != 'pull_request'
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: jokob-sk
-          password: ${{ secrets.GITHUB_TOKEN }}
+          password: ${{ secrets.GHCR_JOKOBSK_PAT }}
 
       - name: Log in to DockerHub
         if: github.event_name != 'pull_request'
@@ -72,10 +101,12 @@ jobs:
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Build and push
-        uses: docker/build-push-action@v3
+        uses: docker/build-push-action@v6
         with:
           context: .
           platforms: linux/amd64,linux/arm64,linux/arm/v7,linux/arm/v6
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/docker_dev_unsafe.yml

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

.github/workflows/docker_prod.yml

@@ -6,21 +6,20 @@
 # GitHub recommends pinning actions to a commit SHA.
 # To get a newer version, you will need to update the SHA.
 # You can also reference a tag or branch, but the action may change without warning.
-
-name: Publish Docker image
+name: 🐳 🚀 Publish Docker image
 
 on:
   release:
     types: [published]
-    tags:
-      - '*.[1-9]+[0-9]?.[1-9]+*'
+
 jobs:
   docker:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 90
     permissions:
       contents: read
       packages: write
+
     steps:
       - name: Checkout
         uses: actions/checkout@v3
@@ -31,42 +30,53 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: Set up dynamic build ARGs
-        id: getargs        
-        run: echo "version=$(cat ./stable/VERSION)" >> $GITHUB_OUTPUT
-
+      # --- Get release version from tag
       - name: Get release version
         id: get_version
-        run: echo "::set-output name=version::${GITHUB_REF#refs/tags/}"
+        run: echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
 
+
+      # --- debug output
+      - name: Debug version
+        run: |
+          echo "GITHUB_REF: $GITHUB_REF"
+          echo "Version: '${{ steps.get_version.outputs.version }}'"
+
+      # --- Write version to .VERSION file
       - name: Create .VERSION file
-        run: echo "${{ steps.get_version.outputs.version }}" >> .VERSION
+        run: echo -n "${{ steps.get_version.outputs.version }}" > .VERSION
 
+      # --- Generate Docker metadata and tags
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@v4
+        uses: docker/metadata-action@v5
         with:
-          # list of Docker images to use as base name for tags
           images: |
+            ghcr.io/netalertx/netalertx
             ghcr.io/jokob-sk/netalertx
-            jokobsk/netalertx  
-          # generate Docker tags based on the following events/attributes
+            jokobsk/netalertx
           tags: |
-            type=semver,pattern={{version}},value=${{ inputs.version }}
-            type=semver,pattern={{major}}.{{minor}},value=${{ inputs.version }}
-            type=semver,pattern={{major}},value=${{ inputs.version }}
-            type=ref,event=branch,suffix=-{{ sha }}
-            type=ref,event=pr
-            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/') }}
+            type=semver,pattern={{version}},value=${{ steps.get_version.outputs.version }}
+            type=semver,pattern={{major}}.{{minor}},value=${{ steps.get_version.outputs.version }}
+            type=semver,pattern={{major}},value=${{ steps.get_version.outputs.version }}
+            type=raw,value=latest
 
-      - name: Log in to Github Container registry
+      - name: Log in to Github Container Registry (GHCR)
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login GHCR (jokob-sk legacy)
+        if: github.event_name != 'pull_request'
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: jokob-sk
-          password: ${{ secrets.GITHUB_TOKEN }}
+          password: ${{ secrets.GHCR_JOKOBSK_PAT }}
 
-      - name: Login to DockerHub
+      - name: Log in to DockerHub
         if: github.event_name != 'pull_request'
         uses: docker/login-action@v3
         with:
@@ -74,13 +84,12 @@ jobs:
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Build and push
-        uses: docker/build-push-action@v3
+        uses: docker/build-push-action@v6
         with:
           context: .
           platforms: linux/amd64,linux/arm64,linux/arm/v7,linux/arm/v6
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          # # ⚠ disable cache if build is failing to download debian packages
           # cache-from: type=registry,ref=ghcr.io/jokob-sk/netalertx:buildcache
           # cache-to: type=registry,ref=ghcr.io/jokob-sk/netalertx:buildcache,mode=max

.github/workflows/docker_rewrite.yml

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

.github/workflows/label-issues.yml

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

.github/workflows/mkdocs.yml

@@ -1,9 +1,12 @@
-name: Deploy MkDocs
+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/run-all-tests.yml

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

.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

@@ -1,6 +1,17 @@
+.coverage
 .vscode
+.dotnet
+.vscode-server
+.gitconfig
+.*CommandMarker
+deviceid
 .DS_Store
+.cache
+nohup.out
 config/*
+.ash_history
+.VERSION
+.VERSION_PREV
 config/pialert.conf
 config/app.conf
 db/*
@@ -8,6 +19,7 @@ db/pialert.db
 db/app.db
 front/log/*
 /log/*
+/log/plugins/*
 front/api/*
 /api/*
 **/plugins/**/*.log
@@ -32,3 +44,7 @@ front/css/cloud_services.css
 
 docker-compose.yml.ffsb42
 .env.omada.ffsb42
+.venv
+test_mounts/
+.gemini/settings.json
+.vscode/mcp.json

.hadolint.yaml

@@ -0,0 +1,2 @@
+ignored:
+  - DL3018

.vscode/launch.json

@@ -29,6 +29,14 @@
             "pathMappings": {
                 "/app": "${workspaceFolder}"
             }
+        },
+        {
+            "name": "Python: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "justMyCode": true
         }
     ]
 }

.vscode/settings.json

@@ -4,10 +4,33 @@
     "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
+    
+    "terminal.integrated.defaultProfile.linux": "zsh",
+    "terminal.integrated.profiles.linux": {
+      "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"
+  ,
+  "python.linting.flake8Enabled": true,
+  "python.linting.enabled": true,
+  "python.linting.flake8Args": [
+    "--config=.flake8"
+  ],
+  "python.formatting.provider": "black",
+  "python.formatting.blackArgs": [
+    "--line-length=180"
+  ],
+  "chat.useAgentSkills": true,
+
 }

.vscode/tasks.json

@@ -1,33 +1,102 @@
 {
   "version": "2.0.0",
+  "inputs": [
+    {
+      "id": "confirmPrune",
+      "type": "promptString",
+      "description": "DANGER! Type YES to confirm pruning all unused Docker resources. This will destroy containers, images, volumes, and networks!",
+      "default": ""
+    },
+    {
+        "id": "prNumber",
+        "type": "promptString",
+        "description": "Enter GitHub PR Number",
+        "default": "1405"
+    }
+  ],
   "tasks": [
     {
-      "label": "Generate Dockerfile",
+      "label": "[Any POSIX] Generate Devcontainer Configs",
       "type": "shell",
-      "command": "${workspaceFolder:NetAlertX}/.devcontainer/scripts/generate-dockerfile.sh",
+      "command": ".devcontainer/scripts/generate-configs.sh",
+      "detail": "Generates devcontainer configs from the template. This must be run after changes to devcontainer to combine/merge them into the final config used by VS Code. Note- this has no bearing on the production or test image.",
       "presentation": {
         "echo": true,
         "reveal": "always",
         "panel": "shared",
-        "showReuseMessage": false
+        "showReuseMessage": false,
+        "group": "POSIX Tasks"
       },
       "problemMatcher": [],
       "group": {
         "kind": "build",
         "isDefault": false
       },
-      "options": {
-        "cwd": "${workspaceFolder:NetAlertX}"
-      },
       "icon": {
         "id": "tools",
         "color": "terminal.ansiYellow"
       }
     },
     {
-      "label": "Re-Run Startup Script",
+      "label": "[Any] Docker system and build Prune",
       "type": "shell",
-      "command": "${workspaceFolder:NetAlertX}/.devcontainer/scripts/setup.sh",
+      "command": ".devcontainer/scripts/confirm-docker-prune.sh",
+      "detail": "DANGER! Prunes all unused Docker resources (images, containers, volumes, networks). Any stopped container will be wiped and data will be lost.  Use with caution.",
+      "options": {
+        "env": {
+          "CONFIRM_PRUNE": "${input:confirmPrune}"
+        }
+      },
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false,
+        "group": "Any"
+      },
+      "problemMatcher": [],
+      "group": {
+        "kind": "build",
+        "isDefault": false
+      },
+      "icon": {
+        "id": "trash",
+        "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",
+      "command": "./isDevContainer.sh || exit 1;/workspaces/NetAlertX/.devcontainer/scripts/setup.sh",
+      "detail": "The startup script runs directly after the container is started. It reprovisions permissions, links folders, and performs other setup tasks. Run this if you have made changes to the setup script or need to reprovision the container.",
+      "options": {
+        "cwd": "/workspaces/NetAlertX/.devcontainer/scripts"
+      },
       "presentation": {
         "echo": true,
         "reveal": "always",
@@ -41,15 +110,20 @@
       }
     },
     {
-      "label": "Start Backend (Python)",
+      "label": "[Dev Container] Start Backend (Python)",
       "type": "shell",
-      "command": "/workspaces/NetAlertX/.devcontainer/scripts/restart-backend.sh",
+      "command": "./isDevContainer.sh || exit 1; /services/start-backend.sh",
+      "detail": "Restarts the NetAlertX backend (Python) service in the dev container. This may take 5 seconds to be completely ready.",
+      "options": {
+        "cwd": "/workspaces/NetAlertX/.devcontainer/scripts"
+      },
       "presentation": {
         "echo": true,
         "reveal": "always",
         "panel": "shared",
         "showReuseMessage": false,
-        "clear": false
+        "clear": false,
+        "group": "Devcontainer"
       },
       "problemMatcher": [],
       "icon": {
@@ -58,15 +132,20 @@
       }
     },
     {
-      "label": "Start Frontend (nginx and PHP-FPM)",
+      "label": "[Dev Container] Start CronD (Scheduler)",
       "type": "shell",
-      "command": "killall php-fpm83 nginx 2>/dev/null || true; sleep 1; php-fpm83 & nginx",
+      "command": "./isDevContainer.sh || exit 1; /services/start-crond.sh",
+      "detail": "Stops and restarts the crond service.",
+      "options": {
+        "cwd": "/workspaces/NetAlertX/.devcontainer/scripts"
+      },
       "presentation": {
         "echo": true,
         "reveal": "always",
         "panel": "shared",
         "showReuseMessage": false,
-        "clear": false
+        "clear": false,
+        "group": "Devcontainer"
       },
       "problemMatcher": [],
       "icon": {
@@ -75,9 +154,99 @@
       }
     },
     {
-      "label": "Stop Frontend & Backend Services",
+      "label": "[Dev Container] Start Frontend (nginx and PHP-FPM)",
       "type": "shell",
-      "command": "pkill -f 'php-fpm83|nginx|crond|python3' || true",
+      "command": "./isDevContainer.sh || exit 1; /services/start-php-fpm.sh & /services/start-nginx.sh  &",
+      "detail": "Stops and restarts the NetAlertX frontend services (nginx and PHP-FPM) in the dev container. This launches almost instantly.",
+      "options": {
+        "cwd": "/workspaces/NetAlertX/.devcontainer/scripts"
+
+      },
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false,
+        "clear": false,
+        "group": "Devcontainer"
+      },
+      "problemMatcher": [],
+      "icon": {
+        "id": "debug-restart",
+        "color": "terminal.ansiGreen"
+      }
+    },
+    {
+      "label": "[Dev Container] Stop Frontend & Backend Services",
+      "type": "shell",
+      "command": "./isDevContainer.sh || exit 1; pkill -f 'php-fpm83|nginx|crond|python3' || true",
+      "detail": "Stops all NetAlertX services running in the dev container.",
+      "options": {
+        "cwd": "/workspaces/NetAlertX/.devcontainer/scripts"
+      },
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false,
+        "group": "Devcontainer"
+      },
+      "problemMatcher": [],
+      "icon": {
+        "id": "debug-stop",
+        "color": "terminal.ansiRed"
+      }
+    },
+    {
+      "label": "[Any] Build Unit Test Docker image",
+      "type": "shell",
+      "command": "docker buildx build -t netalertx-test . && echo '🧪 Unit Test Docker image built: netalertx-test'",
+      "detail": "This must be run after changes to the container.  Unit testing will not register changes until after this image is rebuilt. It takes about 30 seconds to build unless changes to the venv stage are made. venv takes 90s alone.",
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false,
+        "group": "Any"
+
+      },
+      "problemMatcher": [],
+      "group": {
+        "kind": "build",
+        "isDefault": false
+      },
+      "icon": {
+        "id": "beaker",
+        "color": "terminal.ansiBlue"
+      }
+    },
+    {
+      "label": "[Dev Container] Wipe and Regenerate Database",
+      "type": "shell",
+      "command": "killall 'python3' || true && sleep 1 && rm -rf /data/db/* /data/config/* && bash /entrypoint.d/15-first-run-config.sh && bash /entrypoint.d/20-first-run-db.sh && echo '✅ Database and config wiped and regenerated'",
+      "detail": "Wipes devcontainer db and config. Provides a fresh start in devcontainer, run this task, then run the Rerun Startup Task",
+      "options": {},
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false,
+        "group": "Devcontainer"
+      },
+      "problemMatcher": [],
+      "icon": {
+        "id": "database",
+        "color": "terminal.ansiRed"
+      }
+    },
+    {
+      "label": "Build & Launch Prodcution Docker Container",
+      "type": "shell",
+      "command": "docker compose up -d --build --force-recreate",
+      "detail": "Before launching, ensure VSCode Ports are closed and services are stopped. Tasks: Stop Frontend & Backend Services & Remote: Close Unused Forwarded Ports to ensure proper operation of the new container.",
+      "options": {
+        "cwd": "/workspaces/NetAlertX"
+      },
       "presentation": {
         "echo": true,
         "reveal": "always",
@@ -85,10 +254,39 @@
         "showReuseMessage": false
       },
       "problemMatcher": [],
+      "group": {
+        "kind": "build",
+        "isDefault": false
+      },
       "icon": {
-        "id": "debug-stop",
-        "color": "terminal.ansiRed"
+        "id": "package",
+        "color": "terminal.ansiBlue"
       }
+    },
+    {
+        "label": "Analyze PR Instructions",
+        "type": "shell",
+        "command": "python3",
+        "detail": "Pull all of Coderabbit's suggestions from a pull request. Requires `gh auth login` first.",
+        "options": {
+            "cwd": "/workspaces/NetAlertX/.devcontainer/scripts"
+        },
+        "args": [
+            "/workspaces/NetAlertX/.devcontainer/scripts/coderabbit-pr-parser.py",
+            "${input:prNumber}"
+        ],
+        "problemMatcher": [],
+        "presentation": {
+            "echo": true,
+            "reveal": "always",
+            "panel": "new",
+            "showReuseMessage": false,
+            "focus": true
+        },
+        "icon": {
+            "id": "comment-discussion",
+            "color": "terminal.ansiBlue"
+        }
     }
   ]
-}
+}

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! 💙
+We appreciate every contribution, big or small! 💙

Dockerfile

@@ -1,63 +1,246 @@
+# 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
+# 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
+# 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
+# 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.
+#
+# This file can be built with `docker-compose -f docker-compose.yml up --build --force-recreate`
+
 FROM alpine:3.22 AS builder
 
 ARG INSTALL_DIR=/app
 
 ENV PYTHONUNBUFFERED=1
-
-# Install build dependencies
-RUN apk add --no-cache bash shadow python3 python3-dev gcc musl-dev libffi-dev openssl-dev git \
-    && python -m venv /opt/venv
-
-# Enable venv
 ENV PATH="/opt/venv/bin:$PATH"
 
-COPY . ${INSTALL_DIR}/
+# Install build dependencies
+COPY requirements.txt /tmp/requirements.txt
+# 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
 
-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 zeroconf git+https://github.com/foreign-sub/aiofreepybox.git \
-    && bash -c "find ${INSTALL_DIR} -type d -exec chmod 750 {} \;" \
-    && bash -c "find ${INSTALL_DIR} -type f -exec chmod 640 {} \;" \
-    && bash -c "find ${INSTALL_DIR} -type f \( -name '*.sh' -o -name '*.py'  -o -name 'speedtest-cli' \) -exec chmod 750 {} \;"
+# 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
 
-# Append Iliadbox certificate to aiofreepybox
-RUN cat ${INSTALL_DIR}/install/freebox_certificate.pem >> /opt/venv/lib/python3.12/site-packages/aiofreepybox/freebox_certificates.pem
-
-# second stage
+# second stage is the main runtime stage with just the minimum required to run the application
+# The runner is used for both devcontainer, and as a base for the hardened stage.
 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
 
-COPY --from=builder /opt/venv /opt/venv
-COPY --from=builder /usr/sbin/usermod /usr/sbin/groupmod /usr/sbin/
+# NetAlertX app directories
+ENV NETALERTX_APP=${INSTALL_DIR}
+ENV NETALERTX_DATA=/data
+ENV NETALERTX_CONFIG=${NETALERTX_DATA}/config
+ENV NETALERTX_FRONT=${NETALERTX_APP}/front
+ENV NETALERTX_PLUGINS=${NETALERTX_FRONT}/plugins
+ENV NETALERTX_SERVER=${NETALERTX_APP}/server
+ENV NETALERTX_API=/tmp/api
+ENV NETALERTX_DB=${NETALERTX_DATA}/db
+ENV NETALERTX_DB_FILE=${NETALERTX_DB}/app.db
+ENV NETALERTX_BACK=${NETALERTX_APP}/back
+ENV NETALERTX_LOG=/tmp/log
+ENV NETALERTX_PLUGINS_LOG=${NETALERTX_LOG}/plugins
+ENV NETALERTX_CONFIG_FILE=${NETALERTX_CONFIG}/app.conf
 
-# Enable venv
-ENV PATH="/opt/venv/bin:$PATH" 
+# NetAlertX log files
+ENV LOG_IP_CHANGES=${NETALERTX_LOG}/IP_changes.log
+ENV LOG_APP=${NETALERTX_LOG}/app.log
+ENV LOG_APP_FRONT=${NETALERTX_LOG}/app_front.log
+ENV LOG_REPORT_OUTPUT_TXT=${NETALERTX_LOG}/report_output.txt
+ENV LOG_DB_IS_LOCKED=${NETALERTX_LOG}/db_is_locked.log
+ENV LOG_REPORT_OUTPUT_HTML=${NETALERTX_LOG}/report_output.html
+ENV LOG_STDERR=${NETALERTX_LOG}/stderr.log
+ENV LOG_APP_PHP_ERRORS=${NETALERTX_LOG}/app.php_errors.log
+ENV LOG_EXECUTION_QUEUE=${NETALERTX_LOG}/execution_queue.log
+ENV LOG_REPORT_OUTPUT_JSON=${NETALERTX_LOG}/report_output.json
+ENV LOG_STDOUT=${NETALERTX_LOG}/stdout.log
+ENV LOG_CRON=${NETALERTX_LOG}/cron.log
+ENV LOG_NGINX_ERROR=${NETALERTX_LOG}/nginx-error.log
 
-# default port and listen address
-ENV PORT=20211 LISTEN_ADDR=0.0.0.0 
+# System Services configuration files
+ENV ENTRYPOINT_CHECKS=/entrypoint.d
+ENV SYSTEM_SERVICES=/services
+ENV SYSTEM_SERVICES_SCRIPTS=${SYSTEM_SERVICES}/scripts
+ENV SYSTEM_SERVICES_CONFIG=${SYSTEM_SERVICES}/config
+ENV SYSTEM_NGINX_CONFIG=${SYSTEM_SERVICES_CONFIG}/nginx
+ENV SYSTEM_NGINX_CONFIG_TEMPLATE=${SYSTEM_NGINX_CONFIG}/netalertx.conf.template
+ENV SYSTEM_SERVICES_CONFIG_CRON=${SYSTEM_SERVICES_CONFIG}/cron
+ENV SYSTEM_SERVICES_ACTIVE_CONFIG=/tmp/nginx/active-config
+ENV SYSTEM_SERVICES_ACTIVE_CONFIG_FILE=${SYSTEM_SERVICES_ACTIVE_CONFIG}/nginx.conf
+ENV SYSTEM_SERVICES_PHP_FOLDER=${SYSTEM_SERVICES_CONFIG}/php
+ENV SYSTEM_SERVICES_PHP_FPM_D=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.d
+ENV SYSTEM_SERVICES_RUN=/tmp/run
+ENV SYSTEM_SERVICES_RUN_TMP=${SYSTEM_SERVICES_RUN}/tmp
+ENV SYSTEM_SERVICES_RUN_LOG=${SYSTEM_SERVICES_RUN}/logs
+ENV PHP_FPM_CONFIG_FILE=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.conf
+ENV READ_ONLY_FOLDERS="${NETALERTX_BACK} ${NETALERTX_FRONT} ${NETALERTX_SERVER} ${SYSTEM_SERVICES} \
+                       ${SYSTEM_SERVICES_CONFIG} ${ENTRYPOINT_CHECKS}"
+ENV READ_WRITE_FOLDERS="${NETALERTX_DATA} ${NETALERTX_CONFIG} ${NETALERTX_DB} ${NETALERTX_API} \
+                       ${NETALERTX_LOG} ${NETALERTX_PLUGINS_LOG} ${SYSTEM_SERVICES_RUN} \
+                       ${SYSTEM_SERVICES_RUN_TMP} ${SYSTEM_SERVICES_RUN_LOG} \
+                       ${SYSTEM_SERVICES_ACTIVE_CONFIG}"
 
-# needed for s6-overlay
-ENV S6_CMD_WAIT_FOR_SERVICES_MAXTIME=0
+#Python environment
+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"
 
-# ❗ IMPORTANT - if you modify this file modify the /install/install_dependecies.sh file as well ❗ 
+# App Environment
+ENV LISTEN_ADDR=0.0.0.0
+ENV PORT=20211
+ENV NETALERTX_DEBUG=0
+ENV VENDORSPATH=/app/back/ieee-oui.txt
+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
 
-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 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 ${INSTALL_DIR} ${INSTALL_DIR}" \
-    && rm -f /etc/nginx/http.d/default.conf
 
-COPY --from=builder --chown=nginx:www-data ${INSTALL_DIR}/ ${INSTALL_DIR}/
+RUN apk add --no-cache bash mtr libbsd zip lsblk tzdata curl arp-scan iproute2 iproute2-ss nmap fping \
+    nmap-scripts traceroute nbtscan net-tools net-snmp-tools bind-tools awake ca-certificates \
+    sqlite php83 php83-fpm php83-cgi php83-curl php83-sqlite3 php83-session python3 envsubst \
+    nginx supercronic shadow su-exec jq && \
+    rm -Rf /var/cache/apk/*  && \
+    rm -Rf /etc/nginx && \
+    addgroup -g ${NETALERTX_GID} ${NETALERTX_GROUP} && \
+    adduser -u ${NETALERTX_UID} -D -h ${NETALERTX_APP} -G ${NETALERTX_GROUP} ${NETALERTX_USER} && \
+    apk del shadow
 
-# Add crontab file
-COPY --chmod=600 --chown=root:root install/crontab /etc/crontabs/root
 
-# Start all required services
-RUN ${INSTALL_DIR}/dockerfiles/start.sh
 
-HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=2 \
-    CMD curl -sf -o /dev/null ${LISTEN_ADDR}:${PORT}/php/server/query_json.php?file=app_state.json
+# Install application, copy files, set permissions
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} install/production-filesystem/ /
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 back ${NETALERTX_BACK}
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 front ${NETALERTX_FRONT}
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 server ${NETALERTX_SERVER}
+
+# Create required folders with correct ownership and permissions
+RUN install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 700 ${READ_WRITE_FOLDERS} && \
+    sh -c "find ${NETALERTX_APP} -type f \( -name '*.sh' -o -name 'speedtest-cli' \) \
+    -exec chmod 750 {} \;"
+
+# Copy version information into the image
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} .[V]ERSION ${NETALERTX_APP}/.VERSION
+
+# 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; 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,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 ${VIRTUAL_ENV_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 > "${NETALERTX_FRONT}/buildtimestamp.txt"
+
+
+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
+# 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 ${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
+# Permissions 005 and 004 are not typos, they enable read-only. Everyone can
+# read the read-only files, and nobody can write to them, even the readonly user.
+
+# hadolint ignore=SC2114
+RUN chown -R ${READ_ONLY_USER}:${READ_ONLY_GROUP} ${READ_ONLY_FOLDERS} && \
+    chmod -R 004 ${READ_ONLY_FOLDERS} && \
+    find ${READ_ONLY_FOLDERS} -type d -exec chmod 005 {} + && \
+    install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 0777 ${READ_WRITE_FOLDERS} && \
+    chown ${READ_ONLY_USER}:${READ_ONLY_GROUP} /entrypoint.sh /root-entrypoint.sh /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 && \
+    # 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"
+
+# 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
 
-ENTRYPOINT ["/init"]

Dockerfile.debian

@@ -1,53 +1,241 @@
-FROM debian:bookworm-slim
+# Stage 1: Builder
+# Install build dependencies and create virtual environment
+FROM debian:bookworm-slim AS builder
 
-# default UID and GID
-ENV USER=pi USER_ID=1000 USER_GID=1000 PORT=20211 
-#TZ=Europe/London
+ENV PYTHONUNBUFFERED=1
+ENV VIRTUAL_ENV=/opt/venv
+ENV PATH="${VIRTUAL_ENV}/bin:${PATH}"
 
-# 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
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 \
+    python3-dev \
+    python3-pip \
+    python3-venv \
+    gcc \
+    git \
+    libffi-dev \
+    libssl-dev \
+    rustc \
+    cargo \
+    && rm -rf /var/lib/apt/lists/*
 
-RUN apt-get update 
-RUN apt-get install sudo -y 
+RUN python3 -m venv ${VIRTUAL_ENV}
+ENV PATH="${VIRTUAL_ENV}/bin:${PATH}"
+
+COPY requirements.txt /tmp/requirements.txt
+RUN pip install --upgrade pip setuptools wheel && \
+    pip install --no-cache-dir -r /tmp/requirements.txt
+
+# Stage 2: Runner
+# Main runtime stage with minimum requirements
+FROM debian:bookworm-slim AS runner
 
 ARG INSTALL_DIR=/app
+ARG NETALERTX_UID=20211
+ARG NETALERTX_GID=20211
+ARG READONLY_UID=20212
+ARG READONLY_GID=20212
 
-# create pi user and group
-# add root and www-data to pi group so they can r/w files and db
-RUN groupadd --gid "${USER_GID}" "${USER}" && \
-    useradd \
-        --uid ${USER_ID} \
-        --gid ${USER_GID} \
-        --create-home \
-        --shell /bin/bash \
-        ${USER} && \
-    usermod -a -G ${USER_GID} root && \
-    usermod -a -G ${USER_GID} www-data
+ENV NETALERTX_APP=${INSTALL_DIR}
+ENV NETALERTX_DATA=/data
+ENV NETALERTX_CONFIG=${NETALERTX_DATA}/config
+ENV NETALERTX_FRONT=${NETALERTX_APP}/front
+ENV NETALERTX_PLUGINS=${NETALERTX_FRONT}/plugins
+ENV NETALERTX_SERVER=${NETALERTX_APP}/server
+ENV NETALERTX_API=/tmp/api
+ENV NETALERTX_DB=${NETALERTX_DATA}/db
+ENV NETALERTX_DB_FILE=${NETALERTX_DB}/app.db
+ENV NETALERTX_BACK=${NETALERTX_APP}/back
+ENV NETALERTX_LOG=/tmp/log
+ENV NETALERTX_PLUGINS_LOG=${NETALERTX_LOG}/plugins
+ENV NETALERTX_CONFIG_FILE=${NETALERTX_CONFIG}/app.conf
 
-COPY --chmod=775 --chown=${USER_ID}:${USER_GID} . ${INSTALL_DIR}/
+ENV LOG_IP_CHANGES=${NETALERTX_LOG}/IP_changes.log
+ENV LOG_APP=${NETALERTX_LOG}/app.log
+ENV LOG_APP_FRONT=${NETALERTX_LOG}/app_front.log
+ENV LOG_REPORT_OUTPUT_TXT=${NETALERTX_LOG}/report_output.txt
+ENV LOG_DB_IS_LOCKED=${NETALERTX_LOG}/db_is_locked.log
+ENV LOG_REPORT_OUTPUT_HTML=${NETALERTX_LOG}/report_output.html
+ENV LOG_STDERR=${NETALERTX_LOG}/stderr.log
+ENV LOG_APP_PHP_ERRORS=${NETALERTX_LOG}/app.php_errors.log
+ENV LOG_EXECUTION_QUEUE=${NETALERTX_LOG}/execution_queue.log
+ENV LOG_REPORT_OUTPUT_JSON=${NETALERTX_LOG}/report_output.json
+ENV LOG_STDOUT=${NETALERTX_LOG}/stdout.log
+ENV LOG_CRON=${NETALERTX_LOG}/cron.log
+ENV LOG_NGINX_ERROR=${NETALERTX_LOG}/nginx-error.log
 
+ENV ENTRYPOINT_CHECKS=/entrypoint.d
+ENV SYSTEM_SERVICES=/services
+ENV SYSTEM_SERVICES_SCRIPTS=${SYSTEM_SERVICES}/scripts
+ENV SYSTEM_SERVICES_CONFIG=${SYSTEM_SERVICES}/config
+ENV SYSTEM_NGINX_CONFIG=${SYSTEM_SERVICES_CONFIG}/nginx
+ENV SYSTEM_NGINX_CONFIG_TEMPLATE=${SYSTEM_NGINX_CONFIG}/netalertx.conf.template
+ENV SYSTEM_SERVICES_CONFIG_CRON=${SYSTEM_SERVICES_CONFIG}/cron
+ENV SYSTEM_SERVICES_ACTIVE_CONFIG=/tmp/nginx/active-config
+ENV SYSTEM_SERVICES_ACTIVE_CONFIG_FILE=${SYSTEM_SERVICES_ACTIVE_CONFIG}/nginx.conf
+ENV SYSTEM_SERVICES_PHP_FOLDER=${SYSTEM_SERVICES_CONFIG}/php
+ENV SYSTEM_SERVICES_PHP_FPM_D=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.d
+ENV SYSTEM_SERVICES_RUN=/tmp/run
+ENV SYSTEM_SERVICES_RUN_TMP=${SYSTEM_SERVICES_RUN}/tmp
+ENV SYSTEM_SERVICES_RUN_LOG=${SYSTEM_SERVICES_RUN}/logs
+ENV PHP_FPM_CONFIG_FILE=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.conf
 
-# ❗ IMPORTANT - if you modify this file modify the /install/install_dependecies.debian.sh file as well ❗ 
+ENV READ_ONLY_FOLDERS="${NETALERTX_BACK} ${NETALERTX_FRONT} ${NETALERTX_SERVER} ${SYSTEM_SERVICES} \
+    ${SYSTEM_SERVICES_CONFIG} ${ENTRYPOINT_CHECKS}"
+ENV READ_WRITE_FOLDERS="${NETALERTX_DATA} ${NETALERTX_CONFIG} ${NETALERTX_DB} ${NETALERTX_API} \
+    ${NETALERTX_LOG} ${NETALERTX_PLUGINS_LOG} ${SYSTEM_SERVICES_RUN} \
+    ${SYSTEM_SERVICES_RUN_TMP} ${SYSTEM_SERVICES_RUN_LOG} \
+    ${SYSTEM_SERVICES_ACTIVE_CONFIG}"
 
+ENV PYTHONUNBUFFERED=1
+ENV VIRTUAL_ENV=/opt/venv
+ENV VIRTUAL_ENV_BIN=/opt/venv/bin
+ENV PYTHONPATH=${NETALERTX_APP}:${NETALERTX_SERVER}:${NETALERTX_PLUGINS}:${VIRTUAL_ENV}/lib/python3.11/site-packages
+ENV PATH="${SYSTEM_SERVICES}:${VIRTUAL_ENV_BIN}:$PATH"
 
-RUN apt-get install -y \
-    tini snmp ca-certificates curl libwww-perl arp-scan perl apt-utils cron sudo \
-    nginx-light php php-cgi php-fpm php-sqlite3 php-curl sqlite3 dnsutils net-tools php-openssl \
-    python3 python3-dev iproute2 nmap python3-pip zip systemctl usbutils traceroute nbtscan
+ENV LISTEN_ADDR=0.0.0.0
+ENV PORT=20211
+ENV NETALERTX_DEBUG=0
+ENV VENDORSPATH=/app/back/ieee-oui.txt
+ENV VENDORSPATH_NEWEST=${SYSTEM_SERVICES_RUN_TMP}/ieee-oui.txt
+ENV ENVIRONMENT=debian
+ENV READ_ONLY_USER=readonly READ_ONLY_GROUP=readonly
+ENV NETALERTX_USER=netalertx NETALERTX_GROUP=netalertx
+ENV LANG=C.UTF-8
 
-# Alternate dependencies
-RUN apt-get install nginx nginx-core mtr php-fpm php8.2-fpm php-cli php8.2 php8.2-sqlite3 -y
-RUN phpenmod -v 8.2 sqlite3 
+# Install dependencies
+# Using sury.org for PHP 8.3 to match Alpine version
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    tini \
+    snmp \
+    ca-certificates \
+    curl \
+    libwww-perl \
+    arp-scan \
+    sudo \
+    gettext-base \
+    nginx-light \
+    sqlite3 \
+    dnsutils \
+    net-tools \
+    python3 \
+    iproute2 \
+    nmap \
+    fping \
+    zip \
+    git \
+    usbutils \
+    traceroute \
+    nbtscan \
+    lsb-release \
+    wget \
+    apt-transport-https \
+    gnupg2 \
+    mtr \
+    procps \
+    gosu \
+    jq \
+    ipcalc \
+    && wget -qO /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg \
+    && echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends \
+    php8.3-fpm \
+    php8.3-cli \
+    php8.3-sqlite3 \
+    php8.3-common \
+    php8.3-curl \
+    && ln -s /usr/sbin/php-fpm8.3 /usr/sbin/php-fpm \
+    && ln -s /usr/sbin/php-fpm8.3 /usr/sbin/php-fpm83 \
+    && ln -s /usr/sbin/gosu /usr/sbin/su-exec \
+    && rm -rf /var/lib/apt/lists/*
 
-# Setup virtual python environment and use pip3 to install packages
-RUN apt-get install -y python3-venv
-RUN python3 -m venv myenv
+# Fix permissions for /tmp BEFORE copying anything that might overwrite it with bad perms
+RUN chmod 1777 /tmp
 
-RUN /bin/bash -c "source myenv/bin/activate && update-alternatives --install /usr/bin/python python /usr/bin/python3 10 && pip3 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 zeroconf "
+# User setup
+RUN groupadd -g ${NETALERTX_GID} ${NETALERTX_GROUP} && \
+    useradd -u ${NETALERTX_UID} -g ${NETALERTX_GID} -d ${NETALERTX_APP} -s /bin/bash ${NETALERTX_USER}
 
-# Create a buildtimestamp.txt to later check if a new version was released
-RUN date +%s > ${INSTALL_DIR}/front/buildtimestamp.txt
+# Copy filesystem (excluding tmp if possible, or we just fix it after)
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} install/production-filesystem/ /
+# Re-apply sticky bit to /tmp in case COPY overwrote it
+RUN chmod 1777 /tmp
 
-CMD ["${INSTALL_DIR}/install/start.debian.sh"]
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 back ${NETALERTX_BACK}
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 front ${NETALERTX_FRONT}
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 server ${NETALERTX_SERVER}
 
+# Create required folders
+RUN install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 700 ${READ_WRITE_FOLDERS} && \
+    chmod 750 /entrypoint.sh /root-entrypoint.sh
 
+# Copy Version
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} .[V]ERSION ${NETALERTX_APP}/.VERSION
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} .[V]ERSION ${NETALERTX_APP}/.VERSION_PREV
+
+# Copy venv from builder
+COPY --from=builder --chown=${READONLY_UID}:${READONLY_GID} ${VIRTUAL_ENV} ${VIRTUAL_ENV}
+
+# Init process
+RUN for vfile in .VERSION .VERSION_PREV; do \
+    if [ ! -f "${NETALERTX_APP}/${vfile}" ]; then \
+    echo "DEVELOPMENT 00000000" > "${NETALERTX_APP}/${vfile}"; \
+    fi; \
+    chown ${READONLY_UID}:${READONLY_GID} "${NETALERTX_APP}/${vfile}"; \
+    done && \
+    # Set capabilities for raw socket access
+    setcap cap_net_raw,cap_net_admin+eip /usr/bin/nmap && \
+    setcap cap_net_raw,cap_net_admin+eip /usr/sbin/arp-scan && \
+    setcap cap_net_raw,cap_net_admin,cap_net_bind_service+eip /usr/bin/nbtscan && \
+    setcap cap_net_raw,cap_net_admin+eip /usr/bin/traceroute.db && \
+    # Note: python path needs to be dynamic or verificed
+    # setcap cap_net_raw,cap_net_admin+eip $(readlink -f ${VIRTUAL_ENV_BIN}/python) && \
+    /bin/bash /build/init-nginx.sh && \
+    /bin/bash /build/init-php-fpm.sh && \
+    # /bin/bash /build/init-cron.sh && \ 
+    # Debian cron init might differ, skipping for now or need to check init-cron.sh content
+    # Checking init-backend.sh
+    /bin/bash /build/init-backend.sh && \
+    rm -rf /build && \
+    date +%s > "${NETALERTX_FRONT}/buildtimestamp.txt"
+
+ENTRYPOINT ["/bin/bash", "/entrypoint.sh"]
+
+# Stage 3: Hardened
+FROM runner AS hardened
+
+ARG NETALERTX_UID=20211
+ARG NETALERTX_GID=20211
+ARG READONLY_UID=20212
+ARG READONLY_GID=20212
+ENV READ_ONLY_USER=readonly READ_ONLY_GROUP=readonly
+
+# Create readonly user
+RUN groupadd -g ${READONLY_GID} ${READ_ONLY_GROUP} && \
+    useradd -u ${READONLY_UID} -g ${READONLY_GID} -d /app -s /usr/sbin/nologin ${READ_ONLY_USER}
+
+# Hardening: Remove package managers and set permissions
+RUN chown -R ${READ_ONLY_USER}:${READ_ONLY_GROUP} ${READ_ONLY_FOLDERS} && \
+    chmod -R 004 ${READ_ONLY_FOLDERS} && \
+    find ${READ_ONLY_FOLDERS} -type d -exec chmod 005 {} + && \
+    install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 0777 ${READ_WRITE_FOLDERS} && \
+    chown ${READ_ONLY_USER}:${READ_ONLY_GROUP} /entrypoint.sh /root-entrypoint.sh /app /opt /opt/venv && \
+    # Permissions
+    chmod 005 /entrypoint.sh /root-entrypoint.sh ${SYSTEM_SERVICES}/*.sh ${SYSTEM_SERVICES_SCRIPTS}/* ${ENTRYPOINT_CHECKS}/* /app /opt /opt/venv && \
+    # Cleanups
+    rm -f \
+    "${NETALERTX_CONFIG}/app.conf" \
+    "${NETALERTX_DB_FILE}" \
+    "${NETALERTX_DB_FILE}-shm" \
+    "${NETALERTX_DB_FILE}-wal" || true && \
+    # Remove apt and sensitive files
+    rm -rf /var/lib/apt /var/lib/dpkg /var/cache/apt /usr/bin/apt* /usr/bin/dpkg* \
+    /etc/shadow /etc/gshadow /etc/sudoers /root /home/root && \
+    # Dummy sudo
+    printf '#!/bin/sh\n"$@"\n' > /usr/bin/sudo && chmod +x /usr/bin/sudo
+
+USER 0
+ENTRYPOINT ["/root-entrypoint.sh"]
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD /services/healthcheck.sh

README.md

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

api

@@ -0,0 +1 @@
+/tmp/api

back/app.conf

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

back/app.sql

@@ -0,0 +1,427 @@
+CREATE TABLE sqlite_stat1(tbl,idx,stat);
+CREATE TABLE Events (eve_MAC STRING (50) NOT NULL COLLATE NOCASE, eve_IP STRING (50) NOT NULL COLLATE NOCASE, eve_DateTime DATETIME NOT NULL, eve_EventType STRING (30) NOT NULL COLLATE NOCASE, eve_AdditionalInfo STRING (250) DEFAULT (''), eve_PendingAlertEmail BOOLEAN NOT NULL CHECK (eve_PendingAlertEmail IN (0, 1)) DEFAULT (1), eve_PairEventRowid INTEGER);
+CREATE TABLE Sessions (ses_MAC STRING (50) COLLATE NOCASE, ses_IP STRING (50) COLLATE NOCASE, ses_EventTypeConnection STRING (30) COLLATE NOCASE, ses_DateTimeConnection DATETIME, ses_EventTypeDisconnection STRING (30) COLLATE NOCASE, ses_DateTimeDisconnection DATETIME, ses_StillConnected BOOLEAN, ses_AdditionalInfo STRING (250));
+CREATE TABLE IF NOT EXISTS "Online_History" (
+            "Index"	INTEGER,
+            "Scan_Date"	TEXT,
+            "Online_Devices"	INTEGER,
+            "Down_Devices"	INTEGER,
+            "All_Devices"	INTEGER,
+            "Archived_Devices" INTEGER,
+            "Offline_Devices" INTEGER,
+            PRIMARY KEY("Index" AUTOINCREMENT)
+          );
+CREATE TABLE sqlite_sequence(name,seq);
+CREATE TABLE Devices (
+              devMac STRING (50) PRIMARY KEY NOT NULL COLLATE NOCASE,
+              devName STRING (50) NOT NULL DEFAULT "(unknown)",
+              devOwner STRING (30) DEFAULT "(unknown)" NOT NULL,
+              devType STRING (30),
+              devVendor STRING (250),
+              devFavorite BOOLEAN CHECK (devFavorite IN (0, 1)) DEFAULT (0) NOT NULL,
+              devGroup STRING (10),
+              devComments TEXT,
+              devFirstConnection DATETIME NOT NULL,
+              devLastConnection DATETIME NOT NULL,
+              devLastIP STRING (50) NOT NULL COLLATE NOCASE,
+              devPrimaryIPv4 TEXT,
+              devPrimaryIPv6 TEXT,
+              devVlan TEXT,
+              devForceStatus TEXT,
+              devStaticIP BOOLEAN DEFAULT (0) NOT NULL CHECK (devStaticIP IN (0, 1)),
+              devScan INTEGER DEFAULT (1) NOT NULL,
+              devLogEvents BOOLEAN NOT NULL DEFAULT (1) CHECK (devLogEvents IN (0, 1)),
+              devAlertEvents BOOLEAN NOT NULL DEFAULT (1) CHECK (devAlertEvents IN (0, 1)),
+              devAlertDown BOOLEAN NOT NULL DEFAULT (0) CHECK (devAlertDown IN (0, 1)),
+              devSkipRepeated INTEGER DEFAULT 0 NOT NULL,
+              devLastNotification DATETIME,
+              devPresentLastScan BOOLEAN NOT NULL DEFAULT (0) CHECK (devPresentLastScan IN (0, 1)),
+              devIsNew BOOLEAN NOT NULL DEFAULT (1) CHECK (devIsNew IN (0, 1)),
+              devLocation STRING (250) COLLATE NOCASE,
+              devIsArchived BOOLEAN NOT NULL DEFAULT (0) CHECK (devIsArchived IN (0, 1)),
+              devParentMAC TEXT,
+              devParentPort INTEGER,
+              devParentRelType TEXT,
+              devIcon TEXT,
+              devGUID TEXT,
+              devSite TEXT,
+              devSSID TEXT,
+              devSyncHubNode TEXT,
+              devSourcePlugin TEXT,
+              devMacSource TEXT,
+              devNameSource TEXT,
+              devFQDNSource TEXT,
+              devLastIPSource TEXT,
+              devVendorSource TEXT,
+              devSSIDSource TEXT,
+              devParentMACSource TEXT,
+              devParentPortSource TEXT,
+              devParentRelTypeSource TEXT,
+              devVlanSource TEXT,
+              "devCustomProps" TEXT);
+CREATE TABLE IF NOT EXISTS "Settings" (
+            "setKey"	        TEXT,
+            "setName"	        TEXT,
+            "setDescription"	TEXT,
+            "setType"         TEXT,
+            "setOptions"      TEXT,
+            "setGroup"	          TEXT,
+            "setValue"	      TEXT,
+            "setEvents"	        TEXT,
+            "setOverriddenByEnv" INTEGER
+            );
+CREATE TABLE IF NOT EXISTS "Parameters" (
+            "par_ID" TEXT PRIMARY KEY,
+            "par_Value"	TEXT
+          );
+CREATE TABLE Plugins_Objects(
+                                    "Index"	          INTEGER,
+                                    Plugin TEXT NOT NULL,
+                                    Object_PrimaryID TEXT NOT NULL,
+                                    Object_SecondaryID TEXT NOT NULL,
+                                    DateTimeCreated TEXT NOT NULL,
+                                    DateTimeChanged TEXT NOT NULL,
+                                    Watched_Value1 TEXT NOT NULL,
+                                    Watched_Value2 TEXT NOT NULL,
+                                    Watched_Value3 TEXT NOT NULL,
+                                    Watched_Value4 TEXT NOT NULL,
+                                    Status TEXT NOT NULL,
+                                    Extra TEXT NOT NULL,
+                                    UserData TEXT NOT NULL,
+                                    ForeignKey TEXT NOT NULL,
+                                    SyncHubNodeName TEXT,
+                                    "HelpVal1" TEXT,
+                                    "HelpVal2" TEXT,
+                                    "HelpVal3" TEXT,
+                                    "HelpVal4" TEXT,
+                                    ObjectGUID TEXT,
+                                    PRIMARY KEY("Index" AUTOINCREMENT)
+                        );
+CREATE TABLE Plugins_Events(
+                                    "Index"	          INTEGER,
+                                    Plugin TEXT NOT NULL,
+                                    Object_PrimaryID TEXT NOT NULL,
+                                    Object_SecondaryID TEXT NOT NULL,
+                                    DateTimeCreated TEXT NOT NULL,
+                                    DateTimeChanged TEXT NOT NULL,
+                                    Watched_Value1 TEXT NOT NULL,
+                                    Watched_Value2 TEXT NOT NULL,
+                                    Watched_Value3 TEXT NOT NULL,
+                                    Watched_Value4 TEXT NOT NULL,
+                                    Status TEXT NOT NULL,
+                                    Extra TEXT NOT NULL,
+                                    UserData TEXT NOT NULL,
+                                    ForeignKey TEXT NOT NULL,
+                                    SyncHubNodeName TEXT,
+                                    "HelpVal1" TEXT,
+                                    "HelpVal2" TEXT,
+                                    "HelpVal3" TEXT,
+                                    "HelpVal4" TEXT, "ObjectGUID" TEXT,
+                                    PRIMARY KEY("Index" AUTOINCREMENT)
+                        );
+CREATE TABLE Plugins_History(
+                                    "Index"	          INTEGER,
+                                    Plugin TEXT NOT NULL,
+                                    Object_PrimaryID TEXT NOT NULL,
+                                    Object_SecondaryID TEXT NOT NULL,
+                                    DateTimeCreated TEXT NOT NULL,
+                                    DateTimeChanged TEXT NOT NULL,
+                                    Watched_Value1 TEXT NOT NULL,
+                                    Watched_Value2 TEXT NOT NULL,
+                                    Watched_Value3 TEXT NOT NULL,
+                                    Watched_Value4 TEXT NOT NULL,
+                                    Status TEXT NOT NULL,
+                                    Extra TEXT NOT NULL,
+                                    UserData TEXT NOT NULL,
+                                    ForeignKey TEXT NOT NULL,
+                                    SyncHubNodeName TEXT,
+                                    "HelpVal1" TEXT,
+                                    "HelpVal2" TEXT,
+                                    "HelpVal3" TEXT,
+                                    "HelpVal4" TEXT, "ObjectGUID" TEXT,
+                                    PRIMARY KEY("Index" AUTOINCREMENT)
+                        );
+CREATE TABLE Plugins_Language_Strings(
+                                "Index"	          INTEGER,
+                                Language_Code TEXT NOT NULL,
+                                String_Key TEXT NOT NULL,
+                                String_Value TEXT NOT NULL,
+                                Extra TEXT NOT NULL,
+                                PRIMARY KEY("Index" AUTOINCREMENT)
+                        );
+CREATE TABLE CurrentScan (
+                                scanMac STRING(50) NOT NULL COLLATE NOCASE,
+                                scanLastIP STRING(50) NOT NULL COLLATE NOCASE,
+                                scanVendor STRING(250),
+                                scanSourcePlugin STRING(10),
+                                scanName STRING(250),
+                                scanLastQuery STRING(250),
+                                scanLastConnection STRING(250),
+                                scanSyncHubNode STRING(50),
+                                scanSite STRING(250),
+                                scanSSID STRING(250),
+                                scanVlan STRING(250),
+                                scanParentMAC STRING(250),
+                                scanParentPort STRING(250),
+                                scanType STRING(250),
+                                UNIQUE(scanMac)
+                            );
+CREATE TABLE IF NOT EXISTS "AppEvents" (
+                "Index" INTEGER PRIMARY KEY AUTOINCREMENT,
+                "GUID" TEXT UNIQUE,
+                "AppEventProcessed" BOOLEAN,
+                "DateTimeCreated" TEXT,
+                "ObjectType" TEXT,
+                "ObjectGUID" TEXT,
+                "ObjectPlugin" TEXT,
+                "ObjectPrimaryID" TEXT,
+                "ObjectSecondaryID" TEXT,
+                "ObjectForeignKey" TEXT,
+                "ObjectIndex" TEXT,
+                "ObjectIsNew" BOOLEAN,
+                "ObjectIsArchived" BOOLEAN,
+                "ObjectStatusColumn" TEXT,
+                "ObjectStatus" TEXT,
+                "AppEventType" TEXT,
+                "Helper1" TEXT,
+                "Helper2" TEXT,
+                "Helper3" TEXT,
+                "Extra" TEXT
+            );
+CREATE TABLE IF NOT EXISTS "Notifications" (
+            "Index"           INTEGER,
+            "GUID"            TEXT UNIQUE,
+            "DateTimeCreated" TEXT,
+            "DateTimePushed"  TEXT,
+            "Status"          TEXT,
+            "JSON"            TEXT,
+            "Text"            TEXT,
+            "HTML"            TEXT,
+            "PublishedVia"    TEXT,
+            "Extra"           TEXT,
+            PRIMARY KEY("Index" AUTOINCREMENT)
+        );
+CREATE INDEX IDX_eve_DateTime ON Events (eve_DateTime);
+CREATE INDEX IDX_eve_EventType ON Events (eve_EventType COLLATE NOCASE);
+CREATE INDEX IDX_eve_MAC ON Events (eve_MAC COLLATE NOCASE);
+CREATE INDEX IDX_eve_PairEventRowid ON Events (eve_PairEventRowid);
+CREATE INDEX IDX_ses_EventTypeDisconnection ON Sessions (ses_EventTypeDisconnection COLLATE NOCASE);
+CREATE INDEX IDX_ses_EventTypeConnection ON Sessions (ses_EventTypeConnection COLLATE NOCASE);
+CREATE INDEX IDX_ses_DateTimeDisconnection ON Sessions (ses_DateTimeDisconnection);
+CREATE INDEX IDX_ses_MAC ON Sessions (ses_MAC COLLATE NOCASE);
+CREATE INDEX IDX_ses_DateTimeConnection ON Sessions (ses_DateTimeConnection);
+CREATE INDEX IDX_dev_PresentLastScan ON Devices (devPresentLastScan);
+CREATE INDEX IDX_dev_FirstConnection ON Devices (devFirstConnection);
+CREATE INDEX IDX_dev_AlertDeviceDown ON Devices (devAlertDown);
+CREATE INDEX IDX_dev_StaticIP ON Devices (devStaticIP);
+CREATE INDEX IDX_dev_ScanCycle ON Devices (devScan);
+CREATE INDEX IDX_dev_Favorite ON Devices (devFavorite);
+CREATE INDEX IDX_dev_LastIP ON Devices (devLastIP);
+CREATE INDEX IDX_dev_NewDevice ON Devices (devIsNew);
+CREATE INDEX IDX_dev_Archived ON Devices (devIsArchived);
+CREATE VIEW Events_Devices AS
+                            SELECT *
+                            FROM Events
+                            LEFT JOIN Devices ON eve_MAC = devMac
+/* Events_Devices(eve_MAC,eve_IP,eve_DateTime,eve_EventType,eve_AdditionalInfo,eve_PendingAlertEmail,eve_PairEventRowid,devMac,devName,devOwner,devType,devVendor,devFavorite,devGroup,devComments,devFirstConnection,devLastConnection,devLastIP,devStaticIP,devScan,devLogEvents,devAlertEvents,devAlertDown,devSkipRepeated,devLastNotification,devPresentLastScan,devIsNew,devLocation,devIsArchived,devParentMAC,devParentPort,devIcon,devGUID,devSite,devSSID,devSyncHubNode,devSourcePlugin,devCustomProps) */;
+CREATE VIEW LatestEventsPerMAC AS
+                                WITH RankedEvents AS (
+                                    SELECT
+                                        e.*,
+                                        ROW_NUMBER() OVER (PARTITION BY e.eve_MAC ORDER BY e.eve_DateTime DESC) AS row_num
+                                    FROM Events AS e
+                                )
+                                SELECT
+                                    e.*,
+                                    d.*,
+                                    c.*
+                                FROM RankedEvents AS e
+                                LEFT JOIN Devices AS d ON e.eve_MAC = d.devMac
+                                INNER JOIN CurrentScan AS c ON e.eve_MAC = c.scanMac
+                                WHERE e.row_num = 1
+/* LatestEventsPerMAC(eve_MAC,eve_IP,eve_DateTime,eve_EventType,eve_AdditionalInfo,eve_PendingAlertEmail,eve_PairEventRowid,row_num,devMac,devName,devOwner,devType,devVendor,devFavorite,devGroup,devComments,devFirstConnection,devLastConnection,devLastIP,devStaticIP,devScan,devLogEvents,devAlertEvents,devAlertDown,devSkipRepeated,devLastNotification,devPresentLastScan,devIsNew,devLocation,devIsArchived,devParentMAC,devParentPort,devIcon,devGUID,devSite,devSSID,devSyncHubNode,devSourcePlugin,devCustomProps,scanMac,scanLastIP,scanVendor,scanSourcePlugin,scanName,scanLastQuery,scanLastConnection,scanSyncHubNode,scanSite,scanSSID,scanParentMAC,scanParentPort,scanType) */;
+CREATE VIEW Sessions_Devices AS SELECT * FROM Sessions LEFT JOIN "Devices" ON ses_MAC = devMac
+/* Sessions_Devices(ses_MAC,ses_IP,ses_EventTypeConnection,ses_DateTimeConnection,ses_EventTypeDisconnection,ses_DateTimeDisconnection,ses_StillConnected,ses_AdditionalInfo,devMac,devName,devOwner,devType,devVendor,devFavorite,devGroup,devComments,devFirstConnection,devLastConnection,devLastIP,devStaticIP,devScan,devLogEvents,devAlertEvents,devAlertDown,devSkipRepeated,devLastNotification,devPresentLastScan,devIsNew,devLocation,devIsArchived,devParentMAC,devParentPort,devIcon,devGUID,devSite,devSSID,devSyncHubNode,devSourcePlugin,devCustomProps) */;
+CREATE VIEW Convert_Events_to_Sessions AS  SELECT EVE1.eve_MAC,
+                                      EVE1.eve_IP,
+                                      EVE1.eve_EventType AS eve_EventTypeConnection,
+                                      EVE1.eve_DateTime AS eve_DateTimeConnection,
+                                      CASE WHEN EVE2.eve_EventType IN ('Disconnected', 'Device Down') OR
+                                                EVE2.eve_EventType IS NULL THEN EVE2.eve_EventType ELSE '<missing event>' END AS eve_EventTypeDisconnection,
+                                      CASE WHEN EVE2.eve_EventType IN ('Disconnected', 'Device Down') THEN EVE2.eve_DateTime ELSE NULL END AS eve_DateTimeDisconnection,
+                                      CASE WHEN EVE2.eve_EventType IS NULL THEN 1 ELSE 0 END AS eve_StillConnected,
+                                      EVE1.eve_AdditionalInfo
+                                  FROM Events AS EVE1
+                                      LEFT JOIN
+                                      Events AS EVE2 ON EVE1.eve_PairEventRowID = EVE2.RowID
+                                WHERE EVE1.eve_EventType IN ('New Device', 'Connected','Down Reconnected')
+                            UNION
+                                SELECT eve_MAC,
+                                      eve_IP,
+                                      '<missing event>' AS eve_EventTypeConnection,
+                                      NULL AS eve_DateTimeConnection,
+                                      eve_EventType AS eve_EventTypeDisconnection,
+                                      eve_DateTime AS eve_DateTimeDisconnection,
+                                      0 AS eve_StillConnected,
+                                      eve_AdditionalInfo
+                                  FROM Events AS EVE1
+                                WHERE (eve_EventType = 'Device Down' OR
+                                        eve_EventType = 'Disconnected') AND
+                                      EVE1.eve_PairEventRowID IS NULL
+/* Convert_Events_to_Sessions(eve_MAC,eve_IP,eve_EventTypeConnection,eve_DateTimeConnection,eve_EventTypeDisconnection,eve_DateTimeDisconnection,eve_StillConnected,eve_AdditionalInfo) */;
+CREATE TRIGGER "trg_insert_devices"
+            AFTER INSERT ON "Devices"
+            WHEN NOT EXISTS (
+                SELECT 1 FROM AppEvents
+                WHERE AppEventProcessed = 0
+                AND ObjectType = 'Devices'
+                AND ObjectGUID = NEW.devGUID
+                AND ObjectStatus = CASE WHEN NEW.devPresentLastScan = 1 THEN 'online' ELSE 'offline' END
+                AND AppEventType = 'insert'
+            )
+            BEGIN
+                INSERT INTO "AppEvents" (
+                    "GUID",
+                    "DateTimeCreated",
+                    "AppEventProcessed",
+                    "ObjectType",
+                    "ObjectGUID",
+                    "ObjectPrimaryID",
+                    "ObjectSecondaryID",
+                    "ObjectStatus",
+                    "ObjectStatusColumn",
+                    "ObjectIsNew",
+                    "ObjectIsArchived",
+                    "ObjectForeignKey",
+                    "ObjectPlugin",
+                    "AppEventType"
+                )
+                VALUES (
+
+                lower(
+                    hex(randomblob(4)) || '-' || hex(randomblob(2)) || '-' || '4' ||
+                    substr(hex( randomblob(2)), 2) || '-' ||
+                    substr('AB89', 1 + (abs(random()) % 4) , 1)  ||
+                    substr(hex(randomblob(2)), 2) || '-' ||
+                    hex(randomblob(6))
+                )
+            ,
+                    DATETIME('now'),
+                    FALSE,
+                    'Devices',
+                    NEW.devGUID,  -- ObjectGUID
+                    NEW.devMac,  -- ObjectPrimaryID
+                    NEW.devLastIP,  -- ObjectSecondaryID
+                    CASE WHEN NEW.devPresentLastScan = 1 THEN 'online' ELSE 'offline' END,  -- ObjectStatus
+                    'devPresentLastScan',  -- ObjectStatusColumn
+                    NEW.devIsNew,  -- ObjectIsNew
+                    NEW.devIsArchived,  -- ObjectIsArchived
+                    NEW.devGUID,  -- ObjectForeignKey
+                    'DEVICES',  -- ObjectForeignKey
+                    'insert'
+                );
+            END;
+CREATE TRIGGER "trg_update_devices"
+            AFTER UPDATE ON "Devices"
+            WHEN NOT EXISTS (
+                SELECT 1 FROM AppEvents
+                WHERE AppEventProcessed = 0
+                AND ObjectType = 'Devices'
+                AND ObjectGUID = NEW.devGUID
+                AND ObjectStatus = CASE WHEN NEW.devPresentLastScan = 1 THEN 'online' ELSE 'offline' END
+                AND AppEventType = 'update'
+            )
+            BEGIN
+                INSERT INTO "AppEvents" (
+                    "GUID",
+                    "DateTimeCreated",
+                    "AppEventProcessed",
+                    "ObjectType",
+                    "ObjectGUID",
+                    "ObjectPrimaryID",
+                    "ObjectSecondaryID",
+                    "ObjectStatus",
+                    "ObjectStatusColumn",
+                    "ObjectIsNew",
+                    "ObjectIsArchived",
+                    "ObjectForeignKey",
+                    "ObjectPlugin",
+                    "AppEventType"
+                )
+                VALUES (
+
+                lower(
+                    hex(randomblob(4)) || '-' || hex(randomblob(2)) || '-' || '4' ||
+                    substr(hex( randomblob(2)), 2) || '-' ||
+                    substr('AB89', 1 + (abs(random()) % 4) , 1)  ||
+                    substr(hex(randomblob(2)), 2) || '-' ||
+                    hex(randomblob(6))
+                )
+            ,
+                    DATETIME('now'),
+                    FALSE,
+                    'Devices',
+                    NEW.devGUID,  -- ObjectGUID
+                    NEW.devMac,  -- ObjectPrimaryID
+                    NEW.devLastIP,  -- ObjectSecondaryID
+                    CASE WHEN NEW.devPresentLastScan = 1 THEN 'online' ELSE 'offline' END,  -- ObjectStatus
+                    'devPresentLastScan',  -- ObjectStatusColumn
+                    NEW.devIsNew,  -- ObjectIsNew
+                    NEW.devIsArchived,  -- ObjectIsArchived
+                    NEW.devGUID,  -- ObjectForeignKey
+                    'DEVICES',  -- ObjectForeignKey
+                    'update'
+                );
+            END;
+CREATE TRIGGER "trg_delete_devices"
+            AFTER DELETE ON "Devices"
+            WHEN NOT EXISTS (
+                SELECT 1 FROM AppEvents
+                WHERE AppEventProcessed = 0
+                AND ObjectType = 'Devices'
+                AND ObjectGUID = OLD.devGUID
+                AND ObjectStatus = CASE WHEN OLD.devPresentLastScan = 1 THEN 'online' ELSE 'offline' END
+                AND AppEventType = 'delete'
+            )
+            BEGIN
+                INSERT INTO "AppEvents" (
+                    "GUID",
+                    "DateTimeCreated",
+                    "AppEventProcessed",
+                    "ObjectType",
+                    "ObjectGUID",
+                    "ObjectPrimaryID",
+                    "ObjectSecondaryID",
+                    "ObjectStatus",
+                    "ObjectStatusColumn",
+                    "ObjectIsNew",
+                    "ObjectIsArchived",
+                    "ObjectForeignKey",
+                    "ObjectPlugin",
+                    "AppEventType"
+                )
+                VALUES (
+
+                lower(
+                    hex(randomblob(4)) || '-' || hex(randomblob(2)) || '-' || '4' ||
+                    substr(hex( randomblob(2)), 2) || '-' ||
+                    substr('AB89', 1 + (abs(random()) % 4) , 1)  ||
+                    substr(hex(randomblob(2)), 2) || '-' ||
+                    hex(randomblob(6))
+                )
+            ,
+                    DATETIME('now'),
+                    FALSE,
+                    'Devices',
+                    OLD.devGUID,  -- ObjectGUID
+                    OLD.devMac,  -- ObjectPrimaryID
+                    OLD.devLastIP,  -- ObjectSecondaryID
+                    CASE WHEN OLD.devPresentLastScan = 1 THEN 'online' ELSE 'offline' END,  -- ObjectStatus
+                    'devPresentLastScan',  -- ObjectStatusColumn
+                    OLD.devIsNew,  -- ObjectIsNew
+                    OLD.devIsArchived,  -- ObjectIsArchived
+                    OLD.devGUID,  -- ObjectForeignKey
+                    'DEVICES',  -- ObjectForeignKey
+                    'delete'
+                );
+            END;

back/cron_script.sh

@@ -1,14 +1,17 @@
 #!/bin/bash
 export INSTALL_DIR=/app
 
-LOG_FILE="${INSTALL_DIR}/log/execution_queue.log"
-
-# Check if there are any entries with cron_restart_backend
-if grep -q "cron_restart_backend" "$LOG_FILE"; then
-  # Restart python application using s6
-  s6-svc -r /var/run/s6-rc/servicedirs/netalertx
-  echo 'done'
+if [ -f "${LOG_EXECUTION_QUEUE}" ] && grep -q "cron_restart_backend" "${LOG_EXECUTION_QUEUE}"; then
+  echo "$(date): Restarting backend triggered by cron_restart_backend"
+  killall python3 || echo "killall python3 failed or no process found"
+  sleep 2
+  /services/start-backend.sh &
 
   # Remove all lines containing cron_restart_backend from the log file
-  sed -i '/cron_restart_backend/d' "$LOG_FILE"
+  # Atomic replacement with temp file. grep returns 1 if no lines selected (file becomes empty), which is valid here.
+  grep -v "cron_restart_backend" "${LOG_EXECUTION_QUEUE}" > "${LOG_EXECUTION_QUEUE}.tmp"
+  RC=$?
+  if [ $RC -eq 0 ] || [ $RC -eq 1 ]; then
+    mv "${LOG_EXECUTION_QUEUE}.tmp" "${LOG_EXECUTION_QUEUE}"
+  fi
 fi

back/device_heuristics_rules.json

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

db/.gitignore

@@ -1,2 +0,0 @@
-*
-!.gitignore

docker-compose.yml

@@ -1,82 +1,79 @@
 services:
   netalertx:
-    privileged: true
+    network_mode: host   # Use host networking for ARP scanning and other services
     build:
-      dockerfile: Dockerfile
-      context: .
-      cache_from:
-        - type=registry,ref=docker.io/jokob-sk/netalertx:buildcache
-    container_name: netalertx
-    network_mode: host
-    # restart: unless-stopped
+      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 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:
-      # - ${APP_DATA_LOCATION}/netalertx_dev/config:/app/config
-      - ${APP_DATA_LOCATION}/netalertx/config:/app/config
-      # - ${APP_DATA_LOCATION}/netalertx_dev/db:/app/db      
-      - ${APP_DATA_LOCATION}/netalertx/db:/app/db           
-      # (optional) useful for debugging if you have issues setting up the container
-      - ${APP_DATA_LOCATION}/netalertx/log:/app/log      
-      # (API: OPTION 1) use for performance
-      - type: tmpfs
-        target: /app/api
-      # (API: OPTION 2) use when debugging issues 
-      # - ${DEV_LOCATION}/api:/app/api
-      # ---------------------------------------------------------------------------
-      # DELETE START anyone trying to use this file: comment out / delete BELOW lines, they are only for development purposes
-      - ${APP_DATA_LOCATION}/netalertx/dhcp_samples/dhcp1.leases:/mnt/dhcp1.leases      # test data for DCPLSS plugin
-      - ${APP_DATA_LOCATION}/netalertx/dhcp_samples/dhcp2.leases:/mnt/dhcp2.leases      # test data for DCPLSS plugin
-      - ${APP_DATA_LOCATION}/netalertx/dhcp_samples/pihole_dhcp_full.leases:/etc/pihole/dhcp.leases      # test data for DCPLSS plugin
-      - ${APP_DATA_LOCATION}/netalertx/dhcp_samples/pihole_dhcp_2.leases:/etc/pihole/dhcp2.leases        # test data for DCPLSS plugin
-      - ${APP_DATA_LOCATION}/pihole/etc-pihole/pihole-FTL.db:/etc/pihole/pihole-FTL.db    # test data for PIHOLE plugin
-      - ${DEV_LOCATION}/mkdocs.yml:/app/mkdocs.yml
-      - ${DEV_LOCATION}/docs:/app/docs
-      - ${DEV_LOCATION}/server:/app/server            
-      - ${DEV_LOCATION}/test:/app/test            
-      - ${DEV_LOCATION}/dockerfiles:/app/dockerfiles
-      # - ${APP_DATA_LOCATION}/netalertx/php.ini:/etc/php/8.2/fpm/php.ini      
-      - ${DEV_LOCATION}/install:/app/install
-      - ${DEV_LOCATION}/front/css:/app/front/css
-      - ${DEV_LOCATION}/front/img:/app/front/img
-      - ${DEV_LOCATION}/back/update_vendors.sh:/app/back/update_vendors.sh
-      - ${DEV_LOCATION}/front/lib:/app/front/lib
-      - ${DEV_LOCATION}/front/js:/app/front/js
-      - ${DEV_LOCATION}/front/php:/app/front/php      
-      - ${DEV_LOCATION}/front/deviceDetails.php:/app/front/deviceDetails.php
-      - ${DEV_LOCATION}/front/deviceDetailsEdit.php:/app/front/deviceDetailsEdit.php
-      - ${DEV_LOCATION}/front/userNotifications.php:/app/front/userNotifications.php
-      - ${DEV_LOCATION}/front/deviceDetailsTools.php:/app/front/deviceDetailsTools.php
-      - ${DEV_LOCATION}/front/deviceDetailsPresence.php:/app/front/deviceDetailsPresence.php
-      - ${DEV_LOCATION}/front/deviceDetailsSessions.php:/app/front/deviceDetailsSessions.php
-      - ${DEV_LOCATION}/front/deviceDetailsEvents.php:/app/front/deviceDetailsEvents.php
-      - ${DEV_LOCATION}/front/devices.php:/app/front/devices.php
-      - ${DEV_LOCATION}/front/events.php:/app/front/events.php
-      - ${DEV_LOCATION}/front/plugins.php:/app/front/plugins.php
-      - ${DEV_LOCATION}/front/pluginsCore.php:/app/front/pluginsCore.php
-      - ${DEV_LOCATION}/front/index.php:/app/front/index.php
-      - ${DEV_LOCATION}/front/initCheck.php:/app/front/initCheck.php
-      - ${DEV_LOCATION}/front/maintenance.php:/app/front/maintenance.php
-      - ${DEV_LOCATION}/front/network.php:/app/front/network.php
-      - ${DEV_LOCATION}/front/presence.php:/app/front/presence.php
-      - ${DEV_LOCATION}/front/settings.php:/app/front/settings.php      
-      - ${DEV_LOCATION}/front/systeminfo.php:/app/front/systeminfo.php      
-      - ${DEV_LOCATION}/front/systeminfoNetwork.php:/app/front/systeminfoNetwork.php      
-      - ${DEV_LOCATION}/front/systeminfoServer.php:/app/front/systeminfoServer.php      
-      - ${DEV_LOCATION}/front/systeminfoStorage.php:/app/front/systeminfoStorage.php      
-      - ${DEV_LOCATION}/front/cloud_services.php:/app/front/cloud_services.php      
-      - ${DEV_LOCATION}/front/report.php:/app/front/report.php      
-      - ${DEV_LOCATION}/front/workflows.php:/app/front/workflows.php      
-      - ${DEV_LOCATION}/front/workflowsCore.php:/app/front/workflowsCore.php      
-      - ${DEV_LOCATION}/front/appEvents.php:/app/front/appEvents.php      
-      - ${DEV_LOCATION}/front/appEventsCore.php:/app/front/appEventsCore.php      
-      - ${DEV_LOCATION}/front/multiEditCore.php:/app/front/multiEditCore.php      
-      - ${DEV_LOCATION}/front/plugins:/app/front/plugins    
-      # DELETE END anyone trying to use this file: comment out / delete ABOVE lines, they are only for development purposes
-      # ---------------------------------------------------------------------------
-    environment:      
-      # - APP_CONF_OVERRIDE={"SCAN_SUBNETS":"['192.168.1.0/24 --interface=eth1']","GRAPHQL_PORT":"20223","UI_theme":"Light"}
-      - TZ=${TZ}
-      - PORT=${PORT}      
-      # ❗ DANGER ZONE BELOW - Setting ALWAYS_FRESH_INSTALL=true will delete the content of the /db & /config folders
-      - ALWAYS_FRESH_INSTALL=${ALWAYS_FRESH_INSTALL}
-      # - LOADED_PLUGINS=["DHCPLSS","PIHOLE","ASUSWRT","FREEBOX"]
-      
+
+      - type: volume                                # Persistent Docker-managed Named Volume for storage
+        source: netalertx_data                      # the default name of the volume is netalertx_data
+        target: /data                               # consolidated configuration and database storage
+        read_only: false                            # writable volume
+
+    # Example custom local folder called /home/user/netalertx_data
+    # - type: bind
+    #   source: /home/user/netalertx_data
+    #   target: /data
+    #   read_only: false
+    # ... or use the alternative format
+    # - /home/user/netalertx_data:/data:rw
+
+      - type: bind                           # Bind mount for timezone consistency
+        source: /etc/localtime
+        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
+
+    # 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
+
+    # 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
+    tmpfs:
+      - "/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
+      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.
+
+    # Resource limits to prevent resource exhaustion
+    mem_limit: 2048m            # Maximum memory usage
+    mem_reservation: 1024m      # 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:
+      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
+
+volumes:                        # Persistent volume for configuration and database storage
+  netalertx_data:

docker_build.log

@@ -0,0 +1,74 @@
+#0 building with "default" instance using docker driver
+
+#1 [internal] load build definition from Dockerfile
+#1 DONE 0.0s
+
+#1 [internal] load build definition from Dockerfile
+#1 transferring dockerfile: 11.45kB done
+#1 DONE 0.1s
+
+#2 [internal] load metadata for docker.io/library/alpine:3.22
+#2 DONE 0.0s
+
+#3 [internal] load .dockerignore
+#3 transferring context:
+#3 transferring context: 222B done
+#3 DONE 0.1s
+
+#4 [builder 1/4] FROM docker.io/library/alpine:3.22
+#4 DONE 0.0s
+
+#5 [internal] load build context
+#5 transferring context: 46.63kB 0.1s done
+#5 DONE 0.2s
+
+#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 [runner  6/11] COPY --chown=netalertx:netalertx --chmod=755 server /app/server
+#7 CACHED
+
+#8 [runner  5/11] COPY --chown=netalertx:netalertx --chmod=755 front /app/front
+#8 CACHED
+
+#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 [runner  4/11] COPY --chown=netalertx:netalertx --chmod=755 back /app/back
+#10 CACHED
+
+#11 [builder 2/4] COPY requirements.txt /tmp/requirements.txt
+#11 CACHED
+
+#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 [hardened 1/2] RUN addgroup -g 20212 "readonly" &&     adduser -u 20212 -G "readonly" -D -h /app "readonly"
+#13 CACHED
+
+#14 [runner  8/11] COPY --chown=netalertx:netalertx .[V]ERSION /app/.VERSION
+#14 CACHED
+
+#15 [runner  9/11] COPY --chown=netalertx:netalertx .[V]ERSION /app/.VERSION_PREV
+#15 CACHED
+
+#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 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 [runner 10/11] COPY --from=builder --chown=20212:20212 /opt/venv /opt/venv
+#18 CACHED
+
+#19 [runner  3/11] COPY --chown=netalertx:netalertx install/production-filesystem/ /
+#19 CACHED
+
+#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 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

dockerfiles/LICENSE

@@ -1,674 +0,0 @@
-                    GNU GENERAL PUBLIC LICENSE
-                       Version 3, 29 June 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-                            Preamble
-
-  The GNU General Public License is a free, copyleft license for
-software and other kinds of works.
-
-  The licenses for most software and other practical works are designed
-to take away your freedom to share and change the works.  By contrast,
-the GNU General Public License is intended to guarantee your freedom to
-share and change all versions of a program--to make sure it remains free
-software for all its users.  We, the Free Software Foundation, use the
-GNU General Public License for most of our software; it applies also to
-any other work released this way by its authors.  You can apply it to
-your programs, too.
-
-  When we speak of free software, we are referring to freedom, not
-price.  Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-them if you wish), that you receive source code or can get it if you
-want it, that you can change the software or use pieces of it in new
-free programs, and that you know you can do these things.
-
-  To protect your rights, we need to prevent others from denying you
-these rights or asking you to surrender the rights.  Therefore, you have
-certain responsibilities if you distribute copies of the software, or if
-you modify it: responsibilities to respect the freedom of others.
-
-  For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must pass on to the recipients the same
-freedoms that you received.  You must make sure that they, too, receive
-or can get the source code.  And you must show them these terms so they
-know their rights.
-
-  Developers that use the GNU GPL protect your rights with two steps:
-(1) assert copyright on the software, and (2) offer you this License
-giving you legal permission to copy, distribute and/or modify it.
-
-  For the developers' and authors' protection, the GPL clearly explains
-that there is no warranty for this free software.  For both users' and
-authors' sake, the GPL requires that modified versions be marked as
-changed, so that their problems will not be attributed erroneously to
-authors of previous versions.
-
-  Some devices are designed to deny users access to install or run
-modified versions of the software inside them, although the manufacturer
-can do so.  This is fundamentally incompatible with the aim of
-protecting users' freedom to change the software.  The systematic
-pattern of such abuse occurs in the area of products for individuals to
-use, which is precisely where it is most unacceptable.  Therefore, we
-have designed this version of the GPL to prohibit the practice for those
-products.  If such problems arise substantially in other domains, we
-stand ready to extend this provision to those domains in future versions
-of the GPL, as needed to protect the freedom of users.
-
-  Finally, every program is threatened constantly by software patents.
-States should not allow patents to restrict development and use of
-software on general-purpose computers, but in those that do, we wish to
-avoid the special danger that patents applied to a free program could
-make it effectively proprietary.  To prevent this, the GPL assures that
-patents cannot be used to render the program non-free.
-
-  The precise terms and conditions for copying, distribution and
-modification follow.
-
-                       TERMS AND CONDITIONS
-
-  0. Definitions.
-
-  "This License" refers to version 3 of the GNU General Public License.
-
-  "Copyright" also means copyright-like laws that apply to other kinds of
-works, such as semiconductor masks.
-
-  "The Program" refers to any copyrightable work licensed under this
-License.  Each licensee is addressed as "you".  "Licensees" and
-"recipients" may be individuals or organizations.
-
-  To "modify" a work means to copy from or adapt all or part of the work
-in a fashion requiring copyright permission, other than the making of an
-exact copy.  The resulting work is called a "modified version" of the
-earlier work or a work "based on" the earlier work.
-
-  A "covered work" means either the unmodified Program or a work based
-on the Program.
-
-  To "propagate" a work means to do anything with it that, without
-permission, would make you directly or secondarily liable for
-infringement under applicable copyright law, except executing it on a
-computer or modifying a private copy.  Propagation includes copying,
-distribution (with or without modification), making available to the
-public, and in some countries other activities as well.
-
-  To "convey" a work means any kind of propagation that enables other
-parties to make or receive copies.  Mere interaction with a user through
-a computer network, with no transfer of a copy, is not conveying.
-
-  An interactive user interface displays "Appropriate Legal Notices"
-to the extent that it includes a convenient and prominently visible
-feature that (1) displays an appropriate copyright notice, and (2)
-tells the user that there is no warranty for the work (except to the
-extent that warranties are provided), that licensees may convey the
-work under this License, and how to view a copy of this License.  If
-the interface presents a list of user commands or options, such as a
-menu, a prominent item in the list meets this criterion.
-
-  1. Source Code.
-
-  The "source code" for a work means the preferred form of the work
-for making modifications to it.  "Object code" means any non-source
-form of a work.
-
-  A "Standard Interface" means an interface that either is an official
-standard defined by a recognized standards body, or, in the case of
-interfaces specified for a particular programming language, one that
-is widely used among developers working in that language.
-
-  The "System Libraries" of an executable work include anything, other
-than the work as a whole, that (a) is included in the normal form of
-packaging a Major Component, but which is not part of that Major
-Component, and (b) serves only to enable use of the work with that
-Major Component, or to implement a Standard Interface for which an
-implementation is available to the public in source code form.  A
-"Major Component", in this context, means a major essential component
-(kernel, window system, and so on) of the specific operating system
-(if any) on which the executable work runs, or a compiler used to
-produce the work, or an object code interpreter used to run it.
-
-  The "Corresponding Source" for a work in object code form means all
-the source code needed to generate, install, and (for an executable
-work) run the object code and to modify the work, including scripts to
-control those activities.  However, it does not include the work's
-System Libraries, or general-purpose tools or generally available free
-programs which are used unmodified in performing those activities but
-which are not part of the work.  For example, Corresponding Source
-includes interface definition files associated with source files for
-the work, and the source code for shared libraries and dynamically
-linked subprograms that the work is specifically designed to require,
-such as by intimate data communication or control flow between those
-subprograms and other parts of the work.
-
-  The Corresponding Source need not include anything that users
-can regenerate automatically from other parts of the Corresponding
-Source.
-
-  The Corresponding Source for a work in source code form is that
-same work.
-
-  2. Basic Permissions.
-
-  All rights granted under this License are granted for the term of
-copyright on the Program, and are irrevocable provided the stated
-conditions are met.  This License explicitly affirms your unlimited
-permission to run the unmodified Program.  The output from running a
-covered work is covered by this License only if the output, given its
-content, constitutes a covered work.  This License acknowledges your
-rights of fair use or other equivalent, as provided by copyright law.
-
-  You may make, run and propagate covered works that you do not
-convey, without conditions so long as your license otherwise remains
-in force.  You may convey covered works to others for the sole purpose
-of having them make modifications exclusively for you, or provide you
-with facilities for running those works, provided that you comply with
-the terms of this License in conveying all material for which you do
-not control copyright.  Those thus making or running the covered works
-for you must do so exclusively on your behalf, under your direction
-and control, on terms that prohibit them from making any copies of
-your copyrighted material outside their relationship with you.
-
-  Conveying under any other circumstances is permitted solely under
-the conditions stated below.  Sublicensing is not allowed; section 10
-makes it unnecessary.
-
-  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
-
-  No covered work shall be deemed part of an effective technological
-measure under any applicable law fulfilling obligations under article
-11 of the WIPO copyright treaty adopted on 20 December 1996, or
-similar laws prohibiting or restricting circumvention of such
-measures.
-
-  When you convey a covered work, you waive any legal power to forbid
-circumvention of technological measures to the extent such circumvention
-is effected by exercising rights under this License with respect to
-the covered work, and you disclaim any intention to limit operation or
-modification of the work as a means of enforcing, against the work's
-users, your or third parties' legal rights to forbid circumvention of
-technological measures.
-
-  4. Conveying Verbatim Copies.
-
-  You may convey verbatim copies of the Program's source code as you
-receive it, in any medium, provided that you conspicuously and
-appropriately publish on each copy an appropriate copyright notice;
-keep intact all notices stating that this License and any
-non-permissive terms added in accord with section 7 apply to the code;
-keep intact all notices of the absence of any warranty; and give all
-recipients a copy of this License along with the Program.
-
-  You may charge any price or no price for each copy that you convey,
-and you may offer support or warranty protection for a fee.
-
-  5. Conveying Modified Source Versions.
-
-  You may convey a work based on the Program, or the modifications to
-produce it from the Program, in the form of source code under the
-terms of section 4, provided that you also meet all of these conditions:
-
-    a) The work must carry prominent notices stating that you modified
-    it, and giving a relevant date.
-
-    b) The work must carry prominent notices stating that it is
-    released under this License and any conditions added under section
-    7.  This requirement modifies the requirement in section 4 to
-    "keep intact all notices".
-
-    c) You must license the entire work, as a whole, under this
-    License to anyone who comes into possession of a copy.  This
-    License will therefore apply, along with any applicable section 7
-    additional terms, to the whole of the work, and all its parts,
-    regardless of how they are packaged.  This License gives no
-    permission to license the work in any other way, but it does not
-    invalidate such permission if you have separately received it.
-
-    d) If the work has interactive user interfaces, each must display
-    Appropriate Legal Notices; however, if the Program has interactive
-    interfaces that do not display Appropriate Legal Notices, your
-    work need not make them do so.
-
-  A compilation of a covered work with other separate and independent
-works, which are not by their nature extensions of the covered work,
-and which are not combined with it such as to form a larger program,
-in or on a volume of a storage or distribution medium, is called an
-"aggregate" if the compilation and its resulting copyright are not
-used to limit the access or legal rights of the compilation's users
-beyond what the individual works permit.  Inclusion of a covered work
-in an aggregate does not cause this License to apply to the other
-parts of the aggregate.
-
-  6. Conveying Non-Source Forms.
-
-  You may convey a covered work in object code form under the terms
-of sections 4 and 5, provided that you also convey the
-machine-readable Corresponding Source under the terms of this License,
-in one of these ways:
-
-    a) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by the
-    Corresponding Source fixed on a durable physical medium
-    customarily used for software interchange.
-
-    b) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by a
-    written offer, valid for at least three years and valid for as
-    long as you offer spare parts or customer support for that product
-    model, to give anyone who possesses the object code either (1) a
-    copy of the Corresponding Source for all the software in the
-    product that is covered by this License, on a durable physical
-    medium customarily used for software interchange, for a price no
-    more than your reasonable cost of physically performing this
-    conveying of source, or (2) access to copy the
-    Corresponding Source from a network server at no charge.
-
-    c) Convey individual copies of the object code with a copy of the
-    written offer to provide the Corresponding Source.  This
-    alternative is allowed only occasionally and noncommercially, and
-    only if you received the object code with such an offer, in accord
-    with subsection 6b.
-
-    d) Convey the object code by offering access from a designated
-    place (gratis or for a charge), and offer equivalent access to the
-    Corresponding Source in the same way through the same place at no
-    further charge.  You need not require recipients to copy the
-    Corresponding Source along with the object code.  If the place to
-    copy the object code is a network server, the Corresponding Source
-    may be on a different server (operated by you or a third party)
-    that supports equivalent copying facilities, provided you maintain
-    clear directions next to the object code saying where to find the
-    Corresponding Source.  Regardless of what server hosts the
-    Corresponding Source, you remain obligated to ensure that it is
-    available for as long as needed to satisfy these requirements.
-
-    e) Convey the object code using peer-to-peer transmission, provided
-    you inform other peers where the object code and Corresponding
-    Source of the work are being offered to the general public at no
-    charge under subsection 6d.
-
-  A separable portion of the object code, whose source code is excluded
-from the Corresponding Source as a System Library, need not be
-included in conveying the object code work.
-
-  A "User Product" is either (1) a "consumer product", which means any
-tangible personal property which is normally used for personal, family,
-or household purposes, or (2) anything designed or sold for incorporation
-into a dwelling.  In determining whether a product is a consumer product,
-doubtful cases shall be resolved in favor of coverage.  For a particular
-product received by a particular user, "normally used" refers to a
-typical or common use of that class of product, regardless of the status
-of the particular user or of the way in which the particular user
-actually uses, or expects or is expected to use, the product.  A product
-is a consumer product regardless of whether the product has substantial
-commercial, industrial or non-consumer uses, unless such uses represent
-the only significant mode of use of the product.
-
-  "Installation Information" for a User Product means any methods,
-procedures, authorization keys, or other information required to install
-and execute modified versions of a covered work in that User Product from
-a modified version of its Corresponding Source.  The information must
-suffice to ensure that the continued functioning of the modified object
-code is in no case prevented or interfered with solely because
-modification has been made.
-
-  If you convey an object code work under this section in, or with, or
-specifically for use in, a User Product, and the conveying occurs as
-part of a transaction in which the right of possession and use of the
-User Product is transferred to the recipient in perpetuity or for a
-fixed term (regardless of how the transaction is characterized), the
-Corresponding Source conveyed under this section must be accompanied
-by the Installation Information.  But this requirement does not apply
-if neither you nor any third party retains the ability to install
-modified object code on the User Product (for example, the work has
-been installed in ROM).
-
-  The requirement to provide Installation Information does not include a
-requirement to continue to provide support service, warranty, or updates
-for a work that has been modified or installed by the recipient, or for
-the User Product in which it has been modified or installed.  Access to a
-network may be denied when the modification itself materially and
-adversely affects the operation of the network or violates the rules and
-protocols for communication across the network.
-
-  Corresponding Source conveyed, and Installation Information provided,
-in accord with this section must be in a format that is publicly
-documented (and with an implementation available to the public in
-source code form), and must require no special password or key for
-unpacking, reading or copying.
-
-  7. Additional Terms.
-
-  "Additional permissions" are terms that supplement the terms of this
-License by making exceptions from one or more of its conditions.
-Additional permissions that are applicable to the entire Program shall
-be treated as though they were included in this License, to the extent
-that they are valid under applicable law.  If additional permissions
-apply only to part of the Program, that part may be used separately
-under those permissions, but the entire Program remains governed by
-this License without regard to the additional permissions.
-
-  When you convey a copy of a covered work, you may at your option
-remove any additional permissions from that copy, or from any part of
-it.  (Additional permissions may be written to require their own
-removal in certain cases when you modify the work.)  You may place
-additional permissions on material, added by you to a covered work,
-for which you have or can give appropriate copyright permission.
-
-  Notwithstanding any other provision of this License, for material you
-add to a covered work, you may (if authorized by the copyright holders of
-that material) supplement the terms of this License with terms:
-
-    a) Disclaiming warranty or limiting liability differently from the
-    terms of sections 15 and 16 of this License; or
-
-    b) Requiring preservation of specified reasonable legal notices or
-    author attributions in that material or in the Appropriate Legal
-    Notices displayed by works containing it; or
-
-    c) Prohibiting misrepresentation of the origin of that material, or
-    requiring that modified versions of such material be marked in
-    reasonable ways as different from the original version; or
-
-    d) Limiting the use for publicity purposes of names of licensors or
-    authors of the material; or
-
-    e) Declining to grant rights under trademark law for use of some
-    trade names, trademarks, or service marks; or
-
-    f) Requiring indemnification of licensors and authors of that
-    material by anyone who conveys the material (or modified versions of
-    it) with contractual assumptions of liability to the recipient, for
-    any liability that these contractual assumptions directly impose on
-    those licensors and authors.
-
-  All other non-permissive additional terms are considered "further
-restrictions" within the meaning of section 10.  If the Program as you
-received it, or any part of it, contains a notice stating that it is
-governed by this License along with a term that is a further
-restriction, you may remove that term.  If a license document contains
-a further restriction but permits relicensing or conveying under this
-License, you may add to a covered work material governed by the terms
-of that license document, provided that the further restriction does
-not survive such relicensing or conveying.
-
-  If you add terms to a covered work in accord with this section, you
-must place, in the relevant source files, a statement of the
-additional terms that apply to those files, or a notice indicating
-where to find the applicable terms.
-
-  Additional terms, permissive or non-permissive, may be stated in the
-form of a separately written license, or stated as exceptions;
-the above requirements apply either way.
-
-  8. Termination.
-
-  You may not propagate or modify a covered work except as expressly
-provided under this License.  Any attempt otherwise to propagate or
-modify it is void, and will automatically terminate your rights under
-this License (including any patent licenses granted under the third
-paragraph of section 11).
-
-  However, if you cease all violation of this License, then your
-license from a particular copyright holder is reinstated (a)
-provisionally, unless and until the copyright holder explicitly and
-finally terminates your license, and (b) permanently, if the copyright
-holder fails to notify you of the violation by some reasonable means
-prior to 60 days after the cessation.
-
-  Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-  Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License.  If your rights have been terminated and not permanently
-reinstated, you do not qualify to receive new licenses for the same
-material under section 10.
-
-  9. Acceptance Not Required for Having Copies.
-
-  You are not required to accept this License in order to receive or
-run a copy of the Program.  Ancillary propagation of a covered work
-occurring solely as a consequence of using peer-to-peer transmission
-to receive a copy likewise does not require acceptance.  However,
-nothing other than this License grants you permission to propagate or
-modify any covered work.  These actions infringe copyright if you do
-not accept this License.  Therefore, by modifying or propagating a
-covered work, you indicate your acceptance of this License to do so.
-
-  10. Automatic Licensing of Downstream Recipients.
-
-  Each time you convey a covered work, the recipient automatically
-receives a license from the original licensors, to run, modify and
-propagate that work, subject to this License.  You are not responsible
-for enforcing compliance by third parties with this License.
-
-  An "entity transaction" is a transaction transferring control of an
-organization, or substantially all assets of one, or subdividing an
-organization, or merging organizations.  If propagation of a covered
-work results from an entity transaction, each party to that
-transaction who receives a copy of the work also receives whatever
-licenses to the work the party's predecessor in interest had or could
-give under the previous paragraph, plus a right to possession of the
-Corresponding Source of the work from the predecessor in interest, if
-the predecessor has it or can get it with reasonable efforts.
-
-  You may not impose any further restrictions on the exercise of the
-rights granted or affirmed under this License.  For example, you may
-not impose a license fee, royalty, or other charge for exercise of
-rights granted under this License, and you may not initiate litigation
-(including a cross-claim or counterclaim in a lawsuit) alleging that
-any patent claim is infringed by making, using, selling, offering for
-sale, or importing the Program or any portion of it.
-
-  11. Patents.
-
-  A "contributor" is a copyright holder who authorizes use under this
-License of the Program or a work on which the Program is based.  The
-work thus licensed is called the contributor's "contributor version".
-
-  A contributor's "essential patent claims" are all patent claims
-owned or controlled by the contributor, whether already acquired or
-hereafter acquired, that would be infringed by some manner, permitted
-by this License, of making, using, or selling its contributor version,
-but do not include claims that would be infringed only as a
-consequence of further modification of the contributor version.  For
-purposes of this definition, "control" includes the right to grant
-patent sublicenses in a manner consistent with the requirements of
-this License.
-
-  Each contributor grants you a non-exclusive, worldwide, royalty-free
-patent license under the contributor's essential patent claims, to
-make, use, sell, offer for sale, import and otherwise run, modify and
-propagate the contents of its contributor version.
-
-  In the following three paragraphs, a "patent license" is any express
-agreement or commitment, however denominated, not to enforce a patent
-(such as an express permission to practice a patent or covenant not to
-sue for patent infringement).  To "grant" such a patent license to a
-party means to make such an agreement or commitment not to enforce a
-patent against the party.
-
-  If you convey a covered work, knowingly relying on a patent license,
-and the Corresponding Source of the work is not available for anyone
-to copy, free of charge and under the terms of this License, through a
-publicly available network server or other readily accessible means,
-then you must either (1) cause the Corresponding Source to be so
-available, or (2) arrange to deprive yourself of the benefit of the
-patent license for this particular work, or (3) arrange, in a manner
-consistent with the requirements of this License, to extend the patent
-license to downstream recipients.  "Knowingly relying" means you have
-actual knowledge that, but for the patent license, your conveying the
-covered work in a country, or your recipient's use of the covered work
-in a country, would infringe one or more identifiable patents in that
-country that you have reason to believe are valid.
-
-  If, pursuant to or in connection with a single transaction or
-arrangement, you convey, or propagate by procuring conveyance of, a
-covered work, and grant a patent license to some of the parties
-receiving the covered work authorizing them to use, propagate, modify
-or convey a specific copy of the covered work, then the patent license
-you grant is automatically extended to all recipients of the covered
-work and works based on it.
-
-  A patent license is "discriminatory" if it does not include within
-the scope of its coverage, prohibits the exercise of, or is
-conditioned on the non-exercise of one or more of the rights that are
-specifically granted under this License.  You may not convey a covered
-work if you are a party to an arrangement with a third party that is
-in the business of distributing software, under which you make payment
-to the third party based on the extent of your activity of conveying
-the work, and under which the third party grants, to any of the
-parties who would receive the covered work from you, a discriminatory
-patent license (a) in connection with copies of the covered work
-conveyed by you (or copies made from those copies), or (b) primarily
-for and in connection with specific products or compilations that
-contain the covered work, unless you entered into that arrangement,
-or that patent license was granted, prior to 28 March 2007.
-
-  Nothing in this License shall be construed as excluding or limiting
-any implied license or other defenses to infringement that may
-otherwise be available to you under applicable patent law.
-
-  12. No Surrender of Others' Freedom.
-
-  If conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License.  If you cannot convey a
-covered work so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you may
-not convey it at all.  For example, if you agree to terms that obligate you
-to collect a royalty for further conveying from those to whom you convey
-the Program, the only way you could satisfy both those terms and this
-License would be to refrain entirely from conveying the Program.
-
-  13. Use with the GNU Affero General Public License.
-
-  Notwithstanding any other provision of this License, you have
-permission to link or combine any covered work with a work licensed
-under version 3 of the GNU Affero General Public License into a single
-combined work, and to convey the resulting work.  The terms of this
-License will continue to apply to the part which is the covered work,
-but the special requirements of the GNU Affero General Public License,
-section 13, concerning interaction through a network will apply to the
-combination as such.
-
-  14. Revised Versions of this License.
-
-  The Free Software Foundation may publish revised and/or new versions of
-the GNU General Public License from time to time.  Such new versions will
-be similar in spirit to the present version, but may differ in detail to
-address new problems or concerns.
-
-  Each version is given a distinguishing version number.  If the
-Program specifies that a certain numbered version of the GNU General
-Public License "or any later version" applies to it, you have the
-option of following the terms and conditions either of that numbered
-version or of any later version published by the Free Software
-Foundation.  If the Program does not specify a version number of the
-GNU General Public License, you may choose any version ever published
-by the Free Software Foundation.
-
-  If the Program specifies that a proxy can decide which future
-versions of the GNU General Public License can be used, that proxy's
-public statement of acceptance of a version permanently authorizes you
-to choose that version for the Program.
-
-  Later license versions may give you additional or different
-permissions.  However, no additional obligations are imposed on any
-author or copyright holder as a result of your choosing to follow a
-later version.
-
-  15. Disclaimer of Warranty.
-
-  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
-APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
-HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
-OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
-THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
-IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
-ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
-
-  16. Limitation of Liability.
-
-  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
-THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
-GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
-USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
-DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
-PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
-EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
-SUCH DAMAGES.
-
-  17. Interpretation of Sections 15 and 16.
-
-  If the disclaimer of warranty and limitation of liability provided
-above cannot be given local legal effect according to their terms,
-reviewing courts shall apply local law that most closely approximates
-an absolute waiver of all civil liability in connection with the
-Program, unless a warranty or assumption of liability accompanies a
-copy of the Program in return for a fee.
-
-                     END OF TERMS AND CONDITIONS
-
-            How to Apply These Terms to Your New Programs
-
-  If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
-  To do so, attach the following notices to the program.  It is safest
-to attach them to the start of each source file to most effectively
-state the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
-    <one line to give the program's name and a brief idea of what it does.>
-    Copyright (C) <year>  <name of author>
-
-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-Also add information on how to contact you by electronic and paper mail.
-
-  If the program does terminal interaction, make it output a short
-notice like this when it starts in an interactive mode:
-
-    <program>  Copyright (C) <year>  <name of author>
-    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
-    This is free software, and you are welcome to redistribute it
-    under certain conditions; type `show c' for details.
-
-The hypothetical commands `show w' and `show c' should show the appropriate
-parts of the General Public License.  Of course, your program's commands
-might be different; for a GUI interface, you would use an "about box".
-
-  You should also get your employer (if you work as a programmer) or school,
-if any, to sign a "copyright disclaimer" for the program, if necessary.
-For more information on this, and how to apply and follow the GNU GPL, see
-<https://www.gnu.org/licenses/>.
-
-  The GNU General Public License does not permit incorporating your program
-into proprietary programs.  If your program is a subroutine library, you
-may consider it more useful to permit linking proprietary applications with
-the library.  If this is what you want to do, use the GNU Lesser General
-Public License instead of this License.  But first, please read
-<https://www.gnu.org/licenses/why-not-lgpl.html>.

dockerfiles/init.sh

@@ -1,169 +0,0 @@
-#!/usr/bin/with-contenv bash
-
-echo "---------------------------------------------------------
-[INSTALL]                                    Run init.sh
----------------------------------------------------------"
-
-DEFAULT_PUID=102
-DEFAULT_GID=82
-
-PUID=${PUID:-${DEFAULT_PUID}}
-PGID=${PGID:-${DEFAULT_GID}}
-
-echo "[INSTALL] Setting up user UID and GID"
-
-if ! groupmod -o -g "$PGID" www-data && [ "$PGID" != "$DEFAULT_GID" ] ; then
-   echo "Failed to set user GID to ${PGID}, trying with default GID ${DEFAULT_GID}"
-   groupmod -o -g "$DEFAULT_GID" www-data
-fi
-if ! usermod -o -u "$PUID" nginx && [ "$PUID" != "$DEFAULT_PUID" ] ; then
-   echo "Failed to set user UID to ${PUID}, trying with default PUID ${DEFAULT_PUID}"
-   usermod -o -u "$DEFAULT_PUID" nginx
-fi
-
-echo "
----------------------------------------------------------
-GID/UID
----------------------------------------------------------
-User UID:    $(id -u nginx)
-User GID:    $(getent group www-data | cut -d: -f3)
----------------------------------------------------------"
-
-chown nginx:nginx /run/nginx/ /var/log/nginx/ /var/lib/nginx/ /var/lib/nginx/tmp/
-chgrp www-data /var/www/localhost/htdocs/
-
-export INSTALL_DIR=/app  # Specify the installation directory here
-
-# DO NOT CHANGE ANYTHING BELOW THIS LINE!
-
-CONF_FILE="app.conf"
-NGINX_CONF_FILE=netalertx.conf
-DB_FILE="app.db"
-FULL_FILEDB_PATH="${INSTALL_DIR}/db/${DB_FILE}"
-NGINX_CONFIG_FILE="/etc/nginx/http.d/${NGINX_CONF_FILE}"
-OUI_FILE="/usr/share/arp-scan/ieee-oui.txt" # Define the path to ieee-oui.txt and ieee-iab.txt
-
-INSTALL_DIR_OLD=/home/pi/pialert
-OLD_APP_NAME=pialert
-
-# DO NOT CHANGE ANYTHING ABOVE THIS LINE!
-
-# Check if script is run as root
-if [[ $EUID -ne 0 ]]; then
-    echo "This script must be run as root. Please use 'sudo'."
-    exit 1
-fi
-
-# DANGER ZONE: ALWAYS_FRESH_INSTALL
-if [ "$ALWAYS_FRESH_INSTALL" = true ]; then
-  echo "[INSTALL] ❗ ALERT /db and /config folders are cleared because the ALWAYS_FRESH_INSTALL is set to: $ALWAYS_FRESH_INSTALL❗"
-
-  # Delete content of "$INSTALL_DIR/config/"
-  rm -rf "$INSTALL_DIR/config/"*
-  rm -rf "$INSTALL_DIR_OLD/config/"*
-
-  # Delete content of "$INSTALL_DIR/db/"
-  rm -rf "$INSTALL_DIR/db/"*
-  rm -rf "$INSTALL_DIR_OLD/db/"*
-fi
-
-# OVERRIDE settings: Handling APP_CONF_OVERRIDE
-# Check if APP_CONF_OVERRIDE is set
-
-# remove old
-rm "${INSTALL_DIR}/config/app_conf_override.json"
-
-if [ -z "$APP_CONF_OVERRIDE" ]; then
-  echo "APP_CONF_OVERRIDE is not set. Skipping config file creation."
-else
-  # Save the APP_CONF_OVERRIDE env variable as a JSON file
-  echo "$APP_CONF_OVERRIDE" > "${INSTALL_DIR}/config/app_conf_override.json"
-  echo "Config file saved to ${INSTALL_DIR}/config/app_conf_override.json"
-fi
-
-# 🔻 FOR BACKWARD COMPATIBILITY - REMOVE AFTER 12/12/2025
-
-# Check if pialert.db exists, then create a symbolic link to app.db
-if [ -f "${INSTALL_DIR_OLD}/db/${OLD_APP_NAME}.db" ]; then
-    ln -s "${INSTALL_DIR_OLD}/db/${OLD_APP_NAME}.db" "${FULL_FILEDB_PATH}"
-fi
-
-# Check if ${OLD_APP_NAME}.conf exists, then create a symbolic link to app.conf
-if [ -f "${INSTALL_DIR_OLD}/config/${OLD_APP_NAME}.conf" ]; then
-    ln -s "${INSTALL_DIR_OLD}/config/${OLD_APP_NAME}.conf" "${INSTALL_DIR}/config/${CONF_FILE}"
-fi
-# 🔺 FOR BACKWARD COMPATIBILITY - REMOVE AFTER 12/12/2025
-
-echo "[INSTALL] Copy starter ${DB_FILE} and ${CONF_FILE} if they don't exist"
-
-# Copy starter app.db, app.conf if they don't exist
-cp -na "${INSTALL_DIR}/back/${CONF_FILE}" "${INSTALL_DIR}/config/${CONF_FILE}"
-cp -na "${INSTALL_DIR}/back/${DB_FILE}" "${FULL_FILEDB_PATH}"
-
-# if custom variables not set we do not need to do anything
-if [ -n "${TZ}" ]; then
-  FILECONF="${INSTALL_DIR}/config/${CONF_FILE}"
-  echo "[INSTALL] Setup timezone"
-  sed -i "\#^TIMEZONE=#c\TIMEZONE='${TZ}'" "${FILECONF}"
-
-  # set TimeZone in container
-  cp /usr/share/zoneinfo/$TZ /etc/localtime
-  echo $TZ > /etc/timezone
-fi
-
-# if custom variables not set we do not need to do anything
-if [ -n "${LOADED_PLUGINS}" ]; then
-  FILECONF="${INSTALL_DIR}/config/${CONF_FILE}"
-  echo "[INSTALL] Setup custom LOADED_PLUGINS variable"
-  sed -i "\#^LOADED_PLUGINS=#c\LOADED_PLUGINS=${LOADED_PLUGINS}" "${FILECONF}"
-fi
-
-echo "[INSTALL] Setup NGINX"
-echo "Setting webserver to address ($LISTEN_ADDR) and port ($PORT)"
-envsubst '$INSTALL_DIR $LISTEN_ADDR $PORT' < "${INSTALL_DIR}/install/netalertx.template.conf" > "${NGINX_CONFIG_FILE}"
-
-# Run the hardware vendors update at least once
-echo "[INSTALL] Run the hardware vendors update"
-
-# Check if ieee-oui.txt or ieee-iab.txt exist
-if [ -f "${OUI_FILE}" ]; then
-  echo "The file ieee-oui.txt exists. Skipping update_vendors.sh..."
-else
-  echo "The file ieee-oui.txt does not exist. Running update_vendors..."
-
-  # Run the update_vendors.sh script
-  if [ -f "${INSTALL_DIR}/back/update_vendors.sh" ]; then
-    "${INSTALL_DIR}/back/update_vendors.sh"
-  else
-    echo "update_vendors.sh script not found in ${INSTALL_DIR}."
-  fi
-fi
-
-# Create an empty log files
-# Create the execution_queue.log and app_front.log files if they don't exist
-touch "${INSTALL_DIR}"/log/{app.log,execution_queue.log,app_front.log,app.php_errors.log,stderr.log,stdout.log,db_is_locked.log}
-touch "${INSTALL_DIR}"/api/user_notifications.json
-
-# Create plugins sub-directory if it doesn't exist in case a custom log folder is used
-mkdir -p "${INSTALL_DIR}"/log/plugins
-
-echo "[INSTALL] Fixing permissions after copied starter config & DB"
-chown -R nginx:www-data "${INSTALL_DIR}"
-
-chmod 750 "${INSTALL_DIR}"/{config,log,db}
-find "${INSTALL_DIR}"/{config,log,db} -type f -exec chmod 640 {} \;
-
-# Check if buildtimestamp.txt doesn't exist
-if [ ! -f "${INSTALL_DIR}/front/buildtimestamp.txt" ]; then
-    # Create buildtimestamp.txt
-    date +%s > "${INSTALL_DIR}/front/buildtimestamp.txt"
-    chown nginx:www-data "${INSTALL_DIR}/front/buildtimestamp.txt"
-fi
-
-echo -e "
-            [ENV] PATH                      is ${PATH}
-            [ENV] PORT                      is ${PORT}
-            [ENV] TZ                        is ${TZ}
-            [ENV] LISTEN_ADDR               is ${LISTEN_ADDR}
-            [ENV] ALWAYS_FRESH_INSTALL      is ${ALWAYS_FRESH_INSTALL}
-        "

dockerfiles/start.sh

@@ -1,49 +0,0 @@
-#!/bin/bash
-
-export INSTALL_DIR=/app
-export APP_NAME=netalertx
-
-# php-fpm setup
-install -d -o nginx -g www-data /run/php/
-sed -i "/^;pid/c\pid = /run/php/php8.3-fpm.pid" /etc/php83/php-fpm.conf
-sed -i "/^listen/c\listen = /run/php/php8.3-fpm.sock" /etc/php83/php-fpm.d/www.conf
-sed -i "/^;listen.owner/c\listen.owner = nginx" /etc/php83/php-fpm.d/www.conf
-sed -i "/^;listen.group/c\listen.group = www-data" /etc/php83/php-fpm.d/www.conf
-sed -i "/^user/c\user = nginx" /etc/php83/php-fpm.d/www.conf
-sed -i "/^group/c\group = www-data" /etc/php83/php-fpm.d/www.conf
-
-# s6 overlay setup
-mkdir -p /etc/s6-overlay/s6-rc.d/{SetupOneshot,crond/dependencies.d,php-fpm/dependencies.d,nginx/dependencies.d,$APP_NAME/dependencies.d}
-echo "oneshot" > /etc/s6-overlay/s6-rc.d/SetupOneshot/type
-echo "longrun" > /etc/s6-overlay/s6-rc.d/crond/type
-echo "longrun" > /etc/s6-overlay/s6-rc.d/php-fpm/type
-echo "longrun" > /etc/s6-overlay/s6-rc.d/nginx/type
-echo "longrun" > /etc/s6-overlay/s6-rc.d/$APP_NAME/type
-echo -e "${INSTALL_DIR}/dockerfiles/init.sh" > /etc/s6-overlay/s6-rc.d/SetupOneshot/up
-echo -e '#!/bin/execlineb -P
-
-        if { echo
-        "
-            [INSTALL] Starting crond service...
-
-        " }' > /etc/s6-overlay/s6-rc.d/crond/run
-echo -e "/usr/sbin/crond -f" >> /etc/s6-overlay/s6-rc.d/crond/run
-echo -e "#!/bin/execlineb -P\n/usr/sbin/php-fpm83 -F" > /etc/s6-overlay/s6-rc.d/php-fpm/run
-echo -e '#!/bin/execlineb -P\nnginx -g "daemon off;"' > /etc/s6-overlay/s6-rc.d/nginx/run
-echo -e '#!/bin/execlineb -P
-        with-contenv
-
-        importas -u PORT PORT
-
-        if { echo
-        "
-            [INSTALL] 🚀 Starting app (:${PORT})
-
-        " }' > /etc/s6-overlay/s6-rc.d/$APP_NAME/run
-echo -e "python ${INSTALL_DIR}/server" >> /etc/s6-overlay/s6-rc.d/$APP_NAME/run
-touch /etc/s6-overlay/s6-rc.d/user/contents.d/{SetupOneshot,crond,php-fpm,nginx,$APP_NAME} /etc/s6-overlay/s6-rc.d/{crond,php-fpm,nginx,$APP_NAME}/dependencies.d/SetupOneshot
-touch /etc/s6-overlay/s6-rc.d/nginx/dependencies.d/php-fpm
-touch /etc/s6-overlay/s6-rc.d/$APP_NAME/dependencies.d/nginx
-
-# this removes the current file
-rm -f $0

docs/API.md

@@ -1,4 +1,4 @@
-# NetAlertX API Documentation
+# API Documentation
 
 This API provides programmatic access to **devices, events, sessions, metrics, network tools, and sync** in NetAlertX. It is implemented as a **REST and GraphQL server**. All requests require authentication via **API Token** (`API_TOKEN` setting) unless explicitly noted. For example, to authorize a GraphQL request, you need to use a `Authorization: Bearer API_TOKEN` header as per example below:
 
@@ -23,6 +23,8 @@ curl 'http://host:GRAPHQL_PORT/graphql' \
 
 The API server runs on `0.0.0.0:<graphql_port>` with **CORS enabled** for all main endpoints.
 
+CORS configuration: You can limit allowed CORS origins with the `CORS_ORIGINS` environment variable. Set it to a comma-separated list of origins (for example: `CORS_ORIGINS="https://example.com,http://localhost:3000"`). The server parses this list at startup and only allows origins that begin with `http://` or `https://`. If `CORS_ORIGINS` is unset or parses to an empty list, the API falls back to a safe development default list (localhosts) and will include `*` as a last-resort permissive origin.
+
 ---
 
 ## Authentication
@@ -36,9 +38,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
@@ -51,22 +59,42 @@ http://<server>:<GRAPHQL_PORT>/
 
 ## Endpoints
 
+> [!NOTE]
+> You can explore the API endpoints by using the interactive API docs at `http://<server>:<GRAPHQL_PORT>/docs`.
+> ![API docs](./img/API/API_docs.png)
+
 > [!TIP]
 > When retrieving devices or settings try using the GraphQL API endpoint first as it is read-optimized.
 
+### 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
 * [Sessions](API_SESSIONS.md) – Connection sessions and history
 * [Settings](API_SETTINGS.md) – Settings
 * Messaging:
-  * [In app messaging](API_MESSAGING_IN_APP.md) - In-app messaging
+    * [In app messaging](API_MESSAGING_IN_APP.md) - In-app messaging
 * [Metrics](API_METRICS.md) – Prometheus metrics and per-device status
 * [Network Tools](API_NETTOOLS.md) – Utilities like Wake-on-LAN, traceroute, nslookup, nmap, and internet info
 * [Online History](API_ONLINEHISTORY.md) – Online/offline device records
-* [GraphQL](API_GRAPHQL.md) – Advanced queries and filtering
+* [GraphQL](API_GRAPHQL.md) – Advanced queries and filtering for Devices, Settings and Language Strings
 * [Sync](API_SYNC.md) – Synchronization between multiple NetAlertX instances
+* [Logs](API_LOGS.md) – Purging of logs and adding to the event execution queue for user triggered events
 * [DB query](API_DBQUERY.md) (⚠ Internal) - Low level database access - use other endpoints if possible
+* `/server` (⚠ Internal) - Backend server endpoint for internal communication only - **do not use directly**
+
+### MCP Server Bridge
+
+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_DEVICE_FIELD_LOCK.md

@@ -0,0 +1,157 @@
+# Device Field Lock/Unlock API
+
+## Overview
+
+The Device Field Lock/Unlock feature allows users to lock specific device fields to prevent plugin overwrites. This is part of the authoritative device field update system that ensures data integrity while maintaining flexibility for user customization.
+
+## Concepts
+
+### Tracked Fields
+
+Only certain device fields support locking. These are the fields that can be modified by both plugins and users:
+
+- `devName` - Device name/hostname
+- `devVendor` - Device vendor/manufacturer
+- `devFQDN` - Fully qualified domain name
+- `devSSID` - Network SSID
+- `devParentMAC` - Parent device MAC address
+- `devParentPort` - Parent device port
+- `devParentRelType` - Parent device relationship type
+- `devVlan` - VLAN identifier
+
+### Field Source Tracking
+
+Every tracked field has an associated `*Source` field that indicates where the current value originated:
+
+- `NEWDEV` - Created via the UI as a new device
+- `USER` - Manually edited by a user
+- `LOCKED` - Field is locked; prevents any plugin overwrites
+- Plugin name (e.g., `UNIFIAPI`, `PIHOLE`) - Last updated by this plugin
+
+### Locking Mechanism
+
+When a field is **locked**, its source is set to `LOCKED`. This prevents plugin overwrites based on the authorization logic:
+
+1. Plugin wants to update field
+2. Authoritative handler checks field's `*Source` value
+3. If `*Source` == `LOCKED`, plugin update is rejected
+4. User can still manually unlock the field
+
+When a field is **unlocked**, its source is set to `NEWDEV`, allowing plugins to resume updates.
+
+## Endpoints
+
+### Lock or Unlock a Field
+
+```
+POST /device/{mac}/field/lock
+Authorization: Bearer {API_TOKEN}
+Content-Type: application/json
+
+{
+  "fieldName": "devName",
+  "lock": true
+}
+```
+
+#### Parameters
+- `mac` (path, required): Device MAC address (e.g., `AA:BB:CC:DD:EE:FF`)
+- `fieldName` (body, required): Name of the field to lock/unlock. Must be one of the tracked fields listed above.
+- `lock` (body, required): Boolean. `true` to lock, `false` to unlock.
+
+#### Responses
+
+**Success (200)**
+```json
+{
+  "success": true,
+  "message": "Field devName locked",
+  "fieldName": "devName",
+  "locked": true
+}
+```
+
+**Bad Request (400)**
+```json
+{
+  "success": false,
+  "error": "fieldName is required"
+}
+```
+
+```json
+{
+  "success": false,
+  "error": "Field 'devInvalidField' cannot be locked"
+}
+```
+
+**Unauthorized (403)**
+```json
+{
+  "success": false,
+  "error": "Unauthorized"
+}
+```
+
+**Not Found (404)**
+```json
+{
+  "success": false,
+  "error": "Device not found"
+}
+```
+
+## Examples
+
+### Lock a Device Name
+Prevent the device name from being overwritten by plugins:
+
+```bash
+curl -X POST https://your-netalertx.local/api/device/AA:BB:CC:DD:EE:FF/field/lock \
+  -H "Authorization: Bearer your-api-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "fieldName": "devName",
+    "lock": true
+  }'
+```
+
+### Unlock a Field
+Allow plugins to resume updating a field:
+
+```bash
+curl -X POST https://your-netalertx.local/api/device/AA:BB:CC:DD:EE:FF/field/lock \
+  -H "Authorization: Bearer your-api-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "fieldName": "devName",
+    "lock": false
+  }'
+```
+
+## UI Integration
+
+The Device Edit form displays lock/unlock buttons for all tracked fields:
+
+1. **Lock Button** (🔒): Click to prevent plugin overwrites
+2. **Unlock Button** (🔓): Click to allow plugin overwrites again
+3. **Source Indicator**: Shows current field source (USER, LOCKED, NEWDEV, or plugin name)
+
+
+### Authorization Handler
+
+The authoritative field update logic prevents plugin overwrites:
+
+1. Plugin provides new value for field via plugin config `SET_ALWAYS`/`SET_EMPTY`
+2. Authoritative handler (in DeviceInstance) checks `{field}Source` value
+3. If source is `LOCKED` or `USER`, plugin update is rejected
+4. If source is `NEWDEV` or plugin name, plugin update is accepted
+
+## See Also
+
+- [Device locking](./DEVICE_FIELD_LOCK.md)
+- [Device source fields](./DEVICE_SOURCE_FIELDS.md)
+- [API Device Endpoints Documentation](./API_DEVICE.md)
+- [Authoritative Field Updates System](./PLUGINS_DEV.md#authoritative-fields)
+- [Plugin Configuration Reference](./PLUGINS_DEV_CONFIG.md)

docs/API_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_GRAPHQL.md

@@ -1,9 +1,10 @@
 # GraphQL API Endpoint
 
-GraphQL queries are **read-optimized for speed**. Data may be slightly out of date until the file system cache refreshes. The GraphQL endpoints allows you to access the following objects:
+GraphQL queries are **read-optimized for speed**. Data may be slightly out of date until the file system cache refreshes. The GraphQL endpoints allow you to access the following objects:
 
-- Devices
-- Settings
+* Devices
+* Settings
+* Language Strings (LangStrings)
 
 ## Endpoints
 
@@ -190,11 +191,74 @@ curl 'http://host:GRAPHQL_PORT/graphql' \
 }
 ```
 
+
+---
+
+## LangStrings Query
+
+The **LangStrings query** provides access to localized strings. Supports filtering by `langCode` and `langStringKey`. If the requested string is missing or empty, you can optionally fallback to `en_us`.
+
+### Sample Query
+
+```graphql
+query GetLangStrings {
+  langStrings(langCode: "de_de", langStringKey: "settings_other_scanners") {
+    langStrings {
+      langCode
+      langStringKey
+      langStringText
+    }
+    count
+  }
+}
+```
+
+### Query Parameters
+
+| Parameter        | Type    | Description                                                                              |
+| ---------------- | ------- | ---------------------------------------------------------------------------------------- |
+| `langCode`       | String  | Optional language code (e.g., `en_us`, `de_de`). If omitted, all languages are returned. |
+| `langStringKey`  | String  | Optional string key to retrieve a specific entry.                                        |
+| `fallback_to_en` | Boolean | Optional (default `true`). If `true`, empty or missing strings fallback to `en_us`.      |
+
+### `curl` Example
+
+```sh
+curl 'http://host:GRAPHQL_PORT/graphql' \
+  -X POST \
+  -H 'Authorization: Bearer API_TOKEN' \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "query": "query GetLangStrings { langStrings(langCode: \"de_de\", langStringKey: \"settings_other_scanners\") { langStrings { langCode langStringKey langStringText } count } }"
+  }'
+```
+
+### Sample Response
+
+```json
+{
+  "data": {
+    "langStrings": {
+      "count": 1,
+      "langStrings": [
+        {
+          "langCode": "de_de",
+          "langStringKey": "settings_other_scanners",
+          "langStringText": "Other, non-device scanner plugins that are currently enabled."  // falls back to en_us if empty
+        }
+      ]
+    }
+  }
+}
+```
+
 ---
 
 ## Notes
 
-* Device and settings queries can be combined in one request since GraphQL supports batching.
+* Device, settings, and LangStrings queries can be combined in **one request** since GraphQL supports batching.
+* The `fallback_to_en` feature ensures UI always has a value even if a translation is missing.
+* Data is **cached in memory** per JSON file; changes to language or plugin files will only refresh after the cache detects a file modification.
 * The `setOverriddenByEnv` flag helps identify setting values that are locked at container runtime.
 * The schema is **read-only** — updates must be performed through other APIs or configuration management. See the other [API](API.md) endpoints for details. 
 

docs/API_LOGS.md

@@ -0,0 +1,178 @@
+# Logs API Endpoints
+
+Manage or purge application log files stored under `/app/log` and manage the execution queue. These endpoints are primarily used for maintenance tasks such as clearing accumulated logs or adding system actions without restarting the container.
+
+Only specific, pre-approved log files can be purged for security and stability reasons.
+
+---
+
+## Delete (Purge) a Log File
+
+* **DELETE** `/logs?file=<log_file>` → Purge the contents of an allowed log file.
+
+**Query Parameter:**
+
+* `file` → The name of the log file to purge (e.g., `app.log`, `stdout.log`)
+
+**Allowed Files:**
+
+```
+app.log
+IP_changes.log
+stdout.log
+stderr.log
+app.php_errors.log
+execution_queue.log
+db_is_locked.log
+```
+
+**Authorization:**
+Requires a valid API token in the `Authorization` header.
+
+---
+
+### `curl` Example (Success)
+
+```sh
+curl -X DELETE 'http://<server_ip>:<GRAPHQL_PORT>/logs?file=app.log' \
+  -H 'Authorization: Bearer <API_TOKEN>' \
+  -H 'Accept: application/json'
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "message": "[clean_log] File app.log purged successfully"
+}
+```
+
+---
+
+### `curl` Example (Not Allowed)
+
+```sh
+curl -X DELETE 'http://<server_ip>:<GRAPHQL_PORT>/logs?file=not_allowed.log' \
+  -H 'Authorization: Bearer <API_TOKEN>' \
+  -H 'Accept: application/json'
+```
+
+**Response:**
+
+```json
+{
+  "success": false,
+  "message": "[clean_log] File not_allowed.log is not allowed to be purged"
+}
+```
+
+---
+
+### `curl` Example (Unauthorized)
+
+```sh
+curl -X DELETE 'http://<server_ip>:<GRAPHQL_PORT>/logs?file=app.log' \
+  -H 'Accept: application/json'
+```
+
+**Response:**
+
+```json
+{
+  "error": "Forbidden"
+}
+```
+
+---
+
+## Add an Action to the Execution Queue
+
+* **POST** `/logs/add-to-execution-queue` → Add a system action to the execution queue.
+
+**Request Body (JSON):**
+
+```json
+{
+  "action": "update_api|devices"
+}
+```
+
+**Authorization:**
+Requires a valid API token in the `Authorization` header.
+
+---
+
+### `curl` Example (Success)
+
+The below will update the API cache for Devices
+
+```sh
+curl -X POST 'http://<server_ip>:<GRAPHQL_PORT>/logs/add-to-execution-queue' \
+  -H 'Authorization: Bearer <API_TOKEN>' \
+  -H 'Content-Type: application/json' \
+  --data '{"action": "update_api|devices"}'
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "message": "[UserEventsQueueInstance] Action \"update_api|devices\" added to the execution queue."
+}
+```
+
+---
+
+### `curl` Example (Missing Parameter)
+
+```sh
+curl -X POST 'http://<server_ip>:<GRAPHQL_PORT>/logs/add-to-execution-queue' \
+  -H 'Authorization: Bearer <API_TOKEN>' \
+  -H 'Content-Type: application/json' \
+  --data '{}'
+```
+
+**Response:**
+
+```json
+{
+  "success": false,
+  "message": "Missing parameters",
+  "error": "Missing required 'action' field in JSON body"
+}
+```
+
+---
+
+### `curl` Example (Unauthorized)
+
+```sh
+curl -X POST 'http://<server_ip>:<GRAPHQL_PORT>/logs/add-to-execution-queue' \
+  -H 'Content-Type: application/json' \
+  --data '{"action": "update_api|devices"}'
+```
+
+**Response:**
+
+```json
+{
+  "error": "Forbidden"
+}
+```
+
+---
+
+## Notes
+
+* Only predefined files in `/app/log` can be purged — arbitrary paths are **not permitted**.
+* When a log file is purged:
+
+  * Its content is replaced with a short marker text: `"File manually purged"`.
+  * A backend log entry is created via `mylog()`.
+  * A frontend notification is generated via `write_notification()`.
+* Execution queue actions are appended to `execution_queue.log` and can be processed asynchronously by background tasks or workflows.
+* Unauthorized or invalid attempts are safely logged and rejected.
+* For advanced log retrieval, analysis, or structured querying, use the frontend log viewer.
+* Always ensure that sensitive or production logs are handled carefully — purging cannot be undone.

docs/API_MCP.md

@@ -0,0 +1,405 @@
+# 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
+```
+
+### 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 /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/>/devices/*]
+        G[Network Tools<br/>/nettools/*]
+        H[Events API<br/>/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
+```
+
+---
+
+## 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` | `/devices/by-status` | List devices by online status |
+| `get_device_info` | `/device/{mac}` | Get detailed device information |
+| `search_devices` | `/devices/search` | Search devices by MAC, name, or IP |
+| `get_latest_device` | `/devices/latest` | Get most recently connected device |
+| `set_device_alias` | `/device/{mac}/set-alias` | Set device friendly name |
+
+### Network Tools
+
+| Tool | Endpoint | Description |
+|------|----------|-------------|
+| `trigger_scan` | `/nettools/trigger-scan` | Trigger network discovery scan to find new devices. |
+| `run_nmap_scan` | `/nettools/nmap` | Perform NMAP scan on a target to identify open ports. |
+| `get_open_ports` | `/device/open_ports` | Get stored NMAP open ports. Use `run_nmap_scan` first if empty. |
+| `wol_wake_device` | `/nettools/wakeonlan` | Wake device using Wake-on-LAN |
+| `get_network_topology` | `/devices/network/topology` | Get network topology map |
+
+### Event & Monitoring Tools
+
+| Tool | Endpoint | Description |
+|------|----------|-------------|
+| `get_recent_alerts` | `/events/recent` | Get events from last 24 hours |
+| `get_last_events` | `/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:
 
@@ -52,11 +52,11 @@ query GetDevices($options: PageQueryOptionsInput) {
 }
 ```
 
-See also: [Debugging GraphQL issues](./DEBUG_GRAPHQL.md)
+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)`
@@ -141,24 +141,24 @@ The endpoints are updated when objects in the API endpoints are changed.
 
 ### Location of the endpoints
 
-In the container, these files are located under the `/app/api/` folder. You can access them via the `/php/server/query_json.php?file=user_notifications.json` endpoint.
+In the container, these files are located under the API directory (default: `/tmp/api/`, configurable via `NETALERTX_API` environment variable). You can access them via the `/php/server/query_json.php?file=user_notifications.json` endpoint.
 
 ### Available endpoints
 
 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 `/app/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 `/app/log` folder.
 
 ## API Endpoint: /config files
 
-To retrieve files from the `/app/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)`