go-firewall/README.md

go-firewall

A Go module that presents a single, uniform interface over the many firewall managers found across operating systems. You describe rules with one platform‑agnostic Rule struct and the module translates them to whatever backend is actually running on the host.

Reference documentation: https://pkg.go.dev/github.com/grmrgecko/go-firewall

import "github.com/grmrgecko/go-firewall"

Supported backends

Platform	Backends
Linux	firewalld → ufw → CSF → APF → iptables → nftables
macOS	pf (Packet Filter)
FreeBSD	pf (Packet Filter)
Windows	Windows Filtering Platform (WFP)

Usage

package main

import (
	"context"
	"log"

	"github.com/grmrgecko/go-firewall"
)

func main() {
	ctx := context.Background()

	// Detect and connect to the host's firewall. The rule prefix tags/namespaces
	// rules this module creates.
	mgr, err := firewall.NewManager(ctx, "myapp")
	if err != nil {
		log.Fatal(err)
	}
	defer mgr.Close(ctx)

	// Resolve the zone for an interface (empty for backends without zones).
	zone, err := mgr.GetZone(ctx, "eth0")
	if err != nil {
		log.Fatal(err)
	}

	// Allow inbound TCP 443 from a subnet, logged and rate-limited.
	rule := &firewall.Rule{
		Family:    firewall.IPv4,
		Source:    "192.168.0.0/24",
		Port:      443,
		Proto:     firewall.TCP,
		Action:    firewall.Accept,
		Log:       true,
		LogPrefix: "https",
		RateLimit: &firewall.RateLimit{Rate: 20, Unit: firewall.PerSecond, Burst: 10},
	}

	if err := mgr.AddRule(ctx, zone, rule); err != nil {
		log.Fatal(err)
	}

	// Forward inbound TCP 8080 to an internal host (a NAT rule).
	nat := &firewall.NATRule{
		Kind:      firewall.DNAT,
		Family:    firewall.IPv4,
		Proto:     firewall.TCP,
		Port:      8080,
		ToAddress: "10.0.0.5",
		ToPort:    80,
	}
	if err := mgr.AddNATRule(ctx, zone, nat); err != nil {
		log.Fatal(err)
	}

	// Some backends stage changes; Reload activates them (a no-op where
	// changes apply immediately).
	if err := mgr.Reload(ctx); err != nil {
		log.Fatal(err)
	}
}

CLI

cmd/go-firewall is a unified firewall management CLI and implementation demo for the library. It auto-detects the host's active backend and exposes the same surface across all of them. Build it from the repo root:

make cli                  # builds ./build/go-firewall
make install              # installs into $GOBIN

Managing rules needs appropriate privileges (root/Administrator), and the CLI never modifies the host unless you run a mutating subcommand.

go-firewall status                                    # backend + capabilities
go-firewall rule list                                 # all filter rules (PREFIX column flags ours)
go-firewall rule add --proto tcp --port 443 --source 192.168.0.0/24 --log
go-firewall rule add --proto tcp --ports 80,443,1000-2000 --comment "web"
go-firewall rule remove --proto tcp --port 443
go-firewall rule insert 1 --proto tcp --port 22       # 1-based position
go-firewall nat add --kind dnat --proto tcp --port 8080 --to-address 10.0.0.5 --to-port 80
go-firewall nat insert 1 --kind dnat --proto tcp --port 8080 --to-address 10.0.0.5 --to-port 80
go-firewall nat add --kind masquerade
go-firewall policy get
go-firewall policy set --input drop --forward drop
go-firewall set create blocklist --family ipv4 --type hash:net
go-firewall set add-entry blocklist 203.0.113.0/24
go-firewall set show blocklist                        # metadata + every entry
go-firewall backup -o snapshot.json                   # portable JSON snapshot (rules, NAT, policy, sets)
go-firewall restore -f snapshot.json                  # replay the snapshot
go-firewall zone eth0
go-firewall reload
go-firewall install-completions                       # bash/zsh/fish completion

Global flags: --prefix (rule namespace; default go_firewall), --no-reload (skip the automatic reload after a mutation), -j/--json (machine-readable output — list, status, and a {"status":...} object on mutations), --version. A rule's flags are identical across add, remove, insert and move, so the flag set that creates a rule is also its match key for removal. Run go-firewall <command> --help for the full flag reference.

The Rule type

Field	Meaning
Direction	DirInput (default), DirOutput, DirForward, or DirAny — the input, output, forward (routing) chain, or both input and output. See Capabilities().Forward and the multi-state note below.
Priority	Rule priority, where the backend supports it (e.g. firewalld rich rules).
Family	FamilyAny, IPv4, or IPv6.
Source	Source address/CIDR. Prefix with ! to negate, where supported.
Destination	Destination address/CIDR. Prefix with ! to negate, where supported.
Port	Single destination port. A non-zero port requires a port-carrying proto (TCP, UDP, TCPUDP, SCTP).
Ports	Destination port list/ranges ([]PortRange). Overrides Port when non-empty.
Proto	ProtocolAny, TCP, UDP, TCPUDP, ICMP, ICMPv6, SCTP, GRE, ESP, or AH. TCPUDP matches both transports; ProtocolAny matches every IP protocol and cannot carry a port.
ICMPType	Optional single ICMP type for an ICMP/ICMPv6 rule (*uint8, nil = any type).
State	Connection-tracking states to match, OR-combined (e.g. StateEstablished|StateRelated).
InInterface	Inbound interface to match. Empty means any interface. A forward rule may match this alongside OutInterface.
OutInterface	Outbound interface to match. Empty means any interface. A forward rule may match this alongside InInterface.
Action	Accept, Reject, or Drop.
Log	Log each matched packet before applying Action.
LogPrefix	Optional label on the log line (not all backends carry a prefix; pf ignores it).
RateLimit	*RateLimit (Rate/Unit/Burst) — cap the packet rate the rule matches. nil = unlimited.
ConnLimit	*ConnLimit (Count/PerSource) — cap concurrent connections. nil = unlimited.
Packets	Per-rule packet counter, populated by GetRules on backends that read them (nftables, iptables, pf). Zero elsewhere and ignored when adding a rule.
Bytes	Per-rule byte counter, populated alongside Packets. Not part of rule identity.
Comment	Optional human-readable label carried where the backend can store one. Informational: not part of rule identity, ignored where unsupported. See Capabilities().Comments.
HasPrefix	Informational flag reporting whether the rule carries the configured prefix.

Capabilities().Output reports whether a backend distinguishes input from output (firewalld, for example, does not), and Capabilities().Forward reports whether it can express a forward-chain (routing) rule. A DirForward rule on a backend without forward support is rejected with ErrUnsupportedForward.

Multi-state rules and coverage

Three values each describe a rule spanning both values of one axis:

• FamilyAny — both IPv4 and IPv6.
• TCPUDP — both TCP and UDP; it carries a port just as TCP or UDP does. It is not ProtocolAny, which matches every IP protocol (ICMP, GRE, ESP, …).
• DirAny — both the input and output directions (never forward). A DirAny rule is authored in the inbound frame, and its outbound half is the role swap: Source↔Destination, source↔destination ports, and InInterface↔OutInterface. So DirAny with Source: X matches inbound traffic from X and outbound traffic to X.

Whether such a rule becomes one object in the firewall or several depends entirely on the backend's own model:

• On add, the rule is split only on the axes the backend cannot express. nftables stores a FamilyAny + TCPUDP rule as a single row; iptables must write a line per family, per transport and per chain, so a rule spanning all three axes becomes eight lines.
• On read, GetRules reports the firewall's actual rows. It reports a multi-state value only for an entry that genuinely carries both values and never fabricates one by pairing up separately-stored rows, so that same rule reads back as one rule from nftables and as eight from iptables.
• On remove, a target clears every row it covers. Where a stored row covers more than the target, the backend deletes it and re-adds the remainder in its place so the untargeted coverage survives; where its model cannot express the remainder, it returns ErrUnsupported rather than over-removing.
• Where an axis does not exist at all — Capabilities().Output is false, as on firewalld — a DirAny rule degrades to its input half (DirInput, same fields) rather than being rejected.

Because the read-back shape is backend-specific, a caller cannot check for a rule with ==. Covers and CoveredBy express the relation directly, and are the supported way to test a multi-state rule against what the firewall actually holds:

// Does this one rule contain that one?
want := &fw.Rule{Family: fw.FamilyAny, Proto: fw.TCPUDP, Direction: fw.DirAny, Port: 53, Action: fw.Accept}
want.Covers(&fw.Rule{Family: fw.IPv4, Proto: fw.UDP, Direction: fw.DirInput, Port: 53, Action: fw.Accept}) // true

// Is this rule fully present across a set — even if no single rule contains it?
existing, _ := mgr.GetRules(ctx, "")
if !want.CoveredBy(existing) {
    _ = mgr.AddRule(ctx, "", want)
}

Covers is asymmetric: a TCPUDP rule covers its TCP half, never the reverse. CoveredBy is its set-valued inverse — it expands the receiver across all three axes and requires every resulting cell to be covered by some rule in the set. That is what makes it work against a fan-out backend, where no single stored row covers the rule but the rows together do, and why a rule spanning both transports is not reported present when only its TCP half is. NATRule.Covers and NATRule.CoveredBy mirror them over family, the only axis a NAT rule spans. Sync compares this way, which is why it stays a no-op against its own output whichever representation the backend chose.

NAT (port forwarding and masquerade)

NAT rules are managed separately from filter rules through AddNATRule/RemoveNATRule/GetNATRules, using the NATRule type.

Field	Meaning
Kind	DNAT, Redirect, SNAT, or Masquerade.
Family	FamilyAny, IPv4, or IPv6.
Proto	Protocol to match (TCP, UDP, etc.).
Port	Matched destination port (Ports for a list/range). Requires a tcp/udp protocol.
ToAddress	Rewrite target address: new destination for DNAT, new source for SNAT.
ToPort	Rewrite target port (DNAT/Redirect). Unused for SNAT/Masquerade.
Interface	Inbound interface for DNAT/Redirect; outbound for SNAT/Masquerade.
HasPrefix	Informational flag, same semantics as Rule.HasPrefix.

DNAT forwards inbound traffic to ToAddress:ToPort. Redirect sends matching traffic to a local ToPort. SNAT rewrites the source to a fixed address, and Masquerade uses the outgoing interface address. Backends that cannot express NAT return ErrUnsupportedNAT.

Capabilities

mgr.Capabilities() returns a Capabilities struct advertising which features the active backend can express, so a caller can branch before trial-and-error:

caps := mgr.Capabilities()
if !caps.NAT {
    log.Println("this backend cannot do NAT")
}
if caps.RuleCounters {
    // rules read back will carry Packets/Bytes
}

Every boolean corresponds to a Rule/NATRule field or an interface method. A false field means the corresponding operation returns an unsupported error, except RuleCounters and Comments, where it means GetRules reports the value empty. Features every backend supports are not advertised as booleans. The matrix below documents each backend's coverage, booleans and unconditional features alike.

Feature	firewalld	ufw	CSF	APF	iptables	nftables	pf	WFP
Forward rules	no	yes	yes	yes	yes	yes	no	no
IPv6	yes	yes	yes	yes	yes	yes	yes	yes
ICMP	yes	yes	yes	yes	yes	yes	yes	yes
ICMP type	yes	yes	yes	yes	yes	yes	yes	yes
SCTP/GRE/ESP/AH	yes	yes	yes	yes	yes	yes	yes	partial (no SCTP port)
Comment	no	yes	yes	yes	yes	yes	yes	yes
Port range	yes	yes	yes	yes	yes	yes	yes	yes
Port list	no	yes	yes	yes	yes	yes	yes	yes
Source port	partial (not with a destination port)	yes	yes	yes	yes	yes	yes	yes
Connection state	no	yes	yes	yes	yes	yes	no	no
Interface match	no	yes	yes	yes	yes	yes	yes	no
Logging	yes	yes	yes	yes	yes	yes	partial (no prefix)	no
Rate limit	yes	yes	yes	yes	yes	yes	partial (per-source)	no
Connection limit	no	yes	yes	yes	yes	yes	partial (per-source)	no
NAT	partial (forward-port and masquerade only)	yes	yes	yes	yes	yes	partial (no redirect)	no

A yes means the feature is fully expressible, whatever route the backend takes to get there: firewalld reaches several through a rich rule, ufw through its route ruleset, and CSF and APF write the shapes their own config files cannot hold through their managed pre-hook. A partial cell means the backend can only express the narrowed form named beside it. Two of the no cells have a backend-specific reason: firewalld binds interfaces to zones rather than matching them per rule, and pf keeps state on a pass rule automatically but exposes no equivalent of the connection-state match this model carries.

Capabilities().DenyActionFromConfig (true for CSF and APF) flags a backend whose native deny store carries no per-entry action: the tool applies the action its own config names (csf.conf DROP, conf.apf ALL_STOP), so a deny added with the config's action is stored natively, one with a differing action is expressed through the backend's pre-hook, and RemoveRule clears a native deny entry whatever action the removal target names.

The IPv6 row above is the one capability resolved per host rather than per backend, and it covers every IPv6 rule shape, ICMPv6 included. CSF and APF report it false when their own config disables IPv6 (csf.conf IPV6, conf.apf USE_IPV6), since neither tool then keeps an IPv6 ruleset in sync. iptables reports it false on a host whose packaging ships no ip6tables save file — a system built without IPv6, or one that never installed the ip6tables package — and manages IPv4 alone: reads report IPv4 rows only, a FamilyAny write narrows to the IPv4 file, a concrete-IPv6 write returns ErrUnsupported, and a removal is a no-op (there is nothing IPv6 to remove).

Default policy

GetDefaultPolicy/SetDefaultPolicy read and set the default action applied to packets that match no rule. A DefaultPolicy carries an Action per direction (Input, Output, Forward); a direction left as ActionInvalid is not exposed (on Get) or left unchanged (on Set). On a backend that supports it, the policy is captured in a Backup and re-asserted by Restore, so a snapshot of a default-drop host reproduces that policy on replay rather than inheriting the restore host's.

Backend	Directions supported
iptables	input, output, forward
ufw	input, output, forward
nftables	input, output, forward
firewalld	input (the zone target)
others	unsupported (ErrUnsupportedPolicy)

Address sets (ipset / nftset / pf tables)

Address sets are named collections of addresses (AddressSet) that rules can match against, managed separately from filter and NAT rules. A Backup captures the managed sets (with their entries) and Restore recreates them before the rules, so a set-referencing rule (@set) resolves when a snapshot is replayed on a host that does not yet have the set. They map onto the backend's native construct:

Backend	Construct
iptables	ipset (hash:ip, hash:net)
ufw	ipset (via the host iptables)
nftables	a set in the private inet table
firewalld	a firewalld ipset (D-Bus)
pf	a pf table
CSF/APF	ipset commands in the managed pre-hook
WFP	unsupported (ErrUnsupportedSet)

set := &firewall.AddressSet{Name: "blocklist", Family: firewall.IPv4, Type: firewall.SetHashNet}
_ = mgr.AddAddressSet(ctx, set)
_ = mgr.AddAddressSetEntry(ctx, "blocklist", "203.0.113.0/24")
sets, _ := mgr.GetAddressSets(ctx)

Testing

The Makefile drives every test path; run these from the repo root.

make test-general              # unit/parser tests — fast, no root, no VM
make test-integration-linux    # Linux backends end-to-end in a throwaway QEMU VM
make test-integration-freebsd  # pf end-to-end in a throwaway FreeBSD VM
make test-integration-windows  # Windows Firewall end-to-end in a throwaway Windows VM
make test-integration          # all three integration suites
make test                      # test-general plus every integration suite
make lint                      # golangci-lint across every target GOOS

make test-general is the plain go test ./... suite — rule encoding/decoding, capability and helper logic. It never touches a live firewall and needs no root, so it is the one to run while iterating.

The test-integration* targets boot disposable QEMU VMs and run the capability-driven suite against the real backends inside them, so nothing on the host is modified. Backend detection and rule application need the corresponding firewall installed and running, which is what the VMs provide. Limit the Linux run to particular backends with BACKENDS:

BACKENDS="nft firewalld ufw iptables apf csf" make test-integration-linux

They require qemu-system-x86_64, KVM (/dev/kvm), genisoimage, and python3 for the FreeBSD image. VM artifacts are cached under ./.cache; make clean removes that cache and the compiled test binaries.

macOS cannot be automated in a VM, so run its pf backend manually on a Mac:

sudo go test -tags integration -run TestIntegration