# Rules reference

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

The complete grammar for security-group rules: every field, action, condition, operator and `set` entry Sentinel accepts. For an introduction, see [Security groups & rules](/docs/sentinel/v2/concepts/security-groups/).

A security group's `rules` is an ordered JSON array. Rules gate every API-key request (`/v2/challenge`, `/v2/verify`, `/v2/inspect` and API-key calls to the other endpoints). Rules are created and replaced through the security-group endpoints of the [API reference](/sentinel-api-docs-v2.html); an update replaces the whole list.

## Rule object

Unknown keys are rejected. Optional fields are omitted from stored rules when they have their default value.

| Field | Type | Description |
| --- | --- | --- |
| `action` | string | Required. `allow`, `deny`, `accept` or `set`. See [Actions](#actions). |
| `conditions` | array | Optional, default `[]`. At most 20 [condition objects](#condition-object). A rule without conditions always matches. |
| `conditionsOperator` | string | Optional, default `and`. `and`: all conditions must hold; `or`: any condition must hold. |
| `message` | string | Optional. `allow` and `deny` only; at most 200 characters. Returned as `error` when this rule denies the request. |
| `monitor` | boolean | Optional, default `false`. Evaluate the rule without effect. See [Monitor mode](#monitor-mode). |
| `name` | string | Optional. At most 100 characters; must not contain `,` or start with `#`. Labels the rule in `GET /v2/inspect` and in request logs (`context.rules`, `context.monitor`), where unnamed rules appear as `#<index>`. |
| `set` | array | `set` only, and required there: 1 to 10 [set entries](#set-entry), each field at most once per rule. |

### Condition object

| Field | Type | Description |
| --- | --- | --- |
| `field` | string | Required. One of the [condition fields](#condition-fields). |
| `operator` | string | Required. One of the [operators](#operators). |
| `value` | array of strings | Required. 1 to 100 values (comparison operators: exactly 1). Each value is trimmed and must then be 1 to 500 characters. |

### Set entry

| Field | Type | Description |
| --- | --- | --- |
| `field` | string | Required. One of the [set fields](#set-fields). |
| `value` | string | Required. Always a string, also for numbers and booleans (`"true"`, `"5000"`). Leading and trailing whitespace is ignored. |

### Naming convention

Presets name their rules `preset:<id>:<part>`, for example `preset:recommended:base`. A UI can detect an applied preset by its `preset:<id>:` prefix. See [Presets](/docs/sentinel/v2/policies/presets/).

## Actions

Rules run in order. A rule *matches* when it has no conditions, or when all (`and`) or any (`or`) of its conditions hold.

| Action | When it matches | When it doesn't match | `message` | `set` |
| --- | --- | --- | --- | --- |
| `allow` | Continue with the next rule. | Deny the request. | Allowed | Not allowed |
| `deny` | Deny the request. | Continue. | Allowed | Not allowed |
| `accept` | Allow the request; later rules aren't evaluated. | Continue. | Not allowed | Not allowed |
| `set` | Apply its entries, then continue. | Continue. | Not allowed | Required |

- **End of list.** After the last rule, the request is allowed. An empty rule list allows everything with default settings.
- **Settings accumulate.** Later `set` rules overwrite values from earlier ones. Settings are those accumulated until evaluation stopped, so `set` rules after a deciding `deny` or `accept` don't apply.
- **Denial.** A denied request gets `403 ACCESS_DENIED` (see [Errors](/docs/sentinel/v2/reference/errors/)). `error` is the deciding rule's `message`, or `Denied by access rules (rule N).` without one:

```json
{ "code": "ACCESS_DENIED", "error": "Origin not allowed.", "statusCode": 403 }
```

- **After an allow.** `penalty.add` is applied to the client's penalty, then `rateLimit.limits` is enforced. Denied requests add no penalty.

### Monitor mode

A rule with `"monitor": true` is evaluated as written but has no effect: it never denies, allows or stops evaluation, and its `set` entries aren't applied. It is validated as if it were live, so clearing the flag always saves.

| Action | A monitored rule *fires* when | Instead of |
| --- | --- | --- |
| `allow` | its conditions don't hold | denying |
| `deny` | its conditions hold | denying |
| `accept` | its conditions hold | allowing and stopping (later rules still run) |
| `set` | its conditions hold | applying its entries |

Fired monitored rules are listed in the request log's `context.monitor` (a monitored `set` without conditions fires on every request and isn't listed). Later rules see only live state: a monitored `classifier.*` entry doesn't change a later `risk` condition. Monitored `threat` and `threatVerdict` conditions still trigger the threat lookup.

## Combining conditions

| Construct | Semantics |
| --- | --- |
| Several conditions | Joined by `conditionsOperator`: `and` (default) or `or`. No nesting; split complex logic across rules. |
| Several values in one condition | With `=`, the condition holds when the request value matches *any* value. |
| Negation | `!=` is the exact negation of `=`: it holds when the request value matches *none* of the values. |
| Missing request value | When the request has no value (no `Origin`/`Referer`, no `Accept-Language`, unknown country, no network flags, unsigned request for `agent`), `=` is false and `!=` is true. |
| Ranges | Combine two comparisons with `and`, e.g. `penalty >= 2` and `penalty < 6`. |

## Operators

| Operator | Meaning | Fields | Values |
| --- | --- | --- | --- |
| `=` | matches any value | all | 1–100 |
| `!=` | matches no value | all | 1–100 |
| `>` | greater than | `penalty`, `risk` | exactly 1 |
| `>=` | greater than or equal | `penalty`, `risk` | exactly 1 |
| `<` | less than | `penalty`, `risk` | exactly 1 |
| `<=` | less than or equal | `penalty`, `risk` | exactly 1 |

Comparison operators on any other field fail validation with `'>' is only valid on numeric fields (penalty, risk)`.

## Condition fields

| Field | Matches against | Values | Matching | Example |
| --- | --- | --- | --- | --- |
| `agent` | The request's Web Bot Auth signature. | `verified`, `unverified`, an agent name, or a kind: `crawler`, `ai_training`, `ai_search`, `user_fetch`. | [Wildcard](#wildcards). A verified agent matches `verified`, its name and its kind; a signed request that fails verification matches `unverified`; unsigned requests match nothing, so `*` matches every signed request. | `["verified"]` |
| `country` | The client IP's country, from the `[ip_resolver]` providers. | ISO 3166-1 alpha-2 codes, `high_risk`, `eu`; one value may hold several separated by `,`, `;` or whitespace. | Case-insensitive, no wildcards. Unknown codes fail with `unknown country code or list 'xx'`. | `["high_risk", "us ca"]` |
| `headers` | Request headers. | `Name: pattern`, or a bare `Name`. | Header name case-insensitive. Matches when any value of the header matches the wildcard pattern; a bare name (or empty pattern) checks presence. Header values that aren't visible ASCII are skipped. | `["X-Client: mobile-*", "X-Debug"]` |
| `ip` | The client IP. | IP addresses or CIDR ranges (IPv4 or IPv6). | No wildcards. IPv4-mapped IPv6 clients match IPv4 ranges. | `["10.0.0.0/8", "2001:db8::/32"]` |
| `language` | Each `Accept-Language` tag, without `;q=` weights; `*` tags are ignored. | Language tags. | Wildcard. | `["en", "de-*"]` |
| `method` | The HTTP method. | Method names. | Wildcard. | `["POST"]` |
| `network` | The client IP's network flags. | `fixed` (flags known, none set), `mobile`, `hosting`, `proxy`, `tor`. | Case-insensitive, no wildcards. Each flag matches on its own: a Tor exit in a data center matches both `tor` and `hosting`. | `["hosting", "proxy"]` |
| `origin` | `Origin` (unless absent, unparseable or `null`), else `Referer`, reduced to `scheme://authority`. | Origins. | Wildcard. | `["https://example.com", "https://*.example.com"]` |
| `path` | The request path, without the query string. | Paths. | Wildcard. | `["/v2/verify"]` |
| `penalty` | The client's penalty (0–10) from before this request. | Numbers 0–10 with at most one decimal. | Numeric; `=`/`!=` compare exactly. No wildcards or ranges. | `["4"]` with `>=` |
| `risk` | `GET /v2/inspect`'s risk (0–10) without a time zone: device, IP and location rules (`HIGH_RISK_COUNTRY` of the IP's country), capped at 10. | Numbers 0–10 with at most one decimal. | As `penalty`. Computed with the `classifier.*` settings of `set` rules *before* this rule. | `["5"]` with `>=` |
| `signal` | Classifier rules scoring above 0 for the request. | Device rules `ACCEPT_HEADER_MISSING`, `ACCEPT_LANGUAGE_HEADER_MISSING`, `BOT`, `CLI`, `LIBRARY`, `USER_AGENT_HEADER_MISSING`, `USER_AGENT_HEADER_UNCOMMON`; IP rules `BOT`, `HIGH_RISK_COUNTRY`, `HOSTING`, `MALICIOUS`, `PROXY`, `THREAT_SCORE`, `TOR`. | Case-insensitive. All listed rules run regardless of `classifier.enableRules`/`disableRules`; `classifier.trustedApps` and `classifier.highRiskCountries` from earlier rules apply. Rules that need the `/v2/verify` body fail validation. | `["MALICIOUS", "TOR"]` |
| `threat` | The client IP's threat-list matches. | A source name (`manual`, `auto`, or a threat source's name) or a kind: `bot`, `malicious`, `probe`, `proxy`, `tor`, `crawler`, `ai_training`, `ai_search`, `user_fetch`. | Wildcard. Private IPs have no matches; other [non-routable IPs](/docs/sentinel/v2/features/threat-intelligence/#private-and-non-routable-ips) match only manual entries. | `["tor", "malicious"]` |
| `threatVerdict` | The client IP's threat verdict. | `allow`, `block`, `none`. | Case-insensitive, no wildcards. `none` when no match decides (also for private IPs). The most specific entry with an action decides, otherwise any `allow` source, otherwise any `block` source. | `["block"]` |

`country`, `network`, IP signals and `risk` resolve the client IP through the `[ip_resolver]` providers once per request, within 1 second; after a timeout only the threat data is known. See [IP resolvers](/docs/sentinel/v2/configure/ip-resolvers/) and [Threat intelligence](/docs/sentinel/v2/features/threat-intelligence/).

## Wildcards

`agent`, `headers` patterns, `language`, `method`, `origin`, `path` and `threat` values are wildcard patterns, matched against the whole value, case-insensitively.

| Syntax | Meaning | Example |
| --- | --- | --- |
| `*` | Any sequence of characters, including none. | `/v2/*` |
| `?` | Makes the preceding character optional. | `colou?r` matches `color` and `colour` |
| `\x` | Literal `x`. | `\*`, `\?`, `\\` |

A `?` at the start of a pattern or after `*` fails with `'?' must follow a character`; a trailing `\` fails with `dangling '\'`.

## Set fields

Fields use `feature.parameter` notation. Values are strings. Defaults apply when no matching rule sets the field.

### Rate limiting

| Field | Values | Default | Description |
| --- | --- | --- | --- |
| `rateLimit.limits` | Comma-separated `points/duration[(params)]`, e.g. `10/1m,100/1h(sliding&key=ip)`. | — (no limit) | Enforced on every API-key request after the rules allow it; the first exceeded limit answers `429 RATE_LIMITED` (later limits aren't counted). Param `key`: `edk` (default; per device key: client IP, User-Agent, Accept-Language, rotated daily), `ip` (per client IP) or `uid` (one bucket per scope); case-insensitive, last `key=` wins. Other params follow `[rate_limit] global`. |
| `rateLimit.scope` | `apiKey`, `account` (case-sensitive) | `apiKey` | Buckets per API key or shared by all API keys of the account. Also buckets the `/v2/classifier` body's `rateLimit`. |

### Proof-of-work

| Field | Values | Default | Description |
| --- | --- | --- | --- |
| `pow.algorithm` | `PBKDF2/SHA-256`, `PBKDF2/SHA-384`, `PBKDF2/SHA-512`, `SHA-256`, `SHA-384`, `SHA-512`, `ARGON2ID`, `SCRYPT` (case-insensitive) | `PBKDF2/SHA-256` | Challenge algorithm. `ARGON2ID` and `SCRYPT` are memory-hard; widgets need their separately imported solvers. |
| `pow.cost` | Integer; range depends on the algorithm (below). | `5000` (PBKDF2, SHA), `2` (`ARGON2ID`), `65536` (`SCRYPT`) | PBKDF2 iterations or SHA hash rounds: 1–1000000. `ARGON2ID` passes: 1–10. `SCRYPT` N: a power of 2 from 1024 to the largest power of 2 within `[pow] max_memory_cost` (block size 8, so N is also memory in KiB). |
| `pow.memoryCost` | Integer KiB, 1024 to `[pow] max_memory_cost` (default `262144`). | `65536` | `ARGON2ID` memory. Other algorithms ignore it. |
| `pow.counter` | `N` or `MIN-MAX`, within 1–1000000. | `1-15000` (PBKDF2), `1-1000` (SHA), `1-200` (`ARGON2ID`, `SCRYPT`) | Solution counter; a range picks a random value per challenge. Start ranges at 1; see [Proof-of-work](/docs/sentinel/v2/features/proof-of-work/#tuning). |
| `pow.expires` | Duration from `10s` to `24h`, e.g. `20m`. | `20m` | Challenge lifetime. |

A `pow.cost` must fit every algorithm it can end up with when any subset of rules matches: the `pow.algorithm` of its own rule, or else of every earlier rule and the default; plus the algorithm of every later rule that doesn't set its own `pow.cost`. Set `pow.algorithm` and `pow.cost` in the same rule to avoid conflicts. Stored rules aren't rechecked if `[pow] max_memory_cost` changes; challenge issuing clamps costs to the algorithm's range.

### Classifier

| Field | Values | Default | Description |
| --- | --- | --- | --- |
| `classifier.ai` | `true`, `false` | `false` | Turns on the AI decider for `/v2/verify`, `/v2/classifier` and `/v2/eml` (needs a `[classifier.ai]` provider): `AI_SPAM`, `AI_SCAM`, `AI_ABUSE`, `AI_GIBBERISH`, plus `AI_OFF_TOPIC` and `AI_CUSTOM` below. |
| `classifier.aiInstructions` | Text, at most 1000 characters after trimming; empty = none. | — | What to reject. Enables `AI_CUSTOM`. |
| `classifier.aiPurpose` | Text, at most 1000 characters after trimming; empty = none. | — | What the form is for. Enables `AI_OFF_TOPIC`. |
| `classifier.aiSignals` | List of `country`, `network`, `device`, `languages`, `timeZone`, `threats`, `emailDomain`, `rules` (case-insensitive); empty = none. | `country network device languages timeZone` | Detected signals sent to the AI provider with the text. The IP, full email address and payload are never sent. |
| `classifier.disableRules` | List of [classifier rule](/docs/sentinel/v2/reference/classifier-rules/) names (case-insensitive); empty = none. | — | Default for `/v2/verify` and `/v2/classifier` (a request body's `disableRules` replaces it). With a disable list, every rule but those runs. |
| `classifier.enableRules` | List of classifier rule names; empty = none. | — | Default for `/v2/verify` and `/v2/classifier`. Without a disable list, only the enabled rules run; with neither, all run. |
| `classifier.fields` | `true`, `false` | — (challenge's `?fields=`) | Overrides `serverVerificationFields`: whether the widget sends its form fields to `/v2/verify`. |
| `classifier.highRiskCountries` | ISO 3166-1 alpha-2 codes and lists `high_risk`, `eu` (case-insensitive); empty = none. | `high_risk` | A location in one of them scores 2 on `HIGH_RISK_COUNTRY`. `high_risk`: by cd cf cu il iq ir kp lb ly mm ng ru sd so sy ua ve zw; `eu`: the 27 EU members. |
| `classifier.similarityGroups` | Up to 50 training groups (`a-z0-9_-`, at most 64 characters, starting with a letter or digit), `builtin:`-prefixed groups, or `*` (case-insensitive); empty = none. | `*` | Groups `SIMILARITY` and `NEAR_DUPLICATE` compare text against. Unknown groups are skipped. |
| `classifier.trustedApps` | Up to 20 app names (ASCII letters, digits, `-_.+`, at most 64 characters); empty = none. | `altcha-app altcha-rn altcha-flutter` | A User-Agent containing the product token `name/version` of one of them (case-insensitive) scores 0 on `USER_AGENT_HEADER_UNCOMMON`, `CLI` and `LIBRARY`. |

Lists are separated by `,`, `;` or whitespace.

### Header entropy

| Field | Values | Default | Description |
| --- | --- | --- | --- |
| `headerEntropy.limit` | `N/DURATION`, N 1–99, DURATION `1m` to `24h`, e.g. `10/4h`. | — (off) | Distinct device header sets per client IP and `rateLimit.scope` on `/v2/challenge` and `/v2/inspect`, in a fixed window from the first one. More than N answer `429 HEADER_ENTROPY` until the window ends. |
| `headerEntropy.penalty` | Number 0–10, at most one decimal. | `1` | Added to the client's penalty for each new distinct header hash beyond the first; `0` turns it off. |

### Human Interaction Signature

| Field | Values | Default | Description |
| --- | --- | --- | --- |
| `his.blockThreshold` | Number 0.1–1, at most two decimals. | `0.8` | HIS score (higher means more bot-like) at or above which the client is treated as a bot: blocked in `strict`, penalized in `relaxed`, only logged in `monitor`. |
| `his.codeChallenge` | `true`, `false` | `false` | With `his.mode` not `off`, a code challenge also collects HIS data while the code is entered and `/v2/verify` scores it. Widgets that don't send it are blocked in `relaxed`/`strict`. |
| `his.hashTtl` | Duration from `10m` to `7d`, e.g. `12h`. | `12h` | How long a signature hash is remembered for replay detection. |
| `his.mode` | `off`, `monitor`, `relaxed`, `strict` (case-insensitive) | `off` | Turns on HIS scoring of `POST /v2/challenge`. While not `off`, `GET /v2/challenge` doesn't count against `rateLimit.limits`. |
| `his.penalty` | Number 0–10, at most one decimal. | `1` | Added to the client's penalty in `relaxed` and `strict` when HIS data is missing, replayed, or scores at or above `his.blockThreshold`; `0` turns it off. |

See [Human Interaction Signature](/docs/sentinel/v2/features/human-interaction-signature/).

### Penalty

| Field | Values | Default | Description |
| --- | --- | --- | --- |
| `penalty.add` | Number -10 to 10, at most one decimal. | — | Added to the client's penalty (clamped to 0–10) when evaluation ends in allow, before `rateLimit.limits`. |

### Code challenge

| Field | Values | Default | Description |
| --- | --- | --- | --- |
| `codeChallenge.alphabet` | 2–36 ASCII letters or digits, at least 2 distinct (case-insensitive, duplicates ignored). | `234579` | Characters of the code. |
| `codeChallenge.audio` | `true`, `false` | `true` | `false` drops the audio from the challenge; `GET /v2/challenge/audio/<token>.wav` then answers 404. |
| `codeChallenge.audioLanguages` | Voice language codes (see [Languages](/docs/sentinel/v2/features/code-challenge/#languages)), case-insensitive, separated by `,`, `;` or whitespace; unknown codes are rejected. Empty: every voice. | Every voice | Voices the audio may use: the first `language` / `Accept-Language` candidate on the list, else the first listed voice that speaks the code (instead of `en`). No listed voice for the code: the challenge has no audio. |
| `codeChallenge.enabled` | `true`, `false` | `false` | Adds a code challenge to `/v2/challenge`. `/v2/verify` requires the code (case-insensitive); a wrong or missing code answers `INCORRECT_CODE` and burns the challenge. |
| `codeChallenge.imageDifficulty` | `low`, `standard`, `high` (case-insensitive) | `standard` | Image style; `high` draws more and larger noise dots. |
| `codeChallenge.length` | `N` or `MIN-MAX`, within 4–8. | `5` | Code length; a range picks a random length. |

See [Code challenge](/docs/sentinel/v2/features/code-challenge/).

## Limits

| Item | Limit |
| --- | --- |
| Rules per security group | 100 |
| Conditions per rule | 20 |
| Values per condition | 1–100 (comparison operators: 1) |
| Characters per condition value (trimmed) | 1–500 |
| Set entries per `set` rule | 1–10, no duplicate fields |
| `name` | 100 characters |
| `message` | 200 characters |
| `classifier.aiPurpose`, `classifier.aiInstructions` | 1000 characters |

## Validation errors

Rules are validated on create and update. An invalid list returns `400 INVALID_RULES`; `error` is `path: message`, with a path such as `rules[2].conditions[0].value[1]`.

| Path | Message |
| --- | --- |
| `rules` | `at most 100 rules` |
| `rules[i].name` | `at most 100 characters`; `must not contain ',' or start with '#'` |
| `rules[i].message` | `at most 200 characters`; `only allow and deny rules have a message` |
| `rules[i].set` | `a set rule needs 1 to 10 entries`; `only set rules have set entries` |
| `rules[i].set[k].field` | `duplicate set field '…'` |
| `rules[i].set[k].value` | The field's range, e.g. `must be a duration from 10s to 24h, e.g. '20m'`; for `pow.cost` conflicts, the algorithm and a hint such as `set pow.algorithm and pow.cost in the same rule`. |
| `rules[i].conditions` | `at most 20 conditions` |
| `rules[i].conditions[j].operator` | `'…' is only valid on numeric fields (penalty, risk)` |
| `rules[i].conditions[j].value` | `1 to 100 values`; `'…' takes exactly one value` |
| `rules[i].conditions[j].value[k]` | `must be 1 to 500 characters`; `invalid IP or CIDR '…'`; `invalid header name '…'`; `unknown threat verdict '…' (use allow, block or none)`; `unknown network '…' (use fixed, mobile, hosting, proxy or tor)`; `'…' is not a signal (use …)`; `must be a number from 0 to 10 with at most one decimal`; wildcard syntax errors. |

Unknown keys, actions, fields and operators are rejected when the request body is parsed.

## Examples

Restrict a public key to your origins, let your office through, and block threats:

```json
[
{
"name": "office",
"action": "accept",
"conditions": [{ "field": "ip", "operator": "=", "value": ["203.0.113.0/24"] }]
},
{
"name": "origins",
"action": "allow",
"message": "Origin not allowed.",
"conditions": [
  { "field": "origin", "operator": "=", "value": ["https://example.com", "https://*.example.com"] }
]
},
{
"name": "threats",
"action": "deny",
"message": "Blocked by threat intelligence.",
"conditions": [
  { "field": "threatVerdict", "operator": "=", "value": ["block"] },
  { "field": "path", "operator": "!=", "value": ["/v2/verify"] }
]
}
]
```

Base limits plus escalation by risk and penalty, with one rule in monitor mode:

```json
[
{
"name": "base",
"action": "set",
"set": [
  { "field": "rateLimit.limits", "value": "50/10m" },
  { "field": "headerEntropy.limit", "value": "10/4h" }
]
},
{
"name": "elevated",
"action": "set",
"conditionsOperator": "or",
"conditions": [
  { "field": "risk", "operator": ">=", "value": ["4"] },
  { "field": "penalty", "operator": ">", "value": ["2"] },
  { "field": "signal", "operator": "=", "value": ["BOT", "CLI", "LIBRARY", "MALICIOUS", "PROXY", "TOR"] }
],
"set": [
  { "field": "codeChallenge.enabled", "value": "true" },
  { "field": "pow.counter", "value": "1-30000" }
]
},
{
"name": "memory-hard",
"action": "set",
"conditions": [{ "field": "risk", "operator": ">=", "value": ["7"] }],
"set": [
  { "field": "pow.algorithm", "value": "ARGON2ID" },
  { "field": "pow.cost", "value": "3" },
  { "field": "pow.memoryCost", "value": "65536" }
]
},
{
"name": "repeat-offenders",
"action": "deny",
"monitor": true,
"message": "Too many failed attempts.",
"conditions": [{ "field": "penalty", "operator": ">=", "value": ["8"] }]
}
]
```
