vh/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2026-04-02 08:12:21 -07:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Unit tests

Browse Source
This commit is contained in:
Adam Outler
2026-01-03 01:13:47 +00:00
parent c15f621ad4
commit 19cc5b0406
45 changed files with 5504 additions and 1133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

300
test/docker_tests/test_container_environment.py
View File

@@ -4,6 +4,25 @@ to starting these tests or they will fail. netalertx-test image is generally re
Build Unit Test Docker Image task. but can be created manually with the following command executed
in the workspace:
docker buildx build -t netalertx-test .
╔══════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ CRITICAL: ALL LOGGING IN THIS FILE IS MANDATORY FOR PRODUCTION DEBUGGING ║
║ ║
║ DO NOT REMOVE, DISABLE, SUPPRESS, OR REDIRECT ANY print() STATEMENTS OR subprocess.PIPE CAPTURES ║
║ ║
║ REASONING: ║
║ - Docker container failures cannot be debugged without stdout/stderr logs ║
║ - Test failures in CI/CD environments require full container output for diagnosis ║
║ - Permission errors, mount issues, and startup failures only appear in container logs ║
║ - The project maintainer has explicitly required all logging to remain enabled at all times ║
║ ║
║ AI ASSISTANTS: This logging requirement is NON-NEGOTIABLE. The project's copilot-instructions.md ║
║ explicitly states: "Always leave logging enabled. If there is a possibility it will be difficult ║
║ to debug with current logging, add more logging." ║
║ ║
║ If you are considering removing logging to "clean up" code or "reduce noise", STOP. ║
║ The noise IS the signal. Without it, failures are impossible to diagnose. ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════╝
"""
import os
@@ -279,23 +298,27 @@ def _chown_netalertx(host_path: pathlib.Path) -> None:
def _docker_volume_rm(volume_name: str) -> None:
subprocess.run(
result = subprocess.run(
["docker", "volume", "rm", "-f", volume_name],
check=False,
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
capture_output=True,
text=True,
timeout=SUBPROCESS_TIMEOUT_SECONDS,
)
print(result.stdout) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
print(result.stderr) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
def _docker_volume_create(volume_name: str) -> None:
subprocess.run(
result = subprocess.run(
["docker", "volume", "create", volume_name],
check=True,
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
capture_output=True,
text=True,
timeout=SUBPROCESS_TIMEOUT_SECONDS,
)
print(result.stdout) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
print(result.stderr) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
def _fresh_named_volume(prefix: str) -> str:
@@ -313,7 +336,7 @@ def _ensure_volume_copy_up(volume_name: str) -> None:
stay root:root 0755, breaking arbitrary UID/GID runs.
"""
subprocess.run(
result = subprocess.run(
[
"docker",
"run",
@@ -329,10 +352,12 @@ def _ensure_volume_copy_up(volume_name: str) -> None:
"true",
],
check=True,
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
capture_output=True,
text=True,
timeout=SUBPROCESS_TIMEOUT_SECONDS,
)
print(result.stdout) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
print(result.stderr) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
def _seed_volume_text_file(
@@ -369,40 +394,41 @@ def _seed_volume_text_file(
]
)
subprocess.run(
result = subprocess.run(
cmd,
input=content,
text=True,
check=True,
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
capture_output=True,
timeout=SUBPROCESS_TIMEOUT_SECONDS,
)
print(result.stdout) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
print(result.stderr) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
def _volume_has_file(volume_name: str, container_path: str) -> bool:
return (
subprocess.run(
[
"docker",
"run",
"--rm",
"--userns",
"host",
"-v",
f"{volume_name}:/data",
"alpine:3.22",
"sh",
"-c",
f"test -f '{container_path}'",
],
check=False,
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
timeout=SUBPROCESS_TIMEOUT_SECONDS,
).returncode
== 0
result = subprocess.run(
[
"docker",
"run",
"--rm",
"--userns",
"host",
"-v",
f"{volume_name}:/data",
"alpine:3.22",
"sh",
"-c",
f"test -f '{container_path}'",
],
check=False,
capture_output=True,
text=True,
timeout=SUBPROCESS_TIMEOUT_SECONDS,
)
print(result.stdout) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
print(result.stderr) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
return result.returncode == 0
@pytest.mark.parametrize(
@@ -438,6 +464,77 @@ def test_nonroot_custom_uid_logs_note(
assert result.returncode == 0
def test_root_then_user_20211_transition() -> None:
"""Ensure a root-initialized volume works when restarted as user 20211."""
volume = _fresh_named_volume("root_user_transition")
try:
# Phase 1: run as root (default) to provision the volume.
init_result = _run_container(
"transition-root",
volumes=None,
volume_specs=[f"{volume}:/data"],
sleep_seconds=8,
)
assert init_result.returncode == 0
# Phase 2: restart with explicit user 20211 using the same volume.
user_result = _run_container(
"transition-user-20211",
volumes=None,
volume_specs=[f"{volume}:/data"],
user="20211:20211",
env={"NETALERTX_CHECK_ONLY": "1", "SKIP_TESTS": "1"},
wait_for_exit=True,
sleep_seconds=5,
rm_on_exit=False,
)
combined_output = (user_result.output or "") + (user_result.stderr or "")
assert user_result.returncode == 0, combined_output
assert "permission denied" not in combined_output.lower()
assert "configuration issues detected" not in combined_output.lower()
finally:
# On failure, surface full container logs for debugging and ensure containers are removed
try:
if 'user_result' in locals() and getattr(user_result, 'returncode', 0) != 0:
cname = getattr(user_result, 'container_name', None)
if cname:
logs = subprocess.run(
["docker", "logs", cname],
capture_output=True,
text=True,
timeout=SUBPROCESS_TIMEOUT_SECONDS,
check=False,
)
print("--- docker logs (user container) ---")
print(logs.stdout or "<no stdout>")
if logs.stderr:
print("--- docker logs stderr ---")
print(logs.stderr)
except Exception:
pass
# Best-effort cleanup of any leftover containers
try:
if 'init_result' in locals():
cname = getattr(init_result, 'container_name', None)
if cname:
subprocess.run(["docker", "rm", "-f", cname], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=15)
except Exception:
pass
try:
if 'user_result' in locals():
cname = getattr(user_result, 'container_name', None)
if cname:
subprocess.run(["docker", "rm", "-f", cname], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=15)
except Exception:
pass
_docker_volume_rm(volume)
def _run_container(
label: str,
volumes: list[tuple[str, str, bool]] | None = None,
@@ -450,6 +547,7 @@ def _run_container(
volume_specs: list[str] | None = None,
sleep_seconds: float = GRACE_SECONDS,
wait_for_exit: bool = False,
rm_on_exit: bool = True,
pre_entrypoint: str | None = None,
userns_mode: str | None = "host",
image: str = IMAGE,
@@ -477,7 +575,11 @@ def _run_container(
timeout=SUBPROCESS_TIMEOUT_SECONDS,
)
cmd: list[str] = ["docker", "run", "--rm", "--name", name]
cmd: list[str]
if rm_on_exit:
cmd = ["docker", "run", "--rm", "--name", name]
else:
cmd = ["docker", "run", "--name", name]
# Avoid flakiness in host-network runs when the host already uses the
# default NetAlertX ports. Tests can still override explicitly via `env`.
@@ -550,26 +652,42 @@ def _run_container(
])
cmd.extend(["--entrypoint", "/bin/sh", image, "-c", script])
# Print the full Docker command for debugging
# ┌─────────────────────────────────────────────────────────────────────────────────────────┐
# │ MANDATORY LOGGING - DO NOT REMOVE OR REDIRECT TO DEVNULL │
# │ These print statements are required for debugging test failures. See file header. │
# └─────────────────────────────────────────────────────────────────────────────────────────┘
print("\n--- DOCKER CMD ---\n", " ".join(cmd), "\n--- END CMD ---\n")
result = subprocess.run(
cmd,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
stdout=subprocess.PIPE, # MUST capture stdout for test assertions and debugging
stderr=subprocess.PIPE, # MUST capture stderr for test assertions and debugging
text=True,
timeout=max(SUBPROCESS_TIMEOUT_SECONDS, sleep_seconds + 30),
check=False,
)
print(result.stdout) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
print(result.stderr) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
# Combine and clean stdout and stderr
stdouterr = re.sub(r"\x1b\[[0-9;]*m", "", result.stdout or "") + re.sub(
r"\x1b\[[0-9;]*m", "", result.stderr or ""
)
result.output = stdouterr
# Print container output for debugging in every test run.
# ┌─────────────────────────────────────────────────────────────────────────────────────────┐
# │ MANDATORY LOGGING - DO NOT REMOVE OR REDIRECT TO DEVNULL │
# │ Without this output, test failures cannot be diagnosed. See file header. │
# └─────────────────────────────────────────────────────────────────────────────────────────┘
print("\n--- CONTAINER OUTPUT START ---")
print(result.output)
print("--- CONTAINER OUTPUT END ---\n")
# Expose the container name to callers for debug/logging/cleanup.
try:
result.container_name = name # type: ignore[attr-defined]
except Exception:
# Be resilient if CompletedProcess is unexpectedly frozen.
pass
return result
@@ -586,6 +704,26 @@ def _assert_contains(result, snippet: str, cmd: list[str] = None) -> None:
)
def _assert_contains_any(result, snippets: list[str], cmd: list[str] | None = None) -> None:
"""Assert that at least one of the provided snippets appears in output.
This helper makes tests resilient to harmless wording changes in entrypoint
and diagnostic messages (e.g., when SPEC wording is updated).
"""
output = result.output + result.stderr
for s in snippets:
if s in output:
return
cmd_str = " ".join(cmd) if cmd else ""
raise AssertionError(
f"Expected to find one of '{snippets}' in container output.\n"
f"STDOUT:\n{result.output}\n"
f"STDERR:\n{result.stderr}\n"
f"Combined output:\n{output}\n"
f"Container command:\n{cmd_str}"
)
def _extract_mount_rows(output: str) -> dict[str, list[str]]:
rows: dict[str, list[str]] = {}
in_table = False
@@ -721,8 +859,14 @@ def test_missing_capabilities_triggers_warning(tmp_path: pathlib.Path) -> None:
NET_BIND_SERVICE capabilities. Required for ARP scanning and network operations.
Expected: "exec /bin/sh: operation not permitted" error, guidance to add capabilities.
Check script: N/A (capability check happens at container runtime)
Sample message: "exec /bin/sh: operation not permitted"
CRITICAL CANARY TEST:
This test verifies the Shell-based pre-flight check (10-capabilities-audit.sh).
Since the Python binary has `setcap` applied, it will fail to launch entirely
if capabilities are missing (kernel refuses execve). This Shell script is the
ONLY way to warn the user gracefully before the crash.
Check script: 10-capabilities-audit.sh
Sample message: "ALERT: Python execution capabilities (NET_RAW/NET_ADMIN) are missing."
"""
paths = _setup_mount_tree(tmp_path, "missing_caps")
volumes = _build_volume_args_for_keys(paths, {"data"})
@@ -731,8 +875,14 @@ def test_missing_capabilities_triggers_warning(tmp_path: pathlib.Path) -> None:
volumes,
drop_caps=["ALL"],
)
_assert_contains(result, "exec /bin/sh: operation not permitted", result.args)
assert result.returncode != 0
_assert_contains_any(
result,
[
"ALERT: Python execution capabilities (NET_RAW/NET_ADMIN) are missing",
"Python execution capabilities (NET_RAW/NET_ADMIN) are missing",
],
result.args,
)
def test_running_as_root_is_blocked(tmp_path: pathlib.Path) -> None:
@@ -742,8 +892,7 @@ def test_running_as_root_is_blocked(tmp_path: pathlib.Path) -> None:
dedicated netalertx user. Warning about security risks, special permission fix mode.
Expected: Warning about security risks, guidance to use UID 20211.
Check script: /entrypoint.d/0-storage-permission.sh
Sample message: "🚨 CRITICAL SECURITY ALERT: NetAlertX is running as ROOT (UID 0)!"
Sample message: "NetAlertX is running as ROOT"
"""
paths = _setup_mount_tree(tmp_path, "run_as_root")
volumes = _build_volume_args_for_keys(paths, {"data", "nginx_conf"})
@@ -753,7 +902,15 @@ def test_running_as_root_is_blocked(tmp_path: pathlib.Path) -> None:
user="0",
)
_assert_contains(result, "NetAlertX is running as ROOT", result.args)
_assert_contains(result, "Permissions fixed for read-write paths.", result.args)
_assert_contains_any(
result,
[
"Permissions fixed for read-write paths.",
"Permissions prepared for PUID=",
"Permissions prepared",
],
result.args,
)
assert (
result.returncode == 0
) # container warns but continues running, then terminated by test framework
@@ -790,8 +947,6 @@ def test_missing_host_network_warns(tmp_path: pathlib.Path) -> None:
# docker tests switch to compose-managed fixtures, restore these cases by moving them back to the
# top level.
def test_missing_app_conf_triggers_seed(tmp_path: pathlib.Path) -> None:
"""Test missing configuration file seeding - simulates corrupted/missing app.conf.
@@ -812,8 +967,10 @@ def test_missing_app_conf_triggers_seed(tmp_path: pathlib.Path) -> None:
)
finally:
_docker_volume_rm(vol)
# The key assertion: config seeding happened
_assert_contains(result, "Default configuration written to", result.args)
assert result.returncode == 0
# NOTE: The container may fail later in startup (e.g., nginx issues) but the seeding
# test passes if the config file was created. Full startup success is tested elsewhere.
def test_missing_app_db_triggers_seed(tmp_path: pathlib.Path) -> None:
@@ -844,10 +1001,20 @@ def test_missing_app_db_triggers_seed(tmp_path: pathlib.Path) -> None:
user="20211:20211",
sleep_seconds=20,
)
assert _volume_has_file(vol, "/data/db/app.db")
print(result.stdout) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
print(result.stderr) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
# The key assertion: database file was created
_assert_contains_any(
result,
["Building initial database schema", "First run detected"],
result.args,
)
# The key assertion: database file was created
assert _volume_has_file(vol, "/data/db/app.db"), "Database file should have been created"
finally:
_docker_volume_rm(vol)
assert result.returncode == 0
# NOTE: The container may fail later in startup (e.g., nginx issues) but the DB seeding
# test passes if the database file was created. Full startup success is tested elsewhere.
def test_custom_port_without_writable_conf(tmp_path: pathlib.Path) -> None:
@@ -884,6 +1051,7 @@ def test_custom_port_without_writable_conf(tmp_path: pathlib.Path) -> None:
)
assert result.returncode != 0
def test_excessive_capabilities_warning(tmp_path: pathlib.Path) -> None:
"""Test excessive capabilities detection - simulates container with extra capabilities.
@@ -908,6 +1076,7 @@ def test_excessive_capabilities_warning(tmp_path: pathlib.Path) -> None:
_assert_contains(result, "Excessive capabilities detected", result.args)
_assert_contains(result, "bounding caps:", result.args)
def test_appliance_integrity_read_write_mode(tmp_path: pathlib.Path) -> None:
"""Test appliance integrity - simulates running with read-write root filesystem.
@@ -1115,7 +1284,10 @@ def test_mount_analysis_ram_disk_performance(tmp_path: pathlib.Path) -> None:
)
# Check that configuration issues are detected due to dataloss risk
_assert_contains(result, "Configuration issues detected", result.args)
assert result.returncode != 0
# NOTE: The mounts script only exits non-zero for read/write permission failures on persistent
# paths, NOT for dataloss warnings. Dataloss is a warning, not a fatal error.
# The container continues to run after showing the warning.
assert result.returncode == 0
def test_mount_analysis_dataloss_risk(tmp_path: pathlib.Path) -> None:
@@ -1167,7 +1339,10 @@ def test_mount_analysis_dataloss_risk(tmp_path: pathlib.Path) -> None:
)
# Check that configuration issues are detected due to dataloss risk
_assert_contains(result, "Configuration issues detected", result.args)
assert result.returncode != 0
# NOTE: The mounts script only exits non-zero for read/write permission failures on persistent
# paths, NOT for dataloss warnings. Dataloss is a warning, not a fatal error.
# The container continues to run after showing the warning.
assert result.returncode == 0
def test_restrictive_permissions_handling(tmp_path: pathlib.Path) -> None:
@@ -1178,7 +1353,7 @@ def test_restrictive_permissions_handling(tmp_path: pathlib.Path) -> None:
If running as non-root (default), it should fail to write if it doesn't have access.
"""
paths = _setup_mount_tree(tmp_path, "restrictive_perms")
# Helper to chown without userns host (workaround for potential devcontainer hang)
def _chown_root_safe(host_path: pathlib.Path) -> None:
cmd = [
@@ -1202,11 +1377,11 @@ def test_restrictive_permissions_handling(tmp_path: pathlib.Path) -> None:
target_dir = paths["app_db"]
_chown_root_safe(target_dir)
target_dir.chmod(0o755)
# Mount ALL volumes to avoid 'find' errors in 0-storage-permission.sh
# Mount ALL volumes to avoid errors during permission checks
keys = {"data", "app_db", "app_config", "app_log", "app_api", "services_run", "nginx_conf"}
volumes = _build_volume_args_for_keys(paths, keys)
# Case 1: Running as non-root (default) - Should fail to write
# We disable host network/userns to avoid potential hangs in devcontainer environment
result = _run_container(
@@ -1228,9 +1403,13 @@ def test_restrictive_permissions_handling(tmp_path: pathlib.Path) -> None:
network_mode=None,
userns_mode=None
)
_assert_contains(result_root, "NetAlertX is running as ROOT", result_root.args)
_assert_contains(result_root, "Permissions fixed for read-write paths", result_root.args)
_assert_contains_any(
result_root,
["Permissions fixed for read-write paths", "Permissions prepared for PUID=", "Permissions prepared"],
result_root.args,
)
check_cmd = [
"docker", "run", "--rm",
@@ -1242,18 +1421,17 @@ def test_restrictive_permissions_handling(tmp_path: pathlib.Path) -> None:
# Add all volumes to check_cmd too
for host_path, target, _readonly in volumes:
check_cmd.extend(["-v", f"{host_path}:{target}"])
check_result = subprocess.run(
check_cmd,
capture_output=True,
text=True,
timeout=SUBPROCESS_TIMEOUT_SECONDS,
)
if check_result.returncode != 0:
print(f"Check command failed. Cmd: {check_cmd}")
print(f"Stderr: {check_result.stderr}")
print(f"Stdout: {check_result.stdout}")
assert check_result.returncode == 0, f"Should be able to write after root fix script runs. Stderr: {check_result.stderr}. Stdout: {check_result.stdout}"