- Python 48.7%
- Go 33.2%
- Shell 18%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
dev
6e9e4a11c9
Lanes stay strict by default. --allow-subnet lets a lane reach an IPv4 subnet through the host's own route (masqueraded, replies only), and --allow-host-port opens one port on the host itself, also reachable at localhost inside the lane; every other host address and port stays blocked. --deny-*, --strict and an interactive --access prompt change them later, and the TUI gains a LAN Access dialog plus per-assignment access that is reapplied when a lane is recreated. Allowances live in lane state and are enforced in the lane routing table, the lane nft table, the namespace guard, and as scoped iptables/native-chain exceptions, all verified and repaired by the supervisor. Lane iptables and native exceptions are now found and removed by their comment so stale allowances never survive. The forward chain also drops unsolicited traffic into the lane veth. |
||
| cgroup-route | ||
| cmd/net-lane-scripts | ||
| internal/app | ||
| lane-capture | ||
| lane-shaping | ||
| licenses | ||
| netns-lanes | ||
| nic-doctor | ||
| safe-mode | ||
| tests | ||
| tools | ||
| .gitignore | ||
| CHEATSHEET.md | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
| run.sh | ||
| TROUBLESHOOTING.md | ||
Net Lane Scripts
Linux tools for isolating browser profiles to an interface, capturing application
traffic, shaping lanes and diagnosing network connections. Each tool has its own
folder and run.sh entry point.
./run.sh --list
./run.sh --check
./safe-mode/run.sh --snapshot
./netns-lanes/run.sh --pick
Run tools as your normal user. They obtain root when needed. Browser isolation reserves the chosen interface for approved profiles and for apps you run inside the lane. Use explicit commands for unattended setup:
./netns-lanes/run.sh --iface wlan0 --sharing exclusive --up
./netns-lanes/run.sh --iface wlan0 --add-profile work --browser firefox --launch
./netns-lanes/run.sh --profiles
./netns-lanes/run.sh --iface wlan0 --remove-profile work
./netns-lanes/run.sh --iface wlan0 --release
Removing a profile closes only its process tree, preserves its data and offers a normal-network relaunch, defaulting to No. Removing every profile leaves an empty lane; an exclusive interface stays reserved until released. Other host applications need another uplink while an interface is exclusive.
Tools
| Tool | Purpose |
|---|---|
| Network Namespace Lanes | Pin approved browser profiles to one interface with a kill switch and optional LAN access. |
| Lane Capture | Capture a lane's traffic and summarize DNS/TLS names. |
| Lane Shaping | Add delay/loss or disconnect a lane without slowing the host. |
| Cgroup Route | Apply alternate routing to an already-running process, with weaker isolation than a browser lane. |
| NIC Doctor | Diagnose link, addressing, gateway, DNS, captive portal and MTU behavior. |
| Safe Mode | Inspect and remove toolkit network resources. |
Each folder is independently copyable. Keep the lane entry point and its Python companion together. Runtime state, profiles and captures are stored outside the repository. No daemon installation or permanent NetworkManager profile change is required.
Terminal Interface
Build the Go frontend with Go 1.24 or newer:
make build
./run.sh --tui
Once built, ./run.sh opens the TUI in a terminal. ./run.sh --menu retains the
numbered tools menu; existing tool commands remain available. The binary is
bin/net-lane-scripts. Its --inspect option prints read-only JSON status.
The TUI discovers built-in and external Ethernet/Wi-Fi NICs, observes the main host uplink and VPN egress, and verifies lane roles. Virtual interfaces are inspection-only. NetworkManager must already manage a NIC before the TUI can change its connection. Built-in forms cover IP/DNS, hidden/personal Wi-Fi, and PEAP, TTLS, and EAP-TLS enterprise authentication.
Select a Wi-Fi NIC and choose Find Wi-Fi Networks, or open Connections, to scan and list nearby SSIDs with signal strength, security, and saved profiles. Press Enter on a network, enter its password, then choose Save And Connect. SSID, security and NIC are prefilled; IP addresses, gateway and DNS default to automatic network configuration. Existing saved/custom settings are preserved. Advanced Settings exposes manual IP/DNS, hidden networks and connection options; enterprise authentication fields appear when Enterprise security is selected. Press S on Connections or choose Scan Wi-Fi to rescan; use New Wi-Fi Connection for a hidden SSID. Connecting pauses existing browser traffic. Open Browser verifies and resumes protection and checks DNS inside the isolated lane before starting the selected profile.
Register or discover a native/portable Chromium- or Firefox-family browser, including forks, then select Verify Browser. Unknown forks accept an explicit family and custom executable. The probe uses a temporary profile in a blocked network namespace. Flatpak and Snap launchers are unsupported. AppImages must work without privileged runtime setup; extracted portable builds are supported.
Use Approve Profile to create an approved browser profile and reserve its NIC while disconnected. This verifies the browser and leaves the lane held. After connecting, choose Open Browser or press B from any screen. On Profiles and Browsers it preselects the highlighted profile, assignment or browser. Select the profile and NIC access policy, then Open Browser checks the active network, resumes protection, and launches it. It can also create a new profile and verify its browser in the same flow. Successful network connections offer Open Browser immediately. The header shows the selected NIC/network and whether browser traffic is paused or running.
Save an interface, designated NetworkManager connection, browser, profile, and allowed LAN subnets and host ports under Profiles. LAN Access changes a running lane's allowances and stores them on its assignments. Saving or opening the TUI does not apply the assignment. Connect And Launch reserves the NIC before connection activation and holds profiles until routing, DNS, device identity, and guards are verified. A failed operation leaves its lane blocked and reserved. Removing a profile keeps its data; reopening on normal host networking requires explicit confirmation.
Run as a normal user. sudo authenticates lane operations; polkit authorizes
NetworkManager changes, using pkttyagent when terminal authentication is needed.
The frontend uses compiled Go modules tview, tcell/v2, and godbus/dbus/v5;
it adds no Python package or ncurses dependency. NetworkManager's configured
Wi-Fi backend and the selected browser's own runtime libraries are also needed.
Credentials are masked and remembered by NetworkManager only when selected.
Configuration is private at $XDG_CONFIG_HOME/net-lane-scripts/config.json
(default ~/.config/net-lane-scripts/config.json) and contains no credentials.
Existing browser-lane dependencies below remain required.
Optional browser installation is available as Browsers → Install Browser, from Open Browser → New Profile, or with:
./run.sh --install-browser
./run.sh --install-browser --browser google-chrome
./run.sh --install-browser --browser microsoft-edge
The numbered --menu also offers B: Install Browser. Installation always
requires an explicit selection; finding no browser offers a prompt. Built-in
installers support native Google Chrome and Microsoft Edge on Linux amd64 and
reuse existing stable system installations. Downloads come from the vendor's
HTTPS package repository and are checked against its SHA-256 metadata. New
browsers are installed under ~/apps and registered for this user; they do not
change the default browser or auto-update. Keep user-local browsers updated
manually, or use a system-managed installation. Optional extraction dependencies
are ar (binutils) and the archive's xz, zstd, or gzip decoder. Other native
Chromium/Firefox browsers and forks can still be discovered or registered.
Release Bundles
A Linux amd64 bundle contains the compiled TUI and the complete runtime toolkit; keep its directories together. Go is not required to run that bundle. Source archives require Go 1.24 or newer to build the TUI. Runtime requirements below apply to both distributions. Automatic browser downloads support Linux amd64; other Linux architectures can build from source and register native browsers.
Prepare both archives and their SHA-256 checksums in an empty output directory:
make release VERSION=0.1.0 DIST_DIR=dist
make release-check DIST_DIR=dist
Release packaging requires Go, Python 3 and access to the pinned Go modules and
Go 1.27.3 toolchain. It builds a static Linux amd64 TUI with that toolchain,
preserves executable entry points, and includes dependency licenses in
THIRD_PARTY_NOTICES.txt. Each archive carries VERSION and a
RELEASE-MANIFEST.json with its source identity, file hashes and permissions.
release-check verifies both archives, checksums and manifests. Keep browser
profiles, credentials, captures and machine-specific integrations outside the
source tree. Network isolation still requires qualification on the intended
kernel, firewall and physical interface.
Requirements
Linux, iproute2 and iptables are the basic toolkit requirements. Cgroup routing
and lane shaping also use util-linux flock. Capture uses util-linux setpriv
when dropping to the invoking user. Safe Mode requires Python 3.9+
with Linux pidfd support and util-linux flock/setpriv. Hardened browser
lanes additionally require nftables, Python 3.9+ with pidfd support, writable cgroup
v2 with cgroup.kill, and util-linux (setpriv, flock, unshare, mount,
setsid), plus dbus-daemon and dbus-send. Use native or portable Firefox-/Chromium-family browsers, including forks; Snap/Flatpak launchers are unsupported.
The selected interface must already have an IPv4 address and gateway. Wi-Fi
connection management stays with the host. nmcli or wpa_cli supports reconnect;
tc, curl, tcpdump, arping and iw support other toolkit operations.
Lane shell entry points support dash, ash and bash; profile control runs in Python. The browser lane disables IPv6 and confines DNS resolution. Independent nftables rules and terminal policy routes block browser fallback when its uplink fails. The lane supervisor repairs missing protection; deleting toolkit firewall tables can briefly defeat exclusive-host enforcement, so global nftables flushes are unsupported during use. Profiles retain the launching OS user's filesystem permissions. Open assigned profiles through Net Lane, and keep them closed in other browser launchers. Privileged host changes can bypass lane protection.
Cleanup and Verification
./netns-lanes/run.sh --release --all
./safe-mode/run.sh --verify
./safe-mode/run.sh --diff
./run.sh --panic
Release stops lane processes before removing protection. Emergency cleanup finds
namespace, veth, routing, firewall and cgroup fingerprints even if runtime state
was lost. Keep state until cleanup to restore original sysctl values. Browser
data is retained unless --panic --purge is explicitly requested.
An existing legacy lane must be released and recreated before hardened operation.
Kernel checks alone do not establish physical dongle behavior; verify unplug and
replug on the intended hardware. See recipes and
troubleshooting. The source archive includes the native
test harness in tests/.
License
MIT — see LICENSE.