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 (request phase) or rules_response (response phase).

{
  "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"]
}

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.

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 does not validate variable names), 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_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 are macro-resolved (%{remote_addr}, %{request.method|host|scheme|path}, %{request_headers.X}). 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 resolved against the request.

"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}" }
  ]
}

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.

The key macros are %{remote_addr}, %{request.method|host|scheme|path}, and %{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.

"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",
  "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: 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"] }