woninet 2.0.1__py3-none-any.whl

woninet/core/engine.py

@@ -0,0 +1,353 @@
+import time
+import logging
+import threading
+from datetime import datetime
+from typing import Any
+from sqlalchemy import text, inspect
+from sqlalchemy.exc import SQLAlchemyError
+from icmplib import SocketPermissionError, SocketAddressError
+from woninet.core.models import Device, MetricRecord
+from woninet.core.collectors import PingCollector
+from woninet.core.storage import StorageEngine
+from woninet.core.alerts import AlertEngine, AlertRule
+from woninet.core.subnet_enumerator import SubnetEnumerator
+from woninet.core.manual_ip_enumerator import ManualIPEnumerator
+from woninet.core.graph import GraphEngine
+from woninet.database.engine import DatabaseEngine
+from woninet.database.tables import AlertEventTable
+from woninet.utilities.ip_validator import is_device_ip_valid
+from woninet.utilities.detect_ip_range import detect_ip_range
+
+core_logger = logging.getLogger("core")
+
+
+class NetworkMonitorCore:
+    """
+    Central controller coordinating database initialization, telemetry
+    collection, persistence, and heuristic alert processing.
+
+    This class acts as the orchestrator for the network monitoring lifecycle,
+    managing thread pools for asynchronous ICMP polling and interfacing with
+    the SQLite persistence layer via SQLAlchemy.
+
+    Attributes:
+        local_ip (str): The source interface IP used for packet origination.
+        arp_noise_limit (float): Statistical threshold for filtering jitter
+            in ARP resolution timings.
+        max_thread_workers (int): The concurrency limit for the
+            `ThreadPoolExecutor` handling ICMP probes.
+        database_engine (DatabaseEngine): The high-level wrapper for
+            SQLAlchemy engine configuration.
+        storage (StorageEngine): The Data Access Object (DAO) layer for
+            CRUD operations on network metrics.
+        alert_engine (AlertEngine): Logic processor for evaluating
+            latency-based threshold breaches.
+        candidate_devices (list): A list of IP addresses identified during
+            the initial enumeration phase.
+        _stop_event (threading.Event): Primitive used to signal graceful
+            shutdown to the background worker thread.
+    """
+
+    def __init__(
+        self,
+        local_ip: str,
+        target_ip: str,
+        arp_noise_limit: float,
+        database_path: str,
+        max_thread_workers: int,
+        alert_rules: dict,
+    ) -> None:
+        """
+        Initialize the monitor core and prepare the persistence layer.
+
+        Args:
+            local_ip (str): Source IP address used to send packets.
+            target_ip (str): User-provided IP address or range to scan.
+            arp_noise_limit (float): Threshold in milliseconds above which ARP
+                fluctuations are treated as noise.
+            database_path (str): Path to SQLite database.
+            max_thread_workers (int): Maximum number of thread workers used to send ICMP pings.
+            alert_rules (dict): Provided alert rules, loaded from config.json.
+        """
+        self._running: bool = False
+        self._thread: threading.Thread | None = None
+        self._stop_event: threading.Event = threading.Event()
+        self._start_uptime = datetime.now()
+
+        self.local_ip: str = local_ip
+        self.arp_noise_limit: float = arp_noise_limit
+        self.max_thread_workers: int = max_thread_workers
+
+        # Initialize database
+        self.database_engine = DatabaseEngine(database_path=database_path)
+        self.database_engine.init_db()
+        self._engine = self.database_engine.get_database_enigne()
+        self.session_factory = self.database_engine.get_session_factory()
+
+        core_logger.info(f"Initializing network monitor for {self.local_ip}")
+
+        self.subnet_enumerator = SubnetEnumerator()
+        self.manual_ip_enumerator = ManualIPEnumerator()
+        self.storage = StorageEngine(session_factory=self.session_factory)
+
+        self.candidate_devices = self.enumerate_candidate_devices(target_ip)
+
+        self.ping_collector = PingCollector()
+
+        self.alert_engine = AlertEngine(
+            storage=self.storage,
+            rules=[
+                AlertRule(item["metric"], item["threshold"], item["consecutive_checks"])
+                for item in alert_rules
+            ],
+        )
+
+        self.consecutive_checks = {
+            item["metric"]: item["consecutive_checks"]
+            for item in alert_rules
+        }
+
+        self.graph_engine = GraphEngine()
+
+    def start(self) -> None:
+        """
+        Start the monitoring worker thread.
+        """
+        if self._running:
+            return
+
+        self._running = True
+        self._stop_event.clear()
+        self._thread = threading.Thread(
+            target=self.worker_loop, name="woninet-worker", daemon=False
+        )
+        self._thread.start()
+
+    def stop(self) -> None:
+        """
+        Stop the monitoring worker thread.
+        """
+        if not self._running:
+            return
+
+        self._running = False
+        self._stop_event.set()
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=3)
+
+    def wait(self) -> None:
+        """
+        Block until the worker thread finishes.
+        """
+        if self._thread:
+            self._thread.join()
+
+    def worker_loop(self) -> None:
+        """
+        Main monitoring loop.
+        Start the collectors and evaluate alerts.
+        """
+        try:
+            while self._running and not self._stop_event.is_set():
+                if not self._running or self._stop_event.is_set():
+                    break
+
+                for result in self.ping_collector.collect(
+                    candidate_devices=self.candidate_devices,
+                    local_ip=self.local_ip,
+                    device_records=self.get_device_history(),
+                    stop_event=self._stop_event,
+                    arp_noise_limit=self.arp_noise_limit,
+                    max_thread_workers=self.max_thread_workers,
+                ):
+                    try:
+                        self.submit_to_history(
+                            device=result.device,
+                            metrics=[result.latency, result.packet_loss],
+                        )
+                        if result.device is not None:
+                            self.alert_engine.evaluate(
+                                ip=result.device.ip,
+                                metrics_list=[result.latency, result.packet_loss],
+                                default_consecutive_checks={
+                                    "latency": self.consecutive_checks["latency"],
+                                    "packet_loss": self.consecutive_checks[
+                                        "packet_loss"
+                                    ],
+                                },
+                            )
+                    except AttributeError:
+                        # If the tuple doesn't have enough values to unpack
+                        pass
+                time.sleep(1)
+        except (PermissionError, SocketPermissionError):
+            core_logger.error("woninet requires root privileges to scan.")
+            self._running = False
+            self._stop_event.set()
+        except SocketAddressError:
+            core_logger.error("Network connection failed. Quitting.")
+            self._running = False
+            self._stop_event.set()
+        except Exception as e:
+            core_logger.error(f"Unexpected error in NetworkMonitorCore: {e}")
+            self._running = False
+            self._stop_event.set()
+        finally:
+            self._running = False
+            self._stop_event.set()
+
+    def is_alive(self) -> bool:
+        """
+        Return the running state of monitor.
+        """
+        return self._running
+
+    def get_device_history(self) -> list[Device]:
+        """
+        Return a list of all devices in the history.
+        """
+        return self.storage.list_device_history()
+
+    def get_device_info(
+        self, ip: str
+    ) -> tuple[Device | None, dict[str, str] | None, list[AlertEventTable]]:
+        """
+        Retrieve device information and related alert data for a given IP address.
+
+        Args:
+            ip (str): IP address of the device to search for.
+
+        Returns:
+            tuple[Device|None,dict[str,str]|None,list[AlertEventTable]]:
+                A tuple containing
+
+                1. The found device, or `None` if no device exists for the given IP.
+                2. The current alert state as `(metric_name, value)`, or `None` if no state exists.
+                3. The last 10 alert events for the device, or an empty list if none exist.
+        """
+        device_info = self.storage.fetch_device_info(ip=ip)
+        device_alert_state = self.storage.get_device_alert_state(ip=ip)
+        recent_device_alert_events = self.storage.get_recent_device_alert_events(ip=ip)
+        return (device_info, device_alert_state, recent_device_alert_events)
+
+    def device_exists(self, ip: str) -> bool:
+        """
+        Return boolean indicating if device exists for a given IP address.
+        """
+        exists = self.storage.fetch_device_info(ip=ip)
+        if exists:
+            return True
+        return False
+
+    def classify_recent_alert_events(self) -> list[dict[str, Any]]:
+        """
+        Re-order and organize the recent alert events
+        dictionary keys and values.
+        """
+        result = []
+        for event in self.storage.get_recent_alert_events():
+            result.append(
+                {
+                    "device_ip": event.device_ip,
+                    "id": event.id,
+                    "metric": event.metric,
+                    "event_type": event.event_type,
+                    "value": event.value,
+                    "timestamp": event.timestamp.isoformat(),
+                }
+            )
+        return result
+
+    def count_resources(self) -> tuple[int, int]:
+        """
+        Return number of devices and metrics in the history.
+        """
+        return self.storage.count_devices_and_metrics()
+
+    def submit_to_history(self, device: str, metrics: list[MetricRecord]) -> None:
+        """
+        Handle storing new devices and metrics in history.
+        """
+        if isinstance(device, Device):
+            self.storage.store_device(device=device)
+        for metric in metrics:
+            if isinstance(metric, MetricRecord):
+                self.storage.store_metric(metric=metric)
+
+    def enumerate_candidate_devices(
+        self, target_ip_list: list[str] | None
+    ) -> dict[str, Device]:
+        """
+        Control enumeration based on user-provided IP addresses. Use range enumeration
+        if IP range is detected, otherwise use the single IP address. Enumerate on the
+        /24 subnet if no target IP address is provided.
+
+        Args:
+            target_ip (list[str]|None): Target IP addresses to create candidate devices on.
+
+        Returns:
+            dict[str,Device]: Candidate devices.
+
+        Raises:
+            ValueError: If IP addresses are not valid.
+        """
+        candidate_devices = {}
+        if target_ip_list is not None:
+            for target_ip in target_ip_list:
+                if detect_ip_range(ip=target_ip):
+                    candidate_devices.update(
+                        self.manual_ip_enumerator.enumerate_range(target_ip)
+                    )
+                else:
+                    candidate_devices[target_ip] = Device(ip=target_ip)
+        else:
+            candidate_devices.update(self.subnet_enumerator.enumerate(self.local_ip))
+        if not is_device_ip_valid(candidate_devices):
+            raise ValueError("IP address is not valid")
+        return candidate_devices
+
+    def uptime(self) -> int:
+        """
+        Calculate the uptime of program from the initialization of the
+        NetworkMonitorCore class.
+
+        Returns:
+            int: Uptime in seconds.
+        """
+        uptime_seconds = datetime.now() - self._start_uptime
+        return uptime_seconds.seconds
+
+    def database_health(self) -> dict[str, str]:
+        """
+        Check the health status of the database.
+
+        Returns:
+            dict[str,str]: A dictionary with two keys
+
+            - 'connection': 'ok' if executing `SELECT 1` succeeds, otherwise 'error'.
+            - 'schema': 'ok' if database table inspection succeeds, otherwise 'error'.
+            If the database connection fails, this value is 'unknown'.
+        """
+        result = {
+            "connection": "error",
+            "schema": "unknown",
+        }
+        try:
+            # Check connection
+            with self._engine.connect() as conn:
+                conn.execute(text("SELECT 1"))
+            result["connection"] = "ok"
+
+            # Check tables existence
+            inspect_engine = inspect(self._engine)
+            tables = inspect_engine.get_table_names()
+            required = {"devices", "metrics"}
+            if required.issubset(set(tables)):
+                result["schema"] = "ok"
+            else:
+                result["schema"] = "error"
+        except SQLAlchemyError:
+            # Keep default values
+            pass
+
+        return result

woninet/core/graph.py

@@ -0,0 +1,63 @@
+from pathlib import Path
+from matplotlib import pyplot as plt
+from woninet.database.tables import AlertEventTable
+
+CHARTS_PATH = Path(__file__).parent.parent / "charts"
+
+
+class GraphEngine:
+    """
+    Engine for generating graphs and visualizations of network device metrics.
+    """
+
+    def design_device_latency_events(
+        self, ip: str, recent_device_alert_events: list[AlertEventTable]
+    ) -> None:
+        """
+        Generate and save a latency chart for a device.
+
+        Creates a line plot showing latency values over time with trigger and recovery events
+        marked as scatter points. The chart is saved as a PNG file.
+
+        Args:
+            ip: The IP address of the device for the chart title and filename.
+            recent_device_alert_events: List of alert events containing latency metrics and event types.
+        """
+        times = []
+        latency_values = []
+        trigger_times = []
+        trigger_values = []
+        recover_times = []
+        recover_values = []
+
+        for event in recent_device_alert_events:
+            if event.metric == "latency":
+                times.append(event.timestamp)
+                latency_values.append(event.value)
+                if event.event_type == "trigger":
+                    trigger_times.append(event.timestamp)
+                    trigger_values.append(event.value)
+                elif event.event_type == "recover":
+                    recover_times.append(event.timestamp)
+                    recover_values.append(event.value)
+
+        fig, ax = plt.subplots(figsize=(16, 8), dpi=150)
+
+        ax.plot(times, latency_values, label="Latency")
+        ax.axhline(100, linestyle="--", label="Alert Threshold")
+        ax.scatter(
+            trigger_times, trigger_values, marker="^", color="red", label="Trigger"
+        )
+        ax.scatter(
+            recover_times, recover_values, marker="v", color="blue", label="Recover"
+        )
+
+        ax.set_title(f"{ip} - Latency")
+        ax.set_xlabel("Time")
+        ax.set_ylabel("Latency (ms)")
+        ax.legend()
+        ax.grid(True, alpha=0.3)
+
+        fig.autofmt_xdate()
+        fig.savefig(f"{CHARTS_PATH}/{ip}.png", bbox_inches="tight")
+        plt.close(fig)

woninet/core/manual_ip_enumerator.py

@@ -0,0 +1,33 @@
+from woninet.core.models import Device
+
+
+class ManualIPEnumerator:
+    """
+    Build a dictionary of candidate devices for user-provided IP addresses.
+    """
+
+    def enumerate(self, ip_list: list[str]) -> dict[str, str]:
+        devices = {}
+        for ip in ip_list:
+            devices[ip] = Device(ip=ip)
+        return devices
+
+    def enumerate_range(self, ip_range: str) -> dict[str, Device]:
+        """
+        Build a dictionary of candidate devices for user-provided IP addresses range.
+
+        Args:
+            ip_range (str): IP address as a range (e.g. 192.168.1.10-50).
+
+        Raises:
+            ValueError: If the range notation is not in the last octet.
+        """
+        base, last_octect = ip_range.rsplit(".", maxsplit=1)
+        if "-" in base:
+            raise ValueError("Range enumeraton is only supported on the last octet.")
+        start, stop = last_octect.split("-")
+        devices = {}
+        for i in range(int(start), int(stop) + 1):
+            ip = f"{base}.{i}"
+            devices[ip] = Device(ip=ip)
+        return devices

woninet/core/models.py

@@ -0,0 +1,124 @@
+from dataclasses import dataclass
+from datetime import datetime
+
+
+class Device:
+    """
+    Represents a discovered network device and stores identity information
+    and device state.
+
+    Attributes:
+        ip (str): IP address of the host.
+        last_seen (datetime|None): Last time device responded to ICMP request; Otherwise `None`.
+        exists (bool): If device responded to the last ARP scan.
+        reachable (bool): If device responded to the last ICMP scan.
+        mac (str): MAC address if known; Otherwise `None`.
+        latency (float): The last latency of host if reachable; Otherwise zero.
+        packet_loss (float): Most recent packet-loss ratio in the range [0.0, 100.0].
+            A value of 100.0 indicates 100% packet loss or that the device is unreachable.
+    """
+
+    def __init__(self, ip: str) -> None:
+        """
+        Initialize the device model.
+
+        Args:
+            ip: IP address of the host
+        """
+        self.ip: str = ip
+        self.last_seen: datetime | None = None
+        self.exists: bool = False
+        self.reachable: bool = False
+        self.mac: str | None = None
+        self.latency: float = 0
+        self.packet_loss: float = 100
+
+    def update_seen(self) -> None:
+        """
+        Update timestamp indicating the device responded recently.
+        """
+        self.last_seen = datetime.now()
+
+
+class MetricRecord:
+    """
+    Represents a single collected metric measurement
+    for a specific device at a specific time.
+
+    Attributes:
+        device_ip (str): IP address of the host.
+        metric (str): Name of the metric.
+        value (float): Recorded value of the metric.
+        timestamp (datetime|None): Timestamp when the metric was captured.
+            If `None`, defaults to the current time.
+    """
+
+    def __init__(
+        self,
+        device_ip: str,
+        metric: str,
+        value: float,
+        timestamp: datetime | None = None,
+    ) -> None:
+        """
+        Initialize a metric record.
+
+        Args:
+            device_ip (str): IP address of the host the metric belongs to.
+            metric (str): Name of the recorded metric.
+            value (float): Recorded value of the metric.
+            timestamp (datetime|None): Timestamp of the measurement.
+                If omitted, the current time is used.
+        """
+        self.device_ip = device_ip
+        self.metric = metric
+        self.value = value
+        self.timestamp = timestamp or datetime.now()
+
+
+class HostStatus:
+    """
+    Represents a Combined ARP + ICMP status for a given IP.
+
+    Attributes:
+        ip (str): IP address of the host.
+        exists (bool): If device responded to the ARP scan
+        reachable (bool): If device responded to the ICMP scan
+        latency (float): The latency of host if reachable; Otherwise zero.
+        packet_loss (float): Most recent packet-loss ratio in the range [0.0, 100.0].
+            A value of 100.0 indicates 100% packet loss or that the device is unreachable.
+        mac (str): MAC address if known; Otherwise `None`.
+    """
+
+    def __init__(
+        self,
+        ip: str,
+        exists: bool = False,
+        reachable: bool = False,
+        latency: float = 0.0,
+        packet_loss: float = 100.0,
+        mac: str | None = None,
+    ) -> None:
+        """
+        Initialize the host status model.
+
+        Args:
+            ip (str): IP address of the host.
+            exists (bool): If device responded to the ARP scan
+            reachable (bool): If device responded to the ICMP scan
+            latency (float): The latency of host if reachable; Otherwise zero.
+            mac (str): MAC address if known; Otherwise `None`.
+        """
+        self.ip: str = ip
+        self.exists: bool = exists
+        self.reachable: bool = reachable
+        self.latency: float = latency
+        self.packet_loss: float = packet_loss
+        self.mac: str | None = mac
+
+
+@dataclass(frozen=True)
+class ScanResult:
+    device: Device | None
+    latency: float | None
+    packet_loss: float | None