woninet 2.0.1__py3-none-any.whl

woninet/logging.yaml

@@ -0,0 +1,49 @@
+version: 1
+disable_existing_loggers: False
+
+formatters:
+  default:
+    format: "%(asctime)s [%(levelname)s] %(message)s"
+    datefmt: "%Y-%m-%d %H:%M:%S"
+
+  colored:
+    (): woninet.utilities.logger.ColorFormatter
+    format: "%(asctime)s [%(levelname)s] %(message)s"
+    datefmt: "%Y-%m-%d %H:%M:%S"
+
+handlers:
+  file:
+    class: logging.FileHandler
+    filename: PLACEHOLDER.txt
+    formatter: default
+    level: INFO
+
+  console:
+    class: logging.StreamHandler
+    formatter: colored
+    level: INFO
+
+loggers:
+  uvicorn:
+    handlers: [file, console]
+    level: INFO
+    propagate: False
+
+  uvicorn.error:
+    handlers: [file, console]
+    level: INFO
+    propagate: False
+
+  uvicorn.access:
+    handlers: [file, console]
+    level: INFO
+    propagate: False
+
+  core:
+    handlers: [file, console]
+    level: ERROR
+    propagate: False
+
+root:
+  handlers: [console]
+  level: INFO

woninet/main.py

@@ -0,0 +1,225 @@
+import socket
+import logging
+import uvicorn
+import json
+from pathlib import Path
+from yaml import safe_load
+from argparse import Namespace
+from sqlalchemy.exc import OperationalError
+from woninet.core.engine import NetworkMonitorCore
+from woninet.utilities.arguments import args
+from woninet.utilities.logger import get_core_logger, TRACE_LEVEL
+
+# Global Variables
+LOGGING_YAML_PATH = Path(__file__).parent / "logging.yaml"
+CONFIG_JSON_PATH = Path(__file__).parent / "config.json"
+REMOTE_PROBE_IP = "8.8.8.8"
+monitor = None
+
+
+def detect_local_ip(logger: logging.Logger) -> str:
+    """
+    Determine the local IP address by opening a dummy UDP connection
+    to `8.8.8.8:80`.
+
+    Args:
+        logger (Logger): Logger used for recording logs.
+
+    Returns:
+        str: IP address of device.
+    """
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+            logger.trace(f"Sending a dummy UDP request to {REMOTE_PROBE_IP}:80")
+            s.connect((REMOTE_PROBE_IP, 80))
+            return s.getsockname()[0]
+    except OSError:
+        logger.error("Network is unreachable. Quitting.")
+        raise SystemExit(1)
+    except Exception as e:
+        logger.error(f"Local IP detection failed: {e}")
+        raise SystemExit(1)
+
+
+def load_logging_yaml(log_output: str | None) -> dict:
+    """
+    Load logging YAML configuration and adjust file handler if needed.
+
+    Args:
+        log_output (str): The file path to save logs.
+
+    Returns:
+        dict: Logging configuration for uvicorn.
+    """
+    with open(LOGGING_YAML_PATH) as file:
+        config = safe_load(file)
+
+    if log_output:
+        config["handlers"]["file"]["filename"] = log_output
+    else:
+        config["handlers"].pop("file", None)
+
+        for logger in config.get("loggers", {}).values():
+            handlers = logger.get("handlers", [])
+            if "file" in handlers:
+                handlers.remove("file")
+
+    return config
+
+
+def load_config_json() -> dict:
+    try:
+        with open(CONFIG_JSON_PATH) as file:
+            config = json.load(file)
+        return config
+    except FileNotFoundError:
+        raise
+
+
+def configure_logger(arguments: Namespace) -> logging.Logger:
+    """
+    Initialize the core logger and adjust verbosity.
+    """
+    log_output = arguments.logs
+    use_color = arguments.color != "false"
+
+    core_logger = get_core_logger(log_output, use_color)
+
+    if arguments.verbose == 1:
+        core_logger.setLevel(logging.DEBUG)
+    elif arguments.verbose >= 2:
+        core_logger.setLevel(TRACE_LEVEL)
+
+    if not arguments.cli:
+        core_logger.setLevel(logging.ERROR)
+
+    return core_logger
+
+
+def create_monitor(
+    local_ip: str,
+    target_ip: str,
+    database_path: str,
+    arp_noise_limit: float,
+    max_thread_workers: int,
+    logger: logging.Logger,
+    alert_rules: dict,
+) -> NetworkMonitorCore:
+    """
+    Create an instance of NetworkMonitoreCore.
+
+    Args:
+        local_ip (str): IP address of device.
+        target_ip (str): A single or range of user-provided IP addresses to scan.
+        database_path (str): Path to SQLite database.
+        arp_noise_limit (float): Threshold above which ARP fluctuations are treated as noise.
+        max_thread_workers (int): The concurrency limit for the
+            `ThreadPoolExecutor` handling ICMP probes
+        logger (Logger): Logger used for recording logs
+        alert_rules (dict): alert_rules loaded from config.json.
+
+    Returns:
+        NetworkMonitorCore: Instance of NetworkMonitorCore.
+    """
+    global monitor
+    if monitor is None:
+        logger.debug(f"ARP noise limit set to {arp_noise_limit}")
+        logger.trace(f"Using {database_path} as SQLite database.")
+        logger.trace(f"Max thread workers for scanning set to {max_thread_workers}.")
+        monitor = NetworkMonitorCore(
+            local_ip=local_ip,
+            target_ip=target_ip,
+            arp_noise_limit=arp_noise_limit,
+            database_path=database_path,
+            max_thread_workers=max_thread_workers,
+            alert_rules=alert_rules,
+        )
+    return monitor
+
+
+def get_monitor() -> NetworkMonitorCore:
+    """
+    Returns the instance of NetworkMonitorCore for easier access in both CLI mode
+    and web dashboard.
+    """
+    global monitor
+    return monitor
+
+
+def run_server(ip: str, port: int, log_yaml: dict) -> None:
+    """
+    Initialize and run the uvicorn ASGI server.
+
+    Args:
+        ip (str): Host used for running the server.
+        port (int): Port number to serve the host.
+        log_yaml (dict): Logging configuration for uvicorn.
+    """
+    from woninet.server.app import app
+
+    config = uvicorn.Config(app, host=ip, port=port, log_config=log_yaml)
+    server = uvicorn.Server(config)
+    app.state.uvicorn_server = server
+    server.run()
+
+
+def main() -> None:
+    """
+    Entry point for woninet. Launch either the web dashboard or the CLI
+    monitor based on command-line arguments.
+    """
+    global monitor
+
+    arguments = args()
+
+    if arguments.version:
+        from woninet.__init__ import __version__
+
+        print(__version__)
+        return
+
+    configuration = load_config_json()
+
+    target_ip = configuration["target_ip_list"]
+    port = arguments.port
+
+    core_logger = configure_logger(arguments=arguments)
+    log_yaml = load_logging_yaml(log_output=arguments.logs)
+
+    local_ip = detect_local_ip(logger=core_logger)
+
+    try:
+        if hasattr(arguments, "func"):
+            core_logger.setLevel(logging.ERROR)
+
+        monitor = create_monitor(
+            local_ip=local_ip,
+            target_ip=target_ip,
+            database_path=configuration["database"],
+            arp_noise_limit=configuration["monitoring"]["arp_noise_limit"],
+            max_thread_workers=configuration["monitoring"]["max_workers"],
+            logger=core_logger,
+            alert_rules=configuration["alert_rules"],
+        )
+
+        if hasattr(arguments, "func"):
+            arguments.monitor = monitor
+            arguments.func(arguments)
+            return
+
+        if arguments.cli:
+            monitor.start()
+            monitor.wait()
+        else:
+            run_server(ip=local_ip, port=port, log_yaml=log_yaml)
+    except KeyboardInterrupt:
+        core_logger.info("Keyboard interrupted. Wait for shut down...")
+    except ValueError as e:
+        core_logger.error(f"{e} Quitting.")
+    except FileNotFoundError:
+        core_logger.error("Can not find the config.json file. Quitting.")
+    except OperationalError as e:
+        core_logger.error(e)
+    finally:
+        if hasattr(monitor, "stop"):
+            monitor.stop()

woninet/server/__init__.py

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

woninet/server/app.py

@@ -0,0 +1,101 @@
+import asyncio
+from pathlib import Path
+from fastapi import FastAPI, Request, HTTPException, status
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+from fastapi.openapi.docs import get_swagger_ui_html
+from contextlib import asynccontextmanager
+from woninet.server.routes.api.devices import router as devices_api
+from woninet.server.routes.api.stats import router as stats_api
+from woninet.server.routes.page.devices import router as devices_page
+from woninet.server.dependencies import get_static_path
+from woninet.main import get_monitor
+from woninet.__init__ import __version__
+
+# Global variables
+TEMPLATES_DIR, STATIC_DIR = get_static_path()
+CHARTS_DIR = Path(__file__).parent.parent / "charts"
+
+monitor = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global monitor
+
+    # Startup
+    monitor = get_monitor()
+    monitor.start()
+
+    # Assign the instance of Server
+    server = app.state.uvicorn_server
+
+    async def watch():
+        """
+        Periodic monitor watchdog. Triggers server shutdown when the monitor
+        is no longer alive.
+        """
+        while True:
+            await asyncio.sleep(1)
+            if not monitor.is_alive():
+                server.should_exit = True
+                return
+
+    task = asyncio.create_task(watch())
+
+    try:
+        yield
+    finally:
+        # Shutdown
+        task.cancel()
+        monitor.stop()
+
+
+app = FastAPI(
+    title="woninet",
+    description="Network Monitoring Dashboard",
+    lifespan=lifespan,
+    version=__version__,
+    docs_url=None,
+    redoc_url=None,
+)
+
+# Templates
+templates = Jinja2Templates(directory=TEMPLATES_DIR)
+
+# Static files
+app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+app.mount("/charts", StaticFiles(directory=CHARTS_DIR), name="charts")
+
+# Routes
+app.include_router(devices_api)
+app.include_router(stats_api)
+app.include_router(devices_page)
+
+
+# The root path
+@app.get("/", response_class=HTMLResponse)
+def root(request: Request):
+    return templates.TemplateResponse(request=request, name="dashboard.html")
+
+
+@app.get("/docs", include_in_schema=False)
+def custom_swagger_ui():
+    return get_swagger_ui_html(
+        openapi_url=app.openapi_url,
+        title="woninet - Swagger UI",
+        swagger_js_url="/static/swagger-ui/swagger-ui-bundle.js",
+        swagger_css_url="/static/swagger-ui/swagger-ui.css",
+        swagger_favicon_url="/static/swagger-ui/favicon-32x32.png",
+    )
+
+
+@app.exception_handler(404)
+def custom_not_found_exception(request: Request, exc: HTTPException):
+    return templates.TemplateResponse(
+        request=request,
+        name="404.html",
+        context={"request": request},
+        status_code=status.HTTP_404_NOT_FOUND,
+    )

woninet/server/dependencies.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+
+def get_static_path() -> tuple[Path, Path]:
+    """
+    Return the paths to the templates and static directories.
+
+    Returns:
+        tuple[Path, Path]: A tuple containing (TEMPLATES_DIR, STATIC_DIR)
+    """
+    STATIC_DIR = Path(__file__).parent / "static"
+    TEMPLATES_DIR = Path(__file__).parent / "templates"
+
+    return TEMPLATES_DIR, STATIC_DIR
+
+
+def get_monitor_gracefully():
+    """
+    Call get_monitor() and return the intance of NetworkMonitorCore class
+    to prevent circular import error.
+    """
+    from woninet.main import get_monitor
+
+    monitor = get_monitor()
+    return monitor

woninet/server/routes/__init__.py

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

woninet/server/routes/api/devices.py

@@ -0,0 +1,43 @@
+from fastapi import APIRouter, Request, Path, status
+from fastapi.responses import JSONResponse
+from fastapi.encoders import jsonable_encoder
+from woninet.server.dependencies import get_monitor_gracefully
+
+router = APIRouter(prefix="/api/devices", tags=["devices"])
+
+
+@router.get("")
+def list_devices(request: Request):
+    monitor = get_monitor_gracefully()
+    return JSONResponse(
+        content={"devices": jsonable_encoder(monitor.get_device_history())},
+        status_code=status.HTTP_200_OK,
+    )
+
+
+@router.get("/{ip}")
+def device_info_api(
+    request: Request,
+    ip: str = Path(
+        ...,
+        title="IP address",
+        description="IP address of the device.",
+        min_length=7,
+        max_length=15,
+    ),
+):
+    monitor = get_monitor_gracefully()
+    device, device_alert_state, device_recent_alert_events = monitor.get_device_info(
+        ip=ip
+    )
+    monitor.graph_engine.design_device_latency_events(
+        ip=ip, recent_device_alert_events=device_recent_alert_events
+    )
+    return JSONResponse(
+        content={
+            "device": jsonable_encoder(device),
+            "device_alert_state": jsonable_encoder(device_alert_state),
+            "device_recent_alert_events": jsonable_encoder(device_recent_alert_events),
+        },
+        status_code=status.HTTP_200_OK,
+    )

woninet/server/routes/api/stats.py

@@ -0,0 +1,34 @@
+from fastapi import APIRouter, status
+from fastapi.responses import JSONResponse
+from woninet.server.dependencies import get_monitor_gracefully
+
+router = APIRouter(prefix="/api/stats", tags=["stats"])
+
+
+@router.get("")
+def stats():
+    from woninet.__init__ import __version__
+
+    monitor = get_monitor_gracefully()
+    devices_total, metrics_total = monitor.count_resources()
+
+    return JSONResponse(
+        content={
+            "identity": {
+                "service": "woninet",
+                "version": __version__,
+                "server_ip": monitor.local_ip,
+            },
+            "health": {
+                "engine_alive": monitor.is_alive(),
+                "database": monitor.database_health(),
+            },
+            "stats": {
+                "devices_total": devices_total,
+                "metrics_total": metrics_total,
+                "uptime_seconds": monitor.uptime(),
+            },
+            "recent_alert_events": monitor.classify_recent_alert_events(),
+        },
+        status_code=status.HTTP_200_OK,
+    )

woninet/server/routes/page/devices.py

@@ -0,0 +1,28 @@
+from fastapi import APIRouter, Request, Path, HTTPException, status
+from fastapi.responses import HTMLResponse
+from fastapi.templating import Jinja2Templates
+from woninet.server.dependencies import get_static_path, get_monitor_gracefully
+
+TEMPLATES_DIR, STATIC_DIR = get_static_path()
+templates = Jinja2Templates(directory=TEMPLATES_DIR)
+
+router = APIRouter(prefix="/devices", tags=["devices"])
+
+
+@router.get("/{ip}", response_class=HTMLResponse)
+def device_info(
+    request: Request,
+    ip: str = Path(
+        ...,
+        title="IP address",
+        description="IP address of the device.",
+        min_length=7,
+        max_length=15,
+    ),
+):
+    monitor = get_monitor_gracefully()
+
+    if not monitor.device_exists(ip=ip):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Not Found")
+
+    return templates.TemplateResponse(request=request, name="device_info.html")

woninet/server/static/css/404.css

@@ -0,0 +1,164 @@
+:root{
+    --bg:#08111f;
+    --panel:#101b31;
+    --panel-light:#172541;
+
+    --text:#edf3ff;
+    --muted:#8ea1c3;
+
+    --accent:#4f8cff;
+
+    --good:#22c55e;
+    --warn:#f59e0b;
+    --bad:#ef4444;
+
+    --border:rgba(255,255,255,.08);
+
+}
+
+*{
+    margin:0;
+    padding:0;
+    box-sizing:border-box;
+}
+
+body{
+    font-family:Inter,sans-serif;
+    color:var(--text);
+    min-height:100vh;
+    display:flex;
+    justify-content:center;
+    align-items:center;
+    background:
+        radial-gradient(circle at top left,
+            rgba(79,140,255,.15),
+            transparent 25%),
+
+        radial-gradient(circle at bottom right,
+            rgba(34,197,94,.08),
+            transparent 30%),
+
+        linear-gradient(180deg,#08111f,#050b15);
+}
+
+.card{
+    width:min(700px,90vw);
+    background:var(--panel);
+    border:1px solid var(--border);
+    border-radius:24px;
+    padding:50px;
+    text-align:center;
+    box-shadow:
+        0 20px 60px rgba(0,0,0,.35);
+}
+
+.network-icon{
+    width:120px;
+    height:120px;
+    margin:auto;
+    border-radius:50%;
+    background:rgba(79,140,255,.12);
+    display:flex;
+    align-items:center;
+    justify-content:center;
+    font-size:52px;
+    color:var(--accent);
+    margin-bottom:30px;
+}
+
+h1{
+    font-size:100px;
+    line-height:1;
+    margin-bottom:10px;
+}
+
+h2{
+    font-size:32px;
+    margin-bottom:15px;
+}
+
+p{
+    color:var(--muted);
+    line-height:1.7;
+    max-width:520px;
+    margin:auto;
+}
+
+.divider{
+    width:100%;
+    height:1px;
+    background:var(--border);
+    margin:40px 0;
+}
+
+.actions{
+    display:flex;
+    justify-content:center;
+    gap:15px;
+    flex-wrap:wrap;
+}
+
+.btn{
+    display:inline-flex;
+    align-items:center;
+    gap:10px;
+    text-decoration:none;
+    padding:14px 22px;
+    border-radius:12px;
+    transition:.25s;
+    font-weight:600;
+}
+
+.btn-primary{
+    background:var(--accent);
+    color:white;
+}
+
+.btn-primary:hover{
+    transform:translateY(-2px);
+    box-shadow:0 8px 20px rgba(79,140,255,.35);
+}
+
+.btn-secondary{
+    background:var(--panel-light);
+    color:var(--text);
+    border:1px solid var(--border);
+}
+
+.btn-secondary:hover{
+    background:#213250;
+}
+
+.footer{
+    margin-top:35px;
+    color:var(--muted);
+    font-size:.85rem;
+}
+
+.status{
+    display:inline-flex;
+    align-items:center;
+    gap:8px;
+    color:var(--warn);
+    margin-top:20px;
+    font-size:.9rem;
+}
+
+.status-dot{
+    width:10px;
+    height:10px;
+    border-radius:50%;
+    background:var(--warn);
+    animation:pulse 1.8s infinite;
+}
+
+@keyframes pulse{
+    0%{
+        transform:scale(1);
+        opacity:1;
+    }
+    100%{
+        transform:scale(2);
+        opacity:0;
+    }
+}