Merge branch 'main' into feat/adguard-export-plugin

Author: jokob-sk

.github/skills/code-standards/SKILL.md

@@ -8,10 +8,23 @@ description: NetAlertX coding standards and conventions. Use this when writing c
 - ask me to review before going to each next step (mention n step out of x)  (AI only)
 - before starting, prepare implementation plan  (AI only)
 - ask me to review it and ask any clarifying questions first
-- add test creation as last step - follow repo architecture patterns - do not place in the root of /test
+- add test creation as last step - follow repo architecture patterns - do not place in the root of `/test`
 - code has to be maintainable, no duplicate code
 - follow DRY principle - maintainability of code is more important than speed of implementation
 - code files should be less than 500 LOC for better maintainability
+- DB columns must not contain underscores, use camelCase instead (e.g., deviceInstanceId, not device_instance_id)
+- treat DB as temporary storage for stats, long-term configuration should be stored in the `/config` folder, the `/config` folder should allow you to restore most of your functionality (excluding historical data)
+- never access DB directly from application layers, always use helper functions in `server/db/db_helper.py` and implement new functionality in handlers (e.g., `DeviceInstance` in `server/models/device_instance.py`)
+- always validate and normalize MAC addresses before writing to DB (use `normalize_mac` from `plugin_helper.py`)
+- all subprocess calls must set explicit timeouts
+- use `timeNowUTC` from `utils.datetime_utils` for all time-related operations and DB timestamps (store all timestamps in UTC)
+- use sanitizers from `server/helper.py` for user input before storing in DB
+- reuse shared mocks and factories from `test/db_test_helpers.py` for tests, never redefine them locally
+- use environment variables for runtime paths, never hardcode paths or use relative paths
+- follow existing code style and structure, and ensure backward compatibility with existing installations when submitting PRs
+- all code needs to be scalable to handle large networks with thousands of devices (10k+) without performance degradation
+- no inline imports, all imports must be at the top of the file
+
 
 ## File Length
 
@@ -72,6 +85,18 @@ Use sanitizers from `server/helper.py` before storing user input. MAC addresses
 - Everything is already writable
 - If permissions needed, fix `.devcontainer/scripts/setup.sh`
 
+## Test Helpers — No Duplicate Mocks
+
+Reuse shared mocks and factories from `test/db_test_helpers.py`. Never redefine `DummyDB`, `make_db`, or inline DDL in individual test files.
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from db_test_helpers import make_db, DummyDB, insert_device, minutes_ago
+```
+
+If a helper you need doesn't exist yet, add it to `db_test_helpers.py` — not locally in the test file.
+
 ## Path Hygiene
 
 - Use environment variables for runtime paths

.github/workflows/mkdocs.yml

@@ -18,12 +18,15 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.9'
+          python-version: '3.11'
 
       - name: Install MkDocs
         run: |
-          pip install mkdocs mkdocs-material
-          pip install mkdocs-github-admonitions-plugin
+          pip install \
+            mkdocs==1.6.0 \
+            mkdocs-material==9.5.21 \
+            mkdocs-github-admonitions-plugin==0.1.1 \
+            mkdocs-glightbox
 
       - name: Build MkDocs
         run: mkdocs build

CONTRIBUTING.md

@@ -15,6 +15,37 @@ Before opening a new issue:
 - [Check Common Issues & Debug Tips](https://docs.netalertx.com/DEBUG_TIPS#common-issues)
 - [Search Closed Issues](https://github.com/netalertx/NetAlertX/issues?q=is%3Aissue+is%3Aclosed)
 
+---
+
+## Contributing without coding knowledge
+
+Writing code is not the only way how you can contribute to the project. Here are some ideas how you can help out otherwise:
+
+ - Help improving the documentation (text, typos, use cases, screenshots - all this makes things better)
+ - Share your favorite project on socials (see [Growth ideas](./GROWTH.md))
+ - Write a blog post, or a how-to set-up guide
+ - Write how it helped you to achieve something fun or interesting to simplify your personal or work life
+ - Help with the translation effort
+ - Running a nightly or dev build to test for bugs before they make it to the production release
+ - Report bugs and features with sufficient detail and care (super important to ease everyone's maintenance burden and minimize back-and-forth)
+ - running a projects test suite
+
+
+---
+
+## Use of AI
+
+Use of AI-assisted tools is permitted, provided all generated code is reviewed, understood, and verified before submission.
+
+- All AI-generated code must meet the project's **quality, security, and performance standards**.
+- Contributors are responsible for **fully understanding** any code they submit, regardless of how it was produced.
+- Prefer **clarity and maintainability over cleverness or brevity**. Readable code is always favored over dense or obfuscated implementations.
+- Follow the **DRY (Don't Repeat Yourself) principle** where appropriate, without sacrificing readability.
+- Do not submit code that you cannot confidently explain or debug.
+
+All changes must pass the **full test suite** before opening a PR.
+
+
 ---
 
 ## Submitting Pull Requests (PRs)
@@ -28,11 +59,19 @@ Please:
 - Provide a clear title and description for your PR
 - If relevant, add or update tests and documentation
 - For plugins, refer to the [Plugin Dev Guide](https://docs.netalertx.com/PLUGINS_DEV)
+- Switch the PR to DRAFT mode if still being worked on
+- Keep PRs **focused and minimal** — avoid unrelated changes in a single PR
+- PRs that do not meet these guidelines may be closed without review
+
+## Commit Messages
 
+- Use clear, descriptive commit messages
+- Explain *why* a change was made, not just *what* changed
+- Reference related issues where applicable
 
-## Code quality
+## Code Quality
 
-- read and follow the [code-standards](/.github/skills/code-standards/SKILL.md)
+- Read and follow the [code standards](/.github/skills/code-standards/SKILL.md)
 
 ---
 

GROWTH.md

@@ -0,0 +1,142 @@
+# 📈 NetAlertX Growth Playbook
+
+If you like NetAlertX and want to help it grow, this is how.
+
+This isn’t about spam or "growth hacks." It’s just getting the tool in front of people who already have the problem (manual network docs, blind spots, messy networks).
+
+---
+
+## 🎯 Who this is for
+
+* **Homelabbers** → Proxmox, Unraid, Raspberry Pi setups
+* **Self-hosters** → moving away from cloud / want local-first
+* **Sysadmins / MSPs** → need visibility + fast onboarding
+
+---
+
+## 💬 Where to post (and how)
+
+### Reddit (main channel)
+
+Reddit works *if* you don’t sound like marketing.
+
+**Subreddits**
+
+* r/homelab
+* r/selfhosted
+* r/sysadmin
+* r/networking
+
+**What works**
+
+* "Show r/homelab" / "I built this"
+* Problem → solution
+* Real screenshots or short GIFs
+
+**Example**
+
+> Tired of keeping network diagrams up to date?
+> I deployed something that does it automatically.
+
+**Avoid**
+
+* Over-explaining
+* Buzzwords
+* "Check out my project!!!" energy
+
+**Timing (rough guide)**
+
+* Tue–Thu mornings (US time)
+
+---
+
+### Hacker News (Show HN)
+
+Good fit because NetAlertX is:
+
+* local-first
+* privacy-focused
+* actually useful
+
+**Title**
+
+> Show HN: NetAlertX – network documentation that updates itself
+
+Be ready to answer:
+
+* stack (Python / PHP / JS)
+* how discovery works
+* privacy / local scanning
+
+---
+
+### Awesome Lists
+
+Low effort, long-term visibility.
+
+Target:
+
+* awesome-selfhosted
+* awesome-homelab
+
+Keep it simple:
+
+> NetAlertX – automated network discovery and documentation with alerting
+
+---
+
+## 🎥 Content / creators
+
+If you or someone else makes videos, these angles work:
+
+* **First 5 minutes** → "it already found everything"
+* **Before vs after** → manual vs NetAlertX
+* **Docker setup** → show how easy it is
+
+No need for overproduction—real usage > polished demos.
+
+---
+
+## ⚖️ Positioning (keep it simple)
+
+When explaining NetAlertX, this is the mental model:
+
+|         | Manual Docs       | Basic Scanners | NetAlertX                 |
+| ------- | ----------------- | -------------- | ------------------------- |
+| Updates | Manual / outdated | On demand      | **Automatic**             |
+| Alerts  | None              | Limited        | **New / unknown devices** |
+| History | None              | None           | **Device timeline**       |
+| Effort  | High              | Medium         | **Set & forget**          |
+
+---
+
+## 🧑‍💻 MSP / professional angle
+
+If you’re using it in real environments:
+
+* Faster client onboarding
+* Better visibility
+* Less "what changed?" guessing
+
+That’s the value—keep it grounded. And share your experience 🙏
+
+---
+
+## 🛠 Easy ways to help
+
+* Star the repo
+* Post a screenshot of your network
+* Mention it when someone asks "how do you track devices?" or "how do you detect presence?"
+* Write a quick "how I use it" post
+
+---
+
+## Final note
+
+Authenticity matters more than reach.
+
+If it feels like marketing, people ignore it.
+If it feels like "this solved my problem," people pay attention.
+
+Thanks a lot in advance!
+                        - jokob

README.md

@@ -21,13 +21,13 @@
 </details>
 
 
-Centralized network visibility and continuous asset discovery.
+Centralized network visibility and continuous asset discovery for homelabs, IT teams, MSPs, and distributed environments.
 
-Monitor devices, detect change, and stay aware across distributed networks.
+Monitor devices, detect change, and maintain visibility across remote sites, VLANs, branch offices, and segmented networks from a single interface.
 
-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 provides a centralized "Source of Truth" (NSoT) for network infrastructure. Maintain a real-time inventory of connected devices, identify Shadow IT and unauthorized hardware, support compliance initiatives, and automate operational workflows across distributed customer environments.
 
-NetAlertX is designed to bridge the gap between simple network scanning and complex SIEM tools, providing actionable insights without the overhead.
+Designed to bridge the gap between simple network scanners and complex SIEM platforms, NetAlertX delivers actionable network intelligence and centralized monitoring without the operational overhead.
 
 
 ## Table of Contents
@@ -98,6 +98,10 @@ build your own scanners with the [Plugin system](https://docs.netalertx.com/PLUG
 
 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.
 
+### MSP & Multi-Site Monitoring
+
+NetAlertX enables centralized monitoring across remote sites and isolated environments through Sync Nodes for VLANs and branch offices, providing unified visibility of assets across multiple networks. It supports [NOC-style wallboard dashboards](https://docs.netalertx.com/ADVISORY_EYES_ON_GLASS/), [Prometheus metrics export](https://docs.netalertx.com/API_METRICS/), workflow automation for device governance, and distributed discovery with centralized alerting for scalable network operations.
+
 
 ## Documentation
 <!--- --------------------------------------------------------------------- --->
@@ -126,6 +130,15 @@ Compliance & Hardening:
 
 See [Security Best Practices](https://github.com/netalertx/NetAlertX/security) for more details.
 
+## Designed for MSPs, NOCs & Distributed Networks
+
+NetAlertX supports centralized monitoring across VLANs, branch offices, customer environments, isolated networks, and remote sites.
+
+Using [Sync Nodes](https://docs.netalertx.com/ADVISORY_MULTI_SITE_MONITORING), distributed collectors securely send device inventory and network visibility data back to a central hub, enabling unified monitoring, alerting, and asset tracking across all locations.
+
+This provides MSPs and NOCs with a single operational view of many independent networks, without requiring direct access or centralized scanning infrastructure.
+
+Common deployments include MSP wallboards, NOC dashboards, multi-site inventory monitoring, and remote office discovery.
 
 ## FAQ
 
@@ -157,7 +170,7 @@ Check the [GitHub Issues](https://github.com/netalertx/NetAlertX/issues) for the
 ## 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>
+<a href="https://trendshift.io/repositories/19712" target="_blank"><img src="https://trendshift.io/api/badge/repositories/19712" alt="jokob-sk%2FNetAlertX | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 
 ### 📧 Get notified what's new
 
@@ -170,6 +183,7 @@ Get notified about a new release, what new functionality you can use and about b
 - [Fing](https://www.fing.com/) - Network scanner app for your Internet security (Commercial, Phone App, Proprietary hardware)
 - [NetBox](https://netboxlabs.com/) - The gold standard for Network Source of Truth (NSoT) and IPAM.
 - [Zabbix](https://www.zabbix.com/) or [Nagios](https://www.nagios.org/) - Strong focus on infrastructure monitoring.
+- [Domotz](https://www.domotz.com/) - Commercial network monitoring and remote management platform aimed at MSPs, IT teams, and multi-site environments.
 - [NetAlertX](https://netalertx.com) - The streamlined, discovery-focused choice for real-time asset intelligence and noise-free alerting.
 
 ### 💙 Donations

back/app.conf

@@ -30,6 +30,7 @@ REPORT_DASHBOARD_URL='update_REPORT_DASHBOARD_URL_setting'
 INTRNT_RUN='schedule'
 ARPSCAN_RUN='schedule'
 NSLOOKUP_RUN='before_name_updates'
+DIGSCAN_RUN='before_name_updates'
 AVAHISCAN_RUN='before_name_updates'
 NBTSCAN_RUN='before_name_updates'
 

docs/ADVISORY_EYES_ON_GLASS.md

@@ -4,6 +4,9 @@ For Managed Service Providers (MSPs) and Network Operations Centers (NOC), "Eyes
 
 ![filters](./img/ADVISORIES/filters.png)
 
+> [!TIP]
+> If you are using Grafana check the `/metrics` endpoint that exposes **Prometheus-compatible metrics** for NetAlertX, including aggregate device counts and per-device status. See the [Metrics API endpoint](./API_METRICS.md) documentation for details.
+
 ---
 
 ### 1. Configure Auto-Refresh for Live Monitoring