Writing rules

Rule format

A rule is a JSON object. It fires when all of its conditions match, then runs its action. Add it to the plugin config under rules_request — every custom rule goes there whatever its phase, and the engine runs it in the phase named by its phase field.

{
  "id": "1234",
  "phase": "access",
  "conditions": [
    {
      "op": "rx",
      "transform": ["urlDecodeUni"],
      "value": "['\"`]+.*['\"`;&|]+",
      "variables": ["request.arg.value"],
      "multi_match": false
    }
  ],
  "action": { "fixed_response": { "status_code": 403, "body": "Forbidden\r\n" } },
  "log": true,
  "message": "Example injection rule",
  "tags": ["injection", "virtual-patching"]
}

JSON Schema

The rule format is published as a JSON Schema (draft 2020-12), so an editor can complete and check rules as you type them and CI can reject a broken pack before it reaches a gateway. Two documents, both served from this site and both resolvable offline from docs/schema/ in the repository:

In your editor

Point the schema at your rule files and you get completion on operators, transformations and action names, plus an immediate error on a field Karna would have ignored in silence.

{
  "json.schemas": [
    {
      "fileMatch": ["global-rules.d/*.json", "karna-rules*.json"],
      "url": "https://karna.sicuranext.com/docs/schema/karna-rules.schema.json"
    },
    {
      "fileMatch": ["karna-rule-*.json"],
      "url": "https://karna.sicuranext.com/docs/schema/karna-rule.schema.json"
    }
  ]
}

A single-rule file can also carry the reference itself, which works in any editor with no per-project configuration:

{
  "$schema": "https://karna.sicuranext.com/docs/schema/karna-rule.schema.json",
  "id": "100001",
  "phase": "access",
  "conditions": [
    { "op": "libinjection_sqli", "value": "", "variables": ["request.arg.value"] }
  ],
  "action": { "fixed_response": { "status_code": 403 } },
  "message": "SQLi in a request argument"
}

$schema is the only non-rule key the schema accepts, and Karna ignores it at load, so a file annotated this way stays deployable as is.

On the command line

The repository ships a validator that resolves the schemas locally, so it needs no network. It takes a single rule, a pack, or a JSON Lines file of rules, and exits non-zero on the first bad file.

pip install jsonschema
python3 scripts/validate-rules.py global-rules.d/*.json

# ok   global-rules.d/00-exclusions.json (4 rule(s))
# FAIL global-rules.d/10-blocking.json (2 rule(s))
#   conditions[0].variables[0]: 'ARGS' does not match ...
#   action: Additional properties are not allowed ('block' was unexpected)

Any standard validator works just as well, which is the point of publishing a schema rather than a linter:

# python
check-jsonschema --schemafile docs/schema/karna-rules.schema.json global-rules.d/*.json

# node
npx ajv-cli validate --spec=draft2020 \
    -r docs/schema/karna-rule.schema.json \
    -s docs/schema/karna-rules.schema.json \
    -d "global-rules.d/*.json"

Wire whichever one you use into CI on the repository that holds your pack. A global rules pack reaches every service at once, so a rule dropped at load for a typo is a gap you find in the logs rather than in review.

What it catches, and what it cannot

The schema is strict where being strict is safe. Unknown fields are rejected everywhere, because Karna ignores them: a misspelled tags or transform costs you the behaviour you thought you had written, with nothing in the logs to say so. It also enforces the operator and transformation vocabularies, requires an argument for the operators that take one, and requires type on set_variable, where a missing scope means the write is silently dropped.

Variables are checked on their namespace only (request., response., tx:, redis., …), which is enough to reject a ModSecurity name such as ARGS or a typo in the prefix, but not enough to prove a full name resolves. That distinction matters: a variable that resolves to nothing quietly disables a rule, and paired with isSet and negated it makes the rule fire on every request. Beyond the shape, the schema says nothing about whether a rule is correct — a valid rule can still have a regex that never matches. Test in detection-only mode first.

Conditions

Each condition applies its operator to one or more variables, optionally after a transformation chain. A condition matches if the operator matches on any of its resolved values.

Phases

Variables

Variables name what a condition inspects. Many are arrays (e.g. all header values). Append :<selector> to target a specific named element, for example request.header.value:host or request.arg.value:username.

Condition variables

Macro-only names

These are not condition variables. They live in the request’s inspection table, which Karna builds in header_filter, so they resolve as %{…} macros in set_variable and redis_incr_key from header_filter onward, and in set_log_fields at log time. Used in a condition they resolve to nothing and the rule never fires.

Operators

The op field names one operator. An operator not in this set never matches. CRS operators (@detectSQLi, @streq, @detectXSS, …) are translated to these names when SecLang is parsed.

Negation

Every binary operator can be negated. The canonical form is a separate boolean field, not a ! prefix:

{
  "op": "isSet",
  "negated": true,
  "value": "",
  "variables": ["request.header.value:content-type"]
}

Semantics: a negated condition fires when the positive match fails and the value is present. A missing variable does not satisfy a negated condition. The one exception is isSet with negated: true, which is the way to spell "variable is absent" and so fires on a missing variable.

Three things count as "not absent", so a negated isSet does not fire on them: a target removed by a ctl:ruleRemoveTargetById / ruleRemoveTargetByTag exclusion (an excluded target is not a missing variable), an unreadable Redis key, and a Redis read with redis_inspect_enabled off. See Redis variables for how redis_on_error resolves the last two.

Two things do count as absent, and both block every request when you did not mean them to: a variable name no resolver recognises (a typo; Karna warns about it at rule load, see above), and a response.* variable used by an access-phase rule. Both show up on the first request after deploy.

A rule that carries rule_control cannot also use a negated isSet: it is refused at load with an error naming the rule id. Such a rule applies its ctl:* side effects when it matches, so it can switch detection rules off — and keyed on absence it would fire on ordinary traffic, disabling detection for every request. Key the exclusion on something the request actually carries.

For back-compat the engine still accepts "op": "!rx", but new rules should use negated.

Transformations

Listed in transform, applied in order to each value before the operator runs. There are no implicit transforms — what you list is what runs. Results are cached per request.

Actions

The action object decides what happens on a match. Side-effect actions (set_variable, set_log_fields, redis_incr_key, redis_set, redis_sadd, redis_del) fire whether or not the request is blocked. Terminal actions only block when engine_blocking_mode is on.

fixed_response

"action": {
  "fixed_response": {
    "status_code": 403,
    "headers": { "content-type": "text/plain" },
    "body": "Forbidden\r\n"
  }
}

fix_matched_parts

Strips remove_chars_pattern from every matched target and forwards upstream. The audit log marks the entry action: "sanitized".

"action": {
  "fix_matched_parts": { "remove_chars_pattern": "[\"';&|`]*" }
}

rate_limit

Redis fixed-window counter on karna:rl:<rule_id>:<resolved key>. The increment and the window TTL run in one server-side script, so they cannot interleave and the counter can never be left without an expiry. The window is fixed, not sliding: increments inside it do not push the expiry out.

redis_set / redis_sadd / redis_del

Write cluster-wide state on a match. These are fire-and-forget side effects: synchronous in the access phase, deferred to a timer in later phases, and they never block the request themselves. Keys, values, and members accept the request-context macros. Pair them with a redis.<key> inspection rule to close an auto-ban loop — see the auto-ban example.

"action": {
  "redis_set": {
    "key": "ban:%{remote_addr}",
    "value": "1",
    "expire": 600
  }
}

set_variable

type is required (shared → kong.ctx.shared, plugin → kong.ctx.plugin). String values support %{var} macros — which names resolve depends on the phase, see Macros in actions.

"action": {
  "set_variable": {
    "name": "skip_js_challenge",
    "value": true,
    "type": "shared"
  }
}

set_log_fields

"action": {
  "set_log_fields": [
    { "name": "username", "value": "%{request.body.urlencode.value:username}" }
  ]
}

Macros in actions

Action fields that accept %{...} templates do not all draw on the same pool of names, and one group depends on the phase the rule runs in.

Request-context macros resolve in every phase — they are read straight off the request: %{remote_addr}, %{request.method}, %{request.host}, %{request.scheme}, %{request.path}, %{request_headers.<name>} and %{connection.id}.

Per-client key macros pick one cookie out of the request or the response, or one request argument, and can hash any key macro. They are meant for Redis keys that mark a client (or an object the client works on) in one request and check it in a later one.

Each argument macro names one source on purpose. There is no macro that takes the argument from “the query or the body”: the client would choose where to send it and so which key it lands on. If the same argument may arrive either way, write one rule per source.

An absent value never builds a key. When the cookie or the argument is missing, has an empty value (sid=, line_id=, or a deletion Set-Cookie), or a hashed macro has nothing to hash, the key would be the same for every such client. So the write actions (redis_set, redis_sadd, redis_del, redis_incr_key) skip the write, a rate_limit keyed on it counts nothing and bans nothing, and the redis.<key> read is unknown: neither isSet nor its negated form matches, and Redis is not queried, whatever redis_on_error says. Skips are logged at debug level. %{request_headers.<name>} keeps its older behaviour, a missing header resolves to an empty string, for compatibility with existing rules; use %{sha256:request_headers.<name>} when a missing header must not share a key.

[
  {
    "id": "cart-mark", "phase": "header_filter",
    "conditions": [ { "variables": ["response.status"], "op": "eq", "value": "200" } ],
    "action": { "redis_set": { "key": "cart:%{sha256:request_cookies.sid}:t", "expire": 900 } }
  },
  {
    "id": "checkout-needs-cart", "phase": "access",
    "conditions": [
      { "variables": ["request.path"], "op": "beginsWith", "value": "/checkout" },
      { "variables": ["redis.cart:%{sha256:request_cookies.sid}:t"], "op": "isSet", "negated": true }
    ],
    "action": { "fixed_response": { "status_code": 403 } }
  }
]

A request to /checkout with no sid cookie at all does not match the second rule (unknown, not absent); add a separate condition on request.cookie.value:sid if such requests must be blocked too.

[
  {
    "id": "line-edit-count", "phase": "access",
    "conditions": [ { "variables": ["request.path"], "op": "eq", "value": "/cart/edit" } ],
    "action": {
      "redis_incr_key": { "key": "line:n:%{sha256:request.body.urlencode.value:line_id}", "expire": 1800 },
      "redis_set": { "key": "line:young:%{sha256:request.body.urlencode.value:line_id}", "expire": 60, "nx": true }
    }
  },
  {
    "id": "line-edited-too-often", "phase": "access",
    "conditions": [
      { "variables": ["request.path"], "op": "eq", "value": "/cart/edit" },
      { "variables": ["redis.line:n:%{sha256:request.body.urlencode.value:line_id}"], "op": "gt", "value": "10" },
      { "variables": ["redis.line:young:%{sha256:request.body.urlencode.value:line_id}"], "op": "isSet", "negated": true }
    ],
    "action": { "log_only": true }
  }
]

The first rule counts the edits of each line over a fixed 30-minute window and marks the line “young” for 60 seconds after its first edit (nx: later edits do not push the mark forward). The second one logs a line edited more than ten times and still edited after its first minute. A request without line_id is not counted and matches neither rule.

Two consequences to keep in mind. The client controls its cookies and its arguments, so a rate_limit keyed only on a cookie is skipped by a client that drops the cookie, and reset by one that changes it; pair it with a limit on %{remote_addr} when the limit is a defence rather than a fairness rule. And sha256: is unsalted: it keeps a random session id out of Redis, but a low-entropy value (an IP address, a short user id) can be recovered from its hash by trying every candidate.

Every other rule variable (%{request.header.value:host}, %{request.body.json.value:username}, %{response.status}, …) comes from the request’s inspection table, which Karna builds in header_filter. Used by a rule in the access phase, such a macro stays literal — the value does not exist yet.

set_log_fields is the one field resolved purely from the inspection table: it runs at log time, when the table is complete, and its value must be a single %{…} macro rather than a template with text around it. Most request-context names are inspection-table keys too, so they work there; %{request_headers.<name>} is not one and does not.

An unresolvable macro is left literal rather than raising an error, so a typo or an early-phase lookup shows up as a %{…} in the key instead of a failed request. Practical consequence: a Redis key written by one rule and read back by another should use only request-context macros, so both sides derive the same string in any phase.

log_only

A rule whose job is to notice something and record it, without touching the request. The ModSecurity pass,log shape. The match lands in the audit log as a real entry — id, message, tags, matched value — labelled action: "log", in both formats (matches[] in v2, messages[] in v1) and in both the access and header_filter phases.

"action": {
  "log_only": true,
  "set_log_fields": [
    { "name": "app_verdict", "value": "%{response.header.value:x-app-verdict}" }
  ]
}

Because the match is real, it satisfies auditlog_only_on_match. Without log_only a non-terminal rule is invisible under that setting: it fires, but nothing is written, so the only way to see it was to log every request. Several log_only rules can fire on one request and all are recorded — nothing stops the rule loop.

Redis inspection

A redis.<key> variable reads shared state from Redis at request time. The variable names the key (everything after redis., macros allowed), and the operator is the test — it decides which read command runs. Reads are off unless redis_inspect_enabled is on, and the client is locked to a read-only command whitelist.

Keys accept the request-context macros and the per-client key macros (one cookie, one Set-Cookie value, one query or urlencoded body argument, sha256:); the value needle accepts the same set minus %{request_headers.X}. The value needle resolves %{remote_addr} and %{request.*}. When Redis is unreachable, redis_on_error decides the outcome (default skip — the condition does not match and traffic flows).

{
  "op": "isSet",
  "value": "",
  "variables": ["redis.ban:%{remote_addr}"]
}

{
  "op": "redis_sismember",
  "value": "%{request_headers.authorization}",
  "variables": ["redis.revoked_tokens"]
}

Rule controls

A rule's rule_control array modifies rules (itself or others by id / tag). Useful for carving out false positives and patching CRS rules without editing the pack. When a rule carrying controls matches, they apply to every rule evaluated after it in the same request — this is the same surface SecLang exposes as ctl:*, and what an exclusion rule in a global pack or in rules_request uses.

"rule_control": [
  {
    "remove_variable_rx": {
      "name": "request.header.value",
      "rx": ".*(?:[Uu]ser\\-[Aa]gent|[Rr]eferer|[Aa]uthorization).*"
    }
  }
]

CRS overrides

To change what existing CRS rules do without rewriting them, use the config-level rule_action_overrides and rule_response_overrides arrays (see Configuration). Each entry has a selector and a payload; the first matching entry wins.

{
  "selector": { "tags": ["attack-xss"] },
  "action": { "type": "fix", "remove_chars_pattern": "[<>\"'&;]" }
}

SecLang rules

If you prefer ModSecurity syntax, put raw SecRule strings in custom_secrules. They are parsed at worker start and added to the global pool alongside the CRS. Only the canonical SecRule <vars> "<op>" "<actions>" form is parsed; SecRule* derivatives are skipped. ctl:* directives map to the rule controls above (ruleRemoveById, ruleRemoveByTag, ruleRemoveTargetById, ruleRemoveTargetByTag, ruleEngine=Off|DetectionOnly|On, requestBodyAccess=Off, auditLogParts=+C) and are read from every link of a chain, so ctl:ruleEngine=On on the last link fires only when the whole chain matched. Anything else after ctl: is ignored.

"custom_secrules": [
  "SecRule ARGS:debug \"@streq 1\" \"id:9001,phase:1,deny,status:403,msg:'debug arg blocked'\""
]

Global rules

Karna is attached per-service, so Kong has no native way to ship one rule pack to every service — a global plugin instance would be shadowed by the per-service ones. Global rules close that gap: one pack, evaluated on every service Karna is attached to, before local rules and the CRS.

There are two sources, independent and individually optional:

Pick disk when the rules belong in version control and ride your normal deploy (GitOps, DB-less, air-gapped, no Redis to run). Pick Redis when you need to change the pack on a running fleet without touching the nodes. Run both and the disk pack is the authoritative baseline the hot channel cannot overwrite — see Two sources, one pack.

From disk

Point KARNA_GLOBAL_RULES_PATH at a single .json file or at a directory, in which case every *.json inside is loaded in filename order — prefix the files (00-, 10-) and that prefix is the evaluation order. Each file is a bare JSON array of rules in the Karna rule format: the same objects you would put in rules_request, and the same array you would publish to Redis as the json payload, so a pack moves between the two channels verbatim. SecLang is not accepted on this channel.

docker run ... \
    -e KARNA_GLOBAL_RULES_PATH=/etc/kong/karna/global-rules.d \
    -v ./global-rules.d:/etc/kong/karna/global-rules.d:ro \
    karna:latest

# ./global-rules.d/00-exclusions.json   -> evaluated first
# ./global-rules.d/10-blocking.json

The pack is read once per worker at init_worker, synchronously, so it is live before the first request — there is no cold-start window and no filesystem watcher. Editing a file takes effect on kong reload (which respawns the workers) or a container restart. On disk the filesystem is the trust anchor, exactly as for the CRS rules themselves, so the pack carries no signature.

At startup each worker logs one summary line at notice level (Kong's default): the path, how many files it read, how many rules ended up in each list, how many were dropped, and a sha256 fingerprint of the exact bytes the pack was built from. The fingerprint is how you check that every node in a fleet is running the same global rules; unlike a hand-written version field, it cannot be forgotten on an edit.

[karna] global rules: loaded file pack sha256:f2cc8ce2a430 from
  /etc/kong/karna/global-rules.d (2 file(s), 1 controls + 3 detection, worker 0)

From Redis — storage layout

One Redis hash, karna:global_rules, written atomically by a single HSET:

JSON rules are evaluated first (in author order), then SecLang rules (sorted by id). Rules default to "log": true.

Publishing to Redis

Use scripts/karna-rules.py — it validates, previews, signs, and publishes the pack in one atomic write. Set up once:

# 1. generate the signing key
openssl rand -hex 32

# 2. on every Kong node (see Configuration → Environment):
#    KARNA_REDIS_URL=redis://:pass@redis:6379/0
#    KARNA_GLOBAL_RULES_HMAC_KEY=<the key>
# 3. restart Kong once to pick up the env

# publish (the key comes from the env, never from argv)
export KARNA_GLOBAL_RULES_HMAC_KEY=...
./scripts/karna-rules.py --type global-rules \
    --redis redis://localhost:6379/0 \
    --json global_rules.json --seclang global_rules.conf

# dry-run first, if you like: add --dry-run
# inspect what is live: --show   (version, counts, signature status)
# recover your authoring files from Redis: --pull

Publishing only --json preserves the already-published SecLang payload (and vice versa) — pushing one format never wipes the other. Deleting the hash (DEL karna:global_rules) is the explicit off switch: workers clear the pack at the next poll.

Trust model

Redis is a transport, not a trust anchor. With KARNA_GLOBAL_RULES_HMAC_KEY set, a pack with a missing or invalid signature is rejected and the last known good pack stays active — write access to Redis alone is not enough to inject or weaken rules; the signing key is. Workers also refuse non-increasing versions, so an old signed pack cannot be replayed while they run (after a full Kong restart the counter resets; rotate the key if that residual matters to you). Without the key, packs are accepted unsigned and a loud warning is logged at startup — fine for a lab, not for production.

Two sources, one pack

When both are configured, the two packs are merged into the one the request path reads:

• Order — disk before Redis. Inside a source, author order (files in filename order, rules in array order).
• Duplicate ids — first wins. A rule id that already came from disk is discarded when it arrives again from Redis, with a warning naming both sides. So the hot channel can add rules but cannot silently replace a rule you deployed on disk with a weaker one carrying the same id. The same rule applies between two files in a directory: the earlier filename wins.

Blocking rules and exclusions in the same pack

A global pack can carry both, and their order in the file does not matter. At load time each pack is split in two lists:

• controls — rules with a rule_control and no action: CRS-style exclusions. They run first, on the multi-match path, so every matching exclusion contributes its ctl:* side effects, and they land in time to affect the global detection rules, the local rules and the CRS.
• detection — everything else, on the standard first-terminal-wins path with the full action dispatch (fixed_response, fix_matched_parts, rate_limit, set_variable, …). A rule that carries a rule_control next to a real action stays here, so it keeps that dispatch.

Without the split, a blocking rule matching early in the list would end the pass and quietly swallow an exclusion declared after it — visible only in detection mode, where the request continues to the CRS with fewer exclusions applied than the file says.

Evaluation order and failure posture

Global rules run after rule controls and CRS exclusion plugins (so per-service ctl:* exclusions and overrides can tame a global rule on one service without touching the pack) and before local rules and the CRS. Blocking behaviour follows each service's engine_blocking_mode — on a detection-only service a global rule logs instead of blocking. There is deliberately no per-service opt-out; tag your global rules (e.g. "tags": ["global-pack"]) so overrides can select them where exceptions are needed.

Supported phases match local rules: access, header_filter and mcp_event. @pmFromFile is not supported on this channel — a global pack ships no data files and must not reach into the engine's shared data-file store.

Failures are fail-open, granular and loud, because a broken global pack must never take a node down:

• A rule the engine could not evaluate — missing id / phase / conditions, an unsupported @pmFromFile, a phase that is never evaluated — is dropped with the id and the reason in the log. The rest of the pack stays active. Such a rule is not kept: a condition that can never match would look like coverage without being any.
• A file that cannot be read or does not decode is skipped with an error; the other files in the directory still load. A single-file pack that does not decode means no rules from disk, and the node keeps serving with the CRS, the local rules and any Redis pack.
• On a Redis outage or a rejected pack, workers keep the last known good Redis pack and log an error per failed poll. A worker that starts while Redis is down runs without the Redis pack until the first successful poll; the disk pack, the CRS and the local rules are unaffected.

TLS fingerprint: karna-tls-v1

Every TLS request carries a client fingerprint in the audit log (tls.fingerprint, both formats) and in the rule variables tls.fingerprint / tls.fingerprint_version. It is a JA3-like fingerprint reduced to the cipher suites the client offered: the one piece of ClientHello material nginx exposes in the HTTP phases for new and resumed sessions alike ($ssl_ciphers). It is not JA3 and not JA4; do not compare it with databases of either. Nothing negotiated enters it, so it is a property of the client stack, not of the server configuration.

The version string karna-tls-v1 names every detail below. Any change to any of them is a new version; v1 never changes.

# $ssl_ciphers as received (GREASE first, then Chrome's 15 suites)
0x9a9a:TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA:AES256-SHA
# canonical string (GREASE dropped, order kept)
karna-tls-v1|TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256,ECDHE-ECDSA-AES256-GCM-SHA384,ECDHE-RSA-AES256-GCM-SHA384,ECDHE-ECDSA-CHACHA20-POLY1305,ECDHE-RSA-CHACHA20-POLY1305,ECDHE-RSA-AES128-SHA,ECDHE-RSA-AES256-SHA,AES128-GCM-SHA256,AES256-GCM-SHA384,AES128-SHA,AES256-SHA
# tls.fingerprint = sha256(canonical), lowercase hex
32aad363139a0f2f7d9289b1a380ca95c8d099d8b3da6ceb747ebdb30557d489

Example: detect & block

Block header-borne SQL injection, with a carve-out for FP-prone headers.

{
  "id": "2201",
  "phase": "access",
  "conditions": [
    {
      "op": "libinjection_sqli",
      "transform": ["urlDecodeUni"],
      "value": "",
      "variables": ["request.header.value"]
    }
  ],
  "action": { "fixed_response": { "status_code": 403, "body": "Forbidden\r\n" } },
  "message": "SQL Injection: header-borne",
  "rule_control": [
    {
      "remove_variable_rx": {
        "name": "request.header.value",
        "rx": ".*(?:[Uu]ser\\-[Aa]gent|[Rr]eferer|[Aa]uthorization).*"
      }
    }
  ],
  "tags": ["injection", "attack-sqli"]
}

Example: sanitize, don't block

Strip XSS-shape characters from the name argument instead of blocking. GET /signup?name=O'Brien reaches the app as name=OBrien.

{
  "id": "sanitize-name-field",
  "phase": "access",
  "log": true,
  "conditions": [
    {
      "op": "rx",
      "transform": [],
      "value": "[<>\"'&;]",
      "variables": ["request.arg.value:name"]
    }
  ],
  "action": { "fix_matched_parts": { "remove_chars_pattern": "[<>\"'&;]" } },
  "tags": ["sanitize"],
  "message": "neutralize XSS-shape chars in name"
}

Example: rate limit

Cap /api/login to 5 attempts per minute per source IP.

{
  "id": "rl-login-per-ip",
  "phase": "access",
  "log": true,
  "conditions": [
    {
      "op": "beginsWith",
      "transform": [],
      "value": "/api/login",
      "variables": ["request.raw_path"]
    }
  ],
  "action": {
    "rate_limit": {
      "key": "%{remote_addr}",
      "limit": 5,
      "window_seconds": 60,
      "response": { "status_code": 429, "body": "Too many login attempts.\r\n" }
    }
  },
  "message": "login rate limit",
  "tags": ["ratelimit", "auth"]
}

Example: counter + threshold

Two rules: the first increments a Redis counter on a failed login (no session cookie set on a login POST); the second blocks once the counter is high. The read needs redis_inspect_enabled, and both rules key on the same Redis key so the write and read line up.

{
  "id": "count-failed-login",
  "phase": "header_filter",
  "conditions": [
    {
      "op": "beginsWith",
      "value": "/login",
      "variables": ["request.raw_path"]
    },
    {
      "op": "eq",
      "value": "POST",
      "variables": ["request.method"]
    },
    {
      "op": "isSet",
      "negated": true,
      "value": "",
      "variables": ["response.set_cookie.name:session"]
    }
  ],
  "action": {
    "redis_incr_key": { "key": "failed_login:%{remote_addr}", "expire": 300 }
  },
  "log": false
}

{
  "id": "block-failed-login",
  "phase": "access",
  "conditions": [
    {
      "op": "ge",
      "value": "5",
      "variables": ["redis.failed_login:%{remote_addr}"]
    }
  ],
  "action": { "fixed_response": { "status_code": 403, "body": "Too many login attempts.\r\n" } },
  "log": false
}

Example: distributed auto-ban

Two rules close the loop across every Kong node. The first writes a ban with a TTL when it catches an attack; the second blocks any request from a banned IP. Needs redis_inspect_enabled for the read and a shared Redis so all nodes see the same ban.

{
  "id": "ban-on-sqli",
  "phase": "access",
  "conditions": [
    {
      "op": "libinjection_sqli",
      "transform": ["urlDecodeUni"],
      "value": "",
      "variables": ["request.arg.value"]
    }
  ],
  "action": {
    "redis_set": {
      "key": "ban:%{remote_addr}",
      "value": "1",
      "expire": 600
    },
    "fixed_response": { "status_code": 403, "body": "Forbidden\r\n" }
  },
  "message": "SQLi — ban source for 10 min",
  "tags": ["attack-sqli"]
}

{
  "id": "block-banned",
  "phase": "access",
  "conditions": [
    {
      "op": "isSet",
      "value": "",
      "variables": ["redis.ban:%{remote_addr}"]
    }
  ],
  "action": { "fixed_response": { "status_code": 403, "body": "Forbidden\r\n" } },
  "message": "source is banned",
  "tags": ["banlist"]
}

Example: rate limit, then ban

A rate limit answers “how much traffic do I tolerate”. It does not answer “what do I do with a client that keeps hitting the limit”. Stretching window_seconds to express the second one also caps a legitimate client for the whole stretch: the rate you tolerate and how long you punish exceeding it are separate numbers, and they want separate counters.

One rule expresses both numbers: 5 requests per 10 seconds; after 20 refusals, banned for 2 hours.

{
    "id": "rl-login",
    "phase": "access",
    "conditions": [
      { "op": "beginsWith", "value": "/login", "variables": ["request.raw_path"] }
    ],
    "action": {
      "rate_limit": {
        "key": "%{remote_addr}",
        "limit": 5,
        "window_seconds": 10,
        "ban": {
          "key": "%{remote_addr}",
          "after_exceedances": 20,
          "duration_seconds": 7200
        }
      }
    },
    "log": true,
    "message": "login rate limit with temporary ban",
    "tags": ["ratelimit"]
}

Requests over the ordinary limit receive 429. The twentieth refusal creates the ban atomically and receives 403; later requests from the same identity receive 403 until the two hours expire. The counter is reset when the ban starts, so expiry opens a fresh rate-limit window.

With log: true, the audit log records the refusals and every enforced ban. Admitted requests stay quiet unless the rate-limit action sets log_all_matches: true.

Example: chained rule

Conditions are AND-ed. This rule fires only on a POST to /upload carrying a script-like filename.

{
  "id": "block-script-upload",
  "phase": "access",
  "conditions": [
    {
      "op": "eq",
      "value": "POST",
      "variables": ["request.method"]
    },
    {
      "op": "beginsWith",
      "value": "/upload",
      "variables": ["request.raw_path"]
    },
    {
      "op": "rx",
      "transform": ["lowercase"],
      "value": "\\.(php|phtml|jsp|asp)$",
      "variables": ["request.file"]
    }
  ],
  "action": { "fixed_response": { "status_code": 403, "body": "Forbidden\r\n" } },
  "message": "script upload blocked",
  "tags": ["upload"]
}

Example: TLS fingerprint & connection

Five patterns over tls.* and connection.id. They are documentation, not defaults: none ships enabled, and the fingerprints below are placeholders to replace with values read from your own audit log. Rule 5 shows the guard every fingerprint rule should carry.

{ "id": "tls-deny-fp", "phase": "access",
  "conditions": [ { "op": "within", "transform": [],
                    "value": "<fp-of-scanner-A> <fp-of-scanner-B>",
                    "variables": ["tls.fingerprint"] } ],
  "action": { "fixed_response": { "status_code": 403, "body": "Forbidden\r\n" } },
  "message": "TLS fingerprint on deny list", "tags": ["tls-fingerprint"] }

{ "id": "tls-sni-host", "phase": "access", "log": true,
  "conditions": [
    { "op": "eq", "value": "true", "transform": [], "variables": ["tls.enabled"] },
    { "op": "rx", "value": "^(.+)$", "transform": ["lowercase"], "variables": ["tls.sni"] },
    { "op": "eq", "value": "%{group:1}", "negated": true, "transform": ["lowercase"], "variables": ["request.host"] }
  ],
  "action": { "log_only": true },
  "message": "SNI does not match Host", "tags": ["tls-sni"] }

{ "id": "tls-ua-mismatch", "phase": "access", "log": true,
  "conditions": [
    { "op": "eq", "value": "complete", "transform": [], "variables": ["tls.capture_status"] },
    { "op": "rx", "value": "Chrome/\\d+", "transform": [], "variables": ["request.header.value:user-agent"] },
    { "op": "within", "negated": true, "transform": [],
      "value": "<fp-chrome-desktop> <fp-chrome-android> <fp-chrome-ios>", "variables": ["tls.fingerprint"] }
  ],
  "action": { "set_variable": { "type": "shared", "name": "karna_tls_ua_mismatch", "value": "%{tls.fingerprint}" } },
  "message": "Chrome UA with a non-Chrome TLS stack", "tags": ["tls-fingerprint", "bot"] }

{ "id": "tls-legacy-version", "phase": "access",
  "conditions": [ { "op": "within", "value": "TLSv1 TLSv1.1", "transform": [], "variables": ["tls.protocol"] } ],
  "action": { "fixed_response": { "status_code": 426, "body": "Upgrade Required\r\n" } },
  "message": "Legacy TLS version", "tags": ["tls-policy"] }

{ "id": "tls-fp-guarded", "phase": "access",
  "conditions": [
    { "op": "eq", "value": "complete", "transform": [], "variables": ["tls.capture_status"] },
    { "op": "within", "negated": true, "transform": [],
      "value": "<fp-allowed-app-1> <fp-allowed-app-2>", "variables": ["tls.fingerprint"] }
  ],
  "action": { "rate_limit": { "key": "%{connection.id}", "limit": 30, "window_seconds": 60 } },
  "message": "Unknown TLS client: throttled per connection", "tags": ["tls-fingerprint"] }