Metadata-Version: 2.4
Name: netwatchdog
Version: 0.1.0
Summary: See every device on your network and know what each one is — in plain English — and get told when something new shows up. Read-only, no packet capture.
Author: GreenHarvestDev
License: MIT
Project-URL: Homepage, https://github.com/GreenHarvestDev/netwatchdog
Project-URL: Repository, https://github.com/GreenHarvestDev/netwatchdog
Project-URL: Issues, https://github.com/GreenHarvestDev/netwatchdog/issues
Project-URL: Changelog, https://github.com/GreenHarvestDev/netwatchdog/blob/main/CHANGELOG.md
Keywords: network,security,lan,arp,device-discovery,iot,privacy,home-network
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Requires-Dist: psutil>=5.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Dynamic: license-file

# netwatchdog

[![CI](https://github.com/GreenHarvestDev/netwatchdog/actions/workflows/ci.yml/badge.svg)](https://github.com/GreenHarvestDev/netwatchdog/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/netwatchdog.svg)](https://pypi.org/project/netwatchdog/)
[![Python](https://img.shields.io/pypi/pyversions/netwatchdog.svg)](https://pypi.org/project/netwatchdog/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**See every device on your network, know what each one actually is — in plain English — and get told the moment something new shows up.**

`netwatchdog` scans your local network, identifies each device (router, phone, TV,
printer, that suspicious no-name smart plug…), and remembers what it saw so it can
flag new arrivals on the next run.

It is **read-only**: it pings and reads your OS's neighbor/ARP table. No packet
capture, no port scanning, no router login.

<p align="center">
  <img src="assets/demo.png" alt="netwatchdog scan output" width="640">
</p>

<p align="center"><sub>Example scan (fictional devices). Real output is color-coded by device type.</sub></p>

## What it tells you

- **Who's here** — every device on your LAN, with its IP and hostname.
- **What each one is** — vendor + a plain category (phone, media, printer, network
  gear, **IoT chip**, or **Unknown**), so the things worth a second look stand out.
- **What's new** — anything that wasn't on your network last time gets flagged, with
  advice on what to do about it.

Device identification uses a built-in table for the most-wanted categories and,
optionally, the full public Wireshark OUI list (downloaded once, no account).

## Install

```bash
pip install netwatchdog
```

## Usage

```bash
netwatchdog                 # scan, identify, save/update baseline, print a report
netwatchdog --no-ping       # skip the ping sweep (faster, reads existing table)
netwatchdog --no-manuf      # don't download the full vendor database
netwatchdog --json          # emit the full report as JSON (build your own UI)
netwatchdog -b ~/mynet.json # use a specific baseline file
```

The first run saves a **baseline** of what's on your network. Later runs compare
against it and highlight new devices. Your baseline (`netwatch_baseline.json`)
describes your own LAN and is **git-ignored** — keep it local.

**Tip:** give devices a friendly name in the baseline file so future scans read
cleanly, and investigate anything marked *IoT chip* or *Unknown* that you don't
recognize.

## Read-only by design

`netwatchdog` only sends pings and reads the neighbor table your OS already keeps.
It never captures packets, scans ports, or logs into your router. This is a hard
design boundary — see [SECURITY.md](SECURITY.md).

## Development

```bash
git clone https://github.com/GreenHarvestDev/netwatchdog.git
cd netwatchdog
pip install -e ".[dev]"
ruff check . && ruff format --check . && mypy && pytest
```

Tests are fully offline — `subprocess`, `psutil`, and `socket` are mocked, so the
suite runs in well under a second. See [CONTRIBUTING.md](CONTRIBUTING.md); new
device-identification data and ARP/route format parsers are welcome (with a test).

## License

MIT © 2026 GreenHarvestDev
