woninet 2.0.1__py3-none-any.whl

woninet/server/templates/device_info.html

@@ -0,0 +1,93 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Device Info</title>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.6.0/css/all.min.css">
+    <link rel="stylesheet" href="/static/css/style.css">
+</head>
+<body>
+    <div class="dashboard">
+        <header class="topbar">
+            <div>
+                <p class="eyebrow">Device Details</p>
+                <h1 id="device-ip"></h1>
+                <p class="subtitle">Live monitoring and alert history</p>
+            </div>
+        </header>
+
+        <section class="overview-grid">
+            <div class="kpi-card">
+                <div class="kpi-icon primary">
+                    <i class="fa-solid fa-network-wired"></i>
+                    <span>MAC Address</span>
+                </div>
+                <h2 style="font-size: 1rem;" id="device-mac"></h2>
+            </div>
+            <div class="kpi-card">
+                <div class="kpi-icon primary">
+                    <i class="fa-solid fa-wave-square"></i>
+                    <span>Latency</span>
+                </div>
+                <h2 id="device-latency"></h2>
+            </div>
+            <div class="kpi-card">
+                <div class="kpi-icon warning">
+                    <i class="fa-solid fa-triangle-exclamation"></i>
+                    <span>Packet Loss</span>
+                </div>
+                <h2 id="device-packet-loss"></h2>
+            </div>
+        </section>
+
+        <main class="main-layout">
+            <section class="panel">
+                <div class="panel-header">
+                    <h2>Device Details</h2>
+                </div>
+                <div class="device-grid">
+                    <article class="device-card" id="device-card">
+                        <div class="device-header">
+                            <div class="device-status" id="device-status"></div>
+                        </div>
+                        
+                        <div class="metrics">
+                            <div class="metric">
+                                <div class="metric-label">Last Seen</div>
+                                <div class="metric-value" id="device-last-seen"></div>
+                            </div>
+                            <div class="metric">
+                                <div class="metric-label">Latency State</div>
+                                <div class="metric-value" id="alert-state-latency"></div>
+                            </div>
+                            <div class="metric">
+                                <div class="metric-label">Packet Loss State</div>
+                                <div class="metric-value" id="alert-state-packet-loss">}</div>
+                            </div>
+                        </div>
+                    </article>
+                </div>
+            </section>
+
+            <aside class="events-panel">
+                <h3>Alert Events</h3>
+                <div id="events"></div>
+            </aside>
+        </main>
+
+        <br />
+        <section class="panel">
+            <h2>Recent Device Events Graph</h2>
+            <img width="100%" src="placeholder" alt="Device recent events line graph" id="device-recent-events-line-graph"/>
+        </section>
+
+        <div style="margin-top: 20px;">
+            <a href="/" class="back-link">Back to Dashboard</a>
+        </div>
+    </div>
+
+    <script src="/static/js/device_info.js"></script>
+</body>
+</html>

woninet/utilities/__init__.py

@@ -0,0 +1,2 @@
+# woninet/core/__init__.py
+# (This file intentionally left blank)

woninet/utilities/arguments.py

@@ -0,0 +1,94 @@
+import argparse
+from woninet.utilities.cli_parser import list_devices, show_device_info, report_stats
+
+
+def args() -> argparse.Namespace:
+    """
+    The argument handler.
+
+    check `woninet -h` for more info.
+    """
+    description = """
+A local network monitoring system. It enumerates all candidate IP addresses in your /24 subnet
+and performs ARP + ICMP host detection to determine existence, reachability, and latency. Metrics
+are collected continuously and processed through an alert engine."""
+
+    epilog = ""
+
+    parser = argparse.ArgumentParser(
+        description=description,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="woninet",
+        epilog=epilog,
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    device_parser = subparsers.add_parser(
+        "device", help="Fetch Device informations from the database."
+    )
+    device_subparsers = device_parser.add_subparsers(dest="action", required=True)
+
+    device_list = device_subparsers.add_parser(
+        "list", description="List all devices.", help="List all devices."
+    )
+    device_list.set_defaults(func=list_devices)
+
+    device_show = device_subparsers.add_parser(
+        "show", description="Show device info for a given IP.", help="Show device info."
+    )
+    device_show.add_argument("ip", help="Device IP address")
+    device_show.set_defaults(func=show_device_info)
+
+    stats_parser = subparsers.add_parser(
+        "stats", help="Output a JSON report for the woninet statistics."
+    )
+
+    stats_parser.add_argument(
+        "--output",
+        default="stats.json",
+        help="Output path for the JSON report for the woninet statistics (default: %(default)s).",
+    )
+    stats_parser.set_defaults(func=report_stats)
+
+    parser.add_argument(
+        "--cli",
+        action="store_true",
+        help="Run woninet in CLI mode.",
+    )
+
+    parser.add_argument(
+        "-p",
+        "--port",
+        type=int,
+        default=8080,
+        help="Port number to serve the web dashboard (defaut: %(default)s).",
+    )
+
+    parser.add_argument(
+        "--logs",
+        type=str,
+        help="Output path for storing logs.",
+    )
+
+    parser.add_argument(
+        "--color",
+        type=str,
+        choices=["true", "false"],
+        default="true",
+        help="Whether to enable colored console log output (default: %(default)s)",
+    )
+
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="Increase verbosity (repeat for more detail)",
+    )
+
+    parser.add_argument(
+        "-V", "--version", action="store_true", help="Prints the version and quit."
+    )
+
+    return parser.parse_args()

woninet/utilities/cli_parser.py

@@ -0,0 +1,90 @@
+import json
+from typing import Any
+from woninet.main import NetworkMonitorCore
+
+
+def list_devices(args):
+    """
+    Prints list of recorded devices information from the database to stdout.
+    Following entries are shown:
+    1. Device IP address.
+    2. Device MAC address.
+    3. Device last seen timestamp.
+    """
+    monitor: NetworkMonitorCore = args.monitor
+    devices = monitor.get_device_history()
+    if len(devices) == 0:
+        print("No recorded device was found.")
+    else:
+        for device in devices:
+            row = f"Device {device.ip}: MAC={device.mac}, Last seen={device.last_seen}"
+            print(row)
+
+
+def show_device_info(args):
+    """
+    Prints information for a given IP address. Following entries are shown:
+    1. Device IP address.
+    2. Device MAC address.
+    3. Device last captured latency.
+    4. Device last seen timestamp.
+    5. Last alert state of device.
+    6. Last 10 alert events of device.
+    """
+    monitor: NetworkMonitorCore = args.monitor
+    device, devices_state, recent_device_alert_events = monitor.get_device_info(args.ip)
+    if device is None:
+        print(f"Device {args.ip} was not found.")
+    else:
+        latency = device.latency
+        if latency == 0:
+            latency = "OFFLINE"
+        print(
+            f"Found device {device.ip}: MAC={device.mac}, Last latency: {latency}, Last seen={device.last_seen}"
+        )
+        for metric, state in devices_state.items():
+            print(f"Current alert state for {metric}: state={state}")
+        print("Recent alert events:")
+        for event in recent_device_alert_events:
+            content = f"ID: {event.id} - Metric: {event.metric},\t Value={event.value},"
+            content += (
+                f"\t Event type={event.event_type},\t Timestamp={event.timestamp}"
+            )
+            print(content)
+
+
+def report_stats(args) -> None:
+    """
+    Output statistics report into given file.
+    following statistics are provided:
+    1. devices count.
+    2. devices list.
+    3. recent alert events.
+    """
+    try:
+        monitor: NetworkMonitorCore = args.monitor
+        devices_count = monitor.count_resources()[0]
+        devices = monitor.get_device_history()
+        output: str = args.output
+        result: dict[str, Any] = {}
+
+        result["devices_count"] = devices_count
+        result["devices"] = [
+            {
+                "ip": dev.ip,
+                "mac": dev.mac,
+                "last_seen": dev.last_seen.isoformat(),
+                "alert_state": monitor.storage.get_device_alert_state(ip=dev.ip),
+            }
+            for dev in devices
+        ]
+
+        result["recent_alert_events"] = monitor.classify_recent_alert_events()
+
+        with open(output, "w") as stats:
+            json.dump(result, stats, indent=2)
+
+        print(f"Statistics report saved to {output}")
+
+    except Exception as e:
+        print(e)

woninet/utilities/detect_ip_range.py

@@ -0,0 +1,21 @@
+def detect_ip_range(ip: str) -> bool:
+    """
+    Detect if an IP address is provided as a range.
+    (e.g., `192.168.10.10-20`)
+
+    Args:
+        ip (str): IP address to detect.
+
+    Returns:
+        bool: Boolean indicating if IP address is provided as a range.
+
+    Raises:
+        ValueError: If the range notation is used in any of the first three octets.\n
+            (e.g., `192.168.1-10.10` - `192.168-188.1.10` - `192.180.168.1.10`)
+    """
+    base, last_octet = ip.rsplit(".", maxsplit=1)
+    if "-" in base:
+        raise ValueError("Ip addess range is only allowed in the last octet.")
+    if "-" in last_octet:
+        return True
+    return False

woninet/utilities/ip_validator.py

@@ -0,0 +1,39 @@
+from ipaddress import ip_address
+from woninet.core.models import Device
+
+
+def is_ip_list_valid(ip_list: list[str]) -> bool:
+    """
+    Validate a list of IP addresses.
+
+    Args:
+        ip_list (list[str]): IP addresses to validate.
+
+    Returns:
+        bool: Boolean indicating if IP addresses are valid.
+    """
+    for ip in ip_list:
+        try:
+            ip_address(ip)
+        except ValueError:
+            return False
+    return True
+
+
+def is_device_ip_valid(devices: dict[str, Device]) -> bool:
+    """
+    Validate the dictionary of candidate devices.
+
+    Args:
+        devices (dict[str,Device]): Dictrionary of IP addresses and Device model
+            instances to validate.
+
+    Returns:
+        bool: Boolean indicating if IP addresses are valid.
+    """
+    for ip, dev in devices.items():
+        try:
+            ip_address(ip)
+        except ValueError:
+            return False
+    return True

woninet/utilities/logger.py

@@ -0,0 +1,97 @@
+import logging
+from sys import stdout
+
+# Trace level definition
+TRACE_LEVEL = 5
+logging.addLevelName(TRACE_LEVEL, "TRACE")
+
+
+def trace(self, msg, *args, **kwargs) -> None:
+    if self.isEnabledFor(TRACE_LEVEL):
+        self._log(TRACE_LEVEL, msg, args, **kwargs)
+
+
+logging.Logger.trace = trace
+
+
+class ColorFormatter(logging.Formatter):
+    """
+    Applies ANSI color codes to log level names.
+    Colors are applied only when the output stream is an
+    interactive terminal.
+    """
+
+    COLORS = {
+        TRACE_LEVEL: "\033[34m",
+        logging.DEBUG: "\033[36m",
+        logging.INFO: "\033[32m",
+        logging.WARNING: "\033[33m",
+        logging.ERROR: "\033[31m",
+        logging.CRITICAL: "\033[1;31m",
+    }
+    RESET = "\033[0m"
+
+    def formatMessage(self, record) -> str:
+        # Only colorize output if writing to an interactive terminal
+        if stdout.isatty():
+            color = self.COLORS.get(record.levelno, "")
+
+            # Apply ANSI color escape codes to the level name
+            level_name = record.levelname
+            colored = f"{color}{level_name}{self.RESET}"
+
+            # Clone the LogRecord to avoid mutating the original record object
+            new_record = logging.makeLogRecord(record.__dict__.copy())
+            new_record.levelname = colored
+
+            return super().formatMessage(new_record)
+
+        # Fallback - No colors for redirected outputs
+        return super().formatMessage(record)
+
+
+def get_core_logger(
+    log_output: str | None = None, use_color: bool = True
+) -> logging.Logger:
+    """
+    Create and modify the core logger.
+
+    Args:
+        log_output (str|None): Output path for storing logs; `None` if not provided.
+        use_color (bool): Whether to enable colored console log output.
+
+    Returns:
+        Logger: The core logger.
+    """
+    console_format = "%(asctime)s [%(levelname)s] %(message)s"
+    file_format = "%(asctime)s [%(levelname)s] %(message)s"
+    date_format = "%Y-%m-%d %H:%M:%S"
+
+    core_logger = logging.getLogger("core")
+
+    # Prevent duplicated logging
+    if not core_logger.handlers:
+        console_handler = logging.StreamHandler()
+        if use_color:
+            console_handler.setFormatter(
+                ColorFormatter(fmt=console_format, datefmt=date_format)
+            )
+        else:
+            console_handler.setFormatter(
+                logging.Formatter(file_format, datefmt=date_format)
+            )
+        console_handler.setLevel(logging.NOTSET)
+
+        if log_output:
+            file_handler = logging.FileHandler(log_output)
+            file_handler.setFormatter(
+                logging.Formatter(file_format, datefmt=date_format)
+            )
+            file_handler.setLevel(logging.NOTSET)
+            core_logger.addHandler(file_handler)
+
+        core_logger.addHandler(console_handler)
+
+        core_logger.setLevel(logging.INFO)
+
+    return core_logger

woninet-2.0.1.dist-info/METADATA

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