Skip to content

feat: whitelist for allowed env and paths for lua #9220

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rudrakhp wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: whitelist for allowed env and paths for lua #9220

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions api/v1alpha1/envoyproxy_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ type EnvoyProxy struct {
}

// EnvoyProxySpec defines the desired state of EnvoyProxy.
// +kubebuilder:validation:XValidation:rule="!has(self.luaStrictValidation) || !has(self.luaValidation) || self.luaValidation == 'Strict'",message="luaStrictValidation can only be set when luaValidation is Strict"
type EnvoyProxySpec struct {
// Provider defines the desired resource provider and provider-specific configuration.
// If unspecified, the "Kubernetes" resource provider is used with default configuration
Expand Down Expand Up @@ -189,6 +190,20 @@ type EnvoyProxySpec struct {
// +optional
LuaValidation *LuaValidation `json:"luaValidation,omitempty"`

// LuaStrictValidation defines the filesystem paths and environment variables that Lua
// scripts from EnvoyExtensionPolicy resources are permitted to access during Strict
// validation in the gateway controller.
//
// The allowlist is fail-closed: when unset or empty, Lua scripts are denied access to ALL
// filesystem paths and environment variables during validation. Only entries that match the
// allowlist are permitted.
//
// This field only takes effect when LuaValidation is Strict (the default). It has no effect
// for the InsecureSyntax or Disabled validation modes, which do not execute the security sandbox.
//
// +optional
LuaStrictValidation *LuaStrictValidation `json:"luaStrictValidation,omitempty"`

@zirain zirain Jun 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

naive question: does this only worked when LuaValidation=Strict?

@rudrakhp rudrakhp Jun 16, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, because we don't do any security validation in non-strict modes.

@rudrakhp rudrakhp Jun 16, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually let me add a CEL validation for this

@zirain zirain Jun 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if so, I'm wandering should we make a breaking change to luaValidation like following:

luaValidation:
  type: strict
  strict:
     allowedPaths:
     allowedEnvVars:

@rudrakhp rudrakhp Jun 16, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes I was trying to avoid a breaking change. Since we don't do any kind of validation that requires settings in other modes, having a separate one for strict only can be ok ig?

@rudrakhp rudrakhp Jun 16, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@envoyproxy/gateway-maintainers any opinions?

@zhaohuabing zhaohuabing Jul 25, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest deprecating luaValidation and adding a union.

// Deprecated: Use LuaScriptValidation.Type instead. This field will be removed in a future release.
// +optional
LuaValidation *LuaValidation `json:"luaValidation,omitempty"`

// +optional
LuaScriptValidation *LuaScriptValidation `json:"luaScriptValidation,omitempty"`

// +union
type LuaScriptValidation struct {
      // +unionDiscriminator
      // +kubebuilder:default=Strict
      // +optional
      Type *LuaValidation `json:"type,omitempty"`

      // Strict configures the sandbox that Strict validation executes scripts in.
      // No effect for InsecureSyntax and Disabled, which do not execute scripts.
      // +optional
      Strict *LuaStrictValidation `json:"strict,omitempty"`
}
```

@rudrakhp rudrakhp Jul 25, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Works, with minor renames if that feels more intuitive:

  • LuaScriptValidation -> LuaValidationConfig
  • LuaStrictValidation -> StrictValidation (since it is already under LuaValidationConfig
    WDYT @zhaohuabing ?

@arkodg arkodg Jul 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 to a new top level lua field


// DynamicModules defines the set of dynamic modules that are allowed to be
// used by EnvoyExtensionPolicy resources and dynamic module load balancer
// policies. Each entry registers a module by a logical name and specifies
Expand Down Expand Up @@ -250,6 +265,39 @@ const (
LuaValidationDisabled LuaValidation = "Disabled"
)

// LuaStrictValidation defines the configuration that Strict Lua validation runs with.
//
// This configuration only applies to the Strict validation mode; it has no effect on the
// InsecureSyntax and Disabled modes.
type LuaStrictValidation struct {
// AllowedPaths is the list of filesystem path prefixes that Lua scripts are permitted to
// access during validation (via io.open, io.input, io.output, io.lines, os.remove, os.rename).
// A path is allowed when it equals an entry or is contained within an entry's subtree
// (e.g. "/tmp" allows "/tmp/file.txt"). Paths are normalized (separators collapsed, made
// absolute) before matching, and any "." or ".." traversal segment is always rejected.
// When empty, all filesystem access is denied. Blank or whitespace-only entries are rejected,
// as they would otherwise match every path and disable the sandbox.
//
// +kubebuilder:validation:MaxItems=64
// +kubebuilder:validation:items:MinLength=1
// +kubebuilder:validation:items:MaxLength=4096
// +kubebuilder:validation:XValidation:rule="self.all(p, p.trim() != '')",message="allowedPaths entries must not be blank or whitespace-only"
// +optional
AllowedPaths []string `json:"allowedPaths,omitempty"`

@zirain zirain Jun 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the configuration looks a little redundant.

luaValidationAllowlist:
  allowedPaths:

what about using following?

luaValidation:
  allowedPaths:

@rudrakhp rudrakhp Jun 15, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Problem is there is an existing luaValidation API used for configuring the mode/level. It is a string enum type so can't have child params. How about:

luaStrictValidationAllowlist:
  paths:
  envVars:

@zirain zirain Jun 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Problem is there is an existing luaValidation API used for configuring the mode/level. It is a string enum type so can't have child params. How about:

luaStrictValidationAllowlist:
  paths:
  envVars:

I'm mostly concerts with the Allow in the naming, which might be a blocker if we want to add blacklist for the validation instead of whitelist.

@rudrakhp rudrakhp Jun 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it how about:

luaStrictValidation:
  allowedPaths:
  allowedEnvVars:

@zirain zirain Jun 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good to me.


// AllowedEnvVars is the list of environment variable names that Lua scripts are permitted to
// access during validation (via os.getenv, os.setenv). Matching is exact and case-sensitive.
// When empty, access to all environment variables is denied. Blank or whitespace-only entries
// are rejected.
//
// +kubebuilder:validation:MaxItems=64
// +kubebuilder:validation:items:MinLength=1
// +kubebuilder:validation:items:MaxLength=256
// +kubebuilder:validation:XValidation:rule="self.all(e, e.trim() != '')",message="allowedEnvVars entries must not be blank or whitespace-only"
// +optional
AllowedEnvVars []string `json:"allowedEnvVars,omitempty"`
}

// RoutingType defines the type of routing of this Envoy proxy.
type RoutingType string

Expand Down
30 changes: 30 additions & 0 deletions api/v1alpha1/zz_generated.deepcopy.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

51 changes: 51 additions & 0 deletions charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -769,6 +769,53 @@ spec:
and the log level is the value. If unspecified, defaults to "default: warn".
type: object
type: object
luaStrictValidation:
description: |-
LuaStrictValidation defines the filesystem paths and environment variables that Lua
scripts from EnvoyExtensionPolicy resources are permitted to access during Strict
validation in the gateway controller.

The allowlist is fail-closed: when unset or empty, Lua scripts are denied access to ALL
filesystem paths and environment variables during validation. Only entries that match the
allowlist are permitted.

This field only takes effect when LuaValidation is Strict (the default). It has no effect
for the InsecureSyntax or Disabled validation modes, which do not execute the security sandbox.
properties:
allowedEnvVars:
description: |-
AllowedEnvVars is the list of environment variable names that Lua scripts are permitted to
access during validation (via os.getenv, os.setenv). Matching is exact and case-sensitive.
When empty, access to all environment variables is denied. Blank or whitespace-only entries
are rejected.
items:
maxLength: 256
minLength: 1
type: string
maxItems: 64
type: array
x-kubernetes-validations:
- message: allowedEnvVars entries must not be blank or whitespace-only
rule: self.all(e, e.trim() != '')
allowedPaths:
description: |-
AllowedPaths is the list of filesystem path prefixes that Lua scripts are permitted to
access during validation (via io.open, io.input, io.output, io.lines, os.remove, os.rename).
A path is allowed when it equals an entry or is contained within an entry's subtree
(e.g. "/tmp" allows "/tmp/file.txt"). Paths are normalized (separators collapsed, made
absolute) before matching, and any "." or ".." traversal segment is always rejected.
When empty, all filesystem access is denied. Blank or whitespace-only entries are rejected,
as they would otherwise match every path and disable the sandbox.
items:
maxLength: 4096
minLength: 1
type: string
maxItems: 64
type: array
x-kubernetes-validations:
- message: allowedPaths entries must not be blank or whitespace-only
rule: self.all(p, p.trim() != '')
type: object
luaValidation:
description: |-
LuaValidation determines strictness of the Lua script validation for Lua EnvoyExtensionPolicies
Expand Down Expand Up @@ -18112,6 +18159,10 @@ spec:
rule: '!(has(self.samplingRate) && has(self.samplingFraction))'
type: object
type: object
x-kubernetes-validations:
- message: luaStrictValidation can only be set when luaValidation is Strict
rule: '!has(self.luaStrictValidation) || !has(self.luaValidation) ||
self.luaValidation == ''Strict'''
status:
description: EnvoyProxyStatus defines the actual state of EnvoyProxy.
properties:
Expand Down
51 changes: 51 additions & 0 deletions charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -768,6 +768,53 @@ spec:
and the log level is the value. If unspecified, defaults to "default: warn".
type: object
type: object
luaStrictValidation:
description: |-
LuaStrictValidation defines the filesystem paths and environment variables that Lua
scripts from EnvoyExtensionPolicy resources are permitted to access during Strict
validation in the gateway controller.

The allowlist is fail-closed: when unset or empty, Lua scripts are denied access to ALL
filesystem paths and environment variables during validation. Only entries that match the
allowlist are permitted.

This field only takes effect when LuaValidation is Strict (the default). It has no effect
for the InsecureSyntax or Disabled validation modes, which do not execute the security sandbox.
properties:
allowedEnvVars:
description: |-
AllowedEnvVars is the list of environment variable names that Lua scripts are permitted to
access during validation (via os.getenv, os.setenv). Matching is exact and case-sensitive.
When empty, access to all environment variables is denied. Blank or whitespace-only entries
are rejected.
items:
maxLength: 256
minLength: 1
type: string
maxItems: 64
type: array
x-kubernetes-validations:
- message: allowedEnvVars entries must not be blank or whitespace-only
rule: self.all(e, e.trim() != '')
allowedPaths:
description: |-
AllowedPaths is the list of filesystem path prefixes that Lua scripts are permitted to
access during validation (via io.open, io.input, io.output, io.lines, os.remove, os.rename).
A path is allowed when it equals an entry or is contained within an entry's subtree
(e.g. "/tmp" allows "/tmp/file.txt"). Paths are normalized (separators collapsed, made
absolute) before matching, and any "." or ".." traversal segment is always rejected.
When empty, all filesystem access is denied. Blank or whitespace-only entries are rejected,
as they would otherwise match every path and disable the sandbox.
items:
maxLength: 4096
minLength: 1
type: string
maxItems: 64
type: array
x-kubernetes-validations:
- message: allowedPaths entries must not be blank or whitespace-only
rule: self.all(p, p.trim() != '')
type: object
luaValidation:
description: |-
LuaValidation determines strictness of the Lua script validation for Lua EnvoyExtensionPolicies
Expand Down Expand Up @@ -18111,6 +18158,10 @@ spec:
rule: '!(has(self.samplingRate) && has(self.samplingFraction))'
type: object
type: object
x-kubernetes-validations:
- message: luaStrictValidation can only be set when luaValidation is Strict
rule: '!has(self.luaStrictValidation) || !has(self.luaValidation) ||
self.luaValidation == ''Strict'''
status:
description: EnvoyProxyStatus defines the actual state of EnvoyProxy.
properties:
Expand Down
55 changes: 55 additions & 0 deletions internal/gatewayapi/luavalidator/lua_validator.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,59 @@ func (l *LuaValidator) getLuaValidation() egv1a1.LuaValidation {
return egv1a1.LuaValidationStrict
}

// allowlistData generates the Lua source consumed by security.lua: the path allowlist as a list and
// the env var allowlist as a map (name -> true). The allowlist is fail-closed; an unconfigured
// EnvoyProxy yields empty tables, denying all access.
func (l *LuaValidator) allowlistData() string {
var paths, envVars []string
if l.envoyProxy != nil && l.envoyProxy.Spec.LuaStrictValidation != nil {
paths = l.envoyProxy.Spec.LuaStrictValidation.AllowedPaths
envVars = l.envoyProxy.Spec.LuaStrictValidation.AllowedEnvVars
}

var b strings.Builder

b.WriteString("__lua_allowed_paths = {")
for i, p := range paths {
if i > 0 {
b.WriteString(", ")
}
b.WriteString(luaStringLiteral(p))
}
b.WriteString("}\n")

b.WriteString("__lua_allowed_env_vars = {")
for i, e := range envVars {
if i > 0 {
b.WriteString(", ")
}
// Spaces around the key are required: "[[[..." would lex as a long-string opener.
b.WriteString("[ ")
b.WriteString(luaStringLiteral(e))
b.WriteString(" ] = true")
}
b.WriteString("}\n")

return b.String()
}

// luaStringLiteral encodes s as a Lua long-bracket literal ([==[...]==]) with an equals level that
// avoids any closing delimiter in s. Long brackets don't interpret escapes, so spec values are
// passed verbatim as data and cannot inject Lua.
func luaStringLiteral(s string) string {
level := 0
for strings.Contains(s, "]"+strings.Repeat("=", level)+"]") {
level++
}
eq := strings.Repeat("=", level)
// Lua strips a leading newline after the opening bracket; re-add it to preserve such values.
prefix := ""
if strings.HasPrefix(s, "\n") {
prefix = "\n"
}
return "[" + eq + "[" + prefix + s + "]" + eq + "]"
}

// newLuaState creates a new Lua state with global settings and resource limits applied
// Returns the Lua state and a cancel function that must be called when done
func (l *LuaValidator) newLuaState() (*lua.LState, context.CancelFunc) {
Expand Down Expand Up @@ -123,6 +176,8 @@ func (l *LuaValidator) runLua(code string) error {

// Execute mocks first (trusted code, needs setmetatable, defines StreamHandle, etc.)
_ = L.DoString(mockData)
// Inject the allowlists before security.lua, which reads and then clears them.
_ = L.DoString(l.allowlistData())
// Execute Lua security wrappers (trusted code) to protect the gateway controller
// See security advisory: https://github.com/envoyproxy/gateway/security/advisories/GHSA-xrwg-mqj6-6m22
_ = L.DoString(securityData)
Expand Down
Loading