woninet 2.0.1__tar.gz

woninet-2.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alireza Teymuri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

woninet-2.0.1/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: woninet
+Version: 2.0.1
+Summary: A Python-based ARP+ICMP network monitoring tool
+Author-email: Alireza Teymuri <teymuri.alireza98@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/teymuri-alireza/woninet
+Project-URL: Documentation, https://github.com/teymuri-alireza/woninet/tree/main/docs
+Project-URL: Repository, https://github.com/teymuri-alireza/woninet
+Project-URL: Issues, https://github.com/teymuri-alireza/woninet/issues
+Project-URL: Changelog, https://github.com/teymuri-alireza/woninet/blob/main/CHANGELOG.md
+Keywords: network,network-monitoring,icmp,arp
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: icmplib<3.1,>=3.0.4
+Requires-Dist: fastapi<0.137,>=0.136.0
+Requires-Dist: Jinja2<3.2,>=3.1.6
+Requires-Dist: uvicorn<0.45,>=0.44.0
+Requires-Dist: PyYAML<6.1,>=6.0.3
+Requires-Dist: SQLAlchemy<2.1,>=2.0.46
+Requires-Dist: matplotlib<3.12,>=3.11.0
+Provides-Extra: test
+Requires-Dist: pytest<9.2,>=9.1.1; extra == "test"
+Requires-Dist: httpx<0.29,>=0.28.1; extra == "test"
+Dynamic: license-file
+
+# woninet
+
+A local network monitoring system.
+
+**woninet** continuously monitors devices on a local network using ARP
+and ICMP probes. It enumerates candidate IP addresses in a /24 subnet,
+determines device availability, measures latency and packet loss, stores
+metrics in SQLite, and evaluates configurable alert rules in real time.
+
+**Note: This script requires sudo privileges.**
+
+## Features
+
+- **ARP + ICMP Host Detection** (Distinguishes real devices from nonexistent
+IPs and filters out Wi‑Fi ARP‑delay noise.)
+
+- **Alert Engine** (Evaluates real‑time alert rules (e.g., latency thresholds))
+
+- **Threaded Collectors**
+
+- **SQLite database** (for devices, recorded metrics, alert states, and alert events.)
+
+- **Positional Argument for easier access to the database from the CLI**
+
+- **Detailed Logging**
+
+## Future Plans
+
+- Add ARP table caching to further reduce Wi‑Fi latency noise.
+- Accept MAC addresses as command‑line arguments.
+- Fetch MAC address from database for offline devices.
+- Use ARP noise limit as device state for styling in front-end.
+- Add CLI argument to accept target IP addresses from a file.
+
+## Known Issues
+
+- Monitoring Scope Limited to /24 Subnet
+
+## How To Run
+
+**Note:** *woninet* is under active development.
+
+## Installation
+
+Install from PyPI:
+
+```shell
+pip install woninet
+```
+
+Then run:
+
+```shell
+woninet --help
+```
+
+## Installation from Source
+
+### 1. Clone the repository
+
+```shell
+git clone https://github.com/teymuri-alireza/woninet
+cd woninet
+```
+
+### 2. Create and activate a virtual environment:
+
+**Note:** Create the virtual environment outside the project directory to avoid
+`Multiple top-level packages discovered in a flat-layout` errors.
+
+**Unix/Linux note:** The `--copies` flag forces Python to copy the interpreter
+instead of using a symbolic link. This is required because you will apply Linux
+capabilities directly to the Python binary in the virtual environment.
+
+#### Linux/macOS
+
+```shell
+python3 -m venv --copies ../venv
+source ../venv/bin/activate
+```
+
+#### Windows (PowerShell)
+
+```shell
+py -m venv ..\venv
+..\venv\Scripts\Activate.ps1
+```
+
+### 3. Install woninet locally:
+
+```shell
+pip3 install .
+```
+
+### 4. Run woninet
+
+**Unix/Linux only:** To allow raw ICMP without running as root, grant the required
+capability to the Python interpreter inside the virtual environment:
+
+```shell
+sudo setcap cap_net_raw=eip ../venv/bin/python3
+```
+
+Finally, run woninet normally:
+
+```shell
+woninet --version
+```
+
+**Alternative (not recommended):** You can run woninet with sudo instead of using
+setcap, but this is discouraged for security reasons:
+
+```shell
+sudo ../venv/bin/python3 -m woninet
+```
+
+## Configuration
+
+You can define alert rules in a JSON file. Rename the example file at
+`woninet/config.example.json` to `config.json`. The application will load the alert
+rules from that file at startup.
+
+### Example:
+
+```json
+{
+    "monitoring": {
+        "arp_noise_limit": 300.0,
+        "max_workers": 4
+    },
+    "database": "woninet.db",
+    "target_ip_list": [
+        "192.168.1.1-100"
+        // or
+        "192.168.1.1", "192.168.1.10", "192.168.1.20"
+    ],
+    "alert_rules":[
+        {
+            "metric": "latency",
+            "threshold": 100,
+            "consecutive_checks": 3
+        },
+        {
+            "metric": "packet_loss",
+            "threshold": 0.0,
+            "consecutive_checks": 1
+        }
+    ]
+}
+```
+
+### Explanations:
+
+#### Monitoring Settings
+
+- **arp_noise_limit**: Latency threshold in milliseconds used to filter ARP
+resolution noise. Set to 0 to disable filtering. Helps eliminate Wi‑Fi latency spikes.
+- **max_workers**: Maximum number of thread workers used to send ICMP pings.
+Higher values may increase system load and latency.
+
+#### Database
+
+- **database**: The path to the SQLite database file where metrics and alerts are stored.
+
+#### Target IP List
+
+- A single or range of target IP addresses to scan.
+
+#### Alert Rules
+
+- **metric**: The metric name to evaluate (`latency` or `packet_loss`)
+- **threshold**: The value that triggers the alert. For latency, this is in milliseconds.
+For packet loss, this is a percentage (0.0-100.0).
+- **consecutive_checks**: The number of consecutive evaluations required before the alert
+state changes. Higher values reduce false positives.
+
+#### Notes
+
+- **Packet Loss**: Values are in the range [0.0, 100.0]. A value of 100.0 indicates 100%
+packet loss. A value of 0.0 will trigger on any packet loss.
+- **Latency**: All latency thresholds are evaluated in milliseconds.
+
+## Usage
+
+This [guide](./docs/usage.md) explains common ways to run *woninet* and how to resolve common issues.
+
+## Testing
+
+If you want to run the test suite locally, install the optional test dependencies:
+
+```shell
+pip install -e ".[test]"
+```
+
+Then run:
+
+```shell
+pytest
+```
+
+The test suite currently focuses on API behavior and core logic, and it uses pytest for automated verification.
+
+## Requirements
+
+- Python >= 3.12
+- Root privileges
+
+## Documentation
+
+if you have any question or need clarification, check the [documentation](./docs/documentation.md) guide.
+
+## Contribution
+
+Thanks for considering contributing to *woninet!*
+To help us maintain code quality, stability, and a predictable release process, please review
+and follow the guidelines in our [Contributing Guide.](./CONTRIBUTING.md)

woninet-2.0.1/README.md

@@ -0,0 +1,216 @@
+# woninet
+
+A local network monitoring system.
+
+**woninet** continuously monitors devices on a local network using ARP
+and ICMP probes. It enumerates candidate IP addresses in a /24 subnet,
+determines device availability, measures latency and packet loss, stores
+metrics in SQLite, and evaluates configurable alert rules in real time.
+
+**Note: This script requires sudo privileges.**
+
+## Features
+
+- **ARP + ICMP Host Detection** (Distinguishes real devices from nonexistent
+IPs and filters out Wi‑Fi ARP‑delay noise.)
+
+- **Alert Engine** (Evaluates real‑time alert rules (e.g., latency thresholds))
+
+- **Threaded Collectors**
+
+- **SQLite database** (for devices, recorded metrics, alert states, and alert events.)
+
+- **Positional Argument for easier access to the database from the CLI**
+
+- **Detailed Logging**
+
+## Future Plans
+
+- Add ARP table caching to further reduce Wi‑Fi latency noise.
+- Accept MAC addresses as command‑line arguments.
+- Fetch MAC address from database for offline devices.
+- Use ARP noise limit as device state for styling in front-end.
+- Add CLI argument to accept target IP addresses from a file.
+
+## Known Issues
+
+- Monitoring Scope Limited to /24 Subnet
+
+## How To Run
+
+**Note:** *woninet* is under active development.
+
+## Installation
+
+Install from PyPI:
+
+```shell
+pip install woninet
+```
+
+Then run:
+
+```shell
+woninet --help
+```
+
+## Installation from Source
+
+### 1. Clone the repository
+
+```shell
+git clone https://github.com/teymuri-alireza/woninet
+cd woninet
+```
+
+### 2. Create and activate a virtual environment:
+
+**Note:** Create the virtual environment outside the project directory to avoid
+`Multiple top-level packages discovered in a flat-layout` errors.
+
+**Unix/Linux note:** The `--copies` flag forces Python to copy the interpreter
+instead of using a symbolic link. This is required because you will apply Linux
+capabilities directly to the Python binary in the virtual environment.
+
+#### Linux/macOS
+
+```shell
+python3 -m venv --copies ../venv
+source ../venv/bin/activate
+```
+
+#### Windows (PowerShell)
+
+```shell
+py -m venv ..\venv
+..\venv\Scripts\Activate.ps1
+```
+
+### 3. Install woninet locally:
+
+```shell
+pip3 install .
+```
+
+### 4. Run woninet
+
+**Unix/Linux only:** To allow raw ICMP without running as root, grant the required
+capability to the Python interpreter inside the virtual environment:
+
+```shell
+sudo setcap cap_net_raw=eip ../venv/bin/python3
+```
+
+Finally, run woninet normally:
+
+```shell
+woninet --version
+```
+
+**Alternative (not recommended):** You can run woninet with sudo instead of using
+setcap, but this is discouraged for security reasons:
+
+```shell
+sudo ../venv/bin/python3 -m woninet
+```
+
+## Configuration
+
+You can define alert rules in a JSON file. Rename the example file at
+`woninet/config.example.json` to `config.json`. The application will load the alert
+rules from that file at startup.
+
+### Example:
+
+```json
+{
+    "monitoring": {
+        "arp_noise_limit": 300.0,
+        "max_workers": 4
+    },
+    "database": "woninet.db",
+    "target_ip_list": [
+        "192.168.1.1-100"
+        // or
+        "192.168.1.1", "192.168.1.10", "192.168.1.20"
+    ],
+    "alert_rules":[
+        {
+            "metric": "latency",
+            "threshold": 100,
+            "consecutive_checks": 3
+        },
+        {
+            "metric": "packet_loss",
+            "threshold": 0.0,
+            "consecutive_checks": 1
+        }
+    ]
+}
+```
+
+### Explanations:
+
+#### Monitoring Settings
+
+- **arp_noise_limit**: Latency threshold in milliseconds used to filter ARP
+resolution noise. Set to 0 to disable filtering. Helps eliminate Wi‑Fi latency spikes.
+- **max_workers**: Maximum number of thread workers used to send ICMP pings.
+Higher values may increase system load and latency.
+
+#### Database
+
+- **database**: The path to the SQLite database file where metrics and alerts are stored.
+
+#### Target IP List
+
+- A single or range of target IP addresses to scan.
+
+#### Alert Rules
+
+- **metric**: The metric name to evaluate (`latency` or `packet_loss`)
+- **threshold**: The value that triggers the alert. For latency, this is in milliseconds.
+For packet loss, this is a percentage (0.0-100.0).
+- **consecutive_checks**: The number of consecutive evaluations required before the alert
+state changes. Higher values reduce false positives.
+
+#### Notes
+
+- **Packet Loss**: Values are in the range [0.0, 100.0]. A value of 100.0 indicates 100%
+packet loss. A value of 0.0 will trigger on any packet loss.
+- **Latency**: All latency thresholds are evaluated in milliseconds.
+
+## Usage
+
+This [guide](./docs/usage.md) explains common ways to run *woninet* and how to resolve common issues.
+
+## Testing
+
+If you want to run the test suite locally, install the optional test dependencies:
+
+```shell
+pip install -e ".[test]"
+```
+
+Then run:
+
+```shell
+pytest
+```
+
+The test suite currently focuses on API behavior and core logic, and it uses pytest for automated verification.
+
+## Requirements
+
+- Python >= 3.12
+- Root privileges
+
+## Documentation
+
+if you have any question or need clarification, check the [documentation](./docs/documentation.md) guide.
+
+## Contribution
+
+Thanks for considering contributing to *woninet!*
+To help us maintain code quality, stability, and a predictable release process, please review
+and follow the guidelines in our [Contributing Guide.](./CONTRIBUTING.md)

woninet-2.0.1/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=80", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "woninet"
+version = "2.0.1"
+description = "A Python-based ARP+ICMP network monitoring tool"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+
+authors = [
+    { name = "Alireza Teymuri", email = "teymuri.alireza98@gmail.com" }
+]
+
+keywords = [
+    "network",
+    "network-monitoring",
+    "icmp",
+    "arp",
+]
+
+dependencies = [
+    "icmplib>=3.0.4,<3.1",
+    "fastapi>=0.136.0,<0.137",
+    "Jinja2>=3.1.6,<3.2",
+    "uvicorn>=0.44.0,<0.45",
+    "PyYAML>=6.0.3,<6.1",
+    "SQLAlchemy>=2.0.46,<2.1",
+    "matplotlib>=3.11.0,<3.12",
+]
+
+[tool.setuptools.package-data]
+woninet = [
+    "server/static/**/*",
+    "server/templates/**/*",
+    "logging.yaml",
+]
+
+[project.urls]
+Homepage = "https://github.com/teymuri-alireza/woninet"
+Documentation = "https://github.com/teymuri-alireza/woninet/tree/main/docs"
+Repository = "https://github.com/teymuri-alireza/woninet"
+Issues = "https://github.com/teymuri-alireza/woninet/issues"
+Changelog = "https://github.com/teymuri-alireza/woninet/blob/main/CHANGELOG.md"
+
+[project.scripts]
+woninet = "woninet.main:main"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=9.1.1,<9.2",
+    "httpx>=0.28.1,<0.29",
+]

woninet-2.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

woninet-2.0.1/tests/test_alert_events.py

@@ -0,0 +1,151 @@
+from woninet.core.storage import StorageEngine
+from woninet.core.models import MetricRecord
+from woninet.core.alerts import AlertRule, AlertEngine
+
+
+def test_latency_trigger_alert_event(db_session):
+    storage = StorageEngine(session_factory=lambda: db_session)
+
+    metric = MetricRecord(device_ip="192.168.1.10", metric="latency", value=200)
+    storage.store_metric(metric)
+
+    alert_rule = {"metric": "latency", "threshold": 100, "consecutive_checks": 0}
+
+    alert = AlertEngine(
+        storage=storage,
+        rules=[
+            AlertRule(
+                alert_rule["metric"],
+                alert_rule["threshold"],
+                alert_rule["consecutive_checks"],
+            )
+        ],
+    )
+
+    alert.evaluate(
+        ip="192.168.1.10",
+        metrics_list=[
+            MetricRecord(device_ip="192.168.1.10", metric="latency", value=200),
+        ],
+        default_consecutive_checks={
+            "latency": 0,
+        },
+    )
+
+    latency = storage.get_recent_alert_events()[0]
+
+    assert latency.event_type == "trigger"
+
+
+def test_packet_loss_trigger_alert_event(db_session):
+    storage = StorageEngine(session_factory=lambda: db_session)
+
+    metric = MetricRecord(device_ip="192.168.1.10", metric="packet_loss", value=0.5)
+    storage.store_metric(metric)
+
+    alert_rule = {"metric": "packet_loss", "threshold": 0.0, "consecutive_checks": 0}
+
+    alert = AlertEngine(
+        storage=storage,
+        rules=[
+            AlertRule(
+                alert_rule["metric"],
+                alert_rule["threshold"],
+                alert_rule["consecutive_checks"],
+            )
+        ],
+    )
+
+    alert.evaluate(
+        ip="192.168.1.10",
+        metrics_list=[
+            MetricRecord(device_ip="192.168.1.10", metric="packet_loss", value=0.5),
+        ],
+        default_consecutive_checks={
+            "packet_loss": 0,
+        },
+    )
+
+    packet_loss = storage.get_recent_alert_events()[0]
+
+    assert packet_loss.event_type == "trigger"
+
+
+def test_latency_recover_alert_event(db_session):
+    storage = StorageEngine(session_factory=lambda: db_session)
+
+    metric = MetricRecord(device_ip="192.168.1.10", metric="latency", value=20)
+    storage.store_metric(metric)
+
+    state = storage.get_or_create_alert_state(
+        ip="192.168.1.10", metric="latency", consecutive_checks=0
+    )
+    state.state = "warning"
+    storage.update_alert_state(state)
+
+    alert_rule = {"metric": "latency", "threshold": 100, "consecutive_checks": 0}
+
+    alert = AlertEngine(
+        storage=storage,
+        rules=[
+            AlertRule(
+                alert_rule["metric"],
+                alert_rule["threshold"],
+                alert_rule["consecutive_checks"],
+            )
+        ],
+    )
+
+    alert.evaluate(
+        ip="192.168.1.10",
+        metrics_list=[
+            MetricRecord(device_ip="192.168.1.10", metric="latency", value=20),
+        ],
+        default_consecutive_checks={
+            "latency": 0,
+        },
+    )
+
+    latency = storage.get_recent_alert_events()[0]
+
+    assert latency.event_type == "recover"
+
+
+def test_packet_loss_recover_alert_event(db_session):
+    storage = StorageEngine(session_factory=lambda: db_session)
+
+    metric = MetricRecord(device_ip="192.168.1.10", metric="packet_loss", value=0.0)
+    storage.store_metric(metric)
+
+    state = storage.get_or_create_alert_state(
+        ip="192.168.1.10", metric="packet_loss", consecutive_checks=0
+    )
+    state.state = "warning"
+    storage.update_alert_state(state)
+
+    alert_rule = {"metric": "packet_loss", "threshold": 0.0, "consecutive_checks": 0}
+
+    alert = AlertEngine(
+        storage=storage,
+        rules=[
+            AlertRule(
+                alert_rule["metric"],
+                alert_rule["threshold"],
+                alert_rule["consecutive_checks"],
+            )
+        ],
+    )
+
+    alert.evaluate(
+        ip="192.168.1.10",
+        metrics_list=[
+            MetricRecord(device_ip="192.168.1.10", metric="packet_loss", value=0.0),
+        ],
+        default_consecutive_checks={
+            "packet_loss": 0,
+        },
+    )
+
+    packet_loss = storage.get_recent_alert_events()[0]
+
+    assert packet_loss.event_type == "recover"

woninet-2.0.1/tests/test_api.py

@@ -0,0 +1,10 @@
+def test_dashboard_endpoint(client):
+    response = client.get("/")
+    assert response.status_code == 200
+
+
+def test_devices_api_returns_mocked_devices(client):
+    response = client.get("/api/devices")
+
+    assert response.status_code == 200
+    assert response.json()["devices"][0]["ip"] == "192.168.1.10"