feat: add NetAlertX ProxmoxVE helper scripts#1491
feat: add NetAlertX ProxmoxVE helper scripts#1491JVKeller wants to merge 9 commits intonetalertx:mainfrom
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds a Proxmox VE deployment for NetAlertX: LXC template, container installer and in-container installer, updated README and INSTALLATION_GUIDE, NGINX FastCGI env mappings, persistent storage and systemd service integration, bridge detection, update routine, and a new Python dependency. Changes
Sequence Diagram(s)sequenceDiagram
actor User
participant Proxmox as Proxmox VE (host)
participant Orchestrator as netalertx.sh (CT template)
participant Container as LXC Container
participant Installer as netalertx-install.sh
participant System as Systemd / OS services
participant Nginx as NGINX & PHP-FPM
participant App as NetAlertX
User->>Orchestrator: run template (local or mirror)
Orchestrator->>Proxmox: create LXC with metadata
Orchestrator->>Container: push installer (if local) or trigger remote install
Container->>Installer: execute installation steps
Installer->>System: apt installs, PHP setup, venv creation
Installer->>Container: clone /app, create persistent dirs, set permissions
Installer->>Nginx: deploy config (FastCGI envs) and restart
Installer->>System: create start script & systemd unit, enable service
System->>App: start NetAlertX service
Nginx->>App: proxy/frontend requests via FastCGI envs
App-->>User: service accessible (host:PORT)
Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In `@install/proxmox/install/netalertx-install.sh`:
- Around line 199-203: The chmod -R a+rwx "$INSTALL_DIR" makes the whole install
world-writable; instead restrict write access to owner/group (www-data) and
leave others read/execute only: remove the chmod -R a+rwx line and replace it
with setting file/dir modes like u=rwX,g=rwX,o=rX for the tree and make
directories setgid so new files inherit the www-data group (e.g. set directory
mode to 2775), ensure the web-writable parts referenced (front/ and the DB file
${INSTALL_DIR}/db/app.db) are owned by or writable for www-data (chgrp/chown to
www-data and ensure group write), and keep the existing chgrp and chown commands
but apply them only to the needed paths rather than the entire INSTALL_DIR.
In `@install/proxmox/INSTALLATION_GUIDE.md`:
- Around line 68-70: The fenced code block containing the example URL
("http://YOUR_SERVER_IP:YOUR_PORT") is missing a language tag which triggers
MD040; update that fenced block by adding a language identifier (e.g., use
```text) immediately after the opening backticks so the block becomes a fenced
code block with a language tag, preserving the existing content exactly.
In `@install/proxmox/proxmox-install-netalertx.sh`:
- Around line 289-298: The mkdir step creates "${INSTALL_DIR}/log" and
"${INSTALL_DIR}/api" as root so the subsequent sudo -u www-data touch calls can
fail; after creating the directories with mkdir -p, change ownership of those
directories to www-data (chown -R www-data:www-data "${INSTALL_DIR}/log"
"${INSTALL_DIR}/api") before calling sudo -u www-data touch, or alternatively
create the directories as www-data (sudo -u www-data mkdir -p ...) so that the
later touch commands succeed; ensure chown/chmod ordering is:
mkdir/mkdir-as-www-data -> chown (if needed) -> sudo -u www-data touch -> chmod.
In `@install/proxmox/README.md`:
- Around line 14-18: Update the Proxmox VE Helper Script (Recommended) command
in the README to use the canonical helper-script URL instead of the personal
fork; replace the wget URL string
"https://github.com/JVKeller/NetAlertX/raw/proxmox-baremetal-installer/install/proxmox/ct/netalertx.sh"
used in the bash -c "$(wget -qLO - <URL>)" line with the canonical URL
referenced in INSTALLATION_GUIDE.md so the primary install path points to the
official repository.
🧹 Nitpick comments (1)
install/proxmox/install/netalertx-install.sh (1)
237-246: Deduplicate NETALERTX_TMP/PORT exports.The repeated lines add noise without changing behavior.
🧹 Suggested cleanup
export NETALERTX_TMP=/app export PORT=${PORT} -export NETALERTX_TMP=/app -export PORT=${PORT} export PYTHONPATH=/app
… and fix permissions in legacy script
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
install/proxmox/proxmox-install-netalertx.sh (1)
369-369:⚠️ Potential issue | 🟠 MajorSystemd service
PORTvariable will not be expanded.The heredoc on line 369 uses
'EOF'(quoted), which prevents shell variable expansion. This means${PORT}on line 392 will be written literally as${PORT}instead of the actual port number (e.g.,20211).In contrast, the start script heredoc (line 333) uses unquoted
EOF, so${PORT}expands correctly there.🔧 Suggested fix - Remove quotes from EOF delimiter
-cat > /etc/systemd/system/netalertx.service << 'EOF' +cat > /etc/systemd/system/netalertx.service << EOF [Unit] Description=NetAlertX ServiceNote: After removing the quotes, you'll also need to escape any literal
$characters in the service file that should NOT be expanded (if any).Also applies to: 392-392
🧹 Nitpick comments (2)
install/proxmox/proxmox-install-netalertx.sh (2)
336-343: Environment variables are duplicated between start script and systemd service.The
NETALERTX_*environment variables are defined in both the generated start script (lines 336-343) and the systemd service file (lines 386-393). While this redundancy ensures the variables are set regardless of how the script is invoked, consider consolidating to a single source of truth (preferably the systemd service) to simplify maintenance.Also applies to: 386-393
345-348: Self-healing__init__.pycreation may mask packaging issues.The
__init__.pyfiles for/app/front/and/app/front/plugins/do not exist in the repository but are being created at startup. This defensive measure could hide legitimate packaging problems. These files should either be committed to the repository as part of proper package structure, or their creation should be removed if they're genuinely not needed for the application's import structure.
|
looks like I made the bunny happy. |
|
Is this using hardware install instead of docker install? |
|
I was really hoping we could do something more than a debian 13 hardware install next time. I can't get ProxMox working in a VM and my servers are all reserved for other tasks. Can you try something like this and see if it works? Docker installation makes it way easier to upgrade, manage, maintain, and even uninstall if absolutely required. This project can't support hardware installation, but if we can get it to work in a container, then we can enhance user experience and provide support. Step 1: Create the ContainerWhere: Run on Proxmox Node Shell. bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/docker.sh)"
Step 2: Install NetAlertXWhere: Run inside the new Container Console. mkdir -p /opt/netalertx/data && cd /opt/netalertx
wget -qO docker-compose.yml https://raw.githubusercontent.com/netalertx/rpi-image/refs/heads/master/root_filesystem/opt/netalertx/docker-compose.yml
docker compose up -d
Access: |
|
Yes. This will install at the hardware level outside the containers. Super easy if someone wants to work on the code base! I think it just boils down to options and what different people are used to running. Docker isn't harder to use, it just uses a different tool set that a different user might want to use, just like running in HomeAssistant. With the PVE Helper scripts line this one, all you have to do is literally type "update" in the console and it takes care of it. Also, the way it's set up, the helper script just builds the LXC container, with options for an advanced config, and then calls a new version of the 'baremetal' installer to actual populate and build the environment. That script (install/proxmox/install/netalertx-install.sh) could be ran by itself on deb/Ubuntu server directly. Btw, of you want to set up Proxmox in a VM, you can start with a vanilla Debian13 container, and install Proxmox on top of it. |
|
I’m happy to keep the Proxmox/Hardware install scripts around if the community helps support them - just note there’s no official support, and Docker is still the recommended way to install. |
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Fix all issues with AI agents
In `@install/proxmox/ct/netalertx.sh`:
- Around line 33-54: After performing the sed/eval override of build_container
(both the REPOS_URL mirror branch and the LOCAL_INSTALLER branch), immediately
re-read the function (e.g., new_func=$(declare -f build_container)) and verify
it contains the expected unique substring from your replacement (for the mirror
branch check for the ${REPOS_URL}/install/proxmox/install/${var_install}.sh
pattern or another fixed marker; for the local branch check for the pct push
"/root/install.sh" or lxc-attach ... /root/install.sh fragment); if the check
fails, log a clear error via msg_error including the attempted replacement and
exit non-zero so the script does not continue using the unmodified
build_container; use the existing symbols original_func, build_container,
REPOS_URL, and LOCAL_INSTALLER to locate and validate the change.
- Around line 103-135: The update_script() currently runs a bare git pull and an
unsuppressed pip install and then always restarts the service; fix it by making
git update deterministic and error-checked (e.g., inside update_script() use git
stash push --include-untracked or run git fetch && git reset --hard origin/main
to force a known state, or explicitly restore config/app.conf after update), run
pip install while suppressing output with the existing $STD variable (activate
venv at /opt/netalertx-env/bin/activate then pip install -r
install/proxmox/requirements.txt $STD), and add error handling: check the exit
status of the git and pip commands and if either fails call msg_error and exit
without restarting the service (do not run systemctl start netalertx.service on
failure); reference update_script, git pull, pip install,
/opt/netalertx-env/bin/activate, config/app.conf, and systemctl start/stop
netalertx.service when applying the changes.
In `@install/proxmox/install/netalertx-install.sh`:
- Around line 150-157: The PHP-FPM socket detection using PHP_FPM_SOCKET=$(find
/run/php/ -name "php*-fpm.sock" | head -n 1) can run before PHP-FPM is started
and thus leave /etc/nginx/conf.d/netalertx.conf pointing to a non-existent
socket; update the install script to perform this detection after PHP-FPM is
started (or wait/retry briefly) and add a deterministic fallback (e.g.,
unix:/run/php/php8.4-fpm.sock) when PHP_FPM_SOCKET is empty so the sed
replacement against netalertx.conf always sets a valid socket; adjust the block
that calls msg_info/msg_warn and the sed invocation accordingly to use
PHP_FPM_SOCKET or the fallback.
- Around line 66-72: The REPO_URL is used unsafely in the git clone call;
validate REPO_URL (e.g., ensure it matches a safe URL/ssh/https pattern) before
use, then call git clone with a double-dash to separate options from positional
args and remove the trailing slash on INSTALL_DIR; specifically update the git
clone invocation in the script that uses REPO_URL and INSTALL_DIR to: validate
REPO_URL, then run git clone -- "$REPO_URL" "$INSTALL_DIR" (ensure quoting), and
keep the existing rm -rf "$INSTALL_DIR" and cd "$INSTALL_DIR" logic unchanged.
- Around line 101-116: Remove the setcap call that grants network capabilities
to the Python interpreter (the BINARY_PYTHON / setcap
cap_net_raw,cap_net_admin+eip invocation) to avoid elevating every Python
process; instead rely on the existing sudo configuration or create a small
dedicated wrapper with capabilities for the specific scanner commands
(nmap/arp-scan/nbtscan/traceroute). Also remove the duplicated status message by
deleting the extra msg_ok "Installed Python Dependencies" so it only prints
once. Ensure references to BINARY_PYTHON, setcap, and msg_ok are updated
accordingly.
- Around line 234-263: Remove the duplicate export lines for NETALERTX_TMP and
PORT in the startup heredoc that writes INSTALL_DIR/start.netalertx.sh
(duplicates currently set via the heredoc content referencing NETALERTX_TMP and
PORT); also decide whether runtime values should be captured at install time —
if you want the script to retain variable references for later, change the
heredoc to a literal form (use <<'EOF' or escape ${SERVER_IP}/${PORT}) so
${SERVER_IP} and ${PORT} are not expanded at install time, and add a brief
comment in the heredoc clarifying the intended behavior.
- Around line 206-212: The sudoers heredoc currently hardcodes paths; replace
those literals with the dynamically resolved path variables used earlier (e.g.,
the variables that were set when locating binaries for nmap, arp-scan, nbtscan,
traceroute, the venv python and system python — use their exact variable names
from the script such as NMAP_BIN, ARP_SCAN_BIN, NBTSCAN_BIN, TRACEROUTE_BIN,
VENV_PYTHON, PYTHON3_BIN), ensure each variable is non-empty (or fallback to
command -v) before writing /etc/sudoers.d/netalertx, and keep the existing chmod
440 and msg_ok/msg_info calls. This guarantees the sudoers file grants sudo to
the actual resolved binary paths rather than hardcoded locations.
🧹 Nitpick comments (6)
install/proxmox/install/netalertx-install.sh (3)
174-176: Unquoted brace expansion intouchcommand.Line 175 uses brace expansion
${INSTALL_DIR}/log/{app.log,...}which works, but if any path component contained spaces, it would break. More importantly, ifsudo -u www-data touchfails (e.g., permission issue), the error is silently swallowed since there's no error checking.This is a minor robustness concern given the controlled environment.
267-300: Systemd service configuration is reasonable but consider adding security hardening directives.The service runs as
www-datawhich is good. However, for a network monitoring tool, consider adding systemd sandboxing directives to limit the blast radius (e.g.,ProtectSystem=,ProtectHome=,NoNewPrivileges=).NoNewPrivileges=truewould conflict withsetcap/sudousage, so that needs careful thought, but directives likeProtectHome=yesare safe here.
22-58: Large dependency list — consider documenting why each package is needed.This installs ~30 packages. A brief inline comment grouping them by purpose (e.g.,
# Network scanning tools,# Build tools,# Runtime) would help future maintainers understand which are essential vs. optional.Minor:
tiniis typically used as a Docker init process; it's unusual in a systemd-managed LXC container. Is it actually needed here?install/proxmox/ct/netalertx.sh (3)
65-101: Bridge detection logic is thorough with good fallbacks.The multi-method approach (ip link → sysfs → pvesh) with user prompting for multiple bridges is well thought out. The error handling for no-bridge-found is appropriate.
One minor note: line 69 concatenates two sources without deduplication by interface type —
ip -o link show type bridgecould return non-vmbrbridges (e.g.,docker0,br-*). Thegrep vmbron the sysfs path filters correctly, but theipcommand output isn't filtered. Thesort -udedup on line 72 handles exact duplicates but not irrelevant bridges.Consider filtering ip output to vmbr* bridges only
- BRIDGES=($(ip -o link show type bridge | awk -F': ' '{print $2}') $(ls /sys/class/net | grep vmbr | grep -v "vmbr0")) + BRIDGES=($(ip -o link show type bridge | awk -F': ' '{print $2}' | grep '^vmbr') $(ls /sys/class/net 2>/dev/null | grep '^vmbr' | grep -v '^vmbr0$'))
12-13: Sourcing remote code from an unpinned branch over HTTPS.
source <(curl -fsSL https://...ProxmoxVE/raw/main/misc/build.func)fetches and executes arbitrary code frommainwith no integrity verification. This is standard practice for Proxmox community scripts, but be aware that any upstream compromise or breaking change will silently propagate. Consider pinning to a commit SHA for production use.
56-57: ExportingREPO_URLwithout validation.
REPO_URLis exported and eventually consumed bygit clonein the install script. If a user setsREPO_URLto a value containing shell metacharacters, it flows through unchecked. The install script side was noted separately, but the export here is the origin point.
| INSTALL_DIR="/app" | ||
| # Default repository if not specified | ||
| REPO_URL="${REPO_URL:-https://github.com/netalertx/NetAlertX.git}" | ||
| # Ensure directory is empty | ||
| rm -rf "$INSTALL_DIR" | ||
| git clone "$REPO_URL" "$INSTALL_DIR/" --quiet | ||
| cd "$INSTALL_DIR" || exit |
There was a problem hiding this comment.
Unsanitized REPO_URL is passed directly to git clone.
If REPO_URL is set by an external caller (e.g., environment variable from the CT script), a malicious value could inject arguments into the git clone command. Use -- to separate options from the positional argument, and validate the URL format.
Proposed fix
-git clone "$REPO_URL" "$INSTALL_DIR/" --quiet
+git clone --quiet -- "$REPO_URL" "$INSTALL_DIR"Also note the trailing / on "$INSTALL_DIR/" is unnecessary and inconsistent with the rest of the script.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| INSTALL_DIR="/app" | |
| # Default repository if not specified | |
| REPO_URL="${REPO_URL:-https://github.com/netalertx/NetAlertX.git}" | |
| # Ensure directory is empty | |
| rm -rf "$INSTALL_DIR" | |
| git clone "$REPO_URL" "$INSTALL_DIR/" --quiet | |
| cd "$INSTALL_DIR" || exit | |
| INSTALL_DIR="/app" | |
| # Default repository if not specified | |
| REPO_URL="${REPO_URL:-https://github.com/netalertx/NetAlertX.git}" | |
| # Ensure directory is empty | |
| rm -rf "$INSTALL_DIR" | |
| git clone --quiet -- "$REPO_URL" "$INSTALL_DIR" | |
| cd "$INSTALL_DIR" || exit |
🤖 Prompt for AI Agents
In `@install/proxmox/install/netalertx-install.sh` around lines 66 - 72, The
REPO_URL is used unsafely in the git clone call; validate REPO_URL (e.g., ensure
it matches a safe URL/ssh/https pattern) before use, then call git clone with a
double-dash to separate options from positional args and remove the trailing
slash on INSTALL_DIR; specifically update the git clone invocation in the script
that uses REPO_URL and INSTALL_DIR to: validate REPO_URL, then run git clone --
"$REPO_URL" "$INSTALL_DIR" (ensure quoting), and keep the existing rm -rf
"$INSTALL_DIR" and cd "$INSTALL_DIR" logic unchanged.
|
FYI @DJKatastrof , @JVKeller is working on a PR here |
| # Source: https://github.com/ProxmoxVE | ||
|
|
||
| # Import main orchestrator | ||
| source <(curl -fsSL https://github.com/community-scripts/ProxmoxVE/raw/main/misc/build.func) |
There was a problem hiding this comment.
You are loading a community-scripts framework.
Therefore it is mandatory that
/ct/netalertx.sh
/install/netalertx-install.sh
are part of the community-scripts repository.
Hosting on netalertx repro will NOT work!
There was a problem hiding this comment.
The plan is to have it working in the NAX repo and then submit it to the PVE Community repo.
The script works by pulling sum sub scripts so they all stick to the same framework so it will need to link back to that repo as well.
There was a problem hiding this comment.
The read.me has instructions for an over-ride to get around the repo change for testing.
|
I have copy & paste into my community-scripts dev environment. LXC setup indicate no mayor installation errors, but netalertx.service is failing: |
|
My simple view: Split your pull request into two independant pull requests: |
…d hardcoded paths
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@install/proxmox/ct/netalertx.sh`:
- Around line 103-138: The update_script function currently hardcodes the branch
with git reset --hard origin/main and uses plain exit on the missing /app path;
change the update logic to determine the branch dynamically (e.g., detect the
current branch via git rev-parse --abbrev-ref HEAD or read a configurable
default like REPO_BRANCH/REPO_URL) and use that branch name in the git
fetch/reset commands instead of origin/main, and replace the bare exit after the
"No ${APP} Installation Found!" error with exit 1 to return a failure status.
In `@install/proxmox/install/netalertx-install.sh`:
- Around line 206-212: The current here-doc writing /etc/sudoers.d/netalertx
uses the ${BINARY_*} variables directly and can produce an invalid sudoers line
if any are empty; change the logic in netalertx-install.sh to build the
allowed-command list dynamically by collecting non-empty BINARY_NMAP,
BINARY_ARPSCAN, BINARY_NBTSCAN, BINARY_TRACEROUTE and the fixed entries
(/opt/netalertx-env/bin/python, /usr/bin/python3) into an array/string, join
with ", " and only create the sudoers content if the resulting list is
non-empty; before replacing /etc/sudoers.d/netalertx run visudo -cf on a
temporary file to validate syntax and abort (with msg_info/msg_ok) if visudo
reports an error, and only then atomically write the file and set chmod 440.
🧹 Nitpick comments (2)
install/proxmox/install/netalertx-install.sh (2)
234-263: Unquoted heredoc expands${SERVER_IP}and${PORT}at install time.Since
<<EOF(not<<'EOF') is used, these values are baked into the startup script. If the container's IP changes (e.g., DHCP), the banner message will be stale. The environment variablePORTis also expanded, so changing it later requires editing the script. This is likely intentional for a static LXC setup, but worth a comment in the script for maintainers.
267-299: Environment variables are set both in the systemd unit and instart.netalertx.sh.The
Environment=directives in the service file (lines 285–291) duplicate the exports in the startup script (lines 239–246). The startup script's exports will take precedence at runtime, making the systemd entries effectively dead config. Consider keeping them in only one place to avoid drift.
|
This command will run the installer script from my fork which I just updated from the main branch and tested. If you don't want to fork to test, use mine, or update these lines as needed. |
4 participants
@jokob-sk @ingoratsdorf @adamoutler
This PR introduces the NetAlertX helper scripts to provide a streamlined, automated installation of the NetAlertX network security monitoring tool on Proxmox VE.
📝 Description
NetAlertX is a comprehensive WiFi / LAN intruder detector and network monitor. These scripts automate the creation of a Debian-based LXC container, the installation of all necessary runtimes (PHP 8.4, Python 3.13+), and the configuration of environment variables to ensure a "plug-and-play" experience.
✨ Features
setup_phphelper) and NGINX./opt/netalertx-envwith automated dependency management.setcapon key binaries (nmap,arp-scan,python3) to allow network scanning without requiring full root privileges.PYTHONPATH, creates missing package indicators (__init__.py), and ensures the correct working directory.update_script()in the CT script, allowing users to pull latest releases and rebuild dependencies via the helper menu.🛠️ Compliance & Standards
/ctand/installtemplates.source /dev/stdin <<<"$FUNCTIONS_FILE_PATH").$STD.🚀 How to Test
Summary by CodeRabbit
Documentation
New Features
Chores