netscope

module
v0.19.1 Latest Latest
Warning

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

Go to latest
Published: Aug 6, 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 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.
  • Localized — follows your system language (English, 한국어, 日本語).

How it works

A root capture daemon (netscoped, bundled in the app, 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

Everything stays on your Mac. Bytes and hostnames only — payloads are never decrypted, and the country lookup uses an embedded offline database, so the IPs you contact are never sent to any third party.

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
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). Fonts: Work Sans and Space Mono (SIL OFL 1.1). 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