HTTP Plugins

Octelium already supports native ways to manipulate HTTP request/response headers, validate request JSON body and send direct responses back to the downstreams (read more here). However, in many real-world use cases, such native methods might be not flexible enough.

Octelium provides additional, more advanced "plugins" to manipulate HTTP requests and responses in arbitrarily complex ways that might include calling external SaaS HTTP-based APIs and databases, manipulating JSON body content of requests and responses, etc.... Such plugins can be especially useful for many use cases that can be applied to ZTNA/BeyondCorp, API gateways, AI gateways, MCP gateways, etc.... including:

Request/response sanitization and manipulation for headers as well as body content, including JSON, which can be used for API/AI gateways.
Custom identity-based caching, including semantic caching for AI gateways.
DLP for ZTNA/BeyondCorp.
Implementing AI guardrails, including calling SaaS APIs to verify prompts.
Custom identity-based rate limiting.

Currently 3 plugin types are supported:

Lua scripts.
Direct plugin that enables you to directly return a response without proceeding to the upstream.
Envoy's ext_proc filter. Octelium enables you to stack one or more plugins from the same or different types and invoke them at certain phases of the request, as well as to conditionally invoke them via policy-as-code rules on a per-request basis. Plugins are invoked in the same order they are defined.

Lua

Lua plugin invokes a Lua script that includes two functions: onRequest that is invoked upon receiving the request before proxying it to the upstream, and onResponse that is invoked upon receiving the response from the upstream. Here is a detailed example:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  config:
7    upstream:
8      url: https://api.example.com
9    http:
10      plugins:
11        - name: my-lua-script
12          lua:
13            inline: |
14              function onRequest(ctx)
15                octelium.req.setRequestHeader("X-User-Uid", ctx.user.metadata.uid)
16                octelium.req.deleteRequestHeader("X-Delete")
17                octelium.req.setQueryParam("user", ctx.user.metadata.name)
18                octelium.req.deleteQueryParam("param1")
19                local body = json.decode(octelium.req.getRequestBody())
20                if strings.contains(strings.toLower(strings.trim(base64.decode(body.strField))), "privileged") then
21                  local res = {
22                    error = "You are not allowed"
23                  }
24                  octelium.req.setResponseBody(json.encode(res))
25                  octelium.req.exit(403)
26                  return
27                end
28
29                if strings.hasPrefix(ctx.request.http.path, "/users") then
30                  octelium.req.setPath("/users/"..ctx.user.metadata.uid)
31                end
32
33                if strings.hasSuffix(ctx.request.http.path, ".php") then
34                  octelium.req.setPath("/users/"..ctx.user.metadata.uid)
35                end
36
37                if strings.len(body.someStrField) > 1000 then
38                  local c = http.client()
39                  c:setBaseURL("http://my-api.default.svc")
40                  local req = c:request()
41                  req:setBody(json.encode(ctx.user))
42                  req:setHeader("X-User-Uid", ctx.user.metadata.uid)
43                  local resp, err = req:post("/v1/check-user")
44                  if err then
45                    octelium.req.exit(500)
46                    return
47                  end
48
49                  if resp:code() == 200 then
50                    local apiResp = json.decode(resp:body())
51                    if not apiResp.userIsAllowed then
52                      octelium.req.exit(403)
53                      return
54                    end
55                  end
56                end
57              end
58
59              function onResponse(ctx)
60                octelium.req.setResponseHeader("X-Session-Uid", ctx.session.metadata.uid)
61                octelium.req.deleteResponseHeader("X-Delete")
62                local resp = octelium.req.getResponseBody()
63                resp.email = ctx.user.spec.email
64                octelium.req.setResponseBody(json.encode(resp))
65                octelium.req.setStatusCode(209)
66              end

Note that you do not have to define both onRequest and onResponse in every Lua script. If any of these functions does not exist, then it is silently skipped.

Direct

The direct plugin enables you to directly return a response without proceeding to the upstream. This acts as a much more performant, yet less flexible, way compared to Lua and Envoy ext_proc plugins to, for example, drop unwanted requests that contain undesirable request paths, body content, etc.... Here is an example:

1kind: Service
2metadata:
3  name: my-nginx
4spec:
5  mode: WEB
6  isPublic: true
7  config:
8    upstream:
9      container:
10        image: nginx
11        port: 80
12    http:
13      plugins:
14        - name: drop-php
15          direct:
16            condition:
17              match: ctx.request.http.path.toLower().endsWith(".php")
18            body:
19              inline: This is not a PHP server!
20            statusCode: 404
21            headers:
22              X-Custom-Header: some-value
23              X-Another-Header: another-value

Envoy Ext Proc

Octelium also supports Envoy's ext_proc. In this plugin type, Octelium's identity-aware proxy, Vigil, behaves like an Envoy instance and acts as an ext_proc gRPC client that sends ProcessingRequest to your ext_proc gRPC compliant server and waits for ProcessingResponse on every request. Here is an example:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  config:
7    upstream:
8      url: https://api.example.com
9    http:
10      plugins:
11        - name: my-ext-proc-svc
12          extProc:
13            address: ext-proc.default.svc:8080

Phase

By default, plugins are invoked after the authentication and authorization processes are done. However, you might choose to invoke a plugin before authentication/authorization by explicity setting a phase value for that plugin. Currently the values available are: POST_AUTH which is the default behavior when not explicitly set, and PRE_AUTH to force a pre-auth invocation. PRE_AUTH plugins might be useful to do pre-authentication manipulation or even completely dropping the requests before proceeding further to the authentication/authorization process.

Note that PRE_AUTH plugins must be in the default Service configuration. In other words, you can not have a PRE_AUTH in a named dynamic config (read more here). Here is an example:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  config:
7    upstream:
8      url: https://api.example.com
9    http:
10      plugins:
11        - name: check-body-size
12          phase: PRE_AUTH
13          lua:
14            inline: |
15              function onRequest(ctx)
16                local body = octelium.req.getRequestBody()
17                if strings.len(body) > 10000 then
18                  octelium.req.exit(400)
19                  return
20                end
21              end

Rules

By default, a plugin in the chosen Service config is invoked on all requests. You can, however, change that behavior and set per-request conditions for the plugin invocation. Here is an example that only invokes the plugin for paths with a /users prefix:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  config:
7    upstream:
8      url: https://api.example.com
9    http:
10      plugins:
11        - name: my-ext-proc-svc
12          rules:
13            - condition:
14                match: ctx.request.http.request.path.startsWith("/users")
15              effect: ENFORCE
16            - condition:
17                matchAny: true
18              effect: IGNORE
19          extProc:
20            address: ext-proc.default.svc:8080

Disabling a Plugin

You can disable plugin as follows:

1kind: Service
2metadata:
3  name: svc1
4spec:
5  mode: HTTP
6  config:
7    upstream:
8      url: https://api.example.com
9    http:
10      plugins:
11        - name: my-plugin
12          isDisabled: true
13          lua:
14            inline: |
15              function onRequest(ctx)
16              end