Port Guard
os-portguard · Protection
Blocks a device by its MAC address at the firewall - the first part of layer 2 rules for the firewall's ports.
In the menu
- With os-xgs-npu installed: XGS: Port Guard
- Without os-xgs-npu: Firewall: Port Guard
Blocked devices are a list of MAC addresses, each a whole address or its first three to five bytes - every device of one maker. The plugin keeps one MAC alias, portguard_blocked, from the list; OPNsense resolves it into the IPv4 and IPv6 addresses its ARP and NDP tables, or its host discovery, have seen each device use, and keeps them current.
The rules are registered by the plugin at every filter reload: nothing from a listed device passes the firewall, on any interface, and nothing reaches it through the firewall. They come before the interface rules, the anti-lockout rule included, and are never added to the owner's own rules. Nothing is blocked until a device is listed and applied.
OPNsense lets a plugin register no Ethernet rules, so two devices behind the same switch still reach each other - their frames never come to the firewall - and a frame type cannot be matched yet. On a Sophos XGS, rules kept in the switch of the front ports, so that a blocked device is stopped at the port, are the aim; they are not written yet.
Features
-
By address or by maker
A whole MAC address, or its first three to five bytes for every device of one maker.
-
One MAC alias
portguard_blocked, which OPNsense resolves into the IPv4 and IPv6 addresses each device has used, and keeps current.
-
Rules before the others
Registered at every filter reload, on every interface, before the interface rules and the anti-lockout rule; never written into the owner's rules.
-
Devices seen
The devices the firewall has seen in the last day, with their interface, address and maker, each a click from being blocked; the page warns first that it may be the device in use.
-
Summary cards
How many listed devices are present, how many addresses pf blocks now, the packets blocked and the devices seen.
Install and update
From os-xgs-npu's release after 0.1.0-alpha.7.1, XGS: Updates lists it on its Plugins tab - an installed copy is updated there by hand, and a missing one installed there - and the ready-made images built from that release carry it; until then it is installed and updated as below. No cron entry runs the update. To install it on an XGS appliance or on any other OPNsense, as root: from a checkout of the repository with sh install/install.sh, which puts the page under XGS with os-xgs-npu and under Firewall without it, and keeps the settings when run again; or from the release's package, os-portguard-1.0.0.pkg, checked against SHA256SUMS and added with pkg. A copy installed this way is updated by its own self-update.py. Removing the plugin takes its rules out of pf; the portguard_blocked alias stays in Firewall: Aliases, blocking nothing. It is not in the OPNsense plugin repository.
Limits, and what is not tested yet
- Writing the alias from the page (apply.php, which saves config.xml).
- A device blocked through it.
- Not written yet: blocking between two devices behind the same switch, a match by frame type (EtherType), and rules kept in a Sophos XGS's switch.
- A device that changes its MAC address, such as with private Wi-Fi addresses, is blocked only under the one listed.
- The package, built by tools/make-package.sh and added with pkg.
- An install on OPNsense without os-xgs-npu.
- An update through the Plugins tab or self-update.py: 1.0.0 is the first release, so none has been ahead of an installed copy.
Repository
First release: 2026-10-25
The discussion of this page is held in the project's GitHub Discussions. Showing it here loads giscus from giscus.app and GitHub, and writing in it needs a GitHub account - what that means.