FAQ

Why does netscope need root?

netscoped creates cgroups under /sys/fs/cgroup, opens a fanotify permission group, and invokes nft and ip. All of those require privilege. The CLI itself is unprivileged and talks to the daemon over a Unix socket; only the daemon is root.

If you do not want a root daemon, do not run netscope. There is no unprivileged mode.

Why not eBPF?

eBPF could implement similar filtering, but it adds a verifier, program loading, kernel-version-specific bytecode, and a larger privileged surface. cgroup v2 plus nftables already provides a stable socket-to-cgroup match on the kernels netscope targets, with rules that are easy to inspect using nft list. netscope loads no BPF program and no kernel module.

This is a scope decision, not a claim that eBPF is unsuitable for every workload.

Why kernel 5.13?

5.13 is the first kernel with FAN_OPEN_EXEC_PERM, the fanotify permission event that lets the daemon hold an exec while it moves the process into the profile cgroup. Without it, only late attachment is possible and the first sockets can escape. netscope targets 5.13 and newer rather than shipping a weaker guarantee on older kernels.

Is there a wrapper?

No. You launch the application normally. There is no netscope run -- app, no LD_PRELOAD, and no proxy environment variable to set. A native app is selected at exec through fanotify; a Windows PE is selected when Wine opens it; a name target holds the Wine/Proton loader and catches a new launch before its first socket, and the poller catches an already-running process late.

Can I select a running app by name without a path?

Yes. --process <name> attaches a running process by its comm or an argv basename, with no install path and no wrapper:

sudo netscope --uid "$(id -u)" add game --process Overwatch.exe --route tun0

Matching is case-insensitive and a trailing .exe is optional. A new Wine/Proton launch is caught by the loader hold before its first socket; a process that was already running is attached on the next poll, and the sockets it already held are marked with the profile mark at the same time, so their next packets follow the profile too. A restart is not required.

What about applications that are already running?

They are attached late by the poller, if they match. Sockets that were opened before the attach are marked with the profile mark, so their next packets follow the profile. The CLI warns you when it attaches to an already-running app and says the sockets were marked. Restart only if the daemon reports that a descriptor could not be marked.

Does netscope affect the whole system?

No. It scopes selected applications, one profile at a time, up to 32 profiles. Other processes keep their normal networking. There is no system-wide mode.

If you need system-wide filtering or routing, use a firewall, a VPN client with a kill switch, or a network namespace. netscope is not a replacement for those.

Does it hide my IP or encrypt traffic?

No. Filter mode accepts or drops packets. Route mode sends marked packets to an interface you configured; it does not create or encrypt a tunnel. Your VPN or tunnel client provides encryption. netscope does not change your source address by itself.

Does it work with WireGuard, OpenVPN, or another VPN?

Route mode works with any interface that exists on the host, such as wg0 or tun0, as long as the interface can carry the traffic and has a route. netscope does not configure the VPN, its DNS, or its kill switch.

Filter mode is independent of the VPN; it filters destinations regardless of the route they would take.

Does it survive a reboot?

Profiles are stored in /var/lib/netscope/state.json, so definitions survive a reboot. The host rules do not; the daemon recreates them when it starts. Enable netscoped at boot:

sudo systemctl enable netscoped

An application that starts before the daemon is attached late; its existing sockets are marked when it attaches. Start the daemon early if you need the pre-exec path, or restart the app if the daemon reports a mark failure.

Can I edit a profile?

A consumer’s policy can be replaced with netscope policy <profile> --consumer <id> .... The target itself is not edited in place; remove and re-add to change it. enable and disable toggle enforcement without changing the definition.

Can one profile cover several applications?

No. One profile has one target: a native executable, a running process name, a Windows PE run through Wine/Proton, or a Steam app ID. Use separate profiles, up to 32.

Can two profiles target the same application?

Two consumers that name the same target and target uid join one profile and cgroup through netscope open, so they share the process identity instead of competing for it. Each consumer has its own policy; a profile carries one route policy and any number of filter policies. A second netscope add for the same target and uid is refused with target already scoped; use open when two programs need the same app.

Does it capture or log my traffic?

No packet capture, no payload logging, no DNS logging. The daemon logs operational events such as profile changes, attachment source, nftables failures, and reconciliation results. netscope logs shows a bounded recent view.

Does it support IPv6?

Filter mode supports IPv6 CIDRs and loopback. Route mode drops IPv6 by default; --allow-ipv6 installs an IPv6 rule and route. If the tunnel does not carry IPv6, leaving it disabled is the safe choice.

How is DNS handled?

netscope does not rewrite DNS. In filter mode, allow the resolver’s address if the profile uses --filter drop. In route mode, the app’s DNS follows the tunnel; configure DNS in the tunnel client or use a resolver reachable through it.

Does it work with Steam games?

Yes, with --steam <appid>. Add the profile before launching the game and launch it through Steam. If Steam was already running, restart it so the game’s process is attached before it opens sockets.

Does it work with Wine, Proton, or Windows games?

Yes, with --wine <path> pointing at the .exe. The path must be absolute, and the file must start with MZ. netscope marks that PE; when Wine opens it, the daemon holds the open, finds the Wine process whose command line names the PE, moves that process into the profile cgroup, and then allows it. status shows pre-open.

Only a Wine process running the selected PE is attached. Another program that opens the same .exe — a file manager, a scanner, a copy — is allowed and left unscoped. wineserver is never attached: it may open the PE on behalf of a loader, but it is a shared server, not the game.

If fanotify cannot be used, the fallback matches Wine processes by command line, including Z:\... paths and the C:\...//drive_c/ form, and attaches late. Sockets opened during startup are marked at attach, so their next packets follow the profile; restart only if the daemon reports a mark failure.

For Proton, select the actual PE path that Wine opens; a copy under steamapps/compatdata/<appid>/pfx/drive_c/ is a different file from the one under steamapps/common/. --steam <appid> remains available for app-id matching. If you do not want to store a path, --process Overwatch.exe holds the Wine loader for a new launch and learns the PE from the loader’s command line; a game that was already running attaches on the next poll, with its existing sockets marked. Flatpak, Snap, and unusual filesystems are not tested: if the profile does not attach, check netscope status and restart the game. Real Wine and Proton launches are not covered by the project’s automated tests; the attach path is exercised with a Wine-named test loader, so report a reproducible failure.

Is it a firewall?

No. It is a per-application scoping tool built on nftables. It does not replace a firewall, and route mode is not a guaranteed kill switch. See Security and Route mode.

Does it work on Windows or macOS?

No. It relies on Linux cgroup v2, fanotify, nftables, and policy routing.

Does it work with Flatpak or Snap applications?

Not tested in v0.2.1. Sandboxed applications may run in a different cgroup or mount namespace, and the executable path you see outside the sandbox may not be the path the daemon matches. Use netscope status to see whether the process was attached, and report a reproducible case.

What license is it under?

Dual-licensed under MIT OR Apache-2.0, at your option. Contributions are accepted under the same terms and require a DCO sign-off.

Why is there no GUI or remote dashboard?

The v0.2.x scope is a CLI and a local root daemon. There is no network listener, no telemetry, and no hosted service. A remote UI would widen the privileged surface and is out of scope for now.