Configuring Firewall Rules

Learn how to configure rules for your firewall

Firewall rules are used to protect your system by blocking or allowing requests based on specific conditions. In Ironforge, all requests are allowed by default, and rules can be created to perform actions such as Block, Bypass, Log, and Rate Limit

Firewall rules are composed of one or many Conditions and an Action.

  • Conditions: A condition is a set of criteria that must be met for an action to be executed.
  • Actions: An action is the step that will be executed if the conditions are met.

As well, rules in Ironforge are given a rank. When first creating a rule, that rule would have the lowest rank of them all, that can later be rearranged.

Rule Ranking System

The ranking system allows you to tailor your firewall to your needs. By dragging and dropping the rules in the UI you are able to define the order in which the rules are evaluated.

Ranking your rules, gives you more flexibility over their evaluation order. This ensures your most important security policies are always enforced first, creating a more predictable and effective security system.

Conditions

Firewall rules use one or more conditions to protect your system. All conditions in a rule must be true for the rule to trigger and execute its action

A condition is made of a Property, an Operator and a Value.

Below is a comprehensive list of properties available for configuring your firewall rule conditions:

  • JA4
  • Cluster
  • IP Address v4
  • IP Address v6
  • Project
  • City
  • Country
  • User Agent
  • Hostname
  • Protocol
  • HTTP Method
  • API Key
  • JWT Public Key
  • Auth Token
  • RPC Method
  • Program Address
  • Transaction Signer

Combining a property and an operator with a value, you can create a condtion that will be tested against any incoming request. Currently the following operators are supported:

  • Equals: Value must be a single element or a wildcard (*)
  • Does not equal: Value must be a single element or a wildcard (*)
  • Is any of: Value must be a comma-separated list without blank spaces
  • Is not any of: Value must be a comma-separated list without blank spaces

For a given property any value can be passed, from singe elements, to arrays or wilcards ('*'), although keep in mind there are certain formats accepted based on the property selected. E.g One cannot input an sendTransaction as the value for IP Address.

While creating these conditions however, there are some specifications and requirements that should be taken into account.

Property Specifications and Requirements

For any given property, the value field of the condition must be a string or an array of strings, joined by commas without spaces. Additionally, wildcards (*) are supported in the value field of the condition.

The presence of a property within a rule means that the request must contain the property with the value in the request. If the request does not contain the property with the value, the rule will be evaluated against an empty value.

Let's look at an example: Say you create a rule with a Hostname condition that denies requests not coming from example.com. For any requests coming from a browser or a mobile app, the origin is always present and the condition will be evaluated against their values.

Whereas for server requests, the origin might not be present and the condition will evaluate an empty value against the condition value. In this case, the request would fail as it does not match the value.

Additionally, some condition properties require additional configuration or have specific requirements:

Auth Token

When using the Auth Token condition, the request must include an x-ironforge-auth-token HTTP header that includes a valid auth token matching the value in the condition.

JWT Public Key

When using the JWT Public Key condition, the request must include a valid JWT token in the Authorization header with the Bearer scheme signed using the public key specified as the value of the condition.

IPv4 and IPv6 Addresses

The IP Address v4 and IP Address v6 conditions validate that the provided value matches the correct IP address format:

  • IPv4 Format: xxx.xxx.xxx.xxx (e.g. 192.168.1.1)
  • IPv6 Format: xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx (e.g. 2001:0db8:85a3:0000:0000:8a2e:0370:7334)

Each condition strictly enforces its respective format - IPv4 addresses will be rejected by IPv6 conditions and vice versa. This ensures proper validation and prevents format mismatches.

As well, wildcards are supported in the value field of the condition. For example, 192.168.* will match any IPv4 address in the 192.168.0.0/16 subnet, and 2001:0db8:85a3:* will match any IPv6 address starting with 2001:0db8:85a3.

Condition Combinations

Firewall rules support combining multiple conditions using AND and OR condition types to create complex matching patterns.

  • AND combinations require all conditions to evaluate to true for the rule to trigger
  • OR combinations require at least one condition to evaluate to true for the rule to trigger

You can nest conditions by creating subgroups with a different type (AND/OR) than their parent. Each condition supports one subgroup.

For example, consider a rule with AND conditions at the root level. Adding an OR condition creates a subgroup that only applies to the conditions within that group. The UI visualizes these groupings with connecting lines between related conditions. While the AND/OR buttons on the right allows you to add a new condition to each group.

Screenshot of a complex firewall rule with nested conditions

In the example above:

  • The root level uses AND logic
  • A subgroup using OR logic contains additional conditions
  • The connecting lines show which conditions belong to each group

The rule logic can be expressed as:

  • The request is not coming from mainnet AND it is not originated from Madrid
  • The request is not coming from mainnet AND it is not targetting the Token1111 program address
  • The request is not coming from mainnet AND it is not originated from Madrid OR it is not targetting the Token1111 program address

By combining bot of these condition relationships you can manage to create complex rules that can be used to protect your system.

Actions

Actions are the final step of a firewall rule as they describe the action that will be taken if the conditions are met. You can choose from the following actions:

  • Bypass: Allow the request to reach the RPC endpoint without any further checks.
  • Deny: Block the request from reaching the RPC endpoint.
  • Rate Limit: Restrict request frequency using a fixed window rate limiting algorithm. Requests can be limited based on:
    • Global: Rate limit is applied across all requests to the endpoint
    • IP Address: Rate limit is applied per IP address making requests
  • Log: Log the request. This is useful for debugging and monitoring purposes.

Bear in mind that if any rule is matched its action will be executed and only one action at a time is executed for a request. If there are multiple rules that might apply to the same request, the action of the rule with the highest rank will be executed.

How to setup a rule

  1. Navigate to the Firewall section in your Ironforge dashboard
  2. Click "+ New Rule" in the top right
  3. Configure one or more conditions like IP/Program Address whitelisting
  • Select the property (e.g. IP Address, Program ID, Country)
  • Select the operator (e.g. equals, not equals, greater than)
  • Enter the value to match against
  • (Optional) Select a condition type (AND/OR) and chain different conditions
  • (Optional) Add a subgroup to any condition by selecting a different condition type
  1. Select an action: Bypass, Deny, Rate Limit, or Log
  2. Click "Create" to save the rule

Rules are enabled by default but they can be enabled, disabled, edited or deleted from the Firewall dashboard.

As well, you can use the "Expression Overview" section to see a breakdown of the resulting rule logic and conditions.

Screenshot of the rule expression overview