netscope

module
v0.26.1 Latest Latest
Warning

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

Go to latest
Published: Sep 9, 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. Everything runs locally: no traffic contents are read, nothing captured leaves your Mac, and the capture daemon opens no network port.

release license platform lang

netscope dashboard netscope menu-bar popover    netscope in the menu bar

Install

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

netscope.app lands in /Applications and launches — no Gatekeeper prompt, no Homebrew, no Apple account. The installer asks for your admin password once (in the terminal) to set up the capture helper. The download is verified against the release's SHA-256 checksums.txt.

Other ways: brew install --cask doldoldol21/netscope/netscope, or grab the app from the latest release (then xattr -dr com.apple.quarantine /Applications/netscope.app if a browser downloaded it).

Features

  • Menu bar — live ↓↑ rate readout (choose style/color) and a popover with today's total and top apps.
  • Dashboard — throughput chart (live/day/week/month), per-app and per-domain rankings with search and sorting, per-app drill-down, live connections, traffic by country (offline GeoIP — no external lookups).
  • Alerts — macOS notification when today's total, uploads, or a single app crosses a limit you set.
  • Monthly data plan — track a tethered phone's allowance per billing cycle (used, left, projected).
  • Self-updating — checks GitHub Releases and updates in one click; downloads are SHA-256 verified.
  • CLI — netscope, netscope apps --range week, netscope export … > out.csv, netscope --version.
  • Localized — follows your system language (English, 한국어, 日本語).

How it works

A root capture daemon (netscoped, bundled in the app and copied to /Library/PrivilegedHelperTools on install so what runs as root can't be swapped afterwards, managed by launchd) counts bytes per process with libpcap + libproc and maps IPs to domains from your own DNS replies, TLS SNI, and reverse DNS — HTTPS stays encrypted. It serves JSON over a 0600 unix socket only; the app's dashboard window talks to it through a loopback-only proxy. Details in CONTRIBUTING.md.

Privacy

Captured data stays on your Mac, owner-only on disk (the database and DNS cache are 0600 in a 0700 directory), so other local accounts can't read it either. Bytes and hostnames only — payloads are never decrypted, nothing captured is uploaded, and the country lookup uses an embedded offline database, so no address is ever sent to a geolocation service.

Two things do go out, both ordinary network requests rather than capture data:

  • Reverse DNS. Any IP that no observed DNS answer and no TLS SNI has already named gets a PTR lookup, which tells whoever runs your resolver — an ISP, a VPN, a workplace — which addresses this machine reached. DNS and SNI naming are passive by comparison: they read replies your machine was receiving anyway. netscoped --no-revdns stops the lookups; names an earlier run already learned stay in the on-disk cache, since the flag prevents new queries rather than erasing old answers.
  • Update checks. Every few hours the app asks api.github.com for the latest release, and the daemon makes the same check to fill /api/version. These are separate: Automatic updates in settings stops the app's check only, and the daemon's needs netscoped --no-update-check.

Daemon flags live in /Library/LaunchDaemons/io.netscope.daemon.plist under ProgramArguments. After editing it, make launchd re-read the file — a restart keeps the definition it already loaded:

sudo launchctl bootout system/io.netscope.daemon
sudo launchctl bootstrap system /Library/LaunchDaemons/io.netscope.daemon.plist

Reinstalling the capture helper rewrites that plist, so flags added by hand need re-applying afterwards.

Develop

Requires Go 1.25+ and Xcode Command Line Tools.

make demo       # synthetic daemon + app, no root needed
make test       # unit + offline integration tests
make app        # dist/netscope.app
make package    # dist/: app, zip, checksums, installer

Uninstall

sudo launchctl bootout system/io.netscope.daemon 2>/dev/null
sudo rm -f /Library/LaunchDaemons/io.netscope.daemon.plist
sudo rm -f /Library/PrivilegedHelperTools/io.netscope.daemon
rm -rf /Applications/netscope.app ~/Library/LaunchAgents/io.netscope.app.plist
sudo rm -rf /var/db/netscope /var/run/netscope

Credits & license

IP-to-country data: DB-IP Lite (CC BY 4.0). The UI ships no fonts; it uses the system face. Code: 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.
netscoped command
Command netscoped is netscope's capture daemon.
Command netscoped is netscope's capture daemon.
Command netscope-app is netscope's menu-bar application.
Command netscope-app is netscope's menu-bar application.
internal
alerts
Package alerts decides when to notify the user that their network usage has crossed a configured threshold (a daily total cap, or a per-app daily cap).
Package alerts decides when to notify the user that their network usage has crossed a configured threshold (a daily total cap, or a per-app daily cap).
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.
dataplan
Package dataplan turns recorded per-network usage into "how much of my monthly data allowance is gone" — the number a tethered user would otherwise have to open their carrier's app to see.
Package dataplan turns recorded per-network usage into "how much of my monthly data allowance is gone" — the number a tethered user would otherwise have to open their carrier's app to see.
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:
geoip
Package geoip maps an IP address to its ISO 3166-1 alpha-2 country code using a compact database embedded in the binary.
Package geoip maps an IP address to its ISO 3166-1 alpha-2 country code using a compact database embedded in the binary.
i18n
Package i18n localizes the handful of user-facing strings the Go side produces (notification bodies, menu-bar style labels).
Package i18n localizes the handful of user-facing strings the Go side produces (notification bodies, menu-bar style labels).
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).
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 and reports it to the UI.
Package update checks whether a newer netscope release is available on GitHub and reports it to the UI.
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