feat: add NetAlertX ProxmoxVE helper scripts

install/proxmox/INSTALLATION_GUIDE.md

@@ -0,0 +1,160 @@
+# NetAlertX Installation Guide for Proxmox VE
+
+## Quick Start (ProxmoxVE LXC Container)
+
+To create a NetAlertX LXC container on Proxmox VE, run this command on your Proxmox host:
+
+```bash
+bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/netalertx.sh)"
+```
+
+This will:
+- Create a Debian 13 LXC container
+- Install all dependencies automatically
+- Configure NetAlertX with NGINX on port 20211
+- Start the service automatically
+
+### Update Existing Installation
+
+To update an existing NetAlertX container:
+- Type ```update``` in the NetAlertX LXC Console
+- Or run this command on your Proxmox host:
+```bash
+bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/netalertx.sh)" -s update
+```
+
+---
+
+## Installation Process Overview
+
+### 1. **System Preparation**
+- Updates system packages
+
+### 2. **Dependency Installation**
+- Installs NGINX web server
+- Installs Python 3 and development tools
+- Installs network scanning tools (nmap, arp-scan, fping, etc.)
+- Installs system utilities (sqlite3, dnsutils, avahi-daemon, etc.)
+
+### 3. **Application Setup**
+- Clones NetAlertX repository to `/app`
+- Creates Python virtual environment at `/opt/netalertx-env`
+- Installs Python dependencies from requirements.txt
+- Configures NGINX with default port 20211
+
+### 4. **File Structure Creation**
+- Creates persistent directories for `/app/log` and `/app/api`
+- Creates log files and plugin directories
+- Copies initial database and configuration files
+- Sets secure file permissions (www-data user/group)
+- Configures systemd RuntimeDirectory (`/run/netalertx`) for volatile service files
+
+### 5. **Service Configuration**
+- Creates startup script at `/app/start.netalertx.sh`
+- Installs systemd service (`netalertx.service`)
+- Enables auto-start on boot
+- Starts NetAlertX and NGINX services
+
+### 6. **Hardware Vendor Database**
+- Updates IEEE OUI database for MAC address vendor identification (if not present)
+
+---
+
+## Post-Installation
+
+### Accessing NetAlertX
+
+After successful installation, access the web interface at:
+
+```
+http://YOUR_SERVER_IP:YOUR_PORT
+```
+
+**Default port**: 20211
+
+To find your server IP:
+```bash
+ip -4 route get 1.1.1.1 | awk '{for(i=1;i<=NF;i++) if ($i=="src") {print $(i+1); exit}}'
+```
+
+### Service Management
+
+```bash
+# Check service status
+systemctl status netalertx.service
+
+# View real-time logs
+journalctl -u netalertx.service -f
+
+# Restart service
+systemctl restart netalertx.service
+
+# Stop service
+systemctl stop netalertx.service
+```
+
+---
+
+## Important File Locations
+
+| Component | Location |
+|-----------|----------|
+| Installation Directory | `/app` |
+| Configuration File | `/app/config/app.conf` |
+| Database File | `/app/db/app.db` |
+| NGINX Configuration | `/etc/nginx/conf.d/netalertx.conf` |
+| Web UI (symlink) | `/var/www/html/netalertx` → `/app/front` |
+| Python Virtual Env | `/opt/netalertx-env` |
+| Systemd Service | `/etc/systemd/system/netalertx.service` |
+| Startup Script | `/app/start.netalertx.sh` |
+| Application Logs | `/app/log/` (persistent) |
+| API Files | `/app/api/` (persistent) |
+| Service Runtime | `/run/netalertx/` (tmpfs, systemd-managed) |
+
+### Storage Strategy (Hybrid Approach)
+
+**Persistent Storage** (survives reboots):
+- `/app/log/app.log` - Main application log
+- `/app/log/execution_queue.log` - Task execution log
+- `/app/log/app_front.log` - Frontend log
+- `/app/log/app.php_errors.log` - PHP error log
+- `/app/log/stderr.log` - Standard error output
+- `/app/log/stdout.log` - Standard output
+- `/app/log/db_is_locked.log` - Database lock log
+- `/app/api/user_notifications.json` - User notification data
+
+**Volatile Storage** (tmpfs, cleared on reboot):
+- `/run/netalertx/` - Systemd-managed runtime directory for service temporary files
+
+Systemd service logs are always available via: `journalctl -u netalertx.service`
+
+---
+
+## Environment Variables
+
+The installation script supports the following environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NETALERTX_ASSUME_YES` | Skip all interactive prompts | (not set) |
+| `ASSUME_YES` | Alternative to NETALERTX_ASSUME_YES | (not set) |
+| `PORT` | HTTP port for web interface | 20211 |
+| `NETALERTX_FORCE` | Force installation without prompts | (not set) |
+
+---
+
+## Security Considerations
+
+- **Runtime directory**: Systemd manages `/run/netalertx/` as tmpfs with `noexec,nosuid,nodev` flags
+- **File permissions**: Application files restricted to `www-data` user/group only (mode 0750)
+- **Service isolation**: Runs as unprivileged `www-data` user
+- **Automatic restart**: Service configured to restart on failure
+- **Persistent logs**: Application logs survive reboots for debugging and audit trails
+
+---
+
+## Additional Resources
+
+- **GitHub Repository**: https://github.com/netalertx/NetAlertX
+- **Issue Tracker**: https://github.com/netalertx/NetAlertX/issues
+- **Documentation**: https://docs.netalertx.com

install/proxmox/README.md

@@ -11,9 +11,16 @@ An  installer script for deploying NetAlertX on Proxmox VE (Debian-based) system
 
 ### Installation
 
-## Download and run the installer
+#### Proxmox VE Helper Script (Recommended)
+This is the easiest way to deploy NetAlertX on Proxmox. Run this command on your Proxmox host:
 ```bash
-wget https://raw.githubusercontent.com/jokob-sk/NetAlertX/refs/heads/main/install/proxmox/proxmox-install-netalertx.sh -O proxmox-install-netalertx.sh && chmod +x proxmox-install-netalertx.sh && ./proxmox-install-netalertx.sh
+bash -c "$(wget -qLO - https://github.com/netalertx/NetAlertX/raw/main/install/proxmox/ct/netalertx.sh)"
+```
+
+#### Standalone Script (Inside existing LXC/VM)
+Download and run the installer inside a fresh Debian/Ubuntu system:
+```bash
+wget https://raw.githubusercontent.com/netalertx/NetAlertX/main/install/proxmox/proxmox-install-netalertx.sh -O proxmox-install-netalertx.sh && chmod +x proxmox-install-netalertx.sh && ./proxmox-install-netalertx.sh
 ```
 
 ## 📋 What This Installer Does

install/proxmox/ct/netalertx.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+
+# Copyright (c) 2021-2026 community-scripts ORG
+# Author: JVKeller
+
+# License: GPL 3.0 | NetAlertX | https://github.com/netalertx/NetAlertX/blob/main/LICENSE.txt
+# Source: https://github.com/netalertx/NetAlertX
+
+# License: MIT | ProxmoxVE | https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE
+# Source: https://github.com/ProxmoxVE
+
+# Import main orchestrator
+source <(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/build.func)
+
+# Application Configuration
+APP="NetAlertX"
+var_tags="network;monitoring;security"
+var_cpu="2"
+var_ram="2048"
+var_disk="10"
+# Container Type & OS
+var_os="debian"
+var_version="13"
+var_unprivileged="1"  
+# Standard initialization
+header_info "$APP"
+variables
+color
+catch_errors
+
+# Support running from a mirror/fork
+if [[ -n "${REPOS_URL}" ]]; then
+  # Surgical override of build_container
+  # 1. Inject environment variables into the bash -c command
+  # 2. Redirect the official Proxmox installer URL to our fork/branch
+  export_header="export REPOS_URL='${REPOS_URL}'; export REPO_URL='${REPO_URL:-https://github.com/netalertx/NetAlertX.git}'; export REPO_BRANCH='${REPO_BRANCH:-main}';"
+  source <(declare -f build_container | \
+    sed "s|bash -c \"|bash -c \"${export_header} |g" | \
+    sed "s|https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/install/\${var_install}.sh|${REPOS_URL}/install/proxmox/install/\${var_install}.sh|g")
+fi
+
+# Define local installer path for testing
+LOCAL_INSTALLER="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../../install/${NSAPP:-netalertx}-install.sh"
+
+# Override build_container to use local install script if available
+if [[ -f "$LOCAL_INSTALLER" ]]; then
+  msg_info "Using local installer from $LOCAL_INSTALLER"
+  export_header="export REPOS_URL=${REPOS_URL}; export REPO_URL=${REPO_URL}; export REPO_BRANCH=${REPO_BRANCH};"
+  source <(declare -f build_container | sed "s|lxc-attach.*install/\${var_install}.sh.*|${export_header} pct push \"\$CTID\" \"$LOCAL_INSTALLER\" /root/install.sh \&\& lxc-attach -n \"\$CTID\" -- bash /root/install.sh|g")
+fi
+
+# Export variables to ensure they're passed to the installation script
+export NSAPP APP var_os var_version var_cpu var_ram var_disk var_unprivileged PORT VERBOSE REPO_URL REPO_BRANCH REPOS_URL
+
+# Support verbose logging
+if [[ "${VERBOSE:-no}" == "yes" ]]; then
+  set -x
+  STD=""
+fi
+
+# Automatically detect bridge if vmbr0 is missing
+if ! ip link show vmbr0 >/dev/null 2>&1 || [[ "$(cat /sys/class/net/vmbr0/bridge/bridge_id 2>/dev/null)" == "" ]]; then
+  # Get List of Bridges using multiple methods
+  # shellcheck disable=SC2207,SC2010  # Working pattern for bridge detection
+  # We include vmbr0 in the search now to avoid errors if it exists but failed the strict check
+  BRIDGES=($(ip -o link show type bridge | awk -F': ' '{print $2}') $(ls /sys/class/net 2>/dev/null | grep vmbr || true))
+  # Remove duplicates
+  # shellcheck disable=SC2207  # Working pattern for deduplication
+  BRIDGES=($(echo "${BRIDGES[@]}" | tr ' ' '\n' | sort -u | tr '\n' ' '))
+
+  if [ ${#BRIDGES[@]} -eq 0 ]; then
+    # Fallback to pvesh if available
+    if command -v pvesh >/dev/null 2>&1; then
+      # shellcheck disable=SC2207,SC2046  # Working pattern for pvesh output
+      BRIDGES=($(pvesh get /nodes/$(hostname)/network --type bridge --output-format json | grep -oP '"iface":"\K[^"]+'))
+    fi
+  fi
+
+  if [ ${#BRIDGES[@]} -eq 0 ]; then
+    msg_error "No network bridges (vmbr) detected. Please create a Linux Bridge in Proxmox first."
+    exit 1
+  elif [ ${#BRIDGES[@]} -eq 1 ]; then
+    export var_bridge="${BRIDGES[0]}"
+    msg_info "Using detected bridge: ${var_bridge}"
+  else
+    # Multiple bridges found, let the user pick
+    BRIDGE_MENU=()
+    for b in "${BRIDGES[@]}"; do
+      BRIDGE_MENU+=("$b" "Network Bridge")
+    done
+    # shellcheck disable=SC2155  # Standard whiptail pattern
+    export var_bridge=$(whiptail --title "Select Network Bridge" --menu "vmbr0 not found. Please select a valid bridge:" 15 60 5 "${BRIDGE_MENU[@]}" 3>&1 1>&2 2>&3)
+    if [ -z "$var_bridge" ]; then
+      msg_error "No bridge selected. Aborting."
+      exit 1
+    fi
+  fi
+fi
+
+function update_script() {
+  header_info
+  check_container_storage
+  check_container_resources
+
+  if [[ ! -d /app ]]; then
+    msg_error "No ${APP} Installation Found!"
+    exit 1
+  fi
+
+  msg_info "Stopping ${APP} Service"
+  systemctl stop netalertx.service
+  msg_ok "Stopped ${APP} Service"
+
+  msg_info "Updating ${APP}"
+  cd /app || exit 1
+  # Get current branch (default to main if detection fails)
+  BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
+
+  # Ensure clean state before pulling from the detected branch
+  git fetch origin "${BRANCH}" || exit 1
+  git reset --hard "origin/${BRANCH}" || exit 1
+  msg_ok "Updated ${APP} (Branch: ${BRANCH})"
+
+  msg_info "Updating Python Dependencies"
+  # shellcheck disable=SC1091  # venv activation script
+  source /opt/netalertx-env/bin/activate
+  # Suppress pip output unless verbose
+  $STD pip install -r install/proxmox/requirements.txt || exit 1
+  deactivate
+  msg_ok "Updated Python Dependencies"
+
+  msg_info "Applying System Optimizations"
+  mkdir -p /etc/sysctl.d
+  cat <<EOF > /etc/sysctl.d/99-arp-fix.conf
+net.ipv4.conf.all.arp_ignore = 1
+net.ipv4.conf.all.arp_announce = 2
+net.ipv4.conf.default.arp_ignore = 1
+net.ipv4.conf.default.arp_announce = 2
+EOF
+  sysctl -p /etc/sysctl.d/99-arp-fix.conf 2>/dev/null || true
+  msg_ok "System optimizations applied"
+
+  msg_info "Starting ${APP} Service"
+  systemctl start netalertx.service
+  msg_ok "Started ${APP} Service"
+
+  msg_ok "Update Complete"
+  exit
+}
+
+# Start the container creation workflow
+start
+
+# Build the container with selected configuration
+build_container
+
+# Set container description/notes in Proxmox UI
+description
+
+# Display success message
+msg_ok "Completed successfully!\n"
+
+echo -e "${CREATING}${GN}${APP} setup has been successfully initialized!${CL}"
+echo -e "${INFO}${YW} Access it using the following URL:${CL}"
+echo -e "${TAB}${GATEWAY}${BGN}http://${IP}:${PORT:-20211}${CL}"
+echo -e "${INFO}${YW} Service Management:${CL}"
+echo -e "${TAB}systemctl status netalertx.service${CL}"