README
¶
Dezhban
Persian dežbān (دژبان) — "gatekeeper / garrison guard."
A standalone, system-wide and cross-platform network kill switch written in Go, built for
running behind full-tunnel VPNs. It enforces with an always-on interface
guard: it lets traffic out only through the VPN tunnel, so the instant the
tunnel drops it cuts egress instantly, and it full-blocks when the VPN exit
switches to a forbidden country. On a drop it then opens a bounded, self-closing
reconnect window (default 30s) so
your VPN can redial any server with zero interaction — set
vpn.reconnectWindow: "0" for the strict zero-leak-window behavior instead.
Before any tunnel has been seen — a fresh install, or a host whose VPN was removed — it rests in standby: no rules at all, the network fully open, and the UI saying plainly that it is not protecting. It arms itself the moment a VPN connects. The postures and what each one means are in docs/modes.md; for the full story of what happens from launch to teardown, read docs/how-it-works.md.
[!WARNING] dezhban deliberately cuts network access. A bad allowlist, a wrong VPN endpoint, a crash before teardown, or running it over a remote session can lock you out of your own machine. Read docs/safety.md before running
blockfor real. The escape hatch issudo dezhban panic.
Install
macOS and Linux — one line (recommended)
curl -fsSL https://raw.githubusercontent.com/Behnam-RK/dezhban/main/scripts/install.sh | sudo bash
This installs the CLI (/usr/local/bin/dezhban), the menubar app on macOS
(/Applications/Dezhban.app), and registers the background service —
asking for your password exactly once, and verifying the download's
checksum before installing anything. It works with zero Gatekeeper
friction on macOS: curl deliberately doesn't set com.apple.quarantine on
what it downloads (that's documented Apple behavior, not a workaround — see
docs/install.md for why there's no signed .pkg instead).
After that, the everyday operations (block, unblock, switching VPNs) never ask again: the background service performs them for you over a local control socket. See docs/config.md for the security model and how to tighten it.
The installer does not start enforcement — a kill switch configured by guesswork is how you get locked out of your own machine. Two steps to finish:
sudo dezhban setup # choose your settings
sudo dezhban start # arm it
To remove everything: sudo sh /usr/local/share/dezhban/uninstall.sh.
Windows
irm https://raw.githubusercontent.com/Behnam-RK/dezhban/main/scripts/install.ps1 | iex
Run from an elevated (Administrator) PowerShell. Same checksum verification, same "registers but doesn't start enforcement" behavior.
Other ways to install
All of these, plus checksum/signature verification details, are covered in docs/install.md:
- The
.pkg— download from the Releases page andsudo installer -pkg dezhban-<version>.pkg -target /(it's unsigned, so a double-click is blocked by Gatekeeper — see docs/install.md for why). .deb/.rpm— also on the Releases page, for a package-manager-tracked install (dpkg -i/rpm -i).- Bare binaries —
dezhban-<os>-<arch>on the Releases page, for anyone scripting their own install.
Once installed, keep it current with sudo dezhban upgrade check (macOS also
gets upgrade download/upgrade apply — see docs/upgrade.md).
See docs/releasing.md for how releases are cut.
Quick start
Requires Go 1.26+.
task build # host build → ./dezhban (go-task; or: go build ./cmd/dezhban)
sudo dezhban setup # interactive wizard — build the config, no JSON by hand
dezhban validate # confirm it (--config is optional; see docs/config.md)
dezhban monitor # live IP/country/tunnel/verdict, no firewall touched
sudo dezhban run # run the daemon (root; drives the firewall)
sudo dezhban panic # always-available teardown, no daemon needed
Want the guided version, with the "will this lock me out?" checks explained? See docs/quick-start.md.
--config is optional — dezhban resolves it from $DEZHBAN_CONFIG or the system
path (dezhban config path). Tab-completion: source <(dezhban completion zsh).
The binary can also install itself as a boot-persistent service and ships an
optional macOS app (menubar + main window). Full command reference: docs/usage.md.
Postures at a glance
There is one enforcement model — the guard. What changes is the posture:
- STANDBY — no rules, network fully open, not protecting. The resting state before any tunnel has been observed. Arms itself when a VPN connects.
- GUARD — the healthy state. Only the tunnel may carry traffic off the
machine, so a drop is cut instantly (zero leak window with
vpn.reconnectWindow: "0"; by default a bounded reconnect window follows the cut so the VPN can redial). - FULL BLOCK — the VPN's exit landed in a blocked country. All user traffic is cut, but the endpoint handshake stays open so the tunnel can recover.
- SWITCH WINDOW — the one sanctioned relaxation, bounded and self-closing, from exactly two triggers: an explicit operator command, or the automatic reconnect window.
Details and rulesets: docs/modes.md.
Configuration
JSON, with durations as strings (e.g. "30s"). Sample configs live in configs/
(dezhban.example.json is fully automatic; dezhban.vpn-guard.json pins the
tunnel interface and endpoints explicitly). Full field reference, the vpn block,
and validation rules: docs/config.md.
Documentation
| Doc | What's in it |
|---|---|
| docs/quick-start.md | New here? Install → set up → verify → arm, and how to read the menubar icon. |
| docs/modes.md | Every posture and the exact ruleset it installs. |
| docs/config.md | Config field reference and sample configs. |
| docs/usage.md | CLI commands, flags, service install, the macOS app. |
| docs/architecture.md | Three-layer design and the invariants it rests on. |
| docs/safety.md | Kill-switch safety principles and teardown mechanics. |
| docs/troubleshooting.md | Lockout recovery and VPN-guard failure runbook. |
| docs/development.md | Build, cross-compile, dev loop, CI, hooks. |
| docs/releasing.md | Cutting a release, CHANGELOG discipline, unsigned macOS GUI. |
| docs/state.md | The state.json posture file. |
| docs/acceptance.md | The on-host verification checklist CI can't run. |
License
MIT © 2026 Behnam RK
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
dezhban
command
Command dezhban is a cross-platform network kill switch: it watches the machine's public IP, resolves its country, and drives the OS firewall to cut traffic when the country matches a blocklist.
|
Command dezhban is a cross-platform network kill switch: it watches the machine's public IP, resolves its country, and drives the OS firewall to cut traffic when the country matches a blocklist. |
|
internal
|
|
|
command
Package command is the daemon's ROOT control channel: a root-owned command file that the `dezhban switch`/`vpn` CLIs write and the running daemon consumes on a tick.
|
Package command is the daemon's ROOT control channel: a root-owned command file that the `dezhban switch`/`vpn` CLIs write and the running daemon consumes on a tick. |
|
config
Package config defines dezhban's runtime configuration and loading.
|
Package config defines dezhban's runtime configuration and loading. |
|
control
Package control is the daemon's live control channel: a unix socket the daemon listens on and the CLI dials, so routine posture changes (block / unblock / switch window) work without re-elevating to root on every call.
|
Package control is the daemon's live control channel: a unix socket the daemon listens on and the CLI dials, so routine posture changes (block / unblock / switch window) work without re-elevating to root on every call. |
|
decision
Package decision maps monitor readings to an enforcement verdict.
|
Package decision maps monitor readings to an enforcement verdict. |
|
firewall
Package firewall drives the OS firewall to cut and restore network egress.
|
Package firewall drives the OS firewall to cut and restore network egress. |
|
learned
Package learned persists VPN server endpoints that the daemon discovered at runtime (during a switch window, or via live socket discovery under normal guard), so a VPN that has been connected once stays reachable across restarts without the user hand-typing its server address.
|
Package learned persists VPN server endpoints that the daemon discovered at runtime (during a switch window, or via live socket discovery under normal guard), so a VPN that has been connected once stays reachable across restarts without the user hand-typing its server address. |
|
logging
Package logging builds dezhban's structured logger.
|
Package logging builds dezhban's structured logger. |
|
monitor
Package monitor resolves the machine's public IP and its country, on a polling loop, with multi-provider redundancy.
|
Package monitor resolves the machine's public IP and its country, on a polling loop, with multi-provider redundancy. |
|
netdetect
Package netdetect discovers VPN tunnel interfaces for the interface-aware guard, so operators need not hand-name them.
|
Package netdetect discovers VPN tunnel interfaces for the interface-aware guard, so operators need not hand-name them. |
|
privilege
Package privilege reports whether dezhban has the OS privileges needed to modify the firewall (root on unix, Administrator on Windows).
|
Package privilege reports whether dezhban has the OS privileges needed to modify the firewall (root on unix, Administrator on Windows). |
|
runner
Package runner ties the three layers into the live daemon: it polls the Monitor, asks the Decider for a verdict, and drives the firewall Backend — always cleaning up on exit.
|
Package runner ties the three layers into the live daemon: it polls the Monitor, asks the Decider for a verdict, and drives the firewall Backend — always cleaning up on exit. |
|
state
Package state publishes the daemon's live posture to an on-disk JSON file so out-of-process observers (the macOS menubar app, `status --json`) can read exactly what the daemon decided without running their own poller.
|
Package state publishes the daemon's live posture to an on-disk JSON file so out-of-process observers (the macOS menubar app, `status --json`) can read exactly what the daemon decided without running their own poller. |
|
svc
Package svc runs dezhban as a managed background service on each OS, using one cross-platform API (github.com/kardianos/service) that maps to launchd on macOS, systemd/upstart/sysv on Linux, and the Windows Service manager.
|
Package svc runs dezhban as a managed background service on each OS, using one cross-platform API (github.com/kardianos/service) that maps to launchd on macOS, systemd/upstart/sysv on Linux, and the Windows Service manager. |
|
update
Package update implements `dezhban upgrade`: checking GitHub for a newer release, downloading and verifying it, and — on macOS only — applying the signed .pkg and restarting into it.
|
Package update implements `dezhban upgrade`: checking GitHub for a newer release, downloading and verifying it, and — on macOS only — applying the signed .pkg and restarting into it. |
|
vpnimport
Package vpnimport extracts VPN server endpoints from common client config formats so a profile can be created without hand-copying the server address.
|
Package vpnimport extracts VPN server endpoints from common client config formats so a profile can be created without hand-copying the server address. |
|
tools
|
|
|
relsign
command
Command relsign signs a file with the dezhban release ed25519 private key.
|
Command relsign signs a file with the dezhban release ed25519 private key. |
|
taskmenu
command
taskmenu is the interactive picker behind a bare `task` on a TTY: pick a flow, answer the prompts for the vars it takes, and it execs `task <name> KEY=VAL…`.
|
taskmenu is the interactive picker behind a bare `task` on a TTY: pick a flow, answer the prompts for the vars it takes, and it execs `task <name> KEY=VAL…`. |