Firewall Rule Management | The Garnet Wiki

Firewall rule management is the disciplined process of defining, deploying, monitoring, and maintaining the access control policies that govern network traffic across a system. It matters when a service must be accessible from the internet, when microservices need to communicate securely, when security teams enforce compliance, or when a system fails due to a misconfigured access path—especially in multi-environment, multi-team deployments where rules are scattered across layers and tools.

Defining Rules

A firewall rule consists of a set of conditions that match incoming or outgoing network traffic and a set of actions to apply when they match. The core components are source and destination IP ranges, port ranges, protocol (TCP, UDP, ICMP), and a list of actions such as allow, deny, log, and redirect.

Rules are defined using a declarative format. A minimal rule in JSON might be:

{
  "name": "allow-https-from-frontend",
  "description": "Allow HTTPS traffic from frontend subnet",
  "source": "10.0.1.0/24",
  "destination": "10.0.2.0/24",
  "protocol": "tcp",
  "ports": [443],
  "action": "allow",
  "priority": 100,
  "enabled": true
}

The priority field determines evaluation order: rules are applied top-down, and the first match determines the outcome. A rule with priority: 100 is evaluated before one with priority: 200. Rules are applied in order until a match is found, and the first matching rule determines the action.

A rule may also include metadata such as tags, owner, and a created_at timestamp. Tags allow grouping rules by purpose, environment, or team. For instance, ["web", "prod", "team-frontend"] can be used to filter and manage rules.

Deploying Rules

Rules are deployed to a firewall system using a version-controlled configuration file. The most common approach is to store rules in a rules/ directory with one JSON file per rule, versioned in Git.

rules/
  0010-allow-ssh-from-ops.json
  0020-allow-database-backup.json
  0030-allow-https-from-frontend.json

A CI/CD pipeline pulls the latest rules, validates them, and applies them to the target firewall. Validation includes checking required fields, ensuring no duplicate names, and verifying that all referenced IP ranges or tags exist.

Deployment is done via a script using curl to interact with a firewall API. The API endpoint for rule creation is POST /api/v1/rules, with a request body containing the rule object.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d @rules/0020-allow-database-backup.json \
  https://firewall.example.com/api/v1/rules

A successful deployment returns a 201 Created response with the newly created rule in the body.

{
  "id": "r-12345",
  "name": "allow-database-backup",
  "status": "active",
  "revision": 1,
  "created_at": "2023-10-05T14:22:00Z"
}

If a rule with the same name already exists, the API returns 409 Conflict and includes the existing rule’s id.

Updating Rules

Updating a rule is idempotent: reapplying the same rule file updates the existing rule and creates a new revision.

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d @rules/0030-allow-https-from-frontend.json \
  https://firewall.example.com/api/v1/rules/allow-https-from-frontend

The PUT method updates the rule with the given name. If the rule does not exist, it is created.

A common failure is confusion between PUT and PATCH. PUT replaces the entire rule, so missing fields are set to null or default. PATCH merges the provided fields into the existing rule, leaving untouched fields unchanged.

For example, applying this patch:

{
  "priority": 150,
  "description": "Allow HTTPS from frontend VPC, with logging"
}

to a rule with priority: 100 and description: "Allow HTTPS from frontend", results in:

{
  "name": "allow-https-from-frontend",
  "description": "Allow HTTPS from frontend VPC, with logging",
  "priority": 150,
  "enabled": true,
  "action": "allow",
  "source": "10.0.1.0/24",
  "destination": "10.0.2.0/24",
  "protocol": "tcp",
  "ports": [443],
  "created_at": "2023-10-04T10:00:00Z"
}

But using PUT with the same JSON would overwrite enabled, action, and source, potentially removing the destination field if not included.

Monitoring Rule Application

After deployment, rules must be applied to the underlying firewall hardware or software. A rule is active when it is loaded into the forwarding table and begins filtering packets.

The status of a rule is tracked via a status field. Possible values include:

draft: rule is configured but not yet applied.
active: rule is live and processing traffic.
inactive: rule is defined but not applied.
failed: rule could not be applied; details include error message and timestamp.

The status field is updated via a PATCH request after deployment:

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"status": "active", "applied_at": "2023-10-05T14:30:00Z"}' \
  https://firewall.example.com/api/v1/rules/allow-https-from-frontend

A rule’s applied_at timestamp is critical: it indicates when the rule was pushed to the firewall and when it started affecting traffic.

A common failure mode is rule application delay. A rule may be created and marked active, but the firewall engine takes 10–30 seconds to load the rule into its kernel. During this window, traffic is processed under the old rule set. Monitoring tools must track the difference between created_at, status_changed_at, and applied_at.

Managing Rule Dependencies

Rules often depend on external configurations such as IP address ranges, tags, or service groups.

An IP address range might be defined in a separate ip-ranges/ directory:

{
  "name": "frontend-subnet",
  "cidr": "10.0.1.0/24",
  "tags": ["frontend", "prod"]
}

A rule refers to the range by name, and the firewall system resolves the cidr during validation.

If the frontend-subnet range is missing, the rule creation fails with a 400 Bad Request response:

{
  "error": "Validation failed",
  "details": [
    {
      "field": "source",
      "message": "IP range 'frontend-subnet' not found"
    }
  ]
}

The firewall system also supports tagging rules. A rule can be tagged with ["web", "prod", "team-frontend"], and rules can be queried by tag.

curl -H "Authorization: Bearer $API_KEY" \
  "https://firewall.example.com/api/v1/rules?tag=prod&tag=web"

This returns all rules with both prod and web tags.

Tracking Rule Changes

Each rule has a revision history. Every update to a rule creates a new revision, stored in a revisions table with the following schema:

revision_id	rule_id	version	changes	applied_at	user
r-12345-v2	r-12345	2	{ "priority": 150 }	2023-10-05T14:30:00Z	[email protected]

Revisions are created automatically on every PUT or PATCH operation. The changes field is a JSON object that records what fields were modified and their old and new values.

A revision is associated with the rule via a rule_id and includes a version number. The version is used to track rule evolution and to support rollback.

Rollback to a previous version is done via a POST /api/v1/rules/{id}/revisions/{version}/rollback endpoint.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  https://firewall.example.com/api/v1/rules/allow-https-from-frontend/revisions/1/rollback

This applies the state of revision 1 to the rule and updates the applied_at timestamp.

Handling Rule Conflicts

When multiple rules match the same traffic, the first match wins. However, rules may conflict when a later rule overrides an earlier one.

The priority field is the primary mechanism for ordering. But a rule with priority: 100 may be applied after a rule with priority: 50, even though the latter is logically earlier.

To resolve this, the firewall system maintains a rule_order table that records the actual order in which rules are loaded into the engine.

SELECT
  name,
  priority,
  applied_at,
  status
FROM
  rules
ORDER BY
  priority ASC,
  created_at ASC;

If the actual order differs from the expected order, the system logs a warning:

WARN: Rule order mismatch for rule 'allow-https-from-frontend'
Expected: priority 100, applied before priority 50 rules
Actual: priority 100 rule applied after priority 50 rule 'allow-ssh-from-ops'

This warning is critical in multi-environment setups where rules are applied in different sequences.

Applying Rules to Multiple Targets

Rules may be applied to multiple firewalls or network zones. A rule can be scoped to a zone or environment.

A rule with zone: "staging" is applied only to the staging firewall, while a rule with zone: "prod" is applied only to production.

Rules are applied to a zone via a POST /api/v1/zones/{name}/rules endpoint.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"rule_name": "allow-https-from-frontend", "priority": 100}' \
  https://firewall.example.com/api/v1/zones/staging/rules

The zone configuration includes a list of target firewalls, and the system applies the rule to each.

If a rule is not found in the zone, the API returns 404 Not Found with a message:

{
  "error": "Rule not found in zone",
  "details": {
    "zone": "staging",
    "rule_name": "allow-https-from-frontend",
    "available_rules": [
      "allow-ssh-from-ops",
      "allow-database-backup"
    ]
  }
}

Debugging Rule Application Failures

When a service fails to accept traffic, the first step is to check the firewall rules. The status field is critical: a rule marked active but not applied indicates a deployment pipeline failure.

A rule may be active but traffic still not reaching the service. The cause is often a mismatch between source and destination IP ranges.

The firewall system provides a diagnostic endpoint: GET /api/v1/rules/debug.

curl -H "Authorization: Bearer $API_KEY" \
  -d '{"source": "192.0.2.10", "destination": "10.0.2.100", "port": 443, "protocol": "tcp"}' \
  https://firewall.example.com/api/v1/rules/debug

The response includes a list of matching rules, their priority, and the action taken.

{
  "matches": [
    {
      "rule": "allow-https-from-frontend",
      "priority": 100,
      "action": "allow",
      "reason": "Source IP 192.0.2.10 matches 10.0.1.0/24, destination 10.0.2.100 matches 10.0.2.0/24, port 443, protocol tcp"
    },
    {
      "rule": "allow-internal-traffic",
      "priority": 50,
      "action": "allow",
      "reason": "Source IP 192.0.2.10 matches 10.0.0.0/16"
    }
  ],
  "first_match": {
    "rule": "allow-https-from-frontend",
    "action": "allow",
    "priority": 100
  },
  "applied_at": "2023-10-05T14:30:00Z",
  "status": "active"
}

This output is the first line of defense in production troubleshooting.

Summary of Key Concepts

Rules are defined as JSON documents with name, source, destination, protocol, ports, action, priority, and enabled.
priority determines evaluation order; the first match wins.
PUT replaces the entire rule; PATCH merges fields.
A rule’s status is updated after deployment and reflects its lifecycle.
Revisions track changes; rollback restores a rule to a previous state.
Rules depend on named IP ranges and tags; missing dependencies cause validation failures.
Zones allow rules to be scoped to multiple firewalls.
The debug endpoint traces how traffic is matched and actioned.
Conflicts arise when applied order differs from priority order.

The discipline of firewall rule management ensures that network access is predictable, auditable, and resilient—turning a complex, dynamic system into a reliable, well-understood foundation.

This page was rewritten on 18 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.