Configuration options

Engine & blocking

The core switches: whether Karna blocks or only detects, and which rule sources are active.

CRS category toggles

The full CoreRuleSet is loaded once; these per-service switches decide which attack categories are evaluated for this service. A disabled category's rules are skipped in the eval loop (no per-request cost). All are gated by coreruleset_enabled and live under the coreruleset_rulesets record. Each defaults true except where noted.

Engine optimizations

Performance switches. All default on and are detection-neutral. Each degrades gracefully: if a native library is missing, the engine falls back to the pure-Lua path and never silently drops a check.

Validation gates & limits

Request-shape limits. Four of these run as always-on gates before the rule loops and fire regardless of engine_blocking_mode and the CRS toggles: allowed methods, path character limits, denied headers, and content-type/charset. Treat them as hard limits — to loosen, raise the value or extend the allow-list.

CRS-setup knobs

CRS-setup-style values, mapped at access-phase start into the tx.* variables CRS rules expect, so rules written against ModSecurity's TX:<name> resolve without a crs-setup.conf.

Body parsing

MCP (AI / Model Context Protocol)

Request- and response-side detection for the Model Context Protocol. Everything is off by default; Karna behaves identically to non-MCP traffic until mcp_enabled is set on a route.

CRS exclusion plugins

The OWASP project ships rule-exclusion plugins for specific apps (WordPress, Drupal, Nextcloud, phpBB, …). Karna reuses those upstream plugin repos verbatim — clone them into crs_plugins_path and list the ones to load.

Custom rules

Three ways to add your own detection. See Writing rules for the full format.

Action & response overrides

Change what an existing rule does at match time without editing the rule pack. Each entry is a JSON string with a selector (any of ids, id_ranges, tags, except_ids, except_tags, any) and a payload. First matching entry wins; the cached rule pack is never mutated.

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

Audit logging

Karna writes JSON audit logs to disk asynchronously. The log directory must be writable by the Kong worker user.

Redis

Redis is optional. It backs the rate_limit and redis_incr_key rule actions, the redis.<key> inspection variables, the redis_sismember / redis_hexists operators, and the redis_set / redis_sadd / redis_del write actions. The rest of the WAF works without it. With a shared Redis, these turn per-request, single-node state into cluster-wide state: a ban written on one node is seen by every node.

Debug

Identification endpoint

Karna answers a reserved path so you can confirm it is running in front of a service and read its build (version + git commit). It is always on — there is no config flag — and the reserved path never reaches the upstream.

curl -s https://your-host/.well-known/karna
# {"engine":"karna","version":"1.0.0","commit":"<sha>","commit_short":"<short>","built_at":"<iso8601>"}

The same version and commit appear in the engine block of every audit-log v2 entry. The commit is stamped at build time (the Docker image via a build arg, source installs via scripts/install.sh); an unstamped build reports commit: "unknown".

Environment variables

A few paths are read once at worker start via os.getenv(). Because nginx wipes the environment by default, any variable you set must be declared in the nginx main context with an env NAME; directive — point KONG_NGINX_MAIN_INCLUDE at a snippet like docker/main-env.conf.

# included via KONG_NGINX_MAIN_INCLUDE so workers can see these
env KARNA_CRS_PATH;
env KARNA_LIBINJECTION_SO;
env KARNA_LIBKA_RE2_SO;
env KARNA_PROFILE;