Metadata-Version: 2.4
Name: networkwright
Version: 0.0.1
Summary: Self-hosted, offline-capable network monitoring and automation for small teams
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn>=0.30
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: psycopg[binary]>=3.2
Requires-Dist: alembic>=1.13
Requires-Dist: pydantic-settings>=2.4
Requires-Dist: pyotp>=2.9
Requires-Dist: cryptography>=43
Requires-Dist: argon2-cffi>=23.1
Requires-Dist: pyyaml>=6
Requires-Dist: pysnmp<8,>=7.1
Requires-Dist: icalendar>=6
Requires-Dist: recurring-ical-events>=3
Requires-Dist: paramiko>=3.4
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: snmpsim>=1.1; extra == "dev"
Requires-Dist: pysmi>=1.5; extra == "dev"
Requires-Dist: aiosmtpd>=1.4; extra == "dev"
Requires-Dist: playwright>=1.45; extra == "dev"
Dynamic: license-file

# NetworkWright

Self-hosted network monitoring and automation for small network teams.
Device-centric monitoring (replacing PRTG/Orion-style sensor sprawl), config backup,
IPAM, and safe, approved bulk changes with automatic rollback.

**Offline by design.** NetworkWright makes zero outbound connections. Everything it needs
ships in a signed offline bundle; GitHub is only where source and releases live.

> Status: pre-alpha. Phases 1-8 done, plus phase 9 (config compliance rules, software end-of-life tracking, network map, NetBox import, suggested fixes for alerts): foundations, inventory, monitoring collection, alerting, config backup, IPAM and VLANs, device page (web UI), safe bulk changes. Feature-complete for a first release; release-readiness work (account management, migrations, signed bundles) done; not yet tested on real devices (see docs/lab-test-plan.md). Not ready for production use.

## What exists today (phase 1)

- Local accounts with Argon2id passwords, mandatory TOTP, lockout, replay protection
- Roles: viewer / engineer / admin
- Hash-chained, tamper-evident audit log
- `CredentialProvider` interface with a local AES-256-GCM provider
- Docker Compose stack (TimescaleDB, API, worker, alerter, executor) on an internal-only network
- Offline bundle scripts and a CI test that fails on any outbound connection

- Inventory: identity by serial first, management address second; conflicting records are rejected
- Discovery holding list: nothing enters inventory until an engineer approves it
- Search by hostname, serial, site, platform, address or CIDR
- Bulk import from CSV, JSON or YAML with a dry run, per-row errors and whole-batch rollback

- SNMP v2c/v3 polling: bandwidth, errors, CPU, memory, temperature, BGP/OSPF state, LLDP/CDP topology, ICMP
- Port classes (trunk/routed = critical, access = user) with engineer overrides; adjustable poll intervals
- Worker egress limited to management networks by a host firewall rule, tested in CI

- Alerting: settle delay, LLDP/CDP dependency suppression, flap damping, maintenance windows, thresholds
- Email via your internal relay only (STARTTLS, internal CA), outbox with retries; escalation and acknowledgement
- On-call from manual shifts or an internal iCalendar feed (Exchange, CalDAV export); manual swaps win

- Config backup over SSH: daily and on demand, secrets redacted before storage, version history and diffs,
  SSH host keys pinned on first contact (a changed key stops backups and raises an alert)

## Name

The project is **NetworkWright**; **NetWrkWright** is an accepted alternate spelling. The command is `networkwright` (short form `nww`). `pip install netwrkwright` installs the same thing via a tiny pointer package (`packaging/netwrkwright`).

## Quick start (development)

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q
```

## Layout

| Path | Purpose |
|---|---|
| `networkwright/auth` | passwords, TOTP, roles, login service |
| `networkwright/credentials` | CredentialProvider + local AES-256-GCM provider |
| `networkwright/audit.py` | hash-chained audit log |
| `networkwright/collectors` | SNMP client, poller, scheduler, ICMP, worker |
| `networkwright/alerting` | alert engine, suppression, on-call, email |
| `networkwright/backup` | SSH fetch, redaction, versions |
| `networkwright/definitions` | per-platform YAML (health OIDs) |
| `networkwright/api` | FastAPI app |
| `deploy/` | Dockerfile, compose stack |
| `scripts/` | offline bundle (build, sign, verify), release key, egress test |
| `docs/` | design and security notes |

Later phases add `engine`, `notify`, `orchestrator`, `executor`, `backup`,
`ipam`, `definitions`, `jobs` and `web`.

## Licence

Not yet chosen (Apache-2.0 or AGPL-3.0 under consideration). No licence is granted until a `LICENSE` file is added.
