LANHaven

Know what's happening on your network. Control what gets through.

A lightweight, open-source network firewall and traffic monitor for macOS and Linux.
No cloud. No subscriptions. Everything runs locally using your OS's built-in firewall.

---

Why LANHaven?

Every device on your network is constantly making connections — software updates, telemetry, analytics, cloud syncs, and sometimes things you didn't ask for. Most people have no visibility into this traffic, and the built-in OS firewalls (pf on macOS, nftables/iptables on Linux) are powerful but hard to use.

LANHaven gives you:

• Full visibility — See every inbound and outbound connection in real time, including the process name, destination IP/hostname, protocol, and bytes transferred.
• Simple control — Add firewall rules from a clean web UI instead of editing config files or memorising pfctl commands.
• Zero dependencies on external services — LANHaven uses your OS's native packet filter directly. No kernel extensions, no third-party drivers, no data leaves your machine.
• Lightweight — A single ~10 MB binary, minimal CPU overhead, embedded web UI. Runs as a system service and stays out of your way.

---

Features

Feature	Description
Live Traffic Monitor	Real-time dashboard showing every connection: destination IP/hostname, protocol, bytes sent/received, and the originating process.
Firewall Rules	Add, edit, reorder, and toggle rules per IP, port, and protocol. Rules are applied directly to the OS firewall.
System Rules View	Read-only view of all firewall rules active on the OS — including rules from other applications — so you have complete visibility.
Open Ports Dashboard	See every listening port on your machine, which process owns it, and whether it's exposed to the network.
Native Firewall Integration	Uses pf on macOS and nftables/iptables on Linux directly. No kernel extensions or third-party drivers.
System Tray App	Quick-access icon to toggle filtering or open the dashboard without a terminal.
Light & Dark Themes	Full light and dark theme support, with a system-preference option.
Offline & Private	Everything runs on 127.0.0.1. No telemetry, no cloud, no accounts.

---

Quick Start

Prerequisites

Platform	Requirement
macOS	Xcode Command Line Tools (xcode-select --install)
Linux	libpcap-dev (apt install libpcap-dev or yum install libpcap-devel)
Both	Go >= 1.22, Node.js >= 18

Build and install

git clone https://github.com/duladissa/lanhaven.git
cd lanhaven
make all              # builds frontend + both binaries
sudo make install     # installs as a system service

Open the dashboard

lanhaven              # launches tray icon and opens browser

Or navigate to http://localhost:7777 directly.

Verify

# macOS
launchctl list | grep lanhaven
pfctl -a lanhaven -sr

# Linux
systemctl status lanhavend
sudo nft list table inet lanhaven

---

How It Works

┌──────────────────────────────────────────┐
│  Browser UI (React + Tailwind)           │
│  http://localhost:7777                   │
└───────────────┬──────────────────────────┘
                │ REST API + WebSocket
┌───────────────▼──────────────────────────┐
│  lanhavend  (runs as root)               │
│  ├── Firewall: pf (macOS) / nftables     │
│  ├── Packet capture: libpcap             │
│  ├── Process resolver: lsof / /proc      │
│  └── Storage: BoltDB                     │
└──────────────────────────────────────────┘
┌──────────────────────────────────────────┐
│  lanhaven  (runs as user)                │
│  System tray icon + browser launcher     │
└──────────────────────────────────────────┘

LANHaven uses only built-in OS capabilities:

Layer	macOS	Linux
Firewall	pf via pfctl (anchor-based)	nftables via nft (iptables fallback)
Packet capture	libpcap (ships with Xcode CLT)	libpcap
Process resolution	lsof -i	/proc/net/tcp + /proc/$pid/fd

No kernel extensions. No third-party firewall drivers. Everything is managed through the same tools your OS already provides — LANHaven just gives them a usable interface.

---

Development

# Terminal 1 — daemon (dev mode)
make dev-daemon

# Terminal 2 — frontend (Vite dev server with hot-reload)
make dev-web

Open http://localhost:5173 — Vite proxies API and WebSocket calls to the daemon on port 7777.

In dev mode the daemon uses ~/.lanhaven/lanhaven.db, skips firewall writes, and does not require root.

---

Build Targets

Target	Description
make all	Build frontend + both binaries
make web	Build React frontend only
make build	Build Go binaries only
make dev-daemon	Run daemon in dev mode
make dev-web	Start Vite dev server with API proxy
make test	Run all tests with race detection
make install	Build + install as system service (requires root)
make uninstall	Remove system service and binaries
make clean	Remove build artifacts

---

API

The daemon serves a REST API on 127.0.0.1:7777.

Endpoint	Method	Description
/api/v1/health	GET	Daemon status, version, uptime
/api/v1/rules	GET, POST	List or create firewall rules
/api/v1/rules/{id}	GET, PUT, PATCH, DELETE	Read, update, or delete a rule
/api/v1/rules/reorder	POST	Batch update rule priorities
/api/v1/rules/apply	POST	Push rules to OS firewall
/api/v1/rules/system	GET	Read-only view of all OS firewall rules
/api/v1/settings	GET, PUT	Read or update settings
/api/v1/settings/filtering	PUT	Toggle master filtering switch
/api/v1/traffic/snapshot	GET	Point-in-time traffic snapshot
/api/v1/ports	GET	Listening ports on this machine
/api/v1/process/{pid}	GET	Process details by PID
/ws	WebSocket	Live traffic updates (every 1s)

---

File Locations

Path	Description
/etc/lanhaven/lanhaven.db	Database (rules + settings)
~/.lanhaven/lanhaven.db	Database in dev mode
/etc/pf.anchors/lanhaven	macOS pf anchor rules
/Library/LaunchDaemons/com.lanhaven.daemon.plist	macOS LaunchDaemon
/etc/systemd/system/lanhavend.service	Linux systemd service

---

Security

• Binds to 127.0.0.1 only — never accessible from the network.
• CORS restricted to localhost origins.
• On Linux, systemd uses AmbientCapabilities to limit privilege scope.
• No data is transmitted outside the local machine.
• Database files are created with 0600 permissions.

---

Uninstalling

sudo make uninstall

Stops the service, removes binaries, and cleans up config files.

---

License

MIT — see LICENSE.

---

Built with the help of Claude Code AI