User-agent rules let you decide, by User-Agent header, which clients bypass all checks and which are rejected outright. They are managed on Admin > Traffic Guard > Rules (/admin/traffic-guard/rules) under User-Agent Rules, and any site admin or global admin can add or delete them.
How rules are evaluated
- Rules are checked before any other scoring, in ascending Priority order (lowest number first, then oldest first for ties). The first matching rule wins.
- An allow rule ends inspection immediately: the request is let through with no rate counting, no scoring and no log entry.
- A block rule adds the
ua_rule_blocksignal with weight 80 in every mode. Because 80 is above the default block thresholds (70, 55 and 40), the request receives HTTP 403 and, if auto-ban is on, the IP is banned. Only a block threshold raised above 80 would change that. - Rules apply to every request on public and API paths. Admin paths are exempt from scoring.
- Matching is case-insensitive for both match types.
Traffic Guard also ships with a built-in list of bad-bot substrings (curl/, wget/, python-requests, headless, scrapy, ahrefsbot, semrushbot, bytespider and others) that adds a lower-weight signal. Your rules take precedence over that list; see Risk Scoring for the full set.
Adding a rule
- Go to Admin > Traffic Guard > Rules.
- Under Add UA Rule, fill in the form:
| Field | Description |
|---|---|
| Pattern | Required. The text or regular expression to match against the User-Agent header, up to 512 characters. |
| Match Type | Substring (case-insensitive): the header contains the pattern. Regex (case-insensitive): the pattern is a PCRE expression, written without delimiters (the module wraps it in /.../i). Invalid expressions are rejected. |
| Action | Block (403) or Allow (bypass all checks). |
| Priority | Lower numbers are evaluated first. Default 100, range 1 to 9999. |
| Label | Optional description shown in the rules table, up to 128 characters. |
- Click Add Rule.
New rules take effect on the next request. Rules are always created enabled; there is no way to disable a rule from the admin pages other than deleting it.
Examples
| Goal | Pattern | Match Type | Action | Priority |
|---|---|---|---|---|
| Let Googlebot through everything | Googlebot |
Substring | Allow | 1 |
| Block one scraper | BadBot |
Substring | Block | 100 |
| Block versions 2 to 9 of a scraper | EvilScraper/[2-9]\.\d |
Regex | Block | 100 |
| Block empty-looking generic clients | ^Mozilla/5\.0$ |
Regex | Block | 200 |
Give allow rules the lowest priority numbers so that a broad block rule further down cannot catch a crawler you meant to allow.
Deleting a rule
In the User-Agent Rules table, click Delete on the rule's row and confirm. The change applies to the next request.
Rules and the built-in bot list
Allow rules are the way to whitelist a client that the built-in list would otherwise flag. For example, a monitoring service that identifies itself with curl/8.0 gets the bot_ua_pattern signal by default; an allow rule for its exact user agent (or an allowlist entry for its IP, see IP Allowlist) exempts it.