Lua sandboxing in AI Gateway

Some AI Gateway AI Policies let you run Lua code to change requests and responses, read the authenticated AI Consumer, or share values between AI Policies. Anyone who can create or edit one of these AI Policies can run code on your data planes, so sandboxing limits what that code can do. Sandboxing restricts the available environment and the set of modules that the code can load. All Lua (or LuaJIT) language features remain available.

The untrusted_lua data plane setting controls which restrictions apply. Each data plane node reads this setting from its own kong.conf file. The setting applies to every AI Policy on that node.

The following AI Policies run Lua code that you provide in their configuration:

Other AI Policies also use the sandbox when their configuration contains Lua expressions, functions, or templates:

• Templates, expressions, and functions: AI Custom Guardrail, Request Transformer, Route Transformer Advanced, Response Transformer Advanced, and Request Callout.
• Custom log fields: logging AI Policies such as File Log and OpenTelemetry.
• Message functions: messaging AI Policies such as Confluent, Confluent Consume, and Kafka Consume.

AI Gateway also generates a Pre-Function for each AI MCP Server of type conversion-only. A conversion-only server exposes its tools only through the listener AI MCP Servers that name it in config.sources. The generated Pre-Function returns a 404 to any request that doesn’t arrive through the internal connection that the listener uses. You don’t create this Pre-Function, and it runs in the sandbox like any other Pre-Function. If you set untrusted_lua to off, it can’t run, and tool calls through the listener fail. See Disable custom code execution.

The untrusted_lua setting accepts the following sandbox modes:

LuaJIT is not a secure sandbox for running malicious code.

The sandbox prevents trivial attacks and accidental changes to global state.

Use access controls alongside the sandbox, because it does not replace them.

Anyone who can create or edit an AI Policy that runs custom Lua can execute code on your data planes, so limit who can create these AI Policies.

We recommend strict, the default, because it blocks file I/O and network I/O, so custom Lua code can’t read files or call external services. Choose another mode only when you need what it provides:

• lax: Use it when the Lua code in an AI Policy has to make network calls or use vaults, the cache, or read-only configuration. Lax mode adds all of these to strict mode.
• off: Use it when your organization doesn’t allow custom Lua code. Setting off also stops the AI Policies that depend on the sandbox, and some of them make the data plane reject the entire configuration. Check the table in Disable custom code execution before you set it.
• sandbox and on: We don’t recommend either. The sandbox mode is deprecated, and on removes all restrictions.

AI Gateway data planes are self-managed, and the Konnect control plane has no setting for untrusted_lua. Set the parameter on each data plane node, in its kong.conf file or with the equivalent environment variable:

KONG_UNTRUSTED_LUA=strict

The value applies to one node, so set the same value on every data plane node. See untrusted_lua in the AI Gateway configuration reference.

The untrusted_lua_sandbox_requires and untrusted_lua_sandbox_environment parameters apply only in sandbox mode. Other modes ignore both parameters.

If you don’t need custom Lua code, set untrusted_lua=off. The data plane node still starts and runs AI Policies that don’t use the sandbox. What happens to an AI Policy with custom Lua depends on when AI Gateway checks its code:

• At request time: The AI Policy syncs normally, and a request that triggers it fails. The data plane logs loading of untrusted Lua code disabled because 'untrusted_lua' config option is set to 'off'.
• When the data plane loads the configuration: The data plane rejects the entire configuration and logs Error parsing function: loading of untrusted Lua code disabled because 'untrusted_lua' config option is set to 'off'. The node then applies no configuration changes until you remove the AI Policy.

Before you set off, check which of your AI Policies depend on the sandbox:

off also affects the Pre-Function that AI Gateway generates for each conversion-only AI MCP Server, as described in the following paragraphs.

With untrusted_lua=off, tool calls through a listener AI MCP Server that aggregates a conversion-only server fail with request failed: closed, because the generated Pre-Function can’t run. A direct request to the conversion-only server’s route returns an empty reply instead of a 404. The listener itself still answers MCP requests such as initialize.

An AI Custom Guardrail fails on every request, even when its configuration uses a plain string for request.url and no $(...) expression. The request returns a 500 error with the message failed to sanitize request: failed to invoke custom guardrail service: failed to render url: failed to render by template: loading of untrusted Lua code disabled because 'untrusted_lua' config option is set to 'off'.

Because the sandbox applies per data plane node, a configuration that works on one node can fail on a node where untrusted_lua is off.

Strict mode is an allowlist-based execution environment and is the default. You can load and run custom Lua code with some limitations. Most notably, strict mode disallows all file I/O and network I/O.

For example, in strict mode:

• require("resty.http") fails with require("resty.http") not allowed within sandbox.
• io.open, os.execute, and ngx.socket.tcp aren’t available.
• require("cjson") works.

The following lists show what strict mode allows. They differ from the Kong Gateway sandboxing reference as described in Differences in the allowlists.

Environment in strict mode

In strict mode you can use:

Available modules in strict mode

You can use the standard require function to load the following modules in strict mode:

Lax mode includes everything in strict mode, plus network I/O and some other functionality. It also adds kong.router.get_route, kong.router.get_service, and kong.configuration.

Environment in lax mode

Lax mode adds the following to the strict mode environment:

Available modules in lax mode

Lax mode adds the following modules to the strict mode modules:

The sandbox is the same one that Kong Gateway uses, but AI Gateway generates the resources that your code runs against. If you already use sandboxed Lua in Kong Gateway, the following differences apply to AI Policies.

Differences in the allowlists

The Kong Gateway sandboxing reference lists entries that AI Gateway doesn’t allow.

The following functions are nil in strict mode:

• kong.client.get_identity_realm_source, kong.client.set_identity_realm_source, and kong.client.get_principal
• kong.request.get_id, kong.request.get_raw_forwarded_path, and kong.request.get_raw_headers
• kong.table.new

The standard table.new function is available in place of kong.table.new.

kong.router.get_route and kong.router.get_service are also nil in strict mode. In AI Gateway, they are available only in lax mode.

AI Gateway doesn’t allow the following modules in strict mode or lax mode:

• Listed under strict mode in the Kong Gateway reference: MessagePack, binaryheap, ffi-zlib, kong.tools.glob, kong.tools.header, kong.tools.header-mapping, kong.tools.hostname, kong.tools.stack, lua_pack, luaxxhash, lxp, multipart, pl.url, resty.snappy, and xml2lua
• Listed under lax mode in the Kong Gateway reference: kong.enterprise_edition.tools.redis.v2.config_utils, kong.tools.oauth-client, kong.tools.redis.config_utils, and kong.tools.solace

AI Gateway saves an AI Policy that calls one of these functions in strict mode without an error, and the call fails when a request runs it.

To read the Kong Identity Principal of a request, use a condition with the principal.id field instead.

Generated Routes and Services

AI Gateway generates Routes and Services from your AI entities. In lax mode, PDK calls that return a Route or a Service, such as kong.router.get_route and kong.router.get_service, return those generated resources, not your AI Model, AI Agent, or AI MCP Server. The same applies to kong.db.routes, kong.db.services, and the kong.service.set_* calls. In strict mode, kong.router isn’t available, as described in Differences in the allowlists.

The generated names depend on the type of entity:

• AI Model: kong.router.get_route returns a Route named for the provider endpoint, such as openai-chat, and kong.router.get_service returns a Service named ai-gateway. AI Models that resolve to the same provider endpoint share one Route, so the Route name doesn’t identify a single AI Model.
• AI Agent and AI MCP Server: kong.router.get_service returns a Service with the same name as the entity. kong.router.get_route returns a Route with the entity name followed by -route, such as my-agent and my-agent-route.

The generated Routes and Services have no tags.

Consumers

An AI Consumer becomes a Kong Gateway Consumer with the AI Consumer’s name as its username. For an authenticated AI Consumer, kong.client.get_consumer returns a table with id and username. The table includes custom_id and tags when the AI Consumer sets them. The tags list contains the AI Consumer’s labels as key:value strings. kong.client.get_consumer_groups returns a table of the AI Consumer Groups that the AI Consumer belongs to, and each entry has a name. It returns nil when the AI Consumer has no groups.

An oauth AI Consumer behaves the same way. AI Gateway matches the token claim in config.consumer_claims to the AI Consumer’s custom_id. kong.client.get_consumer then returns that AI Consumer’s id, username, custom_id, and tags.

When you enable Kong Identity Principal mapping (config.principals) on an openid-connect AI Auth Strategy, set config.consumer_optional to true if the Principal has no linked AI Consumer. Otherwise, AI Gateway rejects the request with a 401, even when the Principal matches. When the Principal has no linked AI Consumer, kong.client.get_consumer returns nil.

A Pre-Function runs before authentication, so kong.client.get_consumer returns nil there. A Post-Function runs after authentication, so use a Post-Function to read the Consumer. A request without a valid key fails authentication, and the AI Policy doesn’t run.

Shared state

The AI Policies that run during a request share the kong.ctx.shared table. A global Pre-Function can write a value that a Post-Function scoped to an AI Model reads in the same request.

AI Policy configuration

The AI Gateway Pre-Function and Post-Function AI Policies accept only a field for each phase:

• certificate
• rewrite
• access
• header_filter
• body_filter
• log
• ws_handshake
• ws_client_frame
• ws_upstream_frame
• ws_close

The last four fields run in the WebSocket phases. The Pre-Function and Post-Function AI Policies don’t accept the deprecated config.functions field from the Kong Gateway Pre-Function plugin. The Exit Transformer AI Policy takes its code in config.functions, a list of functions.

You can apply Pre-Function and Post-Function AI Policies to an AI Model, AI MCP Server, AI Agent, or globally. You can’t apply them to an AI Consumer or an AI Consumer Group. You can’t apply an Exit Transformer AI Policy to an AI Consumer Group. See AI Policy scopes.

Konnect accepts a Pre-Function or Post-Function AI Policy attached to an AI Consumer or an AI Consumer Group, but the data plane rejects the configuration with in 'consumer': value must be null or in 'consumer_group': value must be null. The data plane then applies no further configuration changes until you remove the AI Policy from the AI Consumer or AI Consumer Group.

An AI Policy scoped to an AI Model runs only when the model field of the request body names that AI Model. A request that names a different model, such as the provider’s own model name, doesn’t run the AI Policy.

If several global Pre-Function AI Policies exist, only the one with the highest ID takes effect. AI Gateway ignores the others without reporting an error.

Exit Transformer

An Exit Transformer AI Policy rewrites responses that other AI Policies send, including authentication 401 responses and responses that a Pre-Function or Post-Function returns with kong.response.exit. Each function receives the status code, the body, and the headers, and returns the new values. By default, it doesn’t rewrite responses that AI Gateway sends for unknown conditions, such as the 404 for a request that matches no Route. Set handle_unknown and handle_unexpected to true to rewrite those too.

Conditions

Unlike the Kong Gateway Pre-Function and Post-Function plugins, the AI Gateway Pre-Function and Post-Function AI Policies support the condition field. When the condition evaluates to false, AI Gateway skips the AI Policy. See AI Policy conditions.

The following examples run in strict mode, the default. Each example is an AI Policy that you attach to an AI Model, or apply globally. For how the scope affects when an AI Policy runs, see AI Policy configuration.

Read the AI Consumer in a Post-Function

A Post-Function runs after authentication, so kong.client.get_consumer returns the authenticated AI Consumer. This example returns the AI Consumer’s identity and its AI Consumer Group names in the response.

ai_gateway_policies:
  - ref: return-ai-consumer-details
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Return AI Consumer details
    name: return-ai-consumer-details
    type: post-function
    config:
      access:
      - |
        local c = kong.client.get_consumer()
        local g = kong.client.get_consumer_groups()
        local names = {}
        if type(g) == "table" then
          for _, group in ipairs(g) do
            names[#names + 1] = group.name
          end
        end
        return kong.response.exit(200, {
          consumer = c and { id = c.id, username = c.username, custom_id = c.custom_id, tags = c.tags } or "nil",
          groups = names,
        })

Make sure to replace the following placeholders with your own values:

• AI_GATEWAY_ID: The id of your AI Gateway.

Share a value between AI Policies

kong.ctx.shared holds values for the duration of a request. In this example, a global Pre-Function stores a value and a Post-Function on an AI Model reads it.

ai_gateway_policies:
  - ref: store-shared-value
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Store a shared value
    name: store-shared-value
    type: pre-function
    global: true
    config:
      access:
      - 'kong.ctx.shared.probe = "from-pre-function"
           '

Make sure to replace the following placeholders with your own values:

• AI_GATEWAY_ID: The id of your AI Gateway.

ai_gateway_policies:
  - ref: read-shared-value
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Read the shared value
    name: read-shared-value
    type: post-function
    config:
      access:
      - 'return kong.response.exit(200, { probe = kong.ctx.shared.probe or "nil" })
           '

Make sure to replace the following placeholders with your own values:

• AI_GATEWAY_ID: The id of your AI Gateway.

Rewrite error responses

An Exit Transformer function receives the status code, the body, and the headers, and returns the new values. This example replaces every response that the Exit Transformer handles with a 418 response that includes the original status code.

ai_gateway_policies:
  - ref: rewrite-error-responses
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Rewrite error responses
    name: rewrite-error-responses
    type: exit-transformer
    global: true
    config:
      functions:
      - |
        return function(status, body, headers)
          return 418, { message = "rewritten", original_status = status }, headers
        end

Make sure to replace the following placeholders with your own values:

• AI_GATEWAY_ID: The id of your AI Gateway.

Check what strict mode blocks

This Post-Function reports which operations the sandbox allows. In strict mode, resty_http, io_open, tcp_socket, and os_execute are false, and cjson is true.

ai_gateway_policies:
  - ref: check-sandbox-restrictions
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Check sandbox restrictions
    name: check-sandbox-restrictions
    type: post-function
    config:
      access:
      - |
        local ok_http = pcall(require, "resty.http")
        local ok_io = pcall(function() return io.open("/etc/passwd") end)
        local ok_tcp = pcall(function() return ngx.socket.tcp() end)
        local ok_os = pcall(function() return os.execute("true") end)
        local ok_cjson = pcall(require, "cjson")
        return kong.response.exit(200, {
          resty_http = ok_http, io_open = ok_io, tcp_socket = ok_tcp, os_execute = ok_os, cjson = ok_cjson,
        })

Make sure to replace the following placeholders with your own values:

• AI_GATEWAY_ID: The id of your AI Gateway.

AI Gateway can change the sandbox allowlists of environment and modules. Most changes add entries. If AI Gateway finds a security vulnerability, it can remove entries and notifies you of the change.