Feat: Enterprise-Grade Security Hardening and Build Overhaul

[adamoutler]

This commit fundamentally refactors the NetAlertX Docker build process, elevating it from a basic, minimal, functional setup to an enterprise-grade, security-first appliance. The primary goal is to drastically reduce the attack surface and implement a defense-in-depth strategy, making the container suitable for deployment in security-sensitive environments.

This is achieved by introducing a new, heavily hardened, multi-stage Dockerfile based on Alpine Linux, defining a secure filesystem layout, and clearly delineating it from a legacy Dockerfile.debian intended only for development and testing.

---

1. The New Hardened Dockerfile (Alpine)

The main Dockerfile now implements a three-stage build process to create a minimal, locked-down, and production-ready image.

Stage 1: builder

• Purpose: Isolates build-time dependencies. It installs tools required to compile Python packages (like gcc, musl-dev) and creates a Python virtual environment (venv).
• Benefit: These tools are not included in the final image, preventing potential misuse and keeping the production environment clean and minimal.

Stage 2: runner

• Purpose: Creates a minimal, operational base for NetAlertX. It installs only the necessary runtime packages (nmap, php, python3, etc.) and copies the application code and the venv from the builder stage.
• Dev/Prod Parity: This stage serves as the base for the Dev Container. This is a critical improvement that ensures the development environment mirrors the production runtime, minimizing environment-specific bugs.

Stage 3: hardened (The Production Image)

This is the final stage and the core of the security overhaul. It takes the runner image and applies a comprehensive set of security restrictions based on the principle of least privilege.

Key Hardening Measures:

• Immutable Filesystem: Application source code (/app/server, /app/front) and service configurations are made read-only. This prevents any modification of the application code at runtime.
• Strict User and Privilege Separation:
  • netalertx user (UID 20211): The application now runs as this unprivileged user.
  • readonly user (UID 20212): A special user with no shell or write permissions owns the read-only application files. This is an "ownership-as-a-lock" pattern; even if an attacker gains control of the readonly user, they cannot modify the files it owns.
  • Root is Disabled: The final image runs as netalertx, and root access is effectively removed.
• Reduced Attack Surface:
  • Package Manager Removal: apk is deleted from the final image, preventing the installation of new packages.
  • Removal of Sensitive Files: sudo, /etc/sudoers, /etc/shadow, and /etc/gshadow are deleted.
  • System Directory Cleanup: Unnecessary directories like /home, /root, /media, and /mnt are removed.
  • Minimal User/Group Profiles: /etc/passwd and /etc/group are stripped to contain only the netalertx and readonly users/groups.
• Linux Capabilities, Not Root:
  • Instead of running network scanning tools with root privileges, we now grant fine-grained Linux capabilities directly to the binaries (nmap, arp-scan, nbtscan).
  • setcap cap_net_raw,cap_net_admin+eip allows these tools to perform network scans without needing full root access.
• Secure Defaults:
  • UMASK=0077: Ensures that any files created at runtime (in the writable directories) are private by default, accessible only by the netalertx user.
  • sudo Stub: sudo is replaced with a harmless shell script stub. Any attempt by compromised code to call sudo will fail safely.
• Container Healthcheck:
  • A HEALTHCHECK instruction has been added. It periodically runs a script to verify that the application is running correctly, allowing container orchestrators to automatically restart the container if it becomes unhealthy.

---

2. Dockerfile.debian: A Compatibility and Testing Image

• Explicit Purpose: A new Dockerfile.debian is provided for backward compatibility and testing purposes only.
• Clear Warnings: The file begins with a prominent warning block that explicitly discourages its use in production and details the extensive security features present in the default Alpine image that are missing from the Debian version. This is a deliberate choice to inform users of the risks associated with running an unhardened image.
• Feature Contrast: The comments in Dockerfile.debian serve as a checklist of modern security practices, highlighting the value of the hardened Alpine image by comparison.

---

3. New Secure Filesystem Layout

A new, secure "Overlay" filesystem structure has been implemented to enforce a strict separation between immutable code and mutable runtime data. This is a cornerstone of the hardening strategy.

• /app - Application Directory:

  • Read-Only Code: back, front, and server directories contain the application source code and are set to read-only, owned by the readonly user.
  • Writable Data: config, db, log, and api are the only writable directories within /app. They are owned by the netalertx user with 700 permissions, ensuring that runtime data, logs, and configuration are isolated and cannot be accessed by other users. During normal operations, a ramdisk or a mount is required for each of these folders as the container is expected to be read-only.

• /services - Service Management:

  • Contains all scripts and configurations for nginx, php-fpm, and crond. This directory is mostly read-only in the final image with the exception of the /services/run folder which contains lock files and tmp functions on a ramdisk.
  • Runtime data for these services (e.g., PID files, temporary sockets) is stored in designated writable directories like /services/run.

• /opt/venv - Python Virtual Environment:

  • The Python venv is entirely read-only, preventing any modification or installation of new packages at runtime.

This filesystem design ensures the integrity of the application by making the code and configuration immutable while providing secure, isolated locations for necessary runtime data.

---

Summary of Impact

This is a transformative change for NetAlertX, moving it from a project that "just works" in Docker to one that adheres to enterprise-grade security standards.

• For Users: Deployments are now secure by default. The production image is a locked-down appliance, significantly reducing the risk of compromise. Error messages are boldly shown at startup in docker logs. Startup times are quicker. The system is more reliable.
• For Developers: The development environment is now consistent with production, leading to higher-quality, more reliable code. The only real differences between the dev and production environments are read-write access and additional debug tools.
• For the Project: This PR demonstrates a strong commitment to security, which is essential for a network monitoring tool.

Future enhancements

• Additional checks in /services/scripts/check- . Currently identified weak points are annotated with TODO.
• Image size reduction - the additional layers introduced in the hardening branch cause significant image size bloat. While the container startup speed is faster, the download speed is slightly slower due to size increase. This can be remedied using various common techniques.
• Since the "hardware install" methods download the Git repository rather than build from source, they must be tuned afterward. I recommend migrating these to documentation ASAP as there is no possible way to keep them in-sync.

Summary by CodeRabbit

• New Features

  • Hardened multi-stage container with monitored entrypoint, healthcheck, devcontainer target, improved debug/port support and curated VS Code extensions.

• Bug Fixes

  • More robust startup with mount, permission and capability checks; clearer failure and restart behavior.

• Documentation

  • Added production-filesystem guide and host-mode devcontainer ports troubleshooting.

• Chores

  • Removed legacy speedtest CLI, updated runtime dependencies and reorganized container/init helper scripts.

[adamoutler]

done

[adamoutler]

This documentation may be inaccurate. It's best to leave it. for review by maintainer.

[coderabbitai]

Actionable comments posted: 5

🧹 Nitpick comments (2)

install/production-filesystem/services/scripts/check-first-run-config.sh (1)

5-5: Quote the variable in the file test to handle paths safely.

If ${NETALERTX_CONFIG} ever contains spaces or special characters, the unquoted test will fail. Use quotes for defensive robustness:

-if [ ! -f ${NETALERTX_CONFIG}/app.conf ]; then
+if [ ! -f "${NETALERTX_CONFIG}/app.conf" ]; then

Dockerfile (1)

191-191: Use exec in sudo stub for efficiency and clarity.

Line 191 creates a sudo pass-through stub, but omits exec, causing the shell to remain in memory unnecessarily. While functional, it's suboptimal.

Apply this diff to use exec:

-    echo -ne '#!/bin/sh\n"$@"\n' > /usr/bin/sudo && chmod +x /usr/bin/sudo
+    echo -ne '#!/bin/sh\nexec "$@"\n' > /usr/bin/sudo && chmod +x /usr/bin/sudo

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8eab7ee and 5ed46da.

📒 Files selected for processing (3)

• Dockerfile (1 hunks)
• install/production-filesystem/services/scripts/check-first-run-config.sh (1 hunks)
• install/production-filesystem/services/scripts/update_vendors.sh (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-09-20T03:01:19.912Z

Learnt from: adamoutler
PR: jokob-sk/NetAlertX#1184
File: .devcontainer/Dockerfile:18-19
Timestamp: 2025-09-20T03:01:19.912Z
Learning: In the NetAlertX repository, .devcontainer/Dockerfile is auto-generated and should not be reviewed directly. Review comments about dependencies and build steps should be directed at the root Dockerfile where the actual source commands are located.

Applied to files:

• Dockerfile

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: docker_dev

🔇 Additional comments (1)

Dockerfile (1)

145-145: Verify readlink robustness for Python binary resolution.

Line 145 uses $(readlink -f ${VIRTUAL_ENV_BIN}/python) to resolve the Python binary before applying capabilities. If the symlink does not resolve (e.g., binary not yet created, wrong name), setcap will silently fail and capabilities won't be set, causing runtime failures when scapy operations execute.

Confirm via inspection or testing:

• Does ${VIRTUAL_ENV_BIN}/python exist and resolve correctly after the venv is copied?
• Should you add a check or fall back to an explicit path like ${VIRTUAL_ENV_BIN}/python3 if readlink fails?

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

install/production-filesystem/services/scripts/check-first-run-config.sh (1)

5-5: Minor: Quote variable for consistency.

Line 5 uses an unquoted variable ${NETALERTX_CONFIG} in the condition, while lines 6 and 10 properly quote it. For robustness against edge cases (e.g., paths with spaces), consider quoting consistently:

-if [ ! -f ${NETALERTX_CONFIG}/app.conf ]; then
+if [ ! -f "${NETALERTX_CONFIG}/app.conf" ]; then

This is a minor consistency nit and unlikely to cause issues in practice given typical env-var usage.

install/production-filesystem/services/scripts/update_vendors.sh (1)

13-16: Optional: Update stale comment for clarity.

The comment mentions updating /usr/share/arp-scan, but the script actually writes to /services/run/tmp/ieee-oui.txt. Consider updating this comment to reflect the current output path and align with the production filesystem refactor.

 # ----------------------------------------------------------------------
 #  Main directories to update:
-#    /usr/share/arp-scan
+#  Output path: /services/run/tmp/ieee-oui.txt
 # ----------------------------------------------------------------------

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5ed46da and 6f2e556.

📒 Files selected for processing (2)

• install/production-filesystem/services/scripts/check-first-run-config.sh (1 hunks)
• install/production-filesystem/services/scripts/update_vendors.sh (1 hunks)

🔇 Additional comments (2)

install/production-filesystem/services/scripts/check-first-run-config.sh (1)

1-26: Excellent work addressing all prior issues—script is production-ready.

The script properly resolves all three previous critical concerns:

• Error handling for mkdir and cp with early exit on failure (lines 6–13) ✓
• Variable expansion in heredoc by using unquoted <<EOF (line 17) ✓
• User-facing message displays the actual path via variable interpolation (line 19) ✓

Color handling and stderr redirection are clean, and error messages are helpful. The control flow is straightforward and safe.

install/production-filesystem/services/scripts/update_vendors.sh (1)

1-44: Excellent hardening work—script is robust and production-ready.

All prior issues have been properly addressed: strict error handling is in place, the download-process-validate-replace pipeline is bulletproof, cleanup is reliable, and exit codes are correct. The combination of set -euo pipefail, if ! error trapping, validation thresholds, and atomic file replacement make this a solid data-update script.