A self-hosted network monitoring tool with real-time ping plotting, network scanning, bandwidth tracking, device inventory, anomaly detection, and Ubiquiti UniFi integration. Runs locally on your machine with a web-based dashboard.
Unified overview of your entire network — live metrics, device counts, bandwidth, latency, anomaly alerts, and data export.
Multi-target ICMP ping with real-time SVG latency graphs. Tracks latency, jitter, packet loss, and TTL. Targets and history persist across restarts — add them once, they keep running.
Three scan modes:
- Quick — ARP + ping sweep (no nmap required)
- Standard — SYN scan + service version detection, top 1000 ports (requires nmap)
- Intensive — Full port range + OS fingerprinting + NSE scripts (requires nmap)
Also includes instant ARP table discovery and single-host deep port scanning.
Background ARP scanning tracks every device on your local network over time:
- Device inventory with custom names, trust flags, and notes
- New/unknown device alerts
- Offline detection for watched devices
- Network topology visualization
- Full event timeline with presence history per device
Real-time interface throughput monitoring at 5-second resolution with 24 hours of history. Per-interface breakdown. Speed tests via speedtest-cli, fast-cli, or curl fallback.
Statistical anomaly detection across all metrics using z-score analysis:
- Latency spikes beyond 3σ from baseline
- Packet loss exceeding 10%
- New unknown devices appearing on the network
- Bandwidth drops to near-zero (possible outage detection)
- All anomalies persisted to disk with deduplication
Direct connection to your Ubiquiti UniFi controller:
- Site health, WAN status, throughput
- Access points, switches, gateways with CPU/memory/experience scores
- All connected clients with signal strength and WiFi experience
- Alerts and events
- Supports UDM-Pro, UDR, UCG, USG, EFG, and legacy controllers
Central data store that all modules feed into:
- 24 hours of raw data (1-second resolution)
- 7 days of 1-minute rollups
- 90 days of hourly rollups
- Automatic persistence to
~/.netscope/
Deliver alerts via Slack, Discord, ntfy.sh, Pushover, or generic webhooks. Built-in deduplication prevents alert fatigue.
Export your full network dataset as JSON for external analysis:
- Full export with all time-series, device inventory, anomalies, and UniFi snapshots
- Summary export (compact, stats only)
- CSV exports for devices, events, and speed tests
- Download the latest release
- Extract the zip
- Double-click
RUN.bat
That's it. On first run it installs npm packages (~15 seconds), then opens your browser to http://localhost:3000.
Requires: Node.js 18+ (download the LTS version).
For a Desktop shortcut, run INSTALL.bat instead.
git clone https://github.com/jamesccupps/NetScope.git
cd NetScope
cp .env.example .env
npm install
npm start
# Open http://localhost:3000For full nmap scanning features (SYN scan, OS detection):
sudo npm start| Requirement | Required | Notes |
|---|---|---|
| Node.js 18+ | Yes | nodejs.org |
| nmap | No | Enables advanced scanning. nmap.org |
| speedtest-cli | No | Enables speed tests. pip install speedtest-cli |
Copy .env.example to .env and adjust:
PORT=3000 # Web server port
MONITOR_INTERVAL=60 # Background scan interval (seconds)- Open the UniFi tab in NetScope
- Enter your controller's local IP (e.g.,
https://192.168.1.1) - Enter your local admin username and password
- Click Connect
Note: This requires a local admin account on the controller, not your Ubiquiti SSO/cloud account. Create one in your UniFi console under Settings → Admins & Users if needed.
Self-signed certificates are automatically accepted.
NetScope/
├── server.js # Express + WebSocket server, REST API
├── lib/
│ ├── datastore.js # Central time-series database
│ ├── anomaly.js # Statistical anomaly detection
│ ├── collector.js # Wires all modules → datastore
│ ├── ping.js # ICMP ping with persistence
│ ├── scanner.js # nmap + ARP + TCP scanning
│ ├── monitor.js # Continuous device tracking
│ ├── bandwidth.js # Interface throughput + speed tests
│ ├── notifications.js # Alert delivery (Slack, Discord, etc.)
│ └── unifi.js # UniFi Controller API client
├── public/
│ └── index.html # React SPA (via CDN, no build step)
├── RUN.bat # Windows launcher
├── INSTALL.bat # Windows installer (creates Desktop shortcut)
└── package.json
All persistent data is stored in ~/.netscope/ (or %USERPROFILE%\.netscope\ on Windows):
| File | Contents |
|---|---|
timeseries.json |
All metric time-series (raw + rollups) |
ping-targets.json |
Saved ping targets |
ping-history.json |
Ping history (last 10,000 points per target) |
devices.json |
Device inventory |
events.json |
Monitor event log |
anomalies.json |
Detected anomalies |
bandwidth.json |
Throughput history |
config.json |
Monitor settings |
Full REST API available at http://localhost:3000/api/. Key endpoints:
| Endpoint | Description |
|---|---|
GET /api/history/metrics |
List all tracked metrics |
GET /api/history/query/:metric?hours=6 |
Query time-series data |
GET /api/history/stats/:metric?minutes=60 |
Get stats (avg, p95, stddev) |
GET /api/anomalies |
All detected anomalies |
GET /api/anomalies/active |
Anomalies from last hour |
GET /api/export/full?hours=24 |
Full data dump (JSON) |
GET /api/export/summary |
Compact summary |
GET /api/ping/targets |
Ping targets and history |
GET /api/monitor/devices |
Device inventory |
GET /api/bandwidth/summary |
Bandwidth stats |
GET /api/unifi/overview |
UniFi overview (when connected) |
Real-time data is streamed via WebSocket at ws://localhost:3000/ws.
Create a scheduled task:
schtasks /create /tn "NetScope" /tr "node C:\path\to\NetScope\server.js" /sc onlogon /rl highest# /etc/systemd/system/netscope.service
[Unit]
Description=NetScope Network Monitor
After=network-online.target
[Service]
Type=simple
User=root
WorkingDirectory=/opt/netscope
ExecStart=/usr/bin/node server.js
Restart=on-failure
Environment=NODE_ENV=production
[Install]
WantedBy=multi-user.targetsudo systemctl enable --now netscope# Create ~/Library/LaunchAgents/com.netscope.plist with your paths
launchctl load ~/Library/LaunchAgents/com.netscope.plist"Node.js not found" — Install from nodejs.org. On Windows, make sure "Add to PATH" is checked during installation. If RUN.bat still can't find it, restart your computer.
"nmap not found" — Optional. Without it, the scanner uses a built-in TCP connect scanner (slower but functional). Install from nmap.org.
"Permission denied" during scan — SYN scans and OS detection require elevated privileges. Run with sudo (Linux/macOS) or as Administrator (Windows).
"Cannot reach UniFi controller" — Verify the URL, ensure the controller is running, and test with curl -k https://YOUR_CONTROLLER_IP.
Empty fields in UniFi tab — Different firmware versions use different API field names. Open http://localhost:3000/api/unifi/debug to see the raw API response for troubleshooting.
Contributions welcome! Please open an issue first to discuss what you'd like to change.