Metadata-Version: 2.4
Name: woninet
Version: 2.0.2
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 from PyPI

### Unix/Linux

Create and activate a virtual environment:

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

Install woninet from PyPI:

```shell
pip install woninet
```

Grant the required capability to the Python interpreter:

```shell
sudo setcap cap_net_raw=eip venv/bin/python3
```

Then run:

```shell
woninet --help
```

#### macOS/Windows

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)
