Rule documentation and meta — why the description field is not optional

A firewall ruleset is the most important configuration file in a production estate. It is the artifact that determines what traffic is allowed, what is blocked, and what is logged. It is also the artifact that is most often undocumented. Operators inherit firewalls with hundreds of rules, no descriptions, no owners, and no change history. The first hour of any incident is spent figuring out what the rules are doing; the first day is spent figuring out why.

This lesson covers the disciplines — the description field, the match-only rule pattern, consistent metadata, and the change-control process — that turn a ruleset into an auditable artefact.

The description field

Every OPNsense rule has a Description field. The field is free text, supports multiple lines in the GUI, and is included in the generated PF ruleset as a comment. The description is the operator’s note to themselves and to the next operator.

A good description has four components:

1. Intent. What does this rule do?
2. Owner. Who is responsible for this rule?
3. Reference. Why was this rule added?
4. Last review. When was this rule last reviewed?

A bad description is “HTTPS”, “test”, “temporary” (with no follow-up), or empty. An empty description is the worst — it is a rule that the operator cannot explain to anyone, including themselves six months later.

$ pfctl -s rules | grep -A 1 '@92'

@92 pass in quick on igb0 inet proto tcp from 192.0.2.0/24 to any port = https
[ Permit outbound HTTPS from LAN clients. Owner: NetOps (alice). Ticket NET-1234. Reviewed 2025-12. ]

Match-only rules: log and tag without deciding

A “match-only” rule is a rule whose action is match, not pass or block. PF treats match as a no-op for the decision: the packet matches the rule, but evaluation continues. The match action is useful for two patterns:

• Logging without deciding. A match-only rule with logging enabled records every packet that matches its criteria in the firewall log, without affecting the firewall’s decision.
• Tagging for downstream rules. A match-only rule can add a tag (match tag <name>) to packets matching its criteria. Per-interface rules below can match the tag and decide on the tagged packets.

This rule records every SSH attempt on every interface in the firewall log. It does not pass or block; the per-interface rules below decide.

Consistent metadata

A team that applies consistent metadata to every rule can answer questions in minutes. A team that does not can answer them in days.

Three metadata fields beyond the description are worth maintaining:

• Category. A short label that groups rules by purpose.
• Owner. The team or person responsible for the rule.
• Reference. The ticket, change record, or document that explains why the rule was added.

The metadata is recorded in the rule description, not in a separate database, because the description is part of the GUI and the generated ruleset.

The cost of undocumented rulesets

The cost of undocumented rulesets is operational, not theoretical:

• Incident response time. A 03:00 incident on a firewall with 500 undocumented rules takes hours to triage.
• Onboarding time. A new operator inheriting an undocumented ruleset cannot safely edit it.
• Audit cost. A security audit asks “what does this rule do?”. An undocumented rule means the auditor and the operator must investigate.
• Drift. An undocumented ruleset drifts faster than a documented one.

The change-control discipline

Documentation is most valuable when it is updated. A description that was correct when the rule was added is wrong after the rule is edited unless the description is updated too.

The discipline:

1. Every rule has a description at creation. No rule is added without a description.
2. Every rule edit updates the description. If the intent changed, the description reflects the new intent.
3. Every rule removal documents the removal. The rule is not simply deleted; it is logged in the change record with a reason.
4. Quarterly review. Every rule is reviewed quarterly. Rules that are no longer needed are removed.

$ diff /conf/backup/filter/filter-20260813-235129.conf /conf/backup/filter/filter-20260814-021453.conf

@@ -87,7 +87,7 @@
@87 pass in quick on igb0 inet proto tcp from 192.0.2.0/24 to any port = https
@88 pass in quick on igb0 inet proto tcp from 192.0.2.0/24 to any port = http
@89 pass in quick on igb0 inet proto tcp from 192.0.2.0/24 to any port = 22
-@100 block drop in quick on igb0 inet from 10.0.0.0/8 to any
+@100 block drop in quick on igb0 inet from 10.0.0.0/8 to any
 [ Block RFC1918 sources on LAN. Owner: NetOps. Ticket NET-1001. ]

A description template

A template that works for most teams:

[Intent]. Owner: [team or person]. Ticket: [reference]. Reviewed: [date].

Example:

Permit outbound HTTPS from LAN clients to any destination.
Owner: NetOps (alice@corp). Ticket: NET-1234. Reviewed: 2025-12-15.

Variations:

• For removal-during-incident rules: “EMERGENCY: [reason]. Owner: [person]. Will be reviewed within 24 hours.”
• For match-only rules: “LOG-ONLY: [what is logged]. No enforcement. Owner: [person].”
• For temporary rules: “TEMPORARY until [date]: [reason]. Owner: [person]. Will be removed at [date].”

The “no description” rule as an incident signal

In a disciplined environment, a rule without a description is an incident signal. Either the rule was added without following process, or the description was stripped during an edit. Either way, the rule needs investigation.

Summary

• Every rule has a description that includes intent, owner, reference, and review date.
• Match-only rules are logging and tagging tools, not enforcement. They are explicitly labelled.
• Consistent metadata (category, owner, reference) makes the ruleset auditable.
• The change-control discipline ensures documentation stays accurate.
• Temporary rules need explicit removal dates and owners.
• The generated ruleset is the audit artefact.
• A rule without a description is an incident signal.