NetInv — Network Asset Monitoring Platform

Centralized, vendor-neutral network monitoring: SNMP (v2c/v3) collection from Cisco, Juniper, Huawei, ZTE, Ubiquiti and Ruckus devices into a modern time-series stack, with a live topology weathermap as the flagship view. The spiritual successor to Cacti + Weathermap, rebuilt on VictoriaMetrics instead of MRTG/RRD.

Status: v1.0.0, released 2026-08-12 and running live. Milestones M1 (collection pipeline), M2 (alerting), M3 (usable product) and M4 (weathermap flagship) are achieved, and the platform monitors a real network: four UniFi gateways in an SD-WAN mesh plus a Ruckus Unleashed estate, with a live weathermap over the WireGuard tunnels between them and NetFlow arriving from the gateways.

v1.0.0 shipped with four release gates open, named rather than dropped (ADR-023). Two have since been closed and dated: the security checklist against TLS, and the backup/restore drill (doc 20 §12). Two remain open. Real-hardware validation: generic, ubiquiti and ruckus are validated against real units and documented in doc 10 with what each device actually exposes — including what it does not; cisco-ios, juniper-junos, huawei-vrp, zte-zxr, fortinet-fortios and paloalto-panos are written from vendor MIBs and have never received a packet from the platform they describe, so expect to find faults and please report them. No soak or chaos run: the Helm chart now installs and runs on a real cluster — verified on Kubernetes 1.35, doc 35 — but it has not been run for 72 hours under load with components killed underneath it, so behaviour under sustained load or failure is untested rather than proven. Sprint log: git log --oneline.

Try it in one command

Docker + Compose v2 is all you need — no Go, Node, or database to install:

git clone https://github.com/freezxp/netinv.git && cd netinv
./deploy/compose-app/quickstart.sh

It generates secrets, builds the images, starts the whole platform (seven services + UI + a bundled data tier and SNMP simulator), generates a TLS certificate, and prints your login. Open https://localhost:8443 — the certificate is self-signed, so the browser will warn once; http://localhost:8090 redirects there. Full guide: docs/32-quickstart.md.

Running Proxmox? deploy/proxmox/netinv-lxc.sh create does all of the above inside a new LXC container, in about ten minutes, and destroy removes it — which also makes it a cheap way to test a branch against real hardware (docs/33-proxmox-lxc.md).

Running Kubernetes? Helm charts for the platform and for remote-site pollers, with the installation procedure and the things that bite in docs/35-kubernetes-deployment.md.

What it looks like

The flagship view — a live weathermap, links coloured by utilization, each rate naming the direction it runs:

The dashboard: status strip, inbound and outbound bandwidth per site, alerts, and a shared time range using Cacti's graph timespans.

Device detail, and the capacity view that answers whether the disk can hold the retention you asked for:

All screenshots are the bundled demo fleet against the SNMP simulator — the same dataset scripts/seed-demo.sh creates, so anyone can reproduce them. No real network appears in them.

What it does (v1)

• Collects interface traffic, errors/discards, device health (CPU/memory/temp/PSU/optics), ICMP availability/latency, and inventory metadata from network devices over SNMP v2c/v3.
• Stores metrics in VictoriaMetrics for 2 years by default (NETINV_VM_RETENTION), inventory/config/audit in PostgreSQL. A capacity view reports what the disk actually sustains against what retention asks for, measured rather than estimated.
• Shows a single dashboard: status summary, inbound and outbound bandwidth per site, active alerts, Top-N lists, capacity watchlist, and an editable utilization-colored weathermap. Every chart shares one time range — Cacti's graph timespans, from Half Hour to 2 Years.
• Tunes collection cadence fleet-wide from the UI (1/5/10/15 minutes), with query resolution and rate() windows following automatically.
• Finds any interface in the fleet by what someone wrote on it — ifAlias, description, name or customer — and tags interfaces with a customer in bulk from CSV, kept clear of sync so a reprovision cannot quietly erase it.
• Reports interface bandwidth over a period — average, 95th percentile, peak and totals per direction — filtered by customer and optionally grouped one row per customer, exportable as CSV. The aggregate is summed before the percentile is taken, so a customer's figures are of their combined traffic rather than a sum of per-circuit numbers.
• Alerts via Email, Webhook, and Slack with severity-based routing, ack/silence workflow.
• Scales from a single site to 100k devices across multiple datacenters via site-local pollers phoning home over RabbitMQ.

Stack (decided — see DECISIONS.md)

Layer	Choice
Backend	Go (modular monolith, microservice-ready)
Frontend	React + TypeScript + Vite, custom visualization (no Grafana)
Metrics	VictoriaMetrics (PromQL/MetricsQL)
Relational	PostgreSQL 16
Cache	Redis
Queue	RabbitMQ
Auth	Local accounts + JWT (OIDC-shaped; Keycloak later)
Deploy	Docker → on-prem Kubernetes, Helm
CI/CD	GitHub Actions → GHCR

Repository map

netinv/
├── README.md          ← you are here
├── CONTRIBUTING.md    ← how to work in this repo; what help is most wanted
├── SECURITY.md        ← reporting vulnerabilities; what NetInv holds worth attacking
├── CLAUDE.md          ← AI onboarding: read this first if you are an AI agent
├── DECISIONS.md       ← architecture decision log (ADR-lite); the "why" behind everything
├── docs/              ← the 35-document design package (numbered, see docs/README.md)
├── backend/           ← Go services: api, scheduler, poller, ingester, alerter, notifier, flow
├── connectors/        ← vendor connectors (cisco, juniper, huawei, zte, ubiquiti,
│                     ruckus, fortinet, paloalto)
├── frontend/          ← React + TypeScript app
├── deploy/            ← Helm charts, k8s manifests, docker-compose, Proxmox LXC installer
└── scripts/           ← dev and CI helpers (seed-demo, licences, connector contract)

Reading order

1. docs/01-executive-summary.md — 5-minute overview
2. docs/05-system-architecture.md — how it works
3. docs/26-development-roadmap.md — what gets built when
4. Full index: docs/README.md

Contributing

Outside eyes are worth more than outside code right now — especially if you own hardware NetInv has never been tested against. Six of the eight connectors have only ever met MIB specifications, and every connector that has met real hardware needed corrections that reading the spec would never have found.

If you point NetInv at a device, tell us what happened — including when it all worked. Start with CONTRIBUTING.md.

Project context

Solo developer + AI pair (Claude). Launch target under 500 devices across 4–5 on-prem datacenters, single organization, self-hosted; multi-tenancy and SaaS are designed-in but dormant. 20 two-week sprints, backend first.

Licence

Apache License 2.0 — commercial use, modification and distribution permitted, with an explicit patent grant (ADR-019). Every shipped dependency is permissively licensed; make licenses verifies that and fails on copyleft.