website/docs/PRODUCT.md

# netOrk — Product Description

## One-liner

**netOrk is a self-hosted network orchestration platform that discovers,
monitors, and manages heterogeneous network infrastructure from a single UI.**

## Elevator Pitch (3 sentences)

netOrk connects to your routers, switches, access points, firewalls, and servers
via NAPALM and custom vendor drivers — regardless of manufacturer. It continuously
polls device state, detects configuration drift, and lets you push corrections in
one click. All findings are synced to NetBox as the source of truth, and security
integrations with Wazuh and Graylog give you visibility across the full stack.

---

## Target Audience

**Primary:** Network engineers and IT administrators managing small to medium
heterogeneous environments (10–500 devices) — mixed vendor, mixed OS.

**Secondary:** Serious homelab operators who run "prosumer" or enterprise-grade
hardware and want operational visibility beyond what consumer dashboards offer.

**Pain points this solves:**
- Multiple vendor-specific management UIs open at once
- No single view of "what's running where"
- Config changes made directly on devices — nobody knows what changed
- Manual SSH into every device to check interface status or VLAN membership
- Security tooling (Wazuh agents, syslog) not consistently deployed

---

## Value Propositions

1. **One UI for everything** — OpenWRT APs, OPNsense firewalls, HP ProCurve
   switches, Proxmox hosts, Linux servers, Fritz!Boxes, NAS devices, and more,
   all managed in one place.

2. **Intent-based configuration** — Define desired state in netOrk (VLAN names,
   SSID settings, AP radio profiles). netOrk pushes the config to devices and
   corrects drift automatically or on demand.

3. **Automatic drift detection** — Every poll compares device config against the
   DB. Drifted devices get a warning; a one-click fix stream applies the
   correction via SSH/UCI/REST and shows live output.

4. **Scheduled automation** — Automatic reboots for OpenWRT APs (GTK key rotation
   workaround), scheduled config fixes, package updates — all with time windows
   and per-site concurrency limits.

5. **Security visibility** — Wazuh agent tracking with CVE counts and alert history
   per device. Graylog syslog forwarding status and auto-fix. CrowdSec org-level
   threat summary per device.

6. **Deep NetBox integration** — Devices, interfaces, IP addresses, prefixes,
   VLANs synced to NetBox automatically. netOrk uses NetBox as the canonical
   documentation target.

7. **Plugin system** — Integrations (Wazuh, Graylog, CrowdSec, apt-cacher-ng)
   are plugins that can be enabled/disabled per deployment. Adding a new
   integration follows a documented pattern.

8. **Self-hosted, no SaaS** — Runs in Docker Compose. Your data stays on your
   infrastructure. No telemetry, no cloud dependency.

9. **NIS2 evidence foundation** — NIS2 Art. 21 mandates asset inventory, patch
   management, access control, and audit trails. netOrk produces all of these as
   day-to-day operational outputs: full device inventory, per-device update status,
   Wazuh CVE tracking, RBAC, config drift detection, and a complete audit log.

---

## Feature List

### Device Management
- CRUD for devices with credential profiles and SSH key management
- Per-device poll intervals (minutes) or manual-only
- Status tracking: planned / staged / active / decommissioning / offline / disabled
- Vendor/model/OS auto-populated from NAPALM `get_facts()`
- Site assignment with FK to structured Site records
- AP Profile assignment for grouped OpenWRT config

### Discovery
- ICMP ping sweep, SNMP scan, HTTP/HTTPS probing
- Device fingerprinting: vendor + platform confidence scoring
- FQDN resolution (reverse DNS)
- Manual adoption from scan results (no auto-create to avoid inventory noise)

### Supported Device Drivers
Custom NAPALM drivers for all of the following:

| Driver | Device type |
|---|---|
| `openwrt` | OpenWRT access points |
| `opnsense` | OPNsense firewalls |
| `proxmox` | Proxmox VE hypervisors |
| `linux` | Generic Linux servers |
| `procurve` | HP ProCurve / Aruba switches |
| `tplink_jetstream` | TP-Link Jetstream managed switches |
| `netgear` | Netgear switches |
| `fritzbox` | AVM Fritz!Box routers |
| `zyxel` | Zyxel switches |
| `openmediavault` | OpenMediaVault NAS |
| `sonos` | Sonos speakers |

Plus all built-in NAPALM drivers: Cisco IOS/IOS-XE/NX-OS, Arista EOS, Juniper JunOS.

### Networking & Inventory
- Interface browser with IPv4/IPv6 addresses, MAC, speed, MTU
- LLDP neighbor discovery and topology graph
- ARP table and DHCP lease browser per device
- Subnet browser with interface-to-subnet assignments
- VLAN list grouped by site; per-VLAN device membership view
- SSID management with push to OpenWRT APs via UCI

### Configuration Management
- Config drift detection: desired state (DB) vs device state (poll snapshot)
- One-click drift fix stream with live SSH output in the browser
- UCI-based config push for OpenWRT (VLAN names, SSID settings, radio config)
- AP profile system: country code, HT/VHT mode, 802.11r, NTP, syslog, SSH port

### Scheduled Operations
- Scheduled reboots for OpenWRT APs with per-site concurrency lock
- Failback cron script written to device for netOrk-unreachable scenarios
- Scheduled config drift fixes with time-window enforcement
- Package update scheduling and one-click apply

### Monitoring & Health
- SNMP health metrics (CPU, memory, interface counters) via `get_health_metrics()`
- Per-device warning system with severity levels (error / warning / info)
- Docker container and image status (Proxmox/Linux)
- Service status and start/stop/restart (systemd)
- VM/container list with OS device cross-linking (Proxmox)

### Security Integrations (plugins)
- **Wazuh** — agent enrollment tracking, vulnerability counts (by severity),
  recent alert history, CIS benchmark scores, one-click agent install fix stream
- **Graylog** — rsyslog forwarding status per device, one-click fix to write rule
- **CrowdSec** — org-level decisions, remediation metrics, top attack scenarios

### DNS
- DNS zone management with authoritative device assignment
- Forward record provisioning (A records from device interfaces)
- PTR record provisioning to reverse zones
- Pending job queue for zone changes when device is unreachable

### Access Control
- JWT authentication with remember-me (localStorage) or session-only (sessionStorage)
- RBAC with four built-in roles: viewer / operator / engineer / administrator
- Custom roles with any permission combination
- Full audit log of all orchestration actions

### NetBox Sync
- Pushes vendor, model, OS version, status to NetBox dcim.devices
- Syncs interfaces, IP addresses, prefixes, VLANs
- VM interfaces and disks for Proxmox hosts

### Developer / Operator Experience
- OpenAPI / Swagger at `/docs`
- Plugin system: new integrations follow a documented pattern
- Celery task queue with dedicated queues per workload type
- Docker Compose deployment (single command)
- Alembic migrations run automatically on deploy

---

## Architecture in One Paragraph

netOrk runs as five Docker containers: a FastAPI API server, two Celery worker
pools (general + poll), a Celery Beat scheduler, and an nginx UI server. Redis
is the broker. PostgreSQL stores all state. Device communication is always
blocking I/O executed in Celery workers — FastAPI request handlers are
async-only for DB and quick operations. Custom NAPALM drivers live in `vendor/`
as editable packages and self-register via `@register_driver`. The plugin system
(`netork/plugins/`) provides a hook bus, a plugin registry with enable/disable
state in the DB, and a documented pattern for adding integrations.