docs: initial product docs and design reference
Establishes the documentation foundation for the netOrk website: - CLAUDE.md — tech stack (React 18/Vite/Tailwind), design rules, tone of voice, and file structure guidance for the implementation instance - docs/PRODUCT.md — one-liner, elevator pitch, target audience, value props, full feature list, driver table, architecture summary - docs/DESIGN.md — exact Tailwind classes for colors, typography, spacing, and all reusable component patterns (cards, buttons, screenshot frames, badges, nav) lifted directly from the product UI - docs/PAGES.md — page-by-page content plan with route, purpose, section structure, and draft copy for every page No code yet — that follows in a separate instance. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Christian Manivong
+173
@@ -0,0 +1,173 @@
|
||||
# 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.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user