Skip to Content
OpenFlare
GuidesDeploymentReferenceArchitectureChangelog

WAF Auto IP Group Rule Syntax

Auto IP groups aggregate metrics per client IP from request logs, then use Expr expressions to determine whether to include an IP in the group. Auto IP groups can be referenced by IP Match nodes in WAF rules. Rule topologies synchronize with site configuration snapshots, while IP group memberships update independently.

Config Structure

An auto IP group config is a JSON object:

{
  "lookback": "1h",
  "rules": [
    {
      "name": "Single-IP high-frequency 404 scanning",
      "expr": "request_count > 100 && StatusRatio(404) >= 0.8"
    }
  ]
}

Field reference:

FieldTypePurpose
lookbackstringLookback window duration in Go Duration syntax (e.g. 30m, 1h, 90m). Defaults to 1h, maximum 30 days. Compatible with legacy lookback_minutes.
rulesarrayAutomatic rule list. If any rule matches, the IP is added to the IP group.
rules[].namestringRule name, used for display and error reporting.
rules[].exprstringExpr expression, must return a boolean.

Execution Semantics

Auto IP groups aggregate metrics per client IP before evaluating expressions:

  1. The Server reads request logs within the configured lookback duration.
  2. Groups logs by normalized remote_addr IP, skipping IPv4 private networks, IPv6 Unique Local Addresses (ULA), loopback, link-local, unspecified, multicast, and broadcast addresses. IPv4-mapped IPv6 addresses resolve to the underlying IPv4 address.
  3. Calculates request counts, 404 counts, direct IP Host counts, and related metrics for each IP.
  4. Evaluates rules[].expr against each candidate IP.
  5. If an IP matches any rule, it is added to the auto IP group list.

Test Rule executes the same address filtering logic as production background evaluation. When an auto IP group updates on schedule, historical entries matching private or loopback ranges are purged automatically regardless of TTL. Manual and subscription IP groups are not filtered by this mechanism.

Whether a request represents "access via IP literal" is evaluated using the Host header: IPv4 or IPv6 literals (such as 203.0.113.10, [2001:db8::10], or 203.0.113.10:443) increment ip_host_count.

Available Keywords

The expression can use these fields directly:

KeywordTypePurpose
ipstringthe client IP currently being judged.
request_countnumberthe current IP's total requests in the lookback window.
status_404_countnumberthe current IP's requests returning 404 in the window.
status_404_rationumber404 ratio, computed as status_404_count / request_count.
ip_host_countnumberrequests where the current IP accessed via an IP-literal Host.
ip_host_rationumberratio of IP-address access, computed as ip_host_count / request_count.
client_error_countnumberthe current IP's requests returning 4xx.
server_error_countnumberthe current IP's requests returning 5xx.
last_seen_unixnumberthe current IP's last request Unix timestamp (seconds) in the window.

Ratio fields are decimals between 0 and 1. 80% is written 0.8, 50% is 0.5.

Custom Status Code Matching

If the built-in status_404_count / status_404_ratio don't fit, use these built-in methods to match arbitrary status codes:

  • StatusCount(code): request count of the current IP returning the given status code (or class) in the window.
    • exact code: StatusCount(403) > 10
    • status class (1xx–5xx, case-insensitive): StatusCount("4xx") > 50
  • StatusRatio(code): the ratio of the above count to the IP's total requests.
    • exact code: StatusRatio(502) >= 0.5
    • status class: StatusRatio("4xx") >= 0.8, StatusRatio("5xx") >= 0.3

A status class aggregates all codes in that hundred range, e.g. "4xx" covers 400–499, "2xx" covers 200–299.

Common Expr Patterns

Auto IP groups use Expr syntax; the expression must return a boolean.

Common operators:

PatternPurposeExample
>、>=、<、<=numeric comparisonrequest_count > 100
==、!=equal / not equalip != "127.0.0.1"
&&andrequest_count > 100 && StatusRatio(404) >= 0.8
``
!negation!(ip == "127.0.0.1")
invalue in listip in ["203.0.113.10", "198.51.100.20"]
not invalue not in listip not in ["127.0.0.1"]
()grouping precedence`(request_count > 100 && StatusRatio(404) >= 0.8)

Built-in Presets

The admin panel ships two preset rules that can be added and then adjusted:

{
  "name": "Single-IP high-frequency 404 scanning",
  "expr": "request_count > 100 && StatusRatio(404) >= 0.8"
}

Meaning: a single IP has over 100 requests in the window and a 404 ratio of at least 80%.

{
  "name": "Single-IP direct-access anomaly",
  "expr": "ip_host_count > 50 && ip_host_ratio > 0.5"
}

Meaning: a single IP accessed via IP-literal Host over 50 times, and that access ratio exceeds 50%.

Examples

High-frequency 404 scanning:

{
  "lookback": "1h",
  "rules": [
    {
      "name": "High-frequency 404 scanning",
      "expr": "request_count > 100 && StatusRatio(404) >= 0.8"
    }
  ]
}

IP direct-access anomaly:

{
  "lookback": "30m",
  "rules": [
    {
      "name": "IP direct-access anomaly",
      "expr": "ip_host_count > 50 && ip_host_ratio > 0.5"
    }
  ]
}

Catching both high 4xx and high 5xx:

{
  "lookback": "2h",
  "rules": [
    {
      "name": "Abnormal error rate",
      "expr": "(client_error_count > 80 && request_count > 100) || server_error_count > 30"
    }
  ]
}

Using status-class syntax (equivalent thinking to client_error_count / server_error_count):

{
  "lookback": "2h",
  "rules": [
    {
      "name": "High 4xx or 5xx ratio",
      "expr": "request_count > 100 && (StatusRatio(\"4xx\") >= 0.8 || StatusRatio(\"5xx\") >= 0.3)"
    }
  ]
}

Excluding trusted IPs:

{
  "lookback": "1h",
  "rules": [
    {
      "name": "404 scanning excluding trusted IPs",
      "expr": "ip not in [\"203.0.113.10\", \"198.51.100.20\"] && request_count > 100 && StatusRatio(404) >= 0.8"
    }
  ]
}

Usage Tips

Start with a shorter lookback and higher thresholds to observe hits, then tune gradually. The admin IP group page supports clicking Test Rule before saving to directly view the IPs hit in the current window; when the auto IP group actually runs, it overwrites the group's IP list. To keep certain addresses long-term, put them in a manual IP group and reference both the manual and auto groups in the WAF rule group.

When an IP group changes, the controller notifies online nodes to refresh the configuration manifest. Nodes use the digest to fetch changed groups. Periodic heartbeats continue detecting changes during WebSocket outages.

On this page