Building Gatehouse: A REST API for OpenBSD's PF Firewall

The API listens on 127.0.0.1:8080 — localhost only. OpenBSD’s built-in relayd handles TLS termination and reverse proxying:

TLS without baking certificate handling into the application, WebSocket proxying for live monitoring, and automatic X-Forwarded-For headers for audit logging.

Gatehouse runs as the _gatehouse system user via OpenBSD’s rc.d framework:

The _gatehouse user has doas permissions for exactly the commands it needs — pfctl, tcpdump, rcctl, crontab, and make in /etc/pf.d. Nothing else.

The initial implementation stored users in a users.json file with bcrypt-hashed passwords:

A manage_users.py CLI handled user CRUD. Simple, portable, but it meant maintaining a separate user database alongside the system’s own accounts.

The current version uses OpenBSD’s auth_userokay(3) — the same function that validates passwords for SSH, console login, and every other authentication on the system. One user database, one password policy, one source of truth.

The ctypes FFI call is straightforward — auth_userokay takes a username, optional style/type, and a mutable password buffer. It returns non-zero on success and zeroes the password buffer for security. No subprocess, no shelling out, just a direct C library call.

Roles map to OpenBSD system groups:

Adding a user to the appropriate group grants API access at that level. Standard Unix group management, no application-level user administration needed.

After authentication, clients receive a JWT token valid for 60 minutes:

Every subsequent request includes Authorization: Bearer <token>. The middleware validates the token, extracts the role, and enforces minimum role requirements per endpoint.

Two layers of rate limiting protect the login endpoint:

Both use in-memory sliding windows with automatic cleanup. No external dependencies, no Redis, no database — just timestamp lists in a dictionary.

The "big red buttons" — PF control operations that affect the entire firewall:

load-safe is the panic button. It loads a minimal ruleset that allows SSH from internal networks and basic outbound — enough to maintain access while you fix whatever went wrong.

Read-only queries against the running PF state:

The anchors endpoint queries all 16 configured anchors and reports which have rules loaded. A single-call dashboard of what features are active.

This is where Gatehouse really shines — toggling PF features without editing config files or remembering pfctl syntax:

Sixteen features are mapped to their anchor names and config files:

The update endpoint runs IP resolution scripts — for example, resolving YouTube’s current IP ranges via DNS and updating the PF table.

Direct manipulation of PF tables — the data structures that hold IP lists:

Blackhole blocking:

FTSO RPC whitelist (dual-table system):

The dual-table pattern — permanent (file-backed) plus temporary (memory-only) — appears throughout the API. Permanent entries survive PF reloads because they’re written to .ips files that PF reads on startup. Temporary entries exist only in kernel memory and vanish on reload, making them perfect for testing.

Four independent device blocking modes, each with identical endpoint structure:

Types: full-block, services-block, youtube-24x7, youtube-sched

Every add operation validates the IP address: it must be RFC1918 (private), properly formatted, and not a gateway IP. You can’t accidentally block the router.

The kill-states endpoint is crucial — adding an IP to a block table doesn’t affect existing connections. You need to explicitly kill the connection states for the block to take immediate effect.

Parse /var/log/pflog for traffic analysis:

These endpoints run tcpdump -n -e -ttt -r /var/log/pflog and parse the output. Not the fastest approach for large logs, but it works without any additional infrastructure and the pflog binary format ensures accurate packet data.

Five managed cron jobs:

Crontab management uses marker comments (# gatehouse: device-block) to identify managed entries. The API reads the crontab, adds/removes marked lines, and writes it back. No external cron libraries — just crontab -l and crontab -.

The base system includes everything you need for a secure API deployment: relayd for TLS termination, rc.d for service management, doas for privilege escalation, crontab for scheduling, and auth_userokay for authentication. No third-party packages needed for infrastructure.

PF anchors — named rule containers that can be loaded and unloaded at runtime — map perfectly to REST endpoints. POST /anchors/youtube/enable loads rules into the youtube-block anchor. POST /anchors/youtube/disable clears it. The main ruleset never changes, so there’s no risk of a syntax error taking down the firewall.

The permanent + temporary table pattern appeared organically. When testing device blocking, I wanted to add an IP temporarily, verify it worked, then either make it permanent or remove it. File-backed tables persist across reloads; memory-only tables don’t. Both are first-class concepts in the API.

The first version of device blocking added IPs to tables but didn’t kill existing connection states. Blocked devices stayed connected for minutes until their TCP sessions naturally expired. Adding kill-states endpoints made blocks take effect immediately.

Ideally, pfctl would have a --json flag. It doesn’t. Parsing text output with regex is fragile — a format change in a future OpenBSD release could break things. But it works today, the output formats have been stable for years, and the alternative (writing a C program that uses PF’s ioctl interface) is dramatically more complex for a home network API.