Skip to content
OpenShell
These docs are for the development version. Go to the latest released version (0.1.9).

Supervisor Middleware Configuration

Attach supervisor middleware to sandbox traffic, register your own middleware services, and observe middleware decisions.

Register your middleware service in gateway configuration, then attach it to destination hosts in sandbox policy. This page also covers ordering, failure behavior, service lifecycle, and observability. Built-in middleware needs only a policy entry.

A middleware service is a gRPC server that implements the supervisor middleware protocol. The content guard example implements request, response, and WebSocket checks in one service, and includes a policy and a local launcher.

To use your own service:

  1. Start the service where both the gateway and sandbox supervisors can reach it.
  2. Register it in gateway configuration.
  3. Restart the gateway.
  4. Attach it in sandbox policy by setting middleware to the registration name.

Register the service in gateway TOML:

[[openshell.supervisor.middleware]]
name = "content-guard"
grpc_endpoint = "https://content-guard.example:50051"
tls_ca_cert_path = "/path/to/content-guard-ca.pem"
max_payload_bytes = 262144
timeout = "500ms"
namestringrequired

Unique name that policies use to attach the service. The openshell/ prefix is reserved for built-ins.

grpc_endpointstringrequired

Service address reachable from the gateway and sandbox supervisors.

max_payload_bytesintegerrequired

Largest request body, response body, or WebSocket message the service inspects. Must be at most 4 MiB and no larger than the service advertises. May be 0 only when the service uses HTTP hooks and every binding advertises a 0 payload limit.

binding_policy'dynamic' | 'allowlist' | 'exact'default: dynamic

Which advertised operation and phase pairs OpenShell uses. To require a request hook, set binding_policy = "allowlist" and bindings = ["http_request_pre_credentials"]. Both the gateway and the supervisor reject a response-only service with this registration. Keep on_error: fail_closed on the policy attachment to block matching requests if the middleware is unavailable.

bindingsstring[]

Bindings required by allowlist or exact: http_request_pre_credentials, http_response_pre_return, or websocket_message_pre_credentials. An allowlist ignores additional valid bindings; an exact policy rejects them. Omit this field for dynamic discovery. Gateway Configuration explains upgrade requirements.

timeoutstringdefault: 500ms

Time limit for Describe, ValidateConfig, and individual evaluations or stream exchanges. Use an integer followed by ms or s, from 10ms through 30s. A binding may advertise a shorter evaluation timeout. Accepted HTTP response and WebSocket streams have no connection-wide deadline.

Private CA for the service certificate. Without it, OpenShell uses platform trust roots.

audiencestringdefault: urn:openshell:extension:middleware:<name>

Token audience. Refer to Authenticating Extensions.

allow_insecure_transportbooleandefault: false

Allows a plaintext http:// endpoint with no authentication. Use it for local development or on a network that already authenticates callers.

At startup, the gateway contacts every registered service to read its capabilities and verify protocol compatibility. The gateway does not start if a service is unavailable or incompatible. Gateway Configuration describes the full TOML context.

When the gateway has JWT signing configured, OpenShell authenticates every call to your service with a short-lived token. Authenticating Extensions describes how your service validates it.

Add entries to the top-level network_middlewares map in sandbox policy. Each entry selects destination hosts and names the middleware to run for them:

Attach a registered service by its registration name. Your service defines and validates the config object:

network_middlewares:
content-guard:
middleware: content-guard
config:
mode: redact
terms: ["internal-only"]
replacement: "[FILTERED]"
endpoints:
include: ["api.example.com"]

The map key, such as content-guard, is the entry’s stable identity in logs. Each entry accepts these fields:

middlewarestringrequired

A built-in middleware name, such as openshell/regex, or the name of a registered service.

endpoints.includestring[]required

Destination hosts to run the middleware for. Uses the same host patterns as network policy endpoints. A pattern matches a host on every port and cannot include a port. An IPv6 host must be a complete address without brackets, such as 2001:db8::1; IPv6 wildcard patterns are not supported.

Policies written for earlier releases that include a port, such as api.example.com:443, or an IPv6 wildcard, such as 2001:db8:*, now fail validation. Remove the port, and list IPv6 addresses individually. Patterns with a port never matched traffic.

Destination hosts to skip. Takes precedence over include.

orderintegerdefault: 0

Position in the chain when several entries match the same host. Lower values run first. Values must be unique within a policy, so set them explicitly when a policy has more than one entry.

on_error'fail_closed' | 'fail_open'default: fail_closed

What happens when the middleware fails. Refer to Choose Failure Behavior. Services that use HTTP hooks accept only fail_closed.

configobject

Configuration passed to the middleware. The middleware defines and validates its format.

namestring

Display name. Defaults to the map key.

Policy Schema lists every field and limit.

Each HTTP request or response runs through middleware of one HTTP hook version. The gateway rejects a policy in which two entries whose endpoint selectors may overlap use different HTTP hook versions for the same operation, requests or responses. To fix it, separate the selectors or move both services to the same hook version. If a chain still mixes hook versions at runtime, OpenShell blocks the traffic with error: middleware_failed and failure_code: middleware_hook_versions_mixed.

The built-in openshell/regex middleware uses legacy HTTP hooks for requests, so it cannot share a selector with an HTTP hook service that inspects requests.

Middleware fails when it cannot complete its check, for example when its service is unavailable, times out, returns an invalid result, or receives a payload over its limit. By default, OpenShell blocks the affected request, response, or WebSocket connection. The on_error field on a policy entry controls this behavior.

Middleware that uses HTTP hooks always fails closed. The gateway rejects fail_open on an entry whose service uses HTTP hooks, including a service that also inspects WebSocket messages. A policy stored before the service moved to HTTP hooks still loads, and supervisors block its HTTP traffic on failure and log a warning.

A denial from middleware always blocks traffic, regardless of on_error. Middleware decisions also stay enforced when the endpoint uses enforcement: audit. To observe traffic without blocking it, have your middleware allow the traffic and report findings.

on_error does not extend what middleware can inspect. The current limitations apply under both settings. With the default behavior, an entry cannot select a tls: skip endpoint, because OpenShell cannot inspect that traffic.

Middleware services sit on the request path of every sandbox that uses them. Plan their availability accordingly:

  • Start registered services before the gateway, and restart the gateway after changing registrations.
  • Keep services available when creating or updating policies. The gateway asks the service to validate its config before it accepts a policy.
  • Keep services reachable from sandbox supervisors, which call them directly for each request.

When a running sandbox receives a configuration change, its supervisor validates the new middleware setup before using it. If validation fails, the supervisor keeps its previous setup and emits a configuration failure event.

OpenShell records middleware activity in its OCSF logs:

  • Each invocation records the policy entry, middleware name, decision, whether it changed the traffic, and any failure.
  • Failed middleware emits a detection finding, whether OpenShell blocks the traffic or skips the middleware.
  • Coverage events record traffic that selected middleware could not inspect, such as WebSocket binary messages.
  • Configuration changes emit state-change events on success and failure.

For denials and findings, OpenShell logs the middleware name and a validated reason code or finding label. It does not log free-form text from your service. OCSF JSON Export describes how to send these events to other systems.

We are a Cloud Native Computing Foundation sandbox project.