Firewall Agents

When Beezifi blocks a request, it can also block that IP address in the operating-system firewall of your servers. A small agent on each server receives those blocks and applies them — to UFW on Linux or to Windows Defender Firewall on Windows. Installing an agent is optional; the decision API works without one.

Download How it works Install Network access Verify Security model Operate & remove Troubleshooting Developer docs

Download

🐧

Linux — UFW agent

Ubuntu, Debian, RHEL/Fedora and other systemd distributions with ufw. Node.js 22+. Installs the beezifi-ufw-tool systemd service.

Installer (.sh) Package (.tar.gz)

🪟

Windows — Windows Firewall agent

Windows 10 or Windows Server 2016 and newer, Windows Defender Firewall. Node.js 22+. Installs the BeezifiFirewallAgent Windows service.

Installer (.ps1) Package (.zip)

SHA-256 checksums are listed under each download and in SHA256SUMS. The installer downloads the package itself; you only need the installer.

How it works

1. Your app asksYour backend calls /api/v1/check for a request.

2. A rule blocks itBeezifi returns BLOCK to your app.

3. The block is pushedWithin seconds, Beezifi sends a deny for that IP to every agent linked to the same API key.

4. The OS firewall drops itThe agent adds the deny rule, so repeat traffic from that IP never reaches your app.

Which servers get the block? Each agent is linked to one of your API keys. Blocks made with that key are pushed to every server linked to it.
Which IPs are never pushed? Private, loopback and link-local addresses (for example 10.x, 192.168.x, 127.0.0.1, fe80::/10) are never sent, so you can't lock out your own network.
Can I manage rules by hand? Yes. The Firewall page in the dashboard lists the agent's rules on each server, and lets you add and remove them.

Install

Register the server in the dashboard. Sign in, open Firewall → + Add Target and enter: a description (e.g. "web-01"), the URL the platform will use to reach the agent (e.g. https://web-01.example.com:4001 — see Network access), and the API key whose blocks should be pushed to it. When you save, the dashboard shows the server's agent secret (bza_…) once, together with ready-to-paste install commands for Linux and Windows. Copy it now — it is stored encrypted and can't be shown again (you can generate a new one at any time).

Run the installer on the server with that secret.

As root (or with sudo):

curl -fsSL https://your-beezifi-host/downloads/install-ufw-tool.sh -o install-ufw-tool.sh
chmod +x install-ufw-tool.sh
sudo ./install-ufw-tool.sh --host https://your-beezifi-host --agent-secret bza_your_agent_secret

The installer checks for Node.js 22+ and ufw, then:

creates a system user beezifi-agent with no login shell;
installs the agent to /opt/beezifi-ufw-tool (owned by root, read-only to the service) with its secret in .env (readable only by root and the service user);
adds a sudoers entry that lets the service run only ufw as root;
registers and starts the beezifi-ufw-tool systemd service (starts on boot, restarts on failure).

Enable UFW first if it isn't already: sudo ufw allow OpenSSH && sudo ufw enable. Allow SSH before enabling, or you can lock yourself out.

Installer options

Option	What it does
`--host <url>`	Your Beezifi address (required).
`--agent-secret <bza_…>`	The server's agent secret. Prompted for if omitted.
`--port <n>`	Listening port (default 4001).
`--bind <addr>`	Listening address (default `127.0.0.1`). Anything else requires TLS.
`--ssl-cert`, `--ssl-key`	Certificate chain and private key (e.g. Let's Encrypt `fullchain.pem` / `privkey.pem`).
`--allow-from <ip,ip>`	Adds a UFW rule allowing the agent port only from these addresses (the platform's).
`--allow-rules`	Also let the platform add allow rules. Off by default.
`--pm2`, `--no-run`	Run under pm2 instead of systemd (non-root installs) / install without starting.

In PowerShell run as Administrator:

Invoke-WebRequest -UseBasicParsing https://your-beezifi-host/downloads/install-windows-firewall-tool.ps1 -OutFile install-windows-firewall-tool.ps1
.\install-windows-firewall-tool.ps1 -PlatformUrl https://your-beezifi-host -AgentSecret bza_your_agent_secret

If script execution is blocked, run Set-ExecutionPolicy -Scope Process Bypass in that window first. The installer checks for Node.js 22+ (winget install OpenJS.NodeJS.LTS), then:

installs the agent to C:\Program Files\Beezifi\WindowsFirewallTool with its secret in .env (readable only by SYSTEM and Administrators);
downloads the WinSW service wrapper and verifies its SHA-256 before use;
registers and starts the BeezifiFirewallAgent service (automatic start, restart on failure, rotating logs).

Installer parameters

Parameter	What it does
`-PlatformUrl <url>`	Your Beezifi address (required).
`-AgentSecret <bza_…>`	The server's agent secret. Prompted for if omitted.
`-Port <n>`	Listening port (default 4001).
`-BindHost <addr>`	Listening address (default `127.0.0.1`). Anything else requires a certificate.
`-PfxPath`, `-PfxPassphrase`	Certificate as a PFX/P12 file (e.g. from win-acme).
`-AllowFrom <ip>,<ip>`	Adds an inbound rule allowing the agent port only from these addresses.
`-AllowRules`	Also let the platform add allow rules. Off by default.
`-InstallDir`, `-NoStart`	Different install folder / install without starting.

Let the platform reach the agent — next section.
Verify — see Verify.

Re-running an installer upgrades the agent in place and keeps its .env. Options you don't pass are reset to their defaults, so repeat the ones you used (port, address, certificate).

Network access

The platform connects to the agent over HTTPS. By default the agent listens on 127.0.0.1 only, which the platform can't reach, and it refuses to listen on the network without TLS. Choose one setup:

A. Agent with its own certificate

Listen on all interfaces with a certificate and allow the port only from the platform. Target URL: https://<server-name>:4001.

B. Behind your reverse proxy

Keep the agent on 127.0.0.1:4001 and publish it through nginx, Caddy or IIS with TLS, restricted to the platform's addresses. Target URL: your proxy's HTTPS URL.

Option A on Linux (Let's Encrypt)

sudo certbot certonly --standalone -d web-01.example.com
sudo ./install-ufw-tool.sh --host https://your-beezifi-host --agent-secret bza_your_agent_secret \
  --bind 0.0.0.0 \
  --ssl-cert /etc/letsencrypt/live/web-01.example.com/fullchain.pem \
  --ssl-key  /etc/letsencrypt/live/web-01.example.com/privkey.pem \
  --allow-from PLATFORM_IP

systemd passes the root-only key to the service. When certbot is installed, the installer also adds a renewal hook that restarts the agent after each certificate renewal.

Option A on Windows

.\install-windows-firewall-tool.ps1 -PlatformUrl https://your-beezifi-host -AgentSecret bza_your_agent_secret `
  -BindHost 0.0.0.0 -PfxPath C:\certs\web-01.pfx -PfxPassphrase 'pfx-password' -AllowFrom PLATFORM_IP

Replace PLATFORM_IP with the address(es) the Beezifi platform connects from — your Beezifi contact can confirm them. If a cloud security group or network firewall sits in front of the server, open the port there too, for the same addresses only.

Verify

On the server, check the service: systemctl status beezifi-ufw-tool (Linux) or Get-Service BeezifiFirewallAgent (Windows).
In the dashboard, open Firewall and select the server. It should connect and show its status and the agent's rules (none yet).
Click + Add Rule, choose Deny and a test source such as 192.0.2.10. The rule appears in the list and on the server (sudo ufw status or Get-NetFirewallRule -Group 'Beezifi Security'). Delete it again from the dashboard.
Optional end-to-end test: add an IP blocklist rule for a test IP on the linked API key, send a check for that IP from the API Tester, and confirm the deny appears on the server within a few seconds.

Security model

Deny-only by default

The agent adds deny/block rules. It refuses allow rules unless you installed with --allow-rules / -AllowRules, so it can't open a port.

Only its own rules

Linux: rules are tagged beezifi: and only those can be deleted. Windows: rules live in the Beezifi Security group, and nothing outside it is ever listed or deleted.

Per-server secret

Each server has its own random secret, stored by Beezifi only encrypted (AES-256-GCM). It is unrelated to your API keys, so rotating a key never breaks the firewall link.

TLS or loopback

The agent will not listen beyond 127.0.0.1 without a certificate, so the secret never crosses the network in plain text.

Least privilege on Linux

Runs as beezifi-agent; the only command it may run as root is ufw. Commands are run without a shell and every field is validated.

Windows service account

Runs as LocalSystem, which Windows requires to change firewall rules. Input reaches PowerShell only as data, never as script text, and catch-all sources (0.0.0.0/0) are refused.

Operate & remove

Task	Linux	Windows
Status	`systemctl status beezifi-ufw-tool`	`Get-Service BeezifiFirewallAgent`
Logs	`journalctl -u beezifi-ufw-tool -f`	`…\WindowsFirewallTool\BeezifiFirewallAgent.out.log` / `.err.log`
Restart (after editing `.env`)	`sudo systemctl restart beezifi-ufw-tool`	`Restart-Service BeezifiFirewallAgent`
See the agent's rules	`sudo ufw status numbered \| grep beezifi:`	`Get-NetFirewallRule -Group 'Beezifi Security'`
Rotate the secret	Dashboard → Firewall → select server → Regenerate Agent Secret, then set `BEEZIFI_AGENT_SECRETS` in `.env` and restart. To avoid any gap, list the old and new secrets comma-separated until the new one is in use.
Upgrade	Re-run the installer	Re-run the installer
Uninstall	`sudo /opt/beezifi-ufw-tool/uninstall.sh --remove-rules`	`& 'C:\Program Files\Beezifi\WindowsFirewallTool\uninstall.ps1' -RemoveRules`

Without --remove-rules / -RemoveRules, the blocks the agent added stay in place after it's removed. Your own firewall rules are never touched either way.

Troubleshooting

Symptom	Cause and fix
Dashboard: "connect ECONNREFUSED" or timeout	The platform can't reach the agent. Check the target URL, that the agent listens on the network with TLS (or behind your proxy), and that the port is open to the platform's addresses in UFW / Windows Firewall and any cloud firewall.
Dashboard: "Unauthorized"	The secret on the server doesn't match. Regenerate it in the dashboard, update `BEEZIFI_AGENT_SECRETS` in `.env`, restart the service.
Dashboard: "does not permit allow rules"	Expected: the agent is deny-only. Reinstall with `--allow-rules` / `-AllowRules` only if you need allow rules.
Linux: rules list is empty but rules were added	UFW is inactive. Run `sudo ufw allow OpenSSH && sudo ufw enable`.
Linux: "sudo: a password is required"	The sudoers entry is missing (installed without root?). Re-run the installer with `sudo`.
Service won't start: "without TLS"	It's set to listen beyond loopback without a certificate. Add the certificate options or bind to `127.0.0.1`.
Windows: "running scripts is disabled"	Run `Set-ExecutionPolicy -Scope Process Bypass` in the same PowerShell window, then the installer again.
Blocks don't arrive automatically	Check the server is linked to the API key that made the decision (Edit Target), and that the blocked IP is public — private addresses are never pushed.

Agent API details, rule formats and integration examples are in the developer documentation.