vh/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2026-03-30 23:03:03 -07:00
Code Issues Actions 15 Packages Projects Releases Wiki Activity

Merge pull request #1499 from netalertx/main

Browse Source 
sync
This commit is contained in:
Jokob @NetAlertX
2026-02-09 09:38:55 +11:00
committed by GitHub
parent 4991b058d3 cedbd59897
commit d434cc5315
258 changed files with 8287 additions and 4880 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.devcontainer/Dockerfile
View File

@@ -137,7 +137,7 @@ ENV LANG=C.UTF-8
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 && \
nginx supercronic shadow su-exec jq && \
rm -Rf /var/cache/apk/* && \
rm -Rf /etc/nginx && \
addgroup -g ${NETALERTX_GID} ${NETALERTX_GROUP} && \

13
.devcontainer/scripts/generate-configs.sh
View File

@@ -31,4 +31,17 @@ cat "${DEVCONTAINER_DIR}/resources/devcontainer-Dockerfile"
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."

13
.devcontainer/scripts/run-tests.sh
View File

@@ -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 "$@"

6
.devcontainer/scripts/setup.sh
View File

@@ -32,7 +32,6 @@ LOG_FILES=(
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
@@ -55,6 +54,9 @@ sudo install -d -m 777 /tmp/log/plugins
sudo rm -rf /entrypoint.d
sudo ln -s "${SOURCE_DIR}/install/production-filesystem/entrypoint.d" /entrypoint.d
sudo rm -rf /services
sudo ln -s "${SOURCE_DIR}/install/production-filesystem/services" /services
sudo rm -rf "${NETALERTX_APP}"
sudo ln -s "${SOURCE_DIR}/" "${NETALERTX_APP}"
@@ -88,8 +90,6 @@ sudo chmod 777 "${LOG_DB_IS_LOCKED}"
sudo pkill -f python3 2>/dev/null || true
sudo chmod -R 777 "${PY_SITE_PACKAGES}" "${NETALERTX_DATA}" 2>/dev/null || true
sudo chown -R "${NETALERTX_USER}:${NETALERTX_GROUP}" "${NETALERTX_APP}"
date +%s | sudo tee "${NETALERTX_FRONT}/buildtimestamp.txt" >/dev/null

59
.gemini/GEMINI.md
View File

@@ -1,59 +0,0 @@
# Gemini-CLI Agent Instructions for NetAlertX
## 1. Environment & Devcontainer
When starting a session, always identify 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).*
## 2. 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).
## 3. Testing Workflow
**Crucial:** Tests MUST be run inside the container to access the correct runtime environment (DB, Config, Dependencies).
### Running Tests
Use `pytest` with the correct PYTHONPATH.
```bash
docker exec <CONTAINER_ID> bash -c "cd /workspaces/NetAlertX && pytest <test_file>"
```
*Example:*
```bash
docker exec <CONTAINER_ID> bash -c "cd /workspaces/NetAlertX && pytest test/api_endpoints/test_mcp_extended_endpoints.py"
```
### Authentication in Tests
The test environment uses `API_TOKEN`. The most reliable way to retrieve the current token from a running container is:
```bash
docker exec <CONTAINER_ID> python3 -c "from helper import get_setting_value; print(get_setting_value('API_TOKEN'))"
```
*Troubleshooting:* If tests fail with 403 Forbidden or empty tokens:
1. Verify server is running and use the aforementioned setup.sh if required.
2. Verify `app.conf` inside the container: `docker exec <ID> cat /data/config/app.conf`
23 Verify Python can read it: `docker exec <ID> python3 -c "from helper import get_setting_value; print(get_setting_value('API_TOKEN'))"`

31
.gemini/skills/devcontainer-management/SKILL.md Normal file
View File

@@ -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).*
```

52
.gemini/skills/mcp-activation/SKILL.md Normal file
View File

@@ -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`).

15
.gemini/skills/project-navigation/SKILL.md Normal file
View File

@@ -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).

78
.gemini/skills/testing-workflow/SKILL.md Normal file
View File

@@ -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'))"`

1
.github/FUNDING.yml vendored
View File

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

8
.github/ISSUE_TEMPLATE/config.yml vendored Normal file
View File

@@ -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.

6
.github/ISSUE_TEMPLATE/documentation-feedback.yml vendored
View File

@@ -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?

6
.github/ISSUE_TEMPLATE/feature_request.yml → .github/ISSUE_TEMPLATE/feature-request.yml vendored Executable file → Normal file
View File

@@ -1,7 +1,11 @@
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?

6
.github/ISSUE_TEMPLATE/i-have-an-issue.yml vendored
View File

@@ -1,7 +1,11 @@
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:

8
.github/ISSUE_TEMPLATE/security-report.yml vendored
View File

@@ -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:

6
.github/ISSUE_TEMPLATE/setup-help.yml vendored
View File

@@ -1,7 +1,11 @@
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:

112
.github/copilot-instructions.md vendored Executable file → Normal file
View File

@@ -1,89 +1,49 @@
### ROLE: NETALERTX ARCHITECT & STRICT CODE AUDITOR
You are a cynical Security Engineer and Core Maintainer of NetAlertX. Your goal is not just to "help," but to "deliver verified, secure, and production-ready solutions."
You are a cynical Security Engineer and Core Maintainer of NetAlertX. Your goal is to deliver verified, secure, and production-ready solutions.
### MANDATORY BEHAVIORAL OVERRIDES:
1. **Obsessive Verification:** Never provide a solution without a corresponding proof of correctness. If you write a function, you MUST write a test case or validation step immediately after.
2. **Anti-Laziness Protocol:** You are forbidden from using placeholders (e.g., `// ... rest of code`, ``). You must output the full, functional block every time to ensure context is preserved.
3. **Priority Hierarchy:** Priority 1 is Correctness. Priority 2 is Completeness. Priority 3 is Speed.
4. **Mantra:** "Job's not done 'till unit tests run."
### 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."
---
# NetAlertX AI Assistant Instructions
This is NetAlertX — network monitoring & alerting. NetAlertX provides Network inventory, awareness, insight, categorization, intruder and presence detection. This is a heavily community-driven project, welcoming of all contributions.
# NetAlertX
## 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`
Network monitoring & alerting. Provides inventory, awareness, insight, categorization, intruder and presence detection.
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.
## Architecture
## 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 `/tmp/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.
- **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
### 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.
## Skills
### Plugin logging & outputs
- Always check relevant logs first.
- Use logging as shown in other plugins.
- 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 `info` level and use `verbose` or `debug` for extra context.
- Do not write ad‑hoc files for results; the only consumable output is `last_result.<PREF>.log` generated by `Plugin_Objects`.
Procedural knowledge lives in `.github/skills/`. Load the appropriate skill when performing these tasks:
## 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')`.
- All responses need to return `"success":<False:True>` and if `False` an "error" message needs to be returned, e.g. `{"success": False, "error": f"No stored open ports for Device"}`
| 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` |
## 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 `mylog(level, [message])`; levels: none/minimal/verbose/debug/trace. `none` is used for most important messages that should always appear, such as exceptions. Do NOT use `error` as level.
- Time/MAC/strings: `server/utils/datetime_utils.py` (`timeNowDB`), `front/plugins/plugin_helper.py` (`normalize_mac`), `server/helper.py` (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.
## Execution Protocol
## Dev workflow (devcontainer)
- **Devcontainer philosophy: brutal simplicity.** One user, everything writable, completely idempotent. No permission checks, no conditional logic, no sudo needed. If something doesn't work, tear down the wall and rebuild - don't patch. We unit test permissions in the hardened build.
- **Permissions:** Never `chmod` or `chown` during operations. Everything is already writable. If you need permissions, the devcontainer setup is broken - fix `.devcontainer/scripts/setup.sh` or `.devcontainer/resources/devcontainer-Dockerfile` instead.
- **Files & Paths:** Use environment variables (`NETALERTX_DB`, `NETALERTX_LOG`, etc.) everywhere. `/data` for persistent config/db, `/tmp` for runtime logs/api/nginx state. Never hardcode `/data/db` or relative paths.
- **Database reset:** Use the `[Dev Container] Wipe and Regenerate Database` task. Kills backend, deletes `/data/{db,config}/*`, runs first-time setup scripts. Clean slate, no questions.
- 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.
- **Subprocess calls:** ALWAYS set explicit timeouts. Default to 60s minimum unless plugin config specifies otherwise. Nested subprocess calls (e.g., plugins calling external tools) need their own timeout - outer plugin timeout won't save you.
- you need to set the BACKEND_API_URL setting (e.g. in teh app.conf file or via the APP_CONF_OVERRIDE env variable) to the backend api port url , e.g. https://something-20212.app.github.dev/ depending on your github codespace url.
## 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 `/tmp/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.
- Always try following the DRY principle, do not re-implement functionality, but re-use existing methods where possible, or refactor to use a common method that is called multiple times
- If new functionality needs to be added, look at impenting it into existing handlers (e.g. `DeviceInstance` in `server/models/device_instance.py`) or create a new one if it makes sense. Do not access the DB from otehr application layers.
- Code files shoudln't be longer than 500 lines of code
## Useful references
- Docs: `docs/PLUGINS_DEV.md`, `docs/SETTINGS_SYSTEM.md`, `docs/API_*.md`, `docs/DEBUG_*.md`
- Logs: All logs are under `/tmp/log/`. Plugin logs are very shortly under `/tmp/log/plugins/` until picked up by the server.
- plugin logs: `/tmp/log/plugins/*.log`
- backend logs: `/tmp/log/stdout.log` and `/tmp/log/stderr.log`
- php errors: `/tmp/log/app.php_errors.log`
- nginx logs: `/tmp/log/nginx-access.log` and `/tmp/log/nginx-error.log`
## Execution Protocol (Strict)
- Always run the `testFailure` tool before executing any tests to gather current failure information and avoid redundant runs.
- Always prioritize using the appropriate tools in the environment first. Example: if a test is failing use `testFailure` then `runTests`.
- Docker tests take an extremely long time to run. Avoid changes to docker or tests until you've examined the existing `testFailure`s and `runTests` results.
- **Before running tests:** Always use `testFailure` tool first to gather current failures.
- **Docker tests are slow.** Examine existing failures before changing tests or Dockerfiles.

69
.github/skills/api-development/SKILL.md vendored Normal file
View File

@@ -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)

60
.github/skills/authentication/SKILL.md vendored Normal file
View File

@@ -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_

65
.github/skills/code-standards/SKILL.md vendored Normal file
View File

@@ -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

38
.github/skills/database-reset/SKILL.md vendored Normal file
View File

@@ -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`

28
.github/skills/devcontainer-configs/SKILL.md vendored Normal file
View File

@@ -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.

50
.github/skills/devcontainer-services/SKILL.md vendored Normal file
View File

@@ -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

36
.github/skills/devcontainer-setup/SKILL.md vendored Normal file
View File

@@ -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.

38
.github/skills/docker-build/SKILL.md vendored Normal file
View File

@@ -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)

32
.github/skills/docker-prune/SKILL.md vendored Normal file
View File

@@ -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.

34
.github/skills/mcp-activation/SKILL.md vendored Normal file
View File

@@ -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**

85
.github/skills/plugin-run-development/SKILL.md vendored Normal file
View File

@@ -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.

59
.github/skills/project-navigation/SKILL.md vendored Normal file
View File

@@ -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` |

31
.github/skills/sample-data/SKILL.md vendored Normal file
View File

@@ -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

47
.github/skills/settings-management/SKILL.md vendored Normal file
View File

@@ -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/
```

61
.github/skills/testing-workflow/SKILL.md vendored Normal file
View File

@@ -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).

23
.github/workflows/code_checks.yml → .github/workflows/code-checks.yml vendored Executable file → Normal file
View File

@@ -1,4 +1,4 @@
name: Code checks
name: ✅ Code checks
on:
push:
branches:
@@ -17,6 +17,23 @@ jobs:
- 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/')..."
@@ -95,5 +112,5 @@ jobs:
- name: Run Docker-based tests
run: |
echo "🐳 Running Docker-based tests..."
chmod +x ./test/docker_tests/run_docker_tests.sh
./test/docker_tests/run_docker_tests.sh
chmod +x ./scripts/run_tests_in_docker_environment.sh
./scripts/run_tests_in_docker_environment.sh

25
.github/workflows/docker_cache-cleaner.yml vendored
View File

@@ -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

2
.github/workflows/docker_dev.yml vendored
View File

@@ -1,4 +1,4 @@
name: docker
name: 🐳 👩‍💻 docker dev
on:
push:

2
.github/workflows/docker_dev_unsafe.yml vendored
View File

@@ -1,4 +1,4 @@
name: docker-unsafe
name: 🐳 ⚠ docker-unsafe from next_release branch
on:
push:

2
.github/workflows/docker_prod.yml vendored
View File

@@ -6,7 +6,7 @@
# 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:

21
.github/workflows/label-issues.yml vendored
View File

@@ -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') || lowerBody.includes('proxmox')) {
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(", ")}`);
}

2
.github/workflows/mkdocs.yml vendored
View File

@@ -1,4 +1,4 @@
name: Deploy MkDocs
name: 📘 Deploy MkDocs
on:
push:

81
.github/workflows/run-all-tests.yml vendored Normal file
View File

@@ -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

0
.github/workflows/social_post_on_release.yml → .github/workflows/social-post-on-release.yml vendored Executable file → Normal file
View File

3
.gitignore vendored
View File

@@ -24,6 +24,7 @@ front/api/*
/api/*
**/plugins/**/*.log
**/plugins/cloud_services/*
**/plugins/cloud_connector/*
**/%40eaDir/
**/@eaDir/
@@ -46,3 +47,5 @@ docker-compose.yml.ffsb42
.env.omada.ffsb42
.venv
test_mounts/
.gemini/settings.json
.vscode/mcp.json

1
.vscode/settings.json vendored
View File

@@ -31,5 +31,6 @@
"python.formatting.blackArgs": [
"--line-length=180"
],
"chat.useAgentSkills": true,
}

2
Dockerfile
View File

@@ -134,7 +134,7 @@ ENV LANG=C.UTF-8
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 && \
nginx supercronic shadow su-exec jq && \
rm -Rf /var/cache/apk/* && \
rm -Rf /etc/nginx && \
addgroup -g ${NETALERTX_GID} ${NETALERTX_GROUP} && \

299
Dockerfile.debian
View File

@@ -1,57 +1,46 @@
# Warning - use of this unhardened image is not recommended for production use.
# This image is provided for backward compatibility, development and testing purposes only.
# For production use, please use the hardened image built with Alpine. This image attempts to
# treat a container as an operating system, which is an anti-pattern and a common source of
# security issues.
#
# The default Dockerfile/docker-compose image contains the following security improvements
# over the Debian image:
# - read-only filesystem
# - no sudo access
# - least possible permissions on all files and folders
# - Root user has all permissions revoked and is unused
# - Secure umask applied so files are owner-only by default
# - non-privileged user runs the application
# - no shell access for non-privileged users
# - no unnecessary packages or services
# - reduced capabilities
# - tmpfs for writable folders
# - healthcheck
# - no package managers
# - no compilers or build tools
# - no systemd, uses lightweight init system
# - no persistent storage except for config and db volumes
# - minimal image size due to segmented build stages
# - minimal base image (Alpine Linux)
# - minimal python environment (venv, no pip)
# - minimal stripped web server
# - minimal stripped php environment
# - minimal services (nginx, php-fpm, crond, no unnecessary services or service managers)
# - minimal users and groups (netalertx and readonly only, no others)
# - minimal permissions (read-only for most files and folders, write-only for necessary folders)
# - minimal capabilities (NET_ADMIN and NET_RAW only, no others)
# - minimal environment variables (only necessary ones, no others)
# - minimal entrypoint (only necessary commands, no others)
# - Uses the same base image as the development environmnment (Alpine Linux)
# - Uses the same services as the development environment (nginx, php-fpm, crond)
# - Uses the same environment variables as the development environment (only necessary ones, no others)
# - Uses the same file and folder structure as the development environment (only necessary ones, no others)
# NetAlertX is designed to be run as an unattended network security monitoring appliance, which means it
# should be able to operate without human intervention. Overall, the hardened image is designed to be as
# secure as possible while still being functional and is recommended because you cannot attack a surface
# that isn't there.
# Stage 1: Builder
# Install build dependencies and create virtual environment
FROM debian:bookworm-slim AS builder
ENV PYTHONUNBUFFERED=1
ENV VIRTUAL_ENV=/opt/venv
ENV PATH="${VIRTUAL_ENV}/bin:${PATH}"
FROM debian:bookworm-slim
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/*
#TZ=Europe/London
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
# NetAlertX app directories
ENV INSTALL_DIR=/app
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
@@ -59,8 +48,8 @@ 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
# 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
@@ -75,102 +64,178 @@ ENV LOG_STDOUT=${NETALERTX_LOG}/stdout.log
ENV LOG_CRON=${NETALERTX_LOG}/cron.log
ENV LOG_NGINX_ERROR=${NETALERTX_LOG}/nginx-error.log
# 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_NGINIX_CONFIG=${SYSTEM_SERVICES_CONFIG}/nginx
ENV SYSTEM_NGINX_CONFIG_FILE=${SYSTEM_NGINIX_CONFIG}/nginx.conf
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 NETALERTX_CONFIG_FILE=${NETALERTX_CONFIG}/app.conf
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_CROND=${SYSTEM_SERVICES_CONFIG}/crond
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
#Python environment
ENV PYTHONPATH=${NETALERTX_SERVER}
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 PATH="${VIRTUAL_ENV}/bin:${PATH}:/services"
ENV VENDORSPATH=/app/back/ieee-oui.txt
ENV VENDORSPATH_NEWEST=${SYSTEM_SERVICES_RUN_TMP}/ieee-oui.txt
ENV PYTHONPATH=${NETALERTX_APP}:${NETALERTX_SERVER}:${NETALERTX_PLUGINS}:${VIRTUAL_ENV}/lib/python3.11/site-packages
ENV PATH="${SYSTEM_SERVICES}:${VIRTUAL_ENV_BIN}:$PATH"
# App Environment
ENV LISTEN_ADDR=0.0.0.0
ENV PORT=20211
ENV NETALERTX_DEBUG=0
#Container environment
ENV VENDORSPATH=/app/back/ieee-oui.txt
ENV VENDORSPATH_NEWEST=${SYSTEM_SERVICES_RUN_TMP}/ieee-oui.txt
ENV ENVIRONMENT=debian
ENV USER=netalertx
ENV USER_ID=1000
ENV USER_GID=1000
ENV READ_ONLY_USER=readonly READ_ONLY_GROUP=readonly
ENV NETALERTX_USER=netalertx NETALERTX_GROUP=netalertx
ENV LANG=C.UTF-8
# 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
# 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
COPY --chmod=775 --chown=${USER_ID}:${USER_GID} install/production-filesystem/ /
COPY --chmod=775 --chown=${USER_ID}:${USER_GID} . ${INSTALL_DIR}/
# ❗ IMPORTANT - if you modify this file modify the /install/install_dependecies.debian.sh file as well ❗
# hadolint ignore=DL3008,DL3027
# 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 php php-cgi php-fpm php-sqlite3 php-curl sqlite3 dnsutils net-tools \
python3 python3-dev iproute2 nmap fping python3-pip zip git systemctl usbutils traceroute nbtscan openrc \
busybox nginx nginx-core mtr python3-venv && \
rm -rf /var/lib/apt/lists/*
# While php8.3 is in debian bookworm repos, php-fpm is not included so we need to add sury.org repo
# (Ondřej Surý maintains php packages for debian. This is temp until debian includes php-fpm in their
# repos. Likely it will be in Debian Trixie.). This keeps the image up-to-date with the alpine version.
# hadolint ignore=DL3008
RUN apt-get install -y --no-install-recommends \
apt-transport-https \
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 && \
wget -q -O /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 php8.3-cgi && \
ln -s /usr/sbin/php-fpm8.3 /usr/sbin/php-fpm83 && \
rm -rf /var/lib/apt/lists/* # make it compatible with alpine version
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 python3 -m venv ${VIRTUAL_ENV} && \
/bin/bash -c "source ${VIRTUAL_ENV_BIN}/activate && update-alternatives --install /usr/bin/python python /usr/bin/python3 10 && pip3 install -r ${INSTALL_DIR}/requirements.txt"
# Fix permissions for /tmp BEFORE copying anything that might overwrite it with bad perms
RUN chmod 1777 /tmp
# Configure php-fpm
RUN chmod -R 755 /services && \
chown -R ${USER}:${USER_GID} /services && \
sed -i 's/^;listen.mode = .*/listen.mode = 0666/' ${SYSTEM_SERVICES_PHP_FPM_D}/www.conf && \
printf "user = %s\ngroup = %s\n" "${USER}" "${USER_GID}" >> /services/config/php/php-fpm.d/www.conf
# User setup
RUN groupadd -g ${NETALERTX_GID} ${NETALERTX_GROUP} && \
useradd -u ${NETALERTX_UID} -g ${NETALERTX_GID} -d ${NETALERTX_APP} -s /bin/bash ${NETALERTX_USER}
# 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
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 a buildtimestamp.txt to later check if a new version was released
RUN date +%s > ${INSTALL_DIR}/front/buildtimestamp.txt
USER netalertx:netalertx
ENTRYPOINT ["/bin/bash","/entrypoint.sh"]
# 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

133
README.md
View File

@@ -4,34 +4,43 @@
[![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://docs.netalertx.com/PLUGINS#readme) with auto-generated UI and in-build notification system. Build out and easily maintain your network source of truth (NSoT) and device inventory.
![main][main]
## 📋 Table of Contents
<details>
<summary>📷 Click for more screenshots</summary>
- [NetAlertX - Network, presence scanner and alert framework](#netalertx---network-presence-scanner-and-alert-framework)
- [📋 Table of Contents](#-table-of-contents)
- [🚀 Quick Start](#-quick-start)
- [📦 Features](#-features)
- [Scanners](#scanners)
- [Notification gateways](#notification-gateways)
- [Integrations and Plugins](#integrations-and-plugins)
- [Workflows](#workflows)
- [📚 Documentation](#-documentation)
- [🔐 Security \& Privacy](#-security--privacy)
- [❓ FAQ](#-faq)
- [🐞 Known Issues](#-known-issues)
- [📃 Everything else](#-everything-else)
- [📧 Get notified what's new](#-get-notified-whats-new)
- [🔀 Other Alternative Apps](#-other-alternative-apps)
- [💙 Donations](#-donations)
- [🏗 Contributors](#-contributors)
- [🌍 Translations](#-translations)
- [License](#license)
| ![Main screen][main] | ![device_details 1][device_details] | ![Screen network][network] |
|----------------------|----------------------|----------------------|
| ![presence][presence] | ![maintenance][maintenance] | ![settings][settings] |
| ![sync_hub][sync_hub] | ![report1][report1] | ![device_nmap][device_nmap] |
Head to [https://netalertx.com/](https://netalertx.com/) for even more gifs and screenshots 📷.
</details>
## 🚀 Quick Start
Centralized network visibility and continuous asset discovery.
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.
@@ -47,14 +56,14 @@ docker run -d \
--tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
-e PORT=20211 \
-e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \
ghcr.io/jokob-sk/netalertx:latest
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/jokob-sk/NetAlertX.git
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
@@ -64,31 +73,17 @@ Need help configuring it? Check the [usage guide](https://docs.netalertx.com/REA
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)
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)
---
| [📑 Docker guide](https://docs.netalertx.com/DOCKER_INSTALLATION) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://docs.netalertx.com/) | [🔌 Plugins](https://docs.netalertx.com/PLUGINS) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
|----------------------| ----------------------| ----------------------| ----------------------| ----------------------|
## Features
![showcase][showcase]
### Discovery & Asset Intelligence
<details>
<summary>📷 Click for more screenshots</summary>
| ![Main screen][main] | ![device_details 1][device_details] | ![Screen network][network] |
|----------------------|----------------------|----------------------|
| ![presence][presence] | ![maintenance][maintenance] | ![settings][settings] |
| ![sync_hub][sync_hub] | ![report1][report1] | ![device_nmap][device_nmap] |
Head to [https://netalertx.com/](https://netalertx.com/) for even more gifs and screenshots 📷.
</details>
## 📦 Features
### Scanners
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://docs.netalertx.com/PLUGINS#readme) docs for a full list of avaliable plugins.
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
@@ -101,12 +96,14 @@ build your own scanners with the [Plugin system](https://docs.netalertx.com/PLUG
### Workflows
The [workflows module](https://docs.netalertx.com/WORKFLOWS) 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://docs.netalertx.com/DOCKER_INSTALLATION)
@@ -117,50 +114,51 @@ Supported browsers: Chrome, Firefox
- [[Development] API docs](https://docs.netalertx.com/API)
- [[Development] Custom Plugins](https://docs.netalertx.com/PLUGINS_DEV)
...or explore all the [documentation here](https://docs.netalertx.com/).
## 🔐 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?**
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://docs.netalertx.com/HW_INSTALL).
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 `/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://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://docs.netalertx.com/).
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.
@@ -169,10 +167,10 @@ Get notified about a new release, what new functionality you can use and about b
### 🔀 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
@@ -183,9 +181,8 @@ Thank you to everyone who appreciates this tool and donates.
<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`
@@ -197,7 +194,7 @@ Thank you to everyone who appreciates this tool and donates.
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
@@ -223,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"

4
back/app.conf
View File

@@ -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'
@@ -100,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 #

34
back/app.sql
View File

@@ -150,21 +150,21 @@ CREATE TABLE Plugins_Language_Strings(
PRIMARY KEY("Index" AUTOINCREMENT)
);
CREATE TABLE CurrentScan (
cur_MAC STRING(50) NOT NULL COLLATE NOCASE,
cur_IP STRING(50) NOT NULL COLLATE NOCASE,
cur_Vendor STRING(250),
cur_ScanMethod STRING(10),
cur_Name STRING(250),
cur_LastQuery STRING(250),
cur_DateTime STRING(250),
cur_SyncHubNodeName STRING(50),
cur_NetworkSite STRING(250),
cur_SSID STRING(250),
cur_devVlan STRING(250),
cur_NetworkNodeMAC STRING(250),
cur_PORT STRING(250),
cur_Type STRING(250),
UNIQUE(cur_MAC)
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,
@@ -237,9 +237,9 @@ CREATE VIEW LatestEventsPerMAC AS
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.cur_MAC
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,cur_MAC,cur_IP,cur_Vendor,cur_ScanMethod,cur_Name,cur_LastQuery,cur_DateTime,cur_SyncHubNodeName,cur_NetworkSite,cur_SSID,cur_NetworkNodeMAC,cur_PORT,cur_Type) */;
/* 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,

144
back/device_heuristics_rules.json
View File

@@ -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"]
}
]
]

7
docs/API.md
View File

@@ -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
@@ -57,6 +59,10 @@ 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.
@@ -76,6 +82,7 @@ http://<server>:<GRAPHQL_PORT>/
* [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

33
docs/API_DEVICE_FIELD_LOCK.md
View File

@@ -138,36 +138,6 @@ The Device Edit form displays lock/unlock buttons for all tracked fields:
2. **Unlock Button** (🔓): Click to allow plugin overwrites again
3. **Source Indicator**: Shows current field source (USER, LOCKED, NEWDEV, or plugin name)
## UI Workflow
### Locking a Field via UI
1. Navigate to Device Details
2. Find the field you want to protect
3. Click the lock button (🔒) next to the field
4. Button changes to unlock (🔓) and source indicator turns red (LOCKED)
5. Field is now protected from plugin overwrites
### Unlocking a Field via UI
1. Find the locked field (button shows 🔓)
2. Click the unlock button
3. Button changes back to lock (🔒) and source resets to NEWDEV
4. Plugins can now update this field again
## Authorization
All lock/unlock operations require:
- Valid API token in `Authorization: Bearer {token}` header
- User must be authenticated to the NetAlertX instance
## Implementation Details
### Backend Logic
The lock/unlock feature is implemented in:
- **API Endpoint**: `/server/api_server/api_server_start.py` - `api_device_field_lock()`
- **Data Model**: `/server/models/device_instance.py` - Authorization checks in `setDeviceData()`
- **Database**: Devices table with `*Source` columns tracking field origins
### Authorization Handler
@@ -179,6 +149,9 @@ The authoritative field update logic prevents plugin overwrites:
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)

45
docs/API_MCP.md
View File

@@ -31,11 +31,6 @@ graph TB
D -->|Response Data| C
C -->|JSON Response| B
B -->|Stream Events| A
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#fff3e0
style D fill:#e8f5e8
```
### MCP Tool Integration
@@ -54,7 +49,7 @@ sequenceDiagram
API-->>MCP: 5. Available tools spec
MCP-->>AI: 6. Tool definitions
AI->>MCP: 7. tools/call: search_devices
MCP->>API: 8. POST /mcp/sse/devices/search
MCP->>API: 8. POST /devices/search
API->>DB: 9. Query devices
DB-->>API: 10. Device data
API-->>MCP: 11. JSON response
@@ -77,9 +72,9 @@ graph LR
end
subgraph "NetAlertX API Server (:20211)"
F[Device APIs<br/>/mcp/sse/devices/*]
G[Network Tools<br/>/mcp/sse/nettools/*]
H[Events API<br/>/mcp/sse/events/*]
F[Device APIs<br/>/devices/*]
G[Network Tools<br/>/nettools/*]
H[Events API<br/>/events/*]
end
subgraph "Backend"
@@ -98,15 +93,6 @@ graph LR
F --> I
G --> J
H --> I
style A fill:#e1f5fe
style B fill:#e1f5fe
style C fill:#f3e5f5
style D fill:#f3e5f5
style E fill:#f3e5f5
style F fill:#fff3e0
style G fill:#fff3e0
style H fill:#fff3e0
```
---
@@ -196,27 +182,28 @@ eventSource.onmessage = function(event) {
| Tool | Endpoint | Description |
|------|----------|-------------|
| `list_devices` | `/mcp/sse/devices/by-status` | List devices by online status |
| `get_device_info` | `/mcp/sse/device/<mac>` | Get detailed device information |
| `search_devices` | `/mcp/sse/devices/search` | Search devices by MAC, name, or IP |
| `get_latest_device` | `/mcp/sse/devices/latest` | Get most recently connected device |
| `set_device_alias` | `/mcp/sse/device/<mac>/set-alias` | Set device friendly name |
| `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` | `/mcp/sse/nettools/trigger-scan` | Trigger network discovery scan |
| `get_open_ports` | `/mcp/sse/device/open_ports` | Get stored NMAP open ports for device |
| `wol_wake_device` | `/mcp/sse/nettools/wakeonlan` | Wake device using Wake-on-LAN |
| `get_network_topology` | `/mcp/sse/devices/network/topology` | Get network topology map |
| `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` | `/mcp/sse/events/recent` | Get events from last 24 hours |
| `get_last_events` | `/mcp/sse/events/last` | Get 10 most recent events |
| `get_recent_alerts` | `/events/recent` | Get events from last 24 hours |
| `get_last_events` | `/events/last` | Get 10 most recent events |
---

2
docs/BACKUPS.md
View File

@@ -2,7 +2,7 @@
> [!NOTE]
> To back up 99% of your configuration, back up at least the `/data/config` folder.
> Database definitions can change between releases, so the safest method is to restore backups using the **same app version** they were taken from, then upgrade incrementally.
> Database definitions can change between releases, so the safest method is to restore backups using the **same app version** they were taken from, then upgrade incrementally by following the [Migration documentation](./MIGRATION.md).
---

20
docs/COMMON_ISSUES.md
View File

@@ -120,3 +120,23 @@ With `ARPSCAN` scans some devices might flip IP addresses after each scan trigge
See how to prevent IP flipping in the [ARPSCAN plugin guide](/front/plugins/arp_scan/README.md).
Alternatively adjust your [notification settings](./NOTIFICATIONS.md) to prevent false positives by filtering out events or devices.
#### Multiple NICs on Same Host Reporting Same IP
On systems with multiple NICs (like a Proxmox server), each NIC has its own MAC address. Sometimes NetAlertX can incorrectly assign the same IP to all NICs, causing false device mappings. This is due to the way ARP responses are handled by the OS and cannot be overridden directly in NetAlertX.
**Resolution (Linux-based systems, e.g., Proxmox):**
Run the following commands on the host to fix ARP behavior:
```bash
sudo sysctl -w net.ipv4.conf.all.arp_ignore=1
sudo sysctl -w net.ipv4.conf.all.arp_announce=2
```
This ensures each NIC responds correctly to ARP requests and prevents NetAlertX from misassigning IPs.
> For setups with multiple interfaces on the same switch, consider [workflows](./WORKFLOWS.md), [device exclusions](./NOTIFICATIONS.md), or [dummy devices](./DEVICE_MANAGEMENT.md) as additional workarounds.
> See [Feature Requests](https://github.com/netalertx/netalertx/issues) for reporting edge cases.

28
docs/DEBUG_PLUGINS.md
View File

@@ -1,7 +1,7 @@
# Troubleshooting plugins
> [!TIP]
> Before troubleshooting, please ensure you have the right [Debugging and LOG_LEVEL set](./DEBUG_TIPS.md).
> Before troubleshooting, please ensure you have the right [Debugging and LOG_LEVEL set](./DEBUG_TIPS.md) in Settings.
## High-level overview
@@ -22,10 +22,25 @@ For a more in-depth overview on how plugins work check the [Plugins development
#### Incorrect input data
Input data from the plugin might cause mapping issues in specific edge cases. Look for a corresponding section in the `app.log` file, for example notice the first line of the execution run of the `PIHOLE` plugin below:
Input data from the plugin might cause mapping issues in specific edge cases. Look for a corresponding section in the `app.log` file, and search for `[Scheduler] run for PLUGINNAME: YES`, so for ICMP you would look for `[Scheduler] run for ICMP: YES`. You can find examples of useful logs below. If your issue is related to a plugin, and you don't include a log section with this data, we can't help you to resolve your issue.
##### ICMP log example
```
17:31:05 [Scheduler] - Scheduler run for PIHOLE: YES
20:39:04 [Scheduler] run for ICMP: YES
20:39:04 [ICMP] fping skipping 192.168.1.124 : [2], timed out (NaN avg, 100% loss)
20:39:04 [ICMP] adding 192.168.1.123 from 192.168.1.123 : [2], 64 bytes, 20.1 ms (8.22 avg, 0% loss)
20:39:04 [ICMP] fping skipping 192.168.1.157 : [1], timed out (NaN avg, 100% loss)
20:39:04 [ICMP] adding 192.168.1.79 from 192.168.1.79 : [2], 64 bytes, 48.3 ms (60.9 avg, 0% loss)
20:39:04 [ICMP] fping skipping 192.168.1.128 : [2], timed out (NaN avg, 100% loss)
20:39:04 [ICMP] fping skipping 192.168.1.129 : [2], timed out (NaN avg, 100% loss)
```
##### PIHOLE log example
```
17:31:05 [Scheduler] run for PIHOLE: YES
17:31:05 [Plugin utils] ---------------------------------------------
17:31:05 [Plugin utils] display_name: PiHole (Device sync)
17:31:05 [Plugins] CMD: SELECT n.hwaddr AS Object_PrimaryID, {s-quote}null{s-quote} AS Object_SecondaryID, datetime() AS DateTime, na.ip AS Watched_Value1, n.lastQuery AS Watched_Value2, na.name AS Watched_Value3, n.macVendor AS Watched_Value4, {s-quote}null{s-quote} AS Extra, n.hwaddr AS ForeignKey FROM EXTERNAL_PIHOLE.Network AS n LEFT JOIN EXTERNAL_PIHOLE.Network_Addresses AS na ON na.network_id = n.id WHERE n.hwaddr NOT LIKE {s-quote}ip-%{s-quote} AND n.hwaddr is not {s-quote}00:00:00:00:00:00{s-quote} AND na.ip is not null
@@ -54,13 +69,13 @@ Input data from the plugin might cause mapping issues in specific edge cases. Lo
17:31:05 [Plugin utils] In pluginObjects there are 2 events with the status "missing-in-last-scan"
17:31:05 [Plugin utils] In pluginObjects there are 2 events with the status "watched-not-changed"
17:31:05 [Plugins] Mapping objects to database table: CurrentScan
17:31:05 [Plugins] SQL query for mapping: INSERT into CurrentScan ( "cur_MAC", "cur_IP", "cur_LastQuery", "cur_Name", "cur_Vendor", "cur_ScanMethod") VALUES ( ?, ?, ?, ?, ?, ?)
17:31:05 [Plugins] SQL query for mapping: INSERT into CurrentScan ( "scanMac", "scanLastIP", "scanLastQuery", "scanName", "scanVendor", "scanSourcePlugin") VALUES ( ?, ?, ?, ?, ?, ?)
17:31:05 [Plugins] SQL sqlParams for mapping: [('01:01:01:01:01:01', '172.30.0.1', 0, 'aaaa', 'vvvvvvvvv', 'PIHOLE'), ('02:42:ac:1e:00:02', '172.30.0.2', 0, 'dddd', 'vvvvv2222', 'PIHOLE')]
🔺
17:31:05 [API] Update API starting
17:31:06 [API] Updating table_plugins_history.json file in /api
```
> [!NOTE]
> The debug output between the 🔻red arrows🔺 is important for debugging (arrows added only to highlight the section on this page, they are not available in the actual debug log)
In the above output notice the section logging how many events are produced by the plugin:
@@ -80,12 +95,11 @@ These values, if formatted correctly, will also show up in the UI:
![Plugins table](./img/DEBUG_PLUGINS/plugin_objects_pihole.png)
### Sharing application state
Sometimes specific log sections are needed to debug issues. The Devices and CurrentScan table data is sometimes needed to figure out what's wrong.
1. Please set `LOG_LEVEL` to `trace` (Disable it once you have the info as this produces big log files).
1. Please set `LOG_LEVEL` to `trace` in the Settings (Disable it once you have the info as this produces big log files).
2. Wait for the issue to occur.
3. Search for `================ DEVICES table content ================` in your logs.
4. Search for `================ CurrentScan table content ================` in your logs.

4
docs/DEBUG_TIPS.md
View File

@@ -21,7 +21,7 @@ docker run \
--tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
-e PORT=20211 \
-e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \
ghcr.io/jokob-sk/netalertx:latest
ghcr.io/netalertx/netalertx:latest
```
@@ -34,7 +34,7 @@ Note: Your `/local_data_dir` should contain a `config` and `db` folder.
If possible, check if your issue got fixed in the `_dev` image before opening a new issue. The container is:
`ghcr.io/jokob-sk/netalertx-dev:latest`
`ghcr.io/netalertx/netalertx-dev:latest`
> ⚠ Please backup your DB and config beforehand!

53
docs/QUICK_REFERENCE_FIELD_LOCK.md → docs/DEVICE_FIELD_LOCK.md
View File

@@ -1,6 +1,8 @@
# Quick Reference Guide - Device Field Lock/Unlock System
## One-Minute Overview
## Overview
![Field source and locks](./img/DEVICE_MANAGEMENT/field_sources_and_locks.png)
The device field lock/unlock system allows you to protect specific device fields from being automatically overwritten by scanning plugins. When you lock a field, NetAlertX remembers your choice and prevents plugins from changing that value until you unlock it.
@@ -10,14 +12,19 @@ The device field lock/unlock system allows you to protect specific device fields
These are the ONLY fields that can be locked:
- devName - Device hostname/alias
- devVendor - Device manufacturer
- devFQDN - Fully qualified domain name
- devSSID - WiFi network name
- devParentMAC - Parent/gateway MAC
- devParentPort - Parent device port
- devParentRelType - Relationship type (e.g., "gateway")
- devVlan - VLAN identifier
- `devName` - Device hostname/alias
- `devVendor` - Device manufacturer
- `devSSID` - WiFi network name
- `devParentMAC` - Parent/gateway MAC
- `devParentPort` - Parent device port
- `devParentRelType` - Relationship type (e.g., "gateway")
- `devVlan` - VLAN identifier
Additional fields that are tracked (and their source is dispalyed in the UI if available):
- `devMac`
- `devLastIP`
- `devFQDN`
## Source Values Explained
@@ -30,7 +37,12 @@ Each locked field has a "source" indicator that shows you why the value is prote
| 📡 **NEWDEV** | Default/unset value | Yes, plugins can update |
| 📡 **Plugin name** | Last updated by a plugin (e.g., UNIFIAPI) | Yes, plugins can update if field in SET_ALWAYS |
## How to Use
Overwrite rules are
> [!TIP]
> You can bulk-unlock devices in the [Multi-edit](./DEVICES_BULK_EDITING.md) dialog. This removes all `USER` and `LOCKED` values from all `*Source` fields of selected devices.
## Usage Examples
### Lock a Field (Prevent Plugin Changes)
@@ -106,12 +118,14 @@ Each locked field has a "source" indicator that shows you why the value is prote
## When to Lock vs. When NOT to Lock
### ✅ **Good reasons to lock:**
- You've customized the device name and it's correct
- You've set a static IP and it shouldn't change
- You've configured VLAN information
- You know the parent device and don't want it auto-corrected
### ❌ **Bad reasons to lock:**
- The value seems wrong—edit it first, then lock
- You want to prevent data from another source—use field lock, not to hide problems
- You're trying to force a value the system disagrees with
@@ -119,29 +133,32 @@ Each locked field has a "source" indicator that shows you why the value is prote
## Troubleshooting
**Lock button not appearing:**
- Confirm the field is one of the tracked fields (see list above)
- Confirm the device is already saved (new devices don't show lock buttons)
- Refresh the page
**Lock button is there but click doesn't work:**
- Check your internet connection
- Check you have permission to edit devices
- Look at browser console (F12 > Console tab) for error messages
- Try again in a few seconds
**Field still changes after locking:**
- Double-check the lock icon shows
- Reload the page—the change might be a display issue
- Check if you accidentally unlocked it
- Open an issue if it persists
## For More Information
## See also
- **Technical details:** See [API_DEVICE_FIELD_LOCK.md](API_DEVICE_FIELD_LOCK.md)
- **Plugin configuration:** See [PLUGINS_DEV_CONFIG.md](PLUGINS_DEV_CONFIG.md)
- **Admin guide:** See [DEVICE_MANAGEMENT.md](DEVICE_MANAGEMENT.md)
---
**Quick Start:** Find a device field you want to protect → Click the lock icon → That's it! The field won't change until you unlock it.
- [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)
- [Device locking APIs](API_DEVICE_FIELD_LOCK.md)
- [Device management](DEVICE_MANAGEMENT.md)

9
docs/DEVICE_MANAGEMENT.md
View File

@@ -49,6 +49,8 @@ To speed up device population you can also copy data from an existing device. Th
## Field Locking (Preventing Plugin Overwrites)
![Field source and locks](./img/DEVICE_MANAGEMENT/field_sources_and_locks.png)
NetAlertX allows you to "lock" specific device fields to prevent plugins from automatically overwriting your custom values. This is useful when you've manually corrected information that might be discovered differently by discovery plugins.
### Quick Start
@@ -57,14 +59,9 @@ NetAlertX allows you to "lock" specific device fields to prevent plugins from au
2. Click the **lock button** (🔒) next to any tracked field
3. The field is now protected—plugins cannot change it until you unlock it
### Tracked Fields
The following 10 fields support locking:
- devMac, devName, devLastIP, devVendor, devFQDN, devSSID, devParentMAC, devParentPort, devParentRelType, devVlan
### See Also
- **For Users:** [Quick Reference - Device Field Lock/Unlock](QUICK_REFERENCE_FIELD_LOCK.md) - How to use field locking
- **For Users:** [Quick Reference - Device Field Lock/Unlock](DEVICE_FIELD_LOCK.md) - How to use field locking
- **For Developers:** [API Device Field Lock Documentation](API_DEVICE_FIELD_LOCK.md) - Technical API reference
- **For Plugin Developers:** [Plugin Field Configuration (SET_ALWAYS/SET_EMPTY)](PLUGINS_DEV_CONFIG.md) - Configure which fields plugins can update

67
docs/DEVICE_SOURCE_FIELDS.md Normal file
View File

@@ -0,0 +1,67 @@
# Understanding Device Source Fields and Field Updates
When the system scans a network, it finds various details about devices (like names, IP addresses, and manufacturers). To ensure the data remains accurate without accidentally overwriting manual changes, the system uses a set of "Source Rules."
![Field source and locks](./img/DEVICE_MANAGEMENT/field_sources_and_locks.png)
---
## The "Protection" Levels
Every piece of information for a device has a **Source**. This source determines whether a new scan is allowed to change that value.
| Source Status | Description | Can a Scan Overwrite it? |
| --- | --- | --- |
| **USER** | You manually entered this value. | **Never** |
| **LOCKED** | This value is pinned and protected. | **Never** |
| **NEWDEV** | This value was initialized from `NEWDEV` plugin settings. | **Always** |
| **(Plugin Name)** | The value was found by a specific scanner (e.g., `NBTSCAN`). | **Only if specific rules are met** |
---
## How Scans Update Information
If a field is **not** protected by a `USER` or `LOCKED` status, the system follows these rules to decide if it should update the info:
### 1. The "Empty Field" Rule (Default)
By default, the system is cautious. It will only fill in a piece of information if the current field is **empty** (showing as "unknown," "0.0.0.0," or blank). It won't change for example an existing name unless you tell it to.
### 2. SET_ALWAYS
Some plugins are configured to be "authoritative." If a field is in the **SET_ALWAYS** setting of a plugin:
* The scanner will **always** overwrite the current value with the new one.
* *Note: It will still never overwrite a `USER` or `LOCKED` field.*
### 3. SET_EMPTY
If a field is in the **SET_EMPTY** list:
* The scanner will **only** provide a value if the current field is currently empty.
* This is used for fields where we want to "fill in the blanks" but never change a value once it has been established by any source.
### 4. Automatic Overrides (Live Tracking)
Some fields, like **IP Addresses** (`devLastIP`) and **Full Domain Names** (`devFQDN`), are set to automatically update whenever they change. This ensures that if a device moves to a new IP on your network, the system reflects that change immediately without you having to do anything.
---
## Summary of Field Logic
| If the current value is... | And the Scan finds... | Does it update? |
| --- | --- | --- |
| **USER / LOCKED** | Anything | **No** |
| **Empty** | A new value | **Yes** |
| **A "Plugin" value** | A different value | **No** (Unless `SET_ALWAYS` is on) |
| **An IP Address** | A different IP | **Yes** (Updates automatically) |
## 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)
- [Device locking APIs](API_DEVICE_FIELD_LOCK.md)
- [Device management](DEVICE_MANAGEMENT.md)

62
docs/DEV_ENV_SETUP.md
View File

@@ -8,26 +8,26 @@ Before starting development, please review the following guidelines.
### Priority Order (Highest to Lowest)
1. 🔼 Fixing core bugs that lack workarounds
2. 🔵 Adding core functionality that unlocks other features (e.g., plugins)
3. 🔵 Refactoring to enable faster development
4. 🔽 UI improvements (PRs welcome, but low priority)
1. 🔼 Fixing core bugs that lack workarounds
2. 🔵 Adding core functionality that unlocks other features (e.g., plugins)
3. 🔵 Refactoring to enable faster development
4. 🔽 UI improvements (PRs welcome, but low priority)
### Design Philosophy
The application architecture is designed for extensibility and maintainability. It relies heavily on configuration manifests via plugins and settings to dynamically build the UI and populate the application with data from various sources.
The application architecture is designed for extensibility and maintainability. It relies heavily on configuration manifests via plugins and settings to dynamically build the UI and populate the application with data from various sources.
For details, see:
- [Plugins Development](PLUGINS_DEV.md) (includes video)
- [Settings System](SETTINGS_SYSTEM.md)
For details, see:
- [Plugins Development](PLUGINS_DEV.md) (includes video)
- [Settings System](SETTINGS_SYSTEM.md)
Focus on **core functionality** and integrate with existing tools rather than reinventing the wheel.
Focus on **core functionality** and integrate with existing tools rather than reinventing the wheel.
Examples:
- Using **Apprise** for notifications instead of implementing multiple separate gateways
- Implementing **regex-based validation** instead of one-off validation for each setting
Examples:
- Using **Apprise** for notifications instead of implementing multiple separate gateways
- Implementing **regex-based validation** instead of one-off validation for each setting
> [!NOTE]
> [!NOTE]
> UI changes have lower priority. PRs are welcome, but please keep them **small and focused**.
## Development Environment Set Up
@@ -43,7 +43,7 @@ The following steps will guide you to set up your environment for local developm
### 1. Download the code:
- `mkdir /development`
- `cd /development && git clone https://github.com/jokob-sk/NetAlertX.git`
- `cd /development && git clone https://github.com/netalertx/NetAlertX.git`
### 2. Create a DEV .env_dev file
@@ -59,13 +59,13 @@ PORT=22222 # make sure this port is unique on your whole network
DEV_LOCATION=/development/NetAlertX
APP_DATA_LOCATION=/volume/docker_appdata
# Make sure your GRAPHQL_PORT setting has a port that is unique on your whole host network
APP_CONF_OVERRIDE={"GRAPHQL_PORT":"22223"}
APP_CONF_OVERRIDE={"GRAPHQL_PORT":"22223"}
# ALWAYS_FRESH_INSTALL=true # uncommenting this will always delete the content of /config and /db dirs on boot to simulate a fresh install
```
### 3. Create /db and /config dirs
### 3. Create /db and /config dirs
Create a folder `netalertx` in the `APP_DATA_LOCATION` (in this example in `/volume/docker_appdata`) with 2 subfolders `db` and `config`.
Create a folder `netalertx` in the `APP_DATA_LOCATION` (in this example in `/volume/docker_appdata`) with 2 subfolders `db` and `config`.
- `mkdir /volume/docker_appdata/netalertx`
- `mkdir /volume/docker_appdata/netalertx/db`
@@ -82,9 +82,9 @@ You can then modify the python script without restarting/rebuilding the containe
## Tips
A quick cheat sheet of useful commands.
A quick cheat sheet of useful commands.
### Removing the container and image
### Removing the container and image
A command to stop, remove the container and the image (replace `netalertx` and `netalertx-netalertx` with the appropriate values)
@@ -98,23 +98,23 @@ Most code changes can be tested without rebuilding the container. When working o
![image](./img/DEV/Maintenance_Logs_Restart_server.png)
2. If above doesn't work, SSH into the container and kill & restart the main script loop
2. If above doesn't work, SSH into the container and kill & restart the main script loop
- `sudo docker exec -it netalertx /bin/bash`
- `pkill -f "python /app/server" && python /app/server & `
3. If none of the above work, restart the docker container.
3. If none of the above work, restart the docker container.
- This is usually the last resort as sometimes the Docker engine becomes unresponsive and the whole engine needs to be restarted.
- This is usually the last resort as sometimes the Docker engine becomes unresponsive and the whole engine needs to be restarted.
## Contributing & Pull Requests
### Before submitting a PR, please ensure:
✔ Changes are **backward-compatible** with existing installs.
✔ No unnecessary changes are made.
✔ New features are **reusable**, not narrowly scoped.
✔ Features are implemented via **plugins** if possible.
✔ Changes are **backward-compatible** with existing installs.
✔ No unnecessary changes are made.
✔ New features are **reusable**, not narrowly scoped.
✔ Features are implemented via **plugins** if possible.
### Mandatory Test Cases
@@ -122,15 +122,15 @@ Most code changes can be tested without rebuilding the container. When working o
- Existing DB/config compatibility.
- Notification testing:
- Email
- Apprise (e.g., Telegram)
- Webhook (e.g., Discord)
- MQTT (e.g., Home Assistant)
- Email
- Apprise (e.g., Telegram)
- Webhook (e.g., Discord)
- MQTT (e.g., Home Assistant)
- Updating Settings and their persistence.
- Updating a Device
- Plugin functionality.
- Error log inspection.
> [!NOTE]
> [!NOTE]
> Always run all available tests as per the [Testing documentation](API_TESTS.md).

6
docs/DOCKER_COMPOSE.md
View File

@@ -17,7 +17,7 @@ services:
netalertx:
#use an environmental variable to set host networking mode if needed
container_name: netalertx # The name when you docker contiainer ls
image: ghcr.io/jokob-sk/netalertx:latest
image: ghcr.io/netalertx/netalertx:latest
network_mode: ${NETALERTX_NETWORK_MODE:-host} # Use host networking for ARP scanning and other services
read_only: true # Make the container filesystem read-only
@@ -27,6 +27,9 @@ services:
- NET_ADMIN # Required for ARP scanning
- NET_RAW # Required for raw socket operations
- NET_BIND_SERVICE # Required to bind to privileged ports (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:
- type: volume # Persistent Docker-managed named volume for config + database
@@ -78,7 +81,6 @@ services:
cpu_shares: 512 # Relative CPU weight for CPU contention scenarios
pids_limit: 512 # Limit the number of processes/threads to prevent fork bombs
logging:
driver: "json-file" # Use JSON file logging driver
options:
max-size: "10m" # Rotate log files after they reach 10MB
max-file: "3" # Keep a maximum of 3 log files

13
docs/DOCKER_INSTALLATION.md
View File

@@ -4,10 +4,11 @@
[![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 scanner & notification framework
# NetAlertX - Network Visibility & Asset Intelligence Framework
| [📑 Docker guide](https://docs.netalertx.com/DOCKER_INSTALLATION) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://docs.netalertx.com/) | [🔌 Plugins](https://docs.netalertx.com/PLUGINS) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
|----------------------| ----------------------| ----------------------| ----------------------| ----------------------|
---
### || [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)
---
<a href="https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/GENERAL/github_social_image.jpg" target="_blank">
<img src="https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/GENERAL/github_social_image.jpg" width="1000px" />
@@ -30,7 +31,7 @@ docker run -d --rm --network=host \
--tmpfs /tmp:uid=${NETALERTX_UID:-20211},gid=${NETALERTX_GID:-20211},mode=1700 \
-e PORT=20211 \
-e APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20214"} \
ghcr.io/jokob-sk/netalertx:latest
ghcr.io/netalertx/netalertx:latest
```
> Runtime UID/GID: The image defaults to a service user `netalertx` (UID/GID 20211). A separate readonly lock owner also uses UID/GID 20211 for 004/005 immutability. You can override the runtime UID/GID at build (ARG) or run (`--user` / compose `user:`) but must align writable mounts (`/data`, `/tmp*`) and tmpfs `uid/gid` to that choice.
@@ -120,8 +121,8 @@ You can read or watch several [community configuration guides](https://docs.neta
## 💙 Support me
| [![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`

13
docs/DOCKER_PORTAINER.md
View File

@@ -35,9 +35,9 @@ services:
netalertx:
container_name: netalertx
# Use this line for stable release
image: "ghcr.io/jokob-sk/netalertx:latest"
image: "ghcr.io/netalertx/netalertx:latest"
# Or, use this for the latest development build
# image: "ghcr.io/jokob-sk/netalertx-dev:latest"
# image: "ghcr.io/netalertx/netalertx-dev:latest"
network_mode: "host"
restart: unless-stopped
cap_drop: # Drop all capabilities for enhanced security
@@ -48,7 +48,7 @@ services:
- NET_BIND_SERVICE
- CHOWN
- SETUID
- SETGID
- SETGID
volumes:
- ${APP_FOLDER}/netalertx/config:/data/config
- ${APP_FOLDER}/netalertx/db:/data/db
@@ -72,6 +72,13 @@ In the **Environment variables** section of Portainer, add the following:
* `PORT=22022` (or another port if needed)
* `APP_CONF_OVERRIDE={"GRAPHQL_PORT":"22023"}` (optional advanced settings, otherwise the backend API server PORT defaults to `20212`)
Additional environment variables (advanced / testing):
* `SKIP_TESTS=1` — when set, the container entrypoint will skip all startup checks and print the message `Skipping startup checks as SKIP_TESTS is set.`. Useful for automated test runs or CI where the container should not perform environment-specific checks.
* `SKIP_STARTUP_CHECKS="<check names>"` — space-delimited list of specific startup checks to skip. Names are the human-friendly names derived from files in `/entrypoint.d` (remove the leading numeric prefix and file extension). Example: `SKIP_STARTUP_CHECKS="mandatory folders"` will skip `30-mandatory-folders.sh`.
Note: these variables are primarily useful for non-production scenarios (testing, CI, or specific deployments) and are processed by the entrypoint scripts. See `entrypoint.sh` and `entrypoint.d/*` for exact behaviour and available check names.
---
## 5. Ensure permissions

2
docs/DOCKER_SWARM.md
View File

@@ -44,7 +44,7 @@ Use the following Compose snippet to deploy NetAlertX with a **static LAN IP** a
```yaml
services:
netalertx:
image: ghcr.io/jokob-sk/netalertx:latest
image: ghcr.io/netalertx/netalertx:latest
...
networks:
swarm-ipvlan:

92
docs/FEATURES.md Normal file
View File

@@ -0,0 +1,92 @@
# NetAlertX Features Overview
NetAlertX is a lightweight, flexible platform for monitoring networks, tracking devices, and delivering actionable alerts. It combines discovery, change detection, and multi-channel notification into a single, streamlined solution.
---
## Network Discovery & Device Tracking
![Network Discovery & Device Tracking](./img/FEATURES/Network_Discovery_Device_Tracking.png)
- **Automatic Device Detection**: Continuously scans your local network to detect all connected devices via ARP, DHCP, SNMP, and compatible controllers.
- **Presence Monitoring**: Track when devices appear, disappear, or reconnect on the network.
- **IP & MAC Tracking**: Log device IP changes, ensuring accurate identification over time.
- **Import from Existing Systems**: Integrates with DHCP servers, Pi-hole, UniFi controllers, and other supported sources to maintain an accurate inventory.
---
## LAN Visualization
![LAN visualization](./img/FEATURES/LAN_Visualization.png)
- **Lightweight Network Map**: View a real-time representation of your local network with all connected devices.
- **Device Status Indicators**: Quickly identify active, missing, or new devices at a glance.
- **Interactive Overview**: Hover over devices to see IP, MAC, and last seen timestamps.
- **Change Highlighting**: Newly detected, disconnected, or reconnected devices are visually flagged to reduce oversight.
- **Simple & Efficient**: Designed for quick insights without heavy resource usage or complex topology maps.
---
## Event-Driven Alerts
![Event-Driven Alerts](./img/FEATURES/Event-Driven_Alerts.png)
- **Real-Time Notifications**: Receive immediate alerts for new devices, disconnected devices, or unexpected changes.
- **Customizable Filters and Rules**: Define rules based on device type, IP ranges, presence, or other network parameters.
- **Alert Deduplication & Suppression**: Avoid unnecessary noise with smart alert handling.
- **Historical Logs**: Maintain a complete timeline of network events for review and reporting.
---
## Workflows for implementing Business rules
![orkflows](./img/WORKFLOWS/workflows.png)
- **Custom rules**: Cretae custom flows and update device information based to scan results.
- **Customizable Triggers**: Define rules based on any device data, including device type, IP ranges, presence, or other network parameters.
- **Automated Updates**: Automate repetitive tasks, making network management more efficient.
---
## Multi-Channel Notification
![Multi-Channel Notification](./img/FEATURES/Multi-Channel_Notifications.png)
- **Flexible Delivery Options**: Send alerts via email, webhooks, MQTT, and more.
- **Integration with Automation**: Connect to ticketing systems, workflow engines, and custom scripts for automated responses.
- **Apprise Support**: Utilize over 80 pre-built notification services without additional configuration.
---
## Security & Compliance-Friendly Logging
![Events](./img/FEATURES/Events.png)
- **Device Accountability**: Maintain an auditable record of every device that appears or disappears from the network.
- **Change Tracking**: Document network events with timestamps for review and compliance reporting.
- **Rogue Device Alerts**: Detect and respond to unexpected or unauthorized network connections.
---
## MCP Server and OpenAPI
![MCP Server](./img/FEATURES/MCP_Server.png)
- **Data Access & Interaction**: The MCP server provides full programmatic access to NetAlertX, allowing you to query, monitor, and interact with network and device data.
- **OpenAPI Integration**: Use the OpenAPI interface to fetch device status, network events, and logs, or trigger actions and alerts programmatically.
- **Full Transparency**: All scan results, logs, and device information are accessible via the API, enabling auditing, automation, or integration with external systems.
- **Flexible & Reliable**: Structured API access ensures predictable, repeatable interactions while allowing real-time data monitoring and operational control.
---
## Extensible & Open Source
![Plugins](./img/plugins_json_settings.png)
- **Plugin System**: Extend discovery methods, ingestion types, or notification channels through modular plugins.
- **Community Contributions**: Open-source architecture encourages collaboration and improvements.
- **Full Transparency**: All logs, scans, and configurations are visible for analysis.
---
NetAlertX provides a centralized, proactive approach to network awareness, combining device visibility, event-driven alerting, and flexible notifications into a single, deployable solution. Its design prioritizes efficiency, clarity, and actionable insights, making it ideal for monitoring dynamic environments.

6
docs/FILE_PERMISSIONS.md
View File

@@ -12,7 +12,7 @@ docker run --rm --network=host \
-v /etc/localtime:/etc/localtime:ro \
--tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
-e PORT=20211 \
ghcr.io/jokob-sk/netalertx:latest
ghcr.io/netalertx/netalertx:latest
```
> [!WARNING]
@@ -70,7 +70,7 @@ If you use a custom `PUID` (e.g. `0`) and `GUID` (e.g. `100`) make sure you also
docker run -it --rm --name netalertx --user "0" \
-v /local_data_dir:/data \
--tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
ghcr.io/jokob-sk/netalertx:latest
ghcr.io/netalertx/netalertx:latest
```
2. Wait for logs showing **permissions being fixed**. The container will then **hang intentionally**.
@@ -95,7 +95,7 @@ docker run -it --rm --name netalertx --user "0" \
services:
netalertx:
container_name: netalertx
image: "ghcr.io/jokob-sk/netalertx"
image: "ghcr.io/netalertx/netalertx"
network_mode: "host"
cap_drop: # Drop all capabilities for enhanced security
- ALL

9
docs/FIX_OFFLINE_DETECTION.md
View File

@@ -42,7 +42,10 @@ ARPSCAN_DURATION=30
### ✅ Add ICMP (Ping) Scanning
Enable the `ICMP` scan plugin to complement ARP detection. ICMP is often more reliable for detecting active hosts, especially when ARP fails.
Enable the `ICMP` scan plugin to complement ARP detection. ICMP is often more reliable for detecting active hosts, especially when ARP fails.
> [!IMPORTANT]
> If using AdGuard/Pi-hole: If devices still show offline after enabling ICMP, temporarily disable your content blocker. If the issue disappears, whitelist the NetAlertX host IP in your blocker's settings to prevent pings from being dropped.
### ✅ Use Multiple Detection Methods
@@ -52,7 +55,7 @@ A combined approach greatly improves detection robustness:
* `ICMP` (ping)
* `NMAPDEV` (nmap)
This hybrid strategy increases reliability, especially for down detection and alerting. See [other plugins](./PLUGINS.md) that might be compatible with your setup. See benefits and drawbacks of individual scan methods in their respective docs.
This hybrid strategy increases reliability, especially for down detection and alerting. See [other plugins](./PLUGINS.md) that might be compatible with your setup. See benefits and drawbacks of individual scan methods in their respective docs.
## Results
@@ -76,4 +79,4 @@ After increasing the ARP timeout and adding ICMP scanning (on select IP ranges),
Let us know in the [NetAlertX Discussions](https://github.com/jokob-sk/NetAlertX/discussions) if you have further feedback or edge cases.
See also [Remote Networks](./REMOTE_NETWORKS.md) for more advanced setups.
See also [Remote Networks](./REMOTE_NETWORKS.md) for more advanced setups.

3
docs/INSTALLATION.md
View File

@@ -8,11 +8,12 @@ NetAlertX can be installed several ways. The best supported option is Docker, fo
- [[Installation] Home Assistant](https://github.com/alexbelgium/hassio-addons/tree/master/netalertx)
- [[Installation] Unraid App](https://unraid.net/community/apps)
- [[Installation] Bare metal (experimental - looking for maintainers)](https://docs.netalertx.com/HW_INSTALL)
- [[Installation] Nix flake (community supported)](https://github.com/netalertx/NetAlertX/blob/main/install/nix/flake.nix) submitted by [2m](https://github.com/2m)
## Help
If facing issues, please spend a few minutes seraching.
If facing issues, please spend a few minutes searching.
- Check [common issues](./COMMON_ISSUES.md)
- Have a look at [Community guides](./COMMUNITY_GUIDES.md)

2
docs/MIGRATION.md
View File

@@ -318,7 +318,7 @@ As per user feedback, we’ve re-introduced the ability to control which user th
services:
netalertx:
container_name: netalertx
image: "ghcr.io/jokob-sk/netalertx"
image: "ghcr.io/netalertx/netalertx"
network_mode: "host"
cap_drop:
- ALL

4
docs/PERFORMANCE.md
View File

@@ -80,9 +80,9 @@ services:
netalertx:
container_name: netalertx
# Use this line for the stable release
image: "ghcr.io/jokob-sk/netalertx:latest"
image: "ghcr.io/netalertx/netalertx:latest"
# Or use this line for the latest development build
# image: "ghcr.io/jokob-sk/netalertx-dev:latest"
# image: "ghcr.io/netalertx/netalertx-dev:latest"
network_mode: "host"
restart: unless-stopped

4
docs/PLUGINS_DEV.md
View File

@@ -268,7 +268,7 @@ To import plugin data into NetAlertX tables for device discovery or notification
"database_column_definitions": [
{
"column": "Object_PrimaryID",
"mapped_to_column": "cur_MAC",
"mapped_to_column": "scanMac",
"show": true,
"type": "device_mac",
"localized": ["name"],
@@ -287,7 +287,7 @@ To always map a static value (not read from plugin output):
```json
{
"column": "NameDoesntMatter",
"mapped_to_column": "cur_ScanMethod",
"mapped_to_column": "scanSourcePlugin",
"mapped_to_column_data": {
"value": "MYPLN"
}

14
docs/PLUGINS_DEV_UI_COMPONENTS.md
View File

@@ -440,7 +440,7 @@ To import plugin data into the device scan pipeline (for notifications, heuristi
"database_column_definitions": [
{
"column": "Object_PrimaryID",
"mapped_to_column": "cur_MAC",
"mapped_to_column": "scanMac",
"show": true,
"type": "device_mac",
"localized": ["name"],
@@ -448,7 +448,7 @@ To import plugin data into the device scan pipeline (for notifications, heuristi
},
{
"column": "Object_SecondaryID",
"mapped_to_column": "cur_IP",
"mapped_to_column": "scanLastIP",
"show": true,
"type": "device_ip",
"localized": ["name"],
@@ -456,7 +456,7 @@ To import plugin data into the device scan pipeline (for notifications, heuristi
},
{
"column": "NameDoesntMatter",
"mapped_to_column": "cur_ScanMethod",
"mapped_to_column": "scanSourcePlugin",
"mapped_to_column_data": {
"value": "MYSCAN"
},
@@ -478,7 +478,7 @@ Use `mapped_to_column_data` to map a static value instead of reading from a colu
```json
{
"column": "NameDoesntMatter",
"mapped_to_column": "cur_ScanMethod",
"mapped_to_column": "scanSourcePlugin",
"mapped_to_column_data": {
"value": "MYSCAN"
},
@@ -489,7 +489,7 @@ Use `mapped_to_column_data` to map a static value instead of reading from a colu
}
```
This always sets `cur_ScanMethod` to `"MYSCAN"` regardless of column data.
This always sets `scanSourcePlugin` to `"MYSCAN"` regardless of column data.
---
@@ -546,7 +546,7 @@ When viewing a device detail page, the `txtMacFilter` field is populated with th
"database_column_definitions": [
{
"column": "Object_PrimaryID",
"mapped_to_column": "cur_MAC",
"mapped_to_column": "scanMac",
"css_classes": "col-sm-2",
"show": true,
"type": "device_mac",
@@ -556,7 +556,7 @@ When viewing a device detail page, the `txtMacFilter` field is populated with th
},
{
"column": "Object_SecondaryID",
"mapped_to_column": "cur_IP",
"mapped_to_column": "scanLastIP",
"css_classes": "col-sm-2",
"show": true,
"type": "device_ip",

12
docs/REMOTE_NETWORKS.md
View File

@@ -13,9 +13,17 @@ The following network setups might make some devices undetectable with `ARPSCAN`
### Wi-Fi Extenders
Wi-Fi extenders typically create a separate network or subnet, which can prevent network scanning tools like `arp-scan` from detecting devices behind the extender.
Wi-Fi extenders often **block or proxy Layer-2 broadcast traffic**, which can prevent network scanning tools like `arp-scan` from detecting devices behind the extender. This can happen **even when the extender uses the same SSID and the same IP subnet** as the main network.
> **Possible workaround**: Scan the specific subnet that the extender uses, if it is separate from the main network.
Please note that being able to `ping` a device does **not** mean it is discoverable via `arp-scan`.
* `arp-scan` relies on **Layer 2 (ARP broadcast)**
* ICMP (`ping`) operates at **Layer 3 (routed traffic)**
That’s why devices behind extenders may respond to ping but remain undiscoverable via `arp-scan`.
> **Possible workaround**:
> If the extender uses a separate subnet, scan that subnet directly. Otherwise, use DHCP-based discovery plugins or router integration instead of ARP. See the **Other Workarounds** section below for more details.
### VPNs

2
docs/REVERSE_DNS.md
View File

@@ -39,7 +39,7 @@ You can specify the DNS server in the docker-compose to improve name resolution
services:
netalertx:
container_name: netalertx
image: "ghcr.io/jokob-sk/netalertx:latest"
image: "ghcr.io/netalertx/netalertx:latest"
...
dns: # specifying the DNS servers used for the container
- 10.8.0.1

898
docs/REVERSE_PROXY.md
View File

@@ -3,13 +3,23 @@
> [!NOTE]
> This is community-contributed. Due to environment, setup, or networking differences, results may vary. Please open a PR to improve it instead of creating an issue, as the maintainer is not actively maintaining it.
> [!NOTE]
> NetAlertX requires access to both the **web UI** (default `20211`) and the **GraphQL backend `GRAPHQL_PORT`** (default `20212`) ports.
> Ensure your reverse proxy allows traffic to both for proper functionality.
> [!TIP]
> You will need to specify the `BACKEND_API_URL` setting if you are running reverse proxies. This is the URL that points to the backend server url (including your `GRAPHQL_PORT`)
> [!IMPORTANT]
> You will need to specify 2 entries in your reverse proxy, one for the front end, one for the backend URL. The custom backend URL, including the `GRAPHQL_PORT`, needs to be aslo specified in the `BACKEND_API_URL` setting.This is the URL that points to the backend API server.
>
> ![BACKEND_API_URL setting](./img/REVERSE_PROXY/BACKEND_API_URL.png)
>
> ![NPM set up](./img/REVERSE_PROXY/nginx_proxy_manager_npm.png)
See also:
- [CADDY + AUTHENTIK](./REVERSE_PROXY_CADDY.md)
- [TRAEFIK](./REVERSE_PROXY_TRAEFIK.md)
## NGINX HTTP Configuration (Direct Path)
> Submitted by amazing [cvc90](https://github.com/cvc90) 🙏
@@ -513,888 +523,4 @@ Mapping the updated file (on the local filesystem at `/appl/docker/netalertx/def
...
```
## Caddy + Authentik Outpost Proxy SSO
> Submitted by [luckylinux](https://github.com/luckylinux) 🙏.
### Introduction
This Setup assumes:
1. Authentik Installation running on a separate Host at `https://authentik.MYDOMAIN.TLD`
2. Container Management is done on Baremetal OR in a Virtual Machine (KVM/Xen/ESXi/..., no LXC Containers !):
i. Docker and Docker Compose configured locally running as Root (needed for `network_mode: host`) OR
ii. Podman (optionally `podman-compose`) configured locally running as Root (needed for `network_mode: host`)
3. TLS Certificates are already pre-obtained and located at `/var/lib/containers/certificates/letsencrypt/MYDOMAIN.TLD`.
I use the `certbot/dns-cloudflare` Podman Container on a separate Host to obtain the Certificates which I then distribute internally.
This Container uses the Wildcard Top-Level Domain Certificate which is valid for `MYDOMAIN.TLD` and `*.MYDOMAIN.TLD`.
4. Proxied Access
i. NetAlertX Web Interface is accessible via Caddy Reverse Proxy at `https://netalertx.MYDOMAIN.TLD` (default HTTPS Port 443: `https://netalertx.MYDOMAIN.TLD:443`) with `REPORT_DASHBOARD_URL=https://netalertx.MYDOMAIN.TLD`
ii. NetAlertX GraphQL Interface is accessible via Caddy Reverse Proxy at `https://netalertx.MYDOMAIN.TLD:20212` with `BACKEND_API_URL=https://netalertx.MYDOMAIN.TLD:20212`
iii. Authentik Proxy Outpost is accessible via Caddy Reverse Proxy at `https://netalertx.MYDOMAIN.TLD:9443`
5. Internal Ports
i. NGINX Web Server is set to listen on internal Port 20211 set via `PORT=20211`
ii. Python Web Server is set to listen on internal Port `GRAPHQL_PORT=20219`
iii. Authentik Proxy Outpost is listening on internal Port `AUTHENTIK_LISTEN__HTTP=[::1]:6000` (unencrypted) and Port `AUTHENTIK_LISTEN__HTTPS=[::1]:6443` (encrypted)
8. Some further Configuration for Caddy is performed in Terms of Logging, SSL Certificates, etc
It's also possible to [let Caddy automatically request & keep TLS Certificates up-to-date](https://caddyserver.com/docs/automatic-https), although please keep in mind that:
1. You risk enumerating your LAN. Every Domain/Subdomain for which Caddy requests a TLS Certificate for you will result in that Host to be listed on [List of Letsencrypt Certificates issued](https://crt.sh/).
2. You need to either:
i. Open Port 80 for external Access ([HTTP challenge](https://caddyserver.com/docs/automatic-https#http-challenge)) in order for Letsencrypt to verify the Ownership of the Domain/Subdomain
ii. Open Port 443 for external Access ([TLS-ALPN challenge](https://caddyserver.com/docs/automatic-https#tls-alpn-challenge)) in order for Letsencrypt to verify the Ownership of the Domain/Subdomain
iii. Give Caddy the Credentials to update the DNS Records at your DNS Provider ([DNS challenge](https://caddyserver.com/docs/automatic-https#dns-challenge))
You can also decide to deploy your own Certificates & Certification Authority, either manually with OpenSSL, or by using something like [mkcert](https://github.com/FiloSottile/mkcert).
In Terms of IP Stack Used:
- External: Caddy listens on both IPv4 and IPv6.
- Internal:
- Authentik Outpost Proxy listens on IPv6 `[::1]`
- NetAlertX listens on IPv4 `0.0.0.0`
### Flow
The Traffic Flow will therefore be as follows:
- Web GUI:
i. Client accesses `http://authentik.MYDOMAIN.TLD:80`: default (built-in Caddy) Redirect to `https://authentik.MYDOMAIN.TLD:443`
ii. Client accesses `https://authentik.MYDOMAIN.TLD:443` -> reverse Proxy to internal Port 20211 (NetAlertX Web GUI / NGINX - unencrypted)
- GraphQL: Client accesses `https://authentik.MYDOMAIN.TLD:20212` -> reverse Proxy to internal Port 20219 (NetAlertX GraphQL - unencrypted)
- Authentik Outpost: Client accesses `https://authentik.MYDOMAIN.TLD:9443` -> reverse Proxy to internal Port 6000 (Authentik Outpost Proxy - unencrypted)
An Overview of the Flow is provided in the Picture below:
![Reverse Proxy Traffic Flow with Authentik SSSO](./img/REVERSE_PROXY/reverse_proxy_flow.svg)
### Security Considerations
#### Caddy should be run rootless
> [!WARNING]
> By default Caddy runs as `root` which is a Security Risk.
> In order to solve this, it's recommended to create an unprivileged User `caddy` and Group `caddy` on the Host:
> ```
> groupadd --gid 980 caddy
> useradd --shell /usr/sbin/nologin --gid 980 --uid 980 -c "Caddy web server" --base-dir /var/lib/caddy
> ```
At least using Quadlets with Usernames (NOT required with UID/GID), but possibly using Compose in certain Cases as well, a custom `/etc/passwd` and `/etc/group` might need to be bind-mounted inside the Container.
`passwd`:
```
root:x:0:0:root:/root:/bin/sh
bin:x:1:1:bin:/bin:/sbin/nologin
daemon:x:2:2:daemon:/sbin:/sbin/nologin
lp:x:4:7:lp:/var/spool/lpd:/sbin/nologin
sync:x:5:0:sync:/sbin:/bin/sync
shutdown:x:6:0:shutdown:/sbin:/sbin/shutdown
halt:x:7:0:halt:/sbin:/sbin/halt
mail:x:8:12:mail:/var/mail:/sbin/nologin
news:x:9:13:news:/usr/lib/news:/sbin/nologin
uucp:x:10:14:uucp:/var/spool/uucppublic:/sbin/nologin
cron:x:16:16:cron:/var/spool/cron:/sbin/nologin
ftp:x:21:21::/var/lib/ftp:/sbin/nologin
sshd:x:22:22:sshd:/dev/null:/sbin/nologin
games:x:35:35:games:/usr/games:/sbin/nologin
ntp:x:123:123:NTP:/var/empty:/sbin/nologin
guest:x:405:100:guest:/dev/null:/sbin/nologin
nobody:x:65534:65534:nobody:/:/sbin/nologin
caddy:x:980:980:caddy:/var/lib/caddy:/bin/sh
```
`group`:
```
root:x:0:root
bin:x:1:root,bin,daemon
daemon:x:2:root,bin,daemon
sys:x:3:root,bin
adm:x:4:root,daemon
tty:x:5:
disk:x:6:root
lp:x:7:lp
kmem:x:9:
wheel:x:10:root
floppy:x:11:root
mail:x:12:mail
news:x:13:news
uucp:x:14:uucp
cron:x:16:cron
audio:x:18:
cdrom:x:19:
dialout:x:20:root
ftp:x:21:
sshd:x:22:
input:x:23:
tape:x:26:root
video:x:27:root
netdev:x:28:
kvm:x:34:kvm
games:x:35:
shadow:x:42:
www-data:x:82:
users:x:100:games
ntp:x:123:
abuild:x:300:
utmp:x:406:
ping:x:999:
nogroup:x:65533:
nobody:x:65534:
caddy:x:980:
```
#### Authentication of GraphQL Endpoint
> [!WARNING]
> Currently the GraphQL Endpoint is NOT authenticated !
### Environment Files
Depending on the Preference of the User (Environment Variables defined in Compose/Quadlet or in external `.env` File[s]), it might be prefereable to place at least some Environment Variables in external `.env` and `.env.<application>` Files.
The following is proposed:
- `.env`: common Settings (empty by Default)
- `.env.caddy`: Caddy Settings
- `.env.server`: NetAlertX Server/Application Settings
- `.env.outpost.proxy`: Authentik Proxy Outpost Settings
The following Contents is assumed.
`.env.caddy`:
```
# Define Application Hostname
APPLICATION_HOSTNAME=netalertx.MYDOMAIN.TLD
# Define Certificate Domain
# In this case: use Wildcard Certificate
APPLICATION_CERTIFICATE_DOMAIN=MYDOMAIN.TLD
APPLICATION_CERTIFICATE_CERT_FILE=fullchain.pem
APPLICATION_CERTIFICATE_KEY_FILE=privkey.pem
# Define Outpost Hostname
OUTPOST_HOSTNAME=netalertx.MYDOMAIN.TLD
# Define Outpost External Port (TLS)
OUTPOST_EXTERNAL_PORT=9443
```
`.env.server`:
```
PORT=20211
PORT_SSL=443
NETALERTX_NETWORK_MODE=host
LISTEN_ADDR=0.0.0.0
GRAPHQL_PORT=20219
NETALERTX_DEBUG=1
BACKEND_API_URL=https://netalertx.MYDOMAIN.TLD:20212
```
`.env.outpost.proxy`:
```
AUTHENTIK_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
AUTHENTIK_LISTEN__HTTP=[::1]:6000
AUTHENTIK_LISTEN__HTTPS=[::1]:6443
```
### Compose Setup
```
version: "3.8"
services:
netalertx-caddy:
container_name: netalertx-caddy
network_mode: host
image: docker.io/library/caddy:latest
pull: missing
env_file:
- .env
- .env.caddy
environment:
CADDY_DOCKER_CADDYFILE_PATH: "/etc/caddy/Caddyfile"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro,z
- /var/lib/containers/data/netalertx/caddy:/data/caddy:rw,z
- /var/lib/containers/log/netalertx/caddy:/var/log:rw,z
- /var/lib/containers/config/netalertx/caddy:/config/caddy:rw,z
- /var/lib/containers/certificates/letsencrypt:/certificates:ro,z
# Set User
user: "caddy:caddy"
# Automatically restart Container
restart: unless-stopped
netalertx-server:
container_name: netalertx-server # The name when you docker contiainer ls
network_mode: host # Use host networking for ARP scanning and other services
depends_on:
netalertx-caddy:
condition: service_started
restart: true
netalertx-outpost-proxy:
condition: service_started
restart: true
# Local built Image including latest Changes
image: localhost/netalertx-dev:dev-20260109-232454
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:
# Override NGINX Configuration Template
- type: bind
source: /var/lib/containers/config/netalertx/server/nginx/netalertx.conf.template
target: /services/config/nginx/netalertx.conf.template
read_only: true
bind:
selinux: Z
# Letsencrypt Certificates
- type: bind
source: /var/lib/containers/certificates/letsencrypt/MYDOMAIN.TLD
target: /certificates
read_only: true
bind:
selinux: Z
# Data Storage for NetAlertX
- type: bind # Persistent Docker-managed Named Volume for storage
source: /var/lib/containers/data/netalertx/server
target: /data # consolidated configuration and database storage
read_only: false # writable volume
bind:
selinux: Z
# Set the Timezone
- type: bind # Bind mount for timezone consistency
source: /etc/localtime
target: /etc/localtime
read_only: true
bind:
selinux: Z
# 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
- type: tmpfs
target: /tmp
tmpfs-mode: 1700
uid: 0
gid: 0
rw: true
noexec: true
nosuid: true
nodev: true
async: true
noatime: true
nodiratime: true
bind:
selinux: Z
env_file:
- .env
- .env.server
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
PORT_SSL: ${PORT_SSL:-443}
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.
BACKEND_API_URL: ${BACKEND_API_URL-"https://netalertx.MYDOMAIN.TLD:20212"}
# Resource limits to prevent resource exhaustion
mem_limit: 4096m # Maximum memory usage
mem_reservation: 2048m # 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:
driver: "json-file" # Use JSON file logging driver
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
# To sign Out, you need to visit
# {$OUTPOST_HOSTNAME}:{$OUTPOST_EXTERNAL_PORT}/outpost.goauthentik.io/sign_out
netalertx-outpost-proxy:
container_name: netalertx-outpost-proxy
network_mode: host
depends_on:
netalertx-caddy:
condition: service_started
restart: true
restart: unless-stopped
image: ghcr.io/goauthentik/proxy:2025.10
pull: missing
env_file:
- .env
- .env.outpost.proxy
environment:
AUTHENTIK_HOST: "https://authentik.MYDOMAIN.TLD"
AUTHENTIK_INSECURE: false
AUTHENTIK_LISTEN__HTTP: "[::1]:6000"
AUTHENTIK_LISTEN__HTTPS: "[::1]:6443"
```
### Quadlet Setup
`netalertx.pod`:
```
[Pod]
# Name of the Pod
PodName=netalertx
# Network Mode Host is required for ARP to work
Network=host
# Automatically start Pod at Boot Time
[Install]
WantedBy=default.target
```
`netalertx-caddy.container`:
```
[Unit]
Description=NetAlertX Caddy Container
[Service]
Restart=always
[Container]
ContainerName=netalertx-caddy
Pod=netalertx.pod
StartWithPod=true
# Generic Environment Configuration
EnvironmentFile=.env
# Caddy Specific Environment Configuration
EnvironmentFile=.env.caddy
Environment=CADDY_DOCKER_CADDYFILE_PATH=/etc/caddy/Caddyfile
Image=docker.io/library/caddy:latest
Pull=missing
# Run as rootless
# Specifying User & Group by Name requires to mount a custom passwd & group File inside the Container
# Otherwise an Error like the following will result: netalertx-caddy[593191]: Error: unable to find user caddy: no matching entries in passwd file
# User=caddy
# Group=caddy
# Volume=/var/lib/containers/config/netalertx/caddy-rootless/passwd:/etc/passwd:ro,z
# Volume=/var/lib/containers/config/netalertx/caddy-rootless/group:/etc/group:ro,z
# Run as rootless
# Specifying User & Group by UID/GID will NOT require a custom passwd / group File to be bind-mounted inside the Container
User=980
Group=980
Volume=./Caddyfile:/etc/caddy/Caddyfile:ro,z
Volume=/var/lib/containers/data/netalertx/caddy:/data/caddy:z
Volume=/var/lib/containers/log/netalertx/caddy:/var/log:z
Volume=/var/lib/containers/config/netalertx/caddy:/config/caddy:z
Volume=/var/lib/containers/certificates/letsencrypt:/certificates:ro,z
```
`netalertx-server.container`:
```
[Unit]
Description=NetAlertX Server Container
Requires=netalertx-caddy.service netalertx-outpost-proxy.service
After=netalertx-caddy.service netalertx-outpost-proxy.service
[Service]
Restart=always
[Container]
ContainerName=netalertx-server
Pod=netalertx.pod
StartWithPod=true
# Local built Image including latest Changes
Image=localhost/netalertx-dev:dev-20260109-232454
Pull=missing
# Make the container filesystem read-only
ReadOnly=true
# Drop all capabilities for enhanced security
DropCapability=ALL
# It is most secure to start with user 20211, but then we lose provisioning capabilities.
# User=20211:20211
# Required for scanning with arp-scan, nmap, nbtscan, traceroute, and zero-conf
AddCapability=NET_ADMIN
# Required for raw socket operations with arp-scan, nmap, nbtscan, traceroute and zero-conf
AddCapability=NET_RAW
# Required to bind to privileged ports with nbtscan
AddCapability=NET_BIND_SERVICE
# Required for root-entrypoint to chown /data + /tmp before dropping privileges
AddCapability=CHOWN
# Required for root-entrypoint to switch to non-root user
AddCapability=SETUID
# Required for root-entrypoint to switch to non-root group
AddCapability=SETGID
# Override the Configuration Template
Volume=/var/lib/containers/config/netalertx/server/nginx/netalertx.conf.template:/services/config/nginx/netalertx.conf.template:ro,Z
# Letsencrypt Certificates
Volume=/var/lib/containers/certificates/letsencrypt/MYDOMAIN.TLD:/certificates:ro,Z
# Data Storage for NetAlertX
Volume=/var/lib/containers/data/netalertx/server:/data:rw,Z
# Set the Timezone
Volume=/etc/localtime:/etc/localtime:ro,Z
# 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
# Mount=type=tmpfs,destination=/tmp,tmpfs-mode=1700,uid=0,gid=0,rw=true,noexec=true,nosuid=true,nodev=true,async=true,noatime=true,nodiratime=true,relabel=private
Mount=type=tmpfs,destination=/tmp,tmpfs-mode=1700,rw=true,noexec=true,nosuid=true,nodev=true
# Environment Configuration
EnvironmentFile=.env
EnvironmentFile=.env.server
# Runtime UID after priming (Synology/no-copy-up safe)
Environment=PUID=20211
# Runtime GID after priming (Synology/no-copy-up safe)
Environment=PGID=20211
# Listen for connections on all interfaces (IPv4)
Environment=LISTEN_ADDR=0.0.0.0
# Application port
Environment=PORT=20211
# SSL Port
Environment=PORT_SSL=443
# GraphQL API port
Environment=GRAPHQL_PORT=20212
# Set to true to reset your config and database on each container start
Environment=ALWAYS_FRESH_INSTALL=false
# 0=kill all services and restart if any dies. 1 keeps running dead services.
Environment=NETALERTX_DEBUG=0
# Set the GraphQL URL for external Access (via Caddy Reverse Proxy)
Environment=BACKEND_API_URL=https://netalertx-fedora.MYDOMAIN.TLD:20212
# Resource limits to prevent resource exhaustion
# Maximum memory usage
Memory=4g
# Limit the number of processes/threads to prevent fork bombs
PidsLimit=512
# Relative CPU weight for CPU contention scenarios
PodmanArgs=--cpus=2
PodmanArgs=--cpu-shares=512
# Soft memory limit
PodmanArgs=--memory-reservation=2g
# !! The following Keys are unfortunately not [yet] supported !!
# Relative CPU weight for CPU contention scenarios
#CpuShares=512
# Soft memory limit
#MemoryReservation=2g
```
`netalertx-outpost-proxy.container`:
```
[Unit]
Description=NetAlertX Authentik Proxy Outpost Container
Requires=netalertx-caddy.service
After=netalertx-caddy.service
[Service]
Restart=always
[Container]
ContainerName=netalertx-outpost-proxy
Pod=netalertx.pod
StartWithPod=true
# General Configuration
EnvironmentFile=.env
# Authentik Outpost Proxy Specific Configuration
EnvironmentFile=.env.outpost.proxy
Environment=AUTHENTIK_HOST=https://authentik.MYDOMAIN.TLD
Environment=AUTHENTIK_INSECURE=false
# Overrides Value from .env.outpost.rac
# Environment=AUTHENTIK_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
# Optional setting to be used when `authentik_host` for internal communication doesn't match the public URL
# Environment=AUTHENTIK_HOST_BROWSER=https://authentik.MYDOMAIN.TLD
# Container Image
Image=ghcr.io/goauthentik/proxy:2025.10
Pull=missing
# Network Configuration
Network=container:supermicro-ikvm-pve031-caddy
# Security Configuration
NoNewPrivileges=true
```
### Firewall Setup
Depending on which GNU/Linux Distribution you are running, it might be required to open up some Firewall Ports in order to be able to access the Endpoints from outside the Host itself.
This is for instance the Case for Fedora Linux, where I had to open:
- Port 20212 for external GraphQL Access (both TCP & UDP are open, unsure if UDP is required)
- Port 9443 for external Authentik Outpost Proxy Access (both TCP & UDP are open, unsure if UDP is required)
![Fedora Firewall Configuration](./img/REVERSE_PROXY/fedora-firewall.png)
### Authentik Setup
In order to enable Single Sign On (SSO) with Authentik, you will need to create a Provider, an Application and an Outpost.
![Authentik Left Sidebar](./img/REVERSE_PROXY/authentik-sidebar.png)
First of all, using the Left Sidebar, navigate to `Applications` &#8594; `Providers`, click on `Create` (Blue Button at the Top of the Screen), select `Proxy Provider`, then click `Next`:
![Authentik Provider Setup (Part 1)](./img/REVERSE_PROXY/authentik-provider-setup-01.png)
Fill in the required Fields:
- Name: choose a Name for the Provider (e.g. `netalertx`)
- Authorization Flow: choose the Authorization Flow. I typically use `default-provider-authorization-implicit-consent (Authorize Application)`. If you select the `default-provider-authorization-explicit-consent (Authorize Application)` you will need to authorize Authentik every Time you want to log in NetAlertX, which can make the Experience less User-friendly
- Type: Click on `Forward Auth (single application)`
- External Host: set to `https://netalertx.MYDOMAIN.TLD`
Click `Finish`.
![Authentik Provider Setup (Part 2)](./img/REVERSE_PROXY/authentik-provider-setup-02.png)
Now, using the Left Sidebar, navigate to `Applications` &#8594; `Applications`, click on `Create` (Blue Button at the Top of the Screen) and fill in the required Fields:
- Name: choose a Name for the Application (e.g. `netalertx`)
- Slug: choose a Slug for the Application (e.g. `netalertx`)
- Group: optionally you can assign this Application to a Group of Applications of your Choosing (for grouping Purposes within Authentik User Interface)
- Provider: select the Provider you created the the `Providers` Section previosly (e.g. `netalertx`)
Then click `Create`.
![Authentik Application Setup (Part 1)](./img/REVERSE_PROXY/authentik-application-setup-01.png)
Now, using the Left Sidebar, navigate to `Applications` &#8594; `Outposts`, click on `Create` (Blue Button at the Top of the Screen) and fill in the required Fields:
- Name: choose a Name for the Outpost (e.g. `netalertx`)
- Type: `Proxy`
- Integration: open the Dropdown and click on `---------`. Make sure it is NOT set to `Local Docker connection` !
In the `Available Applications` Section, select the Application you created in the Previous Step, then click the right Arrow (approx. located in the Center of the Screen), so that it gets copied in the `Selected Applications` Section.
Then click `Create`.
![Authentik Outpost Setup (Part 1)](./img/REVERSE_PROXY/authentik-outpost-setup-01.png)
Wait a few Seconds for the Outpost to be created. Once it appears in the List, click on `Deployment Info` on the Right Side of the relevant Line.
![Authentik Outpost Setup (Part 2)](./img/REVERSE_PROXY/authentik-outpost-setup-02.png)
Take note of that Token. You will need it for the Authentik Outpost Proxy Container, which will read it as the `AUTHENTIK_TOKEN` Environment Variable.
### NGINX Configuration inside NetAlertX Container
> [!NOTE]
> This is something that was implemented based on the previous Content of this Reverse Proxy Document.
> Due to some Buffer Warnings/Errors in the Logs as well as some other Issues I was experiencing, I increased a lot the client_body_buffer_size and large_client_header_buffers Parameters, although these might not be required anymore.
> Further Testing might be required.
```
# Set number of worker processes automatically based on number of CPU cores.
worker_processes auto;
# Enables the use of JIT for regular expressions to speed-up their processing.
pcre_jit on;
# Configures default error logger.
error_log /tmp/log/nginx-error.log warn;
pid /tmp/run/nginx.pid;
events {
# The maximum number of simultaneous connections that can be opened by
# a worker process.
worker_connections 1024;
}
http {
# Mapping of temp paths for various nginx modules.
client_body_temp_path /tmp/nginx/client_body;
proxy_temp_path /tmp/nginx/proxy;
fastcgi_temp_path /tmp/nginx/fastcgi;
uwsgi_temp_path /tmp/nginx/uwsgi;
scgi_temp_path /tmp/nginx/scgi;
# Includes mapping of file name extensions to MIME types of responses
# and defines the default type.
include /services/config/nginx/mime.types;
default_type application/octet-stream;
# Name servers used to resolve names of upstream servers into addresses.
# It's also needed when using tcpsocket and udpsocket in Lua modules.
#resolver 1.1.1.1 1.0.0.1 [2606:4700:4700::1111] [2606:4700:4700::1001];
# Don't tell nginx version to the clients. Default is 'on'.
server_tokens off;
# Specifies the maximum accepted body size of a client request, as
# indicated by the request header Content-Length. If the stated content
# length is greater than this size, then the client receives the HTTP
# error code 413. Set to 0 to disable. Default is '1m'.
client_max_body_size 1m;
# Sendfile copies data between one FD and other from within the kernel,
# which is more efficient than read() + write(). Default is off.
sendfile on;
# Causes nginx to attempt to send its HTTP response head in one packet,
# instead of using partial frames. Default is 'off'.
tcp_nopush on;
# Enables the specified protocols. Default is TLSv1 TLSv1.1 TLSv1.2.
# TIP: If you're not obligated to support ancient clients, remove TLSv1.1.
ssl_protocols TLSv1.2 TLSv1.3;
# Path of the file with Diffie-Hellman parameters for EDH ciphers.
# TIP: Generate with: `openssl dhparam -out /etc/ssl/nginx/dh2048.pem 2048`
#ssl_dhparam /etc/ssl/nginx/dh2048.pem;
# Specifies that our cipher suits should be preferred over client ciphers.
# Default is 'off'.
ssl_prefer_server_ciphers on;
# Enables a shared SSL cache with size that can hold around 8000 sessions.
# Default is 'none'.
ssl_session_cache shared:SSL:2m;
# Specifies a time during which a client may reuse the session parameters.
# Default is '5m'.
ssl_session_timeout 1h;
# Disable TLS session tickets (they are insecure). Default is 'on'.
ssl_session_tickets off;
# Enable gzipping of responses.
gzip on;
# Set the Vary HTTP header as defined in the RFC 2616. Default is 'off'.
gzip_vary on;
# Specifies the main log format.
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
# Sets the path, format, and configuration for a buffered log write.
access_log /tmp/log/nginx-access.log main;
# Virtual host config (unencrypted)
server {
listen ${LISTEN_ADDR}:${PORT} default_server;
root /app/front;
index index.php;
add_header X-Forwarded-Prefix "/app" always;
server_name netalertx-server;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
client_body_buffer_size 512k;
large_client_header_buffers 64 128k;
location ~* \.php$ {
# Set Cache-Control header to prevent caching on the first load
add_header Cache-Control "no-store";
fastcgi_pass unix:/tmp/run/php.sock;
include /services/config/nginx/fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param SCRIPT_NAME $fastcgi_script_name;
fastcgi_connect_timeout 75;
fastcgi_send_timeout 600;
fastcgi_read_timeout 600;
}
}
}
```
### Caddyfile
```
# Example and Guide
# https://caddyserver.com/docs/caddyfile/options
# General Options
{
# (Optional) Debug Mode
# debug
# (Optional ) Enable / Disable Admin API
admin off
# TLS Options
# (Optional) Disable Certificates Management (only if SSL/TLS Certificates are managed by certbot or other external Tools)
auto_https disable_certs
}
# (Optional Enable Admin API)
# localhost {
# reverse_proxy /api/* localhost:9001
# }
# NetAlertX Web GUI (HTTPS Port 443)
# (Optional) Only if SSL/TLS Certificates are managed by certbot or other external Tools and Custom Logging is required
{$APPLICATION_HOSTNAME}:443 {
tls /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_CERT_FILE:fullchain.pem} /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_KEY_FILE:privkey.pem}
log {
output file /var/log/{$APPLICATION_HOSTNAME}/access_web.json {
roll_size 100MiB
roll_keep 5000
roll_keep_for 720h
roll_uncompressed
}
format json
}
route {
# Always forward outpost path to actual outpost
reverse_proxy /outpost.goauthentik.io/* https://{$OUTPOST_HOSTNAME}:{$OUTPOST_EXTERNAL_PORT} {
header_up Host {http.reverse_proxy.upstream.hostport}
}
# Forward authentication to outpost
forward_auth https://{$OUTPOST_HOSTNAME}:{$OUTPOST_EXTERNAL_PORT} {
uri /outpost.goauthentik.io/auth/caddy
# Capitalization of the headers is important, otherwise they will be empty
copy_headers X-Authentik-Username X-Authentik-Groups X-Authentik-Email X-Authentik-Name X-Authentik-Uid X-Authentik-Jwt X-Authentik-Meta-Jwks X-Authentik-Meta-Outpost X-Authentik-Meta-Provider X-Authentik-Meta-App X-Authentik-Meta-Version
# (Optional)
# If not set, trust all private ranges, but for Security Reasons, this should be set to the outposts IP
trusted_proxies private_ranges
}
}
# IPv4 Reverse Proxy to NetAlertX Web GUI (internal unencrypted Host)
reverse_proxy http://0.0.0.0:20211
# IPv6 Reverse Proxy to NetAlertX Web GUI (internal unencrypted Host)
# reverse_proxy http://[::1]:20211
}
# NetAlertX GraphQL Endpoint (HTTPS Port 20212)
# (Optional) Only if SSL/TLS Certificates are managed by certbot or other external Tools and Custom Logging is required
{$APPLICATION_HOSTNAME}:20212 {
tls /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_CERT_FILE:fullchain.pem} /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_KEY_FILE:privkey.pem}
log {
output file /var/log/{$APPLICATION_HOSTNAME}/access_graphql.json {
roll_size 100MiB
roll_keep 5000
roll_keep_for 720h
roll_uncompressed
}
format json
}
# IPv4 Reverse Proxy to NetAlertX GraphQL Endpoint (internal unencrypted Host)
reverse_proxy http://0.0.0.0:20219
# IPv6 Reverse Proxy to NetAlertX GraphQL Endpoint (internal unencrypted Host)
# reverse_proxy http://[::1]:6000
}
# Authentik Outpost
# (Optional) Only if SSL/TLS Certificates are managed by certbot or other external Tools and Custom Logging is required
{$OUTPOST_HOSTNAME}:{$OUTPOST_EXTERNAL_PORT} {
tls /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_CERT_FILE:fullchain.pem} /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_KEY_FILE:privkey.pem}
log {
output file /var/log/outpost/{$OUTPOST_HOSTNAME}/access.json {
roll_size 100MiB
roll_keep 5000
roll_keep_for 720h
roll_uncompressed
}
format json
}
# IPv4 Reverse Proxy to internal unencrypted Host
# reverse_proxy http://0.0.0.0:6000
# IPv6 Reverse Proxy to internal unencrypted Host
reverse_proxy http://[::1]:6000
}
```
### Login
Now try to login by visiting `https://netalertx.MYDOMAIN.TLD`.
You should be greeted with a Login Screen by Authentik.
If you are already logged in Authentik, log out first. You can do that by visiting `https://netalertx.MYDOMAIN.TLD/outpost.goauthentik.io/sign_out`, then click on `Log out of authentik` (2nd Button). Or you can just sign out from your Authentik Admin Panel at `https://authentik.MYDOMAIN.TLD`.
If everything works as expected, then you can now set `SETPWD_enable_password=false` to disable double Authentication.
![Authentik Login Screen](./img/REVERSE_PROXY/authentik-login.png)

892
docs/REVERSE_PROXY_CADDY.md Normal file
View File

@@ -0,0 +1,892 @@
## Caddy + Authentik Outpost Proxy SSO
> Submitted by [luckylinux](https://github.com/luckylinux) 🙏.
> [!NOTE]
> This is community-contributed. Due to environment, setup, or networking differences, results may vary. Please open a PR to improve it instead of creating an issue, as the maintainer is not actively maintaining it.
> [!NOTE]
> NetAlertX requires access to both the **web UI** (default `20211`) and the **GraphQL backend `GRAPHQL_PORT`** (default `20212`) ports.
> Ensure your reverse proxy allows traffic to both for proper functionality.
### Introduction
This Setup assumes:
1. Authentik Installation running on a separate Host at `https://authentik.MYDOMAIN.TLD`
2. Container Management is done on Baremetal OR in a Virtual Machine (KVM/Xen/ESXi/..., no LXC Containers !):
i. Docker and Docker Compose configured locally running as Root (needed for `network_mode: host`) OR
ii. Podman (optionally `podman-compose`) configured locally running as Root (needed for `network_mode: host`)
3. TLS Certificates are already pre-obtained and located at `/var/lib/containers/certificates/letsencrypt/MYDOMAIN.TLD`.
I use the `certbot/dns-cloudflare` Podman Container on a separate Host to obtain the Certificates which I then distribute internally.
This Container uses the Wildcard Top-Level Domain Certificate which is valid for `MYDOMAIN.TLD` and `*.MYDOMAIN.TLD`.
4. Proxied Access
i. NetAlertX Web Interface is accessible via Caddy Reverse Proxy at `https://netalertx.MYDOMAIN.TLD` (default HTTPS Port 443: `https://netalertx.MYDOMAIN.TLD:443`) with `REPORT_DASHBOARD_URL=https://netalertx.MYDOMAIN.TLD`
ii. NetAlertX GraphQL Interface is accessible via Caddy Reverse Proxy at `https://netalertx.MYDOMAIN.TLD:20212` with `BACKEND_API_URL=https://netalertx.MYDOMAIN.TLD:20212`
iii. Authentik Proxy Outpost is accessible via Caddy Reverse Proxy at `https://netalertx.MYDOMAIN.TLD:9443`
5. Internal Ports
i. NGINX Web Server is set to listen on internal Port 20211 set via `PORT=20211`
ii. Python Web Server is set to listen on internal Port `GRAPHQL_PORT=20219`
iii. Authentik Proxy Outpost is listening on internal Port `AUTHENTIK_LISTEN__HTTP=[::1]:6000` (unencrypted) and Port `AUTHENTIK_LISTEN__HTTPS=[::1]:6443` (encrypted)
8. Some further Configuration for Caddy is performed in Terms of Logging, SSL Certificates, etc
It's also possible to [let Caddy automatically request & keep TLS Certificates up-to-date](https://caddyserver.com/docs/automatic-https), although please keep in mind that:
1. You risk enumerating your LAN. Every Domain/Subdomain for which Caddy requests a TLS Certificate for you will result in that Host to be listed on [List of Letsencrypt Certificates issued](https://crt.sh/).
2. You need to either:
i. Open Port 80 for external Access ([HTTP challenge](https://caddyserver.com/docs/automatic-https#http-challenge)) in order for Letsencrypt to verify the Ownership of the Domain/Subdomain
ii. Open Port 443 for external Access ([TLS-ALPN challenge](https://caddyserver.com/docs/automatic-https#tls-alpn-challenge)) in order for Letsencrypt to verify the Ownership of the Domain/Subdomain
iii. Give Caddy the Credentials to update the DNS Records at your DNS Provider ([DNS challenge](https://caddyserver.com/docs/automatic-https#dns-challenge))
You can also decide to deploy your own Certificates & Certification Authority, either manually with OpenSSL, or by using something like [mkcert](https://github.com/FiloSottile/mkcert).
In Terms of IP Stack Used:
- External: Caddy listens on both IPv4 and IPv6.
- Internal:
- Authentik Outpost Proxy listens on IPv6 `[::1]`
- NetAlertX listens on IPv4 `0.0.0.0`
### Flow
The Traffic Flow will therefore be as follows:
- Web GUI:
i. Client accesses `http://authentik.MYDOMAIN.TLD:80`: default (built-in Caddy) Redirect to `https://authentik.MYDOMAIN.TLD:443`
ii. Client accesses `https://authentik.MYDOMAIN.TLD:443` -> reverse Proxy to internal Port 20211 (NetAlertX Web GUI / NGINX - unencrypted)
- GraphQL: Client accesses `https://authentik.MYDOMAIN.TLD:20212` -> reverse Proxy to internal Port 20219 (NetAlertX GraphQL - unencrypted)
- Authentik Outpost: Client accesses `https://authentik.MYDOMAIN.TLD:9443` -> reverse Proxy to internal Port 6000 (Authentik Outpost Proxy - unencrypted)
An Overview of the Flow is provided in the Picture below:
![Reverse Proxy Traffic Flow with Authentik SSSO](./img/REVERSE_PROXY/reverse_proxy_flow.svg)
### Security Considerations
#### Caddy should be run rootless
> [!WARNING]
> By default Caddy runs as `root` which is a Security Risk.
> In order to solve this, it's recommended to create an unprivileged User `caddy` and Group `caddy` on the Host:
> ```
> groupadd --gid 980 caddy
> useradd --shell /usr/sbin/nologin --gid 980 --uid 980 -c "Caddy web server" --base-dir /var/lib/caddy
> ```
At least using Quadlets with Usernames (NOT required with UID/GID), but possibly using Compose in certain Cases as well, a custom `/etc/passwd` and `/etc/group` might need to be bind-mounted inside the Container.
`passwd`:
```
root:x:0:0:root:/root:/bin/sh
bin:x:1:1:bin:/bin:/sbin/nologin
daemon:x:2:2:daemon:/sbin:/sbin/nologin
lp:x:4:7:lp:/var/spool/lpd:/sbin/nologin
sync:x:5:0:sync:/sbin:/bin/sync
shutdown:x:6:0:shutdown:/sbin:/sbin/shutdown
halt:x:7:0:halt:/sbin:/sbin/halt
mail:x:8:12:mail:/var/mail:/sbin/nologin
news:x:9:13:news:/usr/lib/news:/sbin/nologin
uucp:x:10:14:uucp:/var/spool/uucppublic:/sbin/nologin
cron:x:16:16:cron:/var/spool/cron:/sbin/nologin
ftp:x:21:21::/var/lib/ftp:/sbin/nologin
sshd:x:22:22:sshd:/dev/null:/sbin/nologin
games:x:35:35:games:/usr/games:/sbin/nologin
ntp:x:123:123:NTP:/var/empty:/sbin/nologin
guest:x:405:100:guest:/dev/null:/sbin/nologin
nobody:x:65534:65534:nobody:/:/sbin/nologin
caddy:x:980:980:caddy:/var/lib/caddy:/bin/sh
```
`group`:
```
root:x:0:root
bin:x:1:root,bin,daemon
daemon:x:2:root,bin,daemon
sys:x:3:root,bin
adm:x:4:root,daemon
tty:x:5:
disk:x:6:root
lp:x:7:lp
kmem:x:9:
wheel:x:10:root
floppy:x:11:root
mail:x:12:mail
news:x:13:news
uucp:x:14:uucp
cron:x:16:cron
audio:x:18:
cdrom:x:19:
dialout:x:20:root
ftp:x:21:
sshd:x:22:
input:x:23:
tape:x:26:root
video:x:27:root
netdev:x:28:
kvm:x:34:kvm
games:x:35:
shadow:x:42:
www-data:x:82:
users:x:100:games
ntp:x:123:
abuild:x:300:
utmp:x:406:
ping:x:999:
nogroup:x:65533:
nobody:x:65534:
caddy:x:980:
```
#### Authentication of GraphQL Endpoint
> [!WARNING]
> Currently the GraphQL Endpoint is NOT authenticated !
### Environment Files
Depending on the Preference of the User (Environment Variables defined in Compose/Quadlet or in external `.env` File[s]), it might be prefereable to place at least some Environment Variables in external `.env` and `.env.<application>` Files.
The following is proposed:
- `.env`: common Settings (empty by Default)
- `.env.caddy`: Caddy Settings
- `.env.server`: NetAlertX Server/Application Settings
- `.env.outpost.proxy`: Authentik Proxy Outpost Settings
The following Contents is assumed.
`.env.caddy`:
```
# Define Application Hostname
APPLICATION_HOSTNAME=netalertx.MYDOMAIN.TLD
# Define Certificate Domain
# In this case: use Wildcard Certificate
APPLICATION_CERTIFICATE_DOMAIN=MYDOMAIN.TLD
APPLICATION_CERTIFICATE_CERT_FILE=fullchain.pem
APPLICATION_CERTIFICATE_KEY_FILE=privkey.pem
# Define Outpost Hostname
OUTPOST_HOSTNAME=netalertx.MYDOMAIN.TLD
# Define Outpost External Port (TLS)
OUTPOST_EXTERNAL_PORT=9443
```
`.env.server`:
```
PORT=20211
PORT_SSL=443
NETALERTX_NETWORK_MODE=host
LISTEN_ADDR=0.0.0.0
GRAPHQL_PORT=20219
NETALERTX_DEBUG=1
BACKEND_API_URL=https://netalertx.MYDOMAIN.TLD:20212
```
`.env.outpost.proxy`:
```
AUTHENTIK_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
AUTHENTIK_LISTEN__HTTP=[::1]:6000
AUTHENTIK_LISTEN__HTTPS=[::1]:6443
```
### Compose Setup
```
version: "3.8"
services:
netalertx-caddy:
container_name: netalertx-caddy
network_mode: host
image: docker.io/library/caddy:latest
pull: missing
env_file:
- .env
- .env.caddy
environment:
CADDY_DOCKER_CADDYFILE_PATH: "/etc/caddy/Caddyfile"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro,z
- /var/lib/containers/data/netalertx/caddy:/data/caddy:rw,z
- /var/lib/containers/log/netalertx/caddy:/var/log:rw,z
- /var/lib/containers/config/netalertx/caddy:/config/caddy:rw,z
- /var/lib/containers/certificates/letsencrypt:/certificates:ro,z
# Set User
user: "caddy:caddy"
# Automatically restart Container
restart: unless-stopped
netalertx-server:
container_name: netalertx-server # The name when you docker contiainer ls
network_mode: host # Use host networking for ARP scanning and other services
depends_on:
netalertx-caddy:
condition: service_started
restart: true
netalertx-outpost-proxy:
condition: service_started
restart: true
# Local built Image including latest Changes
image: localhost/netalertx-dev:dev-20260109-232454
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:
# Override NGINX Configuration Template
- type: bind
source: /var/lib/containers/config/netalertx/server/nginx/netalertx.conf.template
target: /services/config/nginx/netalertx.conf.template
read_only: true
bind:
selinux: Z
# Letsencrypt Certificates
- type: bind
source: /var/lib/containers/certificates/letsencrypt/MYDOMAIN.TLD
target: /certificates
read_only: true
bind:
selinux: Z
# Data Storage for NetAlertX
- type: bind # Persistent Docker-managed Named Volume for storage
source: /var/lib/containers/data/netalertx/server
target: /data # consolidated configuration and database storage
read_only: false # writable volume
bind:
selinux: Z
# Set the Timezone
- type: bind # Bind mount for timezone consistency
source: /etc/localtime
target: /etc/localtime
read_only: true
bind:
selinux: Z
# 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
- type: tmpfs
target: /tmp
tmpfs-mode: 1700
uid: 0
gid: 0
rw: true
noexec: true
nosuid: true
nodev: true
async: true
noatime: true
nodiratime: true
bind:
selinux: Z
env_file:
- .env
- .env.server
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
PORT_SSL: ${PORT_SSL:-443}
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.
BACKEND_API_URL: ${BACKEND_API_URL-"https://netalertx.MYDOMAIN.TLD:20212"}
# Resource limits to prevent resource exhaustion
mem_limit: 4096m # Maximum memory usage
mem_reservation: 2048m # 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:
driver: "json-file" # Use JSON file logging driver
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
# To sign Out, you need to visit
# {$OUTPOST_HOSTNAME}:{$OUTPOST_EXTERNAL_PORT}/outpost.goauthentik.io/sign_out
netalertx-outpost-proxy:
container_name: netalertx-outpost-proxy
network_mode: host
depends_on:
netalertx-caddy:
condition: service_started
restart: true
restart: unless-stopped
image: ghcr.io/goauthentik/proxy:2025.10
pull: missing
env_file:
- .env
- .env.outpost.proxy
environment:
AUTHENTIK_HOST: "https://authentik.MYDOMAIN.TLD"
AUTHENTIK_INSECURE: false
AUTHENTIK_LISTEN__HTTP: "[::1]:6000"
AUTHENTIK_LISTEN__HTTPS: "[::1]:6443"
```
### Quadlet Setup
`netalertx.pod`:
```
[Pod]
# Name of the Pod
PodName=netalertx
# Network Mode Host is required for ARP to work
Network=host
# Automatically start Pod at Boot Time
[Install]
WantedBy=default.target
```
`netalertx-caddy.container`:
```
[Unit]
Description=NetAlertX Caddy Container
[Service]
Restart=always
[Container]
ContainerName=netalertx-caddy
Pod=netalertx.pod
StartWithPod=true
# Generic Environment Configuration
EnvironmentFile=.env
# Caddy Specific Environment Configuration
EnvironmentFile=.env.caddy
Environment=CADDY_DOCKER_CADDYFILE_PATH=/etc/caddy/Caddyfile
Image=docker.io/library/caddy:latest
Pull=missing
# Run as rootless
# Specifying User & Group by Name requires to mount a custom passwd & group File inside the Container
# Otherwise an Error like the following will result: netalertx-caddy[593191]: Error: unable to find user caddy: no matching entries in passwd file
# User=caddy
# Group=caddy
# Volume=/var/lib/containers/config/netalertx/caddy-rootless/passwd:/etc/passwd:ro,z
# Volume=/var/lib/containers/config/netalertx/caddy-rootless/group:/etc/group:ro,z
# Run as rootless
# Specifying User & Group by UID/GID will NOT require a custom passwd / group File to be bind-mounted inside the Container
User=980
Group=980
Volume=./Caddyfile:/etc/caddy/Caddyfile:ro,z
Volume=/var/lib/containers/data/netalertx/caddy:/data/caddy:z
Volume=/var/lib/containers/log/netalertx/caddy:/var/log:z
Volume=/var/lib/containers/config/netalertx/caddy:/config/caddy:z
Volume=/var/lib/containers/certificates/letsencrypt:/certificates:ro,z
```
`netalertx-server.container`:
```
[Unit]
Description=NetAlertX Server Container
Requires=netalertx-caddy.service netalertx-outpost-proxy.service
After=netalertx-caddy.service netalertx-outpost-proxy.service
[Service]
Restart=always
[Container]
ContainerName=netalertx-server
Pod=netalertx.pod
StartWithPod=true
# Local built Image including latest Changes
Image=localhost/netalertx-dev:dev-20260109-232454
Pull=missing
# Make the container filesystem read-only
ReadOnly=true
# Drop all capabilities for enhanced security
DropCapability=ALL
# It is most secure to start with user 20211, but then we lose provisioning capabilities.
# User=20211:20211
# Required for scanning with arp-scan, nmap, nbtscan, traceroute, and zero-conf
AddCapability=NET_ADMIN
# Required for raw socket operations with arp-scan, nmap, nbtscan, traceroute and zero-conf
AddCapability=NET_RAW
# Required to bind to privileged ports with nbtscan
AddCapability=NET_BIND_SERVICE
# Required for root-entrypoint to chown /data + /tmp before dropping privileges
AddCapability=CHOWN
# Required for root-entrypoint to switch to non-root user
AddCapability=SETUID
# Required for root-entrypoint to switch to non-root group
AddCapability=SETGID
# Override the Configuration Template
Volume=/var/lib/containers/config/netalertx/server/nginx/netalertx.conf.template:/services/config/nginx/netalertx.conf.template:ro,Z
# Letsencrypt Certificates
Volume=/var/lib/containers/certificates/letsencrypt/MYDOMAIN.TLD:/certificates:ro,Z
# Data Storage for NetAlertX
Volume=/var/lib/containers/data/netalertx/server:/data:rw,Z
# Set the Timezone
Volume=/etc/localtime:/etc/localtime:ro,Z
# 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
# Mount=type=tmpfs,destination=/tmp,tmpfs-mode=1700,uid=0,gid=0,rw=true,noexec=true,nosuid=true,nodev=true,async=true,noatime=true,nodiratime=true,relabel=private
Mount=type=tmpfs,destination=/tmp,tmpfs-mode=1700,rw=true,noexec=true,nosuid=true,nodev=true
# Environment Configuration
EnvironmentFile=.env
EnvironmentFile=.env.server
# Runtime UID after priming (Synology/no-copy-up safe)
Environment=PUID=20211
# Runtime GID after priming (Synology/no-copy-up safe)
Environment=PGID=20211
# Listen for connections on all interfaces (IPv4)
Environment=LISTEN_ADDR=0.0.0.0
# Application port
Environment=PORT=20211
# SSL Port
Environment=PORT_SSL=443
# GraphQL API port
Environment=GRAPHQL_PORT=20212
# Set to true to reset your config and database on each container start
Environment=ALWAYS_FRESH_INSTALL=false
# 0=kill all services and restart if any dies. 1 keeps running dead services.
Environment=NETALERTX_DEBUG=0
# Set the GraphQL URL for external Access (via Caddy Reverse Proxy)
Environment=BACKEND_API_URL=https://netalertx-fedora.MYDOMAIN.TLD:20212
# Resource limits to prevent resource exhaustion
# Maximum memory usage
Memory=4g
# Limit the number of processes/threads to prevent fork bombs
PidsLimit=512
# Relative CPU weight for CPU contention scenarios
PodmanArgs=--cpus=2
PodmanArgs=--cpu-shares=512
# Soft memory limit
PodmanArgs=--memory-reservation=2g
# !! The following Keys are unfortunately not [yet] supported !!
# Relative CPU weight for CPU contention scenarios
#CpuShares=512
# Soft memory limit
#MemoryReservation=2g
```
`netalertx-outpost-proxy.container`:
```
[Unit]
Description=NetAlertX Authentik Proxy Outpost Container
Requires=netalertx-caddy.service
After=netalertx-caddy.service
[Service]
Restart=always
[Container]
ContainerName=netalertx-outpost-proxy
Pod=netalertx.pod
StartWithPod=true
# General Configuration
EnvironmentFile=.env
# Authentik Outpost Proxy Specific Configuration
EnvironmentFile=.env.outpost.proxy
Environment=AUTHENTIK_HOST=https://authentik.MYDOMAIN.TLD
Environment=AUTHENTIK_INSECURE=false
# Overrides Value from .env.outpost.rac
# Environment=AUTHENTIK_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
# Optional setting to be used when `authentik_host` for internal communication doesn't match the public URL
# Environment=AUTHENTIK_HOST_BROWSER=https://authentik.MYDOMAIN.TLD
# Container Image
Image=ghcr.io/goauthentik/proxy:2025.10
Pull=missing
# Network Configuration
Network=container:supermicro-ikvm-pve031-caddy
# Security Configuration
NoNewPrivileges=true
```
### Firewall Setup
Depending on which GNU/Linux Distribution you are running, it might be required to open up some Firewall Ports in order to be able to access the Endpoints from outside the Host itself.
This is for instance the Case for Fedora Linux, where I had to open:
- Port 20212 for external GraphQL Access (both TCP & UDP are open, unsure if UDP is required)
- Port 9443 for external Authentik Outpost Proxy Access (both TCP & UDP are open, unsure if UDP is required)
![Fedora Firewall Configuration](./img/REVERSE_PROXY/fedora-firewall.png)
### Authentik Setup
In order to enable Single Sign On (SSO) with Authentik, you will need to create a Provider, an Application and an Outpost.
![Authentik Left Sidebar](./img/REVERSE_PROXY/authentik-sidebar.png)
First of all, using the Left Sidebar, navigate to `Applications` &#8594; `Providers`, click on `Create` (Blue Button at the Top of the Screen), select `Proxy Provider`, then click `Next`:
![Authentik Provider Setup (Part 1)](./img/REVERSE_PROXY/authentik-provider-setup-01.png)
Fill in the required Fields:
- Name: choose a Name for the Provider (e.g. `netalertx`)
- Authorization Flow: choose the Authorization Flow. I typically use `default-provider-authorization-implicit-consent (Authorize Application)`. If you select the `default-provider-authorization-explicit-consent (Authorize Application)` you will need to authorize Authentik every Time you want to log in NetAlertX, which can make the Experience less User-friendly
- Type: Click on `Forward Auth (single application)`
- External Host: set to `https://netalertx.MYDOMAIN.TLD`
Click `Finish`.
![Authentik Provider Setup (Part 2)](./img/REVERSE_PROXY/authentik-provider-setup-02.png)
Now, using the Left Sidebar, navigate to `Applications` &#8594; `Applications`, click on `Create` (Blue Button at the Top of the Screen) and fill in the required Fields:
- Name: choose a Name for the Application (e.g. `netalertx`)
- Slug: choose a Slug for the Application (e.g. `netalertx`)
- Group: optionally you can assign this Application to a Group of Applications of your Choosing (for grouping Purposes within Authentik User Interface)
- Provider: select the Provider you created the the `Providers` Section previosly (e.g. `netalertx`)
Then click `Create`.
![Authentik Application Setup (Part 1)](./img/REVERSE_PROXY/authentik-application-setup-01.png)
Now, using the Left Sidebar, navigate to `Applications` &#8594; `Outposts`, click on `Create` (Blue Button at the Top of the Screen) and fill in the required Fields:
- Name: choose a Name for the Outpost (e.g. `netalertx`)
- Type: `Proxy`
- Integration: open the Dropdown and click on `---------`. Make sure it is NOT set to `Local Docker connection` !
In the `Available Applications` Section, select the Application you created in the Previous Step, then click the right Arrow (approx. located in the Center of the Screen), so that it gets copied in the `Selected Applications` Section.
Then click `Create`.
![Authentik Outpost Setup (Part 1)](./img/REVERSE_PROXY/authentik-outpost-setup-01.png)
Wait a few Seconds for the Outpost to be created. Once it appears in the List, click on `Deployment Info` on the Right Side of the relevant Line.
![Authentik Outpost Setup (Part 2)](./img/REVERSE_PROXY/authentik-outpost-setup-02.png)
Take note of that Token. You will need it for the Authentik Outpost Proxy Container, which will read it as the `AUTHENTIK_TOKEN` Environment Variable.
### NGINX Configuration inside NetAlertX Container
> [!NOTE]
> This is something that was implemented based on the previous Content of this Reverse Proxy Document.
> Due to some Buffer Warnings/Errors in the Logs as well as some other Issues I was experiencing, I increased a lot the client_body_buffer_size and large_client_header_buffers Parameters, although these might not be required anymore.
> Further Testing might be required.
```
# Set number of worker processes automatically based on number of CPU cores.
worker_processes auto;
# Enables the use of JIT for regular expressions to speed-up their processing.
pcre_jit on;
# Configures default error logger.
error_log /tmp/log/nginx-error.log warn;
pid /tmp/run/nginx.pid;
events {
# The maximum number of simultaneous connections that can be opened by
# a worker process.
worker_connections 1024;
}
http {
# Mapping of temp paths for various nginx modules.
client_body_temp_path /tmp/nginx/client_body;
proxy_temp_path /tmp/nginx/proxy;
fastcgi_temp_path /tmp/nginx/fastcgi;
uwsgi_temp_path /tmp/nginx/uwsgi;
scgi_temp_path /tmp/nginx/scgi;
# Includes mapping of file name extensions to MIME types of responses
# and defines the default type.
include /services/config/nginx/mime.types;
default_type application/octet-stream;
# Name servers used to resolve names of upstream servers into addresses.
# It's also needed when using tcpsocket and udpsocket in Lua modules.
#resolver 1.1.1.1 1.0.0.1 [2606:4700:4700::1111] [2606:4700:4700::1001];
# Don't tell nginx version to the clients. Default is 'on'.
server_tokens off;
# Specifies the maximum accepted body size of a client request, as
# indicated by the request header Content-Length. If the stated content
# length is greater than this size, then the client receives the HTTP
# error code 413. Set to 0 to disable. Default is '1m'.
client_max_body_size 1m;
# Sendfile copies data between one FD and other from within the kernel,
# which is more efficient than read() + write(). Default is off.
sendfile on;
# Causes nginx to attempt to send its HTTP response head in one packet,
# instead of using partial frames. Default is 'off'.
tcp_nopush on;
# Enables the specified protocols. Default is TLSv1 TLSv1.1 TLSv1.2.
# TIP: If you're not obligated to support ancient clients, remove TLSv1.1.
ssl_protocols TLSv1.2 TLSv1.3;
# Path of the file with Diffie-Hellman parameters for EDH ciphers.
# TIP: Generate with: `openssl dhparam -out /etc/ssl/nginx/dh2048.pem 2048`
#ssl_dhparam /etc/ssl/nginx/dh2048.pem;
# Specifies that our cipher suits should be preferred over client ciphers.
# Default is 'off'.
ssl_prefer_server_ciphers on;
# Enables a shared SSL cache with size that can hold around 8000 sessions.
# Default is 'none'.
ssl_session_cache shared:SSL:2m;
# Specifies a time during which a client may reuse the session parameters.
# Default is '5m'.
ssl_session_timeout 1h;
# Disable TLS session tickets (they are insecure). Default is 'on'.
ssl_session_tickets off;
# Enable gzipping of responses.
gzip on;
# Set the Vary HTTP header as defined in the RFC 2616. Default is 'off'.
gzip_vary on;
# Specifies the main log format.
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
# Sets the path, format, and configuration for a buffered log write.
access_log /tmp/log/nginx-access.log main;
# Virtual host config (unencrypted)
server {
listen ${LISTEN_ADDR}:${PORT} default_server;
root /app/front;
index index.php;
add_header X-Forwarded-Prefix "/app" always;
server_name netalertx-server;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
client_body_buffer_size 512k;
large_client_header_buffers 64 128k;
location ~* \.php$ {
# Set Cache-Control header to prevent caching on the first load
add_header Cache-Control "no-store";
fastcgi_pass unix:/tmp/run/php.sock;
include /services/config/nginx/fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param SCRIPT_NAME $fastcgi_script_name;
fastcgi_connect_timeout 75;
fastcgi_send_timeout 600;
fastcgi_read_timeout 600;
}
}
}
```
### Caddyfile
```
# Example and Guide
# https://caddyserver.com/docs/caddyfile/options
# General Options
{
# (Optional) Debug Mode
# debug
# (Optional ) Enable / Disable Admin API
admin off
# TLS Options
# (Optional) Disable Certificates Management (only if SSL/TLS Certificates are managed by certbot or other external Tools)
auto_https disable_certs
}
# (Optional Enable Admin API)
# localhost {
# reverse_proxy /api/* localhost:9001
# }
# NetAlertX Web GUI (HTTPS Port 443)
# (Optional) Only if SSL/TLS Certificates are managed by certbot or other external Tools and Custom Logging is required
{$APPLICATION_HOSTNAME}:443 {
tls /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_CERT_FILE:fullchain.pem} /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_KEY_FILE:privkey.pem}
log {
output file /var/log/{$APPLICATION_HOSTNAME}/access_web.json {
roll_size 100MiB
roll_keep 5000
roll_keep_for 720h
roll_uncompressed
}
format json
}
route {
# Always forward outpost path to actual outpost
reverse_proxy /outpost.goauthentik.io/* https://{$OUTPOST_HOSTNAME}:{$OUTPOST_EXTERNAL_PORT} {
header_up Host {http.reverse_proxy.upstream.hostport}
}
# Forward authentication to outpost
forward_auth https://{$OUTPOST_HOSTNAME}:{$OUTPOST_EXTERNAL_PORT} {
uri /outpost.goauthentik.io/auth/caddy
# Capitalization of the headers is important, otherwise they will be empty
copy_headers X-Authentik-Username X-Authentik-Groups X-Authentik-Email X-Authentik-Name X-Authentik-Uid X-Authentik-Jwt X-Authentik-Meta-Jwks X-Authentik-Meta-Outpost X-Authentik-Meta-Provider X-Authentik-Meta-App X-Authentik-Meta-Version
# (Optional)
# If not set, trust all private ranges, but for Security Reasons, this should be set to the outposts IP
trusted_proxies private_ranges
}
}
# IPv4 Reverse Proxy to NetAlertX Web GUI (internal unencrypted Host)
reverse_proxy http://0.0.0.0:20211
# IPv6 Reverse Proxy to NetAlertX Web GUI (internal unencrypted Host)
# reverse_proxy http://[::1]:20211
}
# NetAlertX GraphQL Endpoint (HTTPS Port 20212)
# (Optional) Only if SSL/TLS Certificates are managed by certbot or other external Tools and Custom Logging is required
{$APPLICATION_HOSTNAME}:20212 {
tls /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_CERT_FILE:fullchain.pem} /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_KEY_FILE:privkey.pem}
log {
output file /var/log/{$APPLICATION_HOSTNAME}/access_graphql.json {
roll_size 100MiB
roll_keep 5000
roll_keep_for 720h
roll_uncompressed
}
format json
}
# IPv4 Reverse Proxy to NetAlertX GraphQL Endpoint (internal unencrypted Host)
reverse_proxy http://0.0.0.0:20219
# IPv6 Reverse Proxy to NetAlertX GraphQL Endpoint (internal unencrypted Host)
# reverse_proxy http://[::1]:6000
}
# Authentik Outpost
# (Optional) Only if SSL/TLS Certificates are managed by certbot or other external Tools and Custom Logging is required
{$OUTPOST_HOSTNAME}:{$OUTPOST_EXTERNAL_PORT} {
tls /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_CERT_FILE:fullchain.pem} /certificates/{$APPLICATION_CERTIFICATE_DOMAIN}/{$APPLICATION_CERTIFICATE_KEY_FILE:privkey.pem}
log {
output file /var/log/outpost/{$OUTPOST_HOSTNAME}/access.json {
roll_size 100MiB
roll_keep 5000
roll_keep_for 720h
roll_uncompressed
}
format json
}
# IPv4 Reverse Proxy to internal unencrypted Host
# reverse_proxy http://0.0.0.0:6000
# IPv6 Reverse Proxy to internal unencrypted Host
reverse_proxy http://[::1]:6000
}
```
### Login
Now try to login by visiting `https://netalertx.MYDOMAIN.TLD`.
You should be greeted with a Login Screen by Authentik.
If you are already logged in Authentik, log out first. You can do that by visiting `https://netalertx.MYDOMAIN.TLD/outpost.goauthentik.io/sign_out`, then click on `Log out of authentik` (2nd Button). Or you can just sign out from your Authentik Admin Panel at `https://authentik.MYDOMAIN.TLD`.
If everything works as expected, then you can now set `SETPWD_enable_password=false` to disable double Authentication.
![Authentik Login Screen](./img/REVERSE_PROXY/authentik-login.png)

86
docs/REVERSE_PROXY_TRAEFIK.md Normal file
View File

@@ -0,0 +1,86 @@
# Guide: Routing NetAlertX API via Traefik v3
> [!NOTE]
> NetAlertX requires access to both the **web UI** (default `20211`) and the **GraphQL backend `GRAPHQL_PORT`** (default `20212`) ports.
> Ensure your reverse proxy allows traffic to both for proper functionality.
> [!NOTE]
> This is community-contributed. Due to environment, setup, or networking differences, results may vary. Please open a PR to improve it instead of creating an issue, as the maintainer is not actively maintaining it.
Traefik v3 requires the following setup to route traffic properly. This guide shows a working configuration using a dedicated `PathPrefix`.
---
## 1. Configure NetAlertX Backend URL
1. Open the NetAlertX UI: **Settings → Core → General**.
2. Set the `BACKEND_API_URL` to include a custom path prefix, for example:
```
https://netalertx.yourdomain.com/netalertx-api
```
This tells the frontend where to reach the backend API.
---
## 2. Create a Traefik Router for the API
Define a router specifically for the API with a higher priority and a `PathPrefix` rule:
```yaml
netalertx-api:
rule: "Host(`netalertx.yourdomain.com`) && PathPrefix(`/netalertx-api`)"
service: netalertx-api-service
middlewares:
- netalertx-stripprefix
priority: 100
```
**Notes:**
* `Host(...)` ensures requests are only routed for your domain.
* `PathPrefix(...)` routes anything under `/netalertx-api` to the backend.
* Priority `100` ensures this router takes precedence over other routes.
---
## 3. Add a Middleware to Strip the Prefix
NetAlertX expects requests at the root (`/`). Use Traefik’s `StripPrefix` middleware:
```yaml
middlewares:
netalertx-stripprefix:
stripPrefix:
prefixes:
- "/netalertx-api"
```
This removes `/netalertx-api` before forwarding the request to the backend container.
---
## 4. Map the API Service to the Backend Container
Point the service to the internal GraphQL/Backend port (20212):
```yaml
netalertx-api-service:
loadBalancer:
servers:
- url: "http://<INTERNAL_IP>:20212"
```
Replace `<INTERNAL_IP>` with your NetAlertX container’s internal address.
---
✅ With this setup:
* `https://netalertx.yourdomain.com` → Web interface (port 20211)
* `https://netalertx.yourdomain.com/netalertx-api` → API/GraphQL backend (port 20212)
This cleanly separates API requests from frontend requests while keeping everything under the same domain.

4
docs/SYNOLOGY_GUIDE.md
View File

@@ -37,8 +37,8 @@ services:
netalertx:
container_name: netalertx
# use the below line if you want to test the latest dev image
# image: "ghcr.io/jokob-sk/netalertx-dev:latest"
image: "ghcr.io/jokob-sk/netalertx:latest"
# image: "ghcr.io/netalertx/netalertx-dev:latest"
image: "ghcr.io/netalertx/netalertx:latest"
network_mode: "host"
restart: unless-stopped
cap_drop: # Drop all capabilities for enhanced security

BIN
docs/img/@eaDir/device_details.png@SynoEAStream
View File

Binary file not shown.

BIN
docs/img/@eaDir/devices_dark.png@SynoEAStream
View File

Binary file not shown.

BIN
docs/img/@eaDir/devices_light.png@SynoEAStream
View File

Binary file not shown.

BIN
docs/img/@eaDir/devices_split.png@SynoEAStream
View File

Binary file not shown.

BIN
docs/img/@eaDir/events.png@SynoEAStream
View File

Binary file not shown.

BIN
docs/img/@eaDir/help_faq.png@SynoEAStream
View File

Binary file not shown.

BIN
docs/img/@eaDir/maintenance.png@SynoEAStream
View File

Binary file not shown.

BIN
docs/img/@eaDir/network.png@SynoEAStream
View File

Binary file not shown.

BIN
docs/img/@eaDir/presence.png@SynoEAStream
View File

Binary file not shown.

BIN
docs/img/@eaDir/settings.png@SynoEAStream
View File

Binary file not shown.

BIN
docs/img/API/API_docs.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

BIN
docs/img/DEVICE_MANAGEMENT/field_sources_and_locks.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

BIN
docs/img/FEATURES/Event-Driven_Alerts.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 140 KiB

BIN
docs/img/FEATURES/Events.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 220 KiB

BIN
docs/img/FEATURES/LAN_Visualization.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 328 KiB

BIN
docs/img/FEATURES/MCP_Server.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 107 KiB

BIN
docs/img/FEATURES/Multi-Channel_Notifications.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 142 KiB

BIN
docs/img/FEATURES/Network_Discovery_Device_Tracking.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 332 KiB

BIN
docs/img/device_nmap.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 173 KiB

BIN
docs/img/device_tools.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 190 KiB

BIN
docs/img/devices_split.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 210 KiB

After

Width:  |  Height:  |  Size: 446 KiB

BIN
docs/img/maintenance.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 146 KiB

After

Width:  |  Height:  |  Size: 203 KiB

Some files were not shown because too many files have changed in this diff Show More