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. Its primary mode is 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.
As a fallback for hosts not behind a VPN, it can instead poll the machine's public IP, resolve its country, and cut traffic by destination when that country matches a blocklist — best-effort, since a poller can only react after the next poll. Both modes and how to choose 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 — the installer (recommended)
Download dezhban-<version>.pkg from the
Releases page. It installs the CLI
(/usr/local/bin/dezhban), the menubar app (/Applications/Dezhban.app), and
registers the background service — asking for your password exactly once.
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
[!NOTE] The
.pkgis unsigned (no Apple Developer certificate), so Gatekeeper blocks a double-click. Either install from the terminal —sudo installer -pkg dezhban-<version>.pkg -target /— or double-click, dismiss the warning, and approve it in System Settings → Privacy & Security → Open Anyway. On macOS 14 and earlier, right-click → Open also works.
To remove everything: sudo sh /usr/local/share/dezhban/uninstall.sh.
Other platforms
Prebuilt binaries for macOS (arm64/amd64), Linux (amd64/arm64), and Windows (amd64)
are on the same Releases page: download dezhban-<os>-<arch> (or .exe on
Windows). Dezhban-macos.app.zip is the menubar app on its own, for people who
already have the CLI. SHA256SUMS is attached to every release for verification.
[!NOTE]
Dezhban.appfrom the zip is unsigned too — right-click → Open in Finder, orxattr -dr com.apple.quarantine Dezhban.app.
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
--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.
Modes at a glance
- VPN guard (
vpn.enabled: true) — primary/recommended. Interface-aware, always on, instant cut on a drop (zero leak window withvpn.reconnectWindow: "0"; by default a bounded reconnect window follows the cut so the VPN can redial). Use it whenever you're behind a full-tunnel VPN. - Country-blocklist (
vpn.enabled: false) — fallback. Destination-aware, reactive; only meaningful when you're not tunneled. Defaults to off — a misconfigured guard can lock a host out, so VPN mode is a deliberate opt-in.
Details, rulesets, and the deciding question: docs/modes.md.
Configuration
JSON, with durations as strings (e.g. "30s"). Sample configs live in configs/
(dezhban.vpn-guard.json for the guard, dezhban.example.json for the fallback).
Full field reference, the vpn block, and validation rules:
docs/config.md.
Documentation
| Doc | What's in it |
|---|---|
| docs/modes.md | The two enforcement modes and which one you want. |
| 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. |
|
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
|
|
|
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…`. |