API firewall rule automation — building rules safely from a script · OPNsense

A firewall rule is the most consequential object a script can add to an OPNsense firewall. The rule’s correct evaluation order, its anti-lockout implications, and the difference between pass, block and reject are all the same as in the GUI. What the API adds is automation at scale — a CI pipeline that promotes a rule, an Ansible role that configures a fleet, a ticketing system that opens a port when a change is approved. The lesson here is how to keep that automation safe.

This lesson walks the full lifecycle of an API-driven rule change: the search-then-add-then-verify pattern, the rule-ordering invariants, the verification step that distinguishes success from silent failure, and the audit trail that ties every change to the credential that made it.

The search-then-add-then-apply-then-verify pattern

Automation writes to the automation rule set — Firewall → Automation → Filter, reached through /api/firewall/filter/*. That set is separate from the per-interface rules an operator edits by hand, and it is the only firewall rule set with a model-backed API. The disciplined pattern is four steps:

Search. GET /api/firewall/filter/searchRule returns the existing rules, their UUIDs and their order. The new rule’s position relative to existing rules is decided before any write happens.
Add. POST /api/firewall/filter/addRule with a JSON body containing the new rule. The framework assigns a UUID; the response includes it.
Apply. POST /api/firewall/filter/apply. Until this call runs, the rule exists in /conf/config.xml and does nothing to traffic.
Verify. GET /api/firewall/filter/getRule/{uuid} returns the saved rule; pfctl -sr shows it loaded into pf.

Each step has a defined outcome: success proceeds to the next step; a failure aborts and rolls back to the pre-change backup. There is no “best effort” rule automation; either the rule is applied or the change-set is rolled back.

Read-only / Safeinspect the automation rule set— Before adding a rule, the script lists what is already there. searchRule returns a paginated envelope, so total is the count and the rules themselves are under .rows. The response mixes automation rules with the legacy interface rules and the system's internal rules; the latter two carry legacy: true, so the jq filter drops them and keeps only what this controller can write. Note that legacy entries have a uuid field too — it is a content hash rather than a model UUID, and setRule will not accept it. The last remaining entry's sequence tells the script what number to give a rule that should evaluate after everything currently present.

$ curl -sk -u "$KEY:$SECRET" 'https://localhost/api/firewall/filter/searchRule' | jq '{total, last: (.rows | map(select(.legacy != true)) | .[-1] | {uuid, sequence, description})}'

{
"total": 12,
"last": {
  "uuid": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "sequence": "40",
  "description": "CHG-2026-1180 monitoring scrape"
}
}

Illustrative output

Rule payload anatomy

The payload is one flat object under a single rule key. There are no nested source or destination sub-objects — source and destination are separate top-level fields with source_/destination_ prefixes. A typical outbound allow:

{
  "rule": {
    "enabled": "1",
    "sequence": "50",
    "action": "pass",
    "quick": "1",
    "interface": "lan",
    "direction": "in",
    "ipprotocol": "inet",
    "protocol": "any",
    "source_net": "lan",
    "destination_net": "any",
    "log": "1",
    "description": "CHG-2026-1314: LAN hosts to internet"
  }
}

The fields that surprise an author coming from the GUI:

description, not descr. The legacy per-interface rules use descr in config.xml; the automation model uses description. Sending descr does not error — the model ignores unknown fields — so the rule saves with an empty description and the mistake is only visible later.
source_net and destination_net take a host, a network in CIDR, an alias name, or any. Ports are separate fields, source_port and destination_port, and are left empty to mean “all ports”. source_not and destination_not invert the match.
interface is a comma-separated list of interface names, and it may be empty. An empty interface makes the rule floating — it is evaluated on every interface — which is rarely what an automation intends and is easy to produce by omitting the field.
quick defaults to 1. A non-quick rule does not stop evaluation when it matches; the last matching rule wins instead of the first. Most rules want the default.
direction defaults to in and accepts in, out, or any. ipprotocol defaults to inet and accepts inet, inet6, or inet46.
sequence orders the rule within the automation set; it defaults to 1, so a script that never sets it produces a pile of rules all claiming the same position.
log defaults to 0. An automation-created rule that nobody can see in the log is a rule nobody can debug, so set it explicitly.

NAT is not part of this model. Each kind of translation has its own controller under the same module — /api/firewall/source_nat/* for outbound NAT, /api/firewall/d_nat/* for port forwards, /api/firewall/one_to_one/* and /api/firewall/npt/* for the address-mapping cases — and each follows the same search/add/set/del/apply shape as the filter controller. A filter rule neither performs nor suppresses translation.

Configuration changeadd an automation rule— Adding a rule to the automation set. The framework validates every field against the model — the named interface must exist, action must be pass, block or reject, ipprotocol must be inet, inet6 or inet46 — and writes the rule with a server-assigned UUID. Save that UUID: it is the key for every subsequent setRule, delRule and toggleRule call, and it is also the label pf attaches to the rule, which is how you find it again in pfctl output. The rule is in the configuration at this point and not yet in pf.

$ curl -sk -u "$KEY:$SECRET" -X POST -H "Content-Type: application/json" https://localhost/api/firewall/filter/addRule -d '{"rule":{"enabled":"1","sequence":"50","action":"pass","quick":"1","interface":"lan","direction":"in","ipprotocol":"inet","protocol":"any","source_net":"lan","destination_net":"any","log":"1","description":"CHG-2026-1314 outbound"}}'

{
"result": "saved",
"uuid": "f1e2d3c4-b5a6-7890-1234-567890abcdef"
}

Illustrative output

Rule-ordering invariants

Three invariants that every safe rule-automation script must respect:

sequence is the position, and it has a default. Order within the automation set comes from the sequence field, sorted ascending. Its model default is 1, so a script that never sets it stacks every rule it has ever created at the same position, in whatever order the configuration happens to hold them. Leave gaps — 10, 20, 30 — so a later rule can be inserted between two existing ones without renumbering.
Quick rules stop evaluation; the first match wins. A pass any → any above a block for a specific pair makes the block unreachable. Before adding a rule, searchRule and check what already matches the traffic the new rule is about. Adding a correct rule below an existing general allow changes nothing.
An empty interface means floating. A rule with no interface is evaluated everywhere, and floating rules are placed ahead of interface-bound rules. A script that omits interface because it seemed optional has not written a LAN rule; it has written a rule that applies to WAN as well.

addRule does not choose a position for you — it stores whatever sequence you send, defaulting to 1. To place a rule between two existing ones, read their sequences with searchRule and pick a number in the gap; if there is no gap, setRule/{uuid} on the neighbours to renumber them first.

Automation can still lock you out — just not by deleting the anti-lockout rule

The anti-lockout rule is generated by the system rather than stored as an editable rule, so delRule cannot remove it: it appears in searchRule output alongside the other internal rules, and a delete against it fails. That is a real safety property, and it is not the same as being safe.

What automation can do is add a block rule that matches management traffic and sits ahead of everything that would have allowed it — an over-broad source alias, a floating rule created by omitting interface, a deny written for one interface and applied to all. The result is the same lost session, reached by a different route. The protection is procedural: run the change against a lab firewall first, keep console access available during the window, and take the pre-change backup so the rollback is one restore rather than a rescue.

Verification: distinguishing success from silent failure

Three verification steps after each change-set:

The rule is in the configuration. GET /api/firewall/filter/getRule/{uuid} returns the rule with the expected values. If it does not, the write did not land and there is nothing to apply.
The apply succeeded. POST /api/firewall/filter/apply returns a status body. A ruleset that fails to compile — a bad alias reference, an interface that no longer exists — is reported here, and pf keeps running the previous ruleset.
pf sees the rule. pfctl -sr shows it in the running ruleset. Search by the rule’s UUID, not by its description: OPNsense attaches the automation rule’s UUID as the pf label, whereas the description is emitted as a comment and pf does not retain comments. pfctl -sr | grep <description> finds nothing even when everything worked, which is a confusing way to conclude a change failed.

Service impact possibleapply and verify the rule in pf— apply rebuilds the ruleset and loads it into pf; pfctl -sr then reads back what pf is actually running. The matched line shows the rule live: action (pass), interface (igb1, the LAN assignment), source resolved from the lan alias to 192.0.2.0/24, destination any, keep state, and the label — which is the UUID addRule returned. That label is the reliable handle for the rule, both here and when correlating pf state entries back to the rule that created them. If the grep returns nothing after a successful apply, the rule saved but did not compile into the ruleset, and the change-set should be rolled back.

$ curl -sk -u "$KEY:$SECRET" -X POST https://localhost/api/firewall/filter/apply; sleep 2; pfctl -sr | grep 'f1e2d3c4-b5a6-7890-1234-567890abcdef'

{
"status": "OK
"
}
pass in quick on igb1 inet from 192.0.2.0/24 to any flags S/SA keep state label "f1e2d3c4-b5a6-7890-1234-567890abcdef"

Illustrative output

Audit trail

Every rule change leaves a trail in three places:

The authentication log. The web server and framework log the authenticated user for each request. Because an API key belongs to a user, the log names the user, not the key — which is the argument for one service account per automation tool rather than one shared account.
The configuration history. OPNsense keeps a versioned history of /conf/config.xml under /conf/backup/, with a new revision written on every change and the change’s origin recorded against it. GET /api/core/backup/backups/this lists the revisions and GET /api/core/backup/diff/this/{rev1}/{rev2} returns the difference between two of them — the precise change, as the firewall recorded it.
The running ruleset. pfctl -sr is what pf is enforcing right now. Comparing it against the configuration is what catches a save that was never applied.

A post-change audit report combines the three: who made the change, what the configuration diff shows, and what the firewall is running. A script that omits the audit trail is invisible to the post-incident reviewer.

Why the pf label is the rule's UUID

Every rule OPNsense generates carries a pf label, and the label is chosen differently depending on where the rule came from:

A rule from the automation model gets its own UUID as the label. The model hands label => <uuid> straight to the rule generator.
A legacy interface rule has no UUID, so the generator hashes the rule’s fields and uses that hash instead. Edit the rule and the hash changes, because it is derived from the content.

That difference is why automation is the easier set to audit. A UUID is stable across edits — change the rule’s description or its destination and the label stays the same — so the label is a permanent handle on one rule from the moment addRule returns it. A legacy rule’s label moves whenever the rule does, which makes it useless as an identifier across time.

The label is also the only part of the rule pf keeps for you. The description is written into the generated ruleset as a trailing comment, and pf discards comments when it loads the ruleset, so nothing you can read back from pfctl contains the description. Automation that wants to find its own rules again should record the UUID at creation and search on that.

Summary

Automation writes to the automation rule set through /api/firewall/filter/*: searchRule, addRule, setRule/{uuid}, delRule/{uuid}, then apply.
Save and apply are separate calls. {"result": "saved"} means the configuration changed and pf did not. Batch many saves behind one apply.
The payload is one flat object under rule — source_net, destination_net, source_port, destination_port, description — with no nested source or destination sub-objects and no NAT fields.
Order comes from sequence, which defaults to 1. Leave gaps. An empty interface makes the rule floating rather than interface-bound.
Verify against pf by the rule’s UUID, which is its pf label. The description never reaches pf, so grepping for it always fails.
The audit trail is the authentication log, the versioned configuration history under /conf/backup/, and the running ruleset.