request-validator

A lightweight Envoy and Istio ext-authz service that allows or denies requests using simple YAML rules written in CEL (Common Expression Language).

This service is built for complex authorization scenarios that standard Istio AuthorizationPolicy cannot handle, such as:

• Inspecting the request body (JSON or YAML).
• Mixing IP networks (CIDRs) and JWT claims with request payload values.
• Validating OAuth redirect_uris.
• Blocking specific paths during certain hours.
• Any other custom validation that goes beyond basic method, path, and header matching.

Two ways to configure policies

You can drive the engine in two complementary ways, and you can mix them freely:

1. Declarative YAML. A policy file checked into Git, typically mounted into the pod as a ConfigMap. This is your source of truth and what code review enforces.
2. Admin API at runtime. A small CRUD HTTP API on a separate port that lets you upsert and delete groups, facts, defaults and logging without redeploying. Useful for emergency blocks, A/B experiments, and any change that needs to happen in seconds.

Both paths feed the same evaluator. The YAML is the declarative floor; the admin API overlays it per key. There is no separate "YAML mode" or "API mode": every replica always serves the same effective policy, computed as MergeFromYAML(yaml, admin_overlay).

How the merge works

Section	Behaviour
groups	Keyed by name. API entry replaces the YAML entry with the same name; new names are appended.
facts	Same as groups: per-name overlay.
defaults	Per-field overlay. Fields present in the API replace YAML; absent fields keep the YAML value.
logging	Same per-field overlay as defaults.

Deleting an admin entry (DELETE /api/v1/groups/foo) restores the YAML entry of the same name if there was one. So you can ship a guard-rail policy in Git and let operators add tactical rules on top without losing the base.

You can always inspect what is actually being evaluated with GET /api/v1/config, which returns the merged result with a source: "yaml" | "api" flag on each group.

Hot reload

Whatever changes (the YAML file on disk, the admin overlay in the state store, or both) every replica rebuilds atomically:

Trigger	Path
Edit the YAML (kubectl edit cm request-validator-policy)	fsnotify picks it up within ~200 ms
kill -HUP 1 (fallback for NFS / FUSE)	manual reload
Admin API PUT / DELETE	leader commits, every replica's informer rebuilds

A reload that fails to parse, validate, compile or fetch URL facts is rejected; the previously installed policy keeps serving traffic. Fail-closed by design.

Writes go to the leader, reads work anywhere

In multi-replica deployments the admin API uses a Kubernetes Lease (request-validator-leader) to elect one writer at a time. A write that lands on a follower is transparently proxied to the current leader over an internal HTTP hop, and the leader's response is streamed back to the client. There is no redirect on the wire: the client cannot tell which replica handled the request, and it does not need any direct access to individual pods. Reads are served locally by every replica from its informer cache, with sub-second convergence after a write.

Quick Tour

Here is a simple policy that allows POST requests to a Keycloak Dynamic Client Registration endpoint, but only if the request comes from an internal private IP range:

defaults:
  action: deny

groups:
  - name: dcr-internal
    action: allow
    rules:
      - name: from-internal-cidr
        match: |
          request.method == 'POST' &&
          request.path.startsWith('/realms/mcp/clients-registrations') &&
          inCIDR(request.remoteIp, ['10.0.0.0/8'])

How it works:

• defaults.action: The default action when no rules match. We set this to deny to ensure unmatched requests are blocked.
• groups: Logical collections of rules that share a verdict (like action: allow).
• rules: Individual checks. The match field contains a CEL expression that must return a boolean. If it evaluates to true, the rule matches and the group's action is applied.
• inCIDR: A helper function provided by request-validator to easily check IP ranges.

The rest of this guide covers more advanced features and examples.

Examples

1. Limit Admin Access to Office IP and Working Hours

groups:
  - name: admin-business-hours
    action: allow
    rules:
      - name: office-during-the-day
        match: |
          request.path.startsWith('/admin') &&
          inCIDR(request.remoteIp, ['203.0.113.0/24']) &&
          now().getHours('UTC') >= 7 &&
          now().getHours('UTC') < 19

The now() function returns the current time. You can use standard CEL accessors like getHours, getDayOfWeek, or getMonth to enforce schedules without external dependencies.

2. Require a Header on Webhook Paths

groups:
  - name: webhook-needs-signature
    action: allow
    rules:
      - name: signed-with-x-hub-signature
        match: |
          request.path.startsWith('/hooks/github') &&
          has('x-hub-signature-256', request.headers) &&
          request.header['x-hub-signature-256'].startsWith('sha256=')

The has() helper checks if a header exists and is not empty. You can then access its values directly via request.header.

3. Block Specific Realms on Public Domains

groups:
  - name: keep-master-realm-private
    action: deny
    rules:
      - name: no-master-on-public-hosts
        match: |
          request.host in ['auth.example-1.com', 'auth.example-2.com'] &&
          request.path.startsWith('/realms/master')

Declaring a group with action: deny makes it easy to write and read explicit blocklists.

4. Validate JSON Request Bodies

This is a powerful feature that Istio's built-in policies cannot do. Here, we only allow Keycloak client registrations if all listed redirect_uris belong to trusted domains:

groups:
  - name: dcr-trusted-redirects
    action: allow
    match: |
      request.method == 'POST' &&
      request.path.matches('^/realms/mcp/clients-registrations(/.*)?$') &&
      request.body.jsonOk
    rules:
      - name: antigravity
        match: |
          request.body.json.redirect_uris.all(u,
            u.startsWith('https://antigravity.google/'))

      - name: chatgpt
        match: |
          request.body.json.redirect_uris.all(u,
            u.matches('^https://([a-z0-9-]+\\.)?openai\\.com/.+$'))

The group-level match serves as a pre-filter. If it is a POST to the registration endpoint with valid JSON, we then evaluate the individual rules.

5. Multi-factor Checks (Defense in Depth)

If you want a group to require multiple rules to pass before allowing access, set the group mode to all:

groups:
  - name: admin-defence-in-depth
    action: allow
    mode: all
    match: |
      request.path.startsWith('/admin')
    rules:
      - name: from-internal-network
        match: inCIDR(request.remoteIp, ['10.0.0.0/8', '192.168.0.0/16'])
      - name: has-admin-claim
        match: request.header['x-user-groups'].contains('platform-admins')
      - name: no-debug-header
        match: '!has("x-debug", request.headers)'

In all mode, every single rule must evaluate to true. If even one fails, the group denies the request.

For a comprehensive real-world policy, take a look at examples/policy.yaml.

6. Push a Tactical Block via the Admin API

So far every example has lived in the YAML file. Here is the same shape pushed at runtime through the admin API, useful for an incident response when there is no time for a redeploy:

TOKEN=$(kubectl -n request-validator get secret request-validator-admin \
  -o jsonpath='{.data.token}' | base64 -d)

curl -sLf -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": -100,
    "action": "deny",
    "rules": [
      { "name": "block-bad-ip",
        "match": "request.remoteIp == \"203.0.113.5\"" }
    ]
  }' \
  "http://request-validator.request-validator.svc:8081/api/v1/groups/incident-2026-05-19"

The body is the exact same shape you would write inside groups: in the YAML; the wire format and the on-disk format are intentionally identical. priority: -100 makes the group win against the YAML allow-lists. You can hit any pod (or the Service in front of them); if the pod that receives the request is not the current leader it proxies the write internally and you still get the leader's response back. Reverting the change is a DELETE against the same URL; the YAML floor takes over again without a deploy.

How Policy Evaluation Works

The engine evaluates groups sequentially in the order they are defined. The first group that matches and produces a verdict determines the outcome. If no group produces a verdict, the default action (defaults.action) is applied.

You can customize this flow using several properties:

• priority: Assign an integer (e.g., priority: -100) to run a group earlier. Groups with lower priority values run first. This is useful for placing global blocklists before allowlist groups.
• match (Group level): A filter that decides if the group should look at the request. If false, the group is skipped.
• mode: Controls how rules inside the group are evaluated:
  • firstMatch (default): The first rule that evaluates to true wins.
  • all: All rules must evaluate to true.
• action (Rule level): You can override the group action on a specific rule.
• fallthrough: By default, if a rule does not match, the engine moves to the next rule. You can set fallthrough: allow or fallthrough: deny to immediately stop group evaluation with that verdict.
• dryRun: Set to true to test rules in production. The engine evaluates and logs the decision, but will not block the request.

Available Request Fields in CEL

Every CEL expression has access to two top-level objects: request and facts.

Field	Type	Description
request.method	string	HTTP method (GET, POST, etc.)
request.scheme	string	http or https (extracted from X-Forwarded-Proto)
request.host	string	Request authority (host without port)
request.path	string	URL path
request.remoteIp	string	Client IP (from X-Forwarded-For or remote address)
request.headers	map<string, list<string>>	All headers with lowercased keys
request.header	map<string, string>	First value of each header
request.queries	map<string, list<string>>	All query parameters
request.query	map<string, string>	First value of each query parameter
request.body.raw	string	Raw request body (up to defaults.maxBodyBytes)
request.body.size	int	Body size in bytes
request.body.contentType	string	Content-Type header shortcut
request.body.json	dyn	Parsed JSON object, or {} if not JSON
request.body.jsonOk	bool	True if the body is valid JSON
request.body.yaml	dyn	Parsed YAML object, or {} if not YAML
request.body.yamlOk	bool	True if the body is valid YAML

Note: For the body to be available, you must configure Envoy/Istio to forward request bodies (see the Istio configuration section below).

Facts: Dynamic and External Data

If you have dynamic data that changes frequently (such as IP blocks published by third parties or lists of active customers), you can load them dynamically as facts instead of hardcoding them into your YAML policy.

You define facts at the top level of your policy and reference them in CEL using facts.<name>.

There are three sources for facts:

Method	Source	CEL Type
value	Defined inline in your YAML policy	The declared YAML type
file	Read from a local file path on startup/reload	String (file content)
url	Fetched periodically over HTTP	String (latest response body)

Example configuration:

facts:
  - name: internalCidrs
    method: value
    value:
      - 10.0.0.0/8
      - 192.168.0.0/16

  - name: trustedClients
    method: file
    file:
      path: /etc/policy/lists/trusted-clients.yaml

  - name: chatgptFeed
    method: url
    url:
      address: https://openai.com/chatgpt-actions.json
      interval: 10m
      timeout: 15s
      headers:
        Authorization: "Bearer $TOKEN"

To use them in your CEL rules:

inCIDR(request.remoteIp, facts.internalCidrs)

For facts loaded as raw strings, you can parse them on the fly in CEL:

inCIDR(request.remoteIp, parseJSON(facts.chatgptFeed).prefixes.map(p, p.ipv4Prefix))

The parseJSON and parseYAML helpers return {} if the input is empty or invalid, ensuring your rules do not crash if a fetch fails. It is usually a good idea to protect your rules by checking if the fact is available first:

match: |
  request.path.startsWith('/api') &&
  facts.chatgptFeed != null && facts.chatgptFeed != ""

Note on reliability: If the initial fetch of a URL fact fails during startup, the policy is rejected. If a subsequent background refresh fails, request-validator will log a warning but continue to use the last successfully fetched data. This prevents temporary network issues from blocking requests.

Logging

request-validator writes structured JSON logs for decisions and internal events. You can configure logging directly in your policy:

logging:
  level: info # debug | info | warn | error
  format: json # json | console
  logBody: false # include the request body in logs (opt-in)
  redactReveal: 6 # show only the first N characters of redacted values
  excludeHeaders: # completely exclude these headers from logs
    - cookie
    - set-cookie
  redactHeaders: # mask these header values
    - authorization
    - proxy-authorization
    - x-api-key
    - x-auth-token
  redactQueryParams: # mask these query parameters
    - access_token
    - id_token
    - code

The CLI flags --log-level and --log-format can be used to override these settings without updating the YAML policy.

An example log entry in JSON:

{
  "time": "2026-05-19T12:14:59.845Z",
  "level": "INFO",
  "msg": "request decided",
  "decision": "allow",
  "rule": "dcr-trusted-redirects/antigravity",
  "reason": "matched",
  "dry_run": false,
  "duration_ms": 0.31,
  "request": {
    "method": "POST",
    "host": "auth.example-1.com",
    "path": "/realms/mcp/clients-registrations",
    "query": "code=***&debug=1",
    "remote_ip": "203.0.113.5",
    "headers": {
      "content-type": "application/json",
      "authorization": "Bearer*********************************",
      "x-api-key": "***"
    },
    "body": { "size": 48, "content_type": "application/json" }
  }
}

The console format outputs values as plain key=value lines, which is highly readable when using kubectl logs -f during local development.

CEL Function Reference

On top of the standard CEL functions and libraries (ext.Strings(), ext.Encoders(), ext.Lists(), ext.Sets(), ext.Math(), ext.Bindings()), the service registers the following custom helper functions.

Network Functions

• inCIDR(ip, cidrs): Returns true if ip is in any of the listed CIDR ranges. Supports both IPv4 and IPv6. Plain IPs are automatically treated as /32 or /128.
• ipFamily(ip): Returns "ipv4", "ipv6", or "" if invalid.
• isPrivateIP(ip): Returns true if the IP is in private ranges (RFC1918, RFC4193, or link-local).
• isLoopbackIP(ip): Returns true if the IP is a loopback address (127.0.0.0/8 or ::1).
• parseURL(url): Parses a URL string and returns a map with scheme, host, port, path, query, fragment, username, and password.

Glob Matching

• glob(string, pattern): Evaluates a glob pattern. * matches anything except slashes, ** matches everything recursively, ? matches a single character, and [abc] matches character classes.
• globAny(string, patterns): Returns true if any of the glob patterns match.

Encoding and Security

• sha256Hex(string): Returns the SHA-256 hash of a string as a lowercase hex string.
• parseJWTUnverified(token): Parses a JWT token and returns a map containing {header, payload}. It does not verify the signature. Use this only if signature validation is handled by another gateway layer.

Time

• now(): Returns the current UTC timestamp. You can call CEL accessors like .getHours(), .getDayOfWeek(), or .getMonth() on the result.

Structured Parsing

• parseJSON(string): Parses JSON. Returns {} on empty, null, or invalid input.
• parseYAML(string): Parses YAML. Returns {} on empty, null, or invalid input.
• jsonPath(object, expression): Evaluates a lightweight JSONPath expression (e.g., $.a.b[*], $..name, $[0]).

HTTP Conveniences

• has(name, map): Returns true if the key exists in the map and has a non-empty value.
• firstOr(map, name, default): Returns the first value of a key, or the default value if it is empty or missing.

Deployment and Operation

Running Locally

To run request-validator locally with the included example:

go run ./cmd \
  --config examples/policy.yaml \
  --log-level debug --log-format console \
  --no-kubernetes

The --no-kubernetes flag tells the service to run in standalone, in-memory mode without attempting to contact a Kubernetes cluster.

Deploying to Kubernetes

An official OCI image is available at: ghcr.io/achetronic/request-validator:<version>.

A ready-to-go deployment setup is located in examples/kubernetes/. Pick manifests/ for plain kubectl / kustomize, or helm/ for the bjw-s app-template chart:

# Create the namespace and admin secret
kubectl create namespace request-validator
kubectl -n request-validator create secret generic request-validator-admin \
  --from-literal=token=$(openssl rand -hex 32)

# Deploy the manifests (plain kubectl + kustomize)
kubectl apply -k examples/kubernetes/manifests/

# …or with Helm (bjw-s app-template 5.0.1)
helm repo add bjw-s https://bjw-s-labs.github.io/helm-charts
helm upgrade --install request-validator bjw-s/app-template \
  --version 5.0.1 -n request-validator \
  -f examples/kubernetes/helm/values.yaml

This sets up a Deployment with 2 replicas, RBAC permissions, a ConfigMap for the policy, a Service, and a PodDisruptionBudget.

Ports and Endpoints

The service exposes two ports:

1. ext-authz port (Default: 8080)

This is the port Envoy talks to.

• /: The ext-authz validation endpoint.
• /healthz: Liveness probe.
• /readyz: Readiness probe (becomes healthy once a policy is successfully loaded).
• /metrics: Prometheus metrics.

2. admin port (Default: 8081)

Exposes a CRUD API to modify policies at runtime. Disabled if --admin-token-file is not provided.

• GET/PUT/DELETE /api/v1/groups[/{name}]: Manage policy groups.
• GET/PUT/DELETE /api/v1/facts[/{name}]: Manage facts.
• GET/PUT/DELETE /api/v1/defaults: Override global configuration defaults.
• GET/PUT/DELETE /api/v1/logging: Manage logging rules.
• GET /api/v1/config: View the merged running configuration.
• GET /api/v1/cluster: Details about the leader and cluster state.
• GET /api/v1/openapi.json: OpenAPI 3.1 specification.

All admin requests must include an Authorization: Bearer <token> header, using the token defined in the admin token file.

Hot Reloads and Multi-Replica Mode

These are covered in detail under Two Ways to Configure Policies: file changes propagate via fsnotify (or SIGHUP as fallback), admin API writes go to the elected leader and fan out to every replica's informer cache, and failed reloads keep the previous policy live.

Diagnostic Headers

Every decision returned by request-validator includes headers to help you debug and inspect evaluation results:

• x-rv-result: The verdict (allow or deny).
• x-rv-rule: The rule that matched, formatted as group/rule (or <defaults>).
• x-rv-reason: A short, human-readable explanation.
• x-rv-dry-run: true if the rule was executed in dry-run mode.

Integration with Istio

To integrate the service with Istio, apply these two configurations:

1. Register the Extension Provider in MeshConfig

Add request-validator as an extension provider in your Istio installation settings (usually in the istio-system namespace's istio ConfigMap):

meshConfig:
  extensionProviders:
    - name: request-validator
      envoyExtAuthzHttp:
        service: request-validator.<NAMESPACE>.svc.cluster.local
        port: 8080
        failOpen: false
        timeout: 2s
        includeRequestBodyInCheck:
          maxRequestBytes: 1048576
          allowPartialMessage: false
        headersToDownstreamOnDeny:
          [content-type, x-rv-result, x-rv-rule, x-rv-reason, x-rv-dry-run]
        headersToUpstreamOnAllow:
          [x-rv-result, x-rv-rule, x-rv-reason, x-rv-dry-run]
        includeRequestHeadersInCheck:
          - authorization
          - content-type
          - cookie
          - x-api-key
          - x-user-groups
          - x-forwarded-for
          - x-forwarded-proto

2. Configure an AuthorizationPolicy

Create a CUSTOM policy to route matching traffic to the validator:

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: keycloak-dcr-ext-authz
  namespace: keycloak
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: keycloak
  action: CUSTOM
  provider:
    name: request-validator
  rules:
    - to:
        - operation:
            hosts: [auth.example-1.com, auth.example-2.com]
            paths:
              - /realms/*/clients-registrations
              - /realms/*/clients-registrations/*

For advanced use cases, such as passing all request headers without listing them individually, see the EnvoyFilter examples in examples/config-for-istio.yaml.

License

Apache-2.0.