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 from PyPI

Unix/Linux

1. Method 1 (recommended (Uses the icmplib module)):

Create and activate a virtual environment:

python3 -m venv --copies venv
source venv/bin/activate

Install woninet from PyPI:

pip install woninet

Grant the required capability to the Python interpreter:

sudo setcap cap_net_raw=eip venv/bin/python3

Then run:

woninet --help

2. Method 2 (Uses the system's ping command as a fallback):

Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate

Install from PyPI:

pip install woninet

Then run:

woninet --help

macOS/Windows

Install from PyPI:

pip install woninet

Then run:

woninet --help

Installation from Source

1. Clone the repository

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

python3 -m venv --copies ../venv
source ../venv/bin/activate

Windows (PowerShell)

py -m venv ..\venv
..\venv\Scripts\Activate.ps1

3. Install woninet locally:

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:

sudo setcap cap_net_raw=eip ../venv/bin/python3

Finally, run woninet normally:

woninet --version

Alternative (not recommended): You can run woninet with sudo instead of using setcap, but this is discouraged for security reasons:

sudo ../venv/bin/python3 -m woninet

Configuration

You can define alert rules in a JSON file. Rename the example file at config.example.json to config.json. The application will load the alert rules from that file at startup.

Example:

{
    "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
        },
        {
            "metric": "jitter",
            "threshold": 40.0,
            "consecutive_checks": 3
        }
    ]
}

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, packet_loss or jitter)
• 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.
• Jitter: All jitter thresholds are evaluated in milliseconds.

Usage

This guide 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:

pip install -e ".[test]"

Then run:

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 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.