woninet 2.0.3__tar.gz → 2.2.0__tar.gz

woninet-2.2.0/PKG-INFO

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: woninet
+Version: 2.2.0
+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: python-multipart==0.0.32
+Requires-Dist: fastapi-swagger<0.5,>=0.4.64
+Provides-Extra: test
+Requires-Dist: pytest<9.2,>=9.1.1; extra == "test"
+Requires-Dist: httpx<0.29,>=0.28.1; extra == "test"
+Requires-Dist: ruff<0.16,>=0.15.11; extra == "test"
+Dynamic: license-file
+
+# Woninet
+
+[![PyPI version](https://img.shields.io/pypi/v/woninet)](https://pypi.org/project/woninet/)
+[![Python](https://img.shields.io/badge/python-3.12-blue)](https://www.python.org/)
+[![License](https://img.shields.io/pypi/l/woninet)](https://github.com/teymuri-alireza/woninet/blob/main/LICENSE)
+[![Downloads](https://img.shields.io/pypi/dm/woninet)](https://pypi.org/project/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, packet loss, and jitter, stores metrics in database, and evaluates configurable alert rules in real time.
+
+![Woninet dashboard](https://github.com/teymuri-alireza/woninet/blob/dev/public/img/woninet-dasboard.png)
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Platform Notes](#platform-notes)
+- [Testing](#testing)
+- [Known Issues](#known-issues)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- **ARP + ICMP host detection.** Distinguishes real devices from nonexistent IP addresses and filters out Wi-Fi ARP-delay noise.
+- **Alert engine.** Evaluates real-time alert rules, such as latency thresholds, against collected metrics.
+- **Threaded collectors.** Sends ICMP probes concurrently using a configurable number of worker threads.
+- **SQLite storage.** Persists devices, recorded metrics, alert states, and alert events.
+- **Database access from the CLI.** Accepts a positional argument for easier access to the database.
+- **Detailed logging.**
+
+## Requirements
+
+- Python 3.12 or later.
+- Elevated network privileges, because ARP and ICMP probing use raw sockets. On Linux, either of the following satisfies this requirement:
+  - the `cap_net_raw` capability granted to the Python interpreter (recommended, see [Installation](#installation)), or
+  - root privileges (discouraged for security reasons).
+
+## Quick Start
+
+On Linux, the minimal path is:
+
+```shell
+python3 -m venv --copies venv
+source venv/bin/activate
+pip install woninet
+sudo setcap cap_net_raw=eip venv/bin/python3
+woninet --help
+```
+
+For Docker, macOS, Windows, and source installs, see [Installation](#installation).
+
+## Installation
+
+### Option 1: Install from PyPI
+
+#### Linux (recommended: `icmplib` with `cap_net_raw`)
+
+Create and activate a virtual environment. The `--copies` flag forces Python to copy the interpreter instead of symlinking it, which is required because the capability is applied directly to the interpreter binary:
+
+```shell
+python3 -m venv --copies venv
+source venv/bin/activate
+```
+
+Install Woninet:
+
+```shell
+pip install woninet
+```
+
+Grant the required capability to the Python interpreter:
+
+```shell
+sudo setcap cap_net_raw=eip venv/bin/python3
+```
+
+Run Woninet:
+
+```shell
+woninet --help
+```
+
+#### Linux (fallback: system `ping`)
+
+If you do not grant the capability, Woninet falls back to the system `ping` command. Create the environment without `--copies`:
+
+```shell
+python3 -m venv venv
+source venv/bin/activate
+pip install woninet
+woninet --help
+```
+
+#### macOS and Windows
+
+```shell
+pip install woninet
+woninet --help
+```
+
+See [Platform Notes](#platform-notes) for privilege considerations on these systems.
+
+### Option 2: Docker (Linux only)
+
+Clone the repository and run:
+
+```shell
+chmod +x build_docker.sh
+sudo ./build_docker.sh
+```
+
+The script runs `docker compose up -d --build` and prints the device's private IP address to standard output so you can open the web interface in a browser.
+
+To open Woninet manually, type device's private IP address with the default `8080` port in the browser.
+
+### Option 3: Install from source
+
+1. Clone the repository:
+
+    ```shell
+    git clone https://github.com/teymuri-alireza/woninet
+    cd woninet
+    ```
+
+2. Create and activate a virtual environment **outside** the project directory to avoid `Multiple top-level packages discovered in a flat-layout` errors.
+
+    Linux
+
+    ```shell
+    python3 -m venv --copies ../venv
+    source ../venv/bin/activate
+    ```
+
+    Windows (PowerShell):
+
+    ```powershell
+    py -m venv ..\venv
+    ..\venv\Scripts\Activate.ps1
+    ```
+
+3. Install Woninet locally:
+
+   ```shell
+   pip3 install .
+   ```
+
+4. Grant raw-socket access and run.
+
+   **Linux:** grant the capability to the virtual environment's interpreter, then run Woninet:
+
+   ```shell
+   sudo setcap cap_net_raw=eip ../venv/bin/python3
+   woninet --version
+   ```
+
+   Running with `sudo` instead is possible but discouraged for security reasons:
+
+   ```shell
+   sudo ../venv/bin/python3 -m woninet
+   ```
+
+   **macOS and Windows:** run `woninet --version` after installation.
+
+## Configuration
+
+Alert rules and monitoring settings are defined in a JSON file. Rename `config.example.json` to `config.json`; Woninet loads it at startup.
+
+When installing from PyPI, `config.example.json` is not included, so Woninet creates a `config.json` file with default values.
+
+To use a different configuration file, pass its path with the `--config` CLI flag.
+
+### Example
+
+```json
+{
+    "monitoring": {
+        "arp_noise_limit": 300.0,
+        "max_workers": 4
+    },
+    "database": "woninet.db",
+    "target_ip_list": [
+        "192.168.1.1", "192.168.1.10", "192.168.1.20-30"
+    ],
+    "alert_rules": [
+        {
+            "metric": "latency",
+            "threshold": 100,
+            "consecutive_checks": 3
+        },
+        {
+            "metric": "packet_loss",
+            "threshold": 0.0,
+            "consecutive_checks": 1
+        },
+        {
+            "metric": "jitter",
+            "threshold": 40.0,
+            "consecutive_checks": 3
+        }
+    ]
+}
+```
+
+### Settings reference
+
+#### Monitoring
+
+| Key | Description |
+|---|---|
+| `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 worker threads used to send ICMP pings. Higher values may increase system load and latency. |
+
+#### Database
+
+| Key | Description |
+|---|---|
+| `database` | Path to the SQLite database file where metrics and alerts are stored. |
+
+#### Target IP list
+
+| Key | Description |
+|---|---|
+| `target_ip_list` | A single address, a list of addresses, or a range (for example `192.168.1.1-100`) to scan. Monitoring is currently limited to a /24 subnet (see [Known Issues](#known-issues)). |
+
+#### Alert rules
+
+| Key | Description |
+|---|---|
+| `metric` | The metric to evaluate: `latency`, `packet_loss`, or `jitter`. |
+| `threshold` | The value that triggers the alert. |
+| `consecutive_checks` | Number of consecutive evaluations required before the alert state changes. Higher values reduce false positives. |
+
+#### Units and ranges
+
+- **Latency:** thresholds are evaluated in milliseconds.
+- **Jitter:** thresholds are evaluated in milliseconds.
+- **Packet loss:** values are percentages in the range 0.0 to 100.0. A value of 100.0 indicates 100% packet loss, and a threshold of 0.0 triggers on any packet loss.
+
+## Usage
+
+See the [usage guide](https://github.com/teymuri-alireza/woninet/blob/main/docs/usage.md) for common ways to run Woninet and how to resolve common issues.
+
+## Platform Notes
+
+| Platform | Probing method | Privileges |
+|---|---|---|
+| Linux | `icmplib` (recommended) or system `ping` (fallback) | `cap_net_raw` on the interpreter, or root |
+| macOS | Untested | Untested |
+| Windows | Untested | Untested |
+
+Woninet has been developed and tested on Linux. macOS and Windows have not been tested, so installation and behavior on those platforms are not guaranteed. Feedback and bug reports from users on these systems are welcome.
+
+Docker deployment is available on Linux only.
+
+## Testing
+
+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 uses pytest for automated verification.
+
+## Known Issues
+
+- Monitoring is currently limited to a single /24 subnet.
+
+## Documentation
+
+For questions or clarification, see the [documentation](https://github.com/teymuri-alireza/woninet/blob/main/docs/documentation.md).
+
+## Contributing
+
+Thank you for considering a contribution to Woninet. To help maintain code quality, stability, and a predictable release process, please review the [Contributing Guide](https://github.com/teymuri-alireza/woninet/blob/main/CONTRIBUTING.md) before submitting changes.
+
+## License
+
+This project is licensed under the terms of the MIT license.

woninet-2.2.0/README.md

@@ -0,0 +1,292 @@
+# Woninet
+
+[![PyPI version](https://img.shields.io/pypi/v/woninet)](https://pypi.org/project/woninet/)
+[![Python](https://img.shields.io/badge/python-3.12-blue)](https://www.python.org/)
+[![License](https://img.shields.io/pypi/l/woninet)](https://github.com/teymuri-alireza/woninet/blob/main/LICENSE)
+[![Downloads](https://img.shields.io/pypi/dm/woninet)](https://pypi.org/project/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, packet loss, and jitter, stores metrics in database, and evaluates configurable alert rules in real time.
+
+![Woninet dashboard](https://github.com/teymuri-alireza/woninet/blob/dev/public/img/woninet-dasboard.png)
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Platform Notes](#platform-notes)
+- [Testing](#testing)
+- [Known Issues](#known-issues)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- **ARP + ICMP host detection.** Distinguishes real devices from nonexistent IP addresses and filters out Wi-Fi ARP-delay noise.
+- **Alert engine.** Evaluates real-time alert rules, such as latency thresholds, against collected metrics.
+- **Threaded collectors.** Sends ICMP probes concurrently using a configurable number of worker threads.
+- **SQLite storage.** Persists devices, recorded metrics, alert states, and alert events.
+- **Database access from the CLI.** Accepts a positional argument for easier access to the database.
+- **Detailed logging.**
+
+## Requirements
+
+- Python 3.12 or later.
+- Elevated network privileges, because ARP and ICMP probing use raw sockets. On Linux, either of the following satisfies this requirement:
+  - the `cap_net_raw` capability granted to the Python interpreter (recommended, see [Installation](#installation)), or
+  - root privileges (discouraged for security reasons).
+
+## Quick Start
+
+On Linux, the minimal path is:
+
+```shell
+python3 -m venv --copies venv
+source venv/bin/activate
+pip install woninet
+sudo setcap cap_net_raw=eip venv/bin/python3
+woninet --help
+```
+
+For Docker, macOS, Windows, and source installs, see [Installation](#installation).
+
+## Installation
+
+### Option 1: Install from PyPI
+
+#### Linux (recommended: `icmplib` with `cap_net_raw`)
+
+Create and activate a virtual environment. The `--copies` flag forces Python to copy the interpreter instead of symlinking it, which is required because the capability is applied directly to the interpreter binary:
+
+```shell
+python3 -m venv --copies venv
+source venv/bin/activate
+```
+
+Install Woninet:
+
+```shell
+pip install woninet
+```
+
+Grant the required capability to the Python interpreter:
+
+```shell
+sudo setcap cap_net_raw=eip venv/bin/python3
+```
+
+Run Woninet:
+
+```shell
+woninet --help
+```
+
+#### Linux (fallback: system `ping`)
+
+If you do not grant the capability, Woninet falls back to the system `ping` command. Create the environment without `--copies`:
+
+```shell
+python3 -m venv venv
+source venv/bin/activate
+pip install woninet
+woninet --help
+```
+
+#### macOS and Windows
+
+```shell
+pip install woninet
+woninet --help
+```
+
+See [Platform Notes](#platform-notes) for privilege considerations on these systems.
+
+### Option 2: Docker (Linux only)
+
+Clone the repository and run:
+
+```shell
+chmod +x build_docker.sh
+sudo ./build_docker.sh
+```
+
+The script runs `docker compose up -d --build` and prints the device's private IP address to standard output so you can open the web interface in a browser.
+
+To open Woninet manually, type device's private IP address with the default `8080` port in the browser.
+
+### Option 3: Install from source
+
+1. Clone the repository:
+
+    ```shell
+    git clone https://github.com/teymuri-alireza/woninet
+    cd woninet
+    ```
+
+2. Create and activate a virtual environment **outside** the project directory to avoid `Multiple top-level packages discovered in a flat-layout` errors.
+
+    Linux
+
+    ```shell
+    python3 -m venv --copies ../venv
+    source ../venv/bin/activate
+    ```
+
+    Windows (PowerShell):
+
+    ```powershell
+    py -m venv ..\venv
+    ..\venv\Scripts\Activate.ps1
+    ```
+
+3. Install Woninet locally:
+
+   ```shell
+   pip3 install .
+   ```
+
+4. Grant raw-socket access and run.
+
+   **Linux:** grant the capability to the virtual environment's interpreter, then run Woninet:
+
+   ```shell
+   sudo setcap cap_net_raw=eip ../venv/bin/python3
+   woninet --version
+   ```
+
+   Running with `sudo` instead is possible but discouraged for security reasons:
+
+   ```shell
+   sudo ../venv/bin/python3 -m woninet
+   ```
+
+   **macOS and Windows:** run `woninet --version` after installation.
+
+## Configuration
+
+Alert rules and monitoring settings are defined in a JSON file. Rename `config.example.json` to `config.json`; Woninet loads it at startup.
+
+When installing from PyPI, `config.example.json` is not included, so Woninet creates a `config.json` file with default values.
+
+To use a different configuration file, pass its path with the `--config` CLI flag.
+
+### Example
+
+```json
+{
+    "monitoring": {
+        "arp_noise_limit": 300.0,
+        "max_workers": 4
+    },
+    "database": "woninet.db",
+    "target_ip_list": [
+        "192.168.1.1", "192.168.1.10", "192.168.1.20-30"
+    ],
+    "alert_rules": [
+        {
+            "metric": "latency",
+            "threshold": 100,
+            "consecutive_checks": 3
+        },
+        {
+            "metric": "packet_loss",
+            "threshold": 0.0,
+            "consecutive_checks": 1
+        },
+        {
+            "metric": "jitter",
+            "threshold": 40.0,
+            "consecutive_checks": 3
+        }
+    ]
+}
+```
+
+### Settings reference
+
+#### Monitoring
+
+| Key | Description |
+|---|---|
+| `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 worker threads used to send ICMP pings. Higher values may increase system load and latency. |
+
+#### Database
+
+| Key | Description |
+|---|---|
+| `database` | Path to the SQLite database file where metrics and alerts are stored. |
+
+#### Target IP list
+
+| Key | Description |
+|---|---|
+| `target_ip_list` | A single address, a list of addresses, or a range (for example `192.168.1.1-100`) to scan. Monitoring is currently limited to a /24 subnet (see [Known Issues](#known-issues)). |
+
+#### Alert rules
+
+| Key | Description |
+|---|---|
+| `metric` | The metric to evaluate: `latency`, `packet_loss`, or `jitter`. |
+| `threshold` | The value that triggers the alert. |
+| `consecutive_checks` | Number of consecutive evaluations required before the alert state changes. Higher values reduce false positives. |
+
+#### Units and ranges
+
+- **Latency:** thresholds are evaluated in milliseconds.
+- **Jitter:** thresholds are evaluated in milliseconds.
+- **Packet loss:** values are percentages in the range 0.0 to 100.0. A value of 100.0 indicates 100% packet loss, and a threshold of 0.0 triggers on any packet loss.
+
+## Usage
+
+See the [usage guide](https://github.com/teymuri-alireza/woninet/blob/main/docs/usage.md) for common ways to run Woninet and how to resolve common issues.
+
+## Platform Notes
+
+| Platform | Probing method | Privileges |
+|---|---|---|
+| Linux | `icmplib` (recommended) or system `ping` (fallback) | `cap_net_raw` on the interpreter, or root |
+| macOS | Untested | Untested |
+| Windows | Untested | Untested |
+
+Woninet has been developed and tested on Linux. macOS and Windows have not been tested, so installation and behavior on those platforms are not guaranteed. Feedback and bug reports from users on these systems are welcome.
+
+Docker deployment is available on Linux only.
+
+## Testing
+
+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 uses pytest for automated verification.
+
+## Known Issues
+
+- Monitoring is currently limited to a single /24 subnet.
+
+## Documentation
+
+For questions or clarification, see the [documentation](https://github.com/teymuri-alireza/woninet/blob/main/docs/documentation.md).
+
+## Contributing
+
+Thank you for considering a contribution to Woninet. To help maintain code quality, stability, and a predictable release process, please review the [Contributing Guide](https://github.com/teymuri-alireza/woninet/blob/main/CONTRIBUTING.md) before submitting changes.
+
+## License
+
+This project is licensed under the terms of the MIT license.

{woninet-2.0.3 → woninet-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "woninet"
-version = "2.0.3"
+version = "2.2.0"
 description = "A Python-based ARP+ICMP network monitoring tool"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -28,9 +28,13 @@ dependencies = [
     "uvicorn>=0.44.0,<0.45",
     "PyYAML>=6.0.3,<6.1",
     "SQLAlchemy>=2.0.46,<2.1",
-    "matplotlib>=3.11.0,<3.12",
+    "python-multipart==0.0.32",
+    "fastapi-swagger>=0.4.64,<0.5",
 ]
 
+[tool.setuptools.packages.find]
+include = ["woninet*"]
+
 [tool.setuptools.package-data]
 woninet = [
     "server/static/**/*",
@@ -52,4 +56,5 @@ woninet = "woninet.main:main"
 test = [
     "pytest>=9.1.1,<9.2",
     "httpx>=0.28.1,<0.29",
+    "ruff>=0.15.11,<0.16",
 ]