netscope

module
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 19, 2026 License: MIT

README

netscope

netscope

See which apps are using your network — live, right from the menu bar.

A per-app network traffic monitor for macOS, in the spirit of RunCat / iStat: always-on, glanceable, and useful for everyone. Everything runs locally — no traffic contents are read, no data leaves your Mac, no open network port.

release license platform lang

netscope in the menu bar

live download / upload, always in your menu bar

⚡ Quick Start

curl -fsSL https://raw.githubusercontent.com/doldoldol21/netscope/main/install.sh | bash

That's it — netscope.app lands in /Applications and launches. No Gatekeeper warning (curl-fetched apps aren't quarantined), no Homebrew, no Apple account. The installer asks for your admin password once, right there in the terminal, to set up the capture helper — so the app itself opens with no pop-up dialogs, live in your menu bar and starting at boot.

Click the menu-bar item for the top apps, Open Dashboard… for the full window, or toggle Launch at Login.

One app, fully self-managing. Capture needs root (/dev/bpf*), so the app installs a small root daemon (the one admin prompt) that serves data over a local Unix socket — no TCP port is ever opened. Prefer the terminal? brew install doldoldol21/netscope/netscope-cli builds the netscope / netscoped / netscope-bar binaries from source.

What you get

  • Menu bar — live ↓↑ throughput + a dropdown of the top apps (RunCat-style).
  • Dashboard — a native window: throughput chart, today/week rankings, and per-domain breakdown with neutral categories (cloud, cdn, media, ai, …).
  • CLI — netscope, netscope apps --range week, netscope domains …
  • Private by design — HTTPS stays encrypted; netscope only counts bytes per process and maps IPs to domains by watching your own DNS replies.

How it works

┌── netscoped (root, launchd) ──────────────────────┐
│  libpcap capture ─► decode (IP/TCP/UDP + DNS)      │
│        │                    │                       │
│        ▼                    ▼                       │
│  resolver (libproc)    dnscache (IP→domain)        │
│   socket→PID→app       + reverse DNS               │
│        │                    │                       │
│        └──────► engine (attribute + aggregate)      │
│                     │            │                  │
│                     ▼            ▼                  │
│                 SQLite       live snapshot          │
│                     └─────┬────────┘                │
│                           ▼                          │
│                   /api over UNIX SOCKET             │
└───────────────────────────┬────────────────────────┘
              unix:///var/run/netscope/netscoped.sock  (0600, owned by you)
         ┌─────────────┬─────────────┴───────────┐
         ▼             ▼                          ▼
  netscope-bar   netscope.app (Wails)      netscope CLI
  menu bar       full dashboard window      terminal viewer
Why a daemon + an app (not a single program)

Packet capture needs root (/dev/bpf*); a GUI app must run unprivileged in your login session. So netscope splits the two:

  • netscoped — runs as root under launchd, captures and aggregates, and serves /api on a unix socket. No TCP port is opened, so no browser or other user's process can reach your traffic data; access is gated by the socket file's ownership (chowned to you, mode 0600).
  • netscope-bar — the macOS menu-bar app (Go + systray). Shows the live down/up rate in the menu bar and a native dropdown of the top apps; no dock icon (runs as an accessory). Reads the daemon socket.
  • netscope.app — a Wails window that embeds the dashboard UI (internal/webui, vanilla JS/CSS, no Node build) and reverse-proxies /api (including the live SSE stream) to the daemon's socket. Opened from the menu.
  • netscope — a CLI that reads the same socket for terminal views.

Install

  • App (recommended): the Quick Start one-liner. Installs netscope.app to /Applications with no Gatekeeper prompt.
  • CLI / Homebrew: brew install doldoldol21/netscope/netscope-cli — builds the netscoped/netscope/netscope-bar binaries from source (also no Gatekeeper, since it's compiled locally).
  • Direct download: grab netscope.app from the latest release. If you download it in a browser, clear the quarantine flag once: xattr -dr com.apple.quarantine /Applications/netscope.app.

Want a notarized, zero-step download instead? That needs an Apple Developer account; the signing/notarization hooks are wired in scripts/package.sh (NETSCOPE_SIGN_ID / NETSCOPE_NOTARY_PROFILE).

From source

Requires Go 1.24+ and macOS (Xcode Command Line Tools for the C toolchain).

git clone https://github.com/doldoldol21/netscope
cd netscope
make build          # bin/netscoped, bin/netscope, bin/netscope-bar

Build the binaries (daemon, CLI, menu-bar app) and the dashboard window:

make build                            # bin/netscoped, bin/netscope, bin/netscope-bar
go install github.com/wailsapp/wails/v2/cmd/wails@latest   # once (make app auto-installs if missing)
make app                              # desktop/build/bin/netscope.app (dashboard window)
make bar-app                          # bin/netscope-bar.app (menu-bar app, no dock icon)

Install the always-on capture daemon (launchd, runs as root) and the binaries:

make install        # copies to /usr/local/bin + loads the LaunchDaemon
make uninstall      # remove daemon + binaries

The menu-bar app has a Launch at Login toggle (a per-user LaunchAgent — no admin needed). Use it to keep netscope always on.

Packaging a release
make package        # builds + bundles both .app + binaries into dist/, ad-hoc signed

dist/ gets netscope.app, netscope-bar.app, the netscoped/netscope binaries, an installer and a zip. For distribution to other Macs, set NETSCOPE_SIGN_ID (Developer ID) and NETSCOPE_NOTARY_PROFILE to sign + notarize — otherwise Gatekeeper warns (right-click → Open works). Icons are generated from assets/app-icon.svg via make icons.

The app needs netscoped running. After make install the daemon listens on /var/run/netscope/netscoped.sock; the app connects there automatically. Override the socket path with the NETSCOPE_SOCK env var.

Usage

Live capture (needs root)
sudo bin/netscoped           # capture + serve the API on the unix socket
bin/netscope open            # launch the native app

Packet capture reads /dev/bpf*, which requires root. Running under launchd (make install) is the recommended way to avoid sudo. The daemon chowns the socket to you so the (unprivileged) app and CLI can connect.

CLI viewer (no root — talks to the running daemon)
bin/netscope                 # live terminal table (default: "top")
bin/netscope apps --range week
bin/netscope domains --range today
bin/netscope open            # launch the native app

--range is one of hour | today | day | week. Point at a non-default socket with --sock /path/to.sock.

Demo / development (no root)

One command — runs a synthetic-traffic daemon and launches the menu-bar app, showing realistic named apps (Claude, ChatGPT, Safari, Spotify, …). Look at the menu bar; use the menu's "Open Dashboard…" for the window:

make demo            # Ctrl-C (or the menu's Quit) to stop; uses a user-writable dev socket

For dashboard UI hot-reload, split it across two terminals (both use the dev socket automatically, no env var needed):

make demo-daemon     # terminal 1: synthetic daemon
make app-dev         # terminal 2: dashboard with live-reload

To exercise the real capture pipeline from a file (note: apps show as unknown because the original sockets no longer exist — domains still resolve):

go run tools/gensample.go testdata/sample.pcap
make run-pcap PCAP=testdata/sample.pcap

Daemon flags

--iface       interface to capture (default: auto-detect)
--pcap        replay a pcap file instead of live capture (no root)
--demo        serve synthetic named-app traffic (no root; for UI/dev)
--sock        unix socket to serve the API on (default /var/run/netscope/netscoped.sock,
              or $NETSCOPE_SOCK)
--db          SQLite path (default ~/Library/Application Support/netscope/netscope.db)
--no-store    run in memory only, no persistence
--bucket      aggregation/flush granularity (default 10s)
--retention   how long to keep samples (default 720h; 0 = forever)
--live-window keep apps/domains in the live "session" view if active within this
              window (default 30m; 0 = whole session)
--print       also print top apps to stdout periodically

API (over the unix socket)

The daemon serves JSON on the unix socket only — no static files, no TCP. Probe it with curl --unix-socket /var/run/netscope/netscoped.sock http://x/api/health.

Endpoint Description
GET /api/snapshot current live snapshot (rates + session apps/domains)
GET /api/live Server-Sent Events stream of snapshots (1/s)
GET /api/apps?range=today per-app totals over a range
GET /api/domains?range=today per-domain totals over a range
GET /api/summary?range=today totals, app/domain counts, top app + top domain
GET /api/timeseries?range=day&step=60 rx/tx time series
GET /api/health liveness + persistence status

How attribution works

  • bytes → process: macOS has no "4-tuple → PID" syscall, so the resolver periodically enumerates every process' socket file descriptors via libproc (proc_pidinfo / proc_pidfdinfo) and builds a reverse index keyed by protocol + local port + remote endpoint. Lookups rescan on demand (rate limited) when a brand-new connection misses the cache.
  • IP → domain: the decoder sniffs DNS responses and caches each answer's A/AAAA IP against the queried name, so flows can be grouped by domain.
  • category: domains are matched (by registrable suffix) into neutral groups (cloud / cdn / media / social / ai / tracking) shown as a chip.

Limitations

  • macOS only in Phase 1 (Linux is a Phase 2 goal). Non-darwin builds compile but capture is stubbed out.
  • HTTPS payloads are never decrypted — you see domain + byte counts only.
  • Offline replay shows apps as unknown because the original sockets no longer exist on the host; live capture resolves real app names.
  • App identity is keyed by executable/bundle name, so multiple processes of the same app are merged in rankings.

Development

make test       # unit + offline integration tests (no root needed)
make cover
make vet
make fmt

License

MIT — see LICENSE.

Directories

Path Synopsis
cmd
netscope command
Command netscope is the user-facing CLI client for the netscope daemon.
Command netscope is the user-facing CLI client for the netscope daemon.
netscope-bar command
Command netscope-bar is netscope's macOS menu-bar app.
Command netscope-bar is netscope's macOS menu-bar app.
netscoped command
Command netscoped is netscope's capture daemon.
Command netscoped is netscope's capture daemon.
Command netscope-app is the native macOS shell for netscope.
Command netscope-app is the native macOS shell for netscope.
internal
api
Package api exposes the engine's live snapshot and the store's history over HTTP, and serves the embedded dashboard.
Package api exposes the engine's live snapshot and the store's history over HTTP, and serves the embedded dashboard.
buildinfo
Package buildinfo exposes the build version, shared by every netscope binary.
Package buildinfo exposes the build version, shared by every netscope binary.
capture
Package capture turns raw packets into attributed flows.
Package capture turns raw packets into attributed flows.
classify
Package classify maps domains to human-friendly categories and flags the AI services that motivated netscope in the first place.
Package classify maps domains to human-friendly categories and flags the AI services that motivated netscope in the first place.
daemonctl
Package daemonctl lets the unprivileged menu-bar app bring up the privileged capture daemon itself, so the user only ever launches one app.
Package daemonctl lets the unprivileged menu-bar app bring up the privileged capture daemon itself, so the user only ever launches one app.
demo
Package demo provides a synthetic traffic source and resolver so the UI can be run and developed without root (no packet capture) while still showing realistic, named per-app traffic — unlike offline pcap replay, where apps resolve to "unknown" because the original sockets no longer exist.
Package demo provides a synthetic traffic source and resolver so the UI can be run and developed without root (no packet capture) while still showing realistic, named per-app traffic — unlike offline pcap replay, where apps resolve to "unknown" because the original sockets no longer exist.
dnscache
Package dnscache maps remote IP addresses back to the hostnames the local machine resolved them from.
Package dnscache maps remote IP addresses back to the hostnames the local machine resolved them from.
engine
Package engine is the heart of netscope: it consumes attributed flows, resolves each to an owning app and a domain, and maintains two sets of counters:
Package engine is the heart of netscope: it consumes attributed flows, resolves each to an owning app and a domain, and maintains two sets of counters:
ipc
Package ipc centralises the local IPC between the privileged netscoped daemon and its unprivileged clients (the Wails app and the CLI).
Package ipc centralises the local IPC between the privileged netscoped daemon and its unprivileged clients (the Wails app and the CLI).
menubar
Package menubar implements netscope's macOS menu-bar (status bar) app: a RunCat-style always-on presence that shows the live up/down rate in the menu bar and a native dropdown of the top apps, reading everything from the daemon over its unix socket.
Package menubar implements netscope's macOS menu-bar (status bar) app: a RunCat-style always-on presence that shows the live up/down rate in the menu bar and a native dropdown of the top apps, reading everything from the daemon over its unix socket.
resolver
Package resolver maps a network connection (proto + local port + remote endpoint) to the process that owns it, and that process to a display name.
Package resolver maps a network connection (proto + local port + remote endpoint) to the process that owns it, and that process to a display name.
revdns
Package revdns resolves remote IPs to hostnames via reverse DNS (PTR) as a fallback when netscope never saw a forward DNS answer — e.g.
Package revdns resolves remote IPs to hostnames via reverse DNS (PTR) as a fallback when netscope never saw a forward DNS answer — e.g.
storage
Package storage persists aggregated traffic into SQLite and answers the ranking / time-series queries the API exposes.
Package storage persists aggregated traffic into SQLite and answers the ranking / time-series queries the API exposes.
update
Package update checks whether a newer netscope release is available on GitHub.
Package update checks whether a newer netscope release is available on GitHub.
webui
Package webui holds the embedded dashboard assets shared by the daemon's HTTP server and the Wails desktop shell, so both render the exact same UI from a single source of truth.
Package webui holds the embedded dashboard assets shared by the daemon's HTTP server and the Wails desktop shell, so both render the exact same UI from a single source of truth.
pkg
types
Package types holds the data structures shared between the capture daemon, the aggregation/storage layer and the HTTP API.
Package types holds the data structures shared between the capture daemon, the aggregation/storage layer and the HTTP API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL