Lua sandboxing

Uses: Kong Gateway

Disallow custom code execution

If no custom code is needed, disable all custom code execution by setting untrusted_lua=off. This ensures that the Kong Gateway node will not attempt to load or execute custom code, such as serverless functions used by the pre-function and post-function plugins. The downside is that Lua-based extensibility will not be available.

Strict mode (the default)

Strict mode is an allowlist-based execution environment, selected by setting untrusted_lua=strict. This is also the default value in current Kong Gateway releases. In this mode you can load and execute custom Lua code with some limitations. Most notably, all file I/O and network I/O functionality is disallowed.

Environment in strict mode

In strict mode you are allowed to use:

Group	Available
`bit`	`bit.arshift` `bit.band` `bit.bnot` `bit.bor` `bit.bswap` `bit.bxor` `bit.lshift` `bit.rol` `bit.ror` `bit.rshift` `bit.tobit` `bit.tohex`
`coroutine`	`coroutine.create` `coroutine.resume` `coroutine.running` `coroutine.status` `coroutine.wrap` `coroutine.yield`
`globals`	`_VERSION` `assert` `error` `ipairs` `next` `pairs` `pcall` `print` `select` `tonumber` `tostring` `type` `unpack` `xpcall`
`io`	`io.type`
`jit`	`jit.os` `jit.arch` `jit.version` `jit.version_num`
`kong`	`kong.default_workspace` `kong.version` `kong.version_num`
`kong.client`	`kong.client.authenticate` `kong.client.authenticate_consumer_group_by_consumer_id` `kong.client.get_consumer` `kong.client.get_consumer_group` `kong.client.get_consumer_groups` `kong.client.get_credential` `kong.client.get_forwarded_ip` `kong.client.get_forwarded_port` `kong.client.get_ip` `kong.client.get_port` `kong.client.get_protocol` `kong.client.load_consumer` `kong.client.set_authenticated_consumer_group` `kong.client.set_authenticated_consumer_groups` `kong.client.set_token` `kong.client.get_token` `kong.client.get_jwt_token_header` `kong.client.get_jwt_token_payload` `kong.client.get_identity_realm_source` v3.15+ `kong.client.set_identity_realm_source` v3.15+ `kong.client.get_principal` v3.16+
`kong.cluster`	`kong.cluster.get_id`
`kong.ctx`	`kong.ctx.shared[]` `kong.ctx.plugin[]`
`kong.ip`	`kong.ip.is_trusted`
`kong.jwe`	`kong.jwe.decode` `kong.jwe.decrypt` `kong.jwe.encrypt`
`kong.log`	`kong.log` `kong.log.alert` `kong.log.crit` `kong.log.debug` `kong.log.emerg` `kong.log.err` `kong.log.info` `kong.log.inspect` `kong.log.notice` `kong.log.serialize` `kong.log.set_serialize_value` `kong.log.warn` `kong.log.deprecation` `kong.log.deprecation.write`
`kong.metrics`	`kong.metrics.counter` v3.16+ `kong.metrics.gauge` v3.16+ `kong.metrics.histogram` v3.16+ `kong.metrics.VALUE_TYPE` v3.16+
`kong.nginx`	`kong.nginx.get_subsystem`
`kong.node`	`kong.node.get_hostname` `kong.node.get_id`
`kong.plugin`	`kong.plugin.get_id`
`kong.request`	`kong.request.get_body` `kong.request.get_forwarded_host` `kong.request.get_forwarded_path` `kong.request.get_forwarded_port` `kong.request.get_forwarded_prefix` `kong.request.get_forwarded_scheme` `kong.request.get_header` `kong.request.get_headers` `kong.request.get_host` `kong.request.get_http_version` `kong.request.get_method` `kong.request.get_path` `kong.request.get_path_with_query` `kong.request.get_port` `kong.request.get_query` `kong.request.get_query_arg` `kong.request.get_raw_body` `kong.request.get_raw_path` `kong.request.get_raw_query` `kong.request.get_scheme` `kong.request.get_start_time` `kong.request.get_uri_captures` `kong.request.get_raw_headers` v3.15+ `kong.request.get_id` v3.15+ `kong.request.get_raw_forwarded_path` v3.15+
`kong.response`	`kong.response.add_header` `kong.response.clear_header` `kong.response.error` `kong.response.exit` `kong.response.get_header` `kong.response.get_headers` `kong.response.get_raw_body` `kong.response.get_source` `kong.response.get_status` `kong.response.set_header` `kong.response.set_headers` `kong.response.set_raw_body` `kong.response.set_status`
`kong.router`	`kong.router.get_route` v3.15+ `kong.router.get_service` v3.15+
`kong.service.request`	`kong.service.request.add_header` `kong.service.request.clear_header` `kong.service.request.clear_query_arg` `kong.service.request.enable_buffering` `kong.service.request.set_authentication_headers` `kong.service.request.set_body` `kong.service.request.set_header` `kong.service.request.set_headers` `kong.service.request.set_method` `kong.service.request.set_path` `kong.service.request.set_query` `kong.service.request.set_raw_body` `kong.service.request.set_raw_query` `kong.service.request.set_scheme`
`kong.service.response`	`kong.service.response.get_body` `kong.service.response.get_header` `kong.service.response.get_headers` `kong.service.response.get_raw_body` `kong.service.response.get_status`
`kong.table`	`kong.table.clear` `kong.table.merge` `kong.table.new` v3.15+
`kong.telemetry`	`kong.telemetry.log`
`kong.tracing`	`kong.tracing.active_span` `kong.tracing.create_span` `kong.tracing.get_probability_sampling_decision` `kong.tracing.get_root_span` `kong.tracing.get_sampling_decision` `kong.tracing.get_spans` `kong.tracing.init_spans` `kong.tracing.link_span` `kong.tracing.process_span` `kong.tracing.set_active_span` `kong.tracing.set_should_sample` `kong.tracing.start_span`
`math`	`math.abs` `math.acos` `math.asin` `math.atan` `math.atan2` `math.ceil` `math.cos` `math.cosh` `math.deg` `math.exp` `math.floor` `math.fmod` `math.frexp` `math.huge` `math.ldexp` `math.log` `math.log10` `math.max` `math.min` `math.modf` `math.pi` `math.pow` `math.rad` `math.random` `math.sin` `math.sinh` `math.sqrt` `math.tan` `math.tanh`
`ngx`	`ngx.cookie_time` `ngx.crc32_long` `ngx.crc32_short` `ngx.decode_args` `ngx.decode_base64` `ngx.encode_args` `ngx.encode_base64` `ngx.eof` `ngx.escape_uri` `ngx.exit` `ngx.flush` `ngx.get_phase` `ngx.get_raw_phase` `ngx.hmac_sha1` `ngx.http_time` `ngx.localtime` `ngx.log` `ngx.md5` `ngx.md5_bin` `ngx.now` `ngx.null` `ngx.parse_http_time` `ngx.print` `ngx.quote_sql_str` `ngx.redirect` `ngx.say` `ngx.send_headers` `ngx.sha1_bin` `ngx.sleep` `ngx.time` `ngx.today` `ngx.unescape_uri` `ngx.update_time` `ngx.utctime`
`ngx (constants)`	`ngx.AGAIN` `ngx.ALERT` `ngx.CRIT` `ngx.DEBUG` `ngx.DECLINED` `ngx.DONE` `ngx.EMERG` `ngx.ERR` `ngx.ERROR` `ngx.HTTP_ACCEPTED` `ngx.HTTP_BAD_GATEWAY` `ngx.HTTP_BAD_REQUEST` `ngx.HTTP_CLOSE` `ngx.HTTP_CONFLICT` `ngx.HTTP_CONTINUE` `ngx.HTTP_COPY` `ngx.HTTP_CREATED` `ngx.HTTP_DELETE` `ngx.HTTP_FORBIDDEN` `ngx.HTTP_GATEWAY_TIMEOUT` `ngx.HTTP_GET` `ngx.HTTP_GONE` `ngx.HTTP_HEAD` `ngx.HTTP_ILLEGAL` `ngx.HTTP_INSUFFICIENT_STORAGE` `ngx.HTTP_INTERNAL_SERVER_ERROR` `ngx.HTTP_LOCK` `ngx.HTTP_METHOD_NOT_IMPLEMENTED` `ngx.HTTP_MKCOL` `ngx.HTTP_MOVE` `ngx.HTTP_MOVED_PERMANENTLY` `ngx.HTTP_MOVED_TEMPORARILY` `ngx.HTTP_NOT_ACCEPTABLE` `ngx.HTTP_NOT_ALLOWED` `ngx.HTTP_NOT_FOUND` `ngx.HTTP_NOT_IMPLEMENTED` `ngx.HTTP_NOT_MODIFIED` `ngx.HTTP_NO_CONTENT` `ngx.HTTP_OK` `ngx.HTTP_OPTIONS` `ngx.HTTP_PARTIAL_CONTENT` `ngx.HTTP_PATCH` `ngx.HTTP_PAYMENT_REQUIRED` `ngx.HTTP_PERMANENT_REDIRECT` `ngx.HTTP_POST` `ngx.HTTP_PROPFIND` `ngx.HTTP_PROPPATCH` `ngx.HTTP_PUT` `ngx.HTTP_REQUEST_TIMEOUT` `ngx.HTTP_SEE_OTHER` `ngx.HTTP_SERVICE_UNAVAILABLE` `ngx.HTTP_SPECIAL_RESPONSE` `ngx.HTTP_SWITCHING_PROTOCOLS` `ngx.HTTP_TEMPORARY_REDIRECT` `ngx.HTTP_TOO_MANY_REQUESTS` `ngx.HTTP_TRACE` `ngx.HTTP_UNAUTHORIZED` `ngx.HTTP_UNLOCK` `ngx.HTTP_UPGRADE_REQUIRED` `ngx.HTTP_VERSION_NOT_SUPPORTED` `ngx.INFO` `ngx.NOTICE` `ngx.OK` `ngx.STDERR` `ngx.WARN`
`ngx (fields)`	`ngx.arg[]` `ngx.ctx[]` `ngx.header[]` `ngx.headers_sent` `ngx.is_subrequest` `ngx.status` `ngx.var[]`
`ngx.config`	`ngx.config.nginx_version` `ngx.config.ngx_lua_version` `ngx.config.subsystem`
`ngx.re`	`ngx.re.find` `ngx.re.gmatch` `ngx.re.gsub` `ngx.re.match` `ngx.re.sub`
`ngx.req`	`ngx.req.append_body` `ngx.req.clear_header` `ngx.req.discard_body` `ngx.req.finish_body` `ngx.req.get_body_data` `ngx.req.get_headers` `ngx.req.get_method` `ngx.req.get_post_args` `ngx.req.get_uri_args` `ngx.req.http_version` `ngx.req.init_body` `ngx.req.is_internal` `ngx.req.raw_header` `ngx.req.read_body` `ngx.req.set_body_data` `ngx.req.set_header` `ngx.req.set_method` `ngx.req.set_uri` `ngx.req.set_uri_args` `ngx.req.socket` `ngx.req.start_time`
`ngx.resp`	`ngx.resp.get_headers`
`ngx.worker`	`ngx.worker.count` `ngx.worker.exiting` `ngx.worker.id` `ngx.worker.pid` `ngx.worker.pids`
`os`	`os.clock` `os.date` `os.difftime` `os.time`
`string`	`string.byte` `string.char` `string.find` `string.format` `string.gmatch` `string.gsub` `string.len` `string.lower` `string.match` `string.rep` `string.reverse` `string.sub` `string.upper`
`table`	`table.clear` `table.clone` `table.concat` `table.foreach` `table.foreachi` `table.getn` `table.insert` `table.isarray` `table.isempty` `table.maxn` `table.move` `table.new` `table.nkeys` `table.pack` `table.remove` `table.sort` `table.unpack`

Available modules in strict mode

You are also allowed to use the standard require function to load modules. In strict mode, the following modules are available:

Group	Available
`argon2`	`argon2`
`bcrypt`	`bcrypt`
`binaryheap`	`binaryheap` v3.15+
`bit`	`bit`
`cjson`	`cjson` `cjson.safe`
`ffi-zlib`	`ffi-zlib` v3.15+
`kong`	`kong.constants` `kong.meta`
`kong.tools`	`kong.tools.cjson` `kong.tools.gzip` `kong.tools.ip` `kong.tools.jose` `kong.tools.json` `kong.tools.mime_type` `kong.tools.rand` `kong.tools.sha1` `kong.tools.sha256` `kong.tools.string` `kong.tools.table` `kong.tools.time` `kong.tools.timestamp` `kong.tools.uri` `kong.tools.utils` `kong.tools.uuid` `kong.tools.yield` `kong.tools.header` v3.15+ `kong.tools.header-mapping` v3.15+ `kong.tools.hostname` v3.15+ `kong.tools.stack` v3.15+ `kong.tools.glob` v3.15+
`lua_pack`	`lua_pack` v3.15+
`luaxxhash`	`luaxxhash` v3.15+
`lxp`	`lxp` v3.15+
`lyaml`	`lyaml`
`MessagePack`	`MessagePack` v3.15+
`multipart`	`multipart` v3.15+
`ngx`	`ngx.base64` `ngx.re` `ngx.req` `ngx.resp` `ngx.semaphore`
`pl`	`pl.stringx` `pl.tablex` `pl.url` v3.15+
`resty`	`resty.aes` `resty.lock` `resty.md5` `resty.random` `resty.sha` `resty.sha1` `resty.sha224` `resty.sha256` `resty.sha384` `resty.sha512` `resty.string` `resty.upload` `resty.core.time` `resty.lrucache` `resty.lrucache.pureffi` `resty.ada` `resty.ada.search` `resty.cookie` `resty.ipmatcher` `resty.jit-uuid` `resty.jwt` `resty.evp` `resty.jwt-validators` `resty.hmac` `resty.passwdqc` `resty.snappy` v3.15+
`resty.openssl`	`resty.openssl` `resty.openssl.asn1` `resty.openssl.bn` `resty.openssl.cipher` `resty.openssl.ctx` `resty.openssl.dh` `resty.openssl.digest` `resty.openssl.ec` `resty.openssl.ecx` `resty.openssl.err` `resty.openssl.hmac` `resty.openssl.kdf` `resty.openssl.mac` `resty.openssl.objects` `resty.openssl.param` `resty.openssl.pkcs12` `resty.openssl.pkey` `resty.openssl.provider` `resty.openssl.rand` `resty.openssl.rsa` `resty.openssl.ssl` `resty.openssl.ssl_ctx` `resty.openssl.stack` `resty.openssl.version` `resty.openssl.x509` `resty.openssl.x509.altname` `resty.openssl.x509.chain` `resty.openssl.x509.crl` `resty.openssl.x509.csr` `resty.openssl.x509.name` `resty.openssl.x509.revoked` `resty.openssl.x509.store` `resty.openssl.x509.extension` `resty.openssl.x509.extension.dist_points` `resty.openssl.x509.extension.info_access`
`socket`	`socket.url`
`string`	`string.buffer`
`table`	`table.clear` `table.clone` `table.isarray` `table.isempty` `table.new` `table.nkeys`
`tablepool`	`tablepool`
`version`	`version`
`xml2lua`	`xml2lua` v3.15+
`xmlua`	`xmlua`

Lax mode

The lax mode extends the strict mode with network I/O, and some other functionality.

Environment in lax mode

Lax mode includes everything in strict mode, plus the following:

Group	Available
`kong.cache`	`kong.cache:get` `kong.cache:get_bulk` `kong.cache:probe` `kong.cache:invalidate` `kong.cache:invalidate_local` `kong.cache:safe_set` `kong.cache:renew`
`kong.client`	`kong.client.get_aws_vpce_id`
`kong.client.tls`	`kong.client.tls.disable_session_reuse` `kong.client.tls.get_full_client_certificate_chain` `kong.client.tls.request_client_certificate` `kong.client.tls.set_client_verify`
`kong.configuration`	`kong.configuration[*]`
`kong.db.certificates`	`kong.db.certificates:cache_key` `kong.db.certificates:select` `kong.db.certificates:select_by_cache_key`
`kong.db.consumers`	`kong.db.consumers:cache_key` `kong.db.consumers:select` `kong.db.consumers:select_by_cache_key` `kong.db.consumers:select_by_custom_id` `kong.db.consumers:select_by_username` `kong.db.consumers:select_by_username_ignore_case`
`kong.db.keys`	`kong.db.keys:cache_key` `kong.db.keys:select` `kong.db.keys:select_by_cache_key` `kong.db.keys:select_by_name`
`kong.db.plugins`	`kong.db.plugins:cache_key` `kong.db.plugins:select` `kong.db.plugins:select_by_cache_key` `kong.db.plugins:select_by_instance_name`
`kong.db.routes`	`kong.db.routes:cache_key` `kong.db.routes:select` `kong.db.routes:select_by_cache_key` `kong.db.routes:select_by_name`
`kong.db.services`	`kong.db.services:cache_key` `kong.db.services:select` `kong.db.services:select_by_cache_key` `kong.db.services:select_by_name`
`kong.db.snis`	`kong.db.snis:cache_key` `kong.db.snis:select` `kong.db.snis:select_by_cache_key` `kong.db.snis:select_by_name`
`kong.db.targets`	`kong.db.targets:cache_key` `kong.db.targets:select` `kong.db.targets:select_by_cache_key` `kong.db.targets:select_by_target`
`kong.db.upstreams`	`kong.db.upstreams:cache_key` `kong.db.upstreams:select` `kong.db.upstreams:select_by_cache_key` `kong.db.upstreams:select_by_name`
`kong.dns`	`kong.dns.resolve` `kong.dns.toip`
`kong.nginx`	`kong.nginx.get_statistics`
`kong.node`	`kong.node.get_memory_stats`
`kong.router`	`kong.router.get_route` up to v3.14 `kong.router.get_service` up to v3.14
`kong.service`	`kong.service.enable_recording_upstream_ssl` `kong.service.set_retries` `kong.service.set_target` `kong.service.set_target_retry_callback` `kong.service.set_timeouts` `kong.service.set_tls_cert_key` `kong.service.set_tls_verify` `kong.service.set_tls_verify_depth` `kong.service.set_tls_verify_store` `kong.service.set_upstream`
`kong.vault`	`kong.vault.get` `kong.vault.is_reference` `kong.vault.parse_reference` `kong.vault.try` `kong.vault.update`
`kong.websocket.client`	`kong.websocket.client.close` `kong.websocket.client.drop_frame` `kong.websocket.client.get_frame` `kong.websocket.client.set_frame_data` `kong.websocket.client.set_max_payload_size` `kong.websocket.client.set_status`
`kong.websocket.upstream`	`kong.websocket.upstream.close` `kong.websocket.upstream.drop_frame` `kong.websocket.upstream.get_frame` `kong.websocket.upstream.set_frame_data` `kong.websocket.upstream.set_max_payload_size` `kong.websocket.upstream.set_status`
`ngx.config`	`ngx.config.debug`
`ngx.location`	`ngx.location.capture` `ngx.location.capture_multi`
`ngx.req`	`ngx.req.get_body_file` `ngx.req.set_body_file`
`ngx.socket`	`ngx.socket.connect` `ngx.socket.stream` `ngx.socket.tcp` `ngx.socket.udp`
`ngx.thread`	`ngx.thread.kill` `ngx.thread.spawn` `ngx.thread.wait`

Available modules in lax mode

Lax mode includes everything in strict mode, plus the following:

Group	Available
`kong`	`kong.concurrency`
`kong.enterprise_edition`	`kong.enterprise_edition.tools.redis.v2` `kong.enterprise_edition.tools.redis.v2.config_utils` v3.15+
`kong.tools`	`kong.tools.oauth-client` v3.15+ `kong.tools.solace` v3.15+ `kong.tools.redis.config_utils` v3.15+
`pgmoon`	`pgmoon` `pgmoon.arrays` `pgmoon.hstore`
`resty`	`resty.memcached` `resty.mysql` `resty.dns.resolver` `resty.jq` `resty.session`
`resty.aws`	`resty.aws` `resty.aws.utils` `resty.aws.config` `resty.aws.request.validate` `resty.aws.request.build` `resty.aws.request.sign` `resty.aws.request.execute` `resty.aws.request.signatures.utils` `resty.aws.request.signatures.v4` `resty.aws.request.signatures.presign` `resty.aws.request.signatures.none` `resty.aws.service.rds.signer` `resty.aws.credentials.Credentials` `resty.aws.credentials.ChainableTemporaryCredentials` `resty.aws.credentials.CredentialProviderChain` `resty.aws.credentials.EC2MetadataCredentials` `resty.aws.credentials.EnvironmentCredentials` `resty.aws.credentials.SharedFileCredentials` `resty.aws.credentials.RemoteCredentials` `resty.aws.credentials.TokenFileWebIdentityCredentials` `resty.aws.raw-api.region_config_data`
`resty.azure`	`resty.azure` `resty.azure.config` `resty.azure.utils` `resty.azure.credentials.Credentials` `resty.azure.credentials.ClientCredentials` `resty.azure.credentials.WorkloadIdentityCredentials` `resty.azure.credentials.ManagedIdentityCredentials` `resty.azure.api.keyvault` `resty.azure.api.secrets` `resty.azure.api.keys` `resty.azure.api.certificates` `resty.azure.api.auth` `resty.azure.api.request.build` `resty.azure.api.request.execute` `resty.azure.api.response.handle`
`resty.gcp`	`resty.gcp` `resty.gcp.request.credentials.accesstoken` `resty.gcp.request.discovery`
`resty.http`	`resty.http` `resty.http_connect` `resty.http_headers`
`resty.redis`	`resty.redis` `resty.rediscluster` `resty.xmodem`

Sandbox mode (deprecated)

Sandbox mode is deprecated and may be removed in a future release. Sandbox mode allows (almost) full access to Kong Gateway PDK (kong.*) and Nginx functions (ngx.*). It has somewhat limited access to standard Lua environment (see the strict mode Lua related environment). This is useful when upgrading from older Kong Gateway versions that used the sandbox mode, and thus is backward compatible.

In sandbox mode you are not allowed to use the require function to load modules, unless you are also using untrusted_lua_sandbox_requires and listing the allowed modules there.

Unrestricted mode

It is also possible to run Kong Gateway in unrestricted mode by setting the untrusted_lua configuration option to on. In this mode the access to environment or available modules is completely unrestricted, and no protections are applied.

Notes

Kong Gateway keeps rights to modify the supported allowlists of environment and modules. Most commonly, Kong Gateway will do additions to the allowlists, but in case a security vulnerability is found, Kong Gateway may remove some. In such case, Kong Gateway will notify the user about the change.