woninet 2.0.1__py3-none-any.whl

woninet/__init__.py

@@ -0,0 +1,2 @@
+# woninet/core/__init__.py
+__version__ = "2.0.1"

woninet/__main__.py

@@ -0,0 +1,4 @@
+from .main import main
+
+if __name__ == "__main__":
+    main()

woninet/core/__init__.py

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

woninet/core/alerts.py

@@ -0,0 +1,251 @@
+import logging
+from datetime import datetime
+from woninet.core.storage import StorageEngine
+from woninet.core.models import MetricRecord
+from woninet.database.tables import AlertEventTable
+
+core_logger = logging.getLogger("core")
+
+
+class AlertRule:
+    """
+    Define a monitoring rule that triggers an alert
+    when a metric exceeds a defined threshold.
+
+    Attributes:
+        metric (str): Metric name to be evaluated.
+        threshold (float): The Limit the metric must exceed to trigger the alert
+        consecutive_checks (int): Number of consecutive evaluations required before
+            a state change.
+    """
+
+    def __init__(self, metric: str, threshold: float, consecutive_checks: int) -> None:
+        """
+        Initialize the alert rule.
+
+        Args:
+            metric: Name of the metric the rule evaluates.
+            threshold: The Limit the metric must exceed to trigger the alert.
+            consecutive_checks: Number of consecutive evaluations required before
+                a state change.
+        """
+        self.metric: str = metric
+        self.threshold: float = threshold
+        self.consecutive_checks: int = consecutive_checks
+
+
+class AlertEngine:
+    """
+    Evaluate stored metrics against alert rules
+    and generates alerts when conditions are violated.
+
+    Attributes:
+        storage (StorageEngine): Backend interface for alert state persistence.
+        rules (list[AlertRule]): Configuration describing metric threshold and evaluation logic.
+    """
+
+    def __init__(self, storage: StorageEngine, rules: list[AlertRule]) -> None:
+        """
+        Initialize the alert engine.
+
+        Args:
+            storage (StorageEngine): Storage backend used to manage database sessions.
+            rules (list[AlertRule]): Alert rules evaluated against stored metrics.
+        """
+        self.storage: StorageEngine = storage
+        self.rules: list[AlertRule] = rules
+
+    def is_metric_violated(self, metric: str, value: float) -> bool:
+        """
+        Return True if the given metric exceeds the configured threshold.
+        """
+        for rule in self.rules:
+            if metric == rule.metric:
+                return value > rule.threshold
+        # Fallback - No metric matched the configured rule.
+        return False
+
+    def evaluate(
+        self,
+        ip: str,
+        metrics_list: list[MetricRecord],
+        default_consecutive_checks: dict[str, int],
+    ) -> None:
+        """
+        The central dispatcher.
+
+        Search the metrics list for known metric's names (`latency`, and `packet_loss`)
+        and pass the found metric to the correct evaluation method.
+
+        Args:
+            ip (str): IP address to evaluate.
+            metrics_name (list[MetricRecord]): List of recorded metrics (e.g. `latency`, `packet_loss`).
+            default_consecutive_checks (dict[str,int]): Dictionary of consecutive evaluations
+                required to confirm a state transition for each metric.
+        """
+        for metric in metrics_list:
+            if metric is not None:
+                if metric.metric == "latency":
+                    self._evaluate_latency(
+                        ip=ip,
+                        metric="latency",
+                        value=metric.value,
+                        default_consecutive_checks=default_consecutive_checks[
+                            "latency"
+                        ],
+                    )
+                elif metric.metric == "packet_loss":
+                    self._evaluate_packet_loss(
+                        ip=ip,
+                        metric="packet_loss",
+                        value=metric.value,
+                        default_consecutive_checks=default_consecutive_checks[
+                            "packet_loss"
+                        ],
+                    )
+
+    def _evaluate_latency(
+        self, ip: str, metric: str, value: float, default_consecutive_checks: int
+    ):
+        """
+        Evaluate a latency metric against the related alert rule.
+
+        If the metric crosses its threshold for a consecutive number of checks,
+        trigger or resolve an alert accordingly. Persists state transitions
+        and logs any alert changes.
+
+        Args:
+            ip (str): IP address to evaluate.
+            metric (str): Metric name (e.g. `latency`).
+            value (float): Value of the current metric.
+            default_consecutive_checks (int): Number of consecutive evaluations
+                required to confirm a state transition.
+
+        Side Effects:
+            - Persists alert state in the database via `StorageEngine`.
+            - Emits log events.
+            - Creates `AlertEventTable` records on trigger and recover.
+        """
+        state = self.storage.get_or_create_alert_state(
+            ip=ip, metric=metric, consecutive_checks=default_consecutive_checks
+        )
+        violated = self.is_metric_violated(metric=metric, value=value)
+        if violated:
+            if state.state == "ok":
+                # Confirm remaining consecutive checks before a state transition
+                if state.consecutive_checks > 0:
+                    state.consecutive_checks = state.consecutive_checks - 1
+                    self.storage.update_alert_state(state)
+                    return
+                # Update "ok" to "warning"
+                state.state = "warning"
+                state.triggered_at = datetime.now()
+                state.consecutive_checks = default_consecutive_checks
+                self.storage.update_alert_state(state)
+
+                event = AlertEventTable(
+                    device_ip=ip, metric=metric, value=value, event_type="trigger"
+                )
+                self.storage.store_alert_event(event=event)
+                core_logger.warning(
+                    f"ALERT TRIGGERED | {ip}, metric={metric}, value={value} ms"
+                )
+            else:
+                # Reset consecutive checks to its default value
+                state.consecutive_checks = default_consecutive_checks
+                self.storage.update_alert_state(state)
+        else:
+            if state.state == "warning":
+                # Confirm remaining consecutive checks before a state transition
+                if state.consecutive_checks > 0:
+                    state.consecutive_checks = state.consecutive_checks - 1
+                    self.storage.update_alert_state(state)
+                    return
+                # Update "warning" to "ok"
+                state.state = "ok"
+                state.triggered_at = datetime.now()
+                state.consecutive_checks = default_consecutive_checks
+                self.storage.update_alert_state(state)
+
+                event = AlertEventTable(
+                    device_ip=ip, metric=metric, value=value, event_type="recover"
+                )
+                self.storage.store_alert_event(event=event)
+                core_logger.warning(
+                    f"ALERT RECOVERED | {ip}, metric={metric}, value={value} ms"
+                )
+            else:
+                # Reset consecutive checks to its default value
+                state.consecutive_checks = default_consecutive_checks
+                self.storage.update_alert_state(state)
+
+    def _evaluate_packet_loss(
+        self, ip: str, metric: str, value: float, default_consecutive_checks: int
+    ):
+        """
+        Evaluate a packet loss metric against the related alert rule.
+
+        If the metric crosses its threshold for a consecutive number of checks,
+        trigger or resolve an alert accordingly. Persists state transitions
+        and logs any alert changes.
+
+        Args:
+            ip (str): IP address to evaluate.
+            metric (str): Metric name (e.g. `packet_loss`).
+            value (float): Value of the current metric.
+            default_consecutive_checks (int): Number of consecutive evaluations
+                required to confirm a state transition.
+
+        **Side Effects**:
+            - Persists alert state in the database via `StorageEngine`.
+            - Emits log events.
+            - Creates `AlertEventTable` records on trigger and recover.
+        """
+        state = self.storage.get_or_create_alert_state(
+            ip=ip, metric=metric, consecutive_checks=default_consecutive_checks
+        )
+        violated = self.is_metric_violated(metric=metric, value=value)
+        if violated:
+            if state.state == "ok":
+                # Confirm remaining consecutive checks before a state transition
+                if state.consecutive_checks > 0:
+                    state.consecutive_checks = state.consecutive_checks - 1
+                    self.storage.update_alert_state(state)
+                    return
+                # Update "ok" to "warning"
+                state.state = "warning"
+                state.triggered_at = datetime.now()
+                self.storage.update_alert_state(state)
+                event = AlertEventTable(
+                    device_ip=ip, metric=metric, value=value, event_type="trigger"
+                )
+                self.storage.store_alert_event(event=event)
+                core_logger.warning(
+                    f"ALERT TRIGGERED | {ip}, metric={metric}, value={value} %"
+                )
+            else:
+                # Reset consecutive checks to its default value
+                state.consecutive_checks = default_consecutive_checks
+                self.storage.update_alert_state(state)
+        else:
+            if state.state == "warning":
+                # Confirm remaining consecutive checks before a state transition
+                if state.consecutive_checks > 0:
+                    state.consecutive_checks = state.consecutive_checks - 1
+                    self.storage.update_alert_state(state)
+                    return
+                # Update "warning" to "ok"
+                state.state = "ok"
+                state.triggered_at = datetime.now()
+                self.storage.update_alert_state(state)
+                event = AlertEventTable(
+                    device_ip=ip, metric=metric, value=value, event_type="recover"
+                )
+                self.storage.store_alert_event(event=event)
+                core_logger.warning(
+                    f"ALERT RECOVERED | {ip}, metric={metric}, value={value} %"
+                )
+            else:
+                # Reset consecutive checks to its default value
+                state.consecutive_checks = default_consecutive_checks
+                self.storage.update_alert_state(state)

woninet/core/collectors.py

@@ -0,0 +1,303 @@
+import re
+import logging
+import platform
+import subprocess
+from typing import Generator, Any
+from icmplib import ping, SocketPermissionError, SocketAddressError
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from woninet.core.models import Device, MetricRecord, HostStatus, ScanResult
+
+core_logger = logging.getLogger("core")
+
+
+def read_arp_table() -> dict[str, str]:
+    """
+    Return all valid MAC addresses from the ARP table.
+
+    Returns:
+        dict[str,str]: Dictionary contaning IP addressses and the related MAC addresses.
+    """
+    table = {}
+    try:
+        os_name = platform.system()
+        command = ["arp", "-an"] if os_name != "Windows" else ["arp", "-a"]
+        # Suppress strerr to avoid clutter when ARP table is empty or limited
+        output = subprocess.check_output(command, stderr=subprocess.DEVNULL, text=True)
+    except Exception:
+        return table
+
+    regex = r"\((.*?)\)\s+at\s+([0-9a-fA-F:]+)"
+    if os_name == "Windows":
+        regex = r"([0-9.]+)\s+([0-9a-fA-F-]+)"
+    for line in output.splitlines():
+        match = re.search(regex, line)
+        if match:
+            table[match.group(1)] = match.group(2)
+    return table
+
+
+def get_arp_mac(ip: str) -> str | None:
+    """
+    Return MAC address from ARP table for the given IP, or None if not present.
+    """
+    try:
+        os_name = platform.system()
+        command = ["arp", "-an"] if os_name != "Windows" else ["arp", "-a"]
+        # Suppress strerr to avoid clutter when ARP table is empty or limited
+        output = subprocess.check_output(command, stderr=subprocess.DEVNULL, text=True)
+    except Exception as e:
+        core_logger.error(f"Failed to read ARP table: {e}")
+        return None
+
+    regex = r"\((.*?)\)\s+at\s+([0-9a-fA-F:]+)"
+    if os_name == "Windows":
+        regex = rf"({re.escape(ip)})\s+([0-9a-fA-F-]+)"
+    match = re.search(regex, output)
+    if match:
+        return match.group(2)
+    return None
+
+
+def detect_host(
+    target_ip: str,
+    source_ip: str,
+    timeout: float = 1.0,
+    stop_event=None,
+    arp_noise_limit: float = 300.0,
+    arp_table: dict[str, str] = None,
+) -> HostStatus | None:
+    """
+    Combined ARP + ICMP detection for accurate device status.
+
+    Detection_Rules:
+        - ARP_FAIL and ICMP_FAIL → Host doesn't exist
+        - ARP_OK and ICMP_FAIL → Host exists but is unreachable or blocks ICMP
+        - ARP_OK and ICMP_OK < arp_noise_limit → Host is reachable
+        - ARP_OK and ICMP_OK >= arp_noise_limit → Treat as ARP-timeout noise (unreachable)
+
+    Args:
+        target_ip: IP address of the host to scan.
+        source_ip: Source IP address used to send packets.
+        timeout: Timeout for ICMP scan.
+        stop_event: Event used to control the monitoring life cycle.
+        arp_noise_limit: Threshold above which ARP fluctuations are treated as noise.
+        arp_table: Dictionary of ARP table contaning IP addressses and the related
+            MAC addresses.
+
+    Returns:
+        HostStatus|None: A `HostStatus` instance if the stop event is not triggered; otherwise, None.
+    """
+    status = HostStatus(ip=target_ip)
+
+    # Skip source ip to prevent confusion.
+    if target_ip == source_ip:
+        status.exists = False
+        status.reachable = False
+        status.mac = None
+        status.latency = 0.0
+        status.packet_loss = 100.0
+        return status
+
+    if stop_event and stop_event.is_set():
+        return None
+
+    # ARP check
+    mac = arp_table.get(target_ip)
+    if mac:
+        status.exists = True
+        status.mac = mac
+
+    # ICMP check
+    try:
+        response = ping(
+            source=source_ip,
+            address=target_ip.strip(),
+            timeout=timeout,
+            count=2,
+            privileged=True,
+            interval=1,
+        )
+        if stop_event and stop_event.is_set():
+            return None
+    except (PermissionError, SocketPermissionError):
+        raise
+    except SocketAddressError:
+        raise
+    except Exception as e:
+        core_logger.error(
+            f"Error during ICMP ping at detect_host function, to {target_ip}: {e}"
+        )
+        response = 0
+
+    status.latency = response.avg_rtt
+    status.packet_loss = response.packet_loss * 100
+    latency: float = status.latency
+    if latency == 0:
+        # Latency 0 means device is offline.
+        # Packet loss shoulnd't be determined for offline devices.
+        status.packet_loss = 0.0
+
+    # Classification logic
+    if not mac and latency == 0:
+        # Host is not in ARP table and doesn't respond to ICMP
+        status.exists = False
+        status.reachable = False
+        return status
+
+    if mac and latency == 0:
+        # Device exists but doesn't respond to ICMP
+        status.exists = True
+        status.reachable = False
+        return status
+
+    if latency != 0:
+        if arp_noise_limit == 0 or latency < arp_noise_limit:
+            # Acceptable latency (reachable)
+            status.exists = bool(mac)
+            status.reachable = True
+        else:
+            # High-latency ICMP, often ARP resolution noise (unreachable)
+            status.exists = bool(mac)
+            status.reachable = False
+            status.latency = 0
+
+    # Refresh MAC if host responded to ICMP but ARP cache was stale
+    if status.reachable and mac is None:
+        new_mac = get_arp_mac(ip=target_ip)
+        if new_mac:
+            status.exists = True
+            status.mac = new_mac
+
+    return status
+
+
+class BaseCollector:
+    """
+    Abstract base class for all monitoring collectors.
+    """
+
+    def collect(self, *args, **kwargs) -> Any:
+        raise NotImplementedError
+
+
+class PingCollector(BaseCollector):
+    """
+    Collector that measures ICMP latency to devices,
+    enhanced with ARP-based existence detection.
+    """
+
+    def collect(
+        self,
+        candidate_devices: dict[str, Device],
+        local_ip: str,
+        device_records: list[Device],
+        stop_event=None,
+        arp_noise_limit: float = 300.0,
+        max_thread_workers: int = 4,
+    ) -> Generator[ScanResult, Any, None]:
+        """
+        For each device:
+            - Use ARP + ICMP to determine existence and reachability.
+            - Update Device fields.
+            - Record latency metric only when reachable and latency is sane.
+        """
+        if stop_event and stop_event.is_set():
+            yield ()
+
+        arp_table = read_arp_table()
+
+        def worker(
+            ip: str, dev: Device
+        ) -> tuple[Device, list[MetricRecord]] | tuple[None, list[MetricRecord]]:
+            try:
+                status = detect_host(
+                    target_ip=ip,
+                    source_ip=local_ip,
+                    timeout=1.0,
+                    stop_event=stop_event,
+                    arp_noise_limit=arp_noise_limit,
+                    arp_table=arp_table,
+                )
+            except (PermissionError, SocketPermissionError):
+                raise
+            except SocketAddressError:
+                raise
+
+            # Update device state from status
+            dev.exists = status.exists
+            dev.reachable = status.reachable
+            if status.mac is not None:
+                dev.mac = status.mac
+            dev.latency = status.latency
+            dev.packet_loss = status.packet_loss
+
+            if dev.reachable:
+                # Only consider reachable hosts as recently seen
+                dev.update_seen()
+
+            # Check if the found device is already stored in the database.
+            is_known = any(
+                device_record.ip == dev.ip for device_record in device_records
+            )
+
+            if dev.reachable:
+                core_logger.debug(
+                    f"Device {ip}: \tUP,\t MAC={dev.mac}, latency={dev.latency:.2f} ms"
+                )
+            elif is_known:
+                core_logger.trace(
+                    f"Device {ip}: \tDOWN,\t MAC={dev.mac}, latency=OFFLINE"
+                )
+            else:
+                core_logger.trace(
+                    f"Device {ip}: \tABSENT,\t MAC={dev.mac}, latency=OFFLINE"
+                )
+
+            recorded_metrics = [
+                MetricRecord(ip, "latency", dev.latency),
+                MetricRecord(ip, "packet_loss", dev.packet_loss),
+            ]
+
+            if dev.reachable or is_known:
+                return (dev, recorded_metrics)
+            else:
+                return (None, recorded_metrics)
+
+        with ThreadPoolExecutor(max_workers=max_thread_workers) as executor:
+            future_to_ip = {
+                executor.submit(worker, ip, dev): ip
+                for ip, dev in candidate_devices.items()
+            }
+
+            for future in as_completed(future_to_ip):
+                if stop_event and stop_event.is_set():
+                    break
+
+                try:
+                    future_device, future_metric = future.result()
+                except (PermissionError, SocketPermissionError):
+                    raise
+                except SocketAddressError:
+                    raise
+                except Exception as e:
+                    ip = future_to_ip[future]
+                    core_logger.error(f"Error in PingCollector for {ip}: {e}")
+                    continue
+                else:
+                    latency_metric, packet_loss_metric = future_metric
+
+                    latency = (
+                        latency_metric.value if latency_metric.value != 0 else None
+                    )
+                    packet_loss_metric = (
+                        packet_loss_metric.value
+                        if (future_device is not None and latency is not None)
+                        else None
+                    )
+
+                finally:
+                    yield ScanResult(
+                        device=future_device,
+                        latency=latency_metric,
+                        packet_loss=packet_loss_metric,
+                    )